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)