gishur.gui2
Class Painter

java.lang.Object
  |
  +--gishur.gui2.Painter
Direct Known Subclasses:
EdgePainter, FancyPointPainter, GraphElementInfoPainter, InfoPainter, InrectPainter, InvectPainter, LinePainter, LinkPainter, PolygonPainter, RoundNodePainter, RoundPointPainter, SquarePointPainter

public abstract class Painter
extends java.lang.Object

This class is the basic class for all painters. A Painter is a small piece of a DisplayObject, such as a point, a line or other primitives. The concept of painters makes it easier to write complicated DisplayObject plus the bonus to have small reusable components. For instance once written a painter that represents a point, it can be used to draw endpoints of line segments or points of polygon, even it may be used to draw points of graphs. A DisplayObject that uses Painters, will not need to know the exact type of the painter it uses - for instance it's only interested to display a point, no matter how the drawed point looks like. There are conventions that must be met by a particular Painter, but these are only a few - the Painter should make use of the paramters given by the DisplayObject.

Painters are strongly connected to Styles. A Style is a factory for a special type of {link Painter Painters}. In addition the Style can store global informations for all Painters produced by this Style. A Painter can gain access to its Style using the style() method.

In order to write own Styles and Painters, simply create two classes based upon Style/Painter and overwrite the abstract methods. In the case of a Painter these are recalculate(...) and draw(...). recalculate(...) is used to 'format' the Painter. This method should initialize the local variables using the given local informations and the proprties. The draw(...) should efficiently draw this Painter. Make this methods fast! Avoid creation of objects! A Painter itself will be reused. The Style caches unused instances.

To use Painters by a DisplayObject, simply call the createPainter(...) method of its Style, than reshape it using its reshape(...) method and add it to the DisplayObject via DrawObject.addPainter(gishur.gui2.Painter).

Every Painter has got a name and a subtype prefix string. The name is used to identify the Painter for activation and element transformation. The subtype prefix is used by a PropertyStatusReader for reading properties correctly.

Properties Summary
Key Value Type Default value Meaning
visible java.lang.Boolean true The visibility of this Painter
locateable java.lang.Boolean true Specifies, if this Painter is locateable (by the mouse). Unvisible Painters may still be locateable.
alignment Alignment Alignment#LEFT_TOP_ALIGNMENT The alignment of this Painter. (Read by the align-methods.

Version:
2.0
Author:
Thomas Wolf
See Also:
Style

Field Summary
static byte LEVEL_0
          Level attribute: Level 0
static byte LEVEL_1
          Level attribute: Level 1
static byte LEVEL_2
          Level attribute: Level 2 (default)
static byte LEVEL_3
          Level attribute: Level 3
static byte LEVEL_ALL
          Level attribute: all levels
static byte LEVEL_BITS_USED
          The number of bits used by levels.
static byte LEVEL_DEFAULT
          Level attribute: default level (==LEVEL_2)
static byte LEVEL_FIRST
          Level attribute: first level
static byte LEVEL_LAST
          Level attribute: last level
static int LOCATEABLE
          Painter is locateable.
static int VISIBLE
          Painter is visible.
 
Constructor Summary
Painter()
           
 
Method Summary
protected  void addBounds(int x, int y)
          Adds the given point to this Painters bounds.
protected  void addBounds(int x, int y, int width, int height)
          Adds the given rectangular area to this Painters bounds.
 void alignTo(DrawObject source, PropertyStatusReader prop, Alignment default_align)
          Aligns this Painter at the given DrawObject.
 void alignTo(int x, int y, PropertyStatusReader prop, Alignment default_align)
          Aligns this Painter relatively to the given point.
 java.awt.Point calculateDockingPoint(int x, int y)
          Calculates a docking point, that means a point on the outline of the Painter, that lies nearest to the given point.
 boolean contains(int x, int y)
          Returns true, if the specified point hits the Painter.
protected abstract  void draw(java.awt.Graphics g, RenderContext context, PropertyStatusReader prop, byte level)
          Draws the specified level of this Painter using the given Graphics object and RenderContext for drawing, and the given PropertyStatusReader for reading properties.
protected  java.awt.Point getAlignmentPoint(java.awt.Point p, byte h_align, byte v_align)
          Returns an alignment point for the given alignment values.
protected  java.awt.Point getRelativeAlignmentPoint(java.awt.Point p, byte h_align, byte v_align)
          Returns an alignment point for the given alignment values relatively to the upper left corner of this Painters bounding box.
 int height()
          Returns the height of this Painters bounds.
 boolean isOnLevel(byte level)
          Returns true, if the Painter uses a level of the given level mask.
 byte level()
          Returns the level mask, this Painter uses.
 boolean locateable()
          Returns true, if this Painter is locateable via contains(int, int), otherwise false.
 java.lang.String name()
          Returns the name of the Painter.
 Shape outline()
          Returns the stored outline shape.
