Other Nmenu Routines (XForms (Forms Library) - Version 1.2 (Rev. 4) A Graphical User Interface Toolkit for X)

Next: Nmenu Attributes, Previous: Nmenu Interaction, Up: Nmenu Object [Contents][Index]

#### 19.2.3 Other Nmenu Routines

To find out which item of a nmenu object was selected last use

    FL_POPUP_RETURN *fl_get_nmenu_item(FL_OBJECT *obj);

The function returns either a pointer to a `FL_POPUP_RETURN` structure with informations about the selected item (as already discussed above when talking about callbacks) or `NULL` if no selection was made the last time the nmenu object was used.

For some actions, e.g., deletion of an item etc., it is necessary to know the popup entry that represents it. Therefore it’s possible to search the list of items according to several criteria:

    FL_POPUP_ENTRY *fl_get_nmenu_item_by_value(FL_OBJECT *obj, long val);
    FL_POPUP_ENTRY *fl_get_nmenu_item_by_label(FL_OBJECT *obj,
                                               const char *label);
    FL_POPUP_ENTRY *fl_get_nmenu_item_by_label(FL_OBJECT *obj,
                                               const char *text);

The first function, `fl_get_nmenu_item_by_value()`, searches through the list of all items (including items in sub-popups) and returns the first one with the `val` associated with the item (or `NULL` if none is found). The second, `fl_get_nmenu_item_by_label()` searches for a certain label as displayed for the item in the popup. The third, `fl_get_nmenu_item_by_text()` searches for the text the item was created by (that might be the same as the label text in simple cases). Please note that all functions return a structure of type `FL_POPUP_ENTRY` (and not `FL_POPUP_RETURN`, which gives you direct access to the entry in the popup for the item.

Using e.g., the results of the above searches a nmenu item can be deleted:

    int fl_delete_nmenu_item(FL_OBJECT *obj, FL_POPUP_ENTRY *item);

Alternatively, an item can be replaced by one or more items:

    FL_POPUP_ENTRY *fl_replace_nmenu_item(FL_OBJECT *obj,
                                          FL_POPUP_ENTRY *old,
                                          const char *new_items, ...);

where `old` is the item to replace and `new_items` is a string exactly as used for `fl_add_nmenu_items()` with informations about the new item(s).

One also may insert additional items using

    FL_POPUP_ENTRY *fl_insert_nmenu_items(FL_OBJECT *obj,
                                          FL_POPUP_ENTRY *after,
                                          const char *new_items, ...);

where `after` is the item after which the new items are to be inserted (use `NULL` to insert at the very start) and `new_items` is a string just like used with `fl_add_nmenu_items()` with informations about the additional item(s).

As you may remember, there are two different ways to "populate" a nmenu object. In one case you pass a kind of format string plus a variable number of arguments and in the other case an array of `FL_POPUP_ITEM` structures. The previously listed functions for inserting and replacing used the first "interface". But there are also three functions for using the alternative interface:

    FL_POPUP_ENTRY *fl_add_nmenu_items2(FL_OBJECT *obj,
                                        FL_POPUP_ITEM *items);
    FL_POPUP_ENTRY *fl_insert_nmenu_items2(FL_OBJECT *obj,
                                           FL_POPUP_ENTRY *after,
                                           FL_POPUP_ITEM *items);
    FL_POPUP_ENTRY *fl_replace_nmenu_items2(FL_OBJECT *obj,
                                            FL_POPUP_ENTRY *old_item,
                                            FL_POPUP_ITEM *items);

All three functions return a pointer to the first new entry in the nmenu’s popup on success and `NULL` on failure. The all take a pointer to the nmenu object as their first argument.

`fl_add_nmenu_items2()` appends the items given by the list specified via the second argument to the nmenu’s popup. `fl_insert_nmenu_items2()` inserts one or more new items (as given by the last argument) after the entry specified by `after` (if `after` is `NULL` the new items are inserted before all existing items). Finally, `fl_replace_nmenu_items2()` replaces the existing entry `old_item` with a new (or a list of new items specified by `items`.

Finally, there’s a function to remove all items from a nmenu object at once:

    in fl_clear_nmenu(FL_OBJECT *obj);

Next: Nmenu Attributes, Previous: Nmenu Interaction, Up: Nmenu Object [Contents][Index]