pl.netanel.swt.matrix
Class Painter<X extends java.lang.Number,Y extends java.lang.Number>

java.lang.Object
  extended by pl.netanel.swt.matrix.Painter<X,Y>
Direct Known Subclasses:
ButtonCellBehavior, CellImageButtonPainter, Grouping.SeparatorPainter

public class Painter<X extends java.lang.Number,Y extends java.lang.Number>
extends java.lang.Object

This class draws everything that appears on the matrix canvas: background, images, text, lines.

Optimization

Because the paint(int, int, int, int) method is called in the loop to paint cells and lines then it is recommended to take as many operations out of it as possible in order to improve the the graphics performance. All the repetitive operations that are common to all elements, like setting a font or a background color can be done in the init() method, which is called only once.

It's also a good practice to restore any of the GC attributes modified by in init() or paint(int, int, int, int) back to the default value to provide a clean start for a next painter. It can be done in the clean() method.

This optimization is possible due to replacing of painting operations loop with the cell iteration loop. In Matrix cell iteration happens inside of the painters iteration and it can still fold to a single cell iteration if all the drawing is done by a single painter.


Field Summary
protected  Point availableTextArea
           
protected  Image collapsedImage
           
protected  boolean expanded
           
protected  Image expandedImage
           
protected  Point extent
           
protected  Frozen frozenX
           
protected  Frozen frozenY
           
protected  GC gc
          Provides graphic to the init(), clean(), paint(int, int, int, int) methods.
protected  boolean hasChildren
           
 Image image
          Image to be painted.
 Image[] imagesAfter
          Contains images that will be displayed after the text starting from the closest one.
 Image[] imagesBefore
          Contains images that will be displayed before the text starting from the most distant one.
protected  boolean isSelected
          Expresses the selected state of the cell to paint set by default by the setup(Number, Number) method.
static java.lang.String NAME_BACKGORUND
          Default name of a painter belonging to a zone and responsible to paint its background.
static java.lang.String NAME_CELLS
          Default name of a painter belonging to a zone and responsible to paint its cells.
static java.lang.String NAME_DRAG_ITEM_X
          Default name of the painter belonging to a matrix responsible to paint the items being dragged on x axis.
static java.lang.String NAME_DRAG_ITEM_Y
          Default name of the painter belonging to a matrix responsible to paint the items being dragged on y axis.
static java.lang.String NAME_EMBEDDED_CONTROLS
          Default name of a painter belonging to a zone and responsible to create/dispose or show/hide the embedded controls.
static java.lang.String NAME_EMULATED_CONTROLS
          Default name of a painter belonging to a zone and responsible to paint the emulated controls.
static java.lang.String NAME_FOCUS_CELL
          Default name of a painter belonging to a matrix and responsible to paint the focus cell.
static java.lang.String NAME_FREEZE_HEAD_LINE_X
          Default name of the painter belonging to a matrix responsible to paint the line dividing the frozen head on the horizontal axis.
static java.lang.String NAME_FREEZE_HEAD_LINE_Y
          Default name of the painter belonging to a matrix responsible to paint the line dividing the frozen head on the vertical axis.
static java.lang.String NAME_FREEZE_TAIL_LINE_X
          Default name of the painter belonging to a matrix responsible to paint the line dividing the frozen tail on the horizontal axis.
static java.lang.String NAME_FREEZE_TAIL_LINE_Y
          Default name of the painter belonging to a matrix responsible to paint the line dividing the frozen tail on the vertical axis.
static java.lang.String NAME_FROZEN_HEAD_HEAD
          Default name of a painter belonging to a matrix and responsible to paint the area that is frozen both at the vertical start and horizontal start of the viewport.
static java.lang.String NAME_FROZEN_HEAD_NONE
          Default name of a painter belonging to a matrix and responsible to paint the area that is frozen only at the vertical start of the viewport.
static java.lang.String NAME_FROZEN_HEAD_TAIL
          Default name of a painter belonging to a matrix and responsible to paint the area that is frozen both at the vertical start and horizontal end of the viewport.
