[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 23. Deprecated Objects

In this chapter describes object types that have been replaced by newer ones. But they will remain part of XForms and also can be used in new programs. But there probably will be not more support for these objects than bug fixes etc.

## 23.1 Choice Object

A choice object is an object that allows the user the choose among a number of choices. The current choice is shown in the box of the choice object. The user can either cycle through the list of choices using the middle or right mouse button or get the list as a menu using the left mouse button.

### 23.1.1 Adding Choice Objects

To add a choice object to a form use the routine

    FL_OBJECT *fl_add_choice(int type, FL_Coord x, FL_Coord y,
                             FL_Coord w, FL_Coord h, const char *label);

It shows a box on the screen with the label to the left of it and the current choice (empty in the beginning), centered in the box.

### 23.1.2 Choice Types

The following types are available:

`FL_NORMAL_CHOICE`

  Middle/right mouse button shortcut.

`FL_NORMAL_CHOICE2`

  Same as `FL_NORMAL_CHOICE` except drawn differently.

`FL_DROPLIST_CHOICE`

  Menu is activated only by pressing and releasing the mouse on the arrow.

### 23.1.3 Choice Interaction

Beside simply opening up the popup behind the choice object and selecting an entry with the left mouse button you can also use the middle and right mouse buttons and the scroll wheel: a short click with the middle mouse button selects the entry before the currently selected one, a click with the right mouse button the next. Keeping the middle or right mouse button pressed down slowly cycles trough the entries, backward or forward. The same can be down with the sroll wheel.

In both cases, whenever a choice entry is selected (even when it is the original one) the object is returned to the application program. But you can control the condition under which the choice object gets returned to the application by using the function

    int fl_set_object_return(FL_OBJECT *obj, unsigned int when)

where `when` can have the following values

`FL_RETURN_NONE`

  Never return or invoke callback.

`FL_RETURN_END_CHANGED`

  Return or invoke callback if end of interaction and selection of an item coincide.

`FL_RETURN_CHANGED`

  Return or invoke callback whenever an item is selected (this is the default).

`FL_RETURN_END`

  Return or invoke callback on end of an interaction.

`FL_RETURN_ALWAYS`

  Return (or invoke callback) whenever the interaction ends and/or an item is selected.

### 23.1.4 Other Choice Routines

There are a number of routines to change the list of possible choices. To add a line to a choice object use

    int fl_addto_choice(FL_OBJECT *obj, const char *text);
    int fl_addto_choice_f(FL_OBJECT *obj, const char *fmt, ...);

The function returns the number of the new item. The items in the list are numbered in the order in which they were inserted. The first item has number 1, etc. The two functions differ in that the first one accepts just a simple string while for the second the text is assembled from a format string as used by `printf()` etc. and the following arguments.

Note that, because a choice object uses a popup, the string passed with `fl_addto_choice()` cann also contain some additional information not directly shown in the entries text. E.g., you can create several entries as once if the string you pass to `fl_addto_choice()` contains `'|'` characters - these aren't shown but instead are treated as separators between the strings for the entries. Some extra control sequences, starting with the character `'%'` can also be embedded (see section Creating XPopups), thus a literal `'%'` in a string must be escaped by doubling it.

To delete a line use:

    void fl_delete_choice(FL_OBJECT *obj, int line);

Whenever the application program wants to clear the complete list of choices it should use the routine

    void fl_clear_choice(FL_OBJECT *obj)

One can also replace a line using

    void fl_replace_choice(FL_OBJECT *obj, int line, const char *text);
    void fl_replace_choice(FL_OBJECT *obj, int line, const char *fmt, ...);

(The second function assembles the new text from a format string as used for `printf()` etc. and the following arguments.)

To obtain the currently selected item in the choice object use the call

    int fl_get_choice(FL_OBJECT *obj);

The function returns the number of the current choice (0 if there is no choice).

You can also obtain the text of the currently selected choice item using the call

    const char *fl_get_choice_text(FL_OBJECT *obj);

`NULL` is returned when there is no current choice.

To obtain the text of an arbitrary choice item, use the following routine

    const char *fl_get_choice_item_text(FL_OBJECT *obj, int n);

To obtain the total number of choice items, use the following function

    int fl_get_choice_maxitems(FL_OBJECT *obj);

One can set various attributes of an item using the following routine

    void fl_set_choice_item_mode(FL_OBJECT *obj, int numb, int mode);

Here `mode` is the same as that used for menu objects (see above). See also XPopup, for details.

To find about those settings use

    int fl_get_choice_item_mode(FL_OBJECT *obj, int numb);

You can use the follow routine to populate a choice object at once, including mode and shortcut, by using

    int fl_set_choice_entries(FL_OBJECT *obj, FL_PUP_ENTRY *entries);

where `entries` is a pointer to a `FL_PUP_ENTRY` structure (terminated by a `NULL` text field) as already described above for the function `fl_set_menu_entries()`. Also see XPopup, for more details. Please note that for choice objects no nested entries are permitted and the item callback functions are ignored. The function returns the number of items added to the choice object.

Finally, the application program can set the currently selected entry of the choice using a call of

    void fl_set_choice(FL_OBJECT *obj, int line);
    void fl_set_choice_text(FL_OBJECT *obj, const char *txt)
    void fl_set_choice_text_f(FL_OBJECT *obj, const char *fmt, ...)

where `txt` (for `fl_set_choice_text()` or the text resulting from the expansion of the `printf()`-compatible format string and the following arguments for `fl_set_choice_text_f()` must must be the text of exactly one of the choice items. For example, after the following choice is created

    fl_addto_choice(obj,"item1|item2|item3");

You can select the second item by using any of the following lines

    fl_set_choice(obj, 2);
    fl_set_choice_text(obj, "item2");
    fl_set_choice_text_f(obj, "item%d", 2 );

### 23.1.5 Choice Attributes

Don't use `FL_NO_BOX` as the boxtype for a choice object.

The first color argument (`col1` to `fl_set_object_color()` controls the color of the box and the second (`col2`) the color of the text in the box.

The current choice by default is shown centered in the box. To change the alignment of the choice text in the box, use the following routine

    void fl_set_choice_align(FL_OBJECT *obj, int align);

To set the font size used inside the choice object use

    void fl_set_choice_fontsize(FL_OBJECT *obj, int size);

To set the font style used inside the choice object use

    void fl_set_choice_fontstyle(FL_OBJECT *obj, int style);

Note that the above functions only change the font inside the choice object, not the font used in the popup. To change the font used in the popup, use the XPopup functions `fl_setpup_default_fontsize()` and `fl_setpup_default_fontstyle()`. Note that these functions influence the font settings of all popups! See section Label Attributes and Fonts, for details on font sizes and styles.

Normally the pop-up shown for the choice objects will be displayed at the current mouse position or, for those of type ``FL_DROPLIST_CHOICE``, directly below the choice object. This can be modified by a call of the function

    int fl_set_choice_align_bottom(GL_OBJECT *obj, int flag);

If `flag` is `0` the normal behaviour is used, but when `flag` is `1` the popup will be displayed with its lower right hand corner at the current mouse position or, for objects of type ``FL_DROPLIST_CHOICE`` above the choise object. The function returns the previously set value for `flag`.

### 23.1.6 Remarks

See ``choice.c`' for an example of the use of choice objects.

## 23.2 Menu Object

Also menus can be added to forms. These menus can be used to let the user choose from many different possibilities. Each menu object has a box with a label in it in the form. Whenever the user presses the mouse inside the box (or moves the mouse on top of the box) a pop-up menu appears. The user can then make a selection from the menu.

### 23.2.1 Adding Menu Objects

To add a menu to a form use the routine

    FL_OBJECT *fl_add_menu(int type, FL_Coord x, FL_Coord y,
                           FL_Coord w, FL_Coord h, const char *label);

It shows a box on the screen with the label centered in it.

### 23.2.2 Menu Types

The following types are available:

`FL_PUSH_MENU`

  The menu appears when the user presses a mouse button on it.

`FL_PULLDOWN_MENU`

  The menu appears when the user presses a mouse button on it.

`FL_TOUCH_MENU`

  The menu appears when the user move the mouse inside it.

`FL_PUSH_MENU` and `FL_PULLDOWN_MENU` behave rather similar. When you click on a `FL_PUSH_MENU` per default a pop-up window gets opened on top of the `FL_PUSH_MENU` menu's box that has a label at the top, indicating the currently selected menu item. The pop-up window stays open until you either select an item or press a mouse button somewhere outside the pop-up window.

When you click on `FL_PULLDOWN_MENU` also a pop-up window is shown, but directly below the menu's box. This pop-up window has no label and it only stays open until you release the mouse button.

`FL_PUSH_MENU` and `FL_PULLDOWN_MENU` can be made even more similar by using the `fl_set_menu_notitle()` function (see below). This changes it's properties so that the pop-up window also appears below the menu's box and that no label is shown in the pop-up window. The only remaining difference then is that a `FL_PUSH_MENU` only gets closed when a menu item is selected or the user presses the mouse outside of the pop-up window while a `FL_PULLDOWN_MENU` also gets closed when the mouse button is released.

### 23.2.3 Menu Interaction

When the menu appears the user can make a selection using the left mouse button or make no selection by clicking outside the menu (or by simply releasing the mouse button in case of a `FL_PULLDOWN_MENU` type menu. Normally when he makes a selection the menu object is returned by the interaction routines.

You can control the condition under which the menu object gets returned to the application by using the function

    int fl_set_object_return(FL_OBJECT *obj, unsigned int when)

where `when` can have the following values

`FL_RETURN_NONE`

  Never return the object or invoke its callback.

`FL_RETURN_END_CHANGED`

  Return or invoke callback if end of interaction and selection of an item coincide (this is the default for all menu objects except those of type `FL_TOUCH_MENU`).

`FL_RETURN_CHANGED`

  Return or invoke callback whenever an item is selected (this is the default for all menu objects of type `FL_TOUCH_MENU`).

`FL_RETURN_END`

  Return or invoke callback on end of an interaction.

`FL_RETURN_ALWAYS`

  Return (or invoke callback) whenever the interaction ends and/or an item is selected.

### 23.2.4 Other Menu Routines

There are two ways to populate a menu, i.e., add items. The first one is a bit more complex but allows for more flexibility, e.g., later adding and removing items, associating callbacks with individual items etc. For the more simple (and in many cases sufficient) method see the function `fl_set_menu_entries()`.

To set the actual menu for a menu object, use the routine

    void fl_set_menu(FL_OBJECT *obj, const char *menustr, ...);

`menustr` describes the menu in the form used by XPopups (see section XPopup). In the simplest case it just contains the texts for the menu items, separated by a bar (`'|'`), e.g., `"First|Second|Third"`. But it's also possible to employ special tags (see section Creating XPopups) that can be used to indicate special attributes (radio, toggle and greyed-out, for example). For this usage the unspecified arguments (the `...` in the function call) can be used t add neceassary information. Whenever the user selects a menu item, a pointer to the menu object it belongs to is returned to the application program.

Please note that if you call `fl_set_menu()` on a menu that already contains items those items are removed. The function calls `fl_clear_menu()` internally before the new items are added.

If you explicitely assign a menu item ID to a menu, using the special tag `%x`, it is your responsibility to make sure that this ID isn't already used by a different menu item in the same menu. Failure to do so may make it impossible to use the menu properly. All functions working on items expect the menu item ID as one of their arguments.

In case you don't set menu item IDs they are assigned automatically with the first item obtaining the menu item ID 1, the next 2 etc., i.e., it directly reflects the position of the item in the menu.

It is also possible to add menu items to an existing menu using a call of

    int fl_addto_menu(FL_OBJECT *obj, const char *menustr, ...);

where `menustr` is a string of the same form as used in `fl_set_menu()` (you can add one or more new menu items this way).

Also routines exist to delete a particular menu item or change it:

    void fl_delete_menu_item(FL_OBJECT *obj, int miid);
    void fl_replace_menu_item(FL_OBJECT *obj, int miid,
                               const char *menustr, ...);

`miid` is the menu item ID. `menustr` must be a string as used in `fl_set_menu()` with the only difference that only a single menu item can be specified.

Please note: when deleting a menu item all other items keep their menu item IDs. The menu item ID of the deleted menu item isn't re-used when new items are added later. Instead for each menu an internal counter exists that gets incremented for each menu item added and which value is used for the menu item ID unless one is explicitely assigned to the menu item. The counter oly gets reset to 1 when the menu is cleared used `fl_clear_menu()`.

The menu item ID of a menu item changed by using `fl_replace_menu_item()` does not change unless the library is explicitely asked to via `%x` in `menustr`.

For most applications, the following routine may be easier to use at the expense of somewhat restrictive value a menu item can have as well as a loss of the ability to delete menu items or associate callbacks with menu items.

    int fl_set_menu_entries(FL_OBJECT *obj, FL_PUP_ENTRY *ent);

where `ent` is a pointer to an array of structure of the following type, terminated by an element, where at least the `text` member is a `NULL` pointer:

    typedef struct {
        const char *text;
        FL_PUP_CB callback;
        const char *shortcut;
        int mode;
    } FL_PUP_ENTRY;

The meaning of each member is explained in Section 21.3. For menus, item callback function can be `NULL` if the menu callback handles the interaction results. See demo program ``popup.c`' for an example use of `fl_set_menu_entries()`.

The function `fl_set_menu_entries()` works by creating and associating a popup menu with the menu object. The popup ID is returned by the function. Whenever the function is called, the old popup associated with the object (if one exists) is freed and a new one is created. Although you can manipulate the menu either through the menu API (but adding and removing menu items is not supported for menus created this way ) or popup API, the application should not free the popup directly and use `fl_clear_menu()` instead.

To clear the whole menu use

    void fl_clear_menu(FL_OBJECT *obj);

To find the menu item selected by the user use

    int fl_get_menu(FL_OBJECT *obj);

The the function returns the menu item ID. In the simplest possible case this is just the position of the menu item (starting at 1). This stops to be true when either IDs have been explicitely assigned to items or items have been deleted. In that case the following rules apply:

1. A menu item ID may have been assigned to a menu item using `%xn` in the string for the text of the menu item.
2. Menu items can get associated with a callback function that is executed when the menu item is selected. The callback function is of type `FL_PUP_CB` and receives the menu item ID of the selected menu. If such a callback is set for a menu item the return value of `fl_get_menu()` is the return value of this function instead of the menu item ID that would have been returned otherwise.

To obtain the text of any item, use the following routine

    const char *fl_get_menu_item_text(FL_OBJECT *obj, int miid);

where `miid` is the menu item ID. If `n` isn't a valid menu iem ID item `NULL` is returned.

To obtain the text of the selected enu item use

    const char *fl_get_menu_text(FL_OBJECT *obj);

To obtain the total number of menu items, use the function

    int fl_get_menu_maxitems(FL_OBJECT *obj);

One can change the appearance of different menu items. In particular, it is sometimes desirable to make grey-out menu items and make them unselectable or to put boxes with and without checkmarks in front of them. This can be done using the routine:

    void fl_set_menu_item_mode(FL_OBJECT *obj, int miid, unsigned mode);

`miid` is the menu index ID of the memu item you want to change. `mode` represents the special properties you want to apply to the chosen item. You can specify more than one at a time by adding or bitwise OR-ing these values together. For this parameter, the following symbolic constants exist:

`FL_PUP_NONE`

  No special display characteristic, the default.

`FL_PUP_BOX`

  "Binary" entry, i.e., an entry that stands for a choice that can be switched on and off. Displayed with an unchecked box to the left.

`FL_PUP_RADIO`

  "Radio" item belonging to a group, so that gets automatically switched off when another item of the group is selected. Displayed with a diamoned-shaped box at the left.

`FL_PUP_GREY`

  To be OR-ed with one of the above to make that item appear greyed-out and disable it (i.e., not selectable anymore).

`FL_PUP_CHECK`

  To be OR-ed with one of `FL_PUP_BOX` and `FL_PUP_RADIO` to make the box to the left appear checked or pushed.

There is also a routine that can be used to obtain the current mode of an item after interaction, mostly useful for toggle or radio items:

    unsigned int fl_get_menu_item_mode(FL_OBJECT *obj, int miid);

While a callback associated with a menu entry can be set when it is created it can also set later on or be changed. For this use the function

    FL_PUP_CB fl_set_menu_item_callback(FL_OBJECT *ob,
                                        int numb, FL_PUP_CB cb);

where `numb` is the menu entries ID and `cb` is the callback function of type `FL_PUP_CB` (or `NULL` to disable a callback). The return value is a pointer to the previously used callback function (or `NULL`).

It is often useful to define keyboard shortcuts for particular menu items. For example, it would be nice to have `<Alt>s` behave like selecting "Save" from a menu. This can be done using the following routine:

    void fl_set_menu_item_shortcut(FL_OBJECT *obj, int miid,
                                   const char *str);

`miid` is the menu item ID of the menu item under consideration. `str` contains the shortcut for the item. (Actually, it can contain more shortcuts for the same item.) See section Shortcuts, for more information about shortcuts.

Finally there is the routine:

    void fl_show_menu_symbol(FL_OBJECT *obj, int yes_no);

With this routine you can indicate whether to show a menu symbol at the right of the menu label. By default no symbol is shown.

### 23.2.5 Menu Attributes

Any boxtype can be used for a menu except for those of type `FL_PULLDOWN_MENU`, for which `FL_NO_BOX` should not be used.

Using the functiond

The first color argument (`col1`) to `fl_set_object_color()` controls the color of the menu's box when not open and the second (`col2`) is the color when the menu is shown.

To change the font style and size used in the popup menus (not the menu label), use the following routines

    void fl_setpup_default_fontstyle(int style);
    void fl_setpup_default_fontsize(int size);

These settings apply to all menus at once.

If desired, you can attach an external popup to a menu object via the following routine

    void fl_set_menu_popup(FL_OBJECT *obj, int pupID);

where `pupID` is the ID returned by `fl_newpup()` or `fl_defpup()`. See section XPopup, for more details on popup creation.

For a menu created this way only `fl_get_menu()` and `fl_get_menu_text()` work as expected. Other services such as mode setting and query etc. should be done via the popup routines.

To obtain the popup ID associated with a menu, use the following routine

    int fl_get_menu_popup(FL_OBJECT *obj);

The function returns the popup ID if the menu was created using `fl_set_menu_popup()` or `fl_set_menu_entries()`, otherwise it returns -1.

The callback associated with a menu

Normally in the popup opened for a menu a title is shown. This can be switched off (and back on again by using the function

    fl_set_menu_notitle(FL_OBJECT *obj, int off);

### 23.2.6 Remarks

See ``menu.c`' for an example of the use of menus. You can also use `FL_MENU_BUTTON` to initiate a callback and use an XPopup directly within the callback. See ``pup.c`' for an example of this approach.

## 23.3 XPopup

XPopup is not really an object class, but because it is used by menu and choice objects and can function stand-alone, it is documented here.

XPopups are simple transient windows that show a number of choices the user can click on to select the desired option.

### 23.3.1 Creating XPopups

To define a new popup, use the following routines

    int fl_newpup(Window parent);
    int fl_defpup(Window parent, const char *str, ...);

Both functions allocate and initialize a new popup menu and return the XPopup identifier (or -1 on failure). `fl_defpup()` in addition accepts a pointer `str` to the texts for menu items (optionally also some more arguments, see below). More than one item can be specified by using a vertical bar (`|`) between the items, e.g., `"foo|bar"` adds two menu items. The `parent` parameter specifies the window to which the XPopup belongs. In a situation where the XPopup is used inside an object callback `FL_ObjWin(obj)` will do. If `parent` is `None` the root window will be used.

Calling `fl_defpup()` with the `str` argument set to `NULL` is equivalent to calling `fl_newpup()`.

It is possible to specify XPopup and item properties, such as shortcuts, callbacks etc., together with the items texts using a format string system similar as used for e.g., `oprint(3)`. If XPopup or item properties require arguments, they must be passed to `fl_defpup()` following the `str` argument.

The following item properties are supported:

`%t`

  Marks the item text as the XPopup title string.

`%F`

  Binds a callback function to the XPopup as a whole that is called for every selection made from this XPopup. You must specify the function to be invoked in the parameters following `str`. The value of the selected item is passed as the only argument to the invoked callback function. The callback function must return a non-negative integer. If such a callback function has been registered for a XPopup and you select its third item, in the simplest case 3 will be passed as a parameter to the callback function (more complicated situations would involve that the item had been assigned a different value. e.g., using `%x`, see below, or that there's also a callback bound to the item itself, in which case the global XPopup callback would receive the return value of the items callback function).

`%f`

  Binds a callback to this particular item which is invoked if the item is selected. The routine must be supplied in the parameters following `str`. It has to return a non-negative integer. The value of the selected item is passed as a parameter to this function. If you have also bound the entire XPopup to a callback function via `%F`, then the function specified via `%f` is called first with the items value and its return value (if larger then `0` is then passed as the parameter to to the function bound to the whole XPopup (as set via `%F`).

`%i`

  Disables and greys-out the item. `%d` can be used instead of `%i`.

`%l`

  Adds a line under the current entry. This is useful in providing visual clues to groups of entries

`%m`

  Whenever this item is selected another (already defined) XPopup is bound to the item so that the sub-XPopup is opened when the user moves the mouse onto the item, This can be used to create cascading menus. The identifier of the sub-XPopup to be shown must be provided in the arguments following `str`. 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.

`%h`

  Specify a "hotkeys" that can be used to select this item. Hotkeys must be given in the arguments following `str` as a pointer to a string. Use `#` to specify that a key must be pressed together with the `<Alt>` key, `^` for simultaneous pressing of `<Ctrl>` and `&n` for the function key `Fn`.

  `%s` can be used instead of `%h`.

`%xn`

  Assigns a numerical value to this item. This value must be positive. This new value overrides the default position-based value assigned to this item. Different from most other flags, the value `n` must be entered as part of the text string (i.e., do not try to use the arguments following `str` to specify this value!) and must be number larger than 0. It is the programmers responsibility to make sure that the items value does not clash with those of other items of the XPopup or determining which item was selected may be impossible.

`%b`

  Indicates this item is "binary item" (toggle), currently in off state. When displayed, binary items will be drawn with a small box to the left. See also `FL_PUP_BOX`.

`%B`

  Same as `%b` except that it also signifies that this item is in on or "true" state and consequently is drawn with a checked box on the left. See also `FL_PUP_BOX | FL_PUP_CHECK`.

`%rg`

  Specifies this menu item is a "radio item" belonging to group with number `g`, currently not being selected. The group number `g`, that must be part of the string directly following `%r` (and not specified via the arguments following the string), must be a non-zero, positive number. Radio items are drawn with a small diamond box to the left (empty while not active). See also `FL_PUP_RADIO`.

`%Rg`

  Same as `%rg` except that it also sets the state of the radio item as selected or "pushed", the item is drawn with a filled diamond box to the left. See also `fl_setpup_selection()`. See also `FL_PUP_RADIO | FL_PUP_CHECK`.

`%%`

  Use this if you need a `%` character in the string.

`<Ctrl>H (`\010`)`

  Same as `%l` except that the character must precede the item label, i.e., use `"\010Abc"` and not `"Abc\010"`.

Due to the use of variable arguments error checking can only be minimal. Also note that if `%x` is used to specify a value that happens to be identical to a position-based value, the result is unpredictable when subsequent references to these items are made. There is currently a limit of `FL_MAXPUPI` (64) items per popup.

Tabs characters (`'\t'`) can be embedded in the item string to align different fields.

You can add more items to an existing XPopup using the following routine

    int fl_addtopup(int popup_id, const char *str, ...);

where `popup_id` is the value returned by `fl_newpup()` or `fl_defpup()` for the XPopup. Again, `str` can contain information for one or more new items, including the special sequences described earlier. The function returns -1 if invalid arguments are detected (as far as possible for a function with a variable number of arguments).

To display a popup, use

    int fl_dopup(int popup_id);

This function displays the specified XPopup until the user makes a selection or clicks somewhere outside of the XPopups box. The value returned is the value of the item selected or -1 if no item (or a disabled one) was selected. However, if there is a function bound to the XPopup as a whole or to the selected item itself, this function is invoked with the item value as the argument and the value returned by `fl_dopup()` is then the return value of this function. If a callback function for both the selected item and the XPopup as a whole exists, the callback function for the item is called first with the item value as the argument and then the return value of this item specific callback function is passed to the XPopups callback function. `fl_dopup()` then finally returns the return value of this second function call.

Normally a XPopup get opened when the left mouse button has been pressed down and get closed again when the left mouse button is released. But there are a number of ways to achieve a "hanging" XPopup, i.e., that the XPopup that says open, even though the left mouse button isn't pressed down anymore. This happens e.g., when the user releases the mouse button in the title area of the XPopup or when the XPopup was opened via a keyboard shortcut. In that case it's also possible to navigate through the items and select via the keyboard.

A typical procedure may look as follows:

    int item3_cb(int n) {
         return n + 7;
    }

    /* define the menu */
    int menu = fl_newpup(parent);
    fl_addtopup(menu, "Title %t|Item1%rg1|Item2%Rg1|Item3%x10%f|Item4",
                item3_cb);

    switch (fl_dopup(menu)) {
        case 1:   /* item1 is selected */
            /* handle it */
            break;

        case 2:
            /* handle it */
            break;

        case 4:
            /* handle it */

        case 17:
            /* item 3 call back has been executed */
    }

Here callback function `item3_cb()` is bound to the third item and this item has been assigned the number 10. Thus, when it is selected `fl_dopup()` does not return 3 or 10. Instead the callback function `item3_cb()` is invoked with 10 as its argument. And this function in turn returns `10 + 7`, which is the value `fl_dopup()` finally returns.

Note also that items 1 and 2 both are radio items, belonging to the same group (numbered 1). Item 2 is currently the active item of this group.

Sometimes it might be necessary to obtain the popup ID inside an item callback function. To this end, the following function available:

    int fl_current_pup(void);

If no popup is active, the function returns -1. Until all callback functions have been run the function returns the ID of the XPopup the items belong to.

To destroy a popup menu and release all memory used, use the following routine

    void fl_freepup(int popup_id);

For most applications, the following simplified API may be easier to use

    void fl_setpup_entries(int popup_id, FL_PUP_ENTRIES *entries);

where `popup_id` is the popup ID returned by `fl_newpup()` or `fl_defpup()` and `entries` is an array of the following structures

    typedef struct {
        const char * item_text; /* item text label */
        FL_PUP_CB    callback;  /* item callback routine */
        const char * shortcut;  /* shortcut for this item */
        unsigned int mode;      /* item mode */
    } FL_PUP_ENTRY;

The meaning of each member of the structure is as follows:

`text`

  This is the text of a XPopup item. If text is `NULL`, it signifies the end of this popup menu. The first letter of the text string may have a special meaning if it is one of the following:

  `'/'`

    This indicates the beginning of a sub-popup, starting with the next item and ending with the next item with `text` being `NULL`.

  `'_'`

    Indicates that a line should be drawn below this item (typically as a visual reminder of logical groupings of items).

`callback`

  This is the callback function that will be called when this particular item is selected by the user. `fl_dopup()` returns the value returned by this callback. If the callback is `NULL`, the item number will be returned directly by `fl_dopup()`.

`shortcut`

  Specifies the keyboard shortcut.

`mode`

  Specifies special attributes of this item. This can be one or a combination by bitwise OR of one of the following:

  `FL PUP NONE`

    No special characteristics, the default.

  `FL_PUP_GREY`

    Item is greyed-out an can't be selected. Trying to select it results in `fl_dopup()` returning -1.

  `FL_PUP_BOX`

    "Binary item", drawn with a little box to its left.

  `FL_PUP_RADIO`

    "Radio item", drawn with a little diamond-shaped box to its left. All radio items of the XPopup belong to the same group.

  `FL_PUP_CHECK`

    OR this value with `FL_PUP_BOX` or `FL_PUP_RADIO` to have the box to the left drawn as checked or pushed.

With this simplified API, popup item values start from 1 and are the index in the entries array for the item plus 1. For example, the third element (with index 2) of the array of structure has an item value of 3. Please note that also elements of the array that end a submenu and thus don't appear as visible items in the XPopup get counted. This way, the application can relate the value returned by fl_dopup() to the array easily. See demo program ``popup.c`' for an example use of the API.

To illustrate the usage of `fl_setpup_entries()`, Fig 21.2 shows the popup created with the array of structures defined in the following code example:

    FL_PUP_ENTRY entries[ ] = {
       {"Top item1",  callback},      /* item number 1 */
       {"Top item2",  callback},
       {"Top item3",  callback},
       {"/Top item4", callback},
         {"Sub1 item1",  callback},   /* item number 5 */
         {"Sub1 item2",  callback},
         {"Sub1 item3",  callback},
         {"Sub1 item4",  callback},
         {"/Sub1 item5", callback},
           {"Sub2 item1",  callback}, /* item number 10 */
           {"Sub2 item2",  callback},
           {"Sub2 item3",  callback},
           {NULL,         NULL     }, /* end of level2, item number 13 */
         {NULL,           NULL   },   /* end of sublevel1, item nuber 14 */
       {"Top item5",  callback},      /* item number 15 */
       {NULL,         NULL    }       /* end of popup */
    };

### 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 section 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.

### 23.3.3 Other XPopup Routines

Note that most of the setpup/getpup routines are recursive in nature and the function will search the menu and all its submenus for the item.

It is possible to modify the display characteristics of a given XPopup item after its creation using the following routine

    void fl_setpup_mode(int popup_id, int item_val, unsigned mode);

As usual `popup_id` is the XPopup ID as returned by `fl_newpup()` or `fl_defpup()` and `item_val` the value of the item. `mode` is one of `FL PUP NONE`, `FL PUP GREY`, `FL PUP BOX` or `FL PUP RADIO` (one of the later two can be bitwise ORed with `FL_PUP_CHECK`, as already discussed above.

To obtain the mode of a particular menu item, use the following routine

    unsigned int fl_getpup_mode(int popup_id, int item_val)

This comes in handy to check if a binary or radio item is set

    if (fl_getpup_mode(popupd, item_val) & FL_PUP_CHECK)
        /* item is set */

There exists also a routine that can be used to obtain an items text

    const char *fl_getpup_text(int popup_id, int item_val);

In some situations, especially when the popup is activated by non-pointer events (e.g., as a result of a keyboard shortcut), the default placement of popups based on mouse location might not be adequate or appropriate, thus XPopup provides the following routine to override the default placement

    void fl_setpup_position(int x, int y);

where `x` and `y` specify the location where the top-left corner of the popup should be. `x` and `y` must be given in screen coordinates (i.e., relative to the root window) with the origin at the top-left corner of the screen. This routine should be used immediately before invoking `fl_dopup()`, the position is not remembered afterwards.

If `x` or `y` is negative, the absolute value is taken to mean the desired location relative to the right or bottom corner of the popup (not the screen!).

Another function exists for controlling the positon of the popup. When the fuunction

    void fl_setpup_align_bottom(void);

then the pop-up will appear with its lower right hand corner aligned aligned with the mouse position or, if also `fl_setpup_position()` is active, the postion set this way will be interpreted to mean the lower right hand position of the popu-up.

A radio item in a group can be initialized to be in "pushed" state by using `%R`. But you can also switch a such a radio item to "pushed state also programmatically using

    void fl_setpup_selection(int popup_id, int item_val);

Of course, other radio items of the XPopup belonging to the same group are reset to "unpushed" state.

To obtain the number of items in a popup, use the following routine

    int fl_getpup_items(int popup_id)

### 23.3.4 XPopup Attributes

The title of a XPopup can be set using the functions

    void fl_setpup_title(int popup_id, const char *title);
    void fl_setpup_title_f(int popup_id, const char *fmt, ...);

They only differ in the way the new title is passed to the function, the first one accepts a simple string while the second expects a format string as used for `printf()` etc., followed by the appropriate number of (unspecified) arguments.

Use the following routines to modify the default popup font style, font size and border width:

    int fl_setpup_default_fontsize(int size);
    int fl_setpup_default_fontstyle(int style);
    int fl_setpup_default_bw(int bw);

The functions return the old size, style or border width value, respectively.

All XPopups by default use a right arrow cursor. To change the default cursor, use

    Cursor fl_setpup_default_cursor(int cursor);

where you can use for `cursor` any of the standard cursors defined in `<X11/cursorfont.h>` like `XC_watch` etc. The function returns the previously cursor.

To change the cursor of a particular XPopup only , use the following routine

    Cursor fl_setpup_cursor(int popup_id, int cursor);

For example, after the following sequence,

    id = fl_defpup(win, "item1|item2");
    fl_setpup_cursor(id, XC_hand2);

the popup with ID `id` will use a "hand" instead of the default arrow cursor.

In versions before 1.0.91 XPopups were drawn with a heavy shadow around the box. Drawing of this shadow could be controlled via

    void fl_setpup_shadow(int popup_id, int yes_no);

Nowadays this function still exists for backward-compatibility but does nothing.

The appearance of XPopups (and their associated sub-popups) can be change by the following routines:

    void fl_setpup_bw(int popup_id, int bw);
    void fl_setpup_softedge(int pupup_id, int yes_no);

The first sets the border width for a XPopup. Calling `fl_setpup_softedge()` with a true argument for `yes_no` has the same effect as using a negative border width while using a false (0) argument is equivalent to using a positive one (so this function isn't very useful).

The background color and text color of a popup can be changed using

    void fl_setpup_default_color(FL_COLOR bgcolor, FL_COLOR tcolor);

By default, the background color `bgcolor` is `FL_COL1` and the text color `tcolor` is `FL_BLACK`.

For "binary" or radio items, that have check box associated with them, the "checked" or "pushed" color (default is `FL_BLUE`) can be changed with the following routine

    void fl_setpup_default_checkcolor(FL_COLOR checkcolor);

There is by default a limit of 32 XPopups per process. To enlarge the number of XPopups allowed, use the following routine

    int fl_setpup_maxpups(int new_max);

The function returns the previous limit.

It is possible to use XPopups as a message facility using the following routines

    void fl_showpup(int popup_id);
    void fl_hidepup(int popup_id);

No interaction takes place with a XPopup shown by `fl_showpup()` and it can only be removed from the screen programmatically via `fl_hidepup()`.

### 23.3.5 Remarks

Take care to make sure all items, including the items on submenus, of a XPopup have unique values and are positive.

XPopups are used indirectly in the demo programs ``menu.c`', ``boxtype.c`', ``choice.c`' and others. For a direct pop-up demo see ``popup.c`'.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Jens Thoms Toerring on January 5, 2014 using texi2html 1.82.