Styles
Prev Chapter 3. Elements Next

Styles

Styles are used to define the visual appearance of an element. Properties such as a stroke, paint, font and marker can be defined in an XML file. In order to do so, styles make use of so-called Format objects whose classes deal the aforementioned properties. A StyleItem, therefore, contains zero or more stroke, paint, font and/or marker formats within its XML-definition, depending its type and configuration. Please do not feel confused by the redundant “style” attribute found inside most of these Format definitions. A Style can be a collection of Format items described in XML, a runtime object and even an attribute that is part of a Format definition.

Formats

Formats, as they are defined in the GraphicsAPI, define a graphical style used for drawing operations. All formats hold a color attribute that is represented as an int that defines the red, green and blue values of the color as illustrated by the following hexadecimal pattern:

  • 0x00rrggbb

    In this pattern, rr is a placeholder for the red, gg for the green and bb for the blue value of the color. Notice that the alpha channel is set via the transparency parameter of the Format.

The following Format implementations are defined in the GraphicsAPI:

  • FontFormat

  • PaintFormat

  • StrokeFormat

  • MarkerFormat

FontFormat

FontFormat represents a format for fonts. This format consists of the following attributes:

  • a family

  • a size

  • a weight

  • a color

  • a flag that indicates italic illustration

  • a flag that indicates underlined illustration

  • a flag that indicates strikethrough illustration

The family attribute defines the font family. The family of the font is sometimes also called the name of the font. The available families are system dependent because each system has installed its own fonts. This may even differ between several installations of the same system.

The size attribute defines the size of the font. This value is not given in device coordinates. Moreover it is dependent on the context the font lies within.

The weight attribute defines the weight the font is drawn with. At the actual state of development the font supports only the NORMAL (or PLAIN) and BOLD weights.

The color attribute defines the color the font is drawn with. The color is represented by an int that defines the values for the red, green and blue components as illustrated by the following hexadecimal pattern: 0x00rrggbb where rr stands for the red component, gg stands for the green component and bb stands for the blue component of the color.

The italic flag indicates whether the font is illustrated italic or not.

The underlined flag indicates whether the font has a line below each letter or not.

The strikethrough flag indicates whether each letter is crossed by a line or not.

Since the FontFormat is an object that is frequently used within the graphics framework and all frameworks that use the graphics framework FontFormats are subject of pooling. The pooling of the FontFormat instances is being done by the FormatPool. To get more informations about this class take a look at the documentation about the FormatPool.

In order to pool a FontFormat it has to be immutable because maybe many objects have a reference on the same FontFormat and modifying the FontFormat will affect all these objects.

For the pooling also an unique expression is needed so that a FontFormat can be surely identified. The unique expression is called the canonical description. This canonical description is made up of the attributes a FontFormat consists of and it can be gained by getCanonicalDescription.

A FontFormat can only be created by using the parseFontFormat(String) method to ensure a correct pooling behavior. You can obtain the canonical description by calling the on of the static methods called getCanonicalDescription().

  • FontFormat parseFontFormat(String)

    Parses the given font format description and returns an instance of a FontFormat. The instance is pooled if necessary. If the given font format description is not valid, a FontFormatParseException is thrown. The String "family=Arial, size=50, weight=400, color=-16777216, italic=false, underline=false, strikethrough=false" is an example for a valid canonical description.

  • FontFormat parseFontFormat(int, int, String, int, boolean, boolean, boolean)

    Parses the given font format and returns an instance of a FontFormat. The instance is pooled if necessary.

A FontFormat consists of the following attributes:

  • Font Family The available families are system-dependent because each system has its own fonts installed. This may even differ between several installations of the same system. Arial is an example of a font family name.

  • Size Not surprisingly, the Size attribute defines the font size. This value is not given in device coordinates but depends on the context the font is used within.

  • Weight Possible values for this attribute range from THIN to NORMAL to HEAVY. At the time of writing, only the THIN and NORMAL weights are supported.

  • Color The foreground color of the font. It follows the pattern scheme 0x00rrggbb presented before.

  • A flag that indicates italic illustration

  • A flag that indicates underlined illustration

  • A flag that indicates strikethrough illustration

If you do not require explicit configuration, you should use the font defined by the constant DEFAULT_FONT_FORMAT of class FontFormat. In the Tensegrity's GraphDemo Application, you can configure a font in a runtime dialog box. This dialog contains controls for all discussed attributes:

Figure 3.2. Font Dialog Box

Font Dialog Box

PaintFormat

