Fltk Menus

All widgets that have a menu in fltk are subclassed off of the virtual base class Fl_Menu_. Currently Fltk provides you with Fl_Menu_Button, Fl_Menu_Bar, and Fl_Choice.

The Fl_Menu_ contains a pointer to an array of structures of type Fl_Menu_Item. These describe the contents of the menu. Usually the array is a large initialization constant, but there are methods to build it dynamically.

struct Fl_Menu_Item

struct Fl_Menu_Item {
  const char*	text; // label()
  ulong		shortcut_;
  Fl_Callback*	callback_;
  void*		user_data_;
  int		flags;
  uchar		labeltype_;
  uchar		labelfont_;
  uchar		labelsize_;
  uchar		labelcolor_;
};

enum { // values for flags:
  FL_MENU_INACTIVE	= 1,
  FL_MENU_TOGGLE	= 2,
  FL_MENU_VALUE		= 4,
  FL_MENU_RADIO		= 8,
  FL_MENU_INVISIBLE	= 0x10,
  FL_SUBMENU_POINTER	= 0x20,
  FL_SUBMENU		= 0x40,
  FL_MENU_DIVIDER	= 0x80,
  FL_MENU_HORIZONTAL	= 0x100
};

This is the title of the item. A null here indicates the end of the menu (or of a submenu). A '&' in the item will print an underscore under the next letter, and if the menu is popped up that letter will be a "shortcut" to pick that item. To get a real '&' put two in a row.

void Fl_Menu_Item::label(Fl_Labeltype, const char*);
Fl_Labeltype Fl_Menu_Item::labeltype() const;
void Fl_Menu_Item::labeltype(Fl_Labeltype);

A labeltype identifies a routine that draws the label of the widget. This can be used for special effects such as emboss, or to use the label() pointer as another form of data such as a bitmap. The value FL_NORMAL_LABEL (0) prints the label as text.

Fl_Color Fl_Menu_Item::labelcolor() const;
void Fl_Menu_Item::labelcolor(Fl_Color);

This color is passed to the labeltype routine, and is typically the color of the label text. This defaults to FL_BLACK (0). If this color is not black fltk will not use overlay bitplanes to draw the menu, this is so that images put in the menu draw correctly.

Fl_Font Fl_Menu_Item::labelfont() const;
void Fl_Menu_Item::labelfont(Fl_Font);

Fonts are identified by small 8-bit indexes into a table. See the enumeration list for predefined fonts. The default value (0) uses a Helvetica font. The function Fl::set_font() can define new fonts.

uchar Fl_Menu_Item::labelsize() const;
void Fl_Menu_Item::labelsize(uchar);

Fonts are further identified by a point size. This sets the actual point size field of the X font name.

typedef void (Fl_Callback)(Fl_Widget*, void*);
Fl_Callback* Fl_Menu_Item::callback() const;
void Fl_Menu_Item::callback(Fl_Callback*, void* = 0);

Each item has space for a callback function and an argument for that function. Due to back compatability, the Fl_Menu_Item itself is not passed to the callback, instead you have to get it by calling ((Fl_Menu_*)w)->mvalue() where 'w' is the widget argument.

void* Fl_Menu_Item::user_data() const;
void Fl_Menu_Item::user_data(void*);

You can also just change the void* second argument to the callback with the user_data methods.

void Fl_Menu_Item::callback(void (*)(Fl_Widget*, long), long = 0);
long Fl_Menu_Item::argument() const;
void Fl_Menu_Item::argument(long);

For convenience you can also define the callback as taking a long argument. This is implemented by casting this to a Fl_Callback and casting the long to a void* and may not be portable to some machines.

void Fl_Menu_Item::callback(void (*)(Fl_Widget*));

For convenience you can also define the callback as taking only one argument. This is implemented by casting this to a Fl_Callback and may not be portable to some machines.

void Fl_Menu_Item::do_callback(Fl_Widget*);
void Fl_Menu_Item::do_callback(Fl_Widget*, void*);
void Fl_Menu_Item::do_callback(Fl_Widget*, long);

