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 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 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)