The diagram canvass package contains classes that support a Diagram canvass GUI component.  

Contents

Overview
Creating a Diagram Canvass
Canvass Objects
Adding Canvass Objects to the canvass
Canvass Grouping Objects
Canvass lines

Overview

The diagram canvass package contains classes that support a Diagram canvass GUI component.  

Creating a diagram canvass

A new diagram canvass is created such:

DiagramCanvas myNewCanvass = new DiagramCanvass();

It extends GUIComponent, which in turn extends JPanel, so can be added to any layout manager or JComponent.  When created the canvass has nothing on it.

Canvass Objects

Canvass objects are the items which can be added to the diagram canvass. The canvass Object class is an abstract class that is implemented by:

• uk.co.agena.minerva.guicomponents.diagramcanvas.CanvassLine, a simple line with and end and start coordinate.
• uk.co.agena.minerva.guicomponents.diagramcanvas.CanvassShape, a simple shape, E.G. square, rectangle, circle, ellipse.
• uk.co.agena.minerva.guicomponents.diagramcanvas.CanvassLabel, a label on which text can be placed, this inherits from canvass shape.
  

The canvass objects specified above are referred to as base canvass Objects.  In that they are simple shapes or lines. more complex canvass objects contain groups of canvass objects (see canvass objects grouping) which form more complex shapes. As such the word base is used in this context to distinguish between these two types of canvass object.

Canvass Objects all have a shape attribute, inherited from CanvassObject. When a canvass object (line, shape, or label)  is instantiated its shape must be passed into its constructor.  The shape is of type import java.awt.Shape;  It is recommended that you use the following child classes of shape when instantiating Canvass Objects (as these have been thoroughly tested):

Note that the java.awt.Shape object inherently has a size and position (x,y,width,height), which are used to determine the canvass objects starting position and size. In the case of the java.awt.geom.Line2D you must specify a start and end coordinate (x1,y1,x2,y2). The properties of these objects can be changed later by accessing the shape via the canvassobject in the API, or manipulation by the user of the canvass at runtime.

Adding canvass objects to the canvass

New objects can be added to the diagram canvass by instantiating a new canvass object, then using the add Canvass Object method on the canvass itself. It is done thus:

DiagramCanvas c = new DiagramCanvass();
CanvassObject co = new CanvassShape(new Rectangle2D.Double(300,300,80,80))
c.addNewCanvassObject (co);

Canvass Object Groupings

A CanvassObjectGrouping is a canvass object that contains a set of canvass objects. The objects can be base objects or other canvass object groupings.  They are important in the diagram canvass as they are used as a mechanism for grouping canvass object together, such that the user perceives them as just a single object.  This works in a similar fashion to any other drawing tools (such as PowerPoint or Visio) where object can be grouped and ungrouped.

It is useful to note that the Diagram canvass itself contains a list of canvass object groupings, not base canvass objects.  Thus when a new canvass object is added (see here for more details) a new canvass grouping is created to which the specified object is added, before the grouping is added to the canvass.  For example if you were to create a new canvass and add 3 base objects, the diagram canvass would actually create 3 groupings, adding a single base object to each, then add the groupings to the canvass.

Canvass objects groupings can be joined (using the DiagramCanvass.joinCanvassObjectGroupings method) and decomposed (using DiagramCanvass.decomposeDiagramCanvassObjectGrouping) vias the diagram canvass on which they reside. 

As touched on earlier it is possible to add other canvass grouping objects to a grouping.  This allows a tree structure of groupings to be created, allowing groups within groups.  Since a Canvass Object grouping is also a canvass Object they can be added to a grouping in the same way as a base Canvass Object, thus:

CanvassObjectGrouping.addNewCanvassObject( CanvassObject )

applies equally to:

CanvassObjectGrouping.addNewCanvassObject( CanvassShape )
CanvassObjectGrouping.addNewCanvassObject( CanvassObjectGrouping )

In the same way groupings can be added to the canvass using the same mechanism as you add base canvass objects

Canvass Lines

Canvass lines are Base Canvass Objects They are constructed by parsing in a  java.awt.geom.Line2D. Lines have two important features which are not common to the other objects, firstly they can have arrow heads at ethier end. Arrow heads are attachted by creating an CanvassArrowHead (which is also a canvass object) and attaching it to the relevant end of the line:

CanvassArrowHead cah = new CanvassArrowHead();
CanvassLine cl = new CanvassLine(new Line2D.Double(230,230,300,300));
cl.setEndOfLineArrowHead(cah);

The same can be done for the beginning of the line.  As default the arrow heads are null

Canvass lines can also be anchored to other objects.  When anchored the line end (start or end depending on what was anchored) remains in the center of the target object. Thus if the canvass object to which the line is anchored is moved then the line end also moves. Lines can only be anchored to Base Canvass Objects.  Lines are anchored in the following way:

CanvassLine cl = new CanvassLine(new Line2D.Double(230,230,300,300));
CanvassShape cs =  new CanvassShape(new Rectangle2D.Double(300,300,80,80));
cl.setStartOfLineAnchourObject(cs);

both ends of the line can be anchored.