Next: , 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: , Up: Nmenu Object   [Contents][Index]