The Fl_Menu_Item structure defines a single menu item that is used by the Fl_Menu_ class. More...

#include <Fl_Menu_Item.H>

Public Member Functions
void	activate ()
	Allows a menu item to be picked. More...

int	active () const
	Gets whether or not the item can be picked. More...

int	activevisible () const
	Returns non 0 if FL_INACTIVE and FL_INVISIBLE are cleared, 0 otherwise. More...

int	add (const char , int shortcut, Fl_Callback , void *=0, int=0)
	Adds an item. More...

int	add (const char a, const char b, Fl_Callback c, void d=0, int e=0)
	See int add(const char, int shortcut, Fl_Callback, void*, int)

long	argument () const
	Gets the user_data() argument that is sent to the callback function. More...

void	argument (long v)
	Sets the user_data() argument that is sent to the callback function. More...

Fl_Callback_p	callback () const
	Returns the callback function that is set for the menu item. More...

void	callback (Fl_Callback c, void p)
	Sets the menu item's callback function and userdata() argument. More...

void	callback (Fl_Callback *c)
	Sets the menu item's callback function. More...

void	callback (Fl_Callback0 *c)
	Sets the menu item's callback function. More...

void	callback (Fl_Callback1 *c, long p=0)
	Sets the menu item's callback function and userdata() argument. More...

void	check ()
	back compatibility only More...

int	checkbox () const
	Returns true if a checkbox will be drawn next to this item. More...

int	checked () const
	back compatibility only More...

void	clear ()
	Turns the check or radio item "off" for the menu item. More...

void	deactivate ()
	Prevents a menu item from being picked. More...

void	do_callback (Fl_Widget *o) const
	Calls the Fl_Menu_Item item's callback, and provides the Fl_Widget argument. More...

void	do_callback (Fl_Widget o, void arg) const
	Calls the Fl_Menu_Item item's callback, and provides the Fl_Widget argument. More...

void	do_callback (Fl_Widget *o, long arg) const
	Calls the Fl_Menu_Item item's callback, and provides the Fl_Widget argument. More...

void	draw (int x, int y, int w, int h, const Fl_Menu_ *, int t=0) const
	Draws the menu item in bounding box x,y,w,h, optionally selects the item. More...

const Fl_Menu_Item *	find_shortcut (int *ip=0, const bool require_alt=false) const
	Search only the top level menu for a shortcut. More...

const Fl_Menu_Item *	first () const
	Returns the first menu item, same as next(0). More...

Fl_Menu_Item *	first ()
	Returns the first menu item, same as next(0). More...

void	hide ()
	Hides an item in the menu. More...

void	image (Fl_Image *a)
	compatibility api for FLUID, same as a->label(this)

void	image (Fl_Image &a)
	compatibility api for FLUID, same as a.label(this)

int	insert (int, const char , int, Fl_Callback , void *=0, int=0)
	Inserts an item at position `index`. More...

const char *	label () const
	Returns the title of the item. More...

void	label (const char *a)
	See const char* Fl_Menu_Item::label() const.

void	label (Fl_Labeltype a, const char *b)
	See const char* Fl_Menu_Item::label() const.

Fl_Color	labelcolor () const
	Gets the menu item's label color. More...

void	labelcolor (Fl_Color a)
	Sets the menu item's label color. More...

Fl_Font	labelfont () const
	Gets the menu item's label font. More...

void	labelfont (Fl_Font a)
	Sets the menu item's label font. More...

Fl_Fontsize	labelsize () const
	Gets the label font pixel size/height. More...

void	labelsize (Fl_Fontsize a)
	Sets the label font pixel size/height. More...

Fl_Labeltype	labeltype () const
	Returns the menu item's labeltype. More...

void	labeltype (Fl_Labeltype a)
	Sets the menu item's labeltype. More...

int	measure (int h, const Fl_Menu_ ) const
	Measures width of label, including effect of & characters. More...

const Fl_Menu_Item *	next (int=1) const
	Advance a pointer by n items through a menu array, skipping the contents of submenus and invisible items. More...

Fl_Menu_Item *	next (int i=1)
	Advances a pointer by n items through a menu array, skipping the contents of submenus and invisible items. More...

const Fl_Menu_Item *	popup (int X, int Y, const char title=0, const Fl_Menu_Item picked=0, const Fl_Menu_ *=0) const
	This method is called by widgets that want to display menus. More...

