Provided by: ivtools-dev_1.2.11a1-11_amd64 bug

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, 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)