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

Next: FormBrowser Remarks, Previous: FormBrowser Interaction, Up: FormBrowser Object [Contents][Index]

#### 20.2.4 Other FormBrowser Routines

To populate a formbrowser, use the following routine

    int fl_addto_formbrowser(FL_OBJECT *obj, FL_FORM *form);

where `form` is a pointer to a regular form created between calls of `fl_bgn_form()` and `fl_end_form()`. Only the form pointer is passed to the function, which means that the form should be valid for the duration of the formbrowser and the application program should not destroy a form that is added to a formbrowser before deleting the form from the formbrowser first. The function returns the total number of forms in the formbrowser. Note that although there is no specific requirement on what the backface of the form should be, not all boxtypes look nice.

The form so added is appended to the list of forms that are already in the formbrowser. You can also use the following routine to obtain the total number of forms in a formbrowser

    int fl_get_formbrowser_numforms(FL_OBJECT *formbrowser);

Although a regular form (top-level) and a form used inside a formbrowser behave almost identically, there are some differences. In a top-level form, objects that do not have callbacks bound to them will be returned to the application program when their states change via `fl_do_forms()` or `fl_check_forms()`. When a form is used as member of a formbrowser those objects that do not have callbacks are ignored even when their states change.

To remove a form from the formbrowser, the following routine is available

    int fl_delete_formbrowser(FL_OBJECT *obj, FL_FORM *form);
    FL_FORM* fl_delete_formbrowser_bynumber(FL_OBJECT *obj, int num);

In the first function you specify the form to be removed from the formbrowser by a pointer to the form. If the form was removed successfully the function returns the remaining number of forms in the formbrowser, otherwise -1.

In the second function, you indicate the form to be removed with a sequence number, an integer between 1 and the number of forms in the browser. The sequence number is basically the order in which forms were added to the formbrowser. After a form is removed, the sequence numbers are re-adjusted so they are always consecutive. The function returns `NULL` if `num` was invalid, otherwise it returns address of the form that was removed.

To replace a form in formbrowser, the following routine is available

    FL_FORM *fl_replace_formbrowser(FL_OBJECT *obj, int num,
                                    FL_FORM *form);

where `num` is the sequence number of the form that is to be replaced by `form`. For example, to replace the first form in the browser with a different form, you should use 1 for `num`. The function returns the form that has been replaced on success, otherwise `NULL` is returned.

You can also insert a form into a formbrowser at arbitrary locations using the following routine

    int fl_insert_formbrowser(FL_OBJECT *obj, int num, FL_FORM *form);

where `num` is the sequence number before which the new form `form` is to be inserted into the formbrowser. If successful the function returns the number of forms in the formbrowser, otherwise -1.

To find out the sequence number of a particular form, the following routine is available

    int fl_find_formbrowser_form_number(FL_OBJECT *obj, FL_FORM *form);

The function returns a number between 1 and the number of forms in the formbrowser on success, otherwise 0.

To obtain the form handle from the sequence number, use the following routine

    int fl_get_formbrowser_form(FL_OBJECT *obj, int num);

By default, if the size of the forms exceeds the size of the formbrowser, scrollbars are added automatically. You can use the following routines to control the scrollbars

    void fl_set_formbrowser_hscrollbar(FL_OBJECT *obj, int how);
    void fl_set_formbrowser_vscrollbar(FL_OBJECT *obj, int how);

where `how` can be one of the following

`FL_ON`

  Always on.

`FL_OFF`

  Always off.

`FL_AUTO`

  On when needed. This is the default.

The vertical scrollbar by default scrolls a fixed number of pixels. To change it so each action of the scrollbar scrolls to the next forms, the following routine is available

    void fl_set_formbrowser_scroll(FL_OBJECT *obj, int how)

where `how` can be one of the following

`FL_SMOOTH_SCROLL`

  The default.

`FL_JUMP_SCROLL`

  Scrolls in form increments.

To obtain the form that is currently the first form in the formbrowser visible to the user, the following can be used

    FL_FORM *fl_get_formbrowser_topform(FL_OBJECT *obj);

You can also set which form to show by setting the top form using the following routine

    int fl_set_formbrowser_topform(FL_OBJECT *obj, FL_FORM *form);
    FL_FORM* fl_set_formbrowser_topform_bynumber(FL_OBJECT *obj, int num);

The first function returns the sequence number of the form and the second function returns the form with sequence number `num`.

Since the area occupied by the formbrowser contains the space for the scrollbars, the following routine is available to obtain the actual size of the forms area

    void fl_get_formbrowser_area(FL_OBJECT *obj, int *x, int *y,
                                 int *w, int *h);

where `x` and `y` are relative to the (top-level) form the formbrowser belongs to.

To programatically scroll within a formbrowser in horizontal and vertical direction, the following routines are available

    int fl_set_formbrowser_xoffset(FL_OBJECT *obj, int offset);
    int fl_set_formbrowser_yoffset(FL_OBJECT *obj, int offset);

where `offset` is a positive number, measuring in pixels the offset from the the natural position from the left and the top, respectively. In other words, 0 indicates the natural position of the content within the formbrowser. An x-offset of 10 means the content is scrolled 10 pixels to the left. Similarly an y-offset of 10 means the content is scrolled by 10 pixels upwards.

To obtain the current offsets, use the following routines

    int fl_get_formbrowser_xoffset(FL_OBJECT *obj);
    int fl_get_formbrowser_yoffset(FL_OBJECT *obj);

Next: FormBrowser Remarks, Previous: FormBrowser Interaction, Up: FormBrowser Object [Contents][Index]