PaintFormat represents a format for area fillings. This format consists of the following attributes:

  • a style

  • a background color

  • a foreground color

  • a gradient type

  • a pattern type

  • a flag that indicates transparency

  • a value for the transparency

The style attribute defines the fashion the area is filled out. The different styles PaintFormat provides are as follows.

  • FILL_INVISIBLE

  • FILL_SOLID

  • FILL_GRADIENT

  • FILL_PATTERN

  • FILL_TEXTURE

The background color attribute defines the background color for the area filling. It is used with the following styles.

ConstantDescription
FILL_SOLIDthe color the area is filled with
FILL_GRADIENTthe first color used to render the gradient
FILL_PATTERNthe background color for the pattern

The background color is represented by an int that defines the values for the red, green and blue components as illustrated by the following hexadecimal pattern: 0x00rrggbb where rr stands for the red component, gg stands for the green component and bb stands for the blue component of the color.

The foreground color attribute defines the foreground color for the area filling. It is used with the following styles:

ConstantDescription
FILL_GRADIENTthe second color used to render the gradient
FILL_PATTERNthe color used for the pattern

The foreground color is represented by an int that defines the values for the red, green and blue components as illustrated by the following hexadecimal pattern: 0x00rrggbb where rr stands for the red component, gg stands for the green component and bb stands for the blue component of the color.

The gradient type attribute defines the type of the gradient the area is filled with. To get more informations about gradients and what types of gradients are selectable see the documentation of the Gradient class. Notice that the gradient type attribute is only used when the style of the PaintFormat is set to FILL_GRADIENT.

The pattern type attribute defines the type of the pattern the area is filled with. To get more informations about patterns and what types of pattern are selectable see the documentation of the Pattern class. Notice that the pattern type attribute is only used when the style of the PaintFormat is set to FILL_PATTERN.

The transparent flag indicates whether the filling of the area should be transparent or not.

The transparency value attribute defines the value of transparency for the area filling. This value is given in percent where zero percent means that the filling is not transparent and one hundred percent means that the filling is completely transparent.

Since the PaintFormat is an object that is frequently used within the graphics framework and all frameworks that use the graphics framework PaintFormats are subject of pooling. The pooling of the PaintFormat instances is being done by the FormatPool. To get more information about this class take a look at the documentation about the FormatPool.

In order to pool a PaintFormat it has to be immutable because maybe many objects have a reference on the same PaintFormat and modifying the PaintFormat will affect all these objects.

For the pooling also an unique expression is needed so that a PaintFormat can be surely identified. The unique expression is called the canonical description. This canonical description is made up of the attributes a PaintFormat consists of and it can be gained by getCanonicalDescription.

A PaintFormat provides the following attributes:

  • Fill Style Five main fill style constants are defined in class PaintFormat: FILL_INVISIBLE, FILL_SOLID, FILL_GRADIENT FILL_PATTERN and FILL_TEXTURE

  • Background Color The background color is used for all different types and is the main color of a PaintFormat.

  • Foreground Color This attribute is only needed if the PaintFormat style is set to FILL_GRADIENT or FILL_PATTERN.

  • Gradient Type The Gradient class defines a way to fill an enclosed area with a linear gradient pattern. There are various gradient types and each is defined by a constant. For example, if you choose gradient type RIGHTLEFT with a background color c1 and a foreground color c2, the color of the connecting line from the left to the right of the area will be proportionally changed from c1 to c2. The following picture shows an example of a gradient with type RIGHTLEFT with foreground color “black” and background color “white”.

  • Pattern Type Class Pattern defines a way to fill a closed area with a pattern. As the name implies, the foreground color defines the color that is used to draw the pattern and the background color defines the color that is used to draw the pattern background. It is not possible to create an instance of this class but the API provides some predefined patterns. These patterns can be retrieved by type by calling method getPattern(type). The following diagram shows all currently available pattern types. All listed patterns have a matching constant defined in class Pattern.

  • Transparency flag A boolean flag indicating whether the PaintFormat is transparent or not.

  • Transparency A value for the amount of transparency, if transparency is enabled. This value is given as a percentage. A value of 0 for the transparency means that the PaintFormat is completely opaque and a value of 100 means that it is completely transparent.

The PaintFormat Dialog of Tensegrity's GraphDemo Application contains controls for all discussed attributes:

Figure 3.3. Paint Dialog

Paint Dialog

StrokeFormat

The StrokeFormat class represents a format for lines. This format consists of the following attributes:

  • a style

  • a weight

  • a color

  • a custom pattern

