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)