SECTION 2.6 - THE GRAPH WINDOW VIEW-OBJECT ROUTINES
2.6.1 INTRODUCTION
The graphics window view-object provides an area for the output of graphics. A number of routines are supplied to give access to a basic set of line plotting functions including drawing of rectangles, polygons and arcs. Filled areas may also be drawn. Symbol and text plotting functions are also available and there are two simple axis drawing routines. An option is available to produce Postscript files from the plots in order to obtain hard copies. Sections of the plot may be identified by an graphics object group identifier enabling parts of the plot to be deleted or redrawn under program control. Simple cursor input is provided. A number of options are available for defining the mapping of the user coordinates onto the window and for handling possible re-sizing of the graphics window. When plotting, a current graphics style is used; this determines the colour, the line width and the X-font to be used. This style may be changed when required.The following sets of routines are available:
Creating and Handling a Graph Window View-Object
2.6.2 CREATING AND HANDLING A GRAPH WINDOW VIEW-OBJECT
2.6.2.1 Introduction
The following routines are available:
Create a graphics window view-object - xdl_graph_win
Set mapping option - xdl_graph_win_map
Set style parameters - xdl_graph_win_style
Reset a colour - xdl_graph_win_set_colour
Draw a line - xdl_graph_win_line
Draw a polyline - xdl_graph_win_polyline
Draw a text string - xdl_graph_win_stext
Draw a text string - xdl_graph_win_xtext
Draw a symbol - xdl_graph_win_symbol
Draw polysymbols - xdl_graph_win_polysymbol
Draw a rectangle - xdl_graph_win_rectangle
Draw a polygon - xdl_graph_win_polygon
Draw an arc - xdl_graph_win_arc
Draw a horizontal axis - xdl_graph_win_ax1
Draw a vertical axis - xdl_graph_win_ax2
Get an input cursor position - xdl_graph_win_getcurs
Reset active strip message - xdl_graph_win_input_message
Reset current group id - xdl_graph_win_setid
Delete graphics objects - xdl_graph_win_delete
Calculate size requirements - xdl_graph_win_getsize
2.6.2.2 Create a graphics window view-object - xdl_graph_win
The routine xdl_graph_win (xdlf_graph_win) is used to create a new graphics window view-object. The user may specify the size of the window in pixels. The required options for handling the possible re-sizing of the graphics window are selected. On a colour display a default colour map of 8 colours (black, white, red, yellow, green, cyan, blue and magenta) is always available. If required, the user may define an additional colour map to be used to provide additional colours. Such colours need to be set via calls to the routine xdl_graph_win_set_colour (xdlf_graph_win_set_colour) before being used.
Fortran call:
CALL XDLF_GRAPH_WIN (IVH, IVHPARENT, IX, IY, ICSET, NCOLRS,
+ IGWIDTH, IGHEIGHT,
+ MINW, MINH, IEXPAND, IPOSN, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IVHPARENT (R) View-object handle for parent 0=none
(see vh_parent)
IX (R) X position (may be -1 if no parent) (see x)
IY (R) Y position (may be -1 if no parent) (see y)
ICSET (R) Colorset number for optional additional
colorset of NCOLRS colours (0 if not needed)
(see cset)
NCOLRS (R) No. of colours in additional colorset
IGWIDTH (R) Required width of graphics area in pixels
excluding border (see gr_width)
IGHEIGHT (R) Required height of graphics area in pixels
excluding border (see gr_height)
MINW (R) Minimum width of view-object in pixels
(see min_width)
MINH (R) Minimum height of view-object in pixels
(see min_height)
IEXPAND (R) Flag for handling of expanded/contracted
graphics area.
= 0, do not expand/contract
= 1, expand/contract to fit window size but
preserve ratio of axes
= 2, expand/contact in both directions to
fit window
IPOSN (R) = 0, Position in centre of window
= 1, Position at bottom left of window
IERR (W) Returns status from xdl_graph_win call
'C' call:
int xdl_graph_win (int vh, int vh_parent, int x, int y, int cset,
int ncolrs, int gr_width, int gr_height,
int min_width, int min_height,
int expand, int posn)
Parameters:
int vh; User selected view-object handle (R)
int vh_parent; View-object handle for the parent base frame,
if 0 then a base level frame is created to
enclose the graphics window view-object (R)
int x; x coordinate for the view-object.
If no parent may be -1 to give default x (R)
int y; y coordinate for the view-object.
If no parent may be -1 to give default y (R)
int cset; Colorset number for optional additional
colorset of 'ncolrs' colours. Set to 0 if not
required. The colours for this set will be
numbered from 8 upwards (with 0-7
being used for the default colours) (R)
int ncolrs; No. of colours in the additional colorset if
used (R)
int gr_width; Required width of graphics window in pixels
excluding border (R)
int gr_height; Required height of graphics window in pixels
excluding border (R)
int min_width; Minimum window width of view-object in pixels.
If this is greater than the width calculated
from the graph area width requirement etc.
then this value will be used as the window
width (R)
int min_height; Minimum window height of view-object in
pixels. If this is greater than the height
calculated from the graph area height
requirement etc. then this value will be
used as the window height (R)
int expand; Flag for handling of expanded/contracted
graphics area.
= 0, do not expand/contract
= 1, expand/contract to fit window size but
preserve ratio of axes
= 2, expand/contact in both directions to
fit window (R)
int posn; = 0, Position in centre of window
= 1, Position at bottom left of window (R)
Return: Status flag =0 OK, >0 error
bit 0 set: Requested parent not found in view-objects list
bit 1 set: Memory allocation error
2.6.2.3 Set mapping option - xdl_graph_win_map
The routine xdl_graph_win_map (xdlf_graph_win_map) is used to set the current mapping between coordinate space and display space.
Fortran call:
CALL XDLF_GRAPH_WIN_MAP (IVH, AX1_MIN, AX1_MAX, AX2_MIN, AX2_MAX,
+ DAX1_MIN, DAX1_MAX, DAX2_MIN, DAX2_MAX,
+ ITYP, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_MIN (R) Minimum axis 1 coord. in coordinate space
AX1_MAX (R) Maximum axis 1 coord. in coordinate space
AX2_MIN (R) Minimum axis 2 coord. in coordinate space
AX2_MAX (R) Maximum axis 2 coord. in coordinate space
DAX1_MIN (R) Minimum axis 1 coord. in display space
(see ityp below)
DAX1_MAX (R) Maximum axis 1 coord. in display space
(see ityp below)
DAX2_MIN (R) Minimum axis 2 coord. in display space
(see ityp below)
DAX2_MAX (R) Maximum axis 2 coord. in display space
(see ityp below)
ITYP (R) Display space type = 0 display coordinates
0.0 to 1.0 in axis 1 and
axis 2 represent the full
size of the requested
graphics window when the
graphics window object
was created.
= 1 display coordinates
0.0 to 1.0 in axis 1 and
axis 2 represent the unit
square.
IERR (W) Returns the status from xdl_graph_win_map call
'C' call:
int xdl_graph_win_map (int vh, float ax1_min, float ax1_max,
float ax2_min, float ax2_max,
float dax1_min, float dax1_max,
float dax2_min, float dax2_max, int ityp)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
float ax1_min; Minimum axis 1 coord. in coordinate space (R)
float ax1_max; Maximum axis 1 coord. in coordinate space (R)
float ax2_min; Minimum axis 2 coord. in coordinate space (R)
float ax2_max; Maximum axis 2 coord. in coordinate space (R)
float dax1_min; Minimum axis 1 coord. in display space
(see ityp below) (R)
float dax1_max; Maximum axis 1 coord. in display space
(see ityp below) (R)
float dax2_min; Minimum axis 2 coord. in display space
(see ityp below) (R)
float dax2_max; Maximum axis 2 coord. in display space
(see ityp below) (R)
int ityp; Display space type = 0 display coordinates
0.0 to 1.0 in axis 1 and
axis 2 represent the full
size of the requested
graphics window when the
graphics window object
was created.
= 1 display coordinates
0.0 to 1.0 in axis 1 and
axis 2 represent the unit
square. (R)
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.6.2.4 Set style parameters - xdl_graph_win_style
The routine xdl_graph_win_style (xdlf_graph_win_style) is used to set the current style required for the plotting. The style parameters are the colour, the line width and the X-windows font to be used.
Fortran call:
CALL XDLF_GRAPH_WIN_STYLE (IVH, IFG_COLR, LINW, IFONT, IERR)
Parameters:
IVH (R) View-object handle (see vh)
IFG_COLR (R) Foreground colour -1 = current value
0 = black
1 = white
2 = red
3 = yellow
4 = green
5 = cyan
6 = blue
7 = magenta
8 upwards (colours from additional
colorset if defined). Set via
xdl_graph_win_set_colour)
LINW (R) Line width in pixels (-1 = current value)
IFONT (R) Font type -1 = current font
1 = standard font (very small)
2 = standard font (small)
3 = standard font (medium)
4 = standard font (large)
5 = standard font (very large)
IERR (W) Returns the status from xdl_graph_win_style call
'C' call:
int xdl_graph_win_style (int vh, int fg_colr, int line_width,
int font_type)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
int fg_colr; Foreground colour -1 = current value
0 = black
1 = white
2 = red
3 = yellow
4 = green
5 = cyan
6 = blue
7 = magenta
8 upwards (colours from
additional colorset if
defined - set via
xdl_graph_win_set_colour)
(R)
int line_width; Line width in pixels (-1 = current value) (R)
int font_type; Font type -1 = current font
1 = standard font (very small)
2 = standard font (small)
3 = standard font (medium)
4 = standard font (large)
5 = standard font (very large)
(R)
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set; Memory allocation failure
2.6.2.5 Reset a colour - xdl_graph_win_set_colour
The routine xdl_graph_win_set_colour (xdlf_graph_win_set_colour) is used to reset a colour. The routine will only have an effect if a non-default colorset of additional colours is being used for the graph window view object.
Fortran call:
CALL XDLF_GRAPH_WIN_SET_COLOUR (IVH, ICOLR, IRED, IGREEN,
+ IBLUE, IERR)
Parameters: IVH (R) View-object handle (see vh) ICOLR (R) Colour number (8 upwards) (see icolr) IRED (R) Red component 0 to 65535 (see red) IGREEN (R) Green component 0 to 65535 (see green) IBLUE (R) Blue component 0 to 65535 (see blue) IERR (W) Returns status from xdl_image_set_colour call
'C' call:
int xdl_graph_win_set_colour (int vh, int icolr, int red, int blue,
int green)
Parameters: int vh; View-object handle (R) int icolr; Colour number 8 upwards (R) int red; Red component 0 to 65535 (R) int green; Green component 0 to 65535 (R) int blue; Blue component 0 to 65535 (R)
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.6.2.6 Draw a line - xdl_graph_win_line
The routine xdl_graph_win_line (xdlf_graph_win_line) is used to draw a line on a graphics window view object. The current colour and line width are used and the coordinates are based on the current mapping.
Fortran call:
CALL XDLF_GRAPH_WIN_LINE (IVH, AX1_START, AX2_START,
+ AX1_END, AX2_END, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_START (R) Start position of line axis 1 coordinate
AX2_START (R) Start position of line axis 2 coordinate
AX1_END (R) End position of line axis 1 coordinate
AX2_END (R) End position of line axis 2 coordinate
Note: Coordinates are in 'coordinate' space as set
by the mapping routine.
IERR (W) Returns the status from xdl_graph_win_line call
'C' call:
int xdl_graph_win_line (int vh, float ax1_start, float ax2_start,
float ax1_end, float ax2_end)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
float ax1_start; Start position of line axis 1 coordinate (R)
float ax2_start; Start position of line axis 2 coordinate (R)
float ax1_end; End position of line axis 1 coordinate (R)
float ax2_end; End position of line axis 2 coordinate (R)
Coordinates are in 'coordinate' space as set by
the mapping routine.
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.6.2.7 Draw a polyline - xdl_graph_win_polyline
The routine xdl_graph_win_polyline (xdlf_graph_win_polyline) is used to draw lines on a graphics window view object connecting a given series of points. The current colour and line width are used and the coordinates are based on the current mapping.
Fortran call:
CALL XDLF_GRAPH_WIN_POLYLINE (IVH, AX1_COORDS, AX2_COORDS,
+ NPOINTS, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_COORDS (R) Axis 1 coordinates
AX2_COORDS (R) Axis 2 coordinates
NPOINTS (R) No. of points
Note: Coordinates are in 'coordinate' space as set
by the mapping routine.
IERR (W) Returns the status from xdl_graph_win_polyline call
'C' call:
int xdl_graph_win_polyline (int vh, float * ax1_coords, float * ax2_coords,
int npoints)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
float ax1_coords[]; Axis 1 coordinates (R)
float ax2_coords[]; Axis 2 coordinates (R)
int npoints; No. of points (at least 2) (R)
Coordinates are in 'coordinate' space as set by
the mapping routine.
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate memory
2.6.2.8 Draw a text string - xdl_graph_win_stext
The routine xdl_graph_win_stext (xdlf_graph_win_stext) is used to draw a text string on a graphics window view object using the internal scaleable font. The current colour and line width are used and the coordinates are based on the current mapping. The current X-windows font definition is not used by this routine. Two positioning options are available and the text may be drawn at any angle required.
Fortran call:
CALL XDLF_GRAPH_WIN_STEXT (IVH, AX1_COORD, AX2_COORD,
+ XDLSTR(TXT), LENTXT,
+ SIZE1, SIZE2, ISIZOPT, ICENT,
+ ANGLE, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_COORD (R) Start position of text axis 1 coordinate
AX2_COORD (R) Start position of text axis 2 coordinate
Note: Coordinates are in 'coordinate' space as set
by mapping routine.
TXT (R) Text string
** Pass address using XDLSTR function **
LENTXT (R) Length of the text string (>0)
SIZE1 (R) Size of the characters along axis 1 (may be 0.0 if
size2 > 0.0)
SIZE2 (R) Size of the characters along axis 2 (may be 0.0 if
size1 > 0.0)
ISIZOPT (R) Character size (height) definition option
= 0 sizes are in unit square units (0.0 - 1.0)
= 1 sizes are relative to current axis mapping
If a zero size value is given then it will be
calculated from the other size assuming the
standard character shape with a height:width ratio
of 20:12
ICENT (R) = 0 position is for bottom left of text
= 1 centre text string (both directions)
ANGLE (R) Rotate text string anticlockwise by angle degrees
from the starting horizontal position (if ICENT is
0 the rotation is about the bottom left point of
the text string and if ICENT is 1 then it is about
the mid point of the string). Note: the size
calculations for the text are done before the
string is rotated.
IERR (W) Returns the status from xdl_graph_win_stext call
'C' call:
int xdl_graph_win_stext (int vh, float ax1_coord, float ax2_coord,
char * txt, int lentxt, float size1,
float size2, int sizopt, int cent,
float angle)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
float ax1_coord; Start position of text axis 1 coordinate (R)
float ax2_coord; Start position of text axis 2 coordinate (R)
Coordinates are in 'coordinate' space as set by
the mapping routine.
char *txt; Text string to be drawn (ascii) (R)
int lentxt; Length of text string (may be 0 if a null
terminated string was given) (R)
float size1; Size of the characters along axis 1 (may be 0.0 if
size2 > 0.0) (R)
float size2; Size of the characters along axis 2 (may be 0.0 if
size1 > 0.0) (R)
int sizopt; Character size definition option
= 0 sizes are in unit square units (0.0 - 1.0)
= 1 sizes are relative to current axis mapping
If a zero size value is given then it will be
calculated from the other size assuming the
standard character shape with a height:width
ratio of 20:12 (R)
int cent; = 0 position is for bottom left of text
= 1 centre text string (both directions) (R)
float angle; Rotate text string anticlockwise by angle degrees
from the starting horizontal position (if cent==0
the rotation is about the bottom left point of
the text string and if cent==1 then it is about
the mid point of the string). Note: the size
calculations for the text are done before the
string is rotated. (R)
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.6.2.9 Draw a text string - xdl_graph_win_xtext
The routine xdl_graph_win_xtext (xdlf_graph_win_xtext) is used to draw a text string on a graphics window view object using the current xdl_view standard X-windows font. The text is drawn in the current colour. Only horizontal text strings may be drawn using this routine. Two positioning options are available defined using the current coordinate mapping.
Fortran call:
CALL XDLF_GRAPH_WIN_XTEXT (IVH, AX1_COORD, AX2_COORD,
+ XDLSTR(TXT), LENTXT,
+ ICENT, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_COORD (R) Start position of text axis 1 coordinate
AX2_COORD (R) Start position of text axis 2 coordinate
Note: Coordinates are in 'coordinate' space as set
by mapping routine.
TXT (R) Text string
** Pass address using XDLSTR function **
LENTXT (R) Length of the text string (>0)
ICENT (R) = 0 position is for bottom left of text
= 1 centre text string (both directions)
IERR (W) Returns the status from xdl_graph_win_xtext call
'C' call:
int xdl_graph_win_xtext (int vh, float ax1_coord, float ax2_coord,
char * txt, int lentxt, int cent)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
float ax1_coord; Start position of text axis 1 coordinate (R)
float ax2_coord; Start position of text axis 2 coordinate (R)
Coordinates are in 'coordinate' space as set by
mapping routine.
char *txt; Text string to be drawn (ascii) (R)
int lentxt; Length of text string (may be 0 if a null
terminated string was given) (R)
int cent; = 0 position is for bottom left of text
= 1 centre text string (both directions) (R)
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.6.2.10 Draw a symbol - xdl_graph_win_symbol
The routine xdl_graph_win_symbol (xdlf_graph_win_symbol)is used to draw a symbol on a graphics window view object using one of the scaleable symbols available. The current colour and line width are used and the coordinates are based on the current mapping.
Fortran call:
CALL XDLF_GRAPH_WIN_SYMBOL (IVH, AX1_COORD, AX2_COORD, ISYMB,
+ SIZE, ISIZOPT, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_COORD (R) Symbol position axis 1 coordinate
AX2_COORD (R) Symbol position axis 2 coordinate
Note: Coordinates are in 'coordinate' space as set
by the mapping routine.
ISYMB (R) Symbol type 0 = point (single pixel)
1 = variable sized point
2 = vertical cross
3 = diagonal cross
4 = square
5 = diamond
SIZE (R) Size of the symbol (see ISIZOPT)
ISIZOPT (R) Symbol size definition option
= 0 size is in unit square units (0.0 - 1.0)
= 1 size is relative to current axis 1 axis
mapping
= 2 size is relative to current axis 2 axis
mapping
IERR (W) Returns the status from xdl_graph_win_symbol call
'C' call:
int xdl_graph_win_symbol (int vh, float ax1_coord, float ax2_coord,
int symb, float size, int sizopt)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
float ax1_coord; Symbol position axis 1 coordinate (R)
float ax2_coord; Symbol position axis 2 coordinate (R)
Coordinates are in 'coordinate' space as set by
the mapping routine.
int symb; Symbol type 0 = point (single pixel)
1 = variable sized point
2 = vertical cross
3 = diagonal cross
4 = square
5 = diamond
(R)
float size; Size of the symbol (see sizopt) (R)
int sizopt; Symbol size definition option
= 0 size is in unit square units (0.0 - 1.0)
= 1 size is relative to current axis 1 axis
mapping
= 2 size is relative to current axis 2 axis
mapping
(R)
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate memory
2.6.2.11 Draw polysymbols - xdl_graph_win_polysymbol
The routine xdl_graph_win_polysymbol (xdlf_graph_win_polysymbol) is used to draw a set of symbols on a graphics window view object for given series of points.
Fortran call:
CALL XDLF_GRAPH_WIN_POLYSYMBOL (IVH, AX1_COORDS, AX2_COORDS,
+ NPOINTS, ISYMB, SIZE, ISIZOPT, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_COORDS (R) Axis 1 coordinates
AX2_CORDS (R) Axis 2 coordinates
NPOINTS (R) No. of points
Note: Coordinates are in 'coordinate' space as set
by the mapping routine.
ISYMB (R) Symbol type 0 = point (single pixel)
1 = variable sized point
2 = vertical cross
3 = diagonal cross
4 = square
5 = diamond
SIZE (R) Size of the symbol (see ISIZOPT)
ISIZOPT (R) Symbol size definition option
= 0 size is in unit square units (0.0 - 1.0)
= 1 size is relative to current axis 1 axis
mapping
= 2 size is relative to current axis 2 axis
mapping
IERR (W) Returns the status from xdl_graph_win_polysymbol call
'C' call:
int xdl_graph_win_polysymbol (int vh, float * ax1_coords,
float * ax2_coords, int npoints, int symb,
float size, int sizopt)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
float ax1_coords[]; Axis 1 coordinates (R)
float ax2_coords[]; Axis 2 coordinates (R)
int npoints; No. of points (at least 2) (R)
int symb; Symbol type 0 = point (single pixel)
1 = variable sized point
2 = vertical cross
3 = diagonal cross
4 = square
5 = diamond
(R)
float size; Size of the symbol (see sizopt) (R)
int sizopt; Symbol size definition option
= 0 size is in unit square units (0.0 - 1.0)
= 1 size is relative to current axis 1 axis
mapping
= 2 size is relative to current axis 2 axis
mapping
(R)
Coordinates are in 'coordinate' space as set by
the mapping routine.
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate memory
2.6.2.12 Draw a rectangle - xdl_graph_win_rectangle
The routine xdl_graph_win_rectangle (xdlf_graph_win_rectangle) is used to draw a rectangle on a graphics window view object. The rectangle may be filled if desired. For an unfilled rectangle, the current colour and line width are used and for a filled rectangle, the current colour is used. The coordinates are based on the current mapping.
Fortran call:
CALL XDLF_GRAPH_WIN_RECTANGLE (IVH, AX1_START, AX2_START,
+ AX1_END, AX2_END, IFILL, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_START (R) Start corner axis 1 coordinate
AX2_START (R) Start corner axis 2 coordinate
AX1_END (R) End corner axis 1 coordinate
AX2_END (R) End corner axis 2 coordinate
Note: Coordinates are in 'coordinate' space as set
by the mapping routine.
IFILL (R) = 0 do not fill, = 1 fill
IERR (W) Returns the status from xdl_graph_win_rectangle call
'C' call:
int xdl_graph_win_rectangle (int vh, float ax1_start, float ax2_start,
float ax1_end, float ax2_end, int fill)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
float ax1_start; Start corner axis 1 coordinate (R)
float ax2_start; Start corner axis 2 coordinate (R)
float ax1_end; End corner axis 1 coordinate (R)
float ax2_end; End corner axis 2 coordinate (R)
Coordinates are in 'coordinate' space as set by
the mapping routine.
int fill; = 1 fill, = 0 do not (R)
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate memory
2.6.2.13 Draw a polygon - xdl_graph_win_polygon
The routine xdl_graph_win_polygon (xdlf_graph_win_polygon) is used to draw a polygon on a graphics window view object. The polygon may be filled if desired. The points must define a non-intersecting polygon. If the last point is not the same as the first point, the polygon will be automatically closed. For an unfilled polygon, the current colour and line width are used and for a filled polygon, the current colour is used. The coordinates are based on the current mapping.
Fortran call:
CALL XDLF_GRAPH_WIN_POLYLGON (IVH, AX1_COORDS, AX2_COORDS,
+ NPOINTS, IFILL, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_COORDS (R) Axis 1 coordinates
AX2_COORDS (R) Axis 2 coordinates
NPOINTS (R) No. of points
Note: Coordinates are in 'coordinate' space as set
by the mapping routine.
IFILL (R) = 1 fill, = 0 do not.
IERR (W) Returns the status from xdl_graph_win_polygon call
'C' call:
int xdl_graph_win_polygon (int vh, float * ax1_coords, float * ax2_coords,
int npoints, int fill)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
float ax1_coords[]; Axis 1 coordinates (R)
float ax2_coords[]; Axis 2 coordinates (R)
int npoints; No. of points (at least 3) (R)
Coordinates are in 'coordinate' space as set by
the mapping routine.
int fill; = 1 fill, = 0 do not (R)
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate memory
2.6.2.14 Draw an arc - xdl_graph_win_arc
The routine xdl_graph_win_arc (xdlf_graph_win_arc) is used to draw an arc on a graphics window view object. The arc may be filled if desired in one of two ways, either as a sector (pie slice) or as a filled chord. For an unfilled arc, the current colour and line width are used and for a filled arc, the current colour is used. The coordinates are based on the current mapping.
Fortran call:
CALL XDLF_GRAPH_WIN_ARC (IVH, AX1_CEN, AX2_CEN, RAD1, RAD2,
+ ANGLE_START, ANGLE_RANGE, IFILL, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_CEN (R) Centre position along axis 1
AX2_CEN (R) Centre position along axis 2
RAD1 (R) Radius along axis 1
RAD2 (R) Radius along axis 2
ANGLE_START (R) Start angle (degrees) (anti clockwise
from 3 o'clock)
ANGLE_RANGE (R) Angle range (anticlockwise) in degrees
IFILL (R) =0 do not fill,
=1 fill as sector (pie slice),
=2 fill chord
Note: Coordinates & radii are in 'coordinate' space
as set by the mapping routine.
IERR (W) Returns the status from xdl_graph_win_arc call
'C' call:
int xdl_graph_win_arc (int vh, float ax1_cen, float ax2_cen,
float rad1, float rad2, float angle_start,
float angle_range, int fill)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
float ax1_cen; Centre position along axis 1 (R)
float ax2_cen; Centre position along axis 2 (R)
float rad1; Radius along axis 1 (R)
float rad2; Radius along axis 2 (R)
float angle_start; Start angle (degrees) (anti clockwise from 3
o'clock) (R)
float angle_range; Angle range (anticlockwise) in degrees (R)
int fill; =0 do not fill,
=1 fill as sector (pie slice),
=2 fill chord (R)
Coordinates & radii are in 'coordinate' space
as set by the mapping routine.
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate memory
2.6.2.15 Draw a horizontal axis - xdl_graph_win_ax1
The routine xdl_graph_win_ax1 (xdlf_graph_win_ax1) is used to draw an annotated horizontal graph axis on a graphics window view object. The coordinates are based on the current mapping. Tick sizes, character sizes and annotation intevals are set by the user.
Fortran call:
CALL XDLF_GRAPH_WIN_AX1 (IVH, AX1_ORIG, AX2_ORIG, AXLEN,
+ NDIV, AX1_DIV, ND, HTICK, SIZ,
+ ISIZOPT, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_ORIG (R) Origin (axis 1) (see note)
AX2_ORIG (R) Origin (axis 2) (see note)
AXLEN (R) Axis length (see note)
NDIV (R) No. of divisions for annotation (if not use AX1_DIV)
AX1_DIV (R) Division along axis 1 for annotation if NDIV = 0
(see note)
ND (R) No. of decimal places for axis values
HTICK (R) Height of ticks (see ISIZOPT)
SIZ (R) Character height for annotation (see ISIZOPT)
ISIZOPT (R) Symbol size definition option
= 0 size is in unit square units (0.0 - 1.0)
= 1 size is relative to current axis 1 axis
mapping
= 2 size is relative to current axis 2 axis
mapping
IERR (W) Returns the status from xdl_graph_win_ax1 call
Note: Coordinates are in 'coordinate' space
as set by the mapping routine.
'C' call:
int xdl_graph_win_ax1 (int vh, float ax1_orig, float ax2_orig, float axlen,
int ndiv, float ax1_div, int nd,
float htick, float siz, int sizopt)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
float ax1_orig; Origin (axis 1) (see note) (R)
float ax2_orig; Origin (axis 2) (see note) (R)
float axlen; Axis length (see note) (R)
int ndiv; No. of divisions for annotation (if 0 then use
ax1_div) (R)
float ax1_div; Division along axis 1 for annotation if ndiv = 0
(see note) (R)
int nd; No. of decimal places for axis values (R)
float htick; Height of ticks (see sizopt) (R)
float siz; Character height for annotation (see sizopt) (R)
int sizopt; Symbol size definition option
= 0 size is in unit square units (0.0 - 1.0)
= 1 size is relative to current axis 1 axis
mapping
= 2 size is relative to current axis 2 axis
mapping (R)
Note: Coordinates are in 'coordinate' space
as set by the mapping routine.
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate memory
2.6.2.16 Draw a vertical axis - xdl_graph_win_ax2
The routine xdl_graph_win_ax2 (xdlf_graph_win_ax2) is used to draw an annotated vertical graph axis on a graphics window view object. The coordinates are based on the current mapping. Tick sizes, character sizes and annotation intevals are set by the user.
Fortran call:
CALL XDLF_GRAPH_WIN_AX2 (IVH, AX1_ORIG, AX2_ORIG, AXLEN,
+ NDIV, AX2_DIV, ND, HTICK, SIZ,
+ ISIZOPT, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_ORIG (R) Origin (axis 1) (see note)
AX2_ORIG (R) Origin (axis 2) (see note)
AXLEN (R) Axis length (see note)
NDIV (R) No. of divisions for annotation (if not use AX2_DIV)
AX2_DIV (R) Division along axis 2 for annotation if NDIV = 0
(see note)
ND (R) No. of decimal places for axis values
HTICK (R) Width of ticks (see ISIZOPT)
SIZ (R) Character height for annotation (see ISIZOPT)
ISIZOPT (R) Symbol size definition option
= 0 size is in unit square units (0.0 - 1.0)
= 1 size is relative to current axis 1 axis
mapping
= 2 size is relative to current axis 2 axis
mapping
IERR (W) Returns the status from xdl_graph_win_ax1 call
Note: Coordinates are in 'coordinate' space
as set by the mapping routine.
'C' call:
int xdl_graph_win_ax2 (int vh, float ax1_orig, float ax2_orig, float axlen,
int ndiv, float ax2_div, int nd,
float wtick, float siz, int sizopt)
Parameters:
int vh; The xdl_graph_win view-object handle (R)
float ax1_orig; Origin (axis 1) (see note) (R)
float ax2_orig; Origin (axis 2) (see note) (R)
float axlen; Axis length (see note) (R)
int ndiv; No. of divisions for annotation
(if 0 use ax2_div)(R)
float ax2_div; Division along axis 2 for annotation if ndiv = 0
(see note) (R)
int nd; No. of decimal places for axis values (R)
float wtick; Width of ticks (see sizopt) (R)
float siz; Character height for annotation (see sizopt) (R)
int sizopt; Symbol size definition option
= 0 size is in unit square units (0.0 - 1.0)
= 1 size is relative to current axis 1 axis
mapping
= 2 size is relative to current axis 2 axis
mapping (R)
Note: Coordinates are in 'coordinate' space
as set by the mapping routine.
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Unable to allocate memory
2.6.2.17 Get an input cursor position - xdl_graph_win_getcurs
The routine xdl_graph_win_getcurs (xdlf_graph_win_getcurs) is used to return an selcted cursor position. It should be called after the return from a call to xdl_get_events (xdlf_get_events) indicates that a graph window view-object has returned input. The coordinates returned are based on the current mapping.
Fortran call:
CALL XDLF_GRAPH_WIN_GETCURS (IVH, AX1_COORD, AX2_COORD, IERR)
Parameters:
IVH (R) View-object handle (see vh)
AX1_COORD (W) Returns the axis 1 coordinate value (current
mapping)
AX2_COORD (W) Returns the axis 2 coordinate value (current
mapping)
IERR (W) Returns status from xdl_graph_win_getcurs call
'C' call: int xdl_graph_win_getcurs (int vh, float * ax1_coord, float * ax2_coord)
Parameters:
int vh; View-object handle (R)
float *ax1_coord; Returns the axis 1 coordinate (current mapping)
(W)
float *ax2_coord; Returns the axis 2 coordinate (current mapping)
(W)
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.6.2.18 Reset active strip message - xdl_graph_win_input_message
The routine xdl_graph_win_input_message (xdlf_graph_win_input_message) is used to reset the message which will appear in the active strip when cursor input is requested. When the graphics window view-object is created, the default message is 'Input position'.
Fortran call:
CALL XDLF_GRAPH_WIN_INPUT_MESSAGE (IVH, XDLSTR(MESSAGE),
+ LEN, IERR)
Parameters:
IVH (R) View-object handle (see vh)
MESSAGE (R) Character string containing the message
(see message)
** Pass address using the XDLSTR function **
LEN (R) Length of the message string - must be >0
(cf len) (max 60 chars)
IERR (W) Returns status from xdl_graph_win_input_message
call
'C' call: int xdl_graph_win_input_message (int vh, char * message, int len)
Parameters:
int vh; View-object handle (R)
char *message; Message string (max of 60 chars long) (R)
int len; Length of the message string; if 0 then length
will be found assuming a null terminated string
(R)
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
2.6.2.19 Reset current group id - xdl_graph_win_setid
The routine xdl_graph_win_setid (xdlf_graph_win_setid) is used to reset the current value of the graphics objects group id. This id is associated with each graphics object drawn and enables selected sets of graphics objects to be deleted or moved under program control if required. The default starting id is 1. The valid range is from 1 to 127.
Fortran call:
CALL XDLF_GRAPH_WIN_SETID (IVH, ID, IERR)
Parameters: IVH (R) View-object handle (see vh) ID (R) Graphics objects group id (1 to 127) IERR (W) Returns status from xdl_graph_win_setid call
'C' call: int xdl_graph_win_setid (int vh, int id)
Parameters: int vh; View-object handle (R) int id; New value for graphics objects group id (1-127) (R)
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Invalid group id (not in range 1-127)
2.6.2.20 Delete graphics objects - xdl_graph_win_delete
The routine xdl_graph_win_delete (xdlf_graph_win_delete) is used to delete a set of drawn graphics objects identified by the current graphics objects group id in force when the objects were drawn. A value of zero clears all graphics objects.
Fortran call:
CALL XDLF_GRAPH_WIN_DELETE (IVH, ID, IERR)
Parameters:
IVH (R) View-object handle (see vh)
ID (R) The id of the group of graphics objects to be
deleted (0=all)
IERR (W) Returns status from xdl_graph_win_delete call
'C' call: int xdl_graph_win_delete (int vh, int id)
Parameters:
int vh; View-object handle (R)
int id; The id of the group of graphics objects to be deleted
(1-127) or 0 to delete all (R)
Return: Status = 0 OK, >0 error
bit 0 set: View-object handle not found
bit 1 set: View handle does not match view object
bit 2 set: Invalid id (not in range 0-127)
2.6.2.21 Calculate size requirements - xdl_graph_win_getsize
The routine xdl_graph_win_getsize (xdlf_graph_win_getsize) is used to get the required size for a graphics window view-object given the size of the graphics area required.
Fortran call:
CALL XDLF_GRAPH_WIN_GETSIZE (IGWIDTH, IHEIGHT, IWIDTH,
+ IHEIGHT)
Parameters: IGWIDTH (R) Width of graphics area in pixels IGHEIGHT (R) Height of graphics area in pixels IWIDTH (W) Returns the width required (see w) IHEIGHT (W) Returns the height required (see h)
'C' call: void xdl_graph_win_getsize (int gr_width, int gr_height, int * w, int * h)
Parameters:
int gr_width; Required width of graphics area in pixels
(R)
int gr_height; Required height of graphics area in
pixels (R)
int *w; Returns the width required (W)
int *h; Returns the height required (W)
Return: None
John W. Campbell
CCLRC Daresbury Laboratory
Last update 4 Feb 1998