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

Next: Browser Attributes, Previous: Browser Interaction, Up: Browser Object [Contents][Index]

#### 19.3.4 Other Browser Routines

There are a large number of routines to change the contents of a browser, select and de-select lines, etc.

To remove all lnes from a browser use

    void fl_clear_browser(FL_OBJECT *obj);

To add a line to a browser use one of

    void fl_add_browser_line(FL_OBJECT *obj, const char *text);
    void fl_add_browser_line_f(FL_OBJECT *obj, const char *fmt, ...);

The first function receives a simple string as the argument, the second one expects a format string just like for `printf()` etc. and followed by the appropriate number of arguments of the correct types. The line to be added may contain embedded newline characters (`'\n'`). These will result in the text being split up into several lines, separated at the newline characters.

A second way of adding a line to the browser is to use calls of

    void fl_addto_browser(FL_OBJECT *obj, const char *text);

The difference to `fl_add_browser_line()` and `fl_add_browser_line_f()` is that with these calls the browser will be shifted such that the newly appended line is visible. This is useful when e.g., using the browser to display messages.

Sometimes it may be more convenient to add characters to a browser without starting of a new line. To this end, the following routines exists

    void fl_addto_browser_chars(FL_OBJECT *obj, const char *text);
    void fl_addto_browser_chars_f(FL_OBJECT *obj, const char *fmt, ...);

These functions appends text to the last line in the browser without advancing the line counter. The to functions differ in that the first one takes a simple string argument while the second expects a format string just as for `printf()` etc., followed by a corresponding number of arguments. Again the text may contain embedded newline characters (`'\n'`). In that case, the text before the first embedded newline is appended to the last line, and everything afterwards is put onto new lines. As in the case of `fl_addto_browser()` the last added line will be visible in the browser.

You can also insert a line in front of a given line. All lines after it will be shifted. Note that the top line is numbered 1 (not 0).

    void fl_insert_browser_line(FL_OBJECT *obj, int line,
                                const char *text);
    void fl_insert_browser_line_f(FL_OBJECT *obj, int line,
                                  const char *fmt, ...);

The first function takes a simple string argument while the second one expects a format string as used for `printf()` etc. and the appropriate number of arguments (of the types specified in the format string).

Please note that on insertion (as well as replacements, see below) embedded newline characters don’t result in the line being split up as it’s done in the previous functions. Instead they will rather likely appear as strange looking characters in the text shown. The only exception is when inserting into an empty browser or after the last line, then this function works exactly as if you had called `fl_add_browser_line()` or `fl_add_browser_line_f()`.

To delete a line (shifting the following lines) use:

    void fl_delete_browser_line(FL_OBJECT *obj, int line);

One can also replace a line using one of

    void fl_replace_browser_line(FL_OBJECT *obj, int line,
                                 const char *text);
    void fl_replace_browser_line_f(FL_OBJECT *obj, int line,
                                   const char *fmt, ...);

The first one takes a simple string for the replacement text while for the second it is to be specified by a format string exactly as used in `printf()` etc. and the appropriate number of arguments of the types specifed in the format string. \ As in the case of `fl_insert_browser_line()` and `fl_insert_browser_line_f()` newline characters embedded into the replacement text don’t have any special meaning, i.e., they don’t result in replacement of more than a single line.

Making many changes to a visible browser after another, e.g., clearing it and then adding a number of new lines, is slow because the browser is redrawn on each and every change. This can be avoided by using calls of `fl_freeze_form()` and `fl_unfreeze_form()`. So a piece of code that fills in a visible browser should preferably look like the following

    fl_freeze_form(browser->form);
    fl_clear_browser(browser);
    fl_add_browser_line(browser, "line 1");
    fl_add_browser_line(browser, "line 2");
    ...
    fl_unfreeze_form(brow->form);

where `browser->form` is the form that contains the browser object named `browser`.

To obtain the contents of a particular line in the browser, use

    const char *fl_get_browser_line(FL_OBJECT *obj, int line);

It returns a pointer to the text of that line, exactly as it were passed to the function that created the line.

It is possible to load an entire file into a browser using

    int fl_load_browser(FL_OBJECT *obj, const char *filename);

