NAME

       Editor - base class for top-level windows in an application

SYNOPSIS

       #include <Unidraw/editor.h>

DESCRIPTION

       An  editor  provides a complete user interface for editing a component subject.  It unites
       one or more viewers  with  commands  and  tools  that  act  upon  the  component  and  its
       subcomponents.   Editor is an abstract class derived from MonoScene; the Editor class adds
       the protocol for associating tools, commands,  and  viewers  with  the  component(s)  they
       affect.   A  programmer normally derives one or more application-specific editors from the
       Editor base class and defines their appearance with a composition  of  interactors.   Each
       window  of a Unidraw application is usually an instance of an editor subclass designed for
       the editing domain, and it is these windows that the user recognizes  as  the  application
       program.

PUBLIC OPERATIONS

       virtual ~Editor()
              Editors  should not be deleted explicitly if the Unidraw object is used to open and
              close them.  Moreover, Editor subclasses should not explicitly delete the component
              they  edit.  The Unidraw object will delete the editor's component after the editor
              is closed, provided no other editor references the component (or its relatives) and
              the component is not known to the catalog.

       virtual void Open()
       virtual void Close()
              Open informs the editor that it has just become visible and accessible to the user,
              in case it needs to know, and Close signals the editor that it is no longer  needed
              and  should perform any final housekeeping operations.  For example, the editor may
              display a copyright  message  when  it  is  first  opened,  or  it  make  take  the
              opportunity  when  closed  to  warn  the  user  to save a modified component. These
              operations simply notify the editor of a condition and are not  usually  called  by
              the  application;  instead, the application makes editors appear and disappear with
              the Unidraw object, which calls these operations as appropriate.

       virtual void Handle(Event&)
              Editor redefines Handle to interpret key events as  keyboard  equivalents  via  the
              HandleKey  operation  (described  below).   This  is appropriate in the common case
              where the interactor composition that defines  the  editor's  appearance  does  not
              interpret keyboard events.

       virtual void Update()
              By default, the editor's Update operation calls Update on its viewer(s).

       virtual void SetComponent(Component*)
       virtual void SetViewer(Viewer*, int = 0)
       virtual void SetSelection(Selection*)
       virtual void SetKeyMap(Viewer*, int = 0)
       virtual void SetCurTool(Tool*)

       virtual Component* GetComponent()
       virtual Viewer* GetViewer(int = 0)
       virtual KeyMap* GetKeyMap()
       virtual Selection* GetSelection()
       virtual Tool* GetCurTool()
              Assign  and  return  various  objects  managed by the editor.  These operations are
              undefined by default.

              The component is the object that the user edits through the editor.  The editor can
              have  any number of viewers, identified serially.  An editor can maintain a key map
              for defining keyboard equivalents and a  selection  object  for  keeping  track  of
              selected  components  (typically subcomponents of the component being edited).  The
              editor also has a notion of the tool that is currently engaged, that is,  the  tool
              that  would be used if the user clicked in a viewer.  The SetCurTool and GetCurTool
              operations assign and return this tool, respectively.

       virtual StateVar* GetState(const char*)
              The editor may maintain a string-to-state  variable  mapping  to  provide  external
              access  to  any state variables it defines.  The GetState operation returns a state
              variable given an identifying string.  Defining  such  a  mapping  lets  components
              query  the  editor  for  state variables that may affect them without extending the
              editor protocol, potentially allowing  interchange  of  components  from  different
              applications.  This operation returns nil by default.

       virtual void InsertDialog(Interactor*)
       virtual void RemoveDialog(Interactor*)
              Insert  or  remove  an interactor that provides a modal interface, such as a dialog
              box.  By default, these operations insert the dialog into the world as a  transient
              window  centered  atop the editor's canvas.  Subclasses can redefine them to insert
              and remove an interactor (suitably embellished with a border, drop shadow, etc.) as
              needed.   Subclasses should not assume that two InsertDialog operations will always
              be separated by a RemoveDialog  operation;  that  is,  multiple  dialogs  might  be
              visible at once.

PROTECTED OPERATIONS

       Editor()
              You cannot create instances of the Editor class; rather, you define subclasses that
              suit  your  application.   The  constructor   is   thus   protected   to   disallow
              instantiation.

       virtual void HandleKey(Event&)
              Executes  a  command  given a valid keyboard event as defined by the key-to-command
              mapping in the KeyMap object.

       virtual boolean DependsOn(Component*)
              Return whether the editor depends on the given component in any way.   Unidraw  may
              destroy the component if no editor depends on it.

       void SetWindow(ManagedWindow*)
       ManagedWindow* GetWindow()
              Get and set the window associated with the editor.

SEE ALSO

       Catalog(3U),   Command(3U),   Component(3U),  Interactor(3I),  KeyMap(3U),  MonoScene(3I),
       Selection(3U), StateVar(3U), Tool(3U), Unidraw(3U), Viewer(3U), Window(3I), World(3I)