Provided by: ivtools-dev_2.0.11d.a1-1build4_amd64 
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)