uk.ac.starlink.ast.grf
Class DefaultGrf

java.lang.Object
  extended by uk.ac.starlink.ast.grf.DefaultGrf
All Implemented Interfaces:
Grf

public class DefaultGrf
extends Object
implements Grf

This class implements the Grf interface required to draw graphics using JNIAST. It provides the graphics functions for drawing lines, curves, arbitrary text and markers onto a graphics context.

The state of any graphics drawn is persistent and can be re-drawn onto a Graphics2D object using the paint method. This should be invoked from the paintComponent method of the JComponent.

  public void paintComponent( Graphics g )
  {
        super.paintComponent( g );
        defaultGrf.paint( (Graphics2D)g ):
  }
 
Although if you're using a Plot, then you should use its paint method (which will eventually call this paint method).

Standard Color objects are encoded to an integer using encodeColor(java.awt.Color) method, so that all colours can be represented by a unique integer for passing through the Grf interface. To reconstruct a Color use the decodeColor(int) method.

In addition to the standard Grf interface this implementation also offers a set of additional public methods that can be used directly. For instance a set of double precision methods are available for extra efficiency (the standard Grf interface only works with floats) and methods are provided that control the fonts that are used (see the addFont, deleteFont methods).

Version:
$Id$
Author:
Peter W. Draper

Field Summary
static double BAD
          Constant defining a BAD value (used to break polylines), this is the same as AST__BAD by definition.
static int DASH
          Use a dashed line drawing style.
static String DEFAULT
          Name of the default context list.
static int DOT
          Use a dotted line drawing style.
static int DOTDASH
          Use a dot dash line drawing style.
static int GRF__ALPHA
          Constants defining different attributes.
static int LONGDASH
          Use a long dash line drawing style.
static int PLAIN
          Use a plain line drawing style.
static int SHORTDASH
          Use a short dash line drawing style.
 
Fields inherited from interface uk.ac.starlink.ast.Grf
GRF__COLOUR, GRF__ESC, GRF__FONT, GRF__LINE, GRF__MARK, GRF__MJUST, GRF__SCALES, GRF__SIZE, GRF__STYLE, GRF__TEXT, GRF__WIDTH
 
Constructor Summary
DefaultGrf(FontRenderContext frc)
          Constructor Initialise the font render context being used.
DefaultGrf(JComponent component)
          Constructor which initialises the font render context from a Component.
 
Method Summary
 int addFont(Font font)
          Add a new font.
 double attr(int attr, double value, int prim)
          Enquires or sets a graphics attribute value.
 double attribute(int attr, double value, int prim)
          Enquire or set a graphics attribute value This function returns the current value of a specified graphics attribute, and optionally establishes a new value.
 double[] axisScale()
          Get the axis scales.
static int[] bound(double xcoord, double[] values)
          Locate the indices of the two coordinates that lie closest to a given coordinate.
 int cap(int cap, int value)
          Indicates which abilities this Grf implementation has.
 double[] charHeight()
          Return the character height in component coordinates.
 void clear()
          Clears all known graphics.
static Color decodeColor(int value)
          Decode a colour encoded as an integer using encodeColor.
 int deleteFont(Font font)
          Disable a font by removing it from the known list.
static void drawLine(Graphics2D g2, DefaultGrfContainer cont)
          Draw a polyline onto a given Graphics2D object, using the state in a given GrfContainer.
protected  void drawMark(Graphics2D g2, DefaultGrfContainer cont)
          Draw a graphics marker.
protected  void drawText(Graphics2D g2, DefaultGrfContainer cont)
          Draw a text string.
static int encodeColor(Color colour)
          Encode a Color to a unique integer value that can be used in the Grf interface.
 void establishContext(String key)
          Establish a graphics context for grouping a set of related drawing operations.
 void flush()
          Flush all graphics, thereby redrawing them.
