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