NAME

       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  StringBrowser  or  by  typing  them  in the
       StringEditor. Like Dialog, 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 relinquishes keyboard focus, the other acquires it: for  example,  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* sample, 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.

PROTECTED OPERATIONS

       StringChooser(ButtonState*, Alignment = Center)
              Construct  a  new  StringChooser  with  the given button state and pop-up alignment
              without creating StringBrowser and StringEditor instances.  This constructor 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 StringBrowser if the StringEditor is focused
              currently,  and vice versa.  Focus actually changes when HandleFocus 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), StringEditor(3I)