StringChooser - dialog box for choosing items in a list

SYNOPSIS

       #include <InterViews/strchooser.h>

DESCRIPTION

       StringChooser  is  a  dialog  that  manages keyboard focus
       between a StringBrowser and a StringEditor  to  provide  a
       convenient  interface  to selecting strings.  The user can
       select strings either by selecting  them  in  the  String-
       Browser  or  by typing them in the StringEditor. Like Dia-
       log, StringChooser is an abstract class; programmers  must
       derive from StringChooser to add push buttons, etc. and to
       compose them into custom arrangements.

       The user can  focus  keyboard  input  towards  either  the
       StringEditor  or  the  StringBrowser.  To set focus to the
       StringEditor, for example, the  user  left-clicks  in  its
       canvas  to  make  it interpret subsequent keyboard events.
       When either the StringEditor or the  StringBrowser  relin-
       quishes  keyboard  focus, the other acquires it: for exam-
       ple, the user can toggle focus between the two by pressing
       the  tab key repeatedly.  If an entry in the StringBrowser
       is selected when it  loses  focus,  the  (first)  selected
       string will be transferred into the StringEditor.

PUBLIC OPERATIONS

       StringChooser(ButtonState*,  int rows, int cols, const
              char* sam- ple, Alignment)
       StringChooser(const char* name, ButtonState*, int rows,
              int cols, const char* sample, Alignment)
              Construct a new StringChooser with the given button
              state and  pop-up  alignment.   These  constructors
              create  a StringBrowser of the specified size and a
              StringEditor with the  given  sample  string.   The
              StringChooser,  StringBrowser, and StringEditor all
              share the same button state.

       void Select(int point)
       void Select(int left, int right)
       void SelectMessage()
              Select an  insertion  point,  a  subrange,  or  the
              entire edit buffer in the StringEditor.

       void Message(const char* text)
              Set  the contents of the StringEditor's edit buffer
              to text.

       virtual const char* Choice()
              Return the chosen string. The string is returned in
              a static buffer and should be copied before use.

       StringChooser(ButtonState*, Alignment = Center)
              Construct a new StringChooser with the given button
              state and pop-up alignment without creating String-
              Browser and StringEditor instances.  This construc-
              tor should be called in subclasses that  require  a
              specialized  StringEditor or StringBrowser or both.

       void Init(StringEditor*, StringBrowser*)
              Initialize the StringEditor and StringBrowser  that
              StringChooser will use.  This function is useful in
              the constructors of StringChooser  subclasses  that
              require a specialized StringEditor or StringBrowser
              or both.

       virtual void SwitchFocus()
              Prepare to shift  keyboard  focus  to  the  String-
              Browser  if  the StringEditor is focused currently,
              and vice versa.  Focus actually changes  when  Han-
              dleFocus is called (see below).

       virtual boolean CanFocus(Interactor*)
              Return  whether  or not the given interactor can be
              focused.   This  function  is  used  to   determine
              whether  the  StringChooser  should switch focus in
              response to a downclick.

       virtual void HandleFocus()
              Transfer event  reading  to  the  StringBrowser  or
              StringEditor, whichever is the current focus.

       virtual void UpdateEditor()
       virtual void UpdateBrowser()
              Update  StringEditor  and  StringBrowser state when
              the dialog is accepted or in response to  a  change
              in focus.  This function guarantees that the Choice
              operation will return the last choice. By  default,
              UpdateEditor changes the StringEditor's contents to
              match the StringBrowser  selection  (if  any),  and
              UpdateBrowser  clears  out  any selected strings in
              the StringBrowser.

SEE ALSO

       Button(3I),  Dialog(3I),   StringBrowser(3I),   StringEdi-
       tor(3I)