InterViews Reference Manual -- StringEditor
NAME
StringEditor - single line interactive string editor
SYNOPSIS
#include <InterViews/stringeditor.h>
DESCRIPTION
StringEditor is an interactor that provides a convenient mouse-based
interactive editor for text strings. It is suitable for incorporation into
other components such as dialog boxes. Clicking inside the StringEditor (or
calling the Edit function) initiates an edit. Subsequent keyboard events,
which need not be inside the StringEditor, are interpreted as editing
operations on the text. Clicking outside the StringEdit terminates the edit.
StringEditor works with either fixed width or proportionally spaced fonts.
EDITING MODEL
Text is selected with the mouse or with the keyboard. A single click of the
left mouse button selects a new insertion point between characters. Dragging
across the text selects a range of characters. A set of control characters is
mapped into common editing operations. A character not specifically associated
with commands is inserted in place of the the current selection, the replaced
text is lost, and the selection becomes an insertion point following the
inserted character. Commands currently defined include the following.
CharacterLeft (^B)
CharacterRight (^F)
BeginningOfText (^A)
EndOfText (^E)
Move the selection one character position to the left or right, or to the
beginning or end of the text.
Erase (^H, DEL)
Delete (^D)
Delete the text of the current selection. If the selection is an insertion
point, delete the previous character (Erase) or the next character (Delete)
instead.
SelectAll (^U)
SelectWord (^W)
Select the entire text, or extend the selection to the left by one whole word.
These commands enable common editing operations to be performed without using
the mouse. For example, to replace the previous word in the text, do a
SelectWord and type the new text.
SCROLLING
Strings that are too long to fit into the StringEditor can be scrolled
horizontally. Middle-clicking inside the StringBrowser initiates ``grab-
scrolling''. While the button is held down, the StringEditor scrolls the text
to follow the mouse position, making it appear as though the user is dragging
the test. Right-clicking engages ``rate-scrolling,'' a joy-stick-like
scrolling interface in which the scrolling rate increases as the user drags the
mouse away from the initial click point. For example, dragging the mouse
rightwards after the initial click scrolls the browser rightwards at an
increasing rate; dragging leftwards thereafter reduces the rate until scrolling
stops entirely at the initial click point. Dragging left beyond this point
makes the browser scroll in the reverse direction.
PUBLIC OPERATIONS
StringEditor(ButtonState*, const char* sample, const char*
done)
Create a new StringEditor object. The ButtonState will be used to communicate
the result of editing operations. An edit of the string will be terminated if
any character in the string done is typed, and the ButtonState will be
set to the terminating character. The shape of the new object is calculated
from the length of the sample string.
void Message(const char* text)
Set the contents of the edit buffer to text.
void Select(int point)
void Select(int left, int
right)
Select an insertion point or a subrange of the edit buffer.
void Edit()
void Edit(const char* text, int left,
int right)
Initiate an edit. Specifying a string and selection range is short hand for
first calling Message and Select with the corresponding parameters.
const char* Text()
Return the current value of the edit buffer. Note that this buffer is owned by
the StringEditor, and that its contents are subject to change. It is the
caller's responsibility to copy the string if the value will be needed in the
long term.
Handle(Event&)
Handle the event, and read and process subsequent events until an Accept or
Cancel command is executed or a down click occurs outside the StringEditor's
bounds.
PROTECTED OPERATIONS
virtual bool HandleChar(char)
void
InsertText(const char* text, int length)
Subclasses of StringEditor can perform additional processing on the edit
buffer. For instance, an editor for file names might do file name completion,
or an editor for numeric input might check the validity of the string as it is
entered. Derived classes should redefine the virtual function HandleChar as
required. HandleChar should return true to indicate that the edit is
completed, or false otherwise. InsertText can be used to insert text into the
edit buffer, replacing any currently selected text.
SEE ALSO
Interactor , Button
Next: StringPool
| Prev: StringChooser
| Up: index
| Top: index