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

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

#### 19.1.1 Adding Select Objects

To add a select object to a form use

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

There are currently three types which just differ by the way they look:

`FL_NORMAL_SELECT`

  Per default this type is drawn as a rounded, flat box (but you can change that by setting a different boxtype for the object) with the text of the currently selected item in its center.

`FL_MENU_SELECT`

  This select object looks like a button with a little extra box at its right side (just like a `FL_MENU_BUTTON`) and the text of the currently selected item is drawn on the button-like object.

`FL_DROPLIST_SELECT`

  This type looks like a button with the text of the currently selected item on top of it and a second square button directly beside it with an downward pointing arrow on it.

Per default `label` is drawn outside and to the left of the object.

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

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

`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. If there weren’t any items before the first item will be automatically shown as the selected one.

As also described in the documentation for the similar function `fl_popup_add_entries()` (see Adding Popups) the text for an item may contain "special sequences" that start with the character `%` and the may require an additional argument passed to the function after the `items` argument:

`%x`

  Set a value of type `long int` that’s passed to all callback routines for the item. The value must be given in the arguments following the `items` string.

`%u`

  Set a `user_void` pointer that’s passed to all callbacks of the item. The pointer must be specified in the arguments following the `items` string.

`%f`

  Set a callback function that gets called when the item is selected. The function is of type

      int callback(FL_POPUP_RETURN *r);

  Information about the item etc. gets passed to the callback function via the `FL_POPUP_RETURN` structure and the return value of the function can be used to keep the selection from becoming reported back to the user made by returning a value of `FL_IGNORE` (-1). The function’s address must be given in the arguments following the `items` string.

`%E`

  Set a callback routine that gets called each time the mouse enters the item (as long as the item isn’t disabled or hidden). The type of the function is the same as that of the callback function for the selection of the item but it’s return value is never used. The functions address must be given in the arguments following the `items` string.

`%L`

  Set a callback routine that gets called each time the mouse leaves the item. The type of the function is the same that as of the callback function for the selection of the item but it’s return value is never used. The functions address must be given in the arguments following the `items` string.

`%d`

  Marks the item as disabled, i.e., it can’t be selected and its text is per default drawn in a different color

`%h`

  Marks the item as hidden, i.e., it is not shown while in this state.

`%S`

  For items with shortcut keys it’s quite common to have them shown on the right hand side. Using `"%S"` you can split the items text into two parts, the first one (before `"%S"`) being drawn flushed left and the second part flushed right. Note that using this special sequence doesn’t automatically sets a shortcut key, this still has to be done using `"%s"`.

`%s`

  Sets one or more shortcut keys for an item. Requires a string with the shortcuts in the arguments following the `items` string. See Shortcuts, for details on how to define shortcuts. Please note that the character in the label identical to the shortcut character is only shown as underlined if `"%S"` isn’t used.

`%%`

  Use this to get a `'%'` within the text of an item.

If you compare this list of "special sequences" with those listed for the `fl_popup_add_entries()` function you will find that aome are missing. This is because a select object is a simple linear list of items that uses only parts of the popups functionalities.

Another way to set up the popup of a select object is to use the function

    long fl_set_select_items(FL_OBJECT *obj, FL_POPUP_ITEM *item);

Here `item` is an array of structures of type `FL_POPUP_ITEM` with the `text` member of the very last element of the array being set to `NULL`, indicating the end of the array.

The `text` member is the text of the item. It may only contain one "special sequence", `"%S"` to indicate that the string is to be split at that position into the part of the item label to be drawn to the left and on the right side (also prepending the string with `'_'` or `'/'` has no effect). `callback` is a callback function to be invoked on selection of the item. `shortcut` is a string for setting keybord shortcuts for the item. `type` has no function at all here (there can be only items of type `FL_POPUP_NORMAL` in a select objects popup) and `state` can be set to `FL_POPUP_DISABLED` and/or `FL_POPUP_HIDDEN`.

Please note: when the select object already had items before the call of `fl_set_select_items()` then they are removed before the new ones are set. The values assigned to the items start at 0.

A third way to "populate" a select object is to create a popup directly and then associate it with the select object using

    int fl_set_select_popup(FL_OBJECT *obj, FL_POPUP *popup);

If the select object already had a popup before this will be deleted and replaced by the new popup passed as the second argument. Please note that the popup the argument `popup` points to may not contain any entries other than those of type `FL_POPUP_NORMAL` (and, of course, the popup can’t be a sub-popup of another popup).

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