![[*]](/file/23602/PCWK0296.iso/sharewar/os2/grafika/splot/doc/function.tex/crossref.png)
, `set' Functions.)
void abox(double xsi, double ysi, double xorig, double yorig);
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. 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. abox() is implicitly stroked.
void alineto (double len, double ang);
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.
void arc(double xcen, double ycen, double rad, double alpha, double beta);
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.
void arcn(double xcen, double ycen, double rad, double alpha, double beta);
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.
void arcto(double x1, double y1, double x2, double y2, double rad);
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.
void arrowto(double x,double y,...);
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.
void ascale(int axes, double xstart, double ystart, double xend, double yend);
or
void ascale(int axes, double *data, int col,...);
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.
void axes_box(double xsi, double ysi, double xstart, double ystart double xend, double yend, double xorig, double yorig);
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.
void box(double x1, double y1, double x2, double y2);
Adds a box to the current path. The two end points of the box are (x1,y1) and (x2,y2);
Clears the screen when the program is executed. This function should not be needed for ordinary plots.
Converts the currently defined 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.
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.
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.
void curveto(double x1, double y1, double x2, double y2, double x3, double y3);
Adds a Bezier curve section 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.
void drawdata(double *data, int xcol, int ycol);
Draws the data contained in the array data in the current axes_box. The two numbers xcol and ycol are optional and are the columns of the array data that are to be used for the x-axis and y-axis data respectively. If these values are omitted 0 , 1 are assumed. 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. drawdata() is implicitly stroked.
void errorbars(int axes,double *data, int xcol, int ycol, int errcol);
Draws error bars for the data points in the array "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.
Closes the current path if not already closed and fills the interior region with the current colour as specified by the last 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.
void fitline(double *data, int xcol, int ycol,double *yint,double *slope);
Fits the best straight line to the data in the array "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:
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); or set(YRANGE, ymin, ymax); commands. Only data points within the limits will be used for the fit. fitline() is implicitly stroked.
int or double get(int option,char *str);
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 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); 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.
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.
void gsave();
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.
void label(int axis, char *label);
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,...);. label(); is implicitly stroked.
void lineto(double x,double y,...);
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.
void moveto(double x, double y);
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.
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.
void plotdata(double *data,int xcol, int ycol);
Plots the data found in array data in a box. This command chooses the scale sizes tick marks etc. to display the data which is assumed to be in order of monotonically increasing or decreasing x value order. The optional parameters xcol and ycol correspond to the column numbers (starts at zero) of the tabular array which are to be used for the x and y axis values respectively. If these parameters are omitted then the values 0 and 1 are assumed. If the default choices of plotdata are not acceptable a plot can be generated using the step by step method using axes_box(), tickmarks(), ticklabel() and drawdata(). The data must first be read in to array data using readdata( ). The valid option values are defined in splot.h. See also set() for a description of the various options. plotdata() is implicitly stroked.
void readdata(char * filename, double * data);
Reads a file of name filename and puts the data into the array "data". The file should be in ASCII format with the x data in one column and the y data values next column(s). Any line containing non numeric characters or is blank will be considered a comment and ignored. WARNING! As an optimization data is only read from disk once if the configuration parameter always_load is off. Subsequent executions use the stored data already in memory (except after a reset(). This means that if you modify the array "data" after reading in values the next time the file is executed you will get strange results. Similarly, if you reuse the same array for different plots in the same drawing you will have trouble. The motto is never change the values in the array "data". If you want to change the values declare another array and copy the values. Also remember that readdata() implicitly allocates memory for the data array so it is correct to declare the data array as double *data; at the top. If however, you are going to fill in a new array with calculated values you need to declare the array as double newdata[ysize][xsize]; so that space will be allocated.
void rarrowto(double x, double y,...);
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.
Restores all set able parameters to their default values. Clears the current path and clip path.
void rlineto(double x,double y,...);
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.
void rmoveto(double x, double y);
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.
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.
void scale(double xs, double ys);
Changes the scale of the figure by the factors specified for the x and y axes respectively. Changes in scale are cumulative.
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
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.
Marks the page in memory with the current 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.
void symbol(double x, double y, int symbolconst);
or
void symbol(int symbolconst);
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);
void text(double x, double y, char * str,int just);
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 ∧2∧ 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 ``∧_!#$'' can be printed by preceding them with \ as in \!. The combination \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.
void ticklabel(int axis, double v, char *label,...);
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();' 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,...); ticklabel() is implicitly stroked.
void tickmarks(int axis, double v,...);
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) command. 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.
void translate(double tx, double ty);
Translates the origin of the figure by the x and y distances specified. Translations are cumulative.
void whereis(double *x,double *y);
Returns the coordinates of the current point as set by the last moveto(), lineto() etc.