## class fltk::Menu

### Class Hierarchy

    fltk::Widget
       |
       +----fltk::Group
               |
               +----fltk::Menu
                       |
                       +----fltk::Browser, fltk::Choice, fltk::MenuBar, fltk::MenuButton

### Include Files

    #include <fltk/Menu.h>

### Description

All widgets that display a (possibly hierarchial) list of similar items are subclassed off of `fltk::Menu`. This includes scrolling browsers, pop-up and pull-down menus and menubars, and the Windows-style "combo box".

This is a subclass of `fltk::Group` and each item is a child `fltk::Widget`, usually fltk::Item widgets, or fltk::ItemGroup widgets to make a hierarchy.

An `fltk::Menu` can take a pointer to an `fltk::List`, 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 `fltk::Widget`s in parallel with your own data structures.

It also provides several convienence functions for creating, rearranging, and deleteing fltk::Item and fltk::ItemGroup widgets.

### Methods

- fltk::Menu
- ~Menu
- list
- children
- children
- child

- child
- item
- focus
- get_focus
- value

- size
- popup
- handle_shortcut
- execute
- global

- add
- replace
- find
- insert
- remove

#### fltk::Menu::Menu(int x, int y, int w, int h, const char *label = 0)

Creates a new `fltk::Menu` widget using the given position, size, and label string. It is created with no child items.

#### fltk::Menu::~Menu()

Like all groups, the child widgets are deleted. Any fltk::List is not deleted.

#### fltk::List* fltk::Menu::list() const;
void fltk::Menu::list(fltk::List* list)

Get or set the fltk::List that generates widgets for the menu. If this is set it hides any child widgets (though an fltk::List implementation may retrieve them in order to combine them with it's own widgets).

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

Return how many children are under a given item. If level is zero, this returns how many items are at the top level. Otherwise indexes is an array of level numbers indicating the index of an item at the top level, the index of the an item that is the child of that, and so on.

This returns -1 if any item is not a "parent" or the index array is illegal. It is not necessary to return the correct value until the parent is "open", which means the fltk::OPEN flag was set in it, so if it is expensive to calculate the number an fltk::List can return 1 for any closed parent.

#### int fltk::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 fltk::Group. This is so that an fltk::List can be used. However if no fltk::List is specified the action is identical to `fltk::Group::children()`.

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

Return a given child from somewhere in the hierarchy. indexes is an array of indexes into each parent and contains level+1 numbers. `NULL` is returned if any of the passed indexes are out of range or the level goes below a non-parent.

If an fltk::List is used, this widget may be a temporary data structure and may be overwritten by another call to `child()` in this or any other `fltk::Menu`.

#### fltk::Widget* fltk::Menu::child(int index) const

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

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

#### fltk::Widget* fltk::Menu::item() const
void fltk::Menu::item(fltk::Widget*)

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.

The fltk::Browser sets this to the widget when you call `goto_index()`.

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

You can set the item with the second call, useful for outwitting the callback.

#### bool fltk::Menu::focus(const int* indexes, int level);

The current item is remembered in the `focus()` of each parent at each level. This is used by popup menus to pop up at the same item next time.

Storing it this way allows widgets to be inserted and deleted and the currently selected item does not change (because fltk::Group updates the focus index). But if an fltk::List is used and it does not return a different fltk::Group for each level in the hierarchy, the focus indexes will write over each other. fltk::Browser currently uses it's own code (with the insert/delete broken) to get around this.

`item()` is set to the located widget. True is returned if the indexes differ from last time.

#### fltk::Widget* fltk::Menu::get_focus()

Return the widget identified by the focus fields (or NULL if it is illegal). This also sets `item()` to the same value.

#### int fltk::Menu::value() const
void fltk::Menu::value(int v)

For a non-hierarchial menu this does the same thing as `focus()`. The items are numbered from zero.

#### int fltk::Menu::size() const

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

#### int fltk::Menu::popup(int x,int y,int w=0,int h=0,fltk::Widget* title=0,bool menubar=false);

Create and display a pop-up menu (or hierarchy of menus) showing the children widgets, and waits 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.

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 fltk::Item) that is used to make a title atop the menu, in the style of SGI's popup menus.

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

#### int fltk::Menu::handle_shortcut();

Respond to the current `fltk::SHORTCUT` or `fltk::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()` or for '&' characters in the label.

#### void fltk::Menu::execute(fltk::Widget*);

Standard action when the user picks an item. `item()` is set to it (so the callback can find it) and the callback of the fltk::Menu is called. If you don't change the callback, the default version does `item()->do_callback()` so by default the callback for each menu item is done.

This function also handles toggle/radio menu items, but that might change in the future.

#### void fltk::Menu::global();

Make the shortcuts for this menu work no matter what window has the focus when you type it (as long as `fltk::modal()` is off). This is done by using `fltk::add_handler()`. This `fltk::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 (so don't destroy the widget!)

#### fltk::Widget* fltk::Menu::add(const char* label, int shortcut, fltk::Callback*, void* user_data = 0, int flags = 0);
fltk::Widget* fltk::Menu::add(const char* label, void* user_data);

Convienece function for populating your menu. This creates a new fltk::Item with the given fields filled in. The label is copied to the widget so the passed string can be a temporary value.

The label text is split at '/' characters to automatically produce submenus. To actually put a '/' into a name you must either quote it with a '\\' before it or make it be the first character in a name. The new item is added to the end of the submenu if it already exists.

#### int fltk::Menu::add(const char *)

The passed string is split at any '|' characters and then `add(s,0,0,0,0)` is done with each section. For instance `menu->add("red|green|blue")` will add three items. This is compatable with XForms and many other GL-based programs.

#### fltk::Widget* fltk::Menu::replace(const char* label, int shortcut, fltk::Callback*, void* user_data = 0, int flags = 0);

Same as `add()` but if an item with that name (and in the same submenu) already exists, that widget is altered to these new values. This is what add() on menus did in fltk 1.0.

#### fltk::Widget* fltk::Menu::find(const char* label) const;

Does the same search as `add()` or `replace()` for an item with that name (including using '/' for submenus) and returns that item if it exists, or `NULL` if it does not.

#### fltk::Widget* fltk::Menu::insert(int n, const char* insert, void* user_data = 0);

Same as `add()` but the new item is inserted before item n in the top level. If this is a new submenu the whole submenu is inserted before that item. However if this is an existing submenu the item is added to it and it is not moved.

#### void fltk::Menu::remove(const char* label)

Does `delete find(label)`, thus destroying the matching item, if it exists.