\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 essentially all 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 and the corresponding drawing. 

\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 */
   /* input coordinates with mouse */
   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 represented by an underscore in the text window 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 clicking on the scroll fields 
along the right side of the text window. 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 were 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} or function or at the end of file execution by 
default. 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 error 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 actually 
plotted are easily restricted to those within a range of x or y values. The 
data can also easily 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 for the item under the 
cursor. Help\index{online help} exists for function names, constants and 
global data values. 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 selection lists, the right mouse button 
opens a help window\index{online help} for those items for which help is 
available. 

        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 four buttons labelled 'draw', 'sopt', 'slib' 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 
'sopt' 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' 
button allows selection of a standard C library\index{C, library functions} 
function. Most of these are math functions such as {\tt sin()}\index{math} 
and will not be 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, 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 OS/2 printer drivers. Splot 
can also generate encapsulated postscript (.eps)\index{postscript} 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. 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 when the left mouse button is doubled clicked. 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. 
