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

Next: Popup Attributes, Previous: Popup Interaction, Up: Part III Popups [Contents][Index]

### 22.3 Other Popup Routines

When `fl_popup_do()` is called the popup per default is shown with its left upper corner at the mouse position (unless the popup wouldn’t fit onto the screen). Using

    void fl_popup_set_position(FL_POPUP *popup, int x, int y);

the position where the popup is drawn can be changed (but if it wouldn’t fit onto the screen at that position it will also changed automatically). `x` and `y`. to be given relative to the root window, define the position of the upper left hand corner. Using this function for sub-popups is useless, they always get opened as near as possible to the corresponding sub-popup entry.

When setting the position of a popup it can be useful to know the exact sizes of its window in advance. These can be obtained by calling

    int fl_popup_get_size(FL_POPUP *popup, unsigned int *w, unsigned int
    *h);

The function returns 0 on success and -1 on error (in case the supplied `popup` argument isn’t valid). Please note that the reported values are only valid until the popup is changed, e.g., by adding, deleting or changing entries or changing the appearance of the popup.

A callback function `cb()` of type `FL_POPUP_CB`, to be called when a entry (or an entry of a sub-popup) is selected, can be associated with a popup (or changed) using

    typedef int (*FL_POPUP_CB)(FL_POPUP_RETURN *);
    FL_POPUP_CB fl_popup_set_callback(FL_POPUP *popup, FL_POPUP_CB cb);

The function returns the old setting of the callback routine (on error `NULL` is returned, which may indistinguishable from the case that no callback was set before).

For an entry all three associated callback functions can be set via

    FL_POPUP_CB fl_popup_entry_set_callback(FL_POPUP_ENTRY *entry,
                                            FL_POPUP_CB cb);
    FL_POPUP_CB fl_popup_entry_set_enter_callback(FL_POPUP_ENTRY *entry,
                                                  FL_POPUP_CB enter_cb)
    FL_POPUP_CB fl_popup_entry_set_leave_callback(FL_POPUP_ENTRY *entry,
                                                  FL_POPUP_CB leave_cb);

The first function sets the callback invoked when the entry is selected, the second when the mouse enters the area of the entry and the third, when the mouse leaves that area. All function return the previously set callback or `NULL` when none was set or an error occured. `NULL` also gets returned on errors.

There are three properties that can be set for a popup entry

`FL_POPUP_DISABLED`

  The entry is is shown as disabled and can’t be selected.

`FL_POPUP_HIDDEN`

  The entry is not shown when the popup is opened.

`FL_POPUP_CHECKED`

  Relevant only for toggle and redio entries. When set beside the label of a toggle entry a check-marker is drawn while the circle beside a radio button is drawn colored.

The "state" of an entry is the binary OR of these values which can be set and queried using the functions

    unsigned int fl_popup_entry_set_state(FL_POPUP_ENTRY *entry,
                                          unsigned int state);
    unsigned int fl_popup_entry_get_state(FL_POPUP_ENTRY *entry);

`fl_popup_entry_set_state()` returns the previous state on success and `UINT_MAX` (a value with all bits set) on failure.

Note that when setting `FL_POPUP_CHECKED` for a radio entry all other radio entries belonging to the same group automatically lose their "on" (checked) property.

There are also three convenience function for clearing, raising and toggling bits in the state of an entry. Normally to clear a certain bit of the state you have to first call `fl_popup_entry_get_state()`, then clear the bit in the return value and finally call `fl_popup_entry_set_state()` with the result to set the new state. Use of these convenience functions allows to change state bits in a single call.

    unsigned int fl_popup_entry_clear_state(FL_POPUP_ENTRY *entry,
                                            unsigned int what);
    unsigned int fl_popup_entry_raise_state(FL_POPUP_ENTRY *entry,
                                            unsigned int what);
    unsigned int fl_popup_entry_toggle_state(FL_POPUP_ENTRY *entry,
                                             unsigned int what);

The `what` argument can be any value resulting from a bitwise OR of `FL_POPUP_DISABLED`, `FL_POPUP_HIDDEN` and `FL_POPUP_CHECKED` (thus you can clear, set or toggle one or more bits of the state in a single call). The functions all return the original value of the state.

You may search for an entry in a popup by different criteria (please note that the search also includes sub-popups of the popup, you can identify them by checking the `popup` member of the FL_POPUP_ENTRY structure). The search obviously will only deliver reasonable results if what you’re searching for is unique between all the entries.

First, you can ask for the entry that had been created with a certain text, including all the special sequences, by calling

    FL_POPUP_ENTRY *fl_popup_entry_get_by_text(FL_POPUP *popup,
                                               const char *text);
    FL_POPUP_ENTRY *fl_popup_entry_get_by_text_f(FL_POPUP *popup,
                                                 const char *fmt, ...);

The functions returns either a pointer to the entry found or `NULL` on failure (because either no entry with this text was found or the popup doesn’t exist). (The functions differ in that the first one accepts just a simple string while the second assembles the text from a format string, just as it’s used for `printf()` etc., and an appropriate number of following arguments.)

You may as well search by the left-flushed label parts of the entries as shown on the screen (note that tab characters `'\t'` originally embedded in the text used when creating the label have been replaced by single spaces and backspace characters `'\b'` were removed as well as all special sequences)

    FL_POPUP_ENTRY *fl_popup_entry_get_by_label(FL_POPUP *popup,
                                                const char *label);
    FL_POPUP_ENTRY *fl_popup_entry_get_by_label_f(FL_POPUP *popup,
                                                  const char *fmt, ...);

Thus, since an entry created via a string like `"I\bt%Tem\t1%SCtrl+X"` will shown with a left-flushed label part of `"Item 1"`, this will be found when searching with either this string or a format string fo e.g., `"Item %d"` and a following integer argument of `1`.

Another way to search for an entry is by its value as either specified via the `"%x"` special sequence or assigned automatically by

    FL_POPUP_ENTRY *fl_popup_entry_get_by_value(FL_POPUP *popup,
                                                long value);

Also the `user_data` pointer associated with the entry can be used as the search criterion:

    FL_POPUP_ENTRY *fl_popup_entry_get_by_user_data(FL_POPUP *popup,
                                                    void *user_data);

Finally one can try to find an entry by its current position in the popup (note that here sub-popups aren’t taken into consideration since that would make the meaning of "position" rather hard to define) by

    FL_POPUP_ENTRY *fl_popup_entry_get_by_position(FL_POPUP *popup,
                                                   long position);

where `posistion` is starting with 0, so when called with 0 the first entry will be returned, when called with 1 you get the second entry etc. Note that separator lines aren’t counted but entries currently being hidden are.

Next: Popup Attributes, Previous: Popup Interaction, Up: Part III Popups [Contents][Index]