const Fl_Menu_Item *	pulldown (int X, int Y, int W, int H, const Fl_Menu_Item picked=0, const Fl_Menu_ =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. More...

int	radio () const
	Returns true if this item is a radio item. More...

void	set ()
	Turns the check or radio item "on" for the menu item. More...

void	setonly ()
	Turns the radio item "on" for the menu item and turns off adjacent radio items set. More...

int	shortcut () const
	Gets what key combination shortcut will trigger the menu item. More...

void	shortcut (int s)
	Sets exactly what key combination will trigger the menu item. More...

void	show ()
	Makes an item visible in the menu. More...

int	size () const
	Size of the menu starting from this menu item.

int	submenu () const
	Returns true if either FL_SUBMENU or FL_SUBMENU_POINTER is on in the flags. More...

const Fl_Menu_Item *	test_shortcut () const
	This is designed to be called by a widgets handle() method in response to a FL_SHORTCUT event. More...

void	uncheck ()
	back compatibility only More...

void *	user_data () const
	Gets the user_data() argument that is sent to the callback function.

void	user_data (void *v)
	Sets the user_data() argument that is sent to the callback function.

int	value () const
	Returns the current value of the check or radio item. More...

int	visible () const
	Gets the visibility of an item. More...

Public Attributes
Fl_Callback *	callback_
	menu item callback

int	flags
	menu item flags like FL_MENU_TOGGLE, FL_MENU_RADIO

Fl_Color	labelcolor_
	menu item text color

Fl_Font	labelfont_
	which font for this menu item text

Fl_Fontsize	labelsize_
	size of menu item text

uchar	labeltype_
	how the menu item text looks like

int	shortcut_
	menu item shortcut

const char *	text
	menu item text, returned by label()

void *	user_data_
	menu item user_data for the menu's callback

Detailed Description

The Fl_Menu_Item structure defines a single menu item that is used by the Fl_Menu_ class.

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,      // Deactivate menu item (gray out)
 FL_MENU_TOGGLE = 2,      // Item is a checkbox toggle (shows checkbox for on/off state)
 FL_MENU_VALUE  = 4,      // The on/off state for checkbox/radio buttons (if set, state is 'on')
 FL_MENU_RADIO  = 8,      // Item is a radio button (one checkbox of many can be on)
 FL_MENU_INVISIBLE      = 0x10,   // Item will not show up (shortcut will work)
 FL_SUBMENU_POINTER     = 0x20,   // Indicates user_data() is a pointer to another menu array
 FL_SUBMENU             = 0x40,   // This item is a submenu to other items
 FL_MENU_DIVIDER        = 0x80,   // Creates divider line below this item. Also ends a group of radio buttons.
 FL_MENU_HORIZONTAL     = 0x100   // ??? -- reserved
};

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 separate 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.

Member Function Documentation

void Fl_Menu_Item::activate ( )

inline

Allows a menu item to be picked.

int Fl_Menu_Item::active ( ) const

inline

Gets whether or not the item can be picked.

int Fl_Menu_Item::activevisible ( ) const

inline

Returns non 0 if FL_INACTIVE and FL_INVISIBLE are cleared, 0 otherwise.

int Fl_Menu_Item::add	(	const char *	mytext,
		int	sc,
		Fl_Callback *	cb,
		void *	data = `0`,
		int	myflags = `0`
	)

Adds an item.

The text is split at '/' characters to automatically produce submenus (actually a totally unnecessary feature as you can now add submenu titles directly by setting SUBMENU in the flags):

long Fl_Menu_Item::argument ( ) const

inline

Gets the user_data() argument that is sent to the callback function.

For convenience you can also define the callback as taking a long argument. This method casts the stored userdata() argument to long and returns it as a long value.

void Fl_Menu_Item::argument ( long v )

inline

Sets the user_data() argument that is sent to the callback function.

For convenience you can also define the callback as taking a long argument. This method casts the given argument v to void* and stores it in the menu item's userdata() member. This may not be portable to some machines.

Fl_Callback_p Fl_Menu_Item::callback ( ) const

inline

Returns the callback function that is set for the menu item.

Each item has space for a callback function and an argument for that function. Due to back compatibility, 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::callback	(	Fl_Callback *	c,
		void *	p
	)

inline

Sets the menu item's callback function and userdata() argument.

See Also: Fl_Callback_p Fl_MenuItem::callback() const

void Fl_Menu_Item::callback ( Fl_Callback * c )

inline

Sets the menu item's callback function.

This method does not set the userdata() argument.

See Also: Fl_Callback_p Fl_MenuItem::callback() const

void Fl_Menu_Item::callback ( Fl_Callback0 * c )

inline

Sets the menu item's callback function.

This method does not set the userdata() argument.

See Also: Fl_Callback_p Fl_MenuItem::callback() const

void Fl_Menu_Item::callback	(	Fl_Callback1 *	c,
		long	p = `0`
	)

inline

Sets the menu item's callback function and userdata() argument.

This method does not set the userdata() argument. The argument is cast to void* and stored as the userdata() for the menu item's callback function.

See Also: Fl_Callback_p Fl_MenuItem::callback() const

void Fl_Menu_Item::check ( )

inline

back compatibility only

Deprecated:: .

int Fl_Menu_Item::checkbox ( ) const

inline

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::checked ( ) const

inline

back compatibility only

Deprecated:: .

void Fl_Menu_Item::clear ( )

inline

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

void Fl_Menu_Item::deactivate ( )

inline

Prevents a menu item from being picked.

Note that this will also cause the menu item to appear grayed-out.

void Fl_Menu_Item::do_callback ( Fl_Widget * o ) const

inline

Calls the Fl_Menu_Item item's callback, and provides the Fl_Widget argument.

The callback is called with the stored user_data() as its second argument. You must first check that callback() is non-zero before calling this.

