StringEditor(3I)					    InterViews Reference Manual 					  StringEditor(3I)

NAME

       StringEditor - single line interactive string editor

SYNOPSIS

       #include <InterViews/streditor.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  char-
       acters.	 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 charac-
	      ter.  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  out-
	      side the StringEditor's bounds.

PROTECTED OPERATIONS

       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.

SEE ALSO

       Interactor(3I), Button(3I)

InterViews							    23 May 1989 						  StringEditor(3I)