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

Next: Other Popup Routines, Previous: Adding Popups, Up: Part III Popups [Contents][Index]

### 22.2 Popup Interaction

A popup will be drawn on the screen when the function

    FL_POPUP_RETURN *fl_popup_do(FL_POPUP *popup);

is called. It only returns when the user either selects an entry or closes it in some other way (e.g., by clicking outside the popup’s area). When a selection was made the function returns a pointer to a `FL_POPUP_RETURN` structure with information about the entry that was selected (please note that the structure is internal storage belonging to the Forms Library and is re-used when the popup is shown again, so copy out all data you may need to keep). If no selection was made (or one of the invoked callback routines returned a value of `FL_IGNORE` (-1) `NULL` is returned.

While the popup is shown the user can interact with the popup using the mouse or the keyboard. When the mouse is hovering over a selectable entry of the popup the entry is highlighted, when the mouse reaches an entry for a sub-popup, the associated sub-popup automatically gets opened. A selection is made by clicking on an entry (or, in case that the popup was opened while a mouse button was pressed down, when the mouse button is released). Clicking outside the popups window (or, depending on the "policy", see below, releasing the mouse button somewhere else than over a selectable item) closes the popup without a selection being made.

Popups also can be controlled via the keyboard. First of all, on pressing a key, the shortcuts set for items are evaluated and, if a match is found, the corresponding entry is returned as selected (if the popup currently shown is a sub-popup, first the shortcuts for this sub-popup are checked, then those of its parent etc. until the top-most popup has been reached and checked for). The user can also navigate through the selectable entires using the `<Up>` and `<Down>` arrow keys and open and close sub-popups with the `<Right>` and `<Left>` cursor keys. Pressing the `<Home>` key highlights the first (selectable) entry in the popup, `<End>` the last one. By using the `<Esc>` key (or `<Cancel>` if available) the currently shown popup is closed (if an entry in a sub-popup was highlighted just this sub-popup is closed). Finally, pressing `<Return>` while on a selectable entry results in this entry being reported as selected.

Once the user has selected an entry its callback function is invoked with a `FL_POPUP_RETURN` structure as the argument. When this function returns, the callback for the popup the entry belongs to is called with exactly the same structure. If the popup is a sub-popup, next the callback for its "parent" popup is invoked, again with the same structure (except that the `popup` member is changed each time to indicate which popup the call is made for). Repeat until the callback for the top-most popup has been called. Finally the structure used in all those callback invocations is returned from `fl_popup_do()`. This chain of callback calls is interrupted when one of the callbacks returns a value of `FL_IGNORE` (-1). In that case no further callbacks are invoked and `fl_popup_do()` returns `NULL`, i.e., from the callers perspective it looks as if no selection has been made. This can be useful when one of the callbacks was already was able to do all the work required on a selection.

Per default a popup stays open when the user releases the mouse button anywhere else than on a selectable entry. It only gets closed when the user either selects an entry or clicks somewhere outside of the popup area. An alternative is a "drag-down" popup that gets closed whenever the mouse button is released, even if the mouse isn’t on the area of the popup or a selectable entry. To achieve this effect you can change the "policy" using the function

    int fl_popup_set_policy(FL_POPUP *popup, int policy);

There are two values `policy` can have:

`FL_POPUP_NORMAL_SELECT`

  Default, popup stays open until mouse button is released on a selectable entry or button is clicked outside the popups area.

`FL_POPUP_DRAG_SELECT`

  Popup is closed when the mouse button is released anywhere.

The function can be called with either a (valid) popup address, in which case the policy for that popup is changed, or with a `NULL` pointer to change the default setting of the policy, used in the creation of new popups. The function returns the previous policy value or -1 on errors.

It’s also possible to determine the policy setting by using

    int fl_popup_get_policy(Fl_POPUP *popup);

If called with the address of a (valid) popup the policy for this popup (or its parent if one exists) gets returned. If called with a `NULL` pointer the default policy used in creating new popups is returned. On error -1gets returned.

Calling the function with `NULL` as the `popup` argument changes the default setting for the popups created afterwards.

If the popup is partially off-screen the user can push the mouse at the screen borders in the direction of the currently invisible popup entries. This results in the popups window getting moved so that previosuly invisible entries become accessible. The popup window gets shifted vertically in single entry steps, in horizontal direction by a tenth of the screen width. The delay between shifts is about 100 ms.

Next: Other Popup Routines, Previous: Adding Popups, Up: Part III Popups [Contents][Index]