4. Doing Interaction

4.1 Displaying a Form

After having defined the forms the application program can use them to interact with the user. As a first step the program has to display the forms with which it wants the user to interact. This is done using the routine

Window fl_show_form(FL_FORM *form, int place, int border,
                    const char *name);

It opens a (top-level) window on the screen in which the form is shown. The parameter name is the title of the form (and its associated icon if any). The routine returns the ID of the forms window. You normally never need this. Immediately after the form becomes visible, a full draw of all objects on the form is performed. Due to the two way buffering mechanism of Xlib, if fl_show_form() is followed by something that blocks (e.g., waiting for a device other than X devices to come online), the output buffer might not be properly flushed, resulting in the form only being partially drawn. If your program works this way, use the following function after fl_show_form()

void fl_update_display(int blocking);

where blocking is false (0), the function flushes the X buffer so the drawing requests are on their way to the server. When blocking is true (1), the function flushes the buffer and waits until all the events are received and processed by the server. For typical programs that use fl_do_forms() or fl_check_forms() after fl_show_form(), flushing is not necessary as the output buffer is flushed automatically. Excessive call to fl_update_display() degrades performace.

The location and size of the window to be shown on the call of fl_show_form() are determined by the place argument. The following possibilities exist:

FL_PLACE_SIZE

The user can control the position but the size is fixed. Interactive resizing is not allowed once the form becomes visible.

FL_PLACE_POSITION

Initial position used will be the one set via fl_set_form_position(). Interactive resizing is possible.

FL_PLACE_GEOMETRY

Place at the latest position and size (see also below) or the geometry set via fl_set_form_geometry(). A form so shown will have a fixed size and interactive resizing is not allowed.

FL_PLACE_ASPECT

Allows interactive resizing but any new size will have the aspect ratio as that of the initial size.

FL_PLACE_MOUSE

The form is placed centered below the mouse. Interactive resizing will not be allowed unless this option is accompanied by FL_FREE_SIZE as in FL_PLACE_MOUSE|FL_FREE_SIZE.

FL_PLACE_CENTER

The form is placed in the center of the screen. If FL_FREE_SIZE is also specified, interactive resizing will be allowed.

FL_PLACE_FULLSCREEN

The form is scaled to cover the full screen. If FL_FREE_SIZE is also specified, interactive resizing will be allowed.

FL_PLACE_FREE

Both the position and size are completely free. The initial size used is the designed size. Initial position, if setvia fl_set_form_position(), will be used otherwise interactive positioning may be possible if the window manager allows it.

FL_PLACE_HOTSPOT

The form is placed so that mouse is on the form's "hotspot". If FL_FREE_SIZE is also specified, interactive resizing will be allowed.

FL_PLACE_CENTERFREE

Same as FL_PLACE_CENTER|FL_FREE_SIZE, i.e., place the form at the center of the screen and allow resizing.

FL_PLACE_ICONIC

The form is shown initially iconified. The size and location used are the window manager's default.