static java.lang.String NAME_FROZEN_NONE_HEAD
          Default name of a painter belonging to a matrix and responsible to paint the area that is frozen only at the horizontal start of the viewport.
static java.lang.String NAME_FROZEN_NONE_NONE
          Default name of a painter belonging to a matrix and responsible to paint the area not frozen.
static java.lang.String NAME_FROZEN_NONE_TAIL
          Default name of a painter belonging to a matrix and responsible to paint the area that is frozen only at the horizontal end of the viewport.
static java.lang.String NAME_FROZEN_TAIL_HEAD
          Default name of a painter belonging to a matrix and responsible to paint the area that is frozen both at the vertical end and horizontal start of the viewport.
static java.lang.String NAME_FROZEN_TAIL_NONE
          Default name of a painter belonging to a matrix and responsible to paint the area that is frozen only at the vertical end of the viewport.
static java.lang.String NAME_FROZEN_TAIL_TAIL
          Default name of a painter belonging to a matrix and responsible to paint the area that is frozen both at the vertical end and horizontal end of the viewport.
static java.lang.String NAME_LINES_X
          Default name of a painter belonging to a zone and responsible to paint its lines along x axis.
static java.lang.String NAME_LINES_Y
          Default name of a painter belonging to a zone and responsible to paint its lines along y axis.
protected  Point nodeImageSize
           
static int SCOPE_CELLS
          Shortcut for SCOPE_CELLS_X
static int SCOPE_CELLS_ITEM_X
          Compound boundaries including all cells of an axis X item (column)
static int SCOPE_CELLS_ITEM_Y
          Compound boundaries including all cells of an axis Y item (row)
static int SCOPE_CELLS_X
          Individual cells in horizontal order first.
static int SCOPE_CELLS_Y
          Individual cells in vertical order first.
static int SCOPE_ENTIRE
          Single scope of the whole container
static int SCOPE_LINES_X
          Horizontal lines stretching from the left to the right edge of the zone to which the painter belongs.
static int SCOPE_LINES_Y
          Vertical lines stretching from the top to the bottom edge of the zone to which the painter belongs.
 boolean selectionHighlight
          Selected cells will be highlighted if true.
 Style style
          Painter style properties.
 java.lang.String text
          Text to be painted.
protected  TextLayout textLayout
           
 
Constructor Summary
Painter(java.lang.String name)
          Constructs a painter with the given name.
Painter(java.lang.String name, int scope)
          The main constructor.
 
Method Summary
static int align(int align, int margin, int width, int bound)
          Returns the distance of a graphical element based on the align mode and the padding margin.
 void clean()
          Restores the default GC settings modified by modified by in init() or paint(int, int, int, int).
protected  void clipText()
          Called by paint method to adjust the text to be painted in case the text does not fit the allotted area.
protected  Point computeSize(X indexX, Y indexY, int wHint, int hHint)
          Returns the preferred size of the receiver.
protected  void computeTextSize(java.lang.String s)
          Computes size of the given text using the current font of the graphic context.
 void dispose()
           
 java.lang.Object getData()
          Returns custom data of this painter.
 Image getImageAt(int x, int y)
          Returns an image which bounds contain the given point or null otherwise.
 java.lang.String getName()
          Returns the painter name.
 int getScope()
          Returns the painter scope.
 Zone<X,Y> getZone()
          Returns the zone to which the painter is attached or null if it is attached to matrix.
 boolean hasTreeLinesVisible()
          Returns true if the tree lines are visible, or false otherwise.
protected  boolean init()
          Allows graphic optimization by performing operation that can be taken out of the cell painting loop.
 boolean isEnabled()
          Returns true if the painter is enabled, or false otherwise.
 boolean isTreeEnabled()
          Returns true if the tree painting is enabled, or false otherwise.
