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.

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.