protected abstract  void recalculate(RenderContext context, PropertyStatusReader prop, Parameters param)
          Recalculates this Painter using the given RenderContext, PropertyStatusReader, local point information and other parameters.
 void reshape(RenderContext context, Parameters param)
          Calls the recalculate(gishur.gui2.RenderContext, gishur.gui2.PropertyStatusReader, gishur.core.Parameters) method.
protected  void setBounds(int x, int y, int width, int height)
          Sets the drawing bounds for this Painter.
protected  void setBounds(java.awt.Rectangle r)
          Sets the drawing bounds for this Painter.
protected  void setLevel(byte level)
          Sets the level mask, this Painter uses.
 void setLocation(int x, int y)
          Sets the location of this Painter.
 void setName(java.lang.String name)
          Sets the name of the element.
protected  void setOutline(Shape outline)
          Sets the outline shape.
 void setSubTypePrefix(java.lang.String prefix)
          Sets the subtype prefix that this Painter should use for reading properties.
 Style style()
          Returns the connected Style of this Painter (that is the Style that created this object via its Style.createPainter(java.lang.String, java.lang.String, gishur.gui2.PropertyStatusReader) method).
 boolean visible()
          Returns true, if this Painter is visible, otherwise false.
 int width()
          Returns the width of this Painters bounds.
 int x()
          Returns the x-coordinate of the upper left corner of this Painters bounds.
 int y()
          Returns the y-coordinate of the upper left corner of this Painters bounds.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VISIBLE

public static final int VISIBLE
Painter is visible.

LOCATEABLE

public static final int LOCATEABLE
Painter is locateable.

LEVEL_0

public static final byte LEVEL_0
Level attribute: Level 0

LEVEL_1

public static final byte LEVEL_1
Level attribute: Level 1

LEVEL_2

public static final byte LEVEL_2
Level attribute: Level 2 (default)

LEVEL_3

public static final byte LEVEL_3
Level attribute: Level 3

LEVEL_ALL

public static final byte LEVEL_ALL
Level attribute: all levels

LEVEL_DEFAULT

public static final byte LEVEL_DEFAULT
Level attribute: default level (==LEVEL_2)

LEVEL_FIRST

public static final byte LEVEL_FIRST
Level attribute: first level

LEVEL_LAST

public static final byte LEVEL_LAST
Level attribute: last level

LEVEL_BITS_USED

public static final byte LEVEL_BITS_USED
The number of bits used by levels.
Constructor Detail

Painter

public Painter()
Method Detail

setSubTypePrefix

public void setSubTypePrefix(java.lang.String prefix)
Sets the subtype prefix that this Painter should use for reading properties.
Parameters:
prefix - the new subtype prefix for reading properties (must not be null)

setName

public void setName(java.lang.String name)
Sets the name of the element.
Parameters:
name - the name of the element (must not be null)

name

public java.lang.String name()
Returns the name of the Painter.
Returns:
the name of the Painter.

recalculate

protected abstract void recalculate(RenderContext context,
                                    PropertyStatusReader prop,
                                    Parameters param)
Recalculates this Painter using the given RenderContext, PropertyStatusReader, local point information and other parameters.
Parameters:
context - the RenderContext to use
prop - the PropertyStatusReader to use for reading properties
param - a Parameters-object for location and other parameters parsed by the DisplayObject, that uses this Painter.

draw

protected abstract void draw(java.awt.Graphics g,
                             RenderContext context,
                             PropertyStatusReader prop,
                             byte level)
Draws the specified level of this Painter using the given Graphics object and RenderContext for drawing, and the given PropertyStatusReader for reading properties.
Parameters:
g - the Graphics to draw on
context - the RenderContext to use
prop - the PropertyStatusReader to use for reading properties
level - the level to draw

reshape

public final void reshape(RenderContext context,
                          Parameters param)
Calls the recalculate(gishur.gui2.RenderContext, gishur.gui2.PropertyStatusReader, gishur.core.Parameters) method. This method looks for the visible and locateable properties itself.

setBounds

protected final void setBounds(int x,
                               int y,
                               int width,
                               int height)
Sets the drawing bounds for this Painter.
Parameters:
x,y - upper left corner of the drawing bounds
width,height - width and height of the drawing bounds

setBounds

protected final void setBounds(java.awt.Rectangle r)
Sets the drawing bounds for this Painter.
Parameters:
r - the bounds rectangle

addBounds

protected final void addBounds(int x,
                               int y,
                               int width,
                               int height)
Adds the given rectangular area to this Painters bounds.
Parameters:
x,y - upper left corner of the area
width,height - width and height of the area

addBounds

protected final void addBounds(int x,
                               int y)
Adds the given point to this Painters bounds.
Parameters:
x,y - the point