protected  void paint(int x, int y, int width, int height)
          Draws on the canvas within the given boundaries according to the given indexes.
 void setData(java.lang.Object data)
          Sets custom data for this painter.
 void setEnabled(boolean enabled)
          Sets the enabled state of the receiver.
 void setNodeImages(Image collapsedImage, Image expandedImage)
          Sets the icons to represent collapsed/expanded state of a tree node.
 void setTreeLinesVisible(boolean state)
          Makes the tree lines connecting nodes visible if set to true, or hidden otherwise.
 void setTreeVisible(boolean state)
          Enables a vertical tree in the first column with node icons indicating expanded/collapsed state.
 void setup(X indexX, Y indexY)
          Configures the painter properties according to the given indexes.
 void setupSpatial(X indexX, Y indexY)
          Sets the spatial properties for this painter.
 void trackPosition(Image image, boolean state)
          Tracking image positions during painting allows to refer to its position later with #getImageAt(int, int).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SCOPE_ENTIRE

public static final int SCOPE_ENTIRE
Single scope of the whole container

See Also:
Constant Field Values

SCOPE_LINES_X

public static final int SCOPE_LINES_X
Horizontal lines stretching from the left to the right edge of the zone to which the painter belongs.

See Also:
Constant Field Values

SCOPE_LINES_Y

public static final int SCOPE_LINES_Y
Vertical lines stretching from the top to the bottom edge of the zone to which the painter belongs.

See Also:
Constant Field Values

SCOPE_CELLS_ITEM_X

public static final int SCOPE_CELLS_ITEM_X
Compound boundaries including all cells of an axis X item (column)

See Also:
Constant Field Values

SCOPE_CELLS_ITEM_Y

public static final int SCOPE_CELLS_ITEM_Y
Compound boundaries including all cells of an axis Y item (row)

See Also:
Constant Field Values

SCOPE_CELLS_X

public static final int SCOPE_CELLS_X
Individual cells in horizontal order first. Aids graphics performance in case of drawing homogenic rows.

See Also:
Constant Field Values

SCOPE_CELLS_Y

public static final int SCOPE_CELLS_Y
Individual cells in vertical order first. Aids graphics performance in case of drawing homogenic columns.

See Also:
Constant Field Values

SCOPE_CELLS

public static final int SCOPE_CELLS
Shortcut for SCOPE_CELLS_X

See Also:
Constant Field Values

NAME_CELLS

public static final java.lang.String NAME_CELLS
Default name of a painter belonging to a zone and responsible to paint its cells. Painter with that name should not be removed, because ZoneEditor and NAME_DRAG_ITEM_X use it to perform their functions.

See Also:
Constant Field Values

NAME_LINES_X

public static final java.lang.String NAME_LINES_X
Default name of a painter belonging to a zone and responsible to paint its lines along x axis.

See Also:
Constant Field Values

NAME_LINES_Y

public static final java.lang.String NAME_LINES_Y
Default name of a painter belonging to a zone and responsible to paint its lines along y axis.

See Also:
Constant Field Values

NAME_BACKGORUND

public static final java.lang.String NAME_BACKGORUND
Default name of a painter belonging to a zone and responsible to paint its background.

See Also:
Constant Field Values

NAME_FROZEN_NONE_NONE

public static final java.lang.String NAME_FROZEN_NONE_NONE
Default name of a painter belonging to a matrix and responsible to paint the area not frozen.

See Also:
Constant Field Values

NAME_FROZEN_NONE_TAIL

public static final java.lang.String NAME_FROZEN_NONE_TAIL
Default name of a painter belonging to a matrix and responsible to paint the area that is frozen only at the horizontal end of the viewport.

See Also:
Constant Field Values

NAME_FROZEN_TAIL_NONE

public static final java.lang.String NAME_FROZEN_TAIL_NONE
Default name of a painter belonging to a matrix and responsible to paint the area that is frozen only at the vertical end of the viewport.

See Also:
Constant Field Values

NAME_FROZEN_NONE_HEAD

public static final java.lang.String NAME_FROZEN_NONE_HEAD
Default name of a painter belonging to a matrix and responsible to paint the area that is frozen only at the horizontal start of the viewport.

See Also:
Constant Field Values

NAME_FROZEN_HEAD_NONE

public static final java.lang.String NAME_FROZEN_HEAD_NONE
Default name of a painter belonging to a matrix and responsible to paint the area that is frozen only at the vertical start of the viewport.

