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

Next: Periodic Events and Non-blocking Interaction, Previous: Displaying a Form, Up: Part I Doing Interaction [Contents][Index]

### 4.2 Simple Interaction

Once one or more forms are shown it is time to give control to the library to handle the interaction with the forms. There are a number of different ways of doing this. The first one, appropriate for most programs, is to call of

    FL_OBJECT *fl_do_forms(void);

It controls the interaction until some object in one of the forms changes state. In this case a pointer to the changed object is returned.

A change occurs in the following cases:

box

  A box never changes state and, hence, is never returned by `fl_do_forms()`.

text

  Also a text never changes state.

button

  A button is returned when the user presses a mouse button on it and then releases the button. The change is not reported before the user releases the mouse button, except with touch buttons which are returned all the time as long as the user keeps the mouse pressed on it. (See e.g., `touchbutton.c` for the use of touch buttons.)

slider

  A slider per default is returned whenever its value is changed, so whenever the user clicks on it and moves the mouse the slider object gets returned.

input

  An input field is returned per default when it is deactivated, i.e., the user has selected it and then starts interacting with another object that has the ability to get returned.

(This list just contains a small number of objects that exist, see Part III for a list of all objects and the documentation of the exact behaviour of them.)

When the (address of the) object is returned by `fl_do_forms()` the application program can take action accordingly. See some of the demo programs for examples of use. Normally, after the action is taken by the application program `fl_do_forms()` is called again to continue the interaction. Hence, simpler programs have the following global form:

    /* define the forms */
    /* display the forms */
    while (! ready) {
        obj = fl_do_forms();
        if (obj == obj1)
            /* handle the change in obj1 */
        else if (obj == obj2)
            /* handle the change in obj2 */
        ....
    }

For more complex programs interaction via callbacks is often preferable. For such programs, the global structure looks something like the following

    /* define callbacks */
    void callback(FL_OBJECT *obj, long data) {
        /* perform tasks */
    }

    void terminate_callback(FL_OBJECT *obj, long data) {
        /* cleanup application */
        fl_finish();
        exit(0);
    }

    main(int argc, char *argv[]) {
        /* create form and bind the callbacks to objects */
        /* enter main loop */
        fl_do_forms();
        return 0;
    }

In this case, `fl_do_forms()` handles the interaction indefinitely and never returns. The program exits via one of the callback functions.

There is also the possibility to conrol under which exact conditions the object gets returned. An application that e.g., doesn’t want to be notified about each change of a slider but instead only want a single notification after the mouse button has been released and the value of the slider was changed in the process would call the function

    int fl_set_object_return(FL_OBJECT *obj, unsigned int when);

with `when` set to `FL_RETURN_END_CHANGED`.

There are several values `when` can take:

`FL_RETURN_CHANGED`

  Return (or call object callback) whenever there is a change in the state of the object (button was pressed, input field was changed, slider was moved etc.).

`FL_RETURN_END`

  Return (or invoke callback) at the end of the interaction (typically when the user releases the mouse button) regardless if the objects state was changed or not.

`FL_RETURN_END_CHANGED`

  Return (or call object callback) when interaction stops and the state of the object changed.

`FL_RETURN_SELECTION`

  Return when e.g., a line in a `FL_MULTI_BROWSER` browser was selected.

`FL_RETURN_DESELECTION`

  Return when e.g., a line in a `FL_MULTI_BROWSER` browser was deselected.

`FL_RETURN_ALWAYS`

  Return (or invoke callback) on any of the events that can happen to the object.

`FL_RETURN_NONE`

  Never notiy the application about interactions with this object (i.e., never return it nor invoke its callback). Note: this is not meant for deactivation of an object, it will still seem to work as normal, it just doesn’t get returned to the application nor does is callbak get invoked.

Since for different objects only subsets of these conditions make sense please read the more detailed descriptions for each of the object types in Part III.

All of the values above, except `FL_RETURN_END_CHANGED`, `FL_RETURN_ALWAYS` and `FL_RETURN_NONE` can be logically `OR`’ed. `FL_RETURN_END_CHANGED` is different in that it only can be returned when the conditions for `FL_RETURN_END` and `FL_RETURN_CHANGED` are satisfied at once. If this is requested both `FL_RETURN_END` and `FL_RETURN_CHANGED` will automatically become deselected. So if you want notifications about the conditions that lead to `FL_RETURN_END` or `FL_RETURN_CHANGED` (or both at once) ask instead for the logical `OR` of these two.

`FL_RETURN_ALWAYS` includes all conditions except `FL_RETURN_END_CHANGED`.

Once an object has been returned (or its callback is invoked) you can determine the reason why it was returned by calling

    int fl_get_object_return_state(FL_OBBJECT *obj);

This returns the logical `OR` of the conditions that led to the object being returned, where the conditions can be `FL_RETURN_CHANGED`, `FL_RETURN_END`, `FL_RETURN_SELECTION` and `FL_RETURN_DESELECTION`. (The `FL_RETURN_END_CHANGED` condition is satisfied if both `FL_RETURN_END` and `FL_RETURN_CHANGED` are set.)

Please note that calling this function only makes sense in a callback for an object or when the object has been just returned by e.g., `fl_do_forms()`. Further interactions with the object overwrite the value!

Next: Periodic Events and Non-blocking Interaction, Previous: Displaying a Form, Up: Part I Doing Interaction [Contents][Index]