Deprecated: Function set_magic_quotes_runtime() is deprecated in /storage/content/76/1004576/wiki.jpatch3d.org/public_html/inc/common.php on line 33 Deprecated: Function split() is deprecated in /storage/content/76/1004576/wiki.jpatch3d.org/public_html/inc/auth.php on line 95 Deprecated: Function split() is deprecated in /storage/content/76/1004576/wiki.jpatch3d.org/public_html/inc/common.php on line 743 dev:package_overview [DokuWiki]
 

JPatch code overview

Packages

The JPatch sourcecode is organized in packages and sub-packages. The most important packages are

  • entity
  • boundary
  • control

The design goal was to strictly seperate the user interface from the program logic (this is sometimes called Model-View-Controller architecture).

Instances of classes in the entity package store all the relevant data to represent JPatch models. This includes e.g. the ControlPoint, Curve or Model objects.

The classes in the boundary package represent JPatch’s user interface. Among menus and buttons, there are also classes responsible for rendering JPatch models to the screen and the tools (e.g. the Rotate-Tool) needed to manipulate JPatch models. It is important to note that e.g. the tools don’t manipulate instances of entity classes directly, but use edit-objects instead (see below).

The classes in the control package are used to manipulate JPatch models (i.e. instances of entity classes). This has one big advantage: Every manipulation of an entity instance is encapsulated in an edit object (instances of classes from the control.edit package). These edit objects have two methods: undo and redo. By following the rule that entity classes should not be manipulated directly but only via edit objects, every manipulation automatically becomes undo/redo-able!

The entity, boundary and control packages

entity

All fields usually have either private access, or protected or default access if the class is designed for subclassing. Classes with no (or very few) program logic which are merely ment to store data (Java replacements for C-structures or PASCAL-records) may use public fields.

The classes usually provide accessor methods and some convenient methods to manipulate the entities. The boundary objects usually only access the getter methods of entity classess, while the control objects use setters or other methods too (to manipulate the entities).

boundary

JPatch uses Java’s Swing toolkit. All UI elements are Swing components. The objects responsible for rendering JPatch models are either Swing (lightweight) or AWT (heavyweight) components and are accessed via an Interface. This allows the concrete implementations to be switched, currently a Java2D-, a software- and an OpenGL implementation are available.

The actions (e.g. performed when clicking on a button or selecting a menu-item) are encapsulated in AbstractAction objects and can be found in the boundary.actions package. Actions usually create edit objects to manipulate the model and send them to the UndoManager.

There are two ways how mouse input is processed: Simple operations (like adding ControlPoints) are handled by MouseListeners and MouseMotionListeners (in boundary.mouse). More complex operations are handled by tools (in boundary.tools). Tools do not only provide diverse Mouse(Motion)Listeners, but can also render themselves to the viewports (e.g. the Default- or the RotateTool). Both Tools and Mouse(Motion)Listener don’t modify entity objects directly (at least temporarily), but use edit objects as well.

control

Classes in the control.edit package encapsulate all manipulations of entity classes and are derived from JPatchAbstractUnduableEdit, which provides parameterless undo() and redo() methods. JPatchCompoundEdit can be used to combine several edit objects. It’s redo() method simply calls redo() on all child-edits in the order they were added, and it’s undo() method calls the children’s undo() methods in reverse order. This way it is possible to construct arbitrary complex trees of edit’s - a single operation such as e.g. performed by the Auto-Mirror Tool can create a very complex datastructure, yet it can be undone or redone by simply calling the undo/redo methods of the “root” CompoundEdit. Edits are added to the JPatchUndoManager, which keeps them on a stack. If the maximum depth is reached, the oldest edits will be deleted.

There are also some classes in control.importer which are used to import JPatch models from file. They usually create the entity objects directly (and don’t use edits), so loading a model can’t be undone.

Summary

  • All User-Interface related code should be in the boundary package (or its sub-packages).
  • All manipulations of entities should be done via edit objects. Edits _must_ provide means to undo and redo the manipulation.
 
  dev/package_overview.txt · Last modified: 2005/11/22 10:45