See Also:
Constant Field Values

NAME_FROZEN_HEAD_TAIL

public static final java.lang.String NAME_FROZEN_HEAD_TAIL
Default name of a painter belonging to a matrix and responsible to paint the area that is frozen both at the vertical start and horizontal end of the viewport.

See Also:
Constant Field Values

NAME_FROZEN_TAIL_HEAD

public static final java.lang.String NAME_FROZEN_TAIL_HEAD
Default name of a painter belonging to a matrix and responsible to paint the area that is frozen both at the vertical end and horizontal start of the viewport.

See Also:
Constant Field Values

NAME_FROZEN_TAIL_TAIL

public static final java.lang.String NAME_FROZEN_TAIL_TAIL
Default name of a painter belonging to a matrix and responsible to paint the area that is frozen both at the vertical end and horizontal end of the viewport.

See Also:
Constant Field Values

NAME_FROZEN_HEAD_HEAD

public static final java.lang.String NAME_FROZEN_HEAD_HEAD
Default name of a painter belonging to a matrix and responsible to paint the area that is frozen both at the vertical start and horizontal start of the viewport.

See Also:
Constant Field Values

NAME_FOCUS_CELL

public static final java.lang.String NAME_FOCUS_CELL
Default name of a painter belonging to a matrix and responsible to paint the focus cell.

See Also:
Constant Field Values

NAME_EMULATED_CONTROLS

public static final java.lang.String NAME_EMULATED_CONTROLS
Default name of a painter belonging to a zone and responsible to paint the emulated controls.

See Also:
Constant Field Values

NAME_EMBEDDED_CONTROLS

public static final java.lang.String NAME_EMBEDDED_CONTROLS
Default name of a painter belonging to a zone and responsible to create/dispose or show/hide the embedded controls.

See Also:
Constant Field Values

NAME_DRAG_ITEM_X

public static final java.lang.String NAME_DRAG_ITEM_X
Default name of the painter belonging to a matrix responsible to paint the items being dragged on x axis.

See Also:
Constant Field Values

NAME_DRAG_ITEM_Y

public static final java.lang.String NAME_DRAG_ITEM_Y
Default name of the painter belonging to a matrix responsible to paint the items being dragged on y axis.

See Also:
Constant Field Values

NAME_FREEZE_HEAD_LINE_X

public static final java.lang.String NAME_FREEZE_HEAD_LINE_X
Default name of the painter belonging to a matrix responsible to paint the line dividing the frozen head on the horizontal axis.

See Also:
Constant Field Values

NAME_FREEZE_HEAD_LINE_Y

public static final java.lang.String NAME_FREEZE_HEAD_LINE_Y
Default name of the painter belonging to a matrix responsible to paint the line dividing the frozen head on the vertical axis.

See Also:
Constant Field Values

NAME_FREEZE_TAIL_LINE_X

public static final java.lang.String NAME_FREEZE_TAIL_LINE_X
Default name of the painter belonging to a matrix responsible to paint the line dividing the frozen tail on the horizontal axis.

See Also:
Constant Field Values

NAME_FREEZE_TAIL_LINE_Y

public static final java.lang.String NAME_FREEZE_TAIL_LINE_Y
Default name of the painter belonging to a matrix responsible to paint the line dividing the frozen tail on the vertical axis.

See Also:
Constant Field Values

gc

protected GC gc
Provides graphic to the init(), clean(), paint(int, int, int, int) methods. It is not safe to use it inside of other methods.


isSelected

protected boolean isSelected
Expresses the selected state of the cell to paint set by default by the setup(Number, Number) method.


text

public java.lang.String text
Text to be painted. The placement of the text depends on the Style.textAlignX, Style.textAlignY, Style.textMarginX, Style.textMarginY properties.


image

public Image image
Image to be painted. The placement of the image depends on the Style.imageAlignX, Style.imageAlignY, Style.imageMarginX, Style.imageMarginY properties.


imagesBefore

public Image[] imagesBefore
Contains images that will be displayed before the text starting from the most distant one.