protected  double[] getAnchor(String just, double angle, double x, double y, double[] bbox)
          Return the X and Y AST anchor position of a string.
 Font getFont(int index)
          Get a known font by graphics index.
 int getFontIndex(Font font)
          Get the graphics index of a known font.
 FontRenderContext getFontRenderContext()
          Get the context used to check the drawing of fonts.
 void line(int n, float[] x, float[] y)
          Draws a polyline (a set of connected lines).
static Stroke lineStroke(int type, float width)
          Create a Stroke for drawing a line using one of the possible line styles.
 void mark(int n, float[] x, float[] y, int type)
          Displays markers at the given positions.
 void marker(double[] x, double[] y, int type)
          Update current graphics context to include a set of markers.
 void paint(Graphics g)
          Paints the graphics written to this Grf object since its construction or the last call of clear into the graphics context given.
 void paint(Graphics2D g2)
          Draw the complete current graphics context onto a Graphics2D object.
 void polyline(double[] x, double[] y)
          Update current graphics context to include a polyline.
 float[] qch()
          Returns the character height in world coordinates.
 void reAdd(String key, Object context)
          Re-add a removed context.
 Object remove(String key)
          Remove and return all graphics in a given context.
 void reset()
          Clear all graphics buffers.
 float[] scales()
          Gets the axis scales.
 void setClipRegion(Rectangle region)
          Set the clipping region (null to reset).
 void text(String text, double x, double y, String just, double upx, double upy)
          Update current graphic context with a character string.
 void text(String text, float x, float y, String just, float upx, float upy)
          Displays a character string at a given position using a specified justification and up-vector.
 double[] textExtent(String text, double x, double y, String just, double upx, double upy)
          Return the extent of a character string.
protected  DefaultGrfContainer textProperties(String text, double x, double y, String just, double upx, double upy)
          Calculate the properties of a text object.
 float[][] txExt(String text, float x, float y, String just, float upx, float upy)
          Gets the extent of a character string.
protected  void update(Graphics2D g2)
          Draw the all known graphics to a component.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

GRF__ALPHA

public static final int GRF__ALPHA
Constants defining different attributes. Only one that isn't present in the Grf interface.

See Also:
Constant Field Values

BAD

public static final double BAD
Constant defining a BAD value (used to break polylines), this is the same as AST__BAD by definition.


PLAIN

public static final int PLAIN
Use a plain line drawing style.

See Also:
Constant Field Values

DASH

public static final int DASH
Use a dashed line drawing style.

See Also:
Constant Field Values

DOT

public static final int DOT
Use a dotted line drawing style.

See Also:
Constant Field Values

SHORTDASH

public static final int SHORTDASH
Use a short dash line drawing style.

See Also:
Constant Field Values

LONGDASH

public static final int LONGDASH
Use a long dash line drawing style.

See Also:
Constant Field Values

DOTDASH

public static final int DOTDASH
Use a dot dash line drawing style.

See Also:
Constant Field Values

DEFAULT

public static final String DEFAULT
Name of the default context list.

See Also:
Constant Field Values
Constructor Detail

DefaultGrf

public DefaultGrf(FontRenderContext frc)
Constructor Initialise the font render context being used.

Parameters:
frc - font render context

DefaultGrf

public DefaultGrf(JComponent component)
Constructor which initialises the font render context from a Component.

Parameters:
component - component supplying font render context
Method Detail

getFontRenderContext

public FontRenderContext getFontRenderContext()
Get the context used to check the drawing of fonts.

Returns:
The font render context value

establishContext

public void establishContext(String key)
Establish a graphics context for grouping a set of related drawing operations. The context is associated with the given String, which you must ensure is unique within your application. The key can be used to reference this context when clearing grahics. A special context DEFAULT is recognised as the default context. This is the initial state and can be reused (although switching back will produce a confusion in the Z-ordering of the graphics, all elements drawn to the default context will be rendered first).

Parameters:
key - a key to associate with this context. If null then the DEFAULT context will be assumed.

paint

public void paint(Graphics2D g2)
Draw the complete current graphics context onto a Graphics2D object. This method should be called whenever the JComponent that we are drawing to needs repainting.

Parameters:
g2 - the Graphics2D object to repaint.

reset

