Displaying a Form (XForms (Forms Library) - Version 1.2 (Rev. 4) A Graphical User Interface Toolkit for X)

Next: Simple Interaction, Up: Part I Doing Interaction [Contents][Index]

### 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 size4. 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 border5 and is immune to iconification request. Because of this, borderless forms can be hostile to other applications6, 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,

Value |  | Effect
--- | --- | ---
`FL_NoGravity` |  | Default linear scaling, see below
`FL_NorthWest` |  | `dx1`, `dy1` constant
`FL_North` |  | `dy1` constant
`FL_NorthEast` |  | `dy1`, `dx2` constant
`FL_West` |  | `dx1` constant
`FL_East` |  | `dx2` constant
`FL_SouthWest` |  | `dx1`, `dy2` constant
`FL_South` |  | `dy2` constant
`FL_SouthEast` |  | `dx2`, `dy2` constant
`ForgetGravity` |  | don’t consider the setting for this argument

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.

#### Footnotes

### (4)

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.

### (5)

Provided the window manager is compliant. If the window manager isn’t compliant all bets are off.

### (6)

Actually, they are also hostile to their sibling forms. See Overview of Main Functions.

Next: Simple Interaction, Up: Part I Doing Interaction [Contents][Index]