getRelativeAlignmentPoint

protected java.awt.Point getRelativeAlignmentPoint(java.awt.Point p,
                                                   byte h_align,
                                                   byte v_align)
Returns an alignment point for the given alignment values relatively to the upper left corner of this Painters bounding box. The default implementation calls Alignment.getReferencePoint}-method. Overwrite this method to select other reference points.
Parameters:
p - a Point object where to store the calculated point or null.
h_align - an alignment value (-128==Alignment.LEFT≤0==Alignment.CENTER≤127==Alignment.RIGHT) for the horizontal alignment
v_align - an alignment value (-128==Alignment.TOP≤0==Alignment.CENTER≤127==Alignment.BOTTOM) for the vertical alignment

getAlignmentPoint

protected final java.awt.Point getAlignmentPoint(java.awt.Point p,
                                                 byte h_align,
                                                 byte v_align)
Returns an alignment point for the given alignment values. This method calls getRelativeAlignmentPoint(java.awt.Point, byte, byte).
Parameters:
p - a Point object where to store the calculated point or null.
h_align - an alignment value (-128==Alignment.LEFT≤0==Alignment.CENTER≤127==Alignment.RIGHT) for the horizontal alignment
v_align - an alignment value (-128==Alignment.TOP≤0==Alignment.CENTER≤127==Alignment.BOTTOM) for the vertical alignment

setLocation

public void setLocation(int x,
                        int y)
Sets the location of this Painter. This method translates the bounding box and the outline of this Painter.
Parameters:
x,y - new position

alignTo

public final void alignTo(DrawObject source,
                          PropertyStatusReader prop,
                          Alignment default_align)
Aligns this Painter at the given DrawObject. The method reads the alignment-property via the given PropertyStatusReader.
Parameters:
source - the DrawObject to use to alignment
prop - PropertyStatusReader for reading properties
default_align - the default Alignment

alignTo

public final void alignTo(int x,
                          int y,
                          PropertyStatusReader prop,
                          Alignment default_align)
Aligns this Painter relatively to the given point. The method reads the alignment-property via the given PropertyStatusReader.
Parameters:
x,y - the position to align relatively to
prop - PropertyStatusReader for reading properties
default_align - the default Alignment

visible

public final boolean visible()
Returns true, if this Painter is visible, otherwise false.
Returns:
true, if visible

locateable

public final boolean locateable()
Returns true, if this Painter is locateable via contains(int, int), otherwise false.
Returns:
true, if locateable

outline

public final Shape outline()
Returns the stored outline shape.
Returns:
the stored outline shape.

setOutline

protected final void setOutline(Shape outline)
Sets the outline shape. This shape is used by the default implementation of contains(int, int) in order to decide, if a given point (usually the mouse position) hits this Painter or not.
Parameters:
outline - the outline shape

calculateDockingPoint

public java.awt.Point calculateDockingPoint(int x,
                                            int y)
Calculates a docking point, that means a point on the outline of the Painter, that lies nearest to the given point. The default implementation returns the center point of the outline shape. This is not a real docking-point! Overwrite this method in order to return correct docking points.
Parameters:
x,y - point, where to come from for docking (outside the Painter).
Returns:
docking point

level

public final byte level()
Returns the level mask, this Painter uses.
Returns:
the level mask, this Painter uses.

setLevel

protected final void setLevel(byte level)
Sets the level mask, this Painter uses.
Parameters:
level - the new level mask of this Painter.

isOnLevel

public final boolean isOnLevel(byte level)
Returns true, if the Painter uses a level of the given level mask.
Parameters:
level - the level mask to test
Returns:
true, if a levelof the level mask is used

x

public final int x()
Returns the x-coordinate of the upper left corner of this Painters bounds.
Returns:
x-coordinate of the bounding rectangle

y

public final int y()
Returns the y-coordinate of the upper left corner of this Painters bounds.
Returns:
y-coordinate of the bounding rectangle

width

public final int width()
Returns the width of this Painters bounds.
Returns:
width of the bounding rectangle

height

public final int height()
Returns the height of this Painters bounds.
Returns:
height of the bounding rectangle

contains

public boolean contains(int x,
                        int y)
Returns true, if the specified point hits the Painter. This method should return false, if the painter is not locateable (see locateable()). This method returns true, if the point lies inside the specified painter bounds (see setBounds(int, int, int, int)) and if it lies in the outline shape (see setOutline(gishur.gui2.Shape)) (If no outline shape is defined, true will be returned, if it lies in the bounds).
Returns:
true, if the specified point hits the Painter.

style

public final Style style()
Returns the connected Style of this Painter (that is the Style that created this object via its Style.createPainter(java.lang.String, java.lang.String, gishur.gui2.PropertyStatusReader) method).
Returns:
the connected Style of this Painter