public void reset()
Clear all graphics buffers. Note this does not erase drawing, that happens after next paint.


remove

public Object remove(String key)
Remove and return all graphics in a given context. Returns the complete context, if found, otherwise a null is returned. The returned context maybe re-established using the reAdd(java.lang.String, java.lang.Object) method (although the Z-order will now be different).


reAdd

public void reAdd(String key,
                  Object context)
Re-add a removed context. The context must have been returned by the remove(java.lang.String) method.


polyline

public void polyline(double[] x,
                     double[] y)
Update current graphics context to include a polyline.

Parameters:
x - array of polyline X vertices
y - array of polyline Y vertices

marker

public void marker(double[] x,
                   double[] y,
                   int type)
Update current graphics context to include a set of markers.

Parameters:
x - array of X positions
y - array of Y positions
type - an integer indicating the type of symbol required. The possible values are defined as constants in the DefaultGrfMarker class.

text

public void text(String text,
                 double x,
                 double y,
                 String just,
                 double upx,
                 double upy)
Update current graphic context with a character string.

Parameters:
text - Pointer to the string to be displayed.
x - The reference x coordinate.
y - The reference y coordinate.
just - A character string which specifies the location within the text string which is to be placed at the reference position given by x and y. The first character may be 'T' for "top", 'C' for "centre", or 'B' for "bottom", and specifies the vertical location of the reference position. Note, "bottom" corresponds to the base-line of normal text. Some characters (eg "y", "g", "p", etc) descend below the base-line. The second character may be 'L' for "left", 'C' for "centre", or 'R' for "right", and specifies the horizontal location of the reference position. If the string has less than 2 characters then 'C' is used for the missing characters.
upx - The x component of the up-vector for the text, in graphics world coordinates. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from left to right on the screen.
upy - The y component of the up-vector for the text, in graphics world coordinates. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from bottom to top on the screen.

textProperties

protected DefaultGrfContainer textProperties(String text,
                                             double x,
                                             double y,
                                             String just,
                                             double upx,
                                             double upy)
Calculate the properties of a text object.


flush

public void flush()
Flush all graphics, thereby redrawing them. Required for AST interface, normally do this by (re)paint methods. This is a no-op.

Specified by:
flush in interface Grf

textExtent

public double[] textExtent(String text,
                           double x,
                           double y,
                           String just,
                           double upx,
                           double upy)
Return the extent of a character string.

Note: The text rotation and position is determined by creating an affine transformation and applying this directly to the unrotated bounding box. I hope this saves time and is faster than adding a transform to the Graphics2D object.

Parameters:
text - Pointer to the string to be measured.
x - The reference x coordinate.
y - The reference y coordinate.
just - A character string which specifies the location within the text string which is to be placed at the reference position given by x and y. The first character may be 'T' for "top", 'C' for "centre", or 'B' for "bottom", and specifies the vertical location of the reference position. Note, "bottom" corresponds to the base-line of normal text. Some characters (eg "y", "g", "p", etc) descend below the base-line. The second character may be 'L' for "left", 'C' for "centre", or 'R' for "right", and specifies the horizontal location of the reference position. If the string has less than 2 characters then 'C' is used for the missing characters.
upx - The x component of the up-vector for the text, in graphics world coordinates. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from left to right on the screen.
upy - The y component of the up-vector for the text, in graphics world coordinates. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from bottom to top on the screen.
Returns:
double[] the X and Y bounds

charHeight

public double[] charHeight()
Return the character height in component coordinates.

Returns:
double[2] X and Y size of characters.

attribute

public double attribute(int attr,
                        double value,
                        int prim)
Enquire or set a graphics attribute value This function returns the current value of a specified graphics attribute, and optionally establishes a new value. The supplied value is converted to an integer value if necessary.

Parameters:
attr - An integer value identifying the required attribute. The following symbolic values are defined:
  • GRF__STYLE - Line style.
  • GRF__WIDTH - Line width.
  • GRF__SIZE - Character and marker size scale factor.
  • GRF__FONT - Character font.
  • GRF__COLOUR - Colour index.
  • GRF__ALPHA - Alpha blending fraction.
