InterViews Reference Manual -- StringChooser
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 bool 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 , Dialog , StringBrowser , StringEditor
Next: StringEditor
| Prev: StringBrowser
| Up: index
| Top: index