StringBrowser - browse and/or select items in a list

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 stringindex 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 selectionindex 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.

Name

       StringBrowser - browse and/or select items in a list

Public Operations

StringBrowser(ButtonState*,introws,intcols,booleanuniqueSel,inthighlight,constchar*done)StringBrowser(constchar*name,ButtonState*,int,int,boolean,int,constchar*)
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.

voidBrowse()
Initiate browsing. Subsequent keypresses will be interpreted as browsing and selection commands
according to the key bindings listed above.

voidInsert(constchar*string,intindex)
Insert string at position index. StringBrowser makes a copy of the string for internal use.

voidReplace(constchar*string,intindex)
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.

voidAppend(constchar*string)
Insert a copy of string after the last string.

voidRemove(intindex)
Remove the string at position index, moving subsequent strings up to fill the gap.

intIndex(constchar*string)
Return the index of the first string that matches string.

char*String(intindex)
Return the string at the given index.

intCount()
Return the total number of strings in the StringBrowser.

voidClear()
Remove all strings from the StringBrowser.

voidSelect(intindex)voidUnselect(intindex)
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.

voidSelectAll()voidUnselectAll()
Select (unselect) all strings. SelectAll does nothing if multiple selections have been
disallowed.

intSelection(intn)
Return the string index of the nth selected string.

intSelectionIndex(intn)
Return the selection index of the nth string.

intSelections()
Return the total number of selected strings.

booleanSelected(intn)
Return whether the nth string has been selected.