StringEditor - single line interactive string editor
#include <InterViews/streditor.h>
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.
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.
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.
- 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.
- virtual boolean
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.