value - A new value to store for the attribute. If this is BAD no value is stored.
prim - The sort of graphics primitive to be drawn with the new attribute. Identified by the following values:
  • GRF__LINE
  • GRF__MARK
  • GRF__TEXT
Returns:
The current attribute value (before change).

axisScale

public double[] axisScale()
Get the axis scales. Java assumes an ideal pixel size of 72dpi.


addFont

public int addFont(Font font)
Add a new font.

Parameters:
font - the new Font.
Returns:
the graphics index of the Font.

deleteFont

public int deleteFont(Font font)
Disable a font by removing it from the known list. Do this when a font is no longer required (or can no longer be referenced).

Parameters:
font - the font to remove from the known list
Returns:
the graphics index of the Font.

getFontIndex

public int getFontIndex(Font font)
Get the graphics index of a known font.

Parameters:
font - the font to locate.
Returns:
index of the font or the default font if not known.

getFont

public Font getFont(int index)
Get a known font by graphics index.

Parameters:
index - graphics index of the required font.
Returns:
the known font or, if unknown the default font.

setClipRegion

public void setClipRegion(Rectangle region)
Set the clipping region (null to reset).

Parameters:
region - a region specifying the outer limits of the region to draw in.

getAnchor

protected double[] getAnchor(String just,
                             double angle,
                             double x,
                             double y,
                             double[] bbox)
Return the X and Y AST anchor position of a string.

Parameters:
just - the AST justification string.
angle - rotation of text when plotted.
x - the x coordinate of the bounding box lower corner.
y - the y coordinate of the bounding box lower corner.
bbox - the bounding box of the text that is to be plotted (from Font.getStringBounds()).
Returns:
double[2] the x,y positions of the anchor point, this is adjusted so that the actual rotation about the lower lefthand corner of the text string gives the correct positioning.

update

protected void update(Graphics2D g2)
Draw the all known graphics to a component. Does the real work.


drawLine

public static void drawLine(Graphics2D g2,
                            DefaultGrfContainer cont)
Draw a polyline onto a given Graphics2D object, using the state in a given GrfContainer.

Parameters:
g2 - the Graphics2D object that we are drawing into.
cont - container with the graphics state set.

lineStroke

public static Stroke lineStroke(int type,
                                float width)
Create a Stroke for drawing a line using one of the possible line styles.

Parameters:
type - one of the possible types: PLAIN, DASH, DOT, SHORTDASH, LONGDASH or DOTDASH.
width - the width of the line that will be drawn with this Stroke.
Returns:
the Stroke

drawText

protected void drawText(Graphics2D g2,
                        DefaultGrfContainer cont)
Draw a text string.


drawMark

protected void drawMark(Graphics2D g2,
                        DefaultGrfContainer cont)
Draw a graphics marker.


bound

public static int[] bound(double xcoord,
                          double[] values)
Locate the indices of the two coordinates that lie closest to a given coordinate.

Parameters:
xcoord - the coordinate value to bound.
values - the coordinates to check.
Returns:
array of two integers, the lower and upper indices.

encodeColor

public static int encodeColor(Color colour)
Encode a Color to a unique integer value that can be used in the Grf interface.

Parameters:
colour - the Color to encode.
Returns:
the integer representation.

decodeColor

public static Color decodeColor(int value)
Decode a colour encoded as an integer using encodeColor.

Parameters:
value - the integer that represents a colour.
Returns:
a Color object.

paint

public void paint(Graphics g)
Description copied from interface: Grf
Paints the graphics written to this Grf object since its construction or the last call of clear into the graphics context given.

Specified by:
paint in interface Grf
Parameters:
g - the graphics context. It will be cast to a Graphics2D, but hopefully it will be one of those anyway.

clear

public void clear()
Description copied from interface: Grf
Clears all known graphics. It cannot actually erase graphics drawn to an existing graphics context, but immediately following this call, a subsequent call to paint will draw nothing to its graphics context.

Specified by:
clear in interface Grf

line