void Fl_Menu_Item::do_callback	(	Fl_Widget *	o,
		void *	arg
	)		const

inline

Calls the Fl_Menu_Item item's callback, and provides the Fl_Widget argument.

This call overrides the callback's second argument with the given value arg. You must first check that callback() is non-zero before calling this.

void Fl_Menu_Item::do_callback	(	Fl_Widget *	o,
		long	arg
	)		const

inline

Calls the Fl_Menu_Item item's callback, and provides the Fl_Widget argument.

This call overrides the callback's second argument with the given value arg. long arg is cast to void* when calling the callback. You must first check that callback() is non-zero before calling this.

void Fl_Menu_Item::draw	(	int	x,
		int	y,
		int	w,
		int	h,
		const Fl_Menu_ *	m,
		int	selected = `0`
	)		const

Draws the menu item in bounding box x,y,w,h, optionally selects the item.

const Fl_Menu_Item * Fl_Menu_Item::find_shortcut	(	int *	ip = `0`,
		const bool	require_alt = `false`
	)		const

Search only the top level menu for a shortcut.

Either &x in the label or the shortcut fields are used.

This tests the current event, which must be an FL_KEYBOARD or FL_SHORTCUT, against a shortcut value.

Parameters

ip	returns the index of the item, if `ip` is not NULL.
require_alt	if true: match only if Alt key is pressed.

Returns: found Fl_Menu_Item or NULL

const Fl_Menu_Item* Fl_Menu_Item::first ( ) const

inline

Returns the first menu item, same as next(0).

Fl_Menu_Item* Fl_Menu_Item::first ( )

inline

Returns the first menu item, same as next(0).

void Fl_Menu_Item::hide ( )

inline

Hides an item in the menu.

int Fl_Menu_Item::insert	(	int	index,
		const char *	mytext,
		int	sc,
		Fl_Callback *	cb,
		void *	data = `0`,
		int	myflags = `0`
	)

Inserts an item at position index.

If index is -1, the item is added the same way as Fl_Menu_Item::add().

If 'mytext' contains any un-escaped front slashes (/), it's assumed a menu pathname is being specified, and the value of index will be ignored.

In all other aspects, the behavior of insert() is the same as add().

Parameters

index	insert new items here
mytext	new label string, details see above
sc	keyboard shortcut for new item
cb	callback function for new item
data	user data for new item
myflags	menu flags as described in FL_Menu_Item

Returns: the index into the menu() array, where the entry was added

const char* Fl_Menu_Item::label ( ) const

inline

Returns 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_Color Fl_Menu_Item::labelcolor ( ) const

inline

Gets the menu item's label 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.

void Fl_Menu_Item::labelcolor ( Fl_Color a )

inline

Sets the menu item's label color.

See Also: Fl_Color Fl_Menu_Item::labelcolor() const

Fl_Font Fl_Menu_Item::labelfont ( ) const

inline

Gets the menu item's label 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.

void Fl_Menu_Item::labelfont ( Fl_Font a )

inline

Sets the menu item's label 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.

Fl_Fontsize Fl_Menu_Item::labelsize ( ) const

inline

Gets the label font pixel size/height.

void Fl_Menu_Item::labelsize ( Fl_Fontsize a )

inline

Sets the label font pixel size/height.

Fl_Labeltype Fl_Menu_Item::labeltype ( ) const

inline

Returns the menu item's 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.

void Fl_Menu_Item::labeltype ( Fl_Labeltype a )

inline

Sets the menu item's 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.

int Fl_Menu_Item::measure	(	int *	hp,
		const Fl_Menu_ *	m
	)		const

Measures width of label, including effect of & characters.

Optionally, can get height if hp is not NULL.

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

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.

Fl_Menu_Item* Fl_Menu_Item::next ( int i = 1 )

inline

Advances 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.

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 *	initial_item = `0`,
		const Fl_Menu_ *	pbutton = `0`,
		const Fl_Menu_Item *	t = `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.

int Fl_Menu_Item::radio ( ) const

inline

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.

void Fl_Menu_Item::set ( )

inline

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 items set.

int Fl_Menu_Item::shortcut ( ) const

inline

Gets what key combination shortcut will trigger the menu item.

void Fl_Menu_Item::shortcut ( int s )

inline

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

void Fl_Menu_Item::show ( )

inline

Makes an item visible in the menu.

int Fl_Menu_Item::submenu ( ) const

inline

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.

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 '

void Fl_Menu_Item::uncheck ( )

inline

back compatibility only

Deprecated:: .

int Fl_Menu_Item::value ( ) const

inline

Returns the current value of the check or radio item.

This is zero (0) if the menu item is not checked and non-zero otherwise. You should not rely on a particular value, only zero or non-zero.

Note: The returned value for a checked menu item as of FLTK 1.3.2 is FL_MENU_VALUE (4), but may be 1 in a future version.

int Fl_Menu_Item::visible ( ) const

inline

Gets the visibility of an item.

The documentation for this struct was generated from the following files:

Fl_Menu_Item.H
Fl_Menu.cxx
Fl_Menu_.cxx
Fl_Menu_add.cxx

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation