Next: , Previous: , 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: , Previous: , Up: FormBrowser Object   [Contents][Index]