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

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

#### 23.1.4 Other Choice Routines

There are a number of routines to change the list of possible choices. To add a line to a choice object use

    int fl_addto_choice(FL_OBJECT *obj, const char *text);
    int fl_addto_choice_f(FL_OBJECT *obj, const char *fmt, ...);

The function returns the number of the new item. The items in the list are numbered in the order in which they were inserted. The first item has number 1, etc. The two functions differ in that the first one accepts just a simple string while for the second the text is assembled from a format string as used by `printf()` etc. and the following arguments.

Note that, because a choice object uses a popup, the string passed with `fl_addto_choice()` cann also contain some additional information not directly shown in the entries text. E.g., you can create several entries as once if the string you pass to `fl_addto_choice()` contains `'|'` characters - these aren’t shown but instead are treated as separators between the strings for the entries. Some extra control sequences, starting with the character `'%'` can also be embedded (see Creating XPopups), thus a literal `'%'` in a string must be escaped by doubling it.

To delete a line use:

    void fl_delete_choice(FL_OBJECT *obj, int line);

Whenever the application program wants to clear the complete list of choices it should use the routine

    void fl_clear_choice(FL_OBJECT *obj)

One can also replace a line using

    void fl_replace_choice(FL_OBJECT *obj, int line, const char *text);
    void fl_replace_choice(FL_OBJECT *obj, int line, const char *fmt, ...);

(The second function assembles the new text from a format string as used for `printf()` etc. and the following arguments.)

To obtain the currently selected item in the choice object use the call

    int fl_get_choice(FL_OBJECT *obj);

The function returns the number of the current choice (0 if there is no choice).

You can also obtain the text of the currently selected choice item using the call

    const char *fl_get_choice_text(FL_OBJECT *obj);

`NULL` is returned when there is no current choice.

To obtain the text of an arbitrary choice item, use the following routine

    const char *fl_get_choice_item_text(FL_OBJECT *obj, int n);

To obtain the total number of choice items, use the following function

    int fl_get_choice_maxitems(FL_OBJECT *obj);

One can set various attributes of an item using the following routine

    void fl_set_choice_item_mode(FL_OBJECT *obj, int numb, int mode);

Here `mode` is the same as that used for menu objects (see above). See also XPopup, for details.

To find about those settings use

    int fl_get_choice_item_mode(FL_OBJECT *obj, int numb);

You can use the follow routine to populate a choice object at once, including mode and shortcut, by using

    int fl_set_choice_entries(FL_OBJECT *obj, FL_PUP_ENTRY *entries);

where `entries` is a pointer to a `FL_PUP_ENTRY` structure (terminated by a `NULL` text field) as already described above for the function `fl_set_menu_entries()`. Also see XPopup, for more details. Please note that for choice objects no nested entries are permitted and the item callback functions are ignored. The function returns the number of items added to the choice object.

Finally, the application program can set the currently selected entry of the choice using a call of

    void fl_set_choice(FL_OBJECT *obj, int line);
    void fl_set_choice_text(FL_OBJECT *obj, const char *txt)
    void fl_set_choice_text_f(FL_OBJECT *obj, const char *fmt, ...)

where `txt` (for `fl_set_choice_text()` or the text resulting from the expansion of the `printf()`-compatible format string and the following arguments for `fl_set_choice_text_f()` must must be the text of exactly one of the choice items. For example, after the following choice is created

    fl_addto_choice(obj,"item1|item2|item3");

You can select the second item by using any of the following lines

    fl_set_choice(obj, 2);
    fl_set_choice_text(obj, "item2");
    fl_set_choice_text_f(obj, "item%d", 2 );

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