Call the Fl_Menu_Item item's callback, and provide the Fl_Widget argument (and optionally override the user_data() argument). You must first check that callback() is non-zero before calling this.

ulong Fl_Menu_Item::shortcut() const;
void Fl_Menu_Item::shortcut(ulong);

Sets exactly what key combination will trigger the menu item. The value is a logical 'or' of a key and a set of shift flags, for instance FL_ALT+'a' or FL_ALT+FL_F+10 or just 'a'. A value of zero disables the shortcut.

The key can be any value returned by Fl::event_key(), but will usually be an ascii letter. Use a lower-case letter unless you require the shift key to be held down.

The shift flags can be any set of values accepted by Fl::event_state(). If the bit is on that shift key must be pushed. Meta, Alt, Ctrl, and Shift must be off if they are not in the shift flags (zero for the other bits indicates a "don't care" setting).

int Fl_Menu_Item::submenu() const;

Returns true if either FL_SUBMENU or FL_SUBMENU_POINTER is on in the flags. FL_SUBMENU indicates an embedded submenu that goes from the next item through the next one with a null label(). FL_SUBMENU_POINTER indicates that user_data() is a pointer to another menu array.

int Fl_Menu_Item::checkbox() const;

Returns true if a checkbox will be drawn next to this item. This is true if Fl_Menu_Item_BOX or FL_MENU_RADIO is on in the flags.

int Fl_Menu_Item::radio() const;

Returns true if this item is a radio item. When a radio button is selected all "adjacent" radio buttons are turned off. A set of radio items is delimited by an item that has radio() false, or by an item with FL_MENU_DIVIDER turned on.

int Fl_Menu_Item::value() const;
void Fl_Menu_Item::set();
void Fl_Menu_Item::setonly();
void Fl_Menu_Item::clear();

The current value of a checkbox or radio menu item. You can change it with set() or clear() (don't do this to items with checkbox() false!). setonly() is for radio buttons, it turns off all adjacent radio buttons.

int Fl_Menu_Item::visible() const;
void Fl_Menu_Item::show();
void Fl_Menu_Item::hide();

Get or set the items visibility. Invisible items act exactly as though they are not in the menu.

int Fl_Menu_Item::active() const;
void Fl_Menu_Item::activate();
void Fl_Menu_Item::deactivate();

Get or set whether or not the item can be picked. Inactive items are drawn grayed out.

const Fl_Menu_Item* Fl_Menu_Item::popup(
  int X, int Y,
  const char* title = 0,
  const Fl_Menu_Item* picked = 0,
  const Fl_Menu_* button = 0) const;

This method is called by widgets that want to display menus (such as the Fl_Menu_ widgets described below). The menu stays up until the user picks an item or dismisses it. The selected item (or null if none) is returned. This does not do the callbacks or change the state of check or radio items.

X,Y is the position of the mouse cursor, relative to the window that got the most recent event (usually you can pass Fl::event_x() and Fl::event_y() unchanged here).

title is a character string title for the menu. If non-zero a small box appears above the menu with the title in it.

The menu is positioned so the cursor is centered over the item picked. This will work even if picked is in a submenu. If picked is zero or not in the menu item table the menu is positioned with the cursor in the top-left corner.

button is a pointer to an Fl_Menu_ from which the color and boxtypes for the menu are pulled. If null then SGI-style defaults are used.

const Fl_Menu_Item* Fl_Menu_Item::pulldown(
  int X, int Y, int W, int H,
  const Fl_Menu_Item* picked = 0,
  const Fl_Menu_* button = 0,
  const Fl_Menu_Item* title = 0,
  int menubar=0) const;

pulldown() is similar to popup(), but a rectangle is provided to position the menu. The menu is made at least W wide, and the picked item is centered over the rectangle (like Fl_Choice uses). If picked is zero or not found, the menu is aligned just below the rectangle (like a pulldown menu).

The title and menubar arguments are for internal use, don't use them.

const Fl_Menu_Item* Fl_Menu_Item::test_shortcut() const;

This is designed to be called by a widgets handle() method in response to a FL_SHORTCUT event. If the current event matches one of the items shortcut, that item is returned. If the keystroke does not match any shortcuts then NULL is returned. This only matches the shortcut() fields, not the letters in the title preceeded by '&'.

int Fl_Menu_Item::size();

Return the offset of the null terminator that ends this menu, correctly skipping over submenus. To copy a menu you should copy size()+1 Fl_Menu_Item structures.

const Fl_Menu_Item* Fl_Menu_Item::next(int=1) const;
Fl_Menu_Item* Fl_Menu_Item::next(int=1);

Advance a pointer by n items through a menu array, skipping the contents of submenus and invisible items. There are two calls so that you can advance through const and non-const data.

class Fl_Menu_ : public Fl_Widget

const Fl_Menu_Item* Fl_Menu_::menu() const ;
void Fl_Menu_::menu(const Fl_Menu_Item*);

Get or set the menu array directly. Setting it to null indicates that you want the widget to allocate its own array.

int Fl_Menu_::value() const ;
const Fl_Menu_Item* Fl_Menu_::mvalue() const;
int Fl_Menu_::value(int);
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.

int Fl_Widget::changed() const;
void Fl_Widget::set_changed();
void Fl_Widget::clear_changed();

This value is true if the user picks a different value. It is turned off by value(x) and just before doing a callback (the callback can turn it back on if desired).

Fl_When Fl_Widget::when() const;
void Fl_Widget::when(Fl_When);

It is probably useless to set this to any value other than the default FL_WHEN_RELEASE|FL_WHEN_NOT_CHANGED. See Fl_Choice for a subclass that uses this.

See also Fl_Menu_Button::popup(void).

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 (including destroying the menu).

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.

int Fl_Menu_::size() const ;

This returns menu()->size(), which is how many entries are in the array, not counting the null ending, but including all submenus titles and the nulls that end them. If the menu is null this returns zero.

int Fl_Menu_::add(const char *,const char *,Fl_Callback *,void *v=0,int f=0);

Add a new menu item, with a title string, shortcut string, callback, argument to the callback, and flags. If menu() was originally set with null then space is allocated for the new item. If instead you gave it an array then the array must have enough empty space for the new item. The title string is copied, but the shortcut is not.

Text is a string of the form "foo/bar/baz", this example will result in a submenu called "foo" and one in that called "bar" and and entry called "baz". The text is copied to new memory and can be freed. The other arguments 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.

No bounds checking is done, the table must be big enough for all the entries you plan to add. Don't forget that there is a null terminator on the end, and the first time a item is added to a submenu three items are added (the title and the null terminator, as well as the actual menu item)

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

int Fl_Menu_::add(const char *);

The 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 compatable with some Forms programs.

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

void Fl_Menu_::clear();

Delete all the menu items. Don't do this if you used menu(x) to set it to your own array. You should do this before destroying the Fl_Menu_ widget if it uses it's own array.

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

Change the text of item n. The passed string is copied.

void Fl_Menu_::remove(int);

Delete item n from the menu.

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

Change the shortcut of item i.

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

Change the flags of item n.

Fl_Font Fl_Menu_::textfont() const;
void Fl_Menu_::textfont(Fl_Font);
uchar Fl_Menu_::textsize() const;
void Fl_Menu_::textsize(uchar);
Fl_Color Fl_Menu_::textcolor() const;
void Fl_Menu_::textcolor(Fl_Color);

Get or set the font, font size, or color of the text displayed in the menu (the current implementation ignores the color, although the Fl_Choice subclass will use it for it's own display). The default is normal-sized Bold Italic Helvetica and black.

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 zero/FL_NO_BOX then it acts like FL_THIN_UP_BOX and selection_color() acts like FL_WHITE, for back compatability.

class Fl_Menu_Button : public Fl_Menu_

Normally any mouse button will pop up a menu and it is lined up below the button as shown in the picture. However an Fl_Menu_Button may also control a pop-up menu. This is done by setting the type(), see below.

The menu will also pop up in response to shortcuts indicated by putting a '&' character in the label(). See Fl_Button for a description of this.

Typing the shortcut() of any of the menu items will cause callbacks exactly the same as when you pick the item with the mouse. The '&' character in menu item names are only looked at when the menu is popped up, however.

When the user picks an item off the menu, the item's callback is done with the menu_button as the Fl_Widget* argument. If the item does not have a callback the menu_button's callback is done instead.

Fl_Menu_Button::Fl_Menu_Button(int,int,int,int,const char * = 0);

The constructor sets menu() to null. See Fl_Menu_ for the methods to set or change the menu!

void Fl_Widget::type(uchar);

If type() is zero a normal menu button is produced. If it is nonzero then this is a pop-up menu. The bits in type() indicate what mouse buttons pop up the menu. For convienece the constants Fl_Menu_Button::POPUP1, POPUP2, POPUP3, POPUP12, POPUP13, POPUP23, and POPUP123 are defined. Fl_Menu_Button::POPUP3 is probably what you want.

A popup menu button is invisible and does not interfere with any events other than the mouse button specified (and any shortcuts). The widget can be stretched to cover all your other widgets, put it last in the hierarchy so it is "on top". Or you can make several widgets covering different areas for context-sensitive popup menus.

The popup menus appear with the cursor pointing at the previously selected item. This is a feature. If you don't like it, do value(0) after the menu items are picked to forget the current item.

class Fl_Menu_Bar : public Fl_Menu_

The items on the bar and the menus they bring up are defined by a single Fl_Menu_Item array. Because a Fl_Menu_Item array defines a hierarchy, the top level menu defines the items in the menubar, while the submenus define the pull-down menus. Sub-sub menus and lower pop up to the right of the submenus.

If there is an item in the top menu that is not a title of a submenu, then it acts like a "button" in the menubar. Clicking on it will pick it.

When the user picks an item off the menu, the item's callback is done with the menubar as the Fl_Widget* argument. If the item does not have a callback the menubar's callback is done instead.

Submenus will also pop up in response to shortcuts indicated by putting a '&' character in the name field of the menu item. See Fl_Button for a description of this. If you put a '&' character in a top-level "button" then the shortcut picks it. The '&' character in submenus is ignored until the menu is popped up, to match Micro$oft behavior.

Typing the shortcut() of any of the menu items will cause callbacks exactly the same as when you pick the item with the mouse.

Currently the menu bar does not display as many attributes as a pop-up menu. Invisible and inactive items draw correctly. Checkboxes, divider lines, display of shortcuts, and perhaps other things are not drawn in the current version.

Fl_Menu_Bar::Fl_Menu_Bar(int, int, int, int, const char * = 0);

labelsize() and labelfont() and labelcolor() are used to control how the menubar items are drawn. They are initialized from the Fl_Menu static variables, but you can change them if desired.

label() is ignored unless you change the align() to put it outside the menubar.

class Fl_Choice : public Fl_Menu_

The only difference between this and a Fl_Menu_Button is that the name of the most recent chosen menu item is displayed inside the box, while the label is displayed outside the box. However, since the use of this is most often to control a single variable rather than do individual callbacks, some of the Fl_Menu_Button methods are redescribed here in those terms.

When the user picks an item off the menu the value() is set to that item and then the callback is done.

All three mouse buttons pop up the menu. The Forms behavior of the first two buttons to increment/decrement the choice is not implemented. This could be added with a subclass, however.

The menu will also pop up in response to shortcuts indicated by putting a '&' character in the label(). See Fl_Button for a description of this.

Typing the shortcut() of any of the items will do exactly the same as when you pick the item with the mouse. The '&' character in item names are only looked at when the menu is popped up, however.

Fl_Choice::Fl_Choice(int,int,int,int,const char * =0);

int Fl_Choice::value() const ;
int Fl_Choice::value(int);
int Fl_Choice::value(const Fl_Menu *);

int Fl_Widget::changed() const;
void Fl_Widget::set_changed();
void Fl_Widget::clear_changed();

Fl_When Fl_Widget::when() const;
void Fl_Widget::when(Fl_When);

• 0 : The callback is not done, instead changed() is turned on.
• FL_WHEN_RELEASE : The callback is done when the user picks an item.
• FL_WHEN_RELEASE|FL_WHEN_NOT_CHANGED : Does the callback even if the user picks the same value.

(back to contents)