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::Widgets 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
Creates a new fltk::Menu widget using the given position, size,
and label string. It is created with no child items.
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).
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().
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).
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.
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.
Return the widget identified by the focus fields (or NULL if it is
illegal). This also sets item() to the same
value.
For a non-hierarchial menu this does the same thing as focus(). The items are numbered from zero.
Returns children() (for back compatability with
older versions of fltk).
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.
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.
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.
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!)
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.
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.
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.
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.
Does delete find(label), thus destroying the matching item,
if it exists.