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  call-
       ing the Edit function) initiates an edit.  Subsequent key-
       board events, which need not be inside  the  StringEditor,
       are interpreted as editing operations on the text.  Click-
       ing outside the StringEdit terminates the edit.  StringEd-
       itor  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 inser-
       tion point between characters.  Dragging across  the  text
       selects  a  range of characters.  A set of control charac-
       ters is mapped into common editing operations.  A  charac-
       ter  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 fol-
       lowing 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  previ-
              ous   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 pre-
              vious 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 left-
       wards 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  direc-
       tion.

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  termi-
              nated 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 calcu-
              lated 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 selec-
              tion 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  exe-
              cuted or a down click occurs outside the StringEdi-

       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  comple-
              tion,  or  an  editor for numeric input might check
              the validity  of  the  string  as  it  is  entered.
              Derived  classes  should redefine the virtual func-
              tion 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)