public void line(int n,
                 float[] x,
                 float[] y)
Description copied from interface: Grf
Draws a polyline (a set of connected lines). Nothing should be done if n is less than 2, or if x or y are null.

Specified by:
line in interface Grf
Parameters:
n - the number of points to plot
x - an array of n x-coordinates
y - an array of n y-coordinates

mark

public void mark(int n,
                 float[] x,
                 float[] y,
                 int type)
Description copied from interface: Grf
Displays markers at the given positions. Nothing should be done if n is less than 2, or if x or y are null.

Specified by:
mark in interface Grf
Parameters:
n - the number of points to plot
x - an array of n x-coordinates
y - an array of n y-coordinates
type - an integer indicating the type of marker to plot

text

public void text(String text,
                 float x,
                 float y,
                 String just,
                 float upx,
                 float upy)
Description copied from interface: Grf
Displays a character string at a given position using a specified justification and up-vector. A null value for just is equivalent to supplying "CC". upx=upy=0 should throw an Exception.

Specified by:
text in interface Grf
Parameters:
text - the string to be displayed
x - the reference x coordinate
y - the reference y coordinate
just - a character string which specifies the location within the text string which is to be placed at the reference position given by x and y. The first character may be 'T' for "top", 'C' for "centre", or 'B' for "bottom", and specifies the vertical location of the reference position. Note, "bottom" corresponds to the base-line of normal text. Some characters (eg "y", "g", "p", etc) descend below the base-line. The second character may be 'L' for "left", 'C' for "centre", or 'R' for "right", and specifies the horizontal location of the reference position. If the string has less than 2 characters then 'C' is used for the missing characters.
upx - The x component of the up-vector for the text, in graphics world coordinates. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from left to right on the screen.
upy - The y component of the up-vector for the text, in graphics world coordinates. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from bottom to top on the screen.

attr

public double attr(int attr,
                   double value,
                   int prim)
Enquires or sets a graphics attribute value. The current value is returned, and optionally a new value may be established. The attribute is in all cases represented by a double precision value, which is interpreted according to the attribute as described below.
attr=GRF__STYLE
line style - one of
  • PLAIN
  • DASH
  • DOT
  • SHORTDASH
  • LONGDASH
  • DOTDASH
attr=GRF__WIDTH
line width - an value giving the width of drawn lines
attr=GRF__SIZE
character/marker size scale factor - 1.0 is normal size
attr=GRF__FONT
font index for drawn text. This is an integer mapped to a font by the DefaultGrfFontManager class.
attr=GRF__COLOUR
integer interpreted as a 32-bit alpha-red-green-blue value, as per the result of a encodeColor(java.awt.Color) call.

Normally bits 0-23 of the integer represent the red green and blue intensities in the usual way, and bits 24-31 represent the alpha value (0xff means opaque and 0x00 means transparent), the exception being the value opaque white which is 0x00000000.

Note this means that a 24-bit colour value along the lines 0xc0c0c0 would give you a completely transparent colour - probably not what you want. To specify normal (opaque) grey, you should use 0xffc0c0c0 or equivalantly encodeColor(Color.LIGHT_GRAY).

Specified by:
attr in interface Grf
Parameters:
attr - an integer value identifying the required attribute. One of the following:
  • GRF__STYLE - line style
  • GRF__WIDTH - line width
  • GRF__SIZE - character/marker size scale factor
  • GRF__FONT - character font
  • GRF__COLOUR - colour index
value - a new value to store for the attribute. If this is AstObject.AST__BAD no value is stored.
prim - the sort of graphics primitive to be drawn with the new attribute. One of the following:
  • GRF__LINE
  • GRF__MARK
  • GRF__TEXT
Returns:
the old value of the attribute indicated

qch

public float[] qch()
Description copied from interface: Grf
Returns the character height in world coordinates.

Specified by:
qch in interface Grf
Returns:
a two-element array: the first element gives the height of characters drawn with a vertical baseline (an increment in the X axis) and the second element gives the height of characters drawn with a horizontal baseline (an increment in the Y axis)

txExt

