Editor(3U)						    InterViews Reference Manual 						Editor(3U)

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 applica-
       tion 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  compo-
	      nent.  These operations simply notify the editor of a condition and are not usually called by the application; instead, the applica-
	      tion 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  Get-
	      State  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 dif-
	      ferent 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 dia-
	      log 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)

Unidraw 							   30 July 1990 							Editor(3U)