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

Next: Object Attributes, Previous: Initialization, Up: Part V Overview of Main Functions [Contents][Index]

### 32.3 Creating Forms

To start the definition of a form call

    FL_FORM *fl_bgn_form(int type, FL_Coord w, FL_Coord h);

When the form is created it automatically acquires one object, a box object covering the full area of the form, which is used as the background of the form. The `type` argument is the type of this box object, so you can "style" the look of your forms (but don’t use any non-rectangular box types). `w` and `h` are the width and height of the new form. The function returns a pointer to the new form.

Note: if you look at the code generated by `fdesign` for the creation of a form you may notice that the type of this automatically assigned box is `FL_NO_BOX` (which is invisible) and that for the background another box of the same size but a different (visible) type is added. This is because in `fdesign` the very first object can’t be accessed and thus its properties can not be adjusted (like the box type or its color that then becomes the background color of the form). By using an extra box, which can be accessed from within `fdesign`, that problem is circumvented.

There also exist functions for setting and requesting the background color of a form

    void fl_set_form_background_color(FL_FORM *form, FL_COLOR col);
    FL_COLOR fl_get_form_background_color(FL_FORM *form);

These functions use the color of the very first object of the form, or, if this is a box of type `FL_NO_BOX` as it is the case with forms created via code generated by `fdesign`, the color of the second object. If these object(s) don’t exist the function can’t work properly.

Once all objects required have been added to a form call

    void fl_end_form(void);

Between these two calls objects and groups of objects are added to the form with functions like `fl_add_button()`.

To start a new group of objects use

    FL_OBJECT *fl_bgn_group(void);

The function returns a pointer to the group (actually to an invisible pseudo-object of class `FL_BEGIN_GROUP`). Groups can’t be nested.

When all objects that are supposed to belong to the group are added call

    void fl_end_group(void);

Also this function creates an (invisible) pseudo-object, belonging to class `FL_END_GROUP`, but since it can’t be used its address isn ot returned.

Groups are useful for two reasons. First of all, it is possible to hide or deactivate groups of objects with a single function call. This is often very handy to dynamically change the appearance of a form depending on the context or selected options. In addition it can also be used as a shortcut to set some particular attributes of several objects. It is not uncommon that you want several objects to maintain their relative positioning upon form resizing. This requires to set the gravity for each object. If these objects are placed inside a group, setting the gravity attributes of the group will suffice.

The second reason for use of groups is radio buttons. Radio buttons are considered related only if they belong to the same group. Using groups is the only way to place unrelated groups of radio buttons on a single form without interference from each other.

Both forms and groups that have been ended by `fl_end_form()` or `fl_end_group()` can be "reopened" by using

    FL_FORM *fl_addto_form(FL_FORM *form)
    FL_OBJECT *fl_addto_group(FL_OBJECT *group);

Both functions return their argument on success and `NULL` on failure (e.g., because a different group or form is still open). On success further objects can be appended to the form or group.

To remove an object from a form use

    void fl_delete_object(FL_OBJECT *obj);

This does not yet destroy the object, it just breaks its connection to the form it did belong to, so it can still be referenced and added to the same form again or some other form using

    void fl_add_object(FL_FORM *form, FL_OBJECT *obj);

even without "reopening" the form using `fl_addto_form()`.

To finally destroy an object use

    void fl_free_object(FL_OBJECT *obj);

If `fl_delete_object()` hadn’t been called for the object this will happen now. The object receives a final event of type `FL_FREEMEM` to allow it to free memory it did allocate and do whatever other clean-up required. Finally all memory allocated for the object is freed. After being freed an object can not be referenced anymore.

A form as a whole, together with all the objects it contains can be deleted by calling

    void fl_free_form(FL_FORM *form);

This will first hide the form (emitting warning if this is necessary), then free all of its objects and finally release memory allocated for the form.

Next: Object Attributes, Previous: Initialization, Up: Part V Overview of Main Functions [Contents][Index]