The style attribute defines the pattern the line is drawn with. The different styles StrokeFormat provides are as follows:

  • STYLE_INVISIBLE

  • STYLE_CONTINUOUS

  • STYLE_DASH

  • STYLE_DASHDOT

  • STYLE_DASHDOTDOT

  • STYLE_DOT

  • STYLE_CUSTOM

The weight attribute defines the thickness the line is drawn with. It can be freely chosen and is given in device units. The weight is used for each of the different styles the StrokeFormat provides.

The color attribute defines the color the line is drawn with. The color is represented by an int that defines the values for the red, green and blue components as illustrated by the following hexadecimal pattern: 0x00rrggbb where rr stands for the red component, gg stands for the green component and bb stands for the blue component of the color.

The custom pattern attribute defines the pattern of the stroke by setting the length of the segments that should be drawn or skipped.

Since the StrokeFormat is an object that is frequently used within the graphics framework and all frameworks that use the graphics framework StrokeFormats are subject of pooling. The pooling of the StrokeFormat instances is being done by the FormatPool. To get more informations about this class take a look at the documentation about the FormatPool.

In order to pool a StrokeFormat it has to be immutable because maybe many objects have a reference on the same StrokeFormat and modifying the StrokeFormat will affect all these objects.

For the pooling also an unique expression is needed so that a StrokeFormat can be surely identified. The unique expression is called the canonical description. This canonical description is made up of the attributes a StrokeFormat consists of and it can be gained by getCanonicalDescription.

An instance of class StrokeFormat can only be created by using the parseStrokeFormat(String) method to ensure a correct pooling behavior. You can obtain the canonical description by calling the on of the static methods called getCanonicalDescription().

A StrokeFormat is usually applied to a Primitive by calling the setStroke(StrokeFormat) method.

As with all formats, you can configure a StrokeFormat inside a Dialog box in Tensegrity's GraphDemo Application:

Figure 3.4. Stroke Dialog

Stroke Dialog

MarkerFormat

A MarkerFormat is a somewhat special format: It defines the appearance of line endpoints. This format consists of the following attributes:

  • a type

  • a size

  • a stroke

  • a paint

The type attribute defines the overall appearance of a marker. More than 20 different marker types are defined in class MarkerFormat. The appearance of these types is shown in the following image:

The different types provided are as follows:

ARROW_SMALLFILLED

ARROW_MEDIUMFILLED

ARROW_LARGEFILLED

ARROW_SMALLFILLED_LONG

ARROW_MEDIUMFILLED_LONG

ARROW_LARGEFILLED_LONG

ARROW_SMALLFILLED_HALF

ARROW_MEDIUMFILLED_HALF

ARROW_LARGEFILLED_HALF

ARROW_SMALLFILLED_HALFLONG

ARROW_MEDIUMFILLED_HALFLONG

ARROW_LARGEFILLED_HALFLONG

ARROW_SMALLNOTFILLED

ARROW_MEDIUMNOTFILLED

ARROW_LARGENOTFILLED

ARROW_SMALLNOTFILLED_LONG

ARROW_MEDIUMNOTFILLED_LONG

ARROW_LARGENOTFILLED_LONG

SQUARE

DIAMOND

INVISIBLE

VERTLINE

The size attribute defines the size of the marker. It can be freely chosen and is given in coordinate system units.

The stroke attribute is represented by a StrokeFormat and defines the stroke the marker is surrounded by.

The paint attribute is represented by a PaintFormat and defines the filling of the marker.

Since the MarkerFormat is an object that is frequently used within the graphics api and all apis that use the graphics api MarkerFormats are subject of pooling. The pooling of the MarkerFormat instances is being done by the FormatPool. To get more informations about this class take a look at the documentation about the FormatPool.

In order to pool a MarkerFormat it has to be immutable because maybe many objects have a reference on the same MarkerFormat and modifying the MarkerFormat will affect all these objects.

For the pooling also an unique expression is needed so that a MarkerFormat can be surely identified. The unique expression is called the canonical description. This canonical description is made up of the attributes a MarkerFormat consists of and it can be gained by getCanonicalDescription.

A MarkerFormat can only be created by using the parseMarkerFormat(String) method to ensure a correct pooling behaviour. You can obtain the canonical description by calling the on of the static methods called getCanonicalDescription().

A MarkerFormat is usually applied to a Primitive (e.g. Line2D, Polyline2D) by calling methods like setMarkerBegin(MarkerFormat) or setMarkerEnd(MarkerFormat).