See Also:
imagesAfter

imagesAfter

public Image[] imagesAfter
Contains images that will be displayed after the text starting from the closest one.

See Also:
imagesBefore

selectionHighlight

public boolean selectionHighlight
Selected cells will be highlighted if true. Otherwise cell selection will be ignored. Default value is true.


style

public Style style
Painter style properties.


availableTextArea

protected Point availableTextArea

textLayout

protected TextLayout textLayout

extent

protected Point extent

collapsedImage

protected Image collapsedImage

expandedImage

protected Image expandedImage

nodeImageSize

protected Point nodeImageSize

hasChildren

protected boolean hasChildren

expanded

protected boolean expanded

frozenX

protected Frozen frozenX

frozenY

protected Frozen frozenY
Constructor Detail

Painter

public Painter(java.lang.String name)
Constructs a painter with the given name.

The scope of the painter is determined according to the following rules:
for name NAME_CELLS scope = SCOPE_CELLS
for name NAME_LINES_X scope = SCOPE_LINES_X
for name NAME_LINES_Y scope = SCOPE_LINES_Y
for name NAME_EMBEDDED_CONTROLS scope = SCOPE_CELLS
for name NAME_EMULATED_CONTROLS scope = SCOPE_CELLS
else SCOPE_ENTIRE.

Parameters:
name - of the painter, must be unique in the collection to which it is added
See Also:
Painter(String, int)

Painter

public Painter(java.lang.String name,
               int scope)
The main constructor.

Parameters:
name - the name of the painter, must be unique in the collection to which it is added
scope - the scope of the painter deciding on the order and size of the boundaries the paint(int, int, int, int) method receives. The value must be one of the Painter constants prefixed with SCOPE_.
Method Detail

getName

public java.lang.String getName()
Returns the painter name.

Returns:
the painter name

getScope

public int getScope()
Returns the painter scope.

Returns:
the painter scope

init

protected boolean init()
Allows graphic optimization by performing operation that can be taken out of the cell painting loop.

If this method returns false the paint(int, int, int, int) and clean() methods will not be executed.

Returns:
true if the initialization succeeded or false otherwise.
See Also:
clean()

clean

public void clean()
Restores the default GC settings modified by modified by in init() or paint(int, int, int, int).

See Also:
init()

dispose

public void dispose()

computeSize

protected Point computeSize(X indexX,
                            Y indexY,
                            int wHint,
                            int hHint)
Returns the preferred size of the receiver.

Parameters:
indexX - cell index on the horizontal axis
indexY - cell index on the vertical axis
wHint - the width hint (can be SWT.DEFAULT)
hHint - the height hint (can be SWT.DEFAULT)
Returns:
the preferred size of the control

paint

protected void paint(int x,
                     int y,
                     int width,
                     int height)
Draws on the canvas within the given boundaries according to the given indexes.

Parameters:
x - the x coordinate of the painting boundaries
y - the y coordinate of the painting boundaries
width - the width of the painting boundaries
height - the height of the painting boundaries

clipText

protected void clipText()
Called by paint method to adjust the text to be painted in case the text does not fit the allotted area.

The size of allotted area for text is contained in availableTextAreafield. After the method determines new text to display it should modify the availableTextArea properties to match the size of the new text. It is needed for text alignment other then SWT#LEFT.


computeTextSize

protected void computeTextSize(java.lang.String s)
Computes size of the given text using the current font of the graphic context. The result is stored in #extent variable. The default implementation uses an in house font size cache. It becomes ineficient when the frequency of font changing is higher then 25%. In such case override it with extent = gc.stringExtent(s);

Parameters:
s - text to compute the size for

setup

public void setup(X indexX,
                  Y indexY)
Configures the painter properties according to the given indexes.

Default implementation invokes setupSpatial(Number, Number) and determines if the cell is selected, therefore when overridden should call super.setup.

Parameters:
indexX - cell index on the horizontal axis
indexY - cell index on the vertical axis

setupSpatial

public void setupSpatial(X indexX,
                         Y indexY)
