Menu Class Reference

Inherits Group.

Inherited by Browser, Choice, CycleButton, InputBrowser, ItemGroup, MenuBar, and PopupMenu.

List of all members.

Public Member Functions

 Menu (int, int, int, int, const char *l=0, bool begin=false)
List * list () const
void list (List *l)
void layout ()
int children (const int *indexes, int level) const
int children (int index) const
int children () const
Widget * child (const int *indexes, int level) const
Widget * child (int index) const
Widget * item () const
Widget * item (Widget *v)
bool set_item (const int *indexes, int level)
Widget * get_item ()
int value () const
bool value (int v)
int size () const
void layout_in (Widget *, const int *indexes, int level) const
void draw_in (Widget *, const int *indexes, int level, int, int) const
int find_selected (Widget *, const int *indexes, int level, int, int) const
Rectangle get_location (Widget *, const int *indexes, int level, int) const
int popup (const Rectangle &, const char *title=0, bool menubar=false)
int handle_shortcut ()
void execute (Widget *)
void global ()
Widget * find (const char *) const
void remove (const char *l)
Widget * add (const char *, unsigned shortcut, Callback *, void *=0, int=0)
Widget * replace (const char *, unsigned shortcut, Callback *, void *=0, int=0)
Widget * insert (int n, const char *, unsigned shortcut, Callback *, void *=0, int=0)
Widget * add (const char *, void *=0)
Group * add_group (const char *label, Group *parent=0, void *data=0)
Widget * add_leaf (const char *label, Group *parent=0, void *data=0)
Widget * add_many (const char *)
Widget * replace (const char *, void *=0)
Widget * insert (int n, const char *, void *=0)
void add (Widget &o)
void add (Widget *o)
void insert (Widget &o, int n)
void replace (int index, Widget &o)
void replace (Widget &old, Widget &o)
void remove (int index)
void remove (Widget &o)
void remove (Widget *o)

Static Public Member Functions

void default_callback (Widget *, void *)

Static Public Attributes

NamedStyle * default_style

Protected Member Functions

Widget * try_popup (const Rectangle &, const char *title=0, bool menubar=false)

Detailed Description

The Menu base class is used by Browser, Choice, MenuBar, PopupMenu, ComboBox, and other widgets. It is simply a Group and each item is a child Widget, but it provides functions to select and identify one of the widgets in the hierarchy below it and do that widget's callback directly, and functions to create and add Item and ItemGroup widgets to a hierarchy.

A Menu can take a pointer to a List object, which allows the user program to dynamically provide the items as they are needed. This is much easier than trying to maintain an array of Widgets in parallel with your own data structures.

It also provides several convienence functions for creating, rearranging, and deleting child Item and ItemGroup widgets.

Member Function Documentation

Widget * Menu::add (  const char *  label,
void *  data = 0
) 
 

Create a new Item and add it to the top-level of the hierarchy.

This matches add() from the Browser in fltk1.

Unlike the add() with more arguments, this one does *not* split the label at '/' characters. The label is used unchanged.

Widget * Menu::add (  const char *  label,
unsigned  shortcut,
Callback *  callback,
void *  data = 0,
int  flags = 0
) 
 

Split label at '/' characters and add a hierachial Item.

Adds new items and hierarchy to a Menu or Browser.

label : The label is split at '/' characters to automatically produce submenus. The submenus are created if they do not exist yet, and a new Item widget is added to the end of it.

A trailing '/' can be used to create an empty submenu (useful for forcing a certain ordering of menus before you know what items are in them).

Backslashes in the string "quote" the next character, which allows you to put forward slashes into a menu item. Notice that in C++ you must type "\\/" for a forward slash, and "\\\\" for a backward slash.

shortcut : 0 for no shortcut, CTRL|'a' for ctrl-a, etc.

callback : function to call when item picked. If null, the callback for the Menu widget itself is called.

data : second argument passed to the callback.

flags : useful flags are:

  • INACTIVE makes the item grayed out and unpickable
  • INVISIBLE makes it not visible to the user, as though it was not there. This is most useful for making extra shortcuts that do the same thing.
  • RAW_LABEL stops it from interpreting '&' and '@' characters in the label.

Returns a pointer to the new Item. You can further modify it to get results that can't be gotten from these function arguments.

Group * Menu::add_group (  const char *  label,
Group *  parent = 0,
void *  data = 0
) 
 

Add a parent widget to a (possibly) lower level of the hierarchy, such as returned by add_group().

Widget * Menu::add_leaf (  const char *  label,
Group *  parent = 0,
void *  data = 0
) 
 

Add a non-parent widget to a (possibly) lower level of the hierarchy, such as returned by add_group(). If parent is null or this then this is the same as add(label,data).

Widget * Menu::add_many (  const char *  str  ) 
 

This is a Forms (and SGI GL library) compatable add function, it adds many menu items, with '|' seperating the menu items, and tab seperating the menu item names from an optional shortcut string.

Widget * Menu::child (  int  n  )  const
 

