Documentation

FLTK Apps FLTK Library Forums Links Login

[ Home | Articles & FAQs | Bugs & Features | Documentation | Download ]

class Fl_Menu_

Class Hierarchy

Fl_Widget
   |
   +----Fl_Menu_----Fl_Menu_Item
           |
           +----Fl_Choice, Fl_Menu_Bar, Fl_Menu_Button

Include Files

#include <FL/Fl_Menu_.H>

Description

All widgets that have a menu in FLTK are subclassed off of this class. Currently FLTK provides you with Fl_Menu_Button, Fl_Menu_Bar, and Fl_Choice .

The class contains a pointer to an array of structures of type Fl_Menu_Item. The array may either be supplied directly by the user program, or it may be "private": a dynamically allocated array managed by the Fl_Menu_.

down_box
find_item
global
item_pathname
menu

mode
mvalue
remove
replace

shortcut
size
test_shortcut
text

textfont
textsize
value
textcolor

Fl_Menu_::Fl_Menu_(int x, int y, int w, int h, const char *label = 0)

Creates a new Fl_Menu_ widget using the given position, size, and label string. menu() is initialized to null.

virtual Fl_Menu_::~Fl_Menu_()

If the menu array is private the memory it uses is freed.

int Fl_Menu_::add(const char* label, const char* shortcut, Fl_Callback, void user_data=0, int flags=0)
int Fl_Menu_::add(const char* label, int shortcut, Fl_Callback, void user_data=0, int flags=0)

Adds a new menu item, with a title string, shortcut string, callback, argument to the callback, and flags. If the menu array was directly set with menu(x) then copy() is done to make a private array.

The characters "&", "/", "\", and "_" are treated as special characters in the label string. The "&" character specifies that the following character is an accelerator and will be underlined. The "\" character is used to escape the next character in the string. Labels starting with the "_" character cause a divider to be placed after that menu item.

A label of the form "foo/bar/baz" will create a submenus called "foo" and "bar" with an entry called "baz". The "/" character is ignored if it appears as the first character of the label string, e.g. "/foo/bar/baz".

The label string is copied to new memory and can be freed. The other arguments (including the shortcut) are copied into the menu item unchanged.

If an item exists already with that name then it is replaced with this new one. Otherwise this new one is added to the end of the correct menu or submenu. The return value is the offset into the array that the new entry was placed at.

