@node Part I Doing Interaction
@chapter Doing Interaction

@ifnottex

@menu
* Displaying a Form::
* Simple Interaction::
* Periodic Events and Non-blocking Interaction::
* Dealing With Multiple Windows::
* Using Callback Functions::
* Handling Other Input Sources::
@end menu

@end ifnottex

@node Displaying a Form
@section 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
@findex fl_show_form()
@example
Window fl_show_form(FL_FORM *form, int place, int border,
                    const char *name);
@end example
@noindent
It opens a (top-level) window on the screen in which the form is
shown. The parameter @code{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
@code{@ref{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 @code{@ref{fl_show_form()}}
@findex fl_update_display()
@anchor{fl_update_display()}
@example
void fl_update_display(int blocking);
@end example
@noindent
where @code{blocking} is false (0), the function flushes the X buffer
so the drawing requests are on their way to the server. When
@code{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 @code{@ref{fl_do_forms()}} or
@code{@ref{fl_check_forms()}} after @code{@ref{fl_show_form()}},
flushing is not necessary as the output buffer is flushed
automatically. Excessive call to @code{@ref{fl_update_display()}}
degrades performace.

The location and size of the window to be shown on the call of
@code{@ref{fl_show_form()}} are determined by the @code{place}
argument. The following possibilities exist:
@table @code
@anchor{FL_PLACE_SIZE}
@tindex FL_PLACE_SIZE
@item FL_PLACE_SIZE
The user can control the position but the size is fixed. Interactive
resizing is not allowed once the form becomes visible.

@anchor{FL_PLACE_POSITION}
@tindex FL_PLACE_POSITION
@item FL_PLACE_POSITION
Initial position used will be the one set via
@code{@ref{fl_set_form_position()}}. Interactive resizing is possible.

@anchor{FL_PLACE_GEOMETRY}
@tindex FL_PLACE_GEOMETRY
@item FL_PLACE_GEOMETRY
Place at the latest position and size (see also below) or the geometry
set via @code{@ref{fl_set_form_geometry()}}. A form so shown will have
a fixed size and interactive resizing is not allowed.

@anchor{FL_PLACE_ASPECT}
@tindex FL_PLACE_ASPECT
@item FL_PLACE_ASPECT
Allows interactive resizing but any new size will have the aspect ratio
as that of the initial size.

@anchor{FL_PLACE_MOUSE}
@tindex FL_PLACE_MOUSE
@item FL_PLACE_MOUSE
The form is placed centered below the mouse. Interactive resizing will
not be allowed unless this option is accompanied by
@code{@ref{FL_FREE_SIZE}} as in
@code{@ref{FL_PLACE_MOUSE}|@ref{FL_FREE_SIZE}}.

@anchor{FL_PLACE_CENTER}
@tindex FL_PLACE_CENTER
@item FL_PLACE_CENTER
The form is placed in the center of the screen. If
@code{@ref{FL_FREE_SIZE}} is also specified, interactive resizing will
be allowed.

@anchor{FL_PLACE_FULLSCREEN}
@tindex FL_PLACE_FULLSCREEN
@item FL_PLACE_FULLSCREEN
The form is scaled to cover the full screen. If
@code{@ref{FL_FREE_SIZE}} is also specified, interactive resizing will
be allowed.

@anchor{FL_PLACE_FREE}
@tindex FL_PLACE_FREE
@item FL_PLACE_FREE
Both the position and size are completely free. The initial size used is
the designed size. Initial position, if setvia
@code{@ref{fl_set_form_position()}}, will be used otherwise interactive
positioning may be possible if the window manager allows it.

@anchor{FL_PLACE_HOTSPOT}
@tindex FL_PLACE_HOTSPOT
@item FL_PLACE_HOTSPOT
The form is placed so that mouse is on the form's "hotspot". If
@code{@ref{FL_FREE_SIZE}} is also specified, interactive resizing will
be allowed.

@anchor{FL_PLACE_CENTERFREE}
@tindex FL_PLACE_CENTERFREE
@item FL_PLACE_CENTERFREE
Same as @code{@ref{FL_PLACE_CENTER}|@ref{FL_FREE_SIZE}}, i.e., place
the form at the center of the screen and allow resizing.

@anchor{FL_PLACE_ICONIC}
@tindex FL_PLACE_ICONIC
@item FL_PLACE_ICONIC
The form is shown initially iconified. The size and location used are
the window manager's default.
@end table

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
@anchor{FL_FREE_SIZE}
@tindex FL_FREE_SIZE
@code{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
@findex fl_set_form_position()
@example
void fl_set_form_position(FL_FORM *form, FL_Coord x, FL_Coord y);
@end example
@noindent
and
@findex fl_set_form_size()
@example
void fl_set_form_size(FL_FORM *form, FL_Coord w, FL_Coord h);
@end example
@noindent
or, combining both these two functions,
@findex fl_set_form_geometry()
@example
void fl_set_form_geometry(FL_FORM form*, FL_Coord x, FL_Coord y,
                          FL_Coord w, FL_Coord h);
@end example
@noindent
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.) @code{x}, @code{y}, @code{w} and
@code{h} indicate the position of the form on the screen and its
size@footnote{The parameters should be sensitive to the coordinate
unit in effect at the time of the call, but at present, they are not,
i.e., the function takes only values in pixel units.}. 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
@code{@ref{FL_PLACE_GEOMETRY}}, @code{@ref{FL_PLACE_FREE}}. E.g., to
place a form at the lower-right corner of the screen use
@example
fl_set_form_position(form, -form->w, -form->h);
fl_show_form(form, FL_PLACE_GEOMETRY, FL_TRANSIENT, "formName");
@end example

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"
@findex fl_set_form_hotspot()
@anchor{fl_set_form_hotspot()}
@findex fl_set_form_hotobject()
@anchor{fl_set_form_hotobject()}
@example
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);
@end example
@noindent
and then use @code{@ref{FL_PLACE_HOTSPOT}} for the @code{place}
argument in the call of @code{@ref{fl_show_form()}}. The coordinates
@code{x} and @code{y} are relative to the upper-left hand corner of
the form (within the window decorations).

In the call @code{@ref{fl_show_form()}} the argument @code{border}
indicates whether or not to request window manager's decoration.
@code{border} should take one of the following values:
@table @code
@anchor{FL_FULLBORDER}
@tindex FL_FULLBORDER
@item FL_FULLBORDER
Full border decorations.

@anchor{FL_TRANSIENT}
@tindex FL_TRANSIENT
@item FL_TRANSIENT
Borders with (possibly) less decorations.

@anchor{FL_NOBORDER}
@tindex FL_NOBORDER
@item FL_NOBORDER
No decoration at all.
@end table

For some dialogs, such as demanding an answer etc., you probably do
not want the window manager's full decorations. Use
@code{@ref{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. @code{@ref{FL_NOBORDER}} is guaranteed to have no
border@footnote{Provided the window manager is compliant. If the
window manager isn't compliant all bets are off.} and is immune to
iconification request. Because of this, borderless forms can be
hostile to other applications@footnote{Actually, they are also hostile
to their sibling forms. @xref{Part V Overview of Main Functions, ,
Overview of Main Functions}.}, so use this only if absolutely
necessary.

There are other subtle differences between the different decoration
requests. For instance, (small) transient forms always have
@code{save_under} (see @code{XSetWindowAttributes()}) set to true by
default. Some window properties, @code{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
@findex fl_set_app_mainform()
@example
void fl_set_app_mainform(FL_FORM *form);
@end example
@noindent
Setting the main form of an application will cause the @code{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
@findex fl_prepare_form_window()
@example
Window fl_prepare_form_window(FL_FORM *form, int place, int border,
                              const char *name);
@end example
@noindent
This routine creates a window that obeys any and all constraints just
as @code{@ref{fl_show_form()}} does but remains unmapped. To map such
a window, the following must be used
@findex fl_show_form_window()
@example
Window fl_show_form_window(FL_FORM *form);
@end example
@noindent
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 @code{@ref{fl_show_form()}}.

You can also scale the form and all objects on it programmatically using
the following routine
@findex fl_scale_form()
@example
void fl_scale_form(FL_FORM *form, double xsc, double ysc);
@end example
@noindent
where you indicate a scaling factor in the x- and y-direction with
respect to the current size. See @file{rescale.c} for an example.

When a form is scaled, either programmatically or interactively, all
objects on the form per defaukt 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
@findex fl_set_object_resize()
@findex fl_set_object_gravity()
@example
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);
@end example

The @code{how_resize} argument of @code{@ref{fl_set_object_resize()}}
can be one of
@table @code
@anchor{FL_RESIZE_NONE}
@tindex FL_RESIZE_NONE
@item FL_RESIZE_NONE
don't resize the object at all

@anchor{FL_RESIZE_X}
@tindex FL_RESIZE_X
@item FL_RESIZE_X
resize it in x- (horizontal) direction only

@anchor{FL_RESIZE_Y}
@tindex FL_RESIZE_Y
@item FL_RESIZE_Y
resize it in y- (vertical) direction only

@anchor{FL_RESIZE_ALL}
@tindex FL_RESIZE_ALL
@item FL_RESIZE_ALL
is an alias for @code{@ref{FL_RESIZE_X}|@ref{FL_RESIZE_Y}} and makes
the object resizable in both dimension.
@end table

The arguments @code{nw_gravity} and @code{se_gravity} of
@code{fl_set_object_gravity()} control the positioning of the
upper-left and lower-right corner of the object and work analogously
to the @code{win_gravity} in Xlib. The details are as follows: Let
@code{P} be the corner the gravity applies to, @code{(dx1,dy1)} the
distance to the upper-left corner of the form, @code{(dx2,dy2)} the
distance to the lower-right corner of the form, then,
@multitable @columnfractions 0.4 0.1 0.5
@headitem Value
@tab
@tab Effect
@anchor{FL_NoGravity}
@tindex FL_NoGravity
@item @code{FL_NoGravity}
@tab @tie{}
@tab Default linear scaling, see below

@anchor{FL_NorthWest}
@tindex FL_NorthWest
@item @code{FL_NorthWest}
@tab
@tab @code{dx1}, @code{dy1} constant

@anchor{FL_North}
@tindex FL_North
@item @code{FL_North}
@tab
@tab @code{dy1} constant

@anchor{FL_NorthEast}
@tindex FL_NorthEast
@item @code{FL_NorthEast}
@tab
@tab @code{dy1}, @code{dx2} constant

@anchor{FL_West}
@tindex FL_West
@item @code{FL_West}
@tab
@tab @code{dx1} constant

@anchor{FL_East}
@tindex FL_East
@item @code{FL_East}
@tab
@tab @code{dx2} constant

@anchor{FL_SouthWest}
@tindex FL_SouthWest
@item @code{FL_SouthWest}
@tab
@tab @code{dx1}, @code{dy2} constant

@anchor{FL_South}
@tindex FL_South
@item @code{FL_South}
@tab
@tab @code{dy2} constant

@anchor{FL_SouthEast}
@tindex FL_SouthEast
@item @code{FL_SouthEast}
@tab
@tab @code{dx2}, @code{dy2} constant

@anchor{ForgetGravity}
@tindex ForgetGravity
@item @code{ForgetGravity}
@tab
@tab don't consider the setting for this argument
@end multitable

@ifhtml
@center @image{images/gravity}
@end ifhtml
@ifnothtml
@center @image{images/gravity,7cm}
@end ifnothtml

Default for all object is @code{@ref{FL_RESIZE_ALL}} and
@code{@ref{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
@code{@ref{FL_NoGravity}}.

For the special case where @code{how_resize} is
@code{@ref{FL_RESIZE_NONE}} and both gravities are set to
@code{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 @code{@ref{FL_PLACE_GEOMETRY}} or other size-restricting options,
resizing it later via @code{@ref{fl_set_form_size()}} will likely be
rejected.

To determine the gravity and resize settings for an object use the
functions
@findex fl_get_object_gravity()
@findex fl_get_object_resize()
@example
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 );
@end example

Sometimes, you may want to change an attribute for all objects on a
particular form, to this end, the following iterator is available
@findex fl_for_all_objects()
@anchor{fl_for_all_objects()}
@example
void fl_for_all_objects(FL_FORM *form,
                        int (*operate)(FL_OBJECT *obj, void *data),
                        void *data);
@end example
@noindent
where function @code{operate} is called for every object of the form
@code{form} unless @code{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 call can be used
@findex fl_set_form_title()
@example
void fl_set_form_title(FL_FORM *form, const char *name)
@end example

To set or change the icon shown when a form is iconified, use the
following routine
@findex fl_set_form_icon()
@example
void fl_set_form_icon(FL_FORM *form, Pixmap icon, Pixmap mask);
@end example
@noindent
where @code{icon} and @code{mask} can be any valid Pixmap ID. (See
@ref{Other Pixmap Routines} for some of the routines that can be used
to create Pixmaps.) Note that an @code{icon} previously setvia this
function (if it exists) is not freed or modified in anyway. See the
demo program @file{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
@findex fl_hide_form()
@example
void fl_hide_form(FL_FORM *form);
@end example

To check if a form is visible or not, use the following call
@findex fl_form_is_visible()
@example
int fl_form_is_visible(FL_FORM *form);
@end example
@noindent
The function returns one of
@table @code
@anchor{FL_INVISIBLE}
@tindex FL_INVISIBLE
@item FL_INVISIBLE
if the form is not visible (0),

@anchor{FL_VISIBLE}
@tindex FL_VISIBLE
@item FL_VISIBLE
if the form is visible (1) and

@anchor{FL_BEING_HIDDEN}
@tindex FL_BEING_HIDDEN
@item FL_BEING_HIDDEN
if the form is visible but is in the process of being hidden (-1).
@end table

Note that if you don't need a form anymore you can deallocate its
memory using the call @code{@ref{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 @code{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
@findex fl_set_atclose()
@anchor{fl_set_atclose()}
@example
int fl_set_atclose(int (*at_close)(FL_FORM *, void *), void *data);
@end example
@noindent
The callback function @code{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
@code{WM_DELETE_WINDOW} message. To prevent the Forms Library from
terminating the application, the callback function should return the
constant @code{FL_IGNORE}. Any other value (e.g., @code{FL_OK}) will
result in the termination of the application.

Similar mechanism exists for individual forms
@findex fl_set_form_atclose()
@anchor{fl_set_form_atclose()}
@example
int fl_set_form_atclose(FL_FORM *,
                        int (*at_close)(FL_FORM *, void *),
                        void *data);
@end example
@noindent
except that @code{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 @code{exit(3)} yourself within the
callback function.


@node Simple Interaction
@section 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
@findex fl_do_forms()
@example
FL_OBJECT *fl_do_forms(void);
@end example
@noindent
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:
@table @asis
@item box
A box never changes state and, hence, is never returned by
@code{@ref{fl_do_forms()}}.

@item text
Also a text never changes state.

@item 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.@:
@file{touchbutton.c} for the use of touch buttons.)

@item 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.

@item 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.
@end table

(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
@code{@ref{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
@code{@ref{fl_do_forms()}} is called again to continue the
interaction. Hence, simpler programs have the following global form:
@example
/* 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 */
    ....
@}
@end example

For more complex programs interaction via callbacks is often
preferable. For such programs, the global structure looks something
like the following
@example
/* 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;
@}
@end example
@noindent
In this case, @code{@ref{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
@findex fl_set_object_return()
@anchor{fl_set_object_return()}
@example
int fl_set_object_return(FL_OBJECT *obj, unsigned int when);
@end example
with @code{when} set to @code{FL_RETURN_END_CHANGED}.

There are several values @code{when} can take:
@table @code
@anchor{FL_RETURN_CHANGED}
@tindex FL_RETURN_CHANGED
@item 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.).

@anchor{FL_RETURN_END}
@tindex FL_RETURN_END
@item 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.

@anchor{FL_RETURN_END_CHANGED}
@tindex FL_RETURN_END_CHANGED
@item FL_RETURN_END_CHANGED
Return (or call object callback) when interaction stops @strong{and}
the state of the object changed.

@anchor{FL_RETURN_SELECTION}
@tindex FL_RETURN_SELECTION
@item FL_RETURN_SELECTION
Return when e.g.@: a line in a @code{@ref{FL_MULTI_BROWSER}} browser
was selected.

@anchor{FL_RETURN_DESELECTION}
@tindex FL_RETURN_DESELECTION
@item FL_RETURN_DESELECTION
Return when e.g.@: a line in a @code{@ref{FL_MULTI_BROWSER}} browser
was deselected.

@anchor{FL_RETURN_ALWAYS}
@tindex FL_RETURN_ALWAYS
@item FL_RETURN_ALWAYS
Return (or invoke callback) on any of the events that can happen
to the object.

@anchor{FL_RETURN_NONE}
@tindex FL_RETURN_NONE
@item 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.
@end table

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 @code{@ref{FL_RETURN_END_CHANGED}},
@code{@ref{FL_RETURN_ALWAYS}} and @code{@ref{FL_RETURN_NONE}} can be
logically @code{OR}'ed. @code{@ref{FL_RETURN_END_CHANGED}} is
different in that it only can be returned when the conditions for
@code{@ref{FL_RETURN_END}} and @code{@ref{FL_RETURN_CHANGED}} are
satisfied at once. If this is request @code{@ref{FL_RETURN_END}} and
@code{@ref{FL_RETURN_CHANGED}} will automatically deselected. So if
you want notifications about the conditions that lead to
@code{@ref{FL_RETURN_END}} or @code{@ref{FL_RETURN_CHANGED}} (or both
at once) ask instead for the logical @code{OR} of these two.

@code{@ref{FL_RETURN_ALWAYS}} includes all conditions except
@code{@ref{FL_RETURN_END_CHANGED}}.

Once an object is returned (or its callback invoked) you can determine
the reason it was returned by calling
@findex fl_get_object_return_state()
@anchor{fl_get_object_return_state()}
@example
int fl_get_object_return_state(FL_OBBJECT *obj);
@end example
The returned value is logical @code{OR} of the conditions that led to
the object getting returned, where the conditions can be
@code{@ref{FL_RETURN_CHANGED}}, @code{@ref{FL_RETURN_END}},
@code{@ref{FL_RETURN_SELECTION}} and @code{@ref{FL_RETURN_DESELECTION}}.
(The @code{@ref{FL_RETURN_END_CHANGED}} condition is satisfied
if both @code{@ref{FL_RETURN_END}} and @code{@ref{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.@:
@code{@ref{fl_do_forms()}}. Further interactions with the object
overwrite the value!


@node Periodic Events and Non-blocking Interaction
@section 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
@findex fl_set_idle_callback()
@example
FL_APPEVENT_CB fl_set_idle_callback(FL_APPEVENT_CB callback,
                                    void *user_data);
@end example

After the registration, whenever the main loop
(@code{@ref{fl_do_forms()}}) is idle, i.e., no user action or light
user action, the callback function is called as
@example
int callback(xev, user_data);
@end example
@noindent
where @code{user_data} is the void pointer passed to the system in
@code{@ref{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. @code{xev} is a pointer to a
synthetic@footnote{I.e. @code{xev->xmotion.send_event} is true.}
@code{MotionNotify} event from which some information about mouse
position etc. can be obtained. To remove the idle callback, use
@code{@ref{fl_set_idle_callback()}} with callback set to @code{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
@tindex FL_TIMEOUT_CALLBACK
@findex fl_add_timeout()
@example
typedef void (*FL_TIMEOUT_CALLBACK)(int, void *);
int fl_add_timeout(long msec, FL_TIMEOUT_CALLBACK callback,
                   void *data);
@end example
@noindent
The function returns the timeout's ID@footnote{The function will not
return 0 or -1 as timeout IDs, so the application program can use these
values to tag invalid or expired timeouts.}. When the time interval
specified by @code{msec} (in milli-second) is 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 of
the callback function is passed the data pointer that was passed to
@code{@ref{fl_add_timeout()}}.

To remove a timeout before it triggers, use the following routine
@findex fl_remove_timeout()
@example
void fl_remove_timeout(int id);
@end example
@noindent
where @code{id} is the timeout ID returned by
@code{@ref{fl_add_timeout()}}. There is also an @code{FL_OBJECT}, the
@code{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. @xref{Timer Object},
for complete information on the @code{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:
@findex fl_check_forms()
@example
FL_OBJECT *fl_check_forms(void);
@end example
@noindent
This function is similar to @code{@ref{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 @code{@ref{fl_do_forms()}}. But when no change has
occurred control is also returned but this time a @code{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,
@code{@ref{fl_check_forms()}} always returns @code{NULL}, otherwise,
code similar to the following is needed:
@example
obj = fl_check_forms();
if (obj == obj1)
    /* handle it */
...
@end example
@noindent
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
@code{@ref{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 @code{@ref{fl_exe_command()}} and
@code{@ref{fl_popen()}} documented later in @ref{Command Log}.


@node Dealing With Multiple Windows
@section 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, @code{@ref{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
@findex fl_deactivate_form()
@example
void fl_deactivate_form(FL_FORM *form);
@end example

To reactivate the form later again use
@findex fl_activate_form()
@example
void fl_activate_form(FL_FORM *form);
@end example

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 @code{@ref{fl_set_object_lcol()}} (see
@file{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:
@tindex FL_FORM_ATACTIVATE
@tindex FL_FORM_ATDEACTIVATE
@findex fl_set_form_atactivate()
@findex fl_set_form_atdeactivate()
@example
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);
@end example

It is also possible to deactivate all current forms and reactivate them
again. To this end use the functions:
@findex fl_deactivate_all_forms()
@findex fl_activate_all_forms()
@example
void fl_deactivate_all_forms(void);
void fl_activate_all_forms(void);
@end example
@noindent
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
@code{@ref{fl_do_forms()}} and @code{@ref{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 @code{XNextEvent()}, the program will use
@code{@ref{fl_XNextEvent()}}, with the same parameters except the
@code{Display *} argument. The following is a list of all replacement
routines:
@findex fl_XNextEvent()
@anchor{fl_XNextEvent()}
@findex fl_XPeekEvent()
@anchor{fl_XPeekEvent()}
@findex fl_XEventsQueued()
@anchor{fl_XEventsQueued()}
@findex fl_XPutbackEvent()
@anchor{fl_XPutbackEvent()}
@example
int fl_XNextEvent(XEvent *xev);
int fl_XPeekEvent(XEvent *xev);
int fl_XEventsQueued(int mode);
int fl_XPutbackEvent(XEvent *xev);
@end example

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 @code{XWindowEvent()},
@code{XCheckWindowEvent()} etc.

To help find out when an event has occurred, whenever
@code{@ref{fl_do_forms()}} and @code{@ref{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
@tindex FL_EVENT
@code{FL_EVENT}. Upon receiving this special event, the application
program can and must remove the pending event from the queue using
@code{@ref{fl_XNextEvent()}}.

So the basis of a program with its own windows would look as follows:
@example
/* 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 */
    @}
@}
@end example

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
@code{@ref{fl_do_only_forms()}} and @code{@ref{fl_check_only_forms()}}
that will never return @code{FL_EVENT}. The events don't disappear but
will be returned at later calls to the normal routines
@code{@ref{fl_do_forms()}} etc.

It can't be over-emphasized that it is an error to ignore
@code{FL_EVENT} or use @code{@ref{fl_XNextEvent()}} without seeing
@code{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
@findex fl_mouse_button()
@anchor{fl_mouse_button()}
@example
long fl_mouse_button(void);
@end example
@noindent
This function, if needed, should be called from within a callback. The
function returns one of the constants @code{@ref{FL_LEFT_MOUSE}},
@code{@ref{FL_MIDDLE_MOUSE}}, @code{@ref{FL_RIGHT_MOUSE}},
@code{@ref{FL_SCROLLUP_MOUSE}} or @code{@ref{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
@tindex FL_SHORTCUT
@code{@ref{FL_SHORTCUT}}. For example, if a button has a shortcut
@code{<Ctrl>C} (ASCII value is 3), the button number returned upon
activation of the shortcut would be @code{FL_SHORTCUT + 3}.
@code{@ref{FL_SHORTCUT}} can be used to determine if the callback is
triggered by a shortcut or not
@example
if (fl_mouse_button() >= FL_SHORTCUT)
    /* handle shortcut */
else
    switch (fl_mouse_button()) @{
        case FL_LEFTMOUSE:
        ....
    @}
@end example

More information can be obtained by using the following routine that
returns the last @code{XEvent}
@findex fl_last_event()
@example
const XEvent *fl_last_event(void);
@end example
@noindent
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 @code{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:
@findex fl_get_winorigin()
@findex fl_get_winsize()
@findex fl_get_wingeometry()
@example
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);
@end example
@noindent
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:
@findex fl_get_mouse()
@example
Window fl_get_mouse(FL_Coord *x, FL_Coord *y,
                    unsigned int *keymask);
@end example
@noindent
where @code{keymask} is the same as used in @code{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
@findex fl_get_win_mouse()
@example
Window fl_get_win_mouse(Window win, FL_Coord *x, FL_Coord *y,
                        unsigned int *keymask);
@end example

To print the name of an XEvent, the following routine can be used:
@findex fl_print_xevent_name()
@anchor{fl_print_xevent_name()}
@example
XEvent *fl_print_xevent_name(const char *where, const XEvent *xev);
@end example
@noindent
The function takes an XEvent, prints out its name and some other info,
e.g., @code{expose, count=n}. Parameter @code{where} can be used to
indicate where this function is called:
@example
fl_print_xevent_name("In tricky.c", &xevent);
@end example


@node Using Callback Functions
@section 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,
@code{@ref{fl_do_forms()}} or @code{@ref{fl_check_forms()}} invokes
the callback function instead of returning the object.

To bind a callback routine to an object, use the following
@tindex FL_CALLBACKPTR
@findex fl_set_object_callback()
@example
typedef void (*FL_CALLBACKPTR)(FL_OBJECT *obj, long argument);
FL_CALLBACKPTR fl_set_object_callback(FL_OBJECT *obj,
                                      FL_CALLBACKPTR callback,
                                      long argument);
@end example
@noindent
where @code{callback} is the callback function. @code{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 @file{timer.c}.

The callback routine should have the form
@example
void callback(FL_OBJECT *obj, long argument);
@end example
@noindent
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
@code{@ref{fl_set_object_callback()}}.

See program @file{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, @code{void *u_vdata}, @code{char *u_cdata} and @code{long
u_ldata}, in the @code{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 @code{u_vdata} or some field
in the @code{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 @code{@ref{fl_set_button()}},
@code{@ref{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
@findex fl_call_object_callback()
@example
void fl_call_object_callback(FL_OBJECT *obj);
@end example

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
@findex fl_set_form_callback()
@example
void fl_set_form_callback(FL_FORM *form,
                          void (*callback)(FL_OBJECT *, void *),
                          void *data);
@end example

Whenever @code{@ref{fl_do_forms()}} or @code{@ref{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
@example
void callback(FL_OBJECT *obj, void *data);
@end example

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 @code{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 use the call
@tindex FL_APPEVENT_CB
@findex fl_set_event_callback()
@example
FL_APPEVENT_CB fl_set_event_callback(int (*callback)(XEvent *ev,
                                                     void *data),
                                     void *data);
@end example
@noindent
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
@example
typedef int (*FL_APPEVENT_CB)(XEvent *ev, void *data);
int callback(XEvent *xev, void *data);
@end example

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
@code{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:
@findex fl_add_event_callback()
@example
FL_APPEVENT_CB fl_add_event_callback(Window window, int xev_type,
                                     FL_APPEVENT_CB callback,
                                     void *user_data);
@end example
@noindent
where @code{window} is the window for which the callback routine is to
be registered. @code{xev_type} is the XEvent type you're interested
in, e.g., @code{Expose} etc. If @code{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
@code{@ref{fl_register_raw_callback()}} discussed in @ref{Form Events}.

@code{@ref{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
@findex fl_activate_event_callbacks()
@example
void fl_activate_event_callbacks(Window win);
@end example
@noindent
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, @code{MotionNotify} event can be
mapped into @code{ButtonMotionMask} or @code{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:
@findex fl_addto_selected_xevent()
@anchor{fl_addto_selected_xevent()}
@findex fl_remove_selected_xevent()
@anchor{fl_remove_selected_xevent()}
@example
long fl_addto_selected_xevent(Window win, long mask);
long fl_remove_selected_xevent(Window win, long mask);
@end example

Both functions return the resulting event masks that are currently
selected. If event callback functions are registered via both
@code{fl_set_event_callback()} and
@code{@ref{fl_add_event_callback()}}, the callback via the latter is
invoked first and the callback registered via
@code{@ref{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
@example
fl_add_event_callback(winID, Expose, expose_cb, 0);
fl_set_event_callback(event_callback);
@end example
and all @code{Expose} events on window @code{winID} are consumed
by @code{expose_cb} then @code{event_callback()} would never be
invoked as a result of an @code{Expose} event.

To remove a callback, use the following routine
@findex fl_remove_event_callback()
@example
void fl_remove_event_callback(Window win, int xev_type);
@end example
@noindent
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
@code{@ref{fl_activate_event_callbacks()}}. If @code{xev_type} is 0,
all callbacks for window @code{win} are removed. This routine is
called automatically if @code{@ref{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
@code{XDestroyWindow()}.

A program using all of these has the following basic form:
@example
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;
@}
@end example
@noindent
The routine @code{@ref{fl_do_forms()}} will never return in this case.
See @file{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.


@node Handling Other Input Sources
@section 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
@tindex FL_IO_CALLBACK
@findex fl_add_io_callback()
@anchor{fl_add_io_callback()}
@example
typedef void (*FL_IO_CALLBACK)(int fd, void *data);
void fl_add_io_callback(int fd, unsigned condition,
                        FL_IO_CALLBACK callback, void *data);
@end example
@noindent
registers an input callback with the system. The argument @code{fd}
must be a valid file descriptor on a UNIX-based system or other
operating system dependent device specification while @code{condition}
indicates under what circumstance the input callback should be
invoked. The condition must be one of the following constants
@table @code
@tindex FL_READ
@item FL_READ
File descriptor has data available.

@tindex FL_WRITE
@item FL_WRITE
File descriptor is available for writing.

@tindex FL_EXCEPT
@item FL_EXCEPT
an I/O error has occurred.
@end table

When the given condition occurs, the Forms Library invokes the callback
function specified by @code{callback}. The @code{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
@findex fl_remove_io_callback()
@anchor{fl_remove_io_callback()}
@example
void fl_remove_io_callback(int fd, unsigned condition,
                           FL_IO_CALLBACK callback);
@end example

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.