Format Pooling

Since all Format implementations are frequently used within the GraphicsAPI, all objects of type Format are subject to pooling by class FormatPool. Format objects must be immutable because many objects may reference the same pooled instance.

An unique expression is needed to unambiguously identify a Format, which is referred to as a canonical description of the pooled object. This description is pieced together using the prevailing attributes of a Format object, which can be retrieved by calling the getCanonicalDescription() method.

StyleItem

A StyleItem consists of a name and type description followed by a list of attributes defining the border, fill and/or font. The type of a StyleItem is necessary to distinguish between various styles and their dedicated primitives. Valid types are:

  • Line

  • Rectangle

  • Ellipse

  • Polygon

  • Label

The attributes of a StyleItem are definitions for fill, font and border formats. While the definition for a border is mandatory, fill and font format definitions are optional.

A minimalistic StyleItem looks like:

Example 3.4. Minimum StyleItem

<list name="&STYLEITEM;">
 <attribute name="Name" value="CompanyPolygonStyle"/>
 <attribute name="Type" value="Polygon"/>
 <set name="Attributes">
  <set name="Border"/>
 </set>
</list>

Such an item would consist of the default border and no further definition for fill and font. A StyleItem with a black-and-white right-to-left gradient fill would look like:

Example 3.5. StyleItem with a black-and-white right-to-left gradient fill

<list name="StyleItem">
 <attribute name="Name" value="MySampleItem"/>
 <attribute name="Type" value="rectangle"/>
 <set name="Attributes">
  <set name="Border"/>
  <set name="Fill">
   <attribute name="style" value="gradient"/>
   <attribute name="gradienttype" value="rightleft"/>
  </set>
 </set>
</list>

Format Definition

Basically, formats are used to define the non-geometrical appearance of a basic geometrical object. The following table gives an overview of the supported formats and their attributes:

  • StrokeFormat: A stroke format is used to define the visual appearance of a line.

    AttributeTypeDescription
    styleConstant The style constant defines whether the line is continuous or has a pattern. The following styles are currently supported:

    • Invisible

    • Continuous

    • Dash

    • Dashdot

    • Dashdotdot

    • Dot

    • Custom

    colorColorDefines the color of the line.
    weightInteger Defines the thickness of the line. Valid values are integers between 0 and 10 (inclusive).

  • PaintFormat: A paint format is used to define an area fill.

    AttributeTypeDescription
    styleConstant The style constant defines how to fill an area. The following styles are currently supported:

    • None

    • Solid

    • Gradient

    • Pattern

    • Texture

    backgroundColorDefines the background color.
    foregroundColorDefines the foreground color.
    gradienttypeConstant The gradienttype constant defines what type of gradient should be used to fill an area. Note that this attribute depends on setting the format style to Gradient. The following gradient types are currently supported:

    • Rightleft

    • Verticalcenter

    • Topbottom

    • Horizontalcenter

    • Up

    • Upcenter

    • Down

    • Downcenter

    • Leftbottom

    • Rightbottom

    • Lefttop

    • Righttop

    • Centersquared

    • Centercircle

    • Lefttopcircle

    • Righttopcircle

    patterntypeConstant The patterntype constant defines what type of pattern should be used to fill an area. Note that this attribute depends on setting the format style to Pattern. The following pattern types are currently supported:

    • Solid

    • Grey75

    • Grey50

    • Grey25

    • Grey16

    • Grey8

    • Horizontal

    • Vertical

    • Down

    • Up

    • Checker

    • Semigrey75

    • Lighthorizontal

    • Lightvertical

    • Lightdown

    • Lightup

    • Grid

    • Chrisscross

    texturekeyString The texturekey is used internally to markup texture images. This is the key to retrieve the raster from the ImagePool, if it has been loaded before. You can also use this key to load the image into the pool. To do so, this has to be a relative or absolute path to the image file you want to load and has to be parseable to a file or web url. (e.g. /home/usr/images/tile.gif, C:\Documents and Settings\tile.gif, http://www.CompanyWebsite.com/logo.png, resource/icon/logo.png). See texturekeyreferenceclass!
    texturekeyreferenceclassString This is the reference class used to load the image file from the application resources when using a relative path in the texturekey attribute. e.g. texturekey = "resource/icon/logo.png" texturekeyreferenceclass = "com.tensegrity.graphdesigner.GraphDesigner" (Where resource is a subfolder below the folder GraphDesigner lies in)
    transparencyInteger Defines the fill transparency as a percentage, such that 100% specifies a completely transparent fill.
    transparentBoolean Defines whether transparency is active or not.

  • FontFormat: A font format is used to define the appearance of text.

    AttributeTypeDescription
    familyStringDefine the type of font that should be used.
    colorColorDefines the color of the text.
    sizeIntegerDefines the size of the text.
    italicBooleanDefines whether the text should be in italic or not.
    underlineBooleanDefines whether the text be underlined or not.
    strikethroughBooleanDefines whether the text be strikethrough or not.

  • MarkerFormat: A marker format is used to define the arrows at the end of a line.

    AttributeTypeDescription
    typeConstant The style constant defines whether the line is continuous or has a pattern. The following styles are currently supported:

    • Invisible

    • Continuous

    • Dash

    • Dashdot

    • Dashdotdot

    • dot

    sizeIntegerDefines the color of the line.
    border(attribute)set Defines the border of the arrow and follows the rules for the definition of a StrokeFormat mentioned above.
    fill(attribute)set Defines the fill of the arrow and follows the rules for the definition of a PaintFormat mentioned above.

Definition Of Colors

Color Definition: Some of the formats listed above require a color definition within their attributes. There are several ways to do this.

  • One can define the color directly through its comma separated rgb value, which looks like: 255, 0, 0 (red)

  • One can define the color directly through its hexadecimal rgb value, which looks like: #FF0000 (red)

  • One can choose a color through one of the predefined colors, which are black, white or gray, red, pink, orange, yellow, green, magenta, cyan, blue). Each color (except black and white) can be altered by prepending light or dark (for example: lightpink, darkorange, etc.).

