\chapter{Splot Library Functions}

What follows is a list of the built in draw library functions. This
document does not include information on C\index{C} in general or details of the
editor usage. Details of the standard C library functions and math library
functions can be found in the interpreter chapter \ref{chap:interp}.
Editor documentation is found in chapter \ref{chap:edit} and C
information can be found in any number of readily available texts. 

\section{Drawing Library Reference}
\subsection{Drawing Functions}\index{drawing functions}

\vspace{3mm}

\noindent
void {\bf abox}(double xsi, double ysi, double xorig, double yorig);
\index{abox}
\begin{quote}

 Adds an axes box to the current path. The box is drawn with
 a size of xsi by ysi and centered on the page. No internal
 coordinate system is set up. Use ascale() for this or use
 axes\_box() to combine both functions. All the parameters
 are optional and if present, specify the box size and
 position of the axes origin relative to the page origin. For
 the last two parameters the special constants XCENTER and
 YCENTER can be used for the x or y position coordinate
 respectively and will cause the axes box to be centered on
 the page along that axis. Using both XCENTER and YCENTER is
 equivalent to the default behaviour with the last two
 parameters absent. If no parameters are specified a default
 size of 12 by 16 cm is used and the box centered on the page.
 abox() is implicitly stroked.
\end{quote}

\vspace{3mm}

\noindent
void {\bf alineto} (double len, double ang);
\index{alineto}
\begin{quote}
        Adds a line of length len at an angle of ang with respect to the
previous line to the current path. Generates an error if there is no
previous line in the current path.
\end{quote}

\vspace{3mm}

\noindent
void {\bf arc}(double xcen, double ycen, double rad, double alpha, double beta);
\index{arc}
\begin{quote}
        Adds a circular arc of radius rad centered at (xcen, ycen) to the 
current path. The starting angle is alpha and the stopping angle is beta.
The arc is drawn in the counter clockwise direction. A straight line 
section will be added from the previous current point if any to the 
starting point of the arc. 
\end{quote}

\noindent
void {\bf arcn}(double xcen, double ycen, double rad, double alpha, double beta);
\begin{quote}
        Adds a circular arc of radius rad centered at (xcen, ycen) to the 
current path. The starting angle is alpha and the stopping angle is beta. 
The arc is drawn in the clockwise direction. A straight line section will 
be added from the previous current point if any to the starting point of 
the arc. Exactly as arc() but draws the arc in the opposite direction. 
\end{quote}

\vspace{3mm}

\noindent
void {\bf arcto}(double x1, double y1, double x2, double y2, double rad);
\begin{quote}             
        Adds a circular arc of radius rad to the current path. The center 
and angles are chosen so that the arc is tangent to the line formed by
(x1,y1) and the current point at its start and tangent to the line (x1,y1) 
- (x2,y2) at its end point. A straight line segment is added from the 
current point to the start of the arc. An error is generated is there is no
current point. 
\end{quote}


\vspace{3mm}

\noindent
void {\bf arrowto}(double x,double y,...);
\index{arrowto}
\newline
 or
\newline
\noindent
 void {\bf arrowto}(double *array,int first,int last);
\newline
 or
\newline
\noindent
 void {\bf arrowto}(double *array);

\begin{quote}
 Adds a line segment to the current path from the current
 point to (x,y). The line is terminated by drawing an arrow
 head oriented in the direction of the line. More than one
 coordinate point can be specified in the command in which
 case a series of line segments terminated by arrows
 connecting the points will be added to the current path. If
 there is no current point then an error will be generated.
 The size of the arrow head may be changed with the
 set(FONTWIDTH,...); command. The second format is a pointer
 to a 2D array of coordinate pairs followed by an optional
 pair of integers specifying the first and last pairs to be
 plotted.
\end{quote}

\vspace{3mm}
\noindent
void {\bf ascale}(int axes, double xstart, double ystart, double xend, double yend);
\index{ascale}\index{scale}
\newline
or
\newline
\noindent
void {\bf ascale}(int axes, double *data, int col,...);
\begin{quote}

        An internal coordinate system is set up for subsequent plotting of
data within the existing axes box. The x axis start and stop values are
xstart and xend respectively and ystart, yend for the y axis. for the y
axis. If the axis choice is XAXES or YAXES rather than XYAXES then only two
numbers follow the axes specifier rather than four. This allows the x and y
axes scales to be set independently of each other. The alternate format
allows for auto scaling to the specified data. There can be more than one
data array in the list in which case the scales are chosen so that they
will all fit. Each data array can optionally be followed by one or two
integers specifying which columns to use for the x and y values. If axes is
not XYAXES only one integer is allowed.

\end{quote}

\vspace{3mm}
\noindent
void {\bf axes\_box}(double xsi, double ysi, double xstart, double ystart
          double xend,
\newline
 double yend, double xorig, double yorig);
