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

Next: Other Browser Routines, Previous: Browser Types, Up: Browser Object [Contents][Index]

#### 19.3.3 Browser Interaction

The user can change the position of the slider or use keyboard cursor keys (including `<Home>`, `<PageDown>`, etc.) to scroll through the text. When he/she presses the left mouse below or above the slider, the browser scrolls one page up or down. Any other mouse button scrolls one line at a time (except wheel mouse buttons). When not using an `FL_NORMAL_BROWSER` the user can also make selections with the mouse by pointing to a line or by using the cursor keys.

For `FL_SELECT_BROWSER`’s, as long as the user keeps the left mouse button pressed, the current line under the mouse is highlighted. Whenever she releases the left mouse button the highlighting disappears and the browser is returned to the application program. The application program can now figure out which line was selected using a call of `fl_get_browser()` to be described below. It returns the number of the last selected line (with the topmost line being line 1).

A `FL_HOLD_BROWSER` works exactly the same except that, when the left mouse button is released, the selection remains highlighted. A `FL_DESELECTABLE_HOLD_BROWSER` additionally allows the user to undo a selection (by clicking on it again).

An `FL_MULTI_BROWSER` allows the user to select and de-select multiple lines. Whenever he selects or de-selects a line the browser object is returned to the application program (or a callback is executed when installed) that then can figure out which line was selected using `fl_get_browser()` (described in more detail below). That function returns the number of the last line to be selected or de-selected. When a line was de-selected the negation of the line number gets returned. I.e., if line 10 was selected the routine returns 10 and if line 10 was de-selected -10. When the user presses the left mouse button on a non-selected line and then moves it with the mouse button still pressed down, he will select all lines he touches with his mouse until he releases it. All these lines will become highlighted. When the user starts pressing the mouse on an already selected line he de-selects lines rather than selecting them.

Per default a browser only gets returned (or a possibly associated callback gets invoked) on selection of a line (and, in the case of `FL_MULTI_BROWSER`, on deselections). This behaviour can be changed by using the function

    int fl_set_object_return(FL_OBJECT *obj, unsigned int when)

where `when` can have the following values

`FL_RETURN_NONE`

  Never return or invoke callback.

`FL_RETURN_SELECTION`

  Return or invoke callback on selection of a line. Please note that for `FL_MULTI_BROWSER` the browser may be returned just once for a number of lines having been selected.

`FL_RETURN_DESELECTION`

  Return or invoke a callback on deselection of a line. This only happens for `FL_DESELECTABLE_HOLD_BROWSER` and `FL_MULTI_BROWSER` objects and, for the latter, the browser may get returned (or the callback invoked) just once for a number of lines having been deselected.

`FL_RETURN_END_CHANGED`

  Return or invoke callback at end (mouse release) if the text in the browser has been scrolled.

`FL_RETURN_CHANGED`

  Return or invoke callback whenever the text in the browser has been scrolled.

`FL_RETURN_END`

  Return or invoke callback on end of an interaction for scrolling the text in the browser regardless if the text was scrolled or not.

`FL_RETURN_ALWAYS`

  Return or invoke callback on selection, deselection or scrolling of text or end of scrolling.

The default setting for `when` for a browser object is `FL_RETURN_SELECTION|FL_RETURN_DESELECTION` (unless during the built of XForms you set the configuration flag `--enable-bwc-bs-hack` in which case the default is `FL_RETURN_NONE` to keep backward compatibility with earlier releases of the library).

Next: Other Browser Routines, Previous: Browser Types, Up: Browser Object [Contents][Index]