Shortcut can be 0L, or either a modifier/key combination (for example FL_CTRL+'A') or a string describing the shortcut in one of two ways:

  [#+^]<ascii_value>    eg. "97", "^97", "+97", "#97"
  [#+^]<ascii_char>     eg. "a", "^a", "+a", "#a"

..where <ascii_value> is a decimal value representing an ascii character (eg. 97 is the ascii for 'a'), and the optional prefixes enhance the value that follows. Multiple prefixes must appear in the above order.

  # - Alt
  + - Shift
  ^ - Control

Text shortcuts are converted to integer shortcut by calling int fl_old_shortcut(const char*).

The return value is the index into the array that the entry was put.

No items must be added to a menu during a callback to the same menu.

int Fl_Menu_::add(const char *)

The passed string is split at any '|' characters and then add(s,0,0,0,0) is done with each section. This is often useful if you are just using the value, and is compatible with Forms and other GL programs. The section strings use the same special characters as described for the long version of add()

No items must be added to a menu during a callback to the same menu.

void Fl_Menu_::clear()

Same as menu(NULL), set the array pointer to null, indicating a zero-length menu.

Menus must no be cleared during a callback to the same menu.

void Fl_Menu_::copy(const Fl_Menu_Item, void user_data = 0)

The menu is set to a private copy of the passed Fl_Menu_Item array. This is useful if you want to modify the flags of the menu items. If the user_data argument is non-NULL, then the user_data members of the menu items are set to the given value.

Fl_Boxtype Fl_Menu_::down_box() const
void Fl_Menu_::down_box(Fl_Boxtype)

This box type is used to surround the currently-selected items in the menus. If this is FL_NO_BOX then it acts like FL_THIN_UP_BOX and selection_color() acts like FL_WHITE, for back compatability.

const Fl_Menu_Item Fl_Menu_::find_item(const char name);

Returns a pointer to the menu item with the given (full) pathname. If no matching menu item can be found, a NULL pointer is returned. This function does not search submenus that are linked via FL_SUBMENU_POINTER.

int Fl_Menu_::item_pathname(char name, int namelen ) const;
int Fl_Menu_::item_pathname(char name, int namelen, const Fl_Menu_Item *finditem) const;

Returns the 'menu pathname' (eg. "File/Quit") for the recently picked item in user supplied string 'name'. Useful in the callback function for a menu item, to determine the last picked item's 'menu pathname' string.

If finditem is specified, name will contain the 'menu pathname' for that item.

Returns:

0 - OK: 'name' has the pathname, guaranteed not longer than namelen
-1 - Failed: 'finditem' was not found in the menu
-2 - Failed: 'name' is not large enough to handle the menu names

In the case of errors (-1 or -2), 'name' will be an empty string.

const Fl_Menu_Item* Fl_Menu_::menu() const

Returns a pointer to the array of Fl_Menu_Items. This will either be the value passed to menu(value) or the private copy.

void Fl_Menu_::menu(const Fl_Menu_Item*)

Set the menu array pointer directly. If the old menu is private it is deleted. NULL is allowed and acts the same as a zero-length menu. If you try to modify the array (with add(), replace(), or delete()) a private copy is automatically done.

void Fl_Menu_::mode(int i, int x);

Changes the flags of item i. For a list of the flags, see Fl_Menu_Item.

const Fl_Menu_Item* Fl_Menu_::mvalue() const

Returns a pointer to the last menu item that was picked.

void Fl_Menu_::remove(int n)

Deletes item n from the menu. If the menu array was directly set with menu(x) then copy() is done to make a private array.

No items must be removed from a menu during a callback to the same menu.

void Fl_Menu_::replace(int n, const char *)

Changes the text of item n. This is the only way to get slash into an add()'ed menu item. If the menu array was directly set with menu(x) then copy() is done to make a private array.

void Fl_Menu_::shortcut(int i, int n);

Changes the shortcut of item i to n.

int Fl_Menu_::size() const

This returns the number of Fl_Menu_Item structures that make up the menu, correctly counting submenus. This includes the "terminator" item at the end. To copy a menu array you need to copy size()*sizeof(Fl_Menu_Item) bytes. If the menu is NULL this returns zero (an empty menu will return 1).

const Fl_Menu_Item* Fl_Menu_::test_shortcut()

Only call this in response to FL_SHORTCUT events. If the event matches an entry in the menu that entry is selected and the callback will be done (or changed() will be set). This allows shortcuts directed at one window to call menus in another.

void Fl_Menu_::global()

Make the shortcuts for this menu work no matter what window has the focus when you type it. This is done by using Fl::add_handler(). This Fl_Menu_ widget does not have to be visible (ie the window it is in can be hidden, or it does not have to be put in a window at all).

Currently there can be only one global()menu. Setting a new one will replace the old one. There is no way to remove the global() setting (so don't destroy the widget!)

const char* Fl_Menu_::text() const
const char* Fl_Menu_::text(int i) const

Returns the title of the last item chosen, or of item i.

Fl_Color Fl_Menu_::textcolor() const
void Fl_Menu_::textcolor(Fl_Color)

Get or set the current color of menu item labels.

Fl_Font Fl_Menu_::textfont() const
void Fl_Menu_::textfont(Fl_Font)

Get or set the current font of menu item labels.

uchar Fl_Menu_::textsize() const
void Fl_Menu_::textsize(uchar)

Get or set the font size of menu item labels.

int Fl_Menu_::value() const
int Fl_Menu_::value(int)
const Fl_Menu_Item* mvalue() const
int Fl_Menu_::value(const Fl_Menu_Item*)

The value is the index into menu() of the last item chosen by the user. It is zero initially. You can set it as an integer, or set it with a pointer to a menu item. The set routines return non-zero if the new value is different than the old one.

User Comments [ Add Comment ]

From joekrahn, 16:59 Oct 03, 2005 (score=3)

Multiple prefixes must appear in the reverse order of the one shown here. The required order is [^+#], not [#+^].

Could it be that this got reversed at some time? It is probaly best to make these modifiers order-independent.
[ Reply ]

From greg.ercolano, 22:57 Mar 05, 2005 (score=3)

Example of how to use item_pathname() in a callback to determine which menu item was chosen, new in fltk 1.1.6:

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <FL/Fl.H>
#include <FL/Fl_Window.H>
#include <FL/Fl_Menu_Bar.H>
// Common callback for /all/ menu items
static void Menu_CB(Fl_Widget*w, void*) {
    const Fl_Menu_Bar *menubar = (Fl_Menu_Bar*)w;
    // Get picked menu item's 'pathname'
    char picked[80];
    menubar->item_pathname(picked, sizeof(picked)-1);
    printf("CALLBACK: You picked '%s'\n", picked);
    // Handle callback..
    if ( strcmp(picked, "File/Quit") == 0 ) exit(0);
    if ( strcmp(picked, "Help/Help") == 0 ) printf("Help goes here\n");
}
int main() {
    Fl_Window win(720,486);
    Fl_Menu_Bar menubar(0,0,720,28);
    menubar.add("File/Open", 0, Menu_CB);  // note: no user data used
    menubar.add("File/Quit", 0, Menu_CB);
    menubar.add("Help/Help", 0, Menu_CB);
    win.end();
    win.show();
    return(Fl::run());
}

[ Reply ]

From greg.ercolano, 18:04 Jun 27, 2003 (score=1)

[UPDATE -- The following post has been fixed, and is no longer an issue]

The following is not documented in 1.1.x; see STR#99.

add(const char*name, const char*shortcut,..): ---- 'shortcut' can be NULL for no shortcut, or a text string in one of two forms:

[^+#] eg. "97", "^97", "+97", "#97"
[^+#] eg. "a", "^a", "+a", "#a"

..where is a decimal value representing an ascii character (eg. 97 is the ascii for 'a'), and the optional prefixes enhance the value that follows, as:

    ^ - Control
    + - Shift
    # - Alt

(Note: you cannot combine prefixes, i.e. "^+a" does /not/ result in CONTROL-SHIFT-A) ----
[ Reply ]