\index{axes box}
\begin{quote}
        Adds an axes box to the current path. The box is drawn with a size
of xsi by ysi and centered on the page. An internal coordinate system is
set up for subsequent plotting of data within the box. The x axis start and
stop values are xstart and xend respectively and ystart, yend for the y
axis. for the y axis. The last two parameters are optional and if present
specify the position of the axes origin relative to the page origin. For
the last two parameters the special constants XCENTER and YCENTER can be
used for the x or y position coordinate respectively and will cause the
axes box to be centered on the page along that axis. Using both XCENTER and
YCENTER is equivalent to the default behaviour with the last two parameters
absent. More flexibility is provided by the pair of functions abox() and
ascale() which provide the functionality of axes\_box() in several steps.
axes\_box() is implicitly stroked.
\end{quote}

\vspace{3mm}


\noindent
void {\bf box}(double x1, double y1, double x2, double y2);
\index{box}
\begin{quote}
        Adds a box to the current path. The two end points of the box are 
(x1,y1) and (x2,y2); 
\end{quote}

\vspace{3mm}

\noindent
void {\bf clear}();
\index{clear}
\begin{quote}
 Clears the screen when the program is executed. Also
 the list of drawable elements is deleted.
 This function should not be needed for ordinary plots.
\end{quote}

\vspace{3mm}

\noindent
void {\bf clip}()
\index{clip}
\begin{quote}
        Converts the currently defined path\index{path} into a clipping path. All
subsequent drawing operations are then clipped against this path and only
portions of the drawing on the inside of the clip path are displayed. What
is inside and what is outside depends on whether even-odd or non-zero wind
has been selected as the fill rule using a set(); If the current path is
not closed then the current path is first closed. If there is no current
path an error is generated. clip() is implicitly stroked and takes effect immediately.
\end{quote}

\vspace{3mm}

\noindent
void {\bf closepath}();
\index{closepath}
\begin{quote}
        Closes the current path. A straight line segment is added from the
current point to the start of the current path as set by the moveto() of
rmoveto() command at the beginning of the path definition. Generates an 
error if there is no current point.
\end{quote}

\vspace{3mm}

\noindent
void {\bf cmatch}(int on);
\index{cmatch}
\begin{quote}
        If the passed parameter is TRUE then it does the necessary 
translations and scaling so that the coordinate system for the page matches 
that used within the axes\_box. An error is generated if there is no current 
axes\_box. The font scale is compensated automatically for the change in 
coordinate system so that characters will still be the same size as before. 
If the parameter is FALSE then the previous unmatched coordinates will be 
restored. If there is no parameter TRUE is assumed. 
\end{quote}

\vspace{3mm}

\noindent
void {\bf curveto}(double x1, double y1, double x2, double y2, double x3, double
y3);
\index{curveto}\index{Bezier curves}
\newline
 or
\newline
\noindent
 void {\bf curveto}(double *array,int first,int last);
\newline
 or
\newline
\noindent
 void {\bf curveto}(double *array);
\begin{quote}
 Adds Bezier curve sections to the current path starting
 at the current point. The curve starts tangent to
 (xcur,ycur) - (x1,x2) and ends tangential to (x2,y2) -
 (x3,y3) at (x3,y3); An error is generated if there is no
 current point. The number of coordinate points must be
 a multiple of three else an error is generated.
 Several formats are allowed. The first is a list
 of coordinate pairs. The second format is a pointer to a 2D
 array of coordinate pairs followed by an optional pair of
 integers specifying the first and last pairs to be plotted.
\end{quote}

\vspace{3mm}

\noindent
void {\bf drawdata}(double *data, int xcol, int ycol,...);
\index{drawdata}
\begin{quote}
 Draws the data contained in the array data in the current
 axes\_box. The numbers xcol and ycol are the columns of the
 array data that are to be used for the x-axis and y-axis
 data respectively. Each row of the array data represents
 one coordinate point to be plotted. The values will be
 plotted using the internal coordinate system established by
 the the call to axes\_box. If there is no current axes box
 an error will be generated. The xcol and ycol params are
 optional. If no values are given then xcol = 0 and ycol = 1
 are assumed. For the popular case of one column of x values
 and a set of y values the whole set may be plotted using
 plotdata(data,xcol,ALL\_Y);. drawdata() is implicitly stroked.
 More than one data set with corresponding xcol and ycol may
 be specified.
\end{quote}

\vspace{3mm}

\noindent
void {\bf epsfile}(char *filename)
\index{epsfile}
\begin{quote}
 Writes the current graphics image to a file with the
 given name. The output format is encapsulated postscript.
 Such a file can be printed on a postscript printer or
 included as a graphic in many other programs. Warning! This
 command does not check if it is over writting an existing
 file.
\end{quote}

\vspace{3mm}

\noindent
void {\bf errorbars}(int axes,double *data, int xcol, int ycol, int errcol);
\index{error bars}
\begin{quote}
        Draws error bars for the data points in the array
