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
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
 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


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