The class contains a pointer to an array of structures of type Fl_Menu_Item. The - array may either be supplied directly by the user program, or it may + + Currently FLTK provides you with Fl_Menu_Button, Fl_Menu_Bar, and Fl_Choice. + + The class contains a pointer to an array of structures of type Fl_Menu_Item. + The array may either be supplied directly by the user program, or it may be "private": a dynamically allocated array managed by the Fl_Menu_. When the user clicks a menu item, value() is set to that item and then: - - If the Fl_Menu_Item has a callback set, that callback - is invoked with any userdata configured for it. - (The Fl_Menu_ widget's callback is NOT invoked. + - If the Fl_Menu_Item has a callback set, that callback + is invoked with any userdata configured for it. + (The Fl_Menu_ widget's callback is NOT invoked.) - - For any Fl_Menu_Items that \b don't have a callback set, - the Fl_Menu_ widget's callback is invoked with any userdata - configured for it. The callback can determine which item - was picked using value(), mvalue(), item_pathname(), etc. + - For any Fl_Menu_Items that \b don't have a callback set, + the Fl_Menu_ widget's callback is invoked with any userdata + configured for it. The callback can determine which item + was picked using value(), mvalue(), item_pathname(), etc. */ class FL_EXPORT Fl_Menu_ : public Fl_Widget { @@ -106,12 +106,12 @@ public: } \endcode - */ + */ const Fl_Menu_Item *menu() const {return menu_;} void menu(const Fl_Menu_Item *m); void copy(const Fl_Menu_Item *m, void* user_data = 0); int insert(int index, const char*, int shortcut, Fl_Callback*, void* = 0, int = 0); - int add(const char*, int shortcut, Fl_Callback*, void* = 0, int = 0); // see src/Fl_Menu_add.cxx + int add(const char*, int shortcut, Fl_Callback*, void* = 0, int = 0); // see src/Fl_Menu_add.cxx /** See int Fl_Menu_::add(const char* label, int shortcut, Fl_Callback*, void *user_data=0, int flags=0) */ int add(const char* a, const char* b, Fl_Callback* c, void* d = 0, int e = 0) { return add(a,fl_old_shortcut(b),c,d,e); @@ -127,7 +127,7 @@ public: int clear_submenu(int index); void replace(int,const char *); void remove(int); - /** Changes the shortcut of item i to n. */ + /** Changes the shortcut of item \p i to \p s. */ void shortcut(int i, int s) {menu_[i].shortcut(s);} /** Sets the flags of item i. For a list of the flags, see Fl_Menu_Item. */ void mode(int i,int fl) {menu_[i].flags = fl;} @@ -166,9 +166,9 @@ public: /** This box type is used to surround the currently-selected items in the - menus. If this is FL_NO_BOX then it acts like - FL_THIN_UP_BOX and selection_color() acts like - FL_WHITE, for back compatibility. + menus. If this is FL_NO_BOX then it acts like + FL_THIN_UP_BOX and selection_color() acts like + FL_WHITE, for back compatibility. */ Fl_Boxtype down_box() const {return (Fl_Boxtype)down_box_;} /** See Fl_Boxtype Fl_Menu_::down_box() const */ diff --git a/FL/Fl_Menu_Bar.H b/FL/Fl_Menu_Bar.H index 98127e33c..dcb76652a 100644 --- a/FL/Fl_Menu_Bar.H +++ b/FL/Fl_Menu_Bar.H @@ -3,7 +3,7 @@ // // Menu bar header file for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2010 by Bill Spitzak and others. +// Copyright 1998-2016 by Bill Spitzak and others. // // This library is free software. Distribution and use rights are outlined in // the file "COPYING" which should have been included with this file. If this @@ -29,35 +29,39 @@ put this widget along the top edge of your window. The height of the widget should be 30 for the menu titles to draw correctly with the default font. -
The items on the bar and the menus they bring up are defined by a - single Fl_Menu_Item - array. Because a Fl_Menu_Item array defines a hierarchy, the + + The items on the bar and the menus they bring up are defined by a + single Fl_Menu_Item array. + Because a Fl_Menu_Item array defines a hierarchy, the top level menu defines the items in the menubar, while the submenus define the pull-down menus. Sub-sub menus and lower pop up to the right - of the submenus.
-\image html menubar.png
+ of the submenus. + + \image html menubar.png \image latex menubar.png " menubar" width=12cm -If there is an item in the top menu that is not a title of a + + If there is an item in the top menu that is not a title of a submenu, then it acts like a "button" in the menubar. Clicking on it - will pick it.
+ will pick it. When the user clicks a menu item, value() is set to that item and then: - - The item's callback is done if one has been set; the - Fl_Menu_Bar is passed as the Fl_Widget* argument, - along with any userdata configured for the callback. + - The item's callback is done if one has been set; the + Fl_Menu_Bar is passed as the Fl_Widget* argument, + along with any userdata configured for the callback. - - If the item does not have a callback, the Fl_Menu_Bar's callback - is done instead, along with any userdata configured for the callback. - The callback can determine which item was picked using - value(), mvalue(), item_pathname(), etc. + - If the item does not have a callback, the Fl_Menu_Bar's callback + is done instead, along with any userdata configured for the callback. + The callback can determine which item was picked using + value(), mvalue(), item_pathname(), etc. -Submenus will also pop up in response to shortcuts indicated by + Submenus will also pop up in response to shortcuts indicated by putting a '&' character in the name field of the menu item. If you put a '&' character in a top-level "button" then the shortcut picks it. The - '&' character in submenus is ignored until the menu is popped up.
-Typing the shortcut() of any of the menu items will cause + '&' character in submenus is ignored until the menu is popped up. + + Typing the shortcut() of any of the menu items will cause callbacks exactly the same as when you pick the item with the mouse. */ class FL_EXPORT Fl_Menu_Bar : public Fl_Menu_ { @@ -66,20 +70,24 @@ protected: public: int handle(int); /** - Creates a new Fl_Menu_Bar widget using the given position, + Creates a new Fl_Menu_Bar widget using the given position, size, and label string. The default boxtype is FL_UP_BOX. -
The constructor sets menu() to NULL. See - Fl_Menu_ for the methods to set or change the menu.
-labelsize(), labelfont(), and labelcolor() + + The constructor sets menu() to NULL. See + Fl_Menu_ for the methods to set or change the menu. + + labelsize(), labelfont(), and labelcolor() are used to control how the menubar items are drawn. They are initialized from the Fl_Menu static variables, but you can - change them if desired.
-label() is ignored unless you change align() to + change them if desired. + + label() is ignored unless you change align() to put it outside the menubar. -
The destructor removes the Fl_Menu_Bar widget and all of its
+
+ The destructor removes the Fl_Menu_Bar widget and all of its
menu items.
*/
- Fl_Menu_Bar(int X, int Y, int W, int H,const char *l=0);
+ Fl_Menu_Bar(int X, int Y, int W, int H, const char *l=0);
};
#endif
diff --git a/src/Fl_Menu_.cxx b/src/Fl_Menu_.cxx
index 6ab3797a3..487641a36 100644
--- a/src/Fl_Menu_.cxx
+++ b/src/Fl_Menu_.cxx
@@ -3,7 +3,7 @@
//
// Common menu code for the Fast Light Tool Kit (FLTK).
//
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
//
// This library is free software. Distribution and use rights are outlined in
// the file "COPYING" which should have been included with this file. If this
@@ -154,8 +154,8 @@ const Fl_Menu_Item * Fl_Menu_::find_item(const char *pathname) {
}
/**
- Find the index the menu array for given \p item.
-
+ Find the index into the menu array for a given \p item.
+
A way to convert a menu item pointer into an index.
Does \b not handle items that are in submenu pointers (FL_SUBMENU_POINTER).
@@ -175,7 +175,7 @@ const Fl_Menu_Item * Fl_Menu_::find_item(const char *pathname) {
if ( index == -1 ) { ..error.. }
\endcode
- \param item The *item to be found
+ \param[in] item The item to be found
\returns The index of the item, or -1 if not found.
\see menu()
*/
@@ -212,7 +212,7 @@ int Fl_Menu_::find_index(Fl_Callback *cb) const {
To get the menu item pointer for a pathname, use find_item()
- \param pathname The path and name of the menu item index to find
+ \param[in] pathname The path and name of the menu item to find
\returns The index of the matching item, or -1 if not found.
\see item_pathname()
@@ -254,7 +254,7 @@ int Fl_Menu_::find_index(const char *pathname) const {
internationalisation and a menu item can not be found using its label. This
search is also much faster.
- \param cb find the first item with this callback
+ \param[in] cb find the first item with this callback
\returns The item found, or NULL if not found
\see find_item(const char*)
*/
@@ -482,7 +482,7 @@ void Fl_Menu_::clear() {
is done to make a private array.
\warning Since this method can change the internal menu array, any menu
- item pointers or indecies the application may have cached can become
+ item pointers or indices the application may have cached can become
stale, and should be recalculated/refreshed.
\b Example:
diff --git a/src/Fl_Menu_add.cxx b/src/Fl_Menu_add.cxx
index 52b16d594..2406a383f 100644
--- a/src/Fl_Menu_add.cxx
+++ b/src/Fl_Menu_add.cxx
@@ -3,7 +3,7 @@
//
// Menu utilities for the Fast Light Tool Kit (FLTK).
//
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
//
// This library is free software. Distribution and use rights are outlined in
// the file "COPYING" which should have been included with this file. If this
@@ -94,13 +94,14 @@ static int compare(const char* a, const char* b) {
}
+/** Adds a menu item.
-/** 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).
+ 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 FL_SUBMENU in the flags).
- \returns the index into the menu() array, where the entry was added
- \see Fl_Menu_Item::insert(int, const char*, int, Fl_Callback*, void*, int myflags)
+ \returns the index into the menu() array, where the entry was added
+ \see Fl_Menu_Item::insert(int, const char*, int, Fl_Callback*, void*, int)
*/
int Fl_Menu_Item::add(
const char *mytext,
@@ -113,7 +114,6 @@ int Fl_Menu_Item::add(
}
-
/**
Inserts an item at position \p index.
@@ -125,12 +125,13 @@ int Fl_Menu_Item::add(
In all other aspects, the behavior of insert() is the same as add().
- \param index insert new items here
- \param mytext new label string, details see above
- \param sc keyboard shortcut for new item
- \param cb callback function for new item
- \param data user data for new item
- \param myflags menu flags as described in FL_Menu_Item
+ \param[in] index insert new items here
+ \param[in] mytext new label string, details see above
+ \param[in] sc keyboard shortcut for new item
+ \param[in] cb callback function for new item
+ \param[in] data user data for new item
+ \param[in] myflags menu flags as described in FL_Menu_Item
+
\returns the index into the menu() array, where the entry was added
*/
int Fl_Menu_Item::insert(
@@ -212,30 +213,33 @@ int Fl_Menu_Item::insert(
}
-
/**
Adds a new menu item.
-
- \param[in] label The text label for the menu item.
- \param[in] shortcut Optional keyboard shortcut that can be an int or string; (FL_CTRL+'a') or "^a". Default 0 if none.
- \param[in] callback Optional callback invoked when user clicks the item. Default 0 if none.
- \param[in] userdata Optional user data passed as an argument to the callback. Default 0 if none.
- \param[in] flags Optional flags that control the type of menu item; see below. Default is 0 for none.
- \returns The index into the menu() array, where the entry was added.
-
+
+ \param[in] label The text label for the menu item.
+ \param[in] shortcut Optional keyboard shortcut that can be an int or string:
+ (FL_CTRL+'a') or "^a". Default 0 if none.
+ \param[in] callback Optional callback invoked when user clicks the item.
+ Default 0 if none.
+ \param[in] userdata Optional user data passed as an argument to the callback.
+ Default 0 if none.
+ \param[in] flags Optional flags that control the type of menu item;
+ see below. Default is 0 for none.
+ \returns The index into the menu() array, where the entry was added.
+
\par Description
If the menu array was directly set with menu(x), then copy() is done
to make a private array.
\par
Since this method can change the internal menu array, any menu item
- pointers or indecies the application may have cached can become stale,
+ pointers or indices the application may have cached can become stale,
and should be recalculated/refreshed.
\par
A menu item's callback must not add() items to its parent menu during the callback.
Detailed Description of Parameters
\par label
- The menu item's label. This option is required.
+ The menu item's label. This argument is required and must not be NULL.
\par
The characters "&", "/", "\", and "_" are treated as special characters in the label string.
The "&" character specifies that the following character is an accelerator and will be underlined.
@@ -276,7 +280,7 @@ int Fl_Menu_Item::insert(
\endverbatim
\par
..where \