``data''\index{data}. The first parameter is either XVALS or YVALS indicating
along which axes the error bars are to be drawn. The numbers xcol and ycol
are the columns of the array data that are to be used for the x-axis and
y-axis data respectively. Each row of the array data represents one
coordinate point to be plotted. The values will be plotted using the
internal coordinate system established by the the call to axes\_box. The
last parameter ``errcol'' is the column of the array ``data'' which holds the
size of the error for the corresponding data point in the same row. If
there is no current axes box an error will be generated. errorbars() is
implicitly stroked. \end{quote}

\vspace{3mm}

\noindent
void {\bf fill}();
\index{fill}
\begin{quote}
        Closes the current path\index{path} if not already closed and fills
the interior region with the current colour as specified by the last set(
)\index{set} call. What is inside and what is outside the path depends on
the currently chosen fill rule. The fill rule is either even-odd or
non-zero wind (the default) and is specified using a set() call. An error
is generated if there is no current path. \end{quote}

\vspace{3mm}

\noindent
void {\bf fitline}(double *data, int xcol, int ycol,double *yint,double *slope);
\index{fit line}
\begin{quote}
        Fits the best straight line to the data in the array
"data"\index{data} using the column xcol of the array as the x values and
the column ycol as the corresponding y values. The best line is drawn
constrained to the current axes box. If there is no current axes box an
error is generated. The last two parameters are the returned values giving
the y intercept and slope of the fitted line. Note that they are pointers
to doubles which must be declared at the top of the program. Given a
declaration of the form: double slope,yint;

Call fitline using:

\hspace{2cm}  {\tt fitline(data,0,1,\&yint,\&slope);}

        Assuming that the first and second column of data are the x and y
values respectively. Data points can be excluded from the fit by using the
set(XRANGE, xmin, xmax);\index{set, XRANGE} or set(YRANGE, ymin, ymax);
commands. Only data points within the limits will be used for the fit.
fitline() is implicitly stroked.

\end{quote}

\vspace{3mm}

\noindent
int or double {\bf get}(int option,char *str);
\index{get attributes}
\begin{quote}
        Returns the value of the specified option in the current graphics
state. The numerical value for single valued elements is returned by the
function otherwise the return value is 0. A text representation of the
value is optionally returned in str. If used, be sure to allocate a
character array with sufficient space for str before calling this function
as in {\tt char str[80];} at the top of the program. The valid option
values are defined in splot.h. See also set() for a description of the
various options. The returned string can be printed using the command
puts(str);\index{puts} in the program where ``str'' is the name of the array
in the call to get(). Returned numerical values can be printed using
print(value);. The second array parameter is optional and is only really
needed for getting options that are more than just a single value such as
line patterns.

\end{quote} 

\vspace{3mm}

\noindent
void {\bf grestore}();
\index{gsave/grestore}
\begin{quote}
        Pops a graphics state off the state stack thereby restoring the 
graphics state that was in effect at the time the matching gsave() was 
executed. In particular, the path, the clip path, the line styles, line 
colours etc. are restored to their previous values. 
\end{quote}

\vspace{3mm}

\noindent
void {\bf gsave}();
\begin{quote}
        Pushes the current graphics state onto the state stack. The current 
path, clip path, line style, colour etc. are saved so that they can be 
restored later using a grestore() command. 
\end{quote}

\vspace{3mm}

\noindent
void {\bf label}(int axis, char *label);
\index{label}
\begin{quote}
        Add labels to the axes box previously defined. The first parameter 
is which axis to label either BOTTOM, TOP, LEFT or RIGHT. The following 
parameter is the label to be printed. The label will be printed centered 
between the appropriate edges of the current axes box. An error is 
generated if there is no current axes box. All labels should be after 
plotdata() if used otherwise spacing from the axes may not be correct. The
spacing can also be changed using set(LABELMARG,...);\index{set, 
LABELMARG}. label(); is implicitly stroked. 

\end{quote}

\vspace{3mm}

\noindent
void {\bf legend}(double x, double y, double leng, char *label1, ...);
\index{legend}
\begin{quote}
 Creates a legend for the current axes. There should be a
 matching text label at the end of the parameter list for
 each curve plotted in the axes box. The first two parameters
 are the x and y position of the top item in the legend. The
 leng parameter is the length of the line to draw to the left
 of the text label. This line will be drawn with the same
 colour and style as was used for the data. If the data was
 plotted using the SYM\_LINES style the symbol used for the
 data is also drawn at each end of this line. If, however the
 data was plotted using the SYMBOLS style then only the
 symbol is drawn and the length parameter is ignored. The
 spacing between the line and the text labels is controlled
 using the set(LABELMARG,val); statement. The size of the
 text labels and the text label colour are determined by
 the current graphics state settings and are modified with
 the appropriate set(); command.

\end{quote}