public float[][] txExt(String text,
                       float x,
                       float y,
                       String just,
                       float upx,
                       float upy)
Description copied from interface: Grf
Gets the extent of a character string. This method returns the corners of a box which would enclose the supplied character string if it were displayed using the text method. The returned box includes any leading or trailing spaces. The order of the corners is anti-clockwise (in world coordinates) starting at the bottom left. A null value for just is equivalent to supplying "CC". upx=upy=0 should throw an Exception.

Specified by:
txExt in interface Grf
Parameters:
text - the string to be displayed
x - the reference x coordinate
y - the reference y coordinate
just - a character string which specifies the location within the text string which is to be placed at the reference position given by x and y. The first character may be 'T' for "top", 'C' for "centre", or 'B' for "bottom", and specifies the vertical location of the reference position. Note, "bottom" corresponds to the base-line of normal text. Some characters (eg "y", "g", "p", etc) descend below the base-line. The second character may be 'L' for "left", 'C' for "centre", or 'R' for "right", and specifies the horizontal location of the reference position. If the string has less than 2 characters then 'C' is used for the missing characters.
upx - The x component of the up-vector for the text, in graphics world coordinates. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from left to right on the screen.
upy - The y component of the up-vector for the text, in graphics world coordinates. If necessary the supplied value should be negated to ensure that positive values always refer to displacements from bottom to top on the screen.
Returns:
a two-element array of arrays of doubles. The first element is the x-coordinates of the corners, and the second element is the y-coordinates

cap

public int cap(int cap,
               int value)
Description copied from interface: Grf
Indicates which abilities this Grf implementation has. This method is used by a Plot to determine if this object has given capability. Which capability is being enquired about is indicated by the value of the cap argument. According to the values of cap and val, the method should return a value indicating capability as described below:
GRF__SCALES
Return a non-zero value if it provides a working implementation of the Grf.scales() method, and zero otherwise. The value argument should be ignored.
GRF__MJUST
Return a non-zero value if the Grf.text(java.lang.String, float, float, java.lang.String, float, float) and Grf.txExt(java.lang.String, float, float, java.lang.String, float, float) methods recognise "M" as a character in the justification string. If the first character of a justification string is "M", then the text should be justified with the given reference point at the bottom of the bounding box. This is different to "B" justification, which requests that the reference point be put on the baseline of the text, since some characters hang down below the baseline. If text or txExt cannot differentiate between "M" and "B", then this method should return zero, in which case "M" justification will never be requested by Plot The value argument should be ignored.
GRF__ESC
Return a non-zero value if the Grf.text(java.lang.String, float, float, java.lang.String, float, float) and Grf.txExt(java.lang.String, float, float, java.lang.String, float, float) methods can recognise and interpret graphics escape sequences within the supplied string. Zero should be returned if escape sequences cannot be interpreted (in which case the Plot will interpret them itself if needed). The value argument should be ignored only if escape cannot be interpreted by text and txExt. Otherwise value indicates whether text and txExt should interpret escape sequences in subsequent calls. If value is non-zero then escape sequences should be interpreted by text and txExt. Otherwise they should be drawn as literal text. See GrfEscape for more information about escape sequences.

Specified by:
cap in interface Grf
Parameters:
cap - graphics capability type - one of GRF__SCALES, GRF__MJUST, GRF__ESC as described above
value - flag whose meaning is dependent on cap as described above
See Also:
GrfEscape

scales

public float[] scales()
Description copied from interface: Grf
Gets the axis scales. This function returns an array containing two values (one for each axis) which scale increments on the corresponding axis into a "normal" coordinate system in which:
  1. The axes have equal scale in terms of (for instance) millimetres per unit distance.
  2. X values increase from left to right.
  3. Y values increase from bottom to top.

Specified by:
scales in interface Grf
Returns:
a 2-element array; the first element is the scale for the X axis (Xnorm = scales[0]*Xworld) and the second element is the scale for the Y axis (Ynorm = scales[1]*Yworld)


Copyright © 2017 Central Laboratory of the Research Councils. All Rights Reserved.