uk.ac.starlink.ast

Interface Grf

All Known Implementing Classes:

DefaultGrf

public interface Grf

Interface for specifying graphics implementations used by Plots. Each Plot owns an object which implements this interface and uses it to do the actual graphical output. Implementations of Grf are expected to keep track of all the graphics written to them (i.e. line, mark and text calls) and be able actually to paint all resulting graphics so far requested onto a given graphics context at any time in response to a call of the paint method.

Version:

$Id$

Author:

Mark Taylor (Starlink)

Field Summary

Fields

Modifier and Type	Field and Description
static int	GRF__COLOUR Symbolic attribute type indicating colour index.
static int	GRF__ESC Symbolic capability type indicating escape sequence recognition.
static int	GRF__FONT Symbolic attribute type indicating character font.
static int	GRF__LINE Symbolic primitive type indicating lines.
static int	GRF__MARK Symbolic primitive type indicating markers.
static int	GRF__MJUST Symbolic capability type indicating M-type justification.
static int	GRF__SCALES Symbolic capability type indicating a working scales() method.
static int	GRF__SIZE Symbolic attribute type indicating character/marker size scale factor.
static int	GRF__STYLE Symbolic attribute type indicating line style.
static int	GRF__TEXT Symbolic primitive type indicating text.
static int	GRF__WIDTH Symbolic attribute type indicating line width.

Method Summary

Modifier and Type	Method and Description
double	attr(int attr, double value, int prim) Enquires or sets a graphics attribute value.
int	cap(int cap, int value) Indicates which abilities this Grf implementation has.
void	clear() Clears all known graphics.
void	flush() Flushes all pending graphics to the output device.
void	line(int n, float[] x, float[] y) Draws a polyline (a set of connected lines).
void	mark(int n, float[] x, float[] y, int type) Displays markers at the given positions.
void	paint(Graphics g2) Paints the graphics written to this Grf object since its construction or the last call of clear into the graphics context given.
float[]	qch() Returns the character height in world coordinates.
float[]	scales() Gets the axis scales.
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.
float[][]	txExt(String text, float x, float y, String just, float upx, float upy) Gets the extent of a character string.

Field Detail

GRF__STYLE

static final int GRF__STYLE

Symbolic attribute type indicating line style.

GRF__WIDTH

static final int GRF__WIDTH

Symbolic attribute type indicating line width.

GRF__SIZE

static final int GRF__SIZE

Symbolic attribute type indicating character/marker size scale factor.

GRF__FONT

static final int GRF__FONT

Symbolic attribute type indicating character font.

GRF__COLOUR

static final int GRF__COLOUR

Symbolic attribute type indicating colour index.

GRF__LINE

static final int GRF__LINE

Symbolic primitive type indicating lines.

GRF__MARK

static final int GRF__MARK

Symbolic primitive type indicating markers.

GRF__TEXT

static final int GRF__TEXT

Symbolic primitive type indicating text.

GRF__ESC

static final int GRF__ESC

Symbolic capability type indicating escape sequence recognition.

GRF__MJUST

static final int GRF__MJUST

Symbolic capability type indicating M-type justification.

GRF__SCALES

static final int GRF__SCALES

Symbolic capability type indicating a working scales() method.

Method Detail

paint

void paint(Graphics g2)

Paints the graphics written to this Grf object since its construction or the last call of clear into the graphics context given.

Parameters:

g2 - the graphics context. It will be cast to a Graphics2D, but hopefully it will be one of those anyway.

clear

void clear()

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.

flush

void flush()
    throws Exception

Flushes all pending graphics to the output device.

Throws:

Exception - an Exception may be thrown if there is an error

line

void line(int n,
          float[] x,
          float[] y)
   throws Exception

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.

Parameters:

n - the number of points to plot

x - an array of n x-coordinates

y - an array of n y-coordinates

Throws:

Exception - an Exception may be thrown if there is an error

mark

void mark(int n,
          float[] x,
          float[] y,
          int type)
   throws Exception

Displays markers at the given positions. Nothing should be done if n is less than 2, or if x or y are null.

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

Throws:

Exception - an Exception may be thrown if there is an error

text

void text(String text,
          float x,
          float y,
          String just,
          float upx,
          float upy)
   throws Exception

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.

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.

Throws:

Exception - an Exception may be thrown if there is an error

attr

double attr(int attr,
            double value,
            int prim)
     throws Exception

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; the meaning of this is determined by, and should be documented by, the Grf implementation.

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

Throws:

Exception - an Exception may be thrown if there is an error

qch

float[] qch()
     throws Exception

Returns the character height in world coordinates.

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)

Throws:

Exception - an Exception may be thrown if there is an error

txExt

float[][] txExt(String text,
                float x,
                float y,
                String just,
                float upx,
                float upy)
         throws Exception

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.

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

Throws:

Exception - an Exception may be thrown if there is an error

scales

float[] scales()
        throws Exception

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.

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)

Throws:

Exception

Since:

V3.2

cap

int cap(int cap,
        int value)

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 scales() method, and zero otherwise. The value argument should be ignored.

GRF__MJUST

Return a non-zero value if the text(java.lang.String, float, float, java.lang.String, float, float) and 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 text(java.lang.String, float, float, java.lang.String, float, float) and 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.

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

Since:

V3.2

See Also:

GrfEscape