StringBrowser(3I)					    InterViews Reference Manual 					 StringBrowser(3I)

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 sepa-
       rate 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, 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.

SEE ALSO

       Interactor(2I), Button(3I)

InterViews							 30 November 1989						 StringBrowser(3I)