mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation fixes and clarifications.

Browse Source 
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@11801 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Albrecht Schlosser 2016-07-09 17:06:46 +00:00
parent a0086f7075
commit 189591d4b6
4 changed files with 97 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
FL/Fl_Menu_.H
View File

@ -3,7 +3,7 @@
//
// Menu base class 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,24 +29,24 @@
/**
Base class of all widgets that have a menu in FLTK.
Currently FLTK provides you with
Fl_Menu_Button, Fl_Menu_Bar, and Fl_Choice.
<P>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 */

60
FL/Fl_Menu_Bar.H
View File

@ -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.
<P>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. </P>
<P ALIGN=CENTER>\image html menubar.png</P>
of the submenus.
\image html menubar.png
\image latex menubar.png " menubar" width=12cm
<P>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. </P>
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.
<P>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. </P>
<P>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.
<P>The constructor sets menu() to NULL. See
Fl_Menu_ for the methods to set or change the menu. </P>
<P>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. </P>
<P>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.
<P>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

14
src/Fl_Menu_.cxx
View File

@ -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:

65
src/Fl_Menu_add.cxx
View File

@ -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.
<B>Detailed Description of Parameters</B>
\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 \<ascii_value\> is a decimal value representing an
ascii character (eg. 97 is the ascii code for 'a'), and the optional
ASCII character (eg. 97 is the ascii code for 'a'), and the optional
prefixes enhance the value that follows. Multiple prefixes must
appear in the order below.
\par
@ -316,6 +320,12 @@ int Fl_Menu_Item::insert(
FL_MENU_DIVIDER // Creates divider line below this item. Also ends a group of radio buttons.
\endcode
If FL_SUBMENU is set in an item's flags, then actually two items are added:
the first item is the menu item (submenu title), as expected, and the second
item is the submenu terminating item with the label and all other members
set to 0. If you add submenus with the 'path' technique, then the
corresponding submenu terminators (maybe more than one) are added as well.
\todo Raw integer shortcut needs examples.
Dependent on responses to http://fltk.org/newsgroups.php?gfltk.development+v:10086 and results of STR#2344
*/
@ -324,7 +334,6 @@ int Fl_Menu_::add(const char *label,int shortcut,Fl_Callback *callback,void *use
}
/**
Inserts a new menu item at the specified \p index position.
@ -354,8 +363,8 @@ int Fl_Menu_::add(const char *label,int shortcut,Fl_Callback *callback,void *use
\returns The index into the menu() array, where the entry was added.
\see add()
*/
*/
int Fl_Menu_::insert(
int index,
const char *label,
@ -368,7 +377,7 @@ int Fl_Menu_::insert(
if (this != fl_menu_array_owner) {
if (fl_menu_array_owner) {
Fl_Menu_* o = fl_menu_array_owner;
// the previous owner get's its own correctly-sized array:
// the previous owner gets its own correctly-sized array:
int value_offset = (int) (o->value_-local_array);
int n = local_array_size;
Fl_Menu_Item* newMenu = o->menu_ = new Fl_Menu_Item[n];