StringBrowser - browse and/or select items in a list
#include <InterViews/strbrowser.h>
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.
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.
- StringBrowser(ButtonState*,
int rows, int cols, boolean uniqueSel, int highlight, const char*
done)
- StringBrowser(const
char* name, ButtonState*, int, int, boolean, 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 Replace(const
char* string, int index)
- Replace the string at position index with string.
StringBrowser makes a copy of the string for internal 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 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.
- boolean Selected(int
n)
- Return whether the nth string has been selected.
Interactor(2I), Button(3I)