Next: Browser Attributes, Previous: Browser Interaction, Up: Browser Object [Contents][Index]
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);
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.
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]