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

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

#### 19.1.3 Other Select Routines

To find out which item is currently selected use

    FL_POPUP_RETURN *fl_get_select_item(FL_OBJECT *obj);

It returns a pointer to a structure of type `FL_POPUP_RETURN` as already described above, containing all needed information about the selected item.

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_select_item_by_value(FL_OBJECT *obj, long val);
    FL_POPUP_ENTRY *fl_get_select_item_by_label(FL_OBJECT *obj,
                                                const char *label);
    FL_POPUP_ENTRY *fl_get_select_item_by_label_f(FL_OBJECT *obj,
                                                  const char *fmt, ...);
    FL_POPUP_ENTRY *fl_get_select_item_by_text(FL_OBJECT *obj,
                                               const char *text);
    FL_POPUP_ENTRY *fl_get_select_item_by_text_f(FL_OBJECT *obj,
                                                 const char *fmt, ...);

The first function, `fl_get_select_item_by_value()`, searches through the list of items and returns the first one with the `val` associated with the item (or `NULL` if none is found). The second and third, `fl_get_select_item_by_label()` and `fl_get_select_item_by_label_f()` searches for a certain label as displayed for the item in the popup. The last two, `fl_get_select_item_by_text()` and `fl_get_select_item_by_text_f()` searches for the text the item was created by (that might be the same as the label text in simple cases). The difference between the second and third and the forth and the last is the way the text is passed to the functions, it’s either a simple string or the result of the expansion of a format string as used for `printf()` etc. using the following unspecified arguments.

Please note that all these 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 result of one of the functions above you can also set the currently selected item via your program using

    FL_POPUP_RETURN *fl_set_select_item(FL_OBJECT *obj,
                                        FL_POPUP_ENTRY *entry);

Or you could use the result to delete an item:

    int fl_delete_select_item(FL_OBJECT *obj, FL_POPUP_ENTRY *entry);

Please note that the values associated with items won’t change due to removing an item.

Alternatively, you can replace an item by one or more new ones. To do that use

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

`old` designates the item to be removed and `new_items` is a string exactly like it would be used in `fl_add_select_items()` for the `items` argument, that defines the item(s) to replace the existing item. Please note that, unless values to be associated with the items (see the `val` member of the `FL_POPUP_RETURN` structure) there’s a twist here. When items get created they per default receive increasing values, starting at 0. This also holds for items that get created in the process of replacement. The result is that the ordering of those values in that case wont represent the order in which they appear in the select objects popup.

Another sometimes useful function allows insertion of new items somewhere in the middle of a list of already existing items:

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

`after` is the entry after which the new item(s) are to be inserted (if it’s `NULL` the new items are inserted at the very start). The rest of the arguments are the same as for `fl_replace_select_item()` and the same caveats about the values associated automatically with the new items holds.

It’s possible to remove all items from a select object by calling

    int fl_clear_select(FL_OBJECT *obj);

Afterwards you have to call again e.g., `fl_add_select_items()` to set new entries. Note that if you used `fl_set_select_popup()` to set a popup for the select object then that popup gets deleted automatically on calling `fl_clear_select()`! The values automatically associated with items when calling `fl_add_select_items()` will start at 0 again.

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