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)