diff options
Diffstat (limited to 'src/Fl_Menu_add.cxx')
| -rw-r--r-- | src/Fl_Menu_add.cxx | 91 |
1 files changed, 82 insertions, 9 deletions
diff --git a/src/Fl_Menu_add.cxx b/src/Fl_Menu_add.cxx index ba5d0931d..7bc766948 100644 --- a/src/Fl_Menu_add.cxx +++ b/src/Fl_Menu_add.cxx @@ -24,7 +24,6 @@ // // http://www.fltk.org/str.php // - // Methods to alter the menu in an Fl_Menu_ widget. // These are for Forms emulation and for dynamically changing the @@ -97,9 +96,10 @@ static int compare(const char* a, const char* b) { } } -// Add 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): +/** 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): +*/ int Fl_Menu_Item::add( const char *mytext, int sc, @@ -175,7 +175,68 @@ int Fl_Menu_Item::add( if (array == local_array) local_array_size = msize; return m-array; } - +/** + Adds a new menu item, with a title string, shortcut int (or string), + callback, argument to the callback, and flags. + If the menu array was directly set with menu(x) then copy() is done + to make a private array. + + <p>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. The "\" character is used to escape the next + character in the string. Labels starting with the "_" character + cause a divider to be placed after that menu item.</p> + + <p>A label of the form "foo/bar/baz" will create a + submenus called "foo" and "bar" with an + entry called "baz". The "/" character is ignored if it + appears as the first character of the label string, e.g. + "/foo/bar/baz".</p> + + <p>The label string is copied to new memory and can be freed. + The other arguments (including the shortcut) are copied into the + menu item unchanged. </P> + + <P>If an item exists already with that name then it is replaced with + this new one. Otherwise this new one is added to the end of the + correct menu or submenu. The return value is the offset into the array + that the new entry was placed at.</P> + + <P>Shortcut can be 0L, or either a modifier/key combination (for example + FL_CTRL+'A') or a string describing the shortcut in one of two ways:</p> + + <pre> + [#+^]<ascii_value> eg. "97", "^97", "+97", "#97" + [#+^]<ascii_char> eg. "a", "^a", "+a", "#a" + </pre> + ..where <ascii_value> is a decimal value representing an + ascii character (eg. 97 is the ascii for 'a'), and the optional + prefixes enhance the value that follows. Multiple prefixes must + appear in the above order. + <pre> + # - Alt + + - Shift + ^ - Control + </pre> + Text shortcuts are converted to integer shortcut by calling + int fl_old_shortcut(const char*). + + <P>The return value is the index into the array that the entry was put. </P> + + <P>No items must be added to a menu during a callback to the same menu.</P> + + + <h4>int Fl_Menu_::add(const char *)</H4> + + <P>The passed string is split at any '|' characters and then + add(s,0,0,0,0) is done with each section. This is + often useful if you are just using the value, and is compatible + with Forms and other GL programs. The section strings use the + same special characters as described for the long version of add()</p> + + <P>No items must be added to a menu during a callback to the same menu. +*/ int Fl_Menu_::add(const char *t, int s, Fl_Callback *c,void *v,int f) { // make this widget own the local array: if (this != fl_menu_array_owner) { @@ -218,9 +279,11 @@ int Fl_Menu_::add(const char *t, int s, Fl_Callback *c,void *v,int f) { return r; } -// 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. +/** + This is a Forms (and SGI GL library) compatible add function, it + adds many menu items, with '|' seperating the menu items, and tab + separating the menu item names from an optional shortcut string. +*/ int Fl_Menu_::add(const char *str) { char buf[1024]; int r = 0; @@ -238,6 +301,11 @@ int Fl_Menu_::add(const char *str) { return r; } +/** + Changes the text of item n. This is the only way to get + slash into an add()'ed menu item. If the menu array was directly set + with menu(x) then copy() is done to make a private array. +*/ void Fl_Menu_::replace(int i, const char *str) { if (i<0 || i>=size()) return; if (!alloc) copy(menu_); @@ -247,7 +315,12 @@ void Fl_Menu_::replace(int i, const char *str) { } menu_[i].text = str; } - +/** + Deletes item n from the menu. If the menu array was directly + set with menu(x) then copy() is done to make a private array. + + <P>No items must be removed from a menu during a callback to the same menu. +*/ void Fl_Menu_::remove(int i) { int n = size(); if (i<0 || i>=n) return; |