Provided by: ivtools-dev_2.0.11d.a1-1build4_amd64 bug

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 connection 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 immediate = 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 unexecuted to support arbitrary level undo  and  redo.   For
              example,  after a viewer executes the command that a tool generates by interpreting
              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 corresponding
              future history.  Redo re-executes the future i commands and moves them to the past.
              Note  that  calling  Redo without a preceding 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 (modified 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)