\vspace{3mm}

\noindent
void {\bf lineto}(double x,double y,...);
\index{lineto}
\newline
 or
\newline
\noindent
 void {\bf lineto}(double *array,int first,int last);
\newline
 or
\newline
\noindent
 void {\bf lineto}(double *array);

\begin{quote}
 Adds a line segment to the current path from the current
 point to (x,y). More than one coordinate point can be
 specified in the command in which case a series of line
 segments connecting the points will be added to the current
 path. If there is no current point then an error will be
 generated. Several formats are allowed. The first is a list
 of coordinate pairs. The second format is a pointer to a 2D
 array of coordinate pairs followed by an optional pair of
 integers specifying the first and last pairs to be plotted.
\end{quote}

\vspace{3mm}

\noindent
void {\bf moveto}(double x, double y);
\index{moveto}
\begin{quote}
        Sets the current point to (x,y). Also sets the path close point to 
(x,y) for subsequent use with closepath(). Many path building commands such
as curveto() and lineto() require that a current point exist before calling 
them. 
\end{quote}

\vspace{3mm}

\noindent
void {\bf newpath}();
\index{newpath}
\begin{quote}
 Resets the current path to NULL and also causes the current
 point to be undefined. Furthermore, it turns off the
 implicit stroking of elements that are normally implicitly
 stroked such as text();. Thus using newpath(); these
 elements can be added to a path which must then be
 explicitly stroked. stroke() turns on implicit stroking
 again.
\end{quote}

\vspace{3mm}
\noindent
void {\bf plotdata}(double *data,int xcol, int ycol,...);
\index{plotdata}
\begin{quote}
 Plots the data found in array data in a box. This command
 chooses the scale sizes tick marks etc. to display the data
 The parameters xcol and ycol
 specify which columns of the array data to use for the x
 and y values respectively. The xcol and ycol params are
 optional. If no values are given then xcol = 0 and ycol = 1
 are assumed. For the popular case of one column of x values
 and a set of y values the whole set may be plotted using
 plotdata(data,xcol,ALL\_Y);. If the default choices of
 plotdata are not acceptable a plot can be generated using
 the step by step method using axes\_box(), tickmarks(),
 ticklabels() and drawdata(). The data must first be read in
 to the array data using readdata(). plotdata() is implicitly
 stroked. More than one data, xcol, ycol triplet may be
 entered in which case the auto scaling ensures that the box
 is scaled to the max of all the data sets.
\end{quote}

\vspace{3mm}
\noindent
void {\bf rarrowto}(double x, double y,...);
\index{rarrowto}
\newline
 or
\newline
\noindent
 void {\bf rarrowto}(double *array,int first,int last);
\newline
 or
\newline
\noindent
 void {\bf rarrowto}(double *array);

\begin{quote}
 Adds a line segment to the current path from the current
 point to the current point plus x, y. The line is
 terminated by drawing an arrow head oriented in the
 direction of the line. This command is identical to arrowto
 except that the displacement is specified relative to the
 current point. More than one coordinate point can be
 specified in the command in which case a series of line
 segments terminated by arrows connecting the points will be
 added to the current path. If there is no current point
 then an error will be generated. The size of the arrow
 head may be changed with the set(FONTWIDTH,...); command.
 The second format is a pointer to a 2D array of coordinate
 pairs followed by an optional pair of integers specifying
 the first and last pairs to be plotted.
\end{quote}

\vspace{3mm}
\noindent
void {\bf rarrowto}(double x1, double y1, double x2, double y2, double x3, double y3);
\index{rcurveto}
\newline
 or
\newline
\noindent
 void {\bf rcurveto}(double *array,int first,int last);
\newline
 or
\newline
\noindent
 void {\bf rcurveto}(double *array);

\begin{quote}
 This is identical to curveto() except that the list of
 coordinates are all relative distances from previous point.
 Adds Bezier curve sections to the current path starting
 at the current point. The curve starts tangent to
 (xcur,ycur) - (x1,x2) and ends tangential to (x2,y2) -
 (x3,y3) at (x3,y3); An error is generated if there is no
 current point. The number of coordinate points must be
 a multiple of three else an error is generated.
 Several formats are allowed. The first is a list
 of coordinate pairs. The second format is a pointer to a 2D
 array of coordinate pairs followed by an optional pair of
 integers specifying the first and last pairs to be plotted.
\end{quote}

\vspace{3mm}
\noindent
void {\bf reset}();
\index{reset}
\begin{quote}
        Restores all set able parameters to their default values. Clears
the current path and clip path. 
\end{quote}

\vspace{3mm}

\noindent
void {\bf rlineto}(double x,double y,...);
\index{rlineto}
\newline
 or
\newline
\noindent
 void {\bf rlineto}(double *array,int first,int last);
\newline
 or
\newline
\noindent
 void {\bf rlineto}(double *array);

