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