Next: Other Popup Routines, Previous: Adding Popups, Up: Part III Popups [Contents][Index]
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]