\begin{quote}
 Adds a line segment to the current path from the current
 point to the current point plus x, y. This command is
 identical to lineto except that the displacement is
 specified relative to the current point. More than one
 coordinate point can be specified in the command in which
 case a series of line segments connecting the points will
 be added to the current path. If there is no current point
 then an error will be generated. Several formats
 are allowed. The first is a list of coordinate pairs. The
 second format is a pointer to a 2D array of coordinate
 pairs followed by an optional pair of integers specifying
 the first and last pairs to be plotted.

\end{quote}

\vspace{3mm}
\noindent
void {\bf rmoveto}(double x, double y);
\index{rmoveto}
\begin{quote}
        Sets the current point to the current point plus x,y. This command
is the same as moveto except that a relative move is specified. It also
sets the path close point for subsequent use with closepath(). Many path
building commands such as curveto and lineto require that a current point
exist before calling them.
\end{quote}

\vspace{3mm}
\noindent
void {\bf rspineto}(double x1, double y1, double x2, double y2,...);
\index{rsplineto}
\newline
 or
\newline
\noindent
 void {\bf rsplineto}(double *array,int first,int last);
\newline
 or
\newline
\noindent
 void {\bf rsplineto}(double *array);

\begin{quote}
 This is identical to splineto() except that the list of
 coordinates are all relative distances from previous point.
 This function accepts a list of two or more coordinate
 pairs and using the current point as the first point draws
 a cubic spline which goes through all of the given
 coordinates. It uses Bezier curves internally but
 calculates the necessary control points in order to make
 the derivative continous everywhere. An error is generated
 if there is no current point. Specifying less than two
 additional points also generates an error. Several formats
 are allowed. The first is a list of coordinate pairs. The
 second format is a pointer to a 2D array of coordinate
 pairs followed by an optional pair of integers specifying
 the first and last pairs to be plotted.
\end{quote}


\vspace{3mm}
\noindent
void {\bf rotate}(double ang);
\index{rotate}
\begin{quote}
 Rotates the figure about the
 current origin by the the angle
 specified. The angle units are
 degrees and the +ve direction
 is counterclockwise.
 Changes in rotation are cumulative.
\end{quote}

\vspace{3mm}

\noindent
void {\bf scale}(double xs, double ys);
\index{scale}
\begin{quote}
 Changes the scale of the figure
 by the factors specified for
 the x and y axes respectively.
 Changes in scale are cumulative.
\end{quote}

\vspace{3mm}

\noindent
void {\bf set}(int option, ...);
\index{set attributes}

\begin{quote}
        All set able parameters can be set using the set command. The first 
