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

Next: Other Select Routines, Previous: Adding Select Objects, Up: Select Object [Contents][Index]

#### 19.1.2 Select Interaction

The simplest interaction with a select object consists of clicking onto the object and then selecting an item in the popup that gets shown directly beside the mouse position.

If you click with the left or right mouse button onto the select object previous or next item, respectively, will be selected. If youl keep the left or mouse button pressed down for a longer time slowly all alternatives are selected, one after each other.

You finally can also use the scroll wheel of your mouse to select the next or previous item (scrolling down selects the next, scrolling up the previous item).

On every selection of an item (also if the already selected item is re-selected) a callback that may have been associated with the item is executed. The callback receives as its argument a pointer to a structure of type `FL_POPUP_RETURN`.

Its `val` member is a integer value associated with the entry. It can be set explicitely on creation of the item using the `"%x"` "special sequence". If not given then first item gets the value 0, the next 1 etc. `user_data` is a pointer to some user data, which can be set on creation of the item using `"%u"`. `text` is the string used in creating the item, including all "special sequences", while `label` is the string shown in the popup for the item. If there was a special sequence of `"%S"` in the string that was used to create the item `accel` is the text that appears right-flushed in the popup for the item. `entry` is a pointer to the popup entry that represents the item in the select object and, finally, `popup` is the popup associated with the select object.

Normally, when a new item is selected this is reported back to the caller either by calling the select objects callback (if one exists) or by returning the object as the result of a call of e.g., `fl_do_forms()`. But if the callback for the item itself returns `FL_IGNORE` then the latter doesn’t happen. This can be useful for cases where all work for a change of the selection can already be done within the items callback and the "main loop" shouldn’t get involved anymore.

As for all other normal objects the condition under which a `FL_SELECT` object gets returned to the application (or an associate callback is called) can be influenced by calling the function

    int fl_set_object_return(FL_OBJECT *obj, unsigned int when)

where `when` can have the following values

`FL_RETURN_NONE`

  Never return or invoke a callback.

`FL_RETURN_END_CHANGED`

  Return or invoke callback if end of interaction and selection of an item coincide.

`FL_RETURN_CHANGED`

  Return or invoke callback whenever an item is selected (this is the default).

`FL_RETURN_END`

  Return or invoke callback on end of an interaction.

`FL_RETURN_ALWAYS`

  Return (or invoke callback) whenever the interaction ends and/or an item is selected.

Per default the popup of a select objects remains shown when the user releases the mouse somewhere outside the popup window (or on its title area). The alternative is to close the popup immediately when the user releases the mouse, independent of where it is. Using the function

    int fl_set_select_policy(FL_OBJECT *obj, int policy);

the program can switch between these two modes of operation, where `policy` can be on of two values:

`FL_POPUP_NORMAL_SELECT`

  Keeps the popup opened when the mouse isn’t released on one of the selectable items.

`FL_POPUP_DRAG_SELECT`

  Close the popup immediately when the mouse button is released.

The function returns on success the previous setting of the "policy" and -1 on error.

Next: Other Select Routines, Previous: Adding Select Objects, Up: Select Object [Contents][Index]