InterViews Reference Manual -- StringBrowser

NAME
StringBrowser - browse and/or select items in a list
SYNOPSIS
#include <InterViews/strbrowser.h>
DESCRIPTION
StringBrowser is an interactor that provides a browsing and selection interface to a list of strings. StringBrowsers are often used in dialog boxes to let the user browse and select from an unbounded set of textual entries. A StringBrowser displays the list of strings and provides several ways to scroll the list. The user selects strings with either the mouse or the keyboard; the StringBrowser can restrict selection to a single string or allow multiple selections. The application queries the StringBrowser for the selected string(s).

A  StringBrowser  contains  no  entries   initially;   strings   are   appended
consecutively  or  in  random order, and they can be removed in any order.  The
strings  are  accessed  with  a    string  index  from  0   to
n-1,   where   n   is  the  total  number  of  strings.   The
StringBrowser maintains a separate list of strings  that  have  been  selected;
these  strings  are  accessed with a selection index from 0 to
m-1, where m is the total number of selected strings.

Left-clicking inside the StringBrowser (or calling the Browse  function)  makes
it interpret subsequent keyboard events as scrolling or selection operations on
the entries.  StringBrowser  relinquishes  control  when  it  detects  a  click
outside its canvas or when it receives a predetermined escape character.

Middle-clicking  inside  the  StringBrowser  lets  the user ``grab-scroll'' the
entries.  During grab-scrolling,  the  StringBrowser  scrolls  the  entries  to
follow  the mouse position, making it appear as though the user is dragging the
entries themselves.  Right-clicking engages  ``rate-scrolling,''  a  joy-stick-
like  scrolling  interface  in  which  the scrolling rate increases as the user
drags the mouse away from the initial click point.  For example,  dragging  the
mouse  downwards  after  the  initial click scrolls the browser downwards at an
increasing rate; dragging upwards thereafter reduces the rate  until  scrolling
stops entirely at the initial click point.  Dragging up beyond this point makes
the browser scroll in the reverse direction.
KEY BINDINGS
Below are the key bindings for browsing and selection commands:
g Go to the first string.
G Go to the last string.
a Select all.
DEL or BS Unselect all.
p Select previous string.
n Select next string.
< Select topmost-visible string.
> Select bottommost-visible string.
j Scroll down one string.
k Scroll up one string.
SPACE Scroll down one screenful.
b Scroll up one screenful.
d Scroll down one-half screenful.
u Scroll up one-half screenful.
PUBLIC OPERATIONS
StringBrowser(ButtonState*, int rows, int cols, bool uniqueSel, int highlight, const char* done)
StringBrowser(const char* name, ButtonState*, int, int, bool, int, const char*)
Create a new StringBrowser object. The StringBrowser will use the ButtonState to communicate the result of browsing operations. The StringBrowser bases its shape on the rows and cols parameters: the height equals rows multiplied by the font height, and the width equals cols multiplied by the width of an average character. The uniqueSel parameter specifies whether or not selection is limited to one string (the default), and the highlight parameter specifies the appearance of selected strings (Reversed by default). Typing any character in the string done will make the StringBrowser stop interpreting keyboard events; the ButtonState is set to this terminating character as a side-effect. A double left-click inside the StringBrowser is equivalent to a single left-click selection followed by a key press that generates the first character in done. To be interpreted as a double-click, two clicks must occur not more than clickDelay milliseconds apart. The default click delay is 250 ms; a different value can be specified via the "clickDelay" user-preference attribute.
void Browse()
Initiate browsing. Subsequent keypresses will be interpreted as browsing and selection commands according to the key bindings listed above.
void Insert(const char* string, int index)
Insert string at position index. StringBrowser makes a copy of the string for internal use.
void Append(const char* string)
Insert a copy of string after the last string.
void Remove(int index)
Remove the string at position index, moving subsequent strings up to fill the gap.
int Index(const char* string)
Return the index of the first string that matches string.
char* String(int index)
Return the string at the given index.
int Count()
Return the total number of strings in the StringBrowser.
void Clear()
Remove all strings from the StringBrowser.
void Select(int index)
void Unselect(int index)
Select (unselect) the string at the given index. The string will be redrawn in the appropriate style. If multiple selections are not allowed and an another string has been selected already, then selecting a new string will unselect the original string.
void SelectAll()
void UnselectAll()
Select (unselect) all strings. SelectAll does nothing if multiple selections have been disallowed.
int Selection(int n)
Return the string index of the nth selected string.
int SelectionIndex(int n)
Return the selection index of the nth string.
int Selections()
Return the total number of selected strings.
bool Select(int n)
Return whether the nth string has been selected.
SEE ALSO
Interactor , Button

Next: StringChooser | Prev: Shape | Up: index | Top: index