parameter specifies which option to set. The defined constants 
corresponding to valid options are defined in the header file splot.h. 
(See Section \ref{sec:set}, `set' Functions.)
\end{quote}
               
\vspace{3mm}
\noindent
void {\bf showpage}();
\index{showpage}
\begin{quote}
        Transfers the marked page created in memory by the stroke and fill
commands to the physical page. This is
 automatically done at the end of the file and thus this
 command is only needed if it is desirable to draw parts
 of the figure before the end of execution.
\end{quote}

\vspace{3mm}
\noindent
void {\bf splineto}(double x1,double y1,double x2,double y2,...);
\index{splineto}
\newline
 or
\newline
\noindent
 void {\bf splineto}(double *array,int first,int last);
\newline
 or
\newline
\noindent
 void {\bf splineto}(double *array);

\begin{quote}
 This function accepts a list of two or more coordinate
 pairs and using the current point as the first point draws
 a cubic spline which goes through all of the given
 coordinates. It uses Bezier curves internally but
 calculates the necessary control points in order to make
 the derivative continous everywhere. An error is generated
 if there is no current point. Specifying less than two
 additional points also generates an error. Several formats
 are allowed. The first is a list of coordinate pairs. The
 second format is a pointer to a 2D array of coordinate
 pairs followed by an optional pair of integers specifying
 the first and last pairs to be plotted.
\end{quote}

\vspace{3mm}

\noindent
void {\bf stroke}();
\index{stroke}
\begin{quote}
        Marks the page in memory with the current path\index{path}. The path 
coordinates are transformed using the current coordinate transformation 
matrix and the path is fleshed out using the current line width, style and 
colour in effect at the time of the stroke() command. 
\end{quote}

\vspace{3mm}

\noindent
void {\bf symbol}(double x, double y, int symbolconst);
\index{symbol}
\newline
or
\newline
\noindent
void {\bf symbol}(int symbolconst);
\begin{quote}
 Plots the symbol chosen by symbolconst at the point x,y.
 symbolconst must be one of OCIRCLE, OSQUARE, OTRIANGLE,
 ODIAMOND OSTAR, OARROW, PLUS, CROSS, MULT, CIRCLE, SQUARE,
 TRIANGLE, DIAMOND, STAR,or ARROW. If the point x,y is
 omitted the symbol is drawn at the current point as set
 by a previous moveto();. symbol() is not implicitly
 stroked so follow with a stroke();.
 The size of a symbol can be changed using set(FONTWIDTH,
 val\_in\_cm); since symbols are just a special font. The size
 relative to the current FONTWIDTH can be set using
 set(SYMMULT,mult); To use symbol() to draw data points in an
 axes box call cmatch() first to change the scale to match that
 of the axes box.

\end{quote}

\vspace{3mm}

\noindent
void {\bf text}(double x, double y, char * str,int just);
\index{text}
\begin{quote}
 Adds the text string str to the current path starting at location (x,y).
 The current font, size and orientation as set using the set() command are
 used. Super/sub scripts can be entered as $\wedge$2$\wedge$ and \_2\_ respectively.
 Letters surrounded by '!' or '\#' are printed in Greek or italics
 respectively. For example !m! generates the Greek lower case mu. The
 special characters ``$\wedge$\_!\#\$'' can be printed by preceding them with
 $\backslash$ as in $\backslash$!. The combination $\backslash$b back
 spaces by one character. Symbols may be included in the text string by
 enclosing them with \$. If the starting x,y coordinates are omitted then
 the current string is positioned one line below the previous string added
 to the path using text(). The last parameter is the justification and must
 be one of LEFT, RIGHT or CENTER. This last parameter can be omitted in
 which case the default value of LEFT will be used. text() is implicitly
 stroked.

\end{quote}

\vspace{3mm}

\noindent
void {\bf ticklabel}(int axis, double v, char *label,...);
\index{ticklabel}
\begin{quote}
        Add tick labels to the axes box previously defined. The first
parameter is which axis to label either BOTTOM, TOP, LEFT or RIGHT. The
following parameters are paired values giving the tick position in data
coordinates as established by a prior call to axes\_box() or ascale() and the text
string to be placed at that location. An error is generated if there is no
current axes box. There are several default possibilities. If `ticklabel();'
is called without any parameters then if tick marks have been generated
previously using `tickmarks();'\index{tickmarks} then they will be selectively labelled
along the left and bottom axes. If only an axis parameter is given then the 
corresponding axis tick marks if any will be labelled. If the axis 
parameter is followed by a list of numbers only they will be 
assumed to be both the tick position and the desired label. If the numbers 
are paired with strings in the parameter list then the number will be used 
as the tick label position and the string will be used as the literal 
label. The spacing between the tick labels and the axes box can be changed
using set(TICKLMARG,...);\index{set, TICKLMARG} ticklabel() is implicitly stroked.
\end{quote}

\vspace{3mm}

\noindent
void {\bf tickmarks}(int axis, double v,...);
\index{tickmarks}
\begin{quote}
        Add tick marks to the axes box previously defined. The first 
parameter is which axis either BOTTOM , TOP, LEFT, RIGHT ,XAXES or YAXES. 
The following numbers are the positions were tickmarks are to to be placed. 
The length of the ticks is set using a set(TICKLENGTH,val)\index{set, 
TICKLENGTH} command. The tickmarks will be drawn using the current linestyle 
and colour. The location of the ticks is specified in data 
coordinates as established by the prior call to axes\_box() or ascale(). An
error is generated if there is no current axes\_box. All the above
parameters are optional. The default behaviour is as follows. If all 
parameters are omitted tick marks will be automatically generated for all 
axes. If only an axis specifier is given then tick marks will be generated 
for the corresponding axis or axes. In these cases 'tickmarks();' will try 
to find reasonable positions for a set of tick marks. If this default
behaviour is unacceptable then the actual tick positions can be specified 
as a list of values following the axis specifier. If there is only one 
numeric value it is interpreted as a tick spacing. tickmarks() is
implicitly stroked. 

\end{quote} 

\vspace{3mm}

\noindent
void {\bf translate}(double tx, double ty);
\index{translate}
\begin{quote}
 Translates the origin of the 
 figure by the x and y distances
 specified. Translations are 
 cumulative.
\end{quote}

\vspace{3mm}

\noindent
void {\bf whereis}(double *x,double *y); 
\index{whereis}
\begin{quote}
        Returns  the coordinates  of the  current point  as set by the last 
moveto(), lineto() etc. 
\end{quote}

\subsection{`set' Functions}
\label{sec:set}\index{set, fucntions}
What follows is a very brief description of all the values set able using set(). 

\vspace{3mm}

\noindent
set({\bf AXESCLIP},val);
\index{set, AXESCLIP}
\begin{quote}
        If val is ON then the data values are clipped to the limits of the 
axes box. This is temporarily added to the user set clip limits if any. If 
val is OFF (the default) then the user specified clip limits from the last 
clip() call are used. 
 Alternatively the range of data values plotted can be set
 using set(XRANGE,...); set(YRANGE,...);\index{set, XRANGE} .
\end{quote}

\vspace{3mm}

\noindent
set({\bf AXESTYPE},val); 
\index{set, AXESTYPE}
\begin{quote}
        AXESTYPE may be one of the following. LINEAR (the default), LOGX, 
LOGY, LOGLOG, INVX, INVY, INVINV, INVXLOGY or LOGXINVY. The position of 
data points and tickmarks are automatically adjusted to account for the 
axes type. 
\end{quote}

\vspace{3mm}

\noindent
set({\bf CURSYMBOL},sym);
\index{set, CURSYMBOL}
\begin{quote}
        Sets the symbol to use when plotting data with symbols. sym must be
one of OCIRCLE, OSQUARE, OTRIANGLE , ODIAMOND OSTAR, OARROW, PLUS, CROSS, 
MULT, CIRCLE, SQUARE, TRIANGLE, DIAMOND, STAR, or ARROW. The default symbol 
is CIRCLE. The size of a symbol can be changed using 
set(FONTWIDTH,val\_in\_cm);\index{set, FONTWIDTH} since symbols are just a special font.
The size relative to the current FONTWIDTH can be set using 
 set(SYMMULT,mult);\index{set, SYMMULT}. 
\end{quote}  

\vspace{3mm}

\noindent
set({\bf FILLRULE},type);
\index{set, FILLRULE}
\begin{quote}
        Determines the rule to be used when filling a path. Type must be 
one of NONZWIND (default) or EVENODD. 
\end{quote}

\vspace{3mm}

\noindent
set({\bf FLATNESS},num);
\index{set, FLATNESS}
\begin{quote}
        Sets the maximum allowable error in pixels when converting a curve 
to a set of straight line segments. Smaller values of num give smother 
curves but take longer to process. The default value of num is 1.
\end{quote}  

\vspace{3mm}

\noindent
set({\bf FONT},fonttype);
\index{set, FONT}
\begin{quote}
        Sets the font type to use for subsequent text written using the 
text(); routine. font name type must be either SIMPLEX (default) or COMPLEX. 
\end{quote}  

\vspace{3mm}

\noindent
set({\bf FONTASPECT},asp);
\index{set, FONTASPECT}
\begin{quote}
        Sets the ratio of the glyph height to width used for text written
using text();. The default value is 2.0.
\end{quote}  

\vspace{3mm}

\noindent
set({\bf FONTDIR },angle);
\index{set, FONTDIR}
\begin{quote}
        Sets the rotation angle with respect to the x axis to use when 
writing text using text(); The default is 0. 
\end{quote}

\vspace{3mm}

\noindent
set({\bf FONTMULT},factor);
\index{set, FONTMULT}
\begin{quote}
        Multiplies the current font size by the given factor.
\end{quote}  

\vspace{3mm}

\noindent
set({\bf FONTWIDTH},wid);
\index{set, FONTWIDTH}
\begin{quote}
        Sets the average width of the characters written using text(). The 
default value is 0.7 cm. FONTWIDTH applies also to symbols. 
\end{quote}  

\vspace{3mm}

\noindent
set({\bf LABELMARG},val);
\index{set, LABELMARG}
\begin{quote}
        Adds an additional amount to the margin between the plot and the 
plot labels generated using the "label();" command. val = 0 is the default. 
\end{quote}

\vspace{3mm}

\noindent
set({\bf LINECAP},type);
\index{set, LINECAP}
\begin{quote}
        Determines how thick lines are to be terminated. The allowed types 
are BUTTCAP (default), ROUNDCAP and PROJCAP. 
\end{quote}  

\vspace{3mm}

\noindent
set({\bf LINECOLOUR},col); 
\index{set, LINECOLOUR}
\begin{quote}
        Where col is one of BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN or
WHITE. This set the colour to use when the current path is stroked or 
filled. The default colour is BLACK with the background WHITE. 
\end{quote}

\vspace{3mm}

\noindent
set({\bf LINEJOIN},type);
\index{set, LINEJOIN}
\begin{quote}
        Determines how thick lines are joined together. The allowed join 
types are MITERJOIN (default), BEVELJOIN and ROUNDJOIN. 
\end{quote}  

\vspace{3mm}

\noindent
set({\bf LINESTYLE},pattern,...);
\index{set, LINESTYLE}
\begin{quote}
 Sets the line style to use for the path when it is 
 stroked. The constant LINESTYLE is followed by a list of
 floating point values that define the pattern. The values 
 are interpreted as the length along the path that the line
 is visible followed by the length that it is invisible as 
 an alternating sequence wrapping back to the beginning 
 when the pattern reaches the end. For example a pattern of
 1.0,1.0 implies on for 1 cm followed by off for 1 cm. A 
 pattern of 1.0,0.5 is on for 1 cm followed by off for 0.5 
 cm. The predefined patterns are: SOLID 0 (default) DASHED 
 1.0,0.5 DOTTED 0.2,0.2 and DOTDASH 1.0,0.5,0.2,0.5. There 
 must always be an even number of comma separated values in 
 a pattern definition. 
\end{quote}

\vspace{3mm}

\noindent
set({\bf LINEWIDTH},width); 
\index{set, LINEWIDTH}
\begin{quote}
        Sets the LINEWIDTH to width cm (default 0.05 cm). This line width is 
used when the current path is stroked. 
\end{quote}

\vspace{3mm}

\noindent
set({\bf MITERLIMIT},maxratio);
\index{set, MITERLIMIT}
\begin{quote}
        Sets the maximum length of spikes formed by miter joining two lines 
at an acute angle. If the ratio of the length of the spike to the width 
exceeds the value of maxratio then a BEVELJOIN is done instead. The default 
value is 10.0. 
\end{quote}  

\vspace{3mm}

\noindent
set({\bf PAGEROT},flag);
\index{set, PAGEROT}
\begin{quote}
 Selects landscape orientation if flag is ON. Default is portrait.
\end{quote}

\vspace{3mm}

\noindent
set({\bf PATTOFF},offset);
\index{set, PATTOFF}
\begin{quote}
 Sets the offset into the current LINESTYLE\index{set, LINESTYLE} pattern. Can be
 used to adjust the starting point of a pattern for aesthetic
 reasons.
\end{quote}

\vspace{3mm}

\noindent
set({\bf PLOTTYPE},type);
\index{set, PLOTTYPE}
\begin{quote}
        Sets the current plot type. type must be one of LINES (default), 
SYMBOLS or SYM\_LINES. LINES connects data points with line segments while
SYMBOLS causes the current symbol to be drawn at each data point. SYM\_LINES
does both. The size of a symbol can be changed using set(FONTWIDTH, 
val\_in\_cm); since symbols are just a special font. The size
relative to the current FONTWIDTH can be set using set(SYMMULT,mult);. 
\end{quote}  

\vspace{3mm}

\noindent
set({\bf SCALEALL},val);
\index{set, SCALEALL}
\begin{quote}
        If val is ON then the XSHIFT, YSHIFT, XMULT, YMULT values are
applied to all coordinates (i.e. in lineto, moveto etc.). The default is OFF
in which case only data plotted using plotdata(); or drawdata(); is affected by
these values.
\end{quote}

\vspace{3mm}

\noindent
set({\bf SCRIPTSCALE},val);
\index{set SCRIPTSCALE}
\begin{quote}
        Sets the relative height of a super/sub script as compared to
ordinary text. The default value is 0.5.
\end{quote}

\vspace{3mm}

\noindent
set({\bf SCRIPTSHIFT},val);
\index{set SCRIPTSHIFT}
\begin{quote}
        Sets the distance that a super/sub script is shifted above/below 
ordinary text. The value is specified as a fraction of the ordinary text height.
The default value is 0.7.
\end{quote}


\vspace{3mm}

\noindent
set({\bf SYMMULT},val)
\index{set, SYMMULT}
\begin{quote}
 Sets the symbol size multiplier used when drawing symbols.
 The default value is 1.0. The actual symbol size is 
 determined the current FONTWIDTH multiplied by the curent
 SYMMULT value.
\end{quote}


\vspace{3mm}

\noindent
set({\bf TICKLENGTH},len);
\index{set, TICKLENGTH}
\begin{quote}
        Sets the length of axis tick marks to be used. The default value is
0.3 cm.
\end{quote}

\vspace{3mm}

\noindent
set({\bf TICKLMARG},val);
\index{set TICKMARG}
\begin{quote}
        This value corresponds to the margin used between the axes box and 
any tick labels generated using the ticklabel(); command. val = 0 is
the default.
\end{quote}

\vspace{3mm}

\noindent
\index{set, XMULT}
set({\bf XMULT},xmul);
\begin{quote}
   Causes each x value to be multiplied by xmul before being plotted. 
\end{quote}  

\vspace{3mm}

\noindent
set({\bf XRANGE},xmin,ymin);
\index{set, XRANGE}
\begin{quote}
        data plotted using drawdata is constrained to have x values between 
xmin and xmax. There is also a corresponding YRANGE set option. The default
is no constraints. The values should be specified in user coordinates i.e. 
those established by the current axes\_box() or ascale().
\end{quote}

\vspace{3mm}

\noindent
set({\bf XSHIFT},xshft);
\index{set, XSHIFT}
\begin{quote}
   Causes the value xshft to be added to all x values before plotting. 
\end{quote}  

\vspace{3mm}

\noindent
set({\bf YSHIFT},yshft);
\begin{quote}
   Causes the value yshft to be added to all y values before plotting. 
\end{quote}  

\vspace{3mm}

\noindent
set({\bf YMULT},ymul);
\begin{quote}
   Causes each y value to be multiplied by ymul before being plotted. 
\end{quote}

