\chapter{Using Splot}

\section{Splot Basics - Getting Started}
        When splot is started the user is presented with two windows. The
left window is the drawing area where the image will be drawn. On the right
is a text window were the C\index{C} program specifying the drawing can be
displayed. The text is edited using the built in `e' editor\index{editor}
and the drawing is generated by `executing' the file, i.e. by hitting Ctrl
G or selecting the menu item `exec' at the top. Splot can be used for
drawing, graphing data or both, and since it is basically C programming,
has most of the C programming capabilities. To introduce you to the
program and demonstrate the basic concept, three simple examples are given
below. To begin, an example of a simple splot program to 
read\index{readdata} in and plot\index{plotdata} a data file using splot 
default parameters is given. The resultant drawing is shown next to it. 

{\tt
\begin{verbatim}
/* demo of simplest possible data */
/* plotting using all the defaults */

#include <splot.h>
double *data;
main()
   {
   readdata("demo\data1.dat",data);
   plotdata(data);
   label(LOWER,"Position");
   label(LEFT,"Wavelength in !m!m");
   text(6.20,22.98,"Mepsicron Calibration");
   }
\end{verbatim}
}

\vspace*{2.5cm}
\special{psfile=simple.eps hscale=35 vscale=35 hoffset=250 voffset=0}

\newpage
\noindent
        Here is a simple example of a drawing using some of the
built-in functions.

\vspace{0.5cm}

{\tt
\begin{verbatim}
/* file basic.spt */
/* Demo of a simple drawing using */
/* some built-in functions */

#include <splot.h>
main()
   {
   /* draw two boxes */
   box(6.0,20.0,11.0,16.0);
   box(6.5,19.5,8.5,18.0);
   stroke();
   /* draw two circles */
   arc(5.95,10.91,2.0,0,360);
   stroke();
   arc(8.96,10.73,1.0,0,360);
   stroke();
   /* draw a triangle */
   moveto(7.0,5.0);
   lineto(9.0,7.0);
   lineto(11.0,5.0);
   lineto(7.0,5.0);
   stroke();
   /* add some text */
   text(4.45,23.22,"Basic Drawing using defaults");
   }
\end{verbatim}
}

\vspace*{.1cm}
\special{psfile=basic.eps hscale=40 vscale=40 hoffset=250 voffset=0}

\noindent

\vspace{0.5cm}

\noindent

        Lastly, here is an example using some C programming\index{C} 
capabilities such as loops\index{symbols}. 

{\tt
\begin{verbatim}
/* This demo file shows the available symbols */
/* which can be used for data points. Symbols names */
/* equating to the numerical constants are defined */
/* in splot.h */

#include "splot.h"
main()
   {
   int i;
   /* make the symbols large. Since they are just a special font */
   /* make the font width large. */
   set(FONTWIDTH,4);
   /* change the symbol orientation just for fun */
   set(FONTDIR,30);
   moveto(1,1);
   /* show all 17 symbols in a diagonal line */
   for (i = 0;i < 17;i++)
      {
      /* use a relative move here */
      rmoveto(1,1);
      symbol(i);
      }
   /* try other form of symbol */
   set(SYMMULT,2);
   symbol(4,12,OSTAR);
   set(SYMMULT,0.5);
   /* add some extra arrows to illustrate the */
   /* arrowto() function */
   moveto(3.82,17.19);
   arrowto(7.96,15.68);
   arrowto(10.21,19.72);
   rarrowto(3,0);
   stroke();
   }
\end{verbatim}
}

\vspace*{2.5cm}
\special{psfile=symbol.eps hscale=30 vscale=30 hoffset=225 voffset=0}

\noindent
There are two ways a drawing can be made.
\begin{itemize}
\item[1] By typing in a C program text file using the built-in editor.
\item[2] By using the mouse and pull-down menus to insert commands into
the text file (see section \ref{sec:mouse}).
\end{itemize}
        Depending on which is more convenient for the task at hand, one can
either draw interactively\index{interactive drawing} with the mouse or
enter text. The drawing is only generated upon execution of the text file.

        The text editor\index{editor} that is built into Splot is a fully
featured editor with some very powerful capabilities. Ordinary operation
should, however, be very intuitive. For a description of the text editor
component of Splot refer to Chapter \ref{chap:edit}. Only a brief
introduction to give you the basics to get going is presented here. The
text cursor can be moved
using the arrow key pad or the mouse. Clicking the left mouse\index{using mouse}
button positions the text cursor at the mouse cursor location. Scrolling is
accomplished with the page up/down keys or by using the scroll bars.
A file is written to disk with the
name specified on the highlighted status line at the bottom of the text
window with a Ctrl W (write)\index{saving file} command (or use the save
menu item). To remove a file use the Ctrl Q (quit)\index{exiting program}
command (or use the quit menu item). Splot itself terminates when the last
file is removed. To add a new file to the ring of files to be edited or
executed type {\tt ``$<$esc$>$ e file.nam''} where file.nam is the name of
the desired file or select the open menu item.


\subsection{Making a Drawing}\index{making a drawing}

        In order to make a drawing it is useful to understand the 
underlying philosophy which is based on the postscript\index{postscript} 
imaging model. A very brief introduction to the postscript imaging model 
will be presented here. To make a postscript like drawing it is first 
necessary to generate a current path\index{path}. A path is built using
functions such as {\tt moveto(x1,y1);}\index{moveto} and {\tt lineto(x2,y2 
);}\index{lineto}. These functions by themselves do not cause anything to 
appear on the page. Once a current path is specified then it can be 
stroked\index{stroke} or filled\index{fill}. A path is stroked to the page 
using the current line width, style, and colour with the {\tt stroke();} 
function. This function also resets the current path to null. The current 
values of width etc. are set\index{set function} using the {\tt 
set(attribute,value);} function. It is advisable to use the predefined
values in splot.h for the attributes and values to improve readability of 
the code (The easiest thing is to select them from the pull down menu). 
Alternatively, a closed current path can be filled with the current colour
using the {\tt fill();} command. This also resets the current path to null.
At this point a virtual page in memory has been marked but the actual
physical page has not yet been affected. This allows subsequent drawing
commands to draw over what is already there. The ``paint'' is in effect
opaque. This means that it is possible to draw over something with the
colour set to white and in effect white it out\index{white out}. This can
be put to good use for fixing blemishes as shown in some of the example
files. The virtual page is transferred to the physical page using the {\tt
showpage();}\index{showpage} function or by default at the end of file execution.
However, only things within the current clip\index{clip} window
are transferred to the physical page. The crucial points to remember are 
that in order to see anything on the physical page (either on the screen or 
a printer page) a path must first be stroked or filled and then finally 
transferred using {\tt showpage();}. This imaging model is very powerful 
and allows essentially anything to be drawn given the a suite of path 
building functions. More details on these and other postscript issues can 
be found in a standard postscript reference. 

\subsection{Making Plots}\index{data, plotting}

        Splot also contains some custom functions specialized for 
generating scientific plots. These, such as {\tt plotdata( 
);}\index{plotdata}, depart from the postscript model in the sense that 
they are implicitly stroked\index{implicit stroking}. Implicitly stroked 
functions do not require a {\tt stroke();} in order to mark the page. It is 
possible to override implicit stroking by starting with a {\tt newpath( 
);}\index{newpath} command. 

        There is a function called {\tt readdata();}\index{readdata} which 
reads in tabular data\index{data, file} from a data file into an array. The 
data file must be in ASCII format with one line per data point with the x, 
y and optional aditional values each in separate columns\index{error bars}.
This data can then be drawn inside an axes box\index{axes box} using {\tt 
plotdata();} if the default tick positions, size and labelling are 
acceptable. Alternatively, custom axes boxes, tick marks and labels can be 
generated using the {\tt axes\_box();}, {\tt 
tickmarks();}\index{tickmarks}, and {\tt ticklabel( );}\index{ticklabel} 
commands followed by a {\tt drawdata();}\index{drawdata} or {\tt 
plotdata();} to draw the data points found in the data array. The 
difference between {\tt drawdata();} and {\tt plotdata();} is that {\tt 
plotdata();} will pick default values for the axes box, tickmarks or 
ticklabels if not previously explicitly specified. The plotted data uses 
the current line colour, style and width to connect the data points if an 
ordinary plot was selected. Alternatively, the current 
symbol\index{symbols} can be drawn at each data point. There is a function 
which automatically draws error bars as well as one which fits and draws 
the best straight line to a set of data points. The data points
plotted are easily restricted to those within a range of x or y values. The
data can also be shifted and scaled before plotting.

\subsection{Using The Mouse}\index{using mouse}
\label{sec:mouse}

        Clicking the left mouse button on a window changes the current 
focus if the window does not already have the input focus\index{input 
focus}. On the drawing window the left mouse button is also used to draw 
the rubber zoom box\index{zoom, box} by holding down the left mouse button. 
In the editor window double clicking brings up help or the variable value
for the item under the cursor depending on the type.
Help\index{online help} exists for function names and menu items.
Double clicking the left mouse button with the mouse on
the drawing page inserts the current x,y coordinates\index{ 
coordinates, inserting}\index{interactive drawing} into the text file at the current 
text cursor location. If the mouse was positioned at the beginning of a 
coordinate pair that coordinate pair is replaced with the new one. If the 
mouse cursor is in the text region then hitting the left mouse button will 
move the current text cursor to the mouse cursor location. The left mouse 
button is also used to select items in drop down menus\index{menus}. 

        The right mouse button is used for highlighting 
elements\index{highlighting elements}\index{finding elements} of a drawing. 
If the mouse cursor is on top of a displayed element on the drawing page 
and the right mouse button is hit then the corresponding element is 
highlighted and the text cursor jumps to the corresponding line in the text 
that generated that element. Conversely, if the mouse cursor is on the text 
window hitting the right mouse button will highlight any graphics elements 
generated by the line under the mouse cursor. This feature is very useful 
for finding the code associated with a particular element of a drawing or 
the reverse. For the pull down menus, the right mouse button
opens a help window\index{online help}. The right button help does not work
in version of NT earlier than 4.0.

        When the mouse cursor is on the drawing page the current
coordinates\index{coordinates} are printed at the top. The 
units\index{units} and origin used are those in effect at the end of the 
last program execution. The default units are cm with the origin in the 
bottom left corner of the page. Pressing the middle mouse button (or both 
the left and right mouse buttons together on two button mice) with the 
mouse pointer on the drawing page causes the current coordinate reference
point to be reset so that the status line subsequently reports 
the distance from this point if the relative\index{coordinates, relative} 
option has been selected from the misc menu. 


\subsection{Actions Associated with the Mouse Buttons}

        There are several mouse menu\index{menus} buttons along the top of 
the plot window. The action of these buttons is as follows. Starting at the
left top there are six menus labelled `Draw', `Math', `Slib', `Cnst', `SetO'
and `KeyW'.
These activate drop down menus which allow a function to be selected and
inserted into the text. The `Draw' functions are a suite of drawing
routines which cause lines, arcs, text etc. to be drawn to the page. The
`SetO' menu is a list of textual names for numerical constants which are
used in conjunction with the {\tt set();}\index{set} command to change
attributes\index{attributes, changing} of the current graphics state such
as the current colour, line width, line style, axes type, etc. Choosing set
from the list of drawing functions automatically opens a menu with only an
appropriate subset of these and is the recommended approach. The `Slib' and
`Math' menus
allows selection of a standard C library\index{C, library functions}
function. These are not required for making ordinary plots. They are however useful
for manipulating data before plotting or generating data mathematically all
from within Splot. The last button of this group `KeyW' opens a list of C
keywords\index{C, keywords} for selection. The only one of these that is of
interest for ordinary plots is `main'\index{main}. Every file that
generates a plot or drawing must start with

\vspace{5mm}

\noindent
{\it
\begin{verbatim}
#include <splot.h>
main
   {
   /* list of drawing commands go here between the braces on as many */
   /* lines as necessary */
   }
\end{verbatim}
}

\vspace{5mm}

\noindent
        This is all automatically inserted in the text by selecting
`main'. The remaining keywords in this list are only of interest
 when constructing loops or branches. Note that the actual text inserted
 for the `Draw', `Math', `Slib' and `KeyW' menu choices can be customized by editing the
 corresponding macros in the splot.cfg startup
 file.\ref{sec:config}\index{editor, macros}

        The next set of menu buttons along the top are concerned
with displaying the drawing. The default size of the drawing is one
which fits on a standard 8 x 11 inch piece of paper if printed.
However, as the screen resolution is not as good as that of
printers it is possible to zoom\index{zoom} in on part of a drawing in order to
get a better view.

\subsection{Hard Copy}\index{hard copy}

        In order to send a graph to the printer select the print option in 
the file menu of the editor window. Output can be directed to a file by 
opening the printer settings notebook and selecting 'print to file' Hard
copy is device independent and relies on the printer drivers. Splot
can also generate encapsulated postscript (.eps)\index{postscript},
metafile\index{metafile} and bitmap\index{bitmap} files
of a figure for inclusion in a document.
It is better to let Splot generate an .eps file rather than
to rely on a postscript printer driver with the output directed to a file
as the Splot generated file is much smaller. Splot also adds the required
\%\%BoundingBox statement to the generated ps file as required for
encapsulated\index{postscript, encapsulated} postscript files.


\section{Miscellaneous notes}

        A drawing can be made in either of two ways. First the drawing can 
be specified by simply typing in a C program using the built in editor. Of 
course with this editor it is easy to import components of previous 
drawings. A drawing can however also be made using the 
mouse\index{interactive drawing}. First the desired drawing function is 
selected using the drop down menus on the top row of the graphics window.
There are menu
buttons\index{menus} for the C keywords, drawing functions, miscellaneous
functions, and the defined constants. Selecting an item causes it to be
inserted in the text at the current text cursor position. Many functions
require coordinate\index{coordinates} points as parameters. These can be
entered by moving the mouse to the desired location on the drawing page and
double clicking the left mouse button. If the text cursor is currently
located at the start of a coordinate pair, that coordinate
pair\index{coordinates,changing} is erased and replaced with a new
coordinate. In this way it is
possible to draw interactively with the mouse or by entering text which
ever is more convenient for the task at hand. Parameter errors are not
detected until the file is executed using Ctrl G or the `exec' menu button.

Modifying an existing drawing can be done somewhat interactively by selecting
a previously drawn item with the right mouse button. This will cause the text
cursor to jump to the corresponding line and closest coordinate in the text.
The coordinates on this line may then be modified either by typing or double
clicking with the mouse on the new location. The utility of this method of
modifying an existing drawing depends strongly on how the drawing was made.
If the drawing was created by inserting absolute coordinates then the above
method will work well. If, however, the coordinates used are relative coordinates
or calculated coordinates then it makes no sense to replace them with absolute
coordinates.

