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

Next: Other XPopup Routines, Previous: Creating XPopups, Up: XPopup [Contents][Index]

#### 23.3.2 XPopup Interaction

To select an item, move the mouse to the item to be selected while keeping the mouse button pressed down and then release the mouse button on top of the item to be selected. If you don’t want to make a selection release the mouse button somewhere outside the area of the XPopup.

If you have a "hanging" XPopup, i.e., a XPopup that’s open even though the mouse button isn’t pressed anymore you can select by clicking on an item or use the cursor `Up` and `Down` keys to navigate through the items and select by pressing the `<Return>` key. The `<Home>` and `<End>` keys allow you to jump to the first or last selectable item, respectively. Use `<Esc>` to close the popup without selecting an item.

It is also possible to use convenience functions to bind keyboard keys to items (the "hotkeys") instead of using `%s` with `fl_defpup()`:

    void fl_setpup_shortcut(int popup_id, int item_val,
                            const char *hotkeys);

where `item_val` is the value associated with the item (either due to its position or set with `%x`) and hotkeys is a string specifying all the hotkey combinations. See Shortcuts, for details. Briefly, within that string `#` and `^` denote the `<Alt>` and `<Ctrl>` keys, respectively. `&n` with `n = 1, 2` etc. can be used to denote the function key numbered `n`. Thus if hotkeys is set to `"#a^A`, both `<Ctrl>A` and `<Alt>A` are bound to the item. One additional property of the hotkey is the underlining of corresponding letters in the item string. Again, only the first key in the hotkey string is used. Therefore, the hotkey strings `"Cc"`, `"#C"` and `"^C"` will result in the character `C` in the item string `"A Choice"` being underlined, while the the hotkey strings `"cC"` and `"#c"` will not since there’s no `c` in the item string. There is a limit of maximum 8 shortcut keys.

Two convenience functions are available to set the callback functions for items of a XPopup and the XPopup as a whole (called whenever a selection is made):

    typedef int (*FL_PUP_CB)(int);
    FL_PUP_CB fl_setpup_itemcb(int popup_id, int item_val, FL_PUP_CB cb);
    FL_PUP_CB fl_setpup_menucb(int popup_id, FL_PUP_CB cb);

These functions thus allow to change the popup and item callback functions set at creation of the popup with `%F` and `%f`. As usual, `popup_id` is the ID of the XPopup, `item_val` the value associated with the item (position or value set via `%x`), and `cb` is the address of the callback function.

Please note that Xpopup objects are a bit special in XForms. Normal objects get returned by e.g., `fl_do_forms()` (or an associated callback gets invoked). But since Xpopup objects are meant to be sub-objects of other objects (like `FL_CHOICE` and `L_MENU` objects) and don’t get invoked directly by a call of e.g., `fl_do_forms()` but instead by a call of `fl_dopup()` they can’t get returned to the application. Instead the caller of `fl_dopup()` (normally some internal function of a `FL_CHOICE` or `FL_MENU` object) has to deal with the return value.

Furthermore, also callback functions can be set that get invoked whenever an item in the XPopup is entered or left, even without a selection being made. The following functions can be used to register these item enter/leave callbacks:

    typedef void (*FL_PUP_ENTERCB)(int item_val, void *data);
    typedef void (*FL_PUP_LEAVECB)(int item_val, void *data);

    FL_PUP_ENTERCB fl_setpup_entercb(int popup_id,
                                     FL_PUP_ENTERCB cb, void *data);
    FL_PUP_LEAVECB fl_setpup_leavecb(int popup_id,
                                     FL_PUP_LEAVECB cb, void *data);

The function `cb` will be called when the mouse enters or leaves an (non-disabled) item of the XPopup `popup_id`. Two parameters are passed to the callback function. The first parameter is the item number enter/leave applies to and the second parameter is a data pointer. To remove an enter/leave callback, call the functions with the callback function argument `cb` set to `NULL`.

There is also a function to associate a XPopup item with a sub-XPopup

    void fl_setpup_submenu(int popup_id, int item_val, int subpopup_id);

If a sub-XPopup is associated with item `item_val` that item can’t be selected anymore (releasing the mouse button on this item makes `fl_dopup()` return -1 but instead a new XPopup is opened beside the item and you can now make selections within this sub-XPopup. It is the programmers responsibility to make sure that the item values of the sub-XPopup don’t clash with those of the higher-level XPopup or it may be impossible to determine which item was selected.

Next: Other XPopup Routines, Previous: Creating XPopups, Up: XPopup [Contents][Index]