Unidraw - one-of-a-kind object for coordinating and con-
trolling 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 sys-
tem. It initializes the catalog and other objects, man-
ages editor instances, and defines the application main
loop. It also maintains histories of commands that have
be executed and reverse-executed for each component hier-
archy 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 edi-
tors but after creating a catalog. Below is the main pro-
gram 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 argu-
ments are supplied (except the catalog). To spec-
ify a World instance explicitly, use the second
constructor form.
virtual void Run()
virtual void Quit()
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 multi-
ple consecutive calls do not induce redundant com-
putations. 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 itera-
tor 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 itera-
tor 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 associ-
ated 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 GetCom-
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 com-
ponent (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 com-
mands and moves them to the past. Note that call-
ing 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 speci-
fied.
void ClearHistory(Editor*)
Clear the history associated with the given edi-
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 indi-
cate 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 opera-
tions 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 ele-
ment in an iterator and the command object from the
list element. These are useful in conjunction with
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), state-
vars(3U)
Man(1) output converted with
man2html