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

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

#### 19.2.1 Adding Nmenu Objects

To add a nmenu object use

    FL_OBJECT *fl_add_nmenu(int type, FL_Coord x, FL_Coord y,
                            FL_Coord w, FL_Coord h, const char *label);

There are currently three types:

`FL_NORMAL_NMENU`

  Probably the most often used type: shown as text on a borderless background, popup gets opened when clicked on.

`FL_NORMAL_TOUCH_NMENU`

  Also shown as text on a borderless background, but popup gets opened when the mouse is moved on top of it without any further user action required.

`FL_BUTTON_NMENU`

  When not active shown as text on borderless background, when clicked on popup is shown and the object itself being displayed as a button.

`FL_BUTTON_TOUCH_NMENU`

  When not active shown as text on borderless background, when mouse is moved onto it the popup is shown and the object itself is displayed as a button.

Once a new nmenu object has been created items have to be added to it. For this the following function exists:

    FL_POPUP_ENTRY *fl_add_nmenu_items(FL_OBJECT *obj,
                                       const char items, ...);

(The function can also be used to append new items to a nmenu object that already has items.)

The function returns a pointer to the first menu entry added on success and `NULL` on failure. `items` is a string with the items to add, separated by the `'|'` character. In the simplest case you would just use something like `"Item 1|Item 2|Item 3"` to add three items to the list.

As also described in the documentation for the similar function `fl_popup_add_entries()` the text for an item may contain "special sequences" that start with the character `'%'` and then may require an additional argument passed to the function after the `items` argument. All of those described in detail in the documentation for the `fl_popup_add_entries()` function can also be used for nmenus.

Another way to set up the popup of a select object, using an array of FL_POPUP_ITEM structures, is via the function

    FL_POPUP_ENTRY *fl_set_nmenu_items(FL_OBJECT *obj, FL_POPUP_ITEM *item);

The function returns a pointer to the first menu item on success and `NULL` on failure. The function expects as arguments a pointer to the nmenu object and an array of `FL_POPUP_ITEM` structuress, with the very last element having `NULL` as the `text` member to mark the end of the array.

The `text` member of the structure may contain the character sequence `"%S"` to have the text drawn for the item split up at that position and with everything before `"%S"` drawn left-flushed and the rest right-flushed. Moreover, `text` may start with the character `'/'` and/or `'_'`. For an underline character a line is drawn above the item. And if there’s a slash this item marks the begin of a sub-menu with all further items belonging to the sub-menu until a structure with member `text` being set to `NULL` is found in the array. (The `'/'` and `'_'` characters are, of course, not drawn.)

`type` indicates the type of the item. It can be

`FL_POPUP_NORMAL`

  A normal, plain item.

`FL_POPUP_TOGGLE`

  An item that represents one of two states and is drawn with a check-marker when in "on" state.

`FL_POPUP_RADIO`

  A radio item, i.e., it belongs to a group of items of which only one can be in "on" state at a time. They are drawn with a circle to the left with the circle for the "selected" item being filled with a color.

Please note that if `text` starts with a `'/'` the type must be `FL_POPUP_NORMAL`.

The `state` member per default is `FL_POPUP_NONE`. It can be set to

`FL_POPUP_NONE`

  No special flags are set for the state of the item.

`FL_POPUP_DSABLED`

  The item is disabled and can’t be selected.

`FL_POPUP_HIDDEN`

  The item is hidden, i.e., does not get shown (and thus can’t be selected).

`FL_POPUP_CHECKED`

  Only relevant for toggle or radio items, marks it as in "on" state.

`callback` is a function that will be called if the item is selected. The callback function has the following type:

    typedef int (*FL_POPUP_CB)(FL_POPUP_RETURN *);

It receives a pointer to a structure that contains all information about the entry selected by the user:

    typedef struct {
        long int              val;       /* value assigned to entry */
        void                 *user_data; /* pointer to user data */
        const char           *text;      /* text of selected popup entry */
        const char           *label;     /* text drawn on left side */
        const char           *accel;     /* text drawn on right side */
        const FL_POPUP_ENTRY *entry;     /* selected popup entry */
        const FL_POPUP       *popup;     /* (sub-)popup it belongs to */
    } FL_POPUP_RETURN;

`val` is a value that has been associated with the entry and `user_data` is a pointer that can be used to store the location of further information. `text` is the text that was used to create the entry (including all "special" characters), while `label` and `accel` are the texts shown for the entry on the left and right. `entry` is the pointer to the structure for the entry selected and `popup` to the (sub-) popup the entry belongs to (see Part III Popups for more details on these structures).

If the callback function already does all the work required on selection of the item have it return the value `FL_IGNORE` to keep the selection from being reported back to the main loop of the program.

Finally, `shortcut` is a string encoding the keybord shortcut to be used for the item.

There’s also a third method to "populate" a menu. If you already created a popup than you can set it as the menu’s popup via a call of

    int fl_set_nmenu_popup(FL_POPUP *popup);

Of course, the popup you associate with the nmenu object in this way can’t be a sub-popup.

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