Sets the spatial properties for this painter. Spatial properties are the ones that effect the space of the cell and include: text, image, text and image margins, text wrapping.

Default implementation computes space of in first column when tree is enabled, therefore when overridden should call super.setupSpatial.

It is utilized by both painting mechanism as well as computeSize(Number, Number, int, int) routine. The reason to separate it from setup(Number, Number) method is to improve performance of size computing by eliminating unnecessary processing, like setting colors, determining whether the cell is selected, etc.

The most common usage is to set the text to display:

  public void setupSpatial(Integer indexX, Integer indexY){
 text = data[indexY][indexX];
 }
 

Parameters:
indexX - cell index on the horizontal axis
indexY - cell index on the vertical axis

setData

public void setData(java.lang.Object data)
Sets custom data for this painter.

Painters NAME_DRAG_ITEM_X and NAME_DRAG_ITEM_Y use it to get mouse coordinates and draw drag feedback indicator if supplied with DropTargetEvent object with this method. Example:

dropTarget.addDropListener(new DropTargetAdapter() {
   @Override public void dragOver(DropTargetEvent event) {
     dragPainterY.setData(event);
   }
 });

Parameters:
data - data to set

getData

public java.lang.Object getData()
Returns custom data of this painter.

Returns:
custom data of this painter

setEnabled

public void setEnabled(boolean enabled)
Sets the enabled state of the receiver.

Allows to skip the receiver in the painting sequence. It can be used to hide/show the lines for example.

Parameters:
enabled - the new enabled state

isEnabled

public boolean isEnabled()
Returns true if the painter is enabled, or false otherwise.

Communicates to the client to skip this painter in the painting sequence. It can be used to hide/show the lines for example.

Returns:
the enabled state

setTreeVisible

public void setTreeVisible(boolean state)
Enables a vertical tree in the first column with node icons indicating expanded/collapsed state. The icons are created if are null.

Parameters:
state - true to enable tree painting or false to disable it.

isTreeEnabled

public boolean isTreeEnabled()
Returns true if the tree painting is enabled, or false otherwise.

Returns:
true if the tree painting is enabled, or false otherwise

setTreeLinesVisible

public void setTreeLinesVisible(boolean state)
Makes the tree lines connecting nodes visible if set to true, or hidden otherwise.

Parameters:
state - true to make the tree lines visible, or false otherwise.

hasTreeLinesVisible

public boolean hasTreeLinesVisible()
Returns true if the tree lines are visible, or false otherwise.


setNodeImages

public void setNodeImages(Image collapsedImage,
                          Image expandedImage)
Sets the icons to represent collapsed/expanded state of a tree node.

The image can be null and then no icon is displayed.

Parameters:
collapsedImage - image representing collapsed state.
expandedImage - image representing expanded state.

align

public static int align(int align,
                        int margin,
                        int width,
                        int bound)
Returns the distance of a graphical element based on the align mode and the padding margin.

Parameters:
align - the alignment mode, one of: SWT#LEFT, SWT#RIGHT, SWT#CENTER, SWT#TOP, SWT#BOTTOM, SWT#BEGINNING, SWT#END
margin - the number of pixels from the edge to which to align, does not matter with SWT#CENTER
width - the width of the element
bound - the width of the cell
Returns:
the distance of a graphical element based on the align mode and the padding margin

getZone

public Zone<X,Y> getZone()
Returns the zone to which the painter is attached or null if it is attached to matrix.

Returns:
the zone to which the painter is attached or null if it is attached to matrix

trackPosition

public void trackPosition(Image image,
                          boolean state)
Tracking image positions during painting allows to refer to its position later with #getImageAt(int, int).

Parameters:
image - image to track the positions for

getImageAt

public Image getImageAt(int x,
                        int y)
Returns an image which bounds contain the given point or null otherwise. The image tracking must be set before in order to be returned by this method.

Parameters:
x - the x screen coordinate in the zone to check for the image at
y - the y screen coordinate in the zone to check for the image at
Returns:
an image which bounds contain the given point
See Also:
getImageAt(int, int)


Copyright © 2011 netanel.pl. All Rights Reserved.