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)