home *** CD-ROM | disk | FTP | other *** search
/ The Pier Shareware 6 / The_Pier_Shareware_Number_6_(The_Pier_Exchange)_(1995).iso / 035 / splot122.zip / DOC / USING.TEX < prev   
Text File  |  1994-09-22  |  17KB  |  360 lines
  1. \chapter{Using Splot}
  2.  
  3. \section{Splot Basics - Getting Started}
  4.         When splot is started the user is presented with two windows. The 
  5. left window is the drawing area where the image will be drawn. On the right 
  6. is a text window were the C\index{C} program specifying the drawing can be 
  7. displayed. The text is edited using the built in 'e' editor\index{editor} 
  8. and the drawing is generated by `executing' the file, i.e. by hitting CTRL 
  9. G or selecting the menu item `exec' at the top. Splot can be used for 
  10. drawing, graphing data or both, and since it is basically C programming, 
  11. has essentially all the C programming capabilities. To introduce you to the 
  12. program and demonstrate the basic concept, three simple examples are given 
  13. below. To begin, an example of a simple splot program to 
  14. read\index{readdata} in and plot\index{plotdata} a data file using splot 
  15. default parameters is given. The resultant drawing is shown next to it. 
  16.  
  17. {\tt
  18. \begin{verbatim}
  19. /* demo of simplest possible data */
  20. /* plotting using all the defaults */
  21.  
  22. #include <splot.h>
  23. double *data;
  24. main()
  25.    {
  26.    readdata("demo\data1.dat",data);
  27.    plotdata(data);
  28.    label(LOWER,"Position");
  29.    label(LEFT,"Wavelength in !m!m");
  30.    text(6.20,22.98,"Mepsicron Calibration");
  31.    }
  32. \end{verbatim}
  33. }
  34.  
  35. \vspace*{2.5cm}
  36. \special{psfile=simple.eps hscale=35 vscale=35 hoffset=250 voffset=0}
  37.  
  38. \newpage
  39. \noindent
  40.         Here is a simple example of a drawing using some of the 
  41. built-in functions and the corresponding drawing. 
  42.  
  43. \vspace{0.5cm}
  44.  
  45. {\tt
  46. \begin{verbatim}
  47. /* file basic.spt */
  48. /* Demo of a simple drawing using */
  49. /* some built-in functions */
  50.  
  51. #include <splot.h>
  52. main()
  53.    {
  54.    /* draw two boxes */
  55.    box(6.0,20.0,11.0,16.0);
  56.    box(6.5,19.5,8.5,18.0);
  57.    stroke();
  58.    /* draw two circles */
  59.    /* input coordinates with mouse */
  60.    arc(5.95,10.91,2.0,0,360);
  61.    stroke();
  62.    arc(8.96,10.73,1.0,0,360);
  63.    stroke();
  64.    /* draw a triangle */
  65.    moveto(7.0,5.0);
  66.    lineto(9.0,7.0);
  67.    lineto(11.0,5.0);
  68.    lineto(7.0,5.0);
  69.    stroke();
  70.    /* add some text */
  71.    text(4.45,23.22,"Basic Drawing using defaults");
  72.    }
  73. \end{verbatim}
  74. }
  75.  
  76. \vspace*{.1cm}
  77. \special{psfile=basic.eps hscale=40 vscale=40 hoffset=250 voffset=0}
  78.  
  79. \noindent
  80.  
  81. \vspace{0.5cm}
  82.  
  83. \noindent
  84.  
  85.         Lastly, here is an example using some C programming\index{C} 
  86. capabilities such as loops\index{symbols}. 
  87.  
  88. {\tt
  89. \begin{verbatim}
  90. /* This demo file shows the available symbols */
  91. /* which can be used for data points. Symbols names */
  92. /* equating to the numerical constants are defined */
  93. /* in splot.h */
  94.  
  95. #include "splot.h"
  96. main()
  97.    {
  98.    int i;
  99.    /* make the symbols large. Since they are just a special font */
  100.    /* make the font width large. */
  101.    set(FONTWIDTH,4);
  102.    /* change the symbol orientation just for fun */
  103.    set(FONTDIR,30);
  104.    moveto(1,1);
  105.    /* show all 17 symbols in a diagonal line */
  106.    for (i = 0;i < 17;i++)
  107.       {
  108.       /* use a relative move here */
  109.       rmoveto(1,1);
  110.       symbol(i);
  111.       }
  112.    /* try other form of symbol */
  113.    set(SYMMULT,2);
  114.    symbol(4,12,OSTAR);
  115.    set(SYMMULT,0.5);
  116.    /* add some extra arrows to illustrate the */
  117.    /* arrowto() function */
  118.    moveto(3.82,17.19);
  119.    arrowto(7.96,15.68);
  120.    arrowto(10.21,19.72);
  121.    rarrowto(3,0);
  122.    stroke();
  123.    }
  124. \end{verbatim}
  125. }
  126.  
  127. \vspace*{2.5cm}
  128. \special{psfile=symbol.eps hscale=30 vscale=30 hoffset=225 voffset=0}
  129.  
  130. \noindent
  131. There are two ways a drawing can be made.
  132. \begin{itemize}
  133. \item[1]. by typing in a C program text file using the built-in editor.
  134. \item[2]. by using the mouse and pull-down menus to insert commands into
  135. the text file (see section \ref{sec:mouse}).
  136. \end{itemize}
  137.         Depending on which is more convenient for the task at hand, one can 
  138. either draw interactively\index{interactive drawing} with the mouse or 
  139. enter text. The drawing is only generated upon execution of the text file. 
  140.  
  141.         The text editor\index{editor} that is built into Splot is a fully 
  142. featured editor with some very powerful capabilities. Ordinary operation 
  143. should, however, be very intuitive. For a description of the text editor 
  144. component of Splot refer to Chapter \ref{chap:edit}. Only a brief 
  145. introduction to give you the basics to get going is presented here. The 
  146. text cursor represented by an underscore in the text window can be moved 
  147. using the arrow key pad or the mouse. Clicking the left mouse\index{using mouse} 
  148. button positions the text cursor at the mouse cursor location. Scrolling is 
  149. accomplished with the page up/down keys or by clicking on the scroll fields 
  150. along the right side of the text window. A file is written to disk with the 
  151. name specified on the highlighted status line at the bottom of the text 
  152. window with a CTRL W (write)\index{saving file} command (or use the save 
  153. menu item). To remove a file use the CTRL Q (quit)\index{exiting program} 
  154. command (or use the quit menu item). Splot itself terminates when the last 
  155. file is removed. To add a new file to the ring of files to be edited or 
  156. executed type {\tt '$<$esc$>$ e file.nam'} where file.nam is the name of 
  157. the desired file or select the open menu item. 
  158.  
  159.  
  160. \subsection{Making a Drawing}\index{making a drawing}
  161.  
  162.         In order to make a drawing it is useful to understand the 
  163. underlying philosophy which is based on the postscript\index{postscript} 
  164. imaging model. A very brief introduction to the postscript imaging model 
  165. will be presented here. To make a postscript like drawing it is first 
  166. necessary to generate a current path\index{path}. A path is built using 
  167. functions such as {\tt moveto(x1,y1);}\index{moveto} and {\tt lineto(x2,y2 
  168. );}\index{lineto}. These functions by themselves do not cause anything to 
  169. appear on the page. Once a current path is specified then it can be 
  170. stroked\index{stroke} or filled\index{fill}. A path is stroked to the page 
  171. using the current line width, style, and colour with the {\tt stroke();} 
  172. function. This function also resets the current path to null. The current 
  173. values of width etc. are set\index{set function} using the {\tt 
  174. set(attribute,value);} function were it is advisable to use the predefined 
  175. values in splot.h for the attributes and values to improve readability of 
  176. the code (The easiest thing is to select them from the pull down menu). 
  177. Alternatively a closed current path can be filled with the current colour 
  178. using the {\tt fill();} command. This also resets the current path to null. 
  179. At this point a virtual page in memory has been marked but the actual 
  180. physical page has not yet been affected. This allows subsequent drawing 
  181. commands to draw over what is already there. The "paint" is in effect 
  182. opaque. This means that it is possible to draw over something with the 
  183. colour set to white and in effect white it out\index{white out}. This can 
  184. be put to good use for fixing blemishes as shown in some of the example 
  185. files. The virtual page is transferred to the physical page using the {\tt 
  186. showpage();}\index{showpage} or function or at the end of file execution by 
  187. default. However, only things within the current clip\index{clip} window 
  188. are transferred to the physical page. The crucial points to remember are 
  189. that in order to see anything on the physical page (either on the screen or 
  190. a printer page) a path must first be stroked or filled and then finally 
  191. transferred using {\tt showpage();}. This imaging model is very powerful 
  192. and allows essentially anything to be drawn given the a suite of path 
  193. building functions. More details on these and other postscript issues can 
  194. be found in a standard postscript reference. 
  195.  
  196. \subsection{Making Plots}\index{data, plotting}
  197.  
  198.         Splot also contains some custom functions specialized for 
  199. generating scientific plots. These, such as {\tt plotdata( 
  200. );}\index{plotdata}, depart from the postscript model in the sense that 
  201. they are implicitly stroked\index{implicit stroking}. Implicitly stroked 
  202. functions do not require a {\tt stroke();} in order to mark the page. It is 
  203. possible to override implicit stroking by starting with a {\tt newpath( 
  204. );}\index{newpath} command. 
  205.  
  206.         There is a function called {\tt readdata();}\index{readdata} which 
  207. reads in tabular data\index{data, file} from a data file into an array. The 
  208. data file must be in ASCII format with one line per data point with the x, 
  209. y and optional error values each in separate columns\index{error bars}. 
  210. This data can then be drawn inside an axes box\index{axes box} using {\tt 
  211. plotdata();} if the default tick positions, size and labelling are 
  212. acceptable. Alternatively, custom axes boxes, tick marks and labels can be 
  213. generated using the {\tt axes\_box();}, {\tt 
  214. tickmarks();}\index{tickmarks}, and {\tt ticklabel( );}\index{ticklabel} 
  215. commands followed by a {\tt drawdata();}\index{drawdata} or {\tt 
  216. plotdata();} to draw the data points found in the data array. The 
  217. difference between {\tt drawdata();} and {\tt plotdata();} is that {\tt 
  218. plotdata();} will pick default values for the axes box, tickmarks or 
  219. ticklabels if not previously explicitly specified. The plotted data uses 
  220. the current line colour, style and width to connect the data points if an 
  221. ordinary plot was selected. Alternatively, the current 
  222. symbol\index{symbols} can be drawn at each data point. There is a function 
  223. which automatically draws error bars as well as one which fits and draws 
  224. the best straight line to a set of data points. The data points actually 
  225. plotted are easily restricted to those within a range of x or y values. The 
  226. data can also easily be shifted and scaled before plotting. 
  227.  
  228. \subsection{Using The Mouse}\index{using mouse}
  229. \label{sec:mouse}
  230.  
  231.         Clicking the left mouse button on a window changes the current 
  232. focus if the window does not already have the input focus\index{input 
  233. focus}. On the drawing window the left mouse button is also used to draw 
  234. the rubber zoom box\index{zoom, box} by holding down the left mouse button. 
  235. In the editor window double clicking brings up help for the item under the 
  236. cursor. Help\index{online help} exists for function names, constants and 
  237. global data values. Double clicking the left mouse button with the mouse on 
  238. the drawing page inserts the current x,y coordinates\index{ 
  239. coordinates, inserting}\index{interactive drawing} into the text file at the current 
  240. text cursor location. If the mouse was positioned at the beginning of a 
  241. coordinate pair that coordinate pair is replaced with the new one. If the 
  242. mouse cursor is in the text region then hitting the left mouse button will 
  243. move the current text cursor to the mouse cursor location. The left mouse 
  244. button is also used to select items in drop down menus\index{menus}. 
  245.  
  246.         The right mouse button is used for highlighting 
  247. elements\index{highlighting elements}\index{finding elements} of a drawing. 
  248. If the mouse cursor is on top of a displayed element on the drawing page 
  249. and the right mouse button is hit then the corresponding element is 
  250. highlighted and the text cursor jumps to the corresponding line in the text 
  251. that generated that element. Conversely, if the mouse cursor is on the text 
  252. window hitting the right mouse button will highlight any graphics elements 
  253. generated by the line under the mouse cursor. This feature is very useful 
  254. for finding the code associated with a particular element of a drawing or 
  255. the reverse. For the pull down selection lists, the right mouse button 
  256. opens a help window\index{online help} for those items for which help is 
  257. available. 
  258.  
  259.         When the mouse cursor is on the drawing page the current 
  260. coordinates\index{coordinates} are printed at the top. The 
  261. units\index{units} and origin used are those in effect at the end of the 
  262. last program execution. The default units are cm with the origin in the 
  263. bottom left corner of the page. Pressing the middle mouse button (or both 
  264. the left and right mouse buttons together on two button mice) with the 
  265. mouse pointer on the drawing page causes the current coordinate reference 
  266. point to be reset so that the status line subsequently reports 
  267. the distance from this point if the relative\index{coordinates, relative} 
  268. option has been selected from the misc menu. 
  269.  
  270.  
  271. \subsection{Actions Associated with the Mouse Buttons}
  272.  
  273.         There are several mouse menu\index{menus} buttons along the top of 
  274. the plot window. The action of these buttons is as follows. Starting at the 
  275. left top there are four buttons labelled 'draw', 'sopt', 'slib' and 'keyw'. 
  276. These activate drop down menus which allow a function to be selected and 
  277. inserted into the text. The 'draw' functions are a suite of drawing 
  278. routines which cause lines, arcs, text etc. to be drawn to the page. The 
  279. 'sopt' menu is a list of textual names for numerical constants which are 
  280. used in conjunction with the {\tt set();}\index{set} command to change 
  281. attributes\index{attributes, changing} of the current graphics state such 
  282. as the current colour, line width, line style, axes type, etc. Choosing set 
  283. from the list of drawing functions automatically opens a menu with only an 
  284. appropriate subset of these and is the recommended approach. The 'slib' 
  285. button allows selection of a standard C library\index{C, library functions} 
  286. function. Most of these are math functions such as {\tt sin()}\index{math} 
  287. and will not be required for making ordinary plots. They are however useful 
  288. for manipulating data before plotting or generating data mathematically all 
  289. from within Splot. The last button of this group 'keyw' opens a list of C 
  290. keywords\index{C, keywords} for selection. The only one of these that is of 
  291. interest for ordinary plots is 'main'\index{main}. Every file that 
  292. generates a plot or drawing must start with 
  293.  
  294. \vspace{5mm}
  295.  
  296. \noindent
  297. {\it
  298. \begin{verbatim}
  299. #include <splot.h>
  300. main
  301.    {
  302.    /* list of drawing commands go here between the braces on as many */
  303.    /* lines as necessary */
  304.    }
  305. \end{verbatim}
  306. }
  307.  
  308. \vspace{5mm}
  309.  
  310. \noindent
  311.         This is all automatically inserted in the text by selecting 
  312. 'main'. The remaining keywords in this list are only of interest 
  313.  when constructing loops or branches. Note that the actual text inserted 
  314.  for the draw, slib and keyw menu choices can be customized by editing the
  315.  corresponding macros in the splot.cfg startup 
  316.  file.\ref{sec:config}\index{editor, macros}
  317.  
  318.         The next set of menu buttons along the top are concerned 
  319. with displaying the drawing. The default size of the drawing is one 
  320. which fits on a standard 8 x 11 inch piece of paper if printed. 
  321. However, as the screen resolution is not as good as that of 
  322. printers it is possible to zoom\index{zoom} in on part of a drawing in order to 
  323. get a better view. 
  324.  
  325. \subsection{Hard Copy}\index{hard copy}
  326.  
  327.         In order to send a graph to the printer select the print option in 
  328. the file menu of the editor window. Output can be directed to a file by 
  329. opening the printer settings notebook and selecting 'print to file' Hard 
  330. copy is device independent and relies on the OS/2 printer drivers. Splot 
  331. can also generate encapsulated postscript (.eps)\index{postscript} files
  332. of a figure for inclusion in a document. 
  333. It is better to let Splot generate an .eps file rather than
  334. to rely on a postscript printer driver with the output directed to a file
  335. as the Splot generated file is much smaller. Splot also adds the required
  336. \%\%BoundingBox statement to the generated ps file as required for 
  337. encapsulated\index{postscript, encapsulated} postscript files.
  338.  
  339.  
  340. \section{Miscellaneous notes}
  341.  
  342.         A drawing can be made in either of two ways. First the drawing can 
  343. be specified by simply typing in a C program using the built in editor. Of 
  344. course with this editor it is easy to import components of previous 
  345. drawings. A drawing can however also be made using the 
  346. mouse\index{interactive drawing}. First the desired drawing function is 
  347. selected using the drop down menus on the top row. There are menu 
  348. buttons\index{menus} for the C keywords, drawing functions, miscellaneous 
  349. functions, and the defined constants. Selecting an item causes it to be 
  350. inserted in the text at the current text cursor position. Many functions 
  351. require coordinate\index{coordinates} points as parameters. These can be 
  352. entered by moving the mouse to the desired location on the drawing page and 
  353. double clicking the left mouse button. if the text cursor is currently 
  354. located at the start of a coordinate pair, that coordinate 
  355. pair\index{coordinates,changing} is erased and replaced with a new 
  356. coordinate when the left mouse button is doubled clicked. In this way it is 
  357. possible to draw interactively with the mouse or by entering text which 
  358. ever is more convenient for the task at hand. Parameter errors are not 
  359. detected until the file is executed using CTRL G or the 'exec' menu button. 
  360.