Next: , Previous: , 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: , Previous: , Up: Part I Doing Interaction   [Contents][Index]