Returns the given top-level child. Same as child(&index,0).

This Overrides the method of the same name on Group. This is so that an List can be used. However if no List is specified the action is identical to Group::child(index).

Reimplemented from Group.

Widget * Menu::child (  const int *  indexes,
int  level
)  const
 

Calls list()->child(this, indexes, level). If an List is used, the returned widget may be a temporary data structure and may be overwritten by another call to child() in this or any other Menu!

int Menu::children (   )  const
 

Returns the number of children at the top level. Same as children(0,0).

This Overrides the method of the same name on Group. This is so that an List can be used. However if no List is specified the action is identical to Group::children().

Reimplemented from Group.

int Menu::children (  int  i  )  const
 

Returns the number of children of some child. Same as children(&i,1).

int Menu::children (  const int *  indexes,
int  level
)  const
 

Calls list()->children(this, indexes, level)

void Menu::default_callback (  Widget *  widget,
void *  data
)  [static]
 

The default callback for Menu calls item()->do_callback() but if user_data() is not null it is used instead of the item's user_data().

Reimplemented from Widget.

void Menu::draw_in (  Widget *  widget,
const int *  indexes,
int  level,
int  selected,
int  drawn_selected
)  const
 

Draw the menu items inside the widget.

The widget's box() is drawn and the items are laid out exactly the same as for layout().

If selected is greater or equal to zero then that item is drawn in a selected manner.

If widget->damage()==DAMAGE_CHILD then it is assummed that only the items indicated by selected and drawn_selected need to be redrawn. This is used for minimal update to move the selection from one item to the next.

void Menu::execute (  Widget *  widget  ) 
 

Calls do_callback(). First it sets item() to the given widget, so the callback code can see it.

Notice that this calls the callback on the Menu widget itself, not on the menu item. However the default callback for Menu widget does item()->do_callback() so by default the callback for each menu item is done.

Widget * Menu::find (  const char *  label  )  const
 

Return the item with the given label

This searches both the top level for an exact match, and splits the label at '/' to find an item in a hierarchy. Thus it matches the strings passed to both the long and short forms of add().

If the item is found a pointer to it is returned, otherwise NULL is returned.

int Menu::find_selected (  Widget *  widget,
const int *  indexes,
int  level,
int  mx,
int  my
)  const
 

Return the index of the item that is under the location mx, my in the given widget, if the draw() method had been used to draw the items into the widget.

Widget * Menu::get_item (   ) 
 

Sets and returns item() based on the focus_index() in this and each child group, thus restoring the value saved with set_item().

This either returns a non-group node, or child group that has an illegal Group::focus_index(), or null if this focus_index() is illegal.

If an List is used this will probably only go to the first child and not descend any further.

Rectangle Menu::get_location (  Widget *  widget,
const int *  indexes,
int  level,
int  index
)  const
 

Return the bounding box of the given item inside the widget, if the draw() method had been used to draw the items into the widget.

void Menu::global (   ) 
 

Make the shortcuts for this menu work no matter what window has the focus when you type it (as long as modal() is off). This is done by using add_handler(). This 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, and you cannot destroy the Menu!

This should probably also put the items on the the Mac menubar.

int Menu::handle_shortcut (   ) 
 

Respond to the current SHORTCUT or KEY event by finding a menu item it matches and calling execute() on it. True is returned if a menu item is found, false if none. Items are searched for a matching shortcut() value. "&x" shortcuts are ignored, they are used only for navigating when the menu is visible.

If you use a List, only the top-most level items are searched for shortcuts. Recursion is done only if the children are Group widgets, and then only the actual children of that Group (not any List it may contain if it is another Menu) are searched. This is necessary because some Lists are infinite in size, and usually they don't have shortcuts anyway.

This will return invisible (but active) items, even though it is impossible to select these items with the gui. This is done so that more than one shortcut for an action may be given by putting multiple copies of the item in, where only the first is visible.

Widget * Menu::insert (  int  n,
const char *  label,
void *  data = 0
) 
 

Create a new Item and add it to the top-level of the hierarchy.

This matches insert() from the Browser in fltk1, except the index is 1 less than before (first item is zero, not 1)

Unlike the insert() with more arguments, this one does *not* split the label at '/' characters. The label is used unchanged.

Widget * Menu::insert (  int  n,
const char *  label,
unsigned  shortcut,
Callback *  callback,
void *  data = 0,
int  flags = 0
) 
 

Split label at '/' characters and add a hierachial Item.

Same rules as add() except the item is inserted at index n of the final menu. Use 0 to put it at the start. Any number larger or equal to the current item count adds the new item to the end.

Widget * Menu::item (  Widget *  v  )  [inline]
 

You can set item() with the second call, useful for outwitting the callback. This does not produce any visible change for the user.

Widget * Menu::item (   )  const [inline]
 

The "current item". In callbacks this is the item the user clicked on. Otherwise you probably can't make any assumptions about it's value.

Browser::goto_index() sets this to the current item.

Since this may be the result of calling child() the returned structure may be short-lived if an List is used.