As mentioned above, some of the settings will result in a fixed size of the form (i.e., a size that can't be changed by the user per default). In some cases this can be avoided by OR'ing the value with FL_FREE_SIZE as a modifier.

If no size was specified, the designed (or later scaled) size will be used. Note that the initial position is dependent upon the window manager used. Some window managers allow interactive placement of the windows but some don't.

You can set the position or size to be used via the following calls

void fl_set_form_position(FL_FORM *form, FL_Coord x, FL_Coord y);

and

void fl_set_form_size(FL_FORM *form, FL_Coord w, FL_Coord h);

or, combining both these two functions,

void fl_set_form_geometry(FL_FORM form*, FL_Coord x, FL_Coord y,
                          FL_Coord w, FL_Coord h);

before placing the form on the screen. (Actually the routines can also be called while the form is being displayed. They will change the position and/or size of the form.) x, y, w and h indicate the position of the form on the screen and its size(4). The position is measured from the top-left corner of the screen. When the position is negative the distance from the right or the bottom is indicated. Next the form should be placed on the screen using FL_PLACE_GEOMETRY, FL_PLACE_FREE. E.g., to place a form at the lower-right corner of the screen use

fl_set_form_position(form, -1, -1);
fl_show_form(form, FL_PLACE_GEOMETRY, FL_TRANSIENT, "formName");

(Following the X convention for specifying geometries a negative x-position specifies the distance of the right eside of the form from the right side of the screen and a negative y-position the distance of the bottom of the form from the bottom of the screen.)

To show a form so that a particular object or point is under the mouse, use one of the following two routines to set the "hotspot"

void fl_set_form_hotspot(FL_FORM *form, FL_Coord x, FL_Coord y);
void fl_set_form_hotobject(FL_FORM *form, FL_OBJECT *obj);

and then use FL_PLACE_HOTSPOT for the place argument in the call of fl_show_form(). The coordinates x and y are relative to the upper-left hand corner of the form (within the window decorations).

In the call fl_show_form() the argument border indicates whether or not to request window manager's decoration. border should take one of the following values:

FL_FULLBORDER

Full border decorations.

FL_TRANSIENT

Borders with (possibly) less decorations.

FL_NOBORDER

No decoration at all.

For some dialogs, such as demanding an answer etc., you probably do not want the window manager's full decorations. Use FL_TRANSIENT for this.

A window border is useful to let the user iconify a form, move it around or resize it. If a form is transient or has no border, it is normally more difficult (or even impossible) to move the form. A transient form typically should have less decoration, but not necessarily so. It depends on the window managers as well as their options. FL_NOBORDER is guaranteed to have no border(5) and is immune to iconification request. Because of this, borderless forms can be hostile to other applications(6), so use this only if absolutely necessary.

There are other subtle differences between the different decoration requests. For instance, (small) transient forms always have save_under (see XSetWindowAttributes()) set to true by default. Some window properties, WM_COMMAND in particular, are only set for full-bordered forms and will only migrate to other full-bordered forms when the original form having the property becomes unmapped.

The library has a notion of a "main form" of an application, roughly the form that would be on the screen the longest. By default, the first full-bordered form shown becomes the main form of the application. All transient windows shown afterwards will stay on top of the main form. The application can set or change the main form anytime using the following routine

void fl_set_app_mainform(FL_FORM *form);

Setting the main form of an application will cause the WM_COMMAND property set for the form if no other form has this property.

Sometimes it is necessary to have access to the window resource ID before the window is mapped (shown). For this, the following routine can be used

Window fl_prepare_form_window(FL_FORM *form, int place, int border,
                              const char *name);

This routine creates a window that obeys any and all constraints just as fl_show_form() does but remains unmapped. To map such a window, the following must be used

Window fl_show_form_window(FL_FORM *form);

Between these two calls, the application program has full access to the window and can set all attributes, such as icon pixmaps etc., that are not set by fl_show_form().

You can also scale the form and all objects on it programmatically using the following routine

void fl_scale_form(FL_FORM *form, double xsc, double ysc);

where you indicate a scaling factor in the x- and y-direction with respect to the current size. See `rescale.c' for an example.

When a form is scaled, either programmatically or interactively, all objects on the form per default will also be scaled. This includes both the sizes and positions of the objects. For most cases, this default behavior is adequate. In some cases, e.g., to keep a group of objects together, more control is needed. To this end, the following routines can be used

void fl_set_object_resize(FL_OBJECT *obj, unsigned how_resize);
void fl_set_object_gravity(FL_OBJECT *obj,
                           unsigned nw_gravity, unsigned se_gravity);

The how_resize argument of fl_set_object_resize() can be one of

FL_RESIZE_NONE

don't resize the object at all

FL_RESIZE_X

resize it in x- (horizontal) direction only

FL_RESIZE_Y

resize it in y- (vertical) direction only

FL_RESIZE_ALL

is an alias for FL_RESIZE_X|FL_RESIZE_Y and makes the object resizable in both dimension.

The arguments nw_gravity and se_gravity of fl_set_object_gravity() control the positioning of the upper-left and lower-right corner of the object and work analogously to the win_gravity in Xlib. The details are as follows: Let P be the corner the gravity applies to, (dx1,dy1) the distance to the upper-left corner of the form, (dx2,dy2) the distance to the lower-right corner of the form, then,

Default for all object is FL_RESIZE_ALL and ForgetGravity. Note that the three parameters are not orthogonal and the positioning request will always override the scaling request in case of conflict. This means the resizing settings for an object are considered only if one (or both) of the gravities is FL_NoGravity.

For the special case where how_resize is FL_RESIZE_NONE and both gravities are set to ForgetGravity, the object is left un-scaled, but the object is moved so that the new position keeps the center of gravity of the object constant relative to the form.

Again, since all sizing requests go though the window manager, there is no guarantee that your request will be honored. If a form is placed with FL_PLACE_GEOMETRY or other size-restricting options, resizing it later via fl_set_form_size() will likely be rejected.

To determine the gravity and resize settings for an object use the functions

void fl_get_object_gravity(FL_OBJECT *obj,
                           unsigned int *nw, unsigned int *se);
void fl_get_object_resize(FL_OBJECT *obj, unsigned int *resize );

Sometimes, you may want to change an attribute for all objects on a particular form, to this end, the following iterator is available

void fl_for_all_objects(FL_FORM *form,
                        int (*operate)(FL_OBJECT *obj, void *data),
                        void *data);

where function operate is called for every object of the form form unless operate() returns nonzero, which terminates the iterator.

Multiple forms can be shown at the same moment and the system will interact with all of them simultaneously.

The graphical mode in which the form is shown depends on the type of machine. In general, the visual chosen by XForms is the one that has the most colors. Application programs have many ways to change this default, either through command line options, resources or programmatically. See the Part V for details.

If for any reason, you would like to change the form title (as well as its associated icon) after it is shown, the following functions can be used

void fl_set_form_title(FL_FORM *form, const char *name)
void fl_set_form_title_f(FL_FORM *form, const char *fmt, ...)

To set or change the icon shown when a form is iconified, use the following routine

void fl_set_form_icon(FL_FORM *form, Pixmap icon, Pixmap mask);

where icon and mask can be any valid Pixmap ID. (See Other Pixmap Routines for some of the routines that can be used to create Pixmaps.) Note that an icon previously setvia this function (if it exists) is not freed or modified in anyway. See the demo program `iconify.c' for an example.

If the application program wants to stop interacting with a form and remove it from the screen, it has to use the call

void fl_hide_form(FL_FORM *form);

To check if a form is visible or not, use the following call

int fl_form_is_visible(FL_FORM *form);

The function returns one of

FL_INVISIBLE

if the form is not visible (0),

FL_VISIBLE

if the form is visible (1) and

FL_BEING_HIDDEN

if the form is visible but is in the process of being hidden (-1).

Note that if you don't need a form anymore you can deallocate its memory using the call fl_free_form() described earlier.

Window managers typically have a menu entry labeled "delete" or "close" meant to terminate an application program gently by informing the application program with a WM_DELETE_WINDOW protocol message. Although the Forms Library catches this message, it does not do anything except terminating the application. This can cause problems if the application has to do some record keeping before exiting. To perform record keeping or to elect to ignore this message, register a callback function using the following routine

int fl_set_atclose(int (*at_close)(FL_FORM *, void *), void *data);

The callback function at_close will be called before the Forms Library terminates the application. The first parameter of the callback function is the form that received the WM_DELETE_WINDOW message. To prevent the Forms Library from terminating the application, the callback function should return the constant FL_IGNORE. Any other value (e.g., FL_OK) will result in the termination of the application.

Similar mechanism exists for individual forms

int fl_set_form_atclose(FL_FORM *,
                        int (*at_close)(FL_FORM *, void *),
                        void *data);

except that FL_OK does not terminate the application, it results in the form being closed. Of course, if you'd like to terminate the application, you can always call exit(3) yourself within the callback function.

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 request FL_RETURN_END and FL_RETURN_CHANGED will automatically 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!

4.3 Periodic Events and Non-blocking Interaction

The interaction mentioned above is adequate for many application programs but not for all. When the program also has to perform tasks when no user action takes place (e.g., redrawing a rotating image all the time), some other means of interaction are needed.

There exist two different, but somewhat similar, mechanisms in the library that are designed specifically for generating and handling periodic events or achieving non-blocking interaction. Depending on the application, one method may be more appropriate than the other.

For periodic tasks, e.g., rotating an image, checking the status of some external device or application state etc., interaction via an idle callback comes in very handy. An idle callback is an application function that is registered with the system and is called whenever there are no events pending for forms (or application windows).

To register an idle callback, use the following routine

FL_APPEVENT_CB fl_set_idle_callback(FL_APPEVENT_CB callback,
                                    void *user_data);

After the registration, whenever the main loop (fl_do_forms()) is idle, i.e., no user action or light user action, the callback function of type FL_APPEVENT_CB is called

typedef int (*FL_APPEVENT_CB)(XEvent *xev, void *user_data);

i.e., a function with the signature

int idle_callback(XEvent *xev, void *user_data);

where user_data is the void pointer passed to the system in fl_set_idle_callback() through which some information about the application can be passed. The return value of the callback function is currently not used. xev is a pointer to a synthetic(7) MotionNotify event from which some information about mouse position etc. can be obtained. To remove the idle callback, use fl_set_idle_callback() with callback set to NULL.

Timeouts are similar to idle callbacks but with somewhat more accurate timing. Idle callbacks are called whenever the system is idle, the time interval between any two invocations of the idle callback can vary a great deal depending upon many factors. Timeout callbacks, on the other hand, will never be called before the specified time is elapsed. You can think of timeouts as regularized idle callbacks, and further you can have more than one timeout callbacks.

To add a timeout callback, use the following routine

typedef void (*FL_TIMEOUT_CALLBACK)(int, void *);
int fl_add_timeout(long msec, FL_TIMEOUT_CALLBACK callback,
                   void *data);

The function returns the timeout's ID(8). When the time interval specified by msec (in milli-seconds) has elapsed the timeout is removed, then the callback function is called. The timeout ID is passed to the callback function as the first parameter. The second parameter the callback function is passed is the data pointer that was passed to fl_add_timeout().

To remove a timeout before it triggers, use the following routine

void fl_remove_timeout(int id);

where id is the timeout ID returned by fl_add_timeout(). There is also an FL_OBJECT, the FL_TIMER object, especially the invisible type, that can be used to do timeout. Since it is a proper Forms Library object, it may be easier to use simply because it has the same API as any other GUI elements and is supported by the Form Designer. See section Timer Object, for complete information on the FL_TIMER object.

Note that idle callback and timeout are not appropriate for tasks that block or take a long time to finish because during the busy or blocked period, no interaction with the GUI can take place (both idle callback and timeout are invoked by the main loop, blockage or busy executing application code prevents the main loop from performing its tasks).

So what to do in situations where the application program does require a lengthy computation while still wanting to have the ability to interact with the user interface (for example, a Stop button to terminate the lengthy computation)?

In these situations, the following routine can be used:

FL_OBJECT *fl_check_forms(void);

This function is similar to fl_do_forms() in that it takes care of handling events and appropriate callbacks, but it does not block. Instead it always returns to the application program immediately. If a change has occurred in some object the object is returned as with fl_do_forms(). But when no change has occurred control is also returned but this time a NULL object is returned. Thus, by inserting this statement in the middle of the computation in appropriate places in effect "polls" the user interface. The downside of using this function is that if used excessively, as with all excessive polls, it can chew up considerable CPU cycles. Therefore, it should only be used outside the inner most loops of the computation. If all objects have callbacks bound to them, fl_check_forms() always returns NULL, otherwise, code similar to the following is needed:

obj = fl_check_forms();
if (obj == obj1)
    /* handle it */
...

Depending on the applications, it may be possible to partition the computation into smaller tasks that can be performed within an idle callback one after another, thus eliminating the need of using fl_check_forms().

Handling intensive computation while maintaining user interface responsiveness can be tricky and by no means the above methods are the only options. You can, for example, fork a child process to do some of the tasks and communicate with the interface via pipes and/or signals, both of which can be handled with library routines documented later, or use multi-thread (but be careful to limit Xserver access within one thread). Be creative and have fun.

For running external executables while maintaining responsiveness of the interface, see fl_exe_command() and fl_popen() documented later in Command Log.

4.4 Dealing With Multiple Windows

It is not atypical that an application program may need to take interaction from more than one form at the same time, Forms Library provides a mechanism with which precise control can be exercised.

By default, fl_do_forms() takes interaction from all forms that are shown. In certain situations, you might not want to have interaction with all of them. For example, when the user presses a quit button in a form you might want to ask a confirmation using another form. You don't want to hide the main form because of that but you also don't want the user to be able to press buttons, etc. in this form. The user first has to give the confirmation. So you want to temporarily deactivate the main form. This can be done using the call

void fl_deactivate_form(FL_FORM *form);

To reactivate the form later again use

void fl_activate_form(FL_FORM *form);

It is a good idea to give the user a visual clue that a form is deactivated. This is not automatically done mainly for performance reasons. Experience shows that graying out some important objects on the form is in general adequate. Graying out an object can be accomplished by using fl_set_object_lcolor() (see `objinactive.c'. What objects to gray out is obviously application dependent.

The following two functions can be used to register two callbacks that are called whenever the activation status of a form is changed:

typedef void (*FL_FORM_ATACTIVATE)(FL_FORM *, void *);
FL_FORM_ATACTIVATE fl_set_form_atactivate(FL_FORM *form,
                                   FL_FORM_ATACTIVATE callback,
                                   void *data);

typedef void (*FL_FORM_ATDEACTIVATE)(FL_FORM *, void *);
FL_FORM_ATDEACTIVATE fl_set_form_atdeactivate(FL_FORM *form,
                                   FL_FORM_ATDEACTIVATE callback,
                                   void *data);

It is also possible to deactivate all current forms and reactivate them again. To this end use the functions:

void fl_deactivate_all_forms(void);
void fl_activate_all_forms(void);

Note that deactivation works in an additive way, i.e., when deactivating a form say 3 times it also has to be activated 3 times to become active again.

One problem remains. Mouse actions etc. are presented to a program in the form of events in an event queue. The library routines fl_do_forms() and fl_check_forms() read this queue and handle the events. When the application program itself also opens windows, these windows will rather likely receive events as well. Unfortunately, there is only one event queue. When both the application program and the library routines would read events from this one queue problems would occur and events missed. Hence, the application program should not read the event queue itself.. To solve this problem, the library maintains (or appears to maintain) a separate event queue for the user. This queue behaves in exactly the same way as the normal event queue. To access it, the application program must use replacements for the usual Xlib routines. Instead of using XNextEvent(), the program will use fl_XNextEvent(), with the same parameters except the Display * argument. The following is a list of all replacement routines:

int fl_XNextEvent(XEvent *xev);
int fl_XPeekEvent(XEvent *xev);
int fl_XEventsQueued(int mode);
int fl_XPutbackEvent(XEvent *xev);

Note that these routines normally return 1, but after a call of fl_finish() they return 1 instead.

Other events routines may be directly used if proper care is taken to make sure that only events for the application windows not handled by the library are removed. These routines include XWindowEvent(), XCheckWindowEvent() etc.

To help find out when an event has occurred, whenever fl_do_forms() and fl_check_forms() encounter an event that is not meant for handling by the library but by the application program itself they return a special object FL_EVENT. Upon receiving this special event, the application program can and must remove the pending event from the queue using fl_XNextEvent().

So the basis of a program with its own windows would look as follows:

/* define the forms */
/* display the forms */
/* open your own window(s) */

while (! ready) {
    obj = fl_do_forms();    /* or fl_check_forms() */
    if (obj == FL_EVENT) {
        fl_XNextEvent(&xevent);
        switch (xevent.type) {
            /* handle the event */
        }
    } else if (obj != NULL)
        /* handle the change in obj */
        /* update other things */
    }
}

In some situations you may not want to receive these "user" events. For example, you might want to write a function that pops up a form to change some settings. This routine might not want to be concerned with any redrawing of the main window, etc., but you also not want to discard any events. In this case you can use the routines fl_do_only_forms() and fl_check_only_forms() that will never return FL_EVENT. The events don't disappear but will be returned at later calls to the normal routines fl_do_forms() etc.

It can't be over-emphasized that it is an error to ignore FL_EVENT or use fl_XNextEvent() without seeing FL_EVENT.

Sometimes an application program might need to find out more information about the event that triggered a callback, e.g., to implement mouse button number sensitive functionalities. To this end, the following routines may be called

long fl_mouse_button(void);

This function, if needed, should be called from within a callback. The function returns one of the constants FL_LEFT_MOUSE, FL_MIDDLE_MOUSE, FL_RIGHT_MOUSE, FL_SCROLLUP_MOUSE or FL_SCROLLDOWN_MOUSE, indicating which mouse button was pushed or released. If the callback is triggered by a shortcut, the function returns the keysym (ascii value if ASCII) of the key plus FL_SHORTCUT. For example, if a button has a shortcut <Ctrl>C (ASCII value is 3), the button number returned upon activation of the shortcut would be FL_SHORTCUT + 3. FL_SHORTCUT can be used to determine if the callback is triggered by a shortcut or not

if (fl_mouse_button() >= FL_SHORTCUT)
    /* handle shortcut */
else
    switch (fl_mouse_button()) {
        case FL_LEFTMOUSE:
        ....
    }

More information can be obtained by using the following routine that returns the last XEvent

const XEvent *fl_last_event(void);

Note that if this routine is used outside of a callback function, the value returned may not be the real "last event" if the program was idling and, in this case, it returns a synthetic MotionNotify event.

Some of the utilities used internally by the Forms Library can be used by the application programs, such as window geometry queries etc. Following is a partial list of the available routines:

void fl_get_winorigin(Window win, FL_Coord *x, FL_Coord *y);
void fl_get_winsize(Window win, FL_Coord *w, FL_Coord *h);
void fl_get_wingeometry(Window win, FL_Coord *x, FL_Coord *y,
                        FL_Coord *w, FL_Coord *h);

All positions are relative to the root window.

There are also routines that can be used to obtain the current mouse position relative to the root window:

Window fl_get_mouse(FL_Coord *x, FL_Coord *y,
                    unsigned int *keymask);

where keymask is the same as used in XQueryPointer(3X11). The function returns the window ID the mouse is in.

To obtain the mouse position relative to an arbitrary window, the following routine may be used

Window fl_get_win_mouse(Window win, FL_Coord *x, FL_Coord *y,
                        unsigned int *keymask);

To print the name of an XEvent, the following routine can be used:

XEvent *fl_print_xevent_name(const char *where, const XEvent *xev);

The function takes an XEvent, prints out its name and some other info, e.g., expose, count=n. Parameter where can be used to indicate where this function is called:

fl_print_xevent_name("In tricky.c", &xevent);

4.5 Using Callback Functions

As stated earlier, the recommended method of interaction is to use callback functions. A callback function is a function supplied to the library by the application program that binds a specific condition (e.g., a button is pushed) to the invocation of the function by the system.

The application program can bind a callback routine to any object. Once a callback function is bound and the specified condition is met, fl_do_forms() or fl_check_forms() invokes the callback function instead of returning the object.

To bind a callback routine to an object, use the following

typedef void (*FL_CALLBACKPTR)(FL_OBJECT *obj, long argument);
FL_CALLBACKPTR fl_set_object_callback(FL_OBJECT *obj,
                                      FL_CALLBACKPTR callback,
                                      long argument);

where callback is the callback function. argument is an argument that is passed to the callback routine so that it can take different actions for different objects. The function returns the old callback routine already bound to the object. You can change the callback routine anytime using this function. See, for example, demo program `timer.c'.

The callback routine should have the form

void callback(FL_OBJECT *obj, long argument);

The first argument to every callback function is the object to which the callback is bound. The second parameter is the argument specified by the application program in the call to fl_set_object_callback().

See program `yesno_cb.c' for an example of the use of callback routines. Note that callback routines can be combined with normal objects. It is possible to change the callback routine at any moment.

Sometimes it is necessary to access other objects on the form from within the callback function. This presents a difficult situation that calls for global variables for all the objects on the form. This runs against good programming methodology and can make a program hard to maintain. Forms Library solves (to some degree) this problem by creating three fields, void *u_vdata, char *u_cdata and long u_ldata, in the FL_OBJECT structure that you can use to hold the necessary data to be used in the callback function. A better and more general solution to the problem is detailed in Part II of this documentation where all objects on a form is are grouped into a single structure which can then be "hang" off of u_vdata or some field in the FL_FORM structure.

Another communication problem might arise when the callback function is called and, from within the callback function, some other objects' state is explicitly changed, say, via fl_set_button(), fl_set_input() etc. You probably don't want to put the state change handling code of these objects in another object's callback. To handle this situation, you can simply call

void fl_call_object_callback(FL_OBJECT *obj);

When dealing with multiple forms, the application program can also bind a callback routine to an entire form. To this end it should use the routine

void fl_set_form_callback(FL_FORM *form,
                          void (*callback)(FL_OBJECT *, void *),
                          void *data);

Whenever fl_do_forms() or fl_check_forms() would return an object in form they call the routine callback instead, with the object as an argument. So the callback should have the form

void callback(FL_OBJECT *obj, void *data);

With each form you can associate its own callback routine. For objects that have their own callbacks the object callbacks have priority over the form callback.

When the application program also has its own windows (via Xlib or Xt), it most likely also wants to know about XEvents for the window. As explained earlier, this can be accomplished by checking for FL_EVENT objects. Another (and better) way is to add an event callback routine. This routine will be called whenever an XEvent is pending for the application's own window. To setup an event callback routine (of type FL_APPEVENT_CB use the call

typedef int (*FL_APPEVENT_CB)(XEvent *, void *);
FL_APPEVENT_CB fl_set_event_callback(int (*callback)(XEvent *ev,
                                                     void *data),
                                     void *data);

Whenever an event happens the callback function is invoked with the event as the first argument and a pointer to data you want it to receive. So the callback should have the form

int callback(XEvent *xev, void *data);

This assumes the application program solicits the events and further, the callback routine should be prepared to handle all XEvent for all non-form windows. The callback function normally should return 0 unless the event isn't for one of the applcation-managed windows.

This could be undesirable if more than one application window is active. To further partition and simplify the interaction, callbacks for a specific event on a specific window can be registered:

FL_APPEVENT_CB fl_add_event_callback(Window window, int xev_type,
                                     FL_APPEVENT_CB callback,
                                     void *user_data);

where window is the window for which the callback routine is to be registered. xev_type is the XEvent type you're interested in, e.g., Expose etc. If xev_type is 0, it is taken to mean that the callback routine will handle all events for the window. The newly installed callback replaces the callback already installed. Note that this function only works for windows created directly by the application program (i.e., it won't work for forms' windows or windows created by the canvas object). It is possible to access the raw events that happen on a form's window via fl_register_raw_callback() discussed in Form Events.

fl_add_event_callback() does not alter the window's event mask nor does it solicit events for you. That's mainly for the reason that an event type does not always correspond to a unique event mask, also in this way, the user can solicit events at window's creation and use 0 to register all the event handlers.

To let XForms handle solicitation for you, call the following routine

void fl_activate_event_callbacks(Window win);

This function activates the default mapping of events to event masks built-in in the Forms Library, and causes the system to solicit the events for you. Note however, the mapping of events to masks are not unique and depending on applications, the default mapping may or may not be the one you want. For example, MotionNotify event can be mapped into ButtonMotionMask or PointerMotionMask. Forms Library will use both.

It is possible to control the masks you want precisely by using the following function, which can also be used to add or remove solicited event masks on the fly without altering other masks already selected:

long fl_addto_selected_xevent(Window win, long mask);
long fl_remove_selected_xevent(Window win, long mask);

Both functions return the resulting event masks that are currently selected. If event callback functions are registered via both fl_set_event_callback() and fl_add_event_callback(), the callback via the latter is invoked first and the callback registered via fl_set_event_callback() is called only if the first attempt is unsuccessful, that is, the handler for the event is not present. For example, after the following sequence

fl_add_event_callback(winID, Expose, expose_cb, 0);
fl_set_event_callback(event_callback);

and all Expose events on window winID are consumed by expose_cb then event_callback() would never be invoked as a result of an Expose event.

To remove a callback, use the following routine

void fl_remove_event_callback(Window win, int xev_type);

All parameters have the usual meaning. Again, this routine does not modify the window's event mask. If you like to change the events the window is sensitive to after removing the callback, use fl_activate_event_callbacks(). If xev_type is 0, all callbacks for window win are removed. This routine is called automatically if fl_winclose() is called to unmap and destroy a window. Otherwise, you must call this routine explicitly to remove all event callbacks before destroying a window using XDestroyWindow().

A program using all of these has the following basic form:

void event_cb(XEvent *xev, void *mydata1) {
    /* Handles an X-event. */
}

void expose_cb(XEvent *xev, void *mydata2) {
    /* handle expose */
}

void form1_cb(FL_OBJECT *obj) {
    /* Handles object obj in form1. */
}

void form2_cb(FL_OBJECT *obj) {
    /* Handles object obj in form2. */
}

main(int argc, char *argv[]) {
    /* initialize */
    /* create form1 and form2 and display them */
    fl_set_form_callback(form1, form1cb);
    fl_set_form_callback(form2, form2cb);

    /* create your own window, winID and show it */
    fl_addto_selected_xevent(winID,
                             ExposureMask | ButtonPressMask |... );
    fl_winshow(winID);
    fl_set_event_callback(event_cb, whatever);
    fl_add_event_callback(winID, Expose, expose_cb, data);
    fl_do_forms();
    return 0;
}

The routine fl_do_forms() will never return in this case. See `demo27.c' for a program that works this way.

It is recommended that you set up your programs using callback routines (either for the objects or for entire forms). This ensures that no events are missed, events are treated in the correct order, etc. Note that different event callback routines can be written for different stages of the program and they can be switched when required. This provides a progressive path for building up programs.

Another possibility is to use a free object so that the application window is handled automatically by the internal event processing mechanism just like any other forms.

4.6 Handling Other Input Sources

It is not uncommon that X applications may require input from sources other than the X event queue. Outlined in this section are two routines in the Forms Library that provide a simple interface to handle additional input sources. Applications can define input callbacks to be invoked when input is available from a specified file descriptor.

The function

typedef void (*FL_IO_CALLBACK)(int fd, void *data);
void fl_add_io_callback(int fd, unsigned condition,
                        FL_IO_CALLBACK callback, void *data);

registers an input callback with the system. The argument fd must be a valid file descriptor on a UNIX-based system or other operating system dependent device specification while condition indicates under what circumstance the input callback should be invoked. The condition must be one of the following constants

FL_READ

File descriptor has data available.

FL_WRITE

File descriptor is available for writing.

FL_EXCEPT

an I/O error has occurred.

When the given condition occurs, the Forms Library invokes the callback function specified by callback. The data argument allows the application to provide some data to be passed to the callback function when it is called (be sure that the storage pointed to by data has global (or static) scope).

To remove a callback that is no longer needed or to stop the Forms Library's main loop from watching the file descriptor, use the following function

void fl_remove_io_callback(int fd, unsigned condition,
                           FL_IO_CALLBACK callback);

The procedures outlined above work well with pipes and sockets, but can be a CPU hog on real files. To workaround this problem, you may wish to check the file periodically and only from within an idle callback.

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