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

Previous: Other Popup Routines, Up: Part III Popups [Contents][Index]

### 22.4 Popup Attributes

Using

    void fl_popup_set_title(FL_POPUP *popup, const char *title);
    void fl_popup_set_title_f(FL_POPUP *popup, const char *fmt, ...);
    const char *fl_popup_set_title(FL_POPUP *popup);

the title of a popup can be changed or the currently set title determined. (The two functions for setting the title are just different in the way the title is passed: the first one receives a simple string while the second one assembles the title from a format string just like the one used with `printf()` etc. and an appropriate number of following arguments.)

To query or set the font the popups title is drawn in use

    void fl_popup_get_title_font(FL_POPUP *popup, int *size, int *style);
    void fl_popup_set_title_font(FL_POPUP *popup, int size, int style);

See Label Attributes and Fonts, for details about the sizes and styles that should be used. The default size and style are `FL_NORMAL_SIZE` and `FL_EMBOSSED_STYLE`. This setting also applies to sub-popups of the popup, thus setting a title font for sub-popups is useless.

When called with the `popup` argument set to `NULL` the default settings for popups generated later are returned or set.

Also the font for the entries of a popup can be queried or and set via

    void fl_popup_entry_get_font(FL_POPUP *popup, int *style, int *size);
    void fl_popup_entry_set_font(FL_POPUP *popup, int style, int size);

The defalt size is `FL_NORMAL_SIZE` and the default style is `FL_NORMAL_STYLE`. Again, the returned or set values also apply to all sub-popups, so calling the function for sub-popups doesn’t make sense.

When called with `popup` set to `NULL` the default settings for popups are returned or changed.

The width of a popup is calculated using the widths of the title and the entries. You can influence this width by setting a minimum width a popup should have. There are two functions for the minimum width:

    int fl_popup_get_min_width(FL_POPUP *popup);
    int fl_popup_set_min_width(FL_POPUP *popup, int min_width);

The first one returns the currently set minimum width (a negative return value indicates an error). The second allows sets a new minimum width. Setting the minimum width to 0 or a negative value switches the use of the minimum width off. It returns the previous value (or a negative value on error).

You can query or set the border width popups are drawn width (per default it’s set to `1`). To this purpose call

    int fl_popup_get_bw(FL_POPUP *popup);
    int fl_popup_set_bw(FL_POPUP *popup, int bw);

Please note that the border width setting is automatically applied also to sub-popups, so there’s no good reason to call these functions for sub-popups. The default border width is the same as that for objects.

The functions can also be called with `popup` set to `NULL` in which case the default setting for the border width is returned or set, respectively.

To change the cursor that is displayed when a popup is shown use

    void fl_popup_set_cursor(FL_POPUP *popup, int cursor_name);

Use one of the symbolic cursor names (shapes) defined by standard X or the integer value returned by `fl_create_bitmap_cursor()` or one of the Forms Library’s pre-defined symbolic names for the `cursor_name` argument.

Per default the cursor named `"XC_sb_right_arrow"` is used. If the function is called with `popup` set to `NULL` the default cursor for popups generated afterwards is changed.

There are several colors used in drawing a popup. These can be set or queried with the functions

    FL_COLOR fl_popup_set_color(FL_POPUP *popup, int type,
                                FL_COLOR color);
    FL_COLOR fl_popup_get_color(FL_POPUP *popup, int type);

where `type` can be one of the following values:

`FL_POPUP_BACKGROUND_COLOR`

  Background color of the popup, default is `FL_MCOL`.

`FL_POPUP_HIGHLIGHT_COLOR`

  Backgroud color an entry is drawn with when it’s selectable and the mouse is on top of it, default is `FL_BOTTOM_BCOL`.

`FL_POPUP_TITLE_COLOR`

  Color used for the title text of a popup, default is `FL_BLACK`.

`FL_POPUP_TEXT_COLOR`

  Color normal used for entry texts, default is `FL_BLACK`.

`FL_POPUP_HIGHLIGHT_TEXT_COLOR`

  Color of the entry text when it’s selectable and the mouse is on top of it, default is `FL_WHITE`.

`FL_POPUP_DISABLED_TEXT_COLOR`

  Color for drawing the text of disabled entries, default is `FL_INACTIVE_COL`.

`FL_POPUP_RADIO_COLOR`

  Color the circle drawn for radio entris in "on" state is drawn in.

When setting a new color the color previously used is returned by `fl_popup_set_color()`. Calling these functions for sub-popups doesn’t make sense since sub-popups are always drawn in the colors set for the parent popup.

When called with `popup` set to `NULL` the functions return or set the default colors of popups created afterwards.

To change the text of a popup entry call

    int fl_popup_entry_set_text(FL_POPUP_ENTRY *entry, const char *text);

Please note that in the text no special sequences except `"%S"` (at which place the text is split to make up the left- and right-flushed part of the label drawn) are recognized.

The shortcut keys for a popup label can be changed using

    void fl_popup_entry_set_shortcut(FL_POPUP_ENTRY *entry,
                                     const char *shortcuts);

See Shortcuts, for details on how such a string has to look like.

The value assigned to a popup entry can be changed via

    long fl_popup_entry_set_value(FL_POPUP_ENTRY *entry, long value);

The function returns the previous value.

Also the user data pointer associated with a popup entry can be modified by calling

    void *fl_popup_entry_set_user_data(FL_POPUP_ENTRY *entry,
                                       void *user_data);

The function returns the previous setting of `user_data`.

To determine to which group a radio entry belongs call

    int fl_popup_entry_get_group(FL_POPUP_ENTRY *entry);

Obviously, this function only makes much sense when applied to radio entries. It returns the group number on success and `INT_MAX` on failure (that’s why `INT_MAX` shouldn’t be used for group numbers).

To assign a radio entry to a different group call

    int fl_popup_entry_set_group(FL_POPUP_ENTRY *entry, int group);

Again, for obvious reasons, the function should normally only be called for radio entries. It returns the previous group number on success and `INT_MAX` on failure. If one of the entries of the new group was in "on" state the entries state will be reset to "off" if necessary.

For entries other than radio entries the group isn’t used at all. So, theoretically, it could be used to store a bit of additional information. If that would be good programming practice is another question...

Finally, the sub-popup associated with a sub-popup-entry can be queried or changed using the functions

    FL_POPUP *fl_popup_entry_get_subpopup(FL_POPUP_ENTRY *entry);
    FL_POPUP *fl_popup_entry_get_subpopup(FL_POPUP_ENTRY *entry,
                                          FL_POPUP *subpopup);

Obviously, calling these functions only makes sense for sub-popup entries.

`fl_popup_entry_get_subpopup()` returns the address of the sub-popup associated with the entry or `NULL` on failure.

To change the sub-popup of an entry a valid sub-popup must be passed to `fl_popup_entry_set_subpopup()`, i.e., the sub-popup must not already be a sub-popup of another entry or the popup the entry belongs to itself. You also can’t set a new sub-popup while the old sub-popup associated with the entry or the popup to become the new sub-popup is shown. On success the address of the new sub-popup is returned, on failure `NULL`.

Note that this function deletes the old sub-popup that was associated with the popup.

Previous: Other Popup Routines, Up: Part III Popups [Contents][Index]