For instance, the definition of a color can look like: 

 <attribute name="color" type="Color" value="lightcyan"/>
 <attribute name="color" type="Color" value="#FFAAFF"/>
 <attribute name="color" type="Color" value="12, 145, 23"/>]]>

Default Attribute Values

Default Values: To simplify the definitions of format attributes, users only have to specify those attributes which differ from the default settings, which exist for each Format.

The default definition for a Border is: weight: 1, color: black and style: continuous.

The default definition for Font is: size: 8, weight: normal, family: dialog, color: black, italic/underline/strikethrough: false

The default definition for Fill is: style: solid, background: white, foreground: black, gradienttype: rightleft, pattern: solid, transparency: 50, transparent: false.

StyleDescriptorItem

A StyleDescriptorItem represents another level of abstraction in the definition of a complete style for a Repository element. It is needed because of the following issues:

  • A StyleItem has to be associated with a corresponding GeometryItem. Because they can be used within many StyleDescriptor objects, this cannot be done directly. The association has to be done with a StyleDescriptorItem.

The minimal form of a StyleDescriptorItem looks like below:

Example 3.6. Minimal StyleDescriptorItem

<!-- a minimal style descritptor item -->
<list name="DescriptorItem">
  <attribute name="StyleItem" value="STYLE_DESCRIPTOR_ITEM_NAME"/>
</list>

StyleDescriptor

StyleDescriptor elements combine various StyleItems. These items are later applied to the dedicated GeometryDescriptor. A StyleDescriptor lets you assign single StyleItem to GeometryItem objects (it consists of lists of GeometryItems). A StyleDescriptor consists of 3 attributes:

  • Name

  • Type

  • List of StyleItems

The name of the descriptor is later used to identify the descriptor. Use a human-readable string to ease to the overall readability.

The type parameter defines the descriptor to be used. It must be one of

  • Composite

  • CompositeLine

  • CompositeGroup

A minimum StyleDescriptor might look like this: 

 <!-- A Sample StyleItem used in the Descriptor -->
 <list name="StyleItem">
   <attribute name="Name" value="DefaultRectangleStyle"/>
   <attribute name="Type" value="Rectangle"/>
   <set name="Attributes">
     <set name="Border"/>
     <set name="Fill">
       <attribute name="style" value="pattern"/>
       <attribute name="foreground" type="Color" value="#FF01A1"/>
       <attribute name="background" type="Color" value="darkorange"/>
       <attribute name="patterntype" value="grey75"/>
     </set>
   </set>
 </list>

 <!-- the Descriptor -->
 <list name="StyleDescriptor">
   <attribute name="Name" value="CompanyRectangle"/>
   <attribute name="Type" value="Composite"/>
   <list name="StyleItems">
     <attribute name="StyleItem" value="DefaultRectangleStyle"/>
   </list>
 </list>

© 2004, 2005 Tensegrity Software GmbH

Prev Up Next
Geometries Home | ToC Rules