Unidraw(3U)						    InterViews Reference Manual 					       Unidraw(3U)

NAME

       Unidraw - one-of-a-kind object for coordinating and controlling a Unidraw application

SYNOPSIS

       #include <Unidraw/unidraw.h>

DESCRIPTION

       Unidraw applications create a single instance of a Unidraw object, which does several things.  It creates a World, establishing the connec-
       tion to the underlying window system.  It initializes the catalog and other objects, manages editor instances, and defines the  application
       main  loop.   It also maintains histories of commands that have be executed and reverse-executed for each component hierarchy being edited.
       Finally, it cleans up internal state when it is deleted to ensure orderly program termination.

       The Unidraw object must be created before opening any editors but after creating a catalog.  Below  is  the  main  program  for	a  typical
       Unidraw application:

       int main (int argc, char** argv) {
	   AppSpecificCreator creator;
	   Unidraw* unidraw = new Unidraw(
	       new Catalog("appName", &creator),
	       argc, argv, options, properties
	   );

	   unidraw->Open(new AppSpecificEditor);
	   unidraw->Run();
	   delete unidraw;
	   return 0;
       }

PUBLIC OPERATIONS

       Unidraw(
	   Catalog*, int argc, char** argv,
	   OptionDesc* = nil, PropertyData* = nil
       )

       Unidraw(Catalog*, World*)
	      The  first  constructor  form  requires a catalog object and command line argument information.  Other arguments include pointers to
	      PropertyData and OptionDesc arrays.  This constructor creates a World instance, passing whichever of these  arguments  are  supplied
	      (except the catalog).  To specify a World instance explicitly, use the second constructor form.

       virtual void Run()
       virtual void Quit()
	      Run initiates the main loop of the program.  The call to Run returns when Quit is called.

       virtual void Update(boolean immedate = false)
	      Bring  the  screen  up  to  date	with the state of the application's objects.  By default, this involves moving connectors to their
	      proper positions (by calling Solve on the global csolver object) and telling editors to update themselves (by calling  their  Update
	      functions).   Because  Update  may  carry out potentially lengthy operations, Unidraw batches Update calls by default.  This ensures
	      that multiple consecutive calls do not induce redundant computations.  To force an immediate update, simply call Update(true).

       virtual void Open(Editor*)
       virtual boolean Opened(Editor*)
	      Open inserts an editor into the world, making it visible on the display.	The user positions the editor's window by default.  Opened
	      returns whether an editor has been opened already.

       virtual void Close(Editor*)
       virtual void CloseDependents(Component*)
       virtual void CloseAll()
	      Close closes a specified editor, removing it from the user's view and deleting it.  CloseDependents closes those editors that report
	      a dependence on the given component via their DependsOn operation. CloseAll closes all open editors.  ~Unidraw calls CloseAll.

       void First(Iterator&)
       void Next(Iterator&)
       boolean Done(Iterator)
	      Operations for iterating over the Unidraw object's list of open editors.	First initializes an iterator to point to the beginning of
	      the  list, Next increments the iterator to point to the following editor, and Done returns whether or not the iterator points beyond
	      the first or last editor in the list.

       Editor* GetEditor(Iterator)
	      Return the editor to which an iterator points.

       Editor* Find(Component*)
       Editor* FindAny(Component*)
	      Operations for finding an (or the) editor associated with a given component.  Find searches the list of editors for  the	one  whose
	      GetComponent  operation  returns	the  given  component.	 FindAny returns the first editor in the list whose GetComponent operation
	      returns a component in the same hierarchy as the the given component.

       Catalog* GetCatalog()
	      Return the catalog passed to the constructor.

       World* GetWorld()
	      Return the world object, which the Unidraw object creates when it is instantiated.

       void Log(Command*)
       void Undo(Component*, int i = 1)
       void Redo(Component*, int i = 1)
	      The Unidraw object maintains histories of commands associated with a given component hierarchy.  There are two command histories per
	      hierarchy:  the  past  history and the future history.  These histories normally contain commands that have been executed and unexe-
	      cuted to support arbitrary level undo and redo.  For example, after a viewer executes the command that a tool  generates	by  inter-
	      preting a manipulator, it will record that command in a past history for possible undoing in the future.

	      The  Log operation logs a command, placing it on the past history for the component hierarchy being edited.  Log determines the past
	      that is approprate from the command's editor, which specifies the component (hence the hierarchy) that it is editing.  Undo reverse-
	      executes the last i commands that were logged for a given component's hierarchy and moves them from their past history to the corre-
	      sponding future history.	Redo re-executes the future i commands and moves them to the past.  Note that calling Redo without a  pre-
	      ceding Undo is meaningless; thus calling Log will clear the future history associated with the affected component hierarchy.

       void SetHistoryLength(int)
       int GetHistoryLength()
	      Assign  and  retrieve  the  maximum  command history length.  No more than this many commands can be undone and redone.  The default
	      length is 20.  Older commands are deleted automatically as new commands are logged.

       void ClearHistory(Component* = nil)
	      Clear the past and future for a given component hierarchy, deleting the corresponding commands.  All histories  are  cleared  if	no
	      component is specified.

       void ClearHistory(Editor*)
	      Clear  the  history  associated  with  the  given editor's component if no other editor is editing the same hierarchy.  For example,
	      Unidraw::Close calls this operation to avoid clearing histories when a component hierarchy is being edited in multiple editors.

PROTECTED OPERATIONS

       virtual void Process()
	      Process is called once in the main loop defined by the Run operation.  It does nothing by default.  Subclasses may redefine  Process
	      to carry out any processing that should be done in each pass through the main loop.

       boolean IsClean(Editor*)
	      This  convenience function queries the given editor for a ModifStatusVar instance.  If it has one, then it returns its status (modi-
	      fied or unmodified); otherwise it returns false.

       void Mark(Editor*)
       void Sweep(Editor*)
	      These operations support deferred editor deletion, a mechanism to avoid deleting editors prematurely.  For example, if a command	to
	      close the editor is invoked from a pull-down menu, then the command must not delete the editor, since that will delete the pull-down
	      menu before it has a chance to close.  Thus Close and similar operations do not delete editors directly; instead, they call Mark	to
	      indicate	that  an  editor  should be deleted sometime in the future.  Sweep actually deletes the editors that have been marked.	By
	      default, Unidraw::Run calls Sweep each time an event is handled.

       void DoUpdate()
	      A helper function that performs an immediate update independent of the batching mechanism.

       void GetHistory(Component*, UList*& past, UList*& future)
       void ClearHistory(UList*, int i = 1)
	      Command histories are stored as ULists.  These operations provide a low-level interface to the lists themselves;	the  corresponding
	      public  operations are built on top.  GetHistory returns the past and future lists for a given component, while ClearHistory deletes
	      the first i commands on the given list.

       UList* elem(Iterator)
       Command* command(UList*)
	      Convenience functions for extracting the list element in an iterator and the command object from the list element.  These are useful
	      in conjunction with protected history operations described above.

       boolean updated()
       void updated(boolean)
	      The  first  form	of  this  function  returns  true if there are pending Update(s) to be performed.  The second form sets this value
	      explicitly.

       boolean alive()
       void alive(boolean)
	      The first form of this function returns true if the program is in the run loop defined by Run.  The  second  form  sets  this  value
	      explicitly.

SEE ALSO

       Catalog(3U), Creator(3U), Editor(3U), Interactor(3U), Iterator(3U), Viewer(3I), UList(3U), World(3I), statevars(3U)

Unidraw 							  4 October 1990						       Unidraw(3U)