The routine returns `1` when file could be successfully loaded, otherwise `0`. If the file name is an empty string (or the file could not be opened for reading) the browser is just cleared. This routine is particularly useful when using the browser for a help facility. You can create different help files and load the needed one depending on context.

The application program can select or de-select lines in the browser. To this end the following calls exist with the obvious meaning:

    void fl_select_browser_line(FL_OBJECT *obj, int line);
    void fl_deselect_browser_line(FL_OBJECT *obj, int line);
    void fl_deselect_browser(FL_OBJECT *obj);

The last call de-selects all lines.

To check whether a line is selected, use the routine

    int fl_isselected_browser_line(FL_OBJECT *obj, int line);

The routine

    int fl_get_browser_maxline(FL_OBJECT *obj);

returns the number of lines in the browser. For example, when the application program wants to figure out which lines in a `FL_MULTI_BROWSER` are selected code similar to the following can be used:

    int total_lines = fl_get_browser_maxline(browser);
    for (i = 1; i <= total_lines; i++)
        if (fl_isselected_browser_line(browser, i))
            /* Handle the selected line */

Sometimes it is useful to know how many lines are visible in the browser. To this end, the following call can be used

    int fl_get_browser_screenlines(FL_OBJECT *obj);

Please note that this count only includes lines that are shown completely in the browser, lines that are partially obscured aren’t counted in.

To obtain the last selection made by the user, e.g., when the browser is returned, the application program can use the routine

    int fl_get_browser(FL_OBJECT *obj);

It returns the line number of the last selection being made (0 if no selection was made). When the last action was a de-selection (only for `FL_MULTI_BROWSER`) the negative of the de-selected line number is returned.

The following function allows to find out the (unobscured) line that is currently shown at the top of the browser:

    int fl_get_browser_topline(FL_OBJECT *obj);

Note that the index of the top line is `1`, not `0`. A value of `0` is returned if the browser doesn’t contain any lines.

Finally, the function

shifts the browsers content so that (as far as possible) the line indexed by `ln` is shown at the center of the browser.

It is possible to register a callback function that gets called when a line is double-clicked on. To do so, the following function is available:

    void fl_set_browser_dblclick_callback(FL_OBJECT *obj,
                                          void (*cb)(FL_OBJECT *, long),
    `                                     long data);

Of course, double-click callbacks make most sense for `FL_HOLD_BROWSER`s.

The part if the text visible within the browser can be set programmatically in a number of ways. With the functions

    void fl_set_browser_topline(FL_OBJECT *obj, int line);
    void fl_set_browser_bottomline(FL_OBJECT *obj, int line);

the line shown at the top or the bottom can be set (note again that line numbers start with 1).

Instead of by line number also the amount the text is scrolled in horizontal and vertical direction can be set with the functions

    void fl_set_browser_xoffset(FL_OBJECT *obj, FL_Coord xoff);
    void fl_set_browser_rel_xoffset(FL_OBJECT *obj, double xval);
    void fl_set_browser_yoffset(FL_OBJECT *obj, FL_Coord yoff);
    void fl_set_browser_rel_yoffset(FL_OBJECT *obj, double yval);

where `xoff` and `yoff` indicate how many pixels to scroll horizontally (relative to the left margin) or vertically (relative to the top of the text), while `xval` and `yval` stand for positions relative to the total width or height of all of the text and thus have to be numbers between `0.0` and `1.0`.

There are also a number of functions that can be used to obtain the current amount of scrolling:

    FL_Coord fl_get_browser_xoffset(FL_OBJECT *obj);
    FL_Coord fl_get_browser_rel_xoffset(FL_OBJECT *obj);
    FL_Coord fl_get_browser_yoffset(FL_OBJECT *obj);
    FL_Coord fl_get_browser_rel_yoffset(FL_OBJECT *obj);

Finally, there’s a function that tells you the vertical position of a line in pixels:

    int fl_get_browser_line_yoffset(FL_OBJECT *obj, imt line);

The return value is just the value that would have to be passed to `fl_set_browser_yoffset()` to make the line appear at the top of the browser. If the line does not exist it returns `-1` instead.

Next: Browser Attributes, Previous: Browser Interaction, Up: Browser Object [Contents][Index]