void Menu::layout (   )  [virtual]
 

Does nothing. This avoids wasting time measuring all the menu items.

Reimplemented from Group.

void Menu::layout_in (  Widget *  widget,
const int *  indexes,
int  level
)  const
 

Resize the widget to contain the menu items that are the children of the item indicated by indexes and level (use 0 for the immediate children).

If the widget has vertical() true the menu items are laid out one above the other, as is usally done in the pull-down menu below a menubar. w() is set to the widest item, and h() to the sum of all the heights.

If the widget has horizontal() true then the items are laid out in rows, wrapping only when w() is exceeded. w() is changed only if it is too small to contain the smallest item. h() is set to the total height of all the rows.

The box(), leading(), textfont(), textsize(), and perhaps other style attributes of the widget are used when figuring out the total size and the size of each item.

void Menu::list (  List *  list  )  [inline]
 

Set the List that generates widgets for the menu. By default this is a dummy List that returns the child widgets of the Menu.

int Menu::popup (  const Rectangle &  rectangle,
const char *  title = 0,
bool  menubar = false
) 
 

Create and display a pop-up menu (or hierarchy of menus) showing the children of this Menu, then wait until the user picks an item or dismisses the menu. If the user picks an item then execute() is called for it and true is returned. False is returned if the user cancels the menu.

If there is a selected item in the menu (as determined by get_item()) then submenus are opened and all of them are positioned intitially so the mouse cursor is pointing at the selected item. This is incredibly useful and one of the main features of fltk that is missing from other toolkits.

x,y,w,h describe a rectangle that the current menu item should be centered over, and the menu is widened horizontally to w if it is narrower. The coordinates are measured relative to the widget whose handle() method is being executed now.

title is a widget (usually an Item) that is used to make a title atop the menu, in the style of SGI's popup menus. You cannot use a List child, as the drawing of the menu may navigate that list to other children, overwriting the original widget.

menubar is for internal use by menubars and should be left false.

void Menu::remove (  const char *  l  )  [inline]
 

Does find(l) and then deletes that widget.

Widget * Menu::replace (  const char *  label,
void *  data = 0
) 
 

Create or replace an Item at the top-level of the hierarchy.

The top level is searched for an item that matches the given label. If found it's data is changed to the passed data, if not found a new Item is created and added at the end.

Widget * Menu::replace (  const char *  label,
unsigned  shortcut,
Callback *  callback,
void *  data = 0,
int  flags = 0
) 
 

Split label at '/' characters and add or replace a hierachial Item.

This is what menu::add() did in fltk 1.

Same rules as add() except if the item already exists it is changed to this new data, instead of a second item with the same label being created.

If the label has any @ or & commands in any portion, that portion is relabelled, thus you can use this to change the appearance of existing menu items. However if the new label does not have any such commands, the label remains as before, with any older @-commands.

bool Menu::set_item (  const int *  indexes,
int  level
) 
 

Remembers a currently selected item in a hierarchy by setting the focus_index() of each group to point to the next one. The widget can then be recovered with get_item(). A redraw(DAMAGE_VALUE) is done so pulldown menus redraw their display.

int Menu::size (   )  const [inline]
 

Returns children() (for back compatability with older versions of fltk).

Widget * Menu::try_popup (  const Rectangle &  r,
const char *  title = 0,
bool  menubar = false
)  [protected]
 

Exactly the same as popup() except the selected child widget is returned, rather than execute() being called. This is probably more useful in most cases...

bool Menu::value (  int  v  ) 
 

Convienence function to do set_item() when there is only one level of hierarchy. In this case you can consider the menu items to be indexes starting at zero.

Reimplemented in Browser.

Member Data Documentation

NamedStyle * Menu::default_style [static]
 

This style is assigned to Menu subclasses.

Because of the need to be compatable with Windows, which has a somewhat inconsistent appearance, the default is different than Widget::default_style, and the usage of the fields is somewhat unusual:

  • The color(), textfont(), textsize(), textcolor() are used to draw each Item in the menu, unless the items set their own preferences. box() defaults to FLAT_BOX and color() defaults to GRAY75 to replicate Windows.
  • The popup menu window itself uses the box() that is stored in MenuWindow::default_style. It is not possible (or at least not easy) to make different popups have different borders.
  • However that box is colored by color(). Thus you can make the color different for each popup menu. This will only be visible if the items have transparent boxes.
  • The leading() is used to space apart the menu items. It defaults to 4 to replicate Windows.
  • buttonbox(), buttoncolor(), labelfont(), labelsize() and labelcolor() are not used. They can be used to draw the actual widget.

The Browser subclass sets the style back to Widget::default_style, so that they appear more like a text editor (ie they put the color and leading back to normal).

Reimplemented from Widget.

Reimplemented in Browser.

The documentation for this class was generated from the following files:
Sun Jan 7 00:55:18 2007. FLTK ©2006 Bill Spitzak and others.
Permission is granted to reproduce this manual or any portion for any purpose, provided this copyright and permission notice are preserved.