A Geometry is a general term for the specification
fragments and framework interfaces GeometryItem, GeometryDescriptorItem
and GeometryDescriptor. Although these names might seem confusing now,
you will understand them better as we explain them one by one.
A GeometryItem defines a basic, atomic geometric shape, such as
a line, rectangle, ellipse, polygon or label. These items are created in a
geometry.xml or similarly named file and customized with attribute
parameters. These attributes define specific visual aspects of the geometry
item and vary depending on the items basic type. New types may be introduced
by applications.
Once a GeometryItem has been defined, it can be referenced by
any number of composites, which group items into new geometry entities of
type GeometryDescriptor. This separation of items and composites
allows you to easily attain a consistent look and feel for all of your repository
elements by centralizing and reusing one or more GeometryItem
definitions.
Every GeometryItem consists of a name, a type and a list of
optional attributes.
Instances of this class are usually configured in a xml file
that is loaded and parsed by a GeometryPool singleton. A minimal
definition of a GeometryItem looks like this:
<!-- A Minimal Item --> <list name="GeometryItem"> <attribute name="Name" value="GEOMETRY_ITEM_NAME"/> <attribute name="Type" value="GEOMETRY_ITEM_TYPE"/> [..] </list>
The following list provides you with the different GeometryItem
implementations that are currently supported, as well as the attributes
for each. Please note that these implementation names in bold are simply
aliases for the actual Java® classes that are instantiated.
Rectangle: Specifies a rectangular graphical shape .
The following table describes the attributes which may be configured in a
geometry.xml file. For each attribute listed, a corresponding setter and
getter method is available for runtime Rect2D configuration.
| Name | Value Type | Description |
|---|---|---|
| RoundEdges | Boolean | If set to true, the rectangle will be displayed with rounded edges. |
| ArcWidth | Integer |
Defines the width of the rounded edges. The ArcWidth must be given in units
of the CoordinateSystem the rectangle lies within.
|
| ArcHeight | Integer |
Defines the height of the rounded edges. The ArcHeight must be given in units
of the CoordinateSystem the rectangle lies within.
|
Ellipse: Specifies an elliptical graphical shape that has no configurable geometrical attributes.
Polygon: Specifies a polygonal graphical shape that has no configurable geometrical attributes.
Label: Specifies a textual graphical shape that exposes the following geometrical attributes:
| Name | Value Type | Description |
|---|---|---|
| Text | String | Specifies the text that should be initially displayed. |
| FontUnit | String Constant |
Specifies the unit that should be used to measure the font.
The following constants are currently supported:
Point, Object.
|
| LineShortening | Boolean | Specifies whether the label lines should be shortened, which means that characters extending past the label boundaries are truncated. |
| SizeAdjustment | String Constant |
Specifies the size adjustment mode of the label. The following constants
are currently supported:
None,
LineCount,
LineLength,
LineCountAndLength.
|
Element:
Here a GeometryDescriptor may be used as an item as well so that
hierarchies can be built up. Note that this type of GeometryItem
is translated into a CompositeGroup
object at runtime.
| Name | Value Type | Description |
|---|---|---|
| ElementName | String | The name of the referenced GeometryDescriptor. |
Port: Specifies a VisualPort for a VisualNode.
This GeometryItem is only supported by the Graph API.
| Name | Value Type | Description |
|---|---|---|
| DenotationName | String | Specifies the name of the port. |
| DenotationIntervalBegin | Double | Specifies the begin of the interval the port should except incoming and outgoing edges. The value must be given in degrees. Note that this attribute is used by a graph layout. |
| DenotationIntervalEnd | Double | Specifies the end of the interval the port should except incoming and outgoing edges. The value must be given in degrees. Note that this attribute is used by a graph layout. |
In summary, a GeometryItem for a rectangle with rounded edges would
be defined in this manner:
Example 3.2. GeometryItem for rectangle with rounded edges
<list name="GeometryItem"> <attribute name="Name" value="RoundedRect"/> <attribute name="Type" value="Rectangle"/> <set name="Attributes"> <attribute name="RoundEdges" type="Boolean" value="true"/> <attribute name="ArcWidth" type="Integer" value="75"/> <attribute name="ArcHeight" type="Integer" value="75"/> </set> </list>
A GeometryDescriptorItem represents the first level of
GeometryItem (aka "basic item") reuse. This interface
exists because basic items will be referenced by one or more composites.
Moreover, basic items do not specify any coordinate data for the objects
that aggregate and draw them. This makes perfect sense. A composite will
need to position basic items relative to one another. In most cases,
drawing individual items in the context of a composite will not always
begin in the upper left-hand corner of a composites coordinate system.
To make things perfectly clear, a GeometryDescriptorItem
represents an association between a single GeometryItem
(atomic geometry, basic item) and a single GeometryDescriptor.
A GeometryDescriptorItem element is embedded inside a
<DescriptorItem> tag inside the geometry.xml configuration file.
Each and every GeometryDescriptorItem references a particular
GeometryItem by name and includes additional coordinate data
inside one or more child <attribute> tags.
Every GeometryDescriptorItem, embedded inside a parent
GeometryDescriptor element, consists of its unique name,
the name of the referenced GeometryItem as well the drawing
coordinates within the composite.
A minimal specification for a GeometryDescriptorItem is this:
<!-- a minimal geometry descriptor --> <list name="DescriptorItem"> <attribute name="Name" value="GEOMETRY_DESCRIPTOR_ITEM_NAME"/> <attribute name="GeometryItemName" value="REFERENCED_GEOMETRY_ITEM_NAME"/> <list name="Coordinates"> <attribute name="Coordinate" value="X_COMPONENT, Y_COMPONENT"/> <attribute name="Coordinate" value="X_COMPONENT, Y_COMPONENT"/> [...]
A single coordinate of a GeometryDescriptorItem specifies a single point of
the basic graphical object it represents. Such a coordinate is defined in form of an
attribute whose value represents the coordinate value. The definition looks like this:
<attribute name="Coordinate" value="X_COMPONENT, Y_COMPONENT" />
As you can see, the attribute contains two values separated by a comma. The first value part holds the value for X and the second value part holds the value for Y. A well-defined coordinate would therefore look like this:
<attribute name="Coordinate" value="100, 100" />
The coordinates of a GeometryDescriptorItem are given in the units of the
GeometryDescriptor that contains it.
A GeometryDescriptor represents a grouping of one or more basic
items of type GeometryItem. Each aggregated item is represented
as a uniquely named GeometryDescriptorItem.
Each GeometryDescriptor definition consists of a name, a type, a
CoordinateSystem and, of course, a list of atomic parts of type
GeometryDescriptorItem. The Type attribute can be one
of the following string enumerations: Composite, CompositeLine
or CompositeGroup.
A basic definition of a GeometryDescriptor looks like this:
<!-- a minimal geometry descriptor -->
<list name="GeometryDescriptor">
<attribute name="Name" value="GEOMETRY_DESCRIPTOR_NAME"/>
<attribute name="Type" value="GEOMETRY_DESCRITPOR_TYPE"/>
<list name="CoordinateSystem">
<attribute name="ScaleX" value="MINIMUM_VALUE, MAXIMUM_VALUE" />
<attribute name="ScaleY" value="MINIMUM_VALUE, MAXIMUM_VALUE" />
</list>
<!-- optional attributes of the geometry descriptor -->
<set name="Attributes">
<attribute name="ATTRIBUTENAME"
type="ATTRIBUTETYPE"
value="ATTRIBUTEVALUE" />
[...]
</set>
<list name="DescriptorItems">
<list name="DescriptorItem">
[...]
</list>
</list>
</list>
The “Name” attribute is used later to locate the
GeometryDescriptor instance. When creating a Composite, for example,
a GeometryDescriptor can be applied by first retrieving it from a
GeometryPool using this “Name” as the lookup key.
The following lists show the GeometryDescriptor types that are
currently supported and their attributes, if available:
GeometryDescriptor Types & Attributes
CompositeLine:
Definition of a CompositeLine:
| Name | Value Type | Description |
|---|---|---|
| Type | Constant |
Specifies the line type.
The following types are currently supported:
|
| isLabelVisible | Boolean | Specifies whether the label is visible or not. |
| LabelPositioning | Constant |
Specifies the label positioning.
The following positioning types are currently supported:
|
Composite:
Definition of a Composite.
| Name | Value Type | Description |
|---|---|---|
| MinimumSize | Size |
The minimum size of the Composite.
|
CompositeGroup:
Definition of a CompositeGroup.
| Attribute Name | Value Type | Description |
|---|---|---|
| HorizontalBorderToContent | Integer |
The horizontal distance between the border and the elements
inside the CompositeGroup.
|
| VerticalBorderToContent | Integer |
The vertical distance between the border and the elements
inside the CompositeGroup.
|
| Foldable | Boolean |
Specifies whether the CompositeGroup should be foldable or not.
|
| FoldedSize | Size |
The size of the CompositeGroup when folded.
|
| FoldStateButtonSize | Size |
The size of the button the CompositeGroup is folded with.
|
The list of possible implementations and attributes might be extended in the future to accomodate new requirements.
The coordinate system specifies the inner measurement for the object and is
defined by a list within the GeometryDescriptor. An example of such
a list is below:
<list name="CoordinateSystem"> <attribute name="ScaleX" value="MINIMUM_VALUE, MAXIMUM_VALUE" /> <attribute name="ScaleY" value="MINIMUM_VALUE, MAXIMUM_VALUE" /> [...]
As you can see above, the definition is divided into two attributes that define the extensions of the coordinate system in the X and Y directions. Note that the coordinate system; must start at the origin. A well-defined coordinate system looks as follows:
<list name="CoordinateSystem"> <attribute name="ScaleX" value="0, 500" /> <attribute name="ScaleY" value="0, 500" /> [...]
Polygons must not be connected by straight lines only - bezier curves are possible as well. To define such a curve, two additional attributes (geometric constraints) are required:
RefCoordinate: A reference coordinate is used to calculate the curve of the line. For example, a polygon which consists of 3 points and 3 bezier curves requires 6 reference coordinates. For a simple bezier curve, only 2 reference coordinates are needed.
Segment: A segment is a single section in a polygon which uses bezier curves to describe its shape. For each section, you can define which Bezier algorithm should be used to calculate the curve. Available values for this attribute are: 'Bezier' and 'CatmullRom'.
The following GeometryDescriptor defines a cylinder which can be represented in
2D space, using two polygons.
Example 3.3. Complex GeometryDescriptor
<!-- definition of the geometry item -->
<list name="GeometryItem">
<attribute name="Name" value="DefaultPolygon" />
<attribute name="Type" value="Polygon" />
</list>
<!-- definition of the geometry descriptor -->
<list name="GeometryDescriptor">
<attribute name="Name" value="Cylinder"/>
<attribute name="Type" value="Composite"/>
<list name="CoordinateSystem">
<attribute name="ScaleX" value="0, 400" />
<attribute name="ScaleY" value="0, 400" />
</list>
<list name="DescriptorItems">
<list name="DescriptorItem">
<attribute name="Name" value="Cap"/>
<attribute name="GeometryItemName" value="DefaultPolygon"/>
<list name="Coordinates">
<attribute name="Coordinate" value="0, 100"/>
<attribute name="Coordinate" value="400, 100"/>
<attribute name="RefCoordinate" value="0, -33"/>
<attribute name="RefCoordinate" value="400, -33"/>
<attribute name="RefCoordinate" value="400, 233"/>
<attribute name="RefCoordinate" value="0, 233"/>
<attribute name="Segment" value="CatmullRom"/>
<attribute name="Segment" value="CatmullRom"/>
</list>
</list>
<list name="DescriptorItem">
<attribute name="Name" value="Base"/>
<attribute name="GeometryItemName" value="DefaultPolygon"/>
<list name="Coordinates">
<attribute name="Coordinate" value="0, 100"/>
<attribute name="Coordinate" value="400, 100"/>
<attribute name="Coordinate" value="400, 300"/>
<attribute name="Coordinate" value="0, 300"/>
<attribute name="RefCoordinate" value="0, 233"/>
<attribute name="RefCoordinate" value="400, 233"/>
<attribute name="RefCoordinate" value="0, 0"/>
<attribute name="RefCoordinate" value="0, 0"/>
<attribute name="RefCoordinate" value="400, 433"/>
<attribute name="RefCoordinate" value="0, 433"/>
<attribute name="RefCoordinate" value="0, 0"/>
<attribute name="RefCoordinate" value="0, 0"/>
<attribute name="Segment" value="CatmullRom"/>
<attribute name="Segment" value="Bezier"/>
<attribute name="Segment" value="CatmullRom"/>
<attribute name="Segment" value="Bezier"/>
</list>
</list>
</list>
</list>
© 2004, 2005 Tensegrity Software GmbH