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)

InterViews                                      30 November 1989                               StringChooser(3I)