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. String-
Browsers 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 com-
mands:
g Go to the first 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, boolean
unique- Sel, int highlight, const char* done)
StringBrowser(const char* name, ButtonState*, int, int,
boolean, int, const char*)
Create a new StringBrowser object. The String-
Browser 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 high-
character in the string done will make the String-
Browser stop interpreting keyboard events; the But-
tonState 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 Replace(const char* string, int index)
Replace the string at position index with string.
StringBrowser makes a copy of the string for inter-
nal use. This operation does nothing if the index
supplied is not valid.
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 subse-
quent 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 String-
Browser.
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
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 disal-
lowed.
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.
boolean Selected(int n)
Return whether the nth string has been selected.
SEE ALSO
Interactor(2I), Button(3I)
Man(1) output converted with
man2html