Fl_Menu_Item

## struct Fl_Menu_Item

### Class Hierarchy

    struct Fl_Menu_Item

### Include Files

    #include <FL/Fl_Menu_Item.H>

### Description

The `Fl_Menu_Item` structure defines a single menu item that is used by the Fl_Menu_ class. This structure is defined in `<FL/Fl_Menu_Item.H>`

    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
    };

Typically menu items are statically defined; for example:

    Fl_Menu_Item popup[] = {
      {"&alpha",   FL_ALT+'a', the_cb, (void*)1},
      {"&beta",    FL_ALT+'b', the_cb, (void*)2},
      {"gamma",    FL_ALT+'c', the_cb, (void*)3, FL_MENU_DIVIDER},
      {"&strange",  0,   strange_cb},
      {"&charm",    0,   charm_cb},
      {"&truth",    0,   truth_cb},
      {"b&eauty",   0,   beauty_cb},
      {"sub&menu",	0,   0, 0, FL_SUBMENU},
        {"one"},
        {"two"},
        {"three"},
      {0},
      {"inactive", FL_ALT+'i', 0, 0, FL_MENU_INACTIVE|FL_MENU_DIVIDER},
      {"invisible",FL_ALT+'i', 0, 0, FL_MENU_INVISIBLE},
      {"check",    FL_ALT+'i', 0, 0, FL_MENU_TOGGLE|FL_MENU_VALUE},
      {"box",      FL_ALT+'i', 0, 0, FL_MENU_TOGGLE},
    {0}};

produces:

A submenu title is identified by the bit `FL_SUBMENU` in the `flags` field, and ends with a `label()` that is `NULL`. You can nest menus to any depth. A pointer to the first item in the submenu can be treated as an `Fl_Menu` array itself. It is also possible to make seperate submenu arrays with `FL_SUBMENU_POINTER` flags.

You should use the method functions to access structure members and not access them directly to avoid compatibility problems with future releases of FLTK.

### Methods

label labeltype labelcolor labelfont labelsize callback | user_data argument do_callback shortcut submenu checkbox | radio value set setonly clear visible | show hide active activate deactivate | popup pulldown test_shortcut size next

#### const char* Fl_Menu_Item::label() const
void Fl_Menu_Item::label(const char*)
void Fl_Menu_Item::label(Fl_Labeltype, const char*)

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.

#### 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` 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`. 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 is a Helvetica font. The function `Fl::set_font()` can define new fonts.

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

Gets or sets the label font pixel size/height.

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

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*)

Get or set the `user_data` argument that is sent to the callback function.

#### 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::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_TOGGLE` or `FL_MENU_RADIO` is set 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

Returns the current value of the check or radio item.

#### void Fl_Menu_Item::set()

Turns the check or radio item "on" for the menu item. Note that this does not turn off any adjacent radio items like `set_only()` does.

#### void Fl_Menu_Item::setonly()

Turns the radio item "on" for the menu item and turns off adjacent radio item.

#### void Fl_Menu_Item::clear()

Turns the check or radio item "off" for the menu item.

#### int Fl_Menu_Item::visible() const

Gets the visibility of an item.

#### void Fl_Menu_Item::show()

Makes an item visible in the menu.

#### void Fl_Menu_Item::hide()

Hides an item in the menu.

#### int Fl_Menu_Item::active() const

Get whether or not the item can be picked.

#### void Fl_Menu_Item::activate()

Allows a menu item to be picked.

#### void Fl_Menu_Item::deactivate()

Prevents a menu item from being picked. Note that this will also cause the menu item to appear 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. 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 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 used internally by the `Fl_Menu_Bar` widget.

#### 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()

Returns the number of Fl_Menu_Item structures that make up this menu, correctly counting submenus. This includes the "terminator" item at the end. So to copy a menu you need to copy `size()*sizeof(Fl_Menu_Item)` bytes.

#### const Fl_Menu_Item* Fl_Menu_Item::next(int n=1) const
Fl_Menu_Item* Fl_Menu_Item::next(int n=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.