SciPlot Widget Programmer's Reference

• Viewing this document
• Usage
• Color
• Fonts
• Point Styles
• Line Styles
• Postscript Output
• New Resources
• Public Functions
  • Refresh Functions
  • Color Functions
  • Data Manipulation Functions
  • Graph Control Functions
  • Hardcopy/Output Functions
• Bugs

• Back to SciPlot home page

Viewing this document

This programmer's reference for the SciPlot widget uses HTML3 tables, support for which is becoming very common among WWW browsers. Both Netscape and Mosaic (the most common browsers) support tables, and support for tables in Chimera (my browser of choice) will be included in version 2.0.

Usage

To use the SciPlot widget in an application, include the three source code files SciPlot.c, SciPlot.h, and SciPlotP.h with the rest of the source code for the application. Include the object SciPlot.o in the Makefile rule that compiles the application.

If it is important for the widget to respond to Motif keyboard traversal or any events while in a Motif program, define the keyword "MOTIF" for the C compiler. In a Makefile, a commom place to put this definition is in a variable called "DEFINES". The line in the Makefile would look like this:

DEFINES=-DMOTIF

In source code that uses the SciPlot widget, include the following two header files before references to the plot widget:

#include <X11/Intrinsic.h>

#include "SciPlot.h"

This example creates a 250x250 polar plot widget as a child of parent, using degrees as the angle measurement unit.

Data is plotted on the graph in groups called lists. Each list consists of a group of coordinates that will be connected together by a drawn line, and share the same point style, point color, line style, line color and legend label. Data is added to the widget using convenience functions only. There is no current provision to add data via the argument list.

An example using one of the convenience functions is given below:

double rlist[]={14.,18.,22.,26.,SCIPLOT_SKIP_VAL,30.,34.,38.,42.};

double tlist[]={30.,60.,90.,120.,SCIPLOT_SKIP_VAL,150.,180.,270.,355.};

int line1;

line1=SciPlotListCreateFromDouble(plotWidget,

9,rlist,tlist,

"List 1");

The variable line1 is the identifier of the list that will be needed to modify the list by the other convenience functions that operate on lists.

This example adds a list to be plotted in plotWidget. If plotWidget was created using the call to XtVaCreateManagedWidget above, the line would be added to a polar plot, where the angles in tlist would be interpreted as degrees.

Note that this example includes the new feature of skipping over a blank space in the line. There will not be a line segment connecting the point (26,120) to (30,150).

There are other convenience functions to specify colors and styles of the points and lines drawn in the Plot widget, as well as functions to pick the colors used and others to update previously defined lists. See Public Functions below for descriptions of all of the convenience functions.

Color

The SciPlot widget fully supports color on displays which also support color. By default, two colors are allocated at creation time: black for the foreground, and white for the background. For the SciPlot widget to use any other color, one of the color convenience functions must be used to allocate a color in the global colormap.

Colors are indicated by an integer returned from the color allocation convenience functions. The two default colors occupy the first two spaces in the color table, where the default background (white) is number 0, and the default foreground (black) is number 1.

Fonts

Fonts used by the SciPlot widget are referenced using special notation. This non-standard notation was used to be able to easily convert between PostScript and X11 notation, and as a result, only a subset of the fonts that are available in both X11 and PostScript are available.

Fonts are referenced by using predefined keywords to indicate the typeface, style, and point size. Each keyword is an integer value defined in SciPlot.h, and a complete font definition is created by logically or-ing keywords together.

Supported fonts and styles are listed below:

Font Name	Description
XtFONT_TIMES	Times
XtFONT_COURIER	Courier (monospaced font)
XtFONT_HELVETICA	Helvetica
XtFONT_LUCIDA	Lucida
XtFONT_LUCIDASANS	Lucida Sans Serif
XtFONT_NCSCHOOLBOOK	New Century Schoolbook

Style Name	Description
XtFONT_BOLD	Bold
XtFONT_ITALIC	Italic
XtFONT_BOLD_ITALIC	Bold and Italic

A font is specified by logically or-ing together these keywords, plus the size in points.

Some examples follow:

12 point Times, bold:

XtFONT_TIMES|XtFONT_BOLD|12

10 point Courier:

XtFONT_COURIER|10

16 point Lucida, bold and italic:

XtFONT_LUCIDA|XtFONT_BOLD_ITALIC|16

Note that XtFONT_BOLD_ITALIC is simply shorthand for XtFONT_BOLD|XtFONT_ITALIC

Point Styles

The SciPlot widget is capable of drawing markers at each data point. There are 19 predefined point marker definitions:

Style Name	Description
XtMARKER_NONE	no point marker drawn
XtMARKER_CIRCLE	open circle
XtMARKER_SQUARE	square
XtMARKER_UTRIANGLE	triangle (pointing up)
XtMARKER_DTRIANGLE	triangle (pointing down)
XtMARKER_LTRIANGLE	triangle (pointing left)
XtMARKER_RTRIANGLE	triangle (pointing right)
XtMARKER_DIAMOND	diamond
XtMARKER_HOURGLASS	hourglass shape
XtMARKER_BOWTIE	bowtie shape
XtMARKER_FCIRCLE	filled variants of the above...
XtMARKER_FSQUARE
XtMARKER_FUTRIANGLE
XtMARKER_FDTRIANGLE
XtMARKER_FLTRIANGLE
XtMARKER_FRTRIANGLE
XtMARKER_FDIAMOND
XtMARKER_FHOURGLASS
XtMARKER_FBOWTIE

Line Styles

For each list in the SciPlot widget, one of the following styles may be used to draw the lines that connect each point in the list:

Style Name	Description
XtLINE_NONE	no line (only points drawn)
XtLINE_SOLID	solid line (the default)
XtLINE_DOTTED	dotted line
XtLINE_WIDEDOT	widely spaced dotted line

Postscript Output

Encapsulated PostScript (EPS) files of the plot displayed in the SciPlot widget may be generated. These files are suitable for printing or importing into documents that can handle the EPS format. Color is ignored when creating the EPS files, however.

New Resources

Resources for the SciPlot widget are documented below, also showing the default values.

Name	Class	Type	Default
XtNaxisFont	XtCSciPlotFont	int	XtFONT_TIMES|10
XtNchartType	XtCMargin	int	XtCARTESIAN
XtNdegrees	XtCBoolean	Boolean	True
XtNdefaultMarkerSize	XtCInt	int	3
XtNdrawMajor	XtCBoolean	Boolean	True
XtNdrawMajorTics	XtCBoolean	Boolean	True
XtNdrawMinor	XtCBoolean	Boolean	True
XtNdrawMinorTics	XtCBoolean	Boolean	True
XtNlabelFont	XtCSciPlotFont	int	XtFONT_TIMES|18
XtNlegendLineSize	XtCMargin	int	16
XtNlegendMargin	XtCMargin	int	3
XtNmargin	XtCMargin	int	5
XtNmonochrome	XtCBoolean	Boolean	False
XtNplotTitle	XtCString	String	"Plot"
XtNshowLegend	XtCBoolean	Boolean	True
XtNshowTitle	XtCBoolean	Boolean	True
XtNshowXLabel	XtCBoolean	Boolean	True
XtNshowYLabel	XtCBoolean	Boolean	True
XtNtitleFont	XtCSciPlotFont	int	XtFONT_HELVETICA|24
XtNtitleMargin	XtCMargin	int	8
XtNxAxisNumbers	XtCBoolean	Boolean	True
XtNyAxisNumbers	XtCBoolean	Boolean	True
XtNxLabel	XtCString	String	"X Axis"
XtNyLabel	XtCString	String	"Y Axis"
XtNxLog	XtCBoolean	Boolean	False
XtNyLog	XtCBoolean	Boolean	False
XtNyNumbersHorizontal	XtCBoolean	Boolean	True
XtNxOrigin	XtCBoolean	Boolean	False
XtNyOrigin	XtCBoolean	Boolean	False

XtNchartType

Specifies a the type of chart to be drawn. Currently, two types are available: XtCARTESIAN = cartesian (X-Y) plot, XtPOLAR = polar plot.

XtNdegrees

Sets the type of angular unit measurement: True=degrees, False=radians.

XtNdefaultMarkerSize

Size of the point style markers in pixels.

XtNdrawMajor

Controls the display of major gridlines.

XtNdrawMajorTics

Controls the display of major tic marks on the axes.

XtNdrawMinor

Controls the display of minor gridlines.

XtNdrawMinorTics

Controls the display of minor tic marks on the axes.

XtNlabelFont

Names the font for use on the axis labels, as well as the numbers that mark the scale for each axis.

XtNlegendLineSize

The length (in pixels) of the small lines used to show the line style and color in the legend box.

XtNlegendMargin

Sets the border margin (in pixels) between the legend box outline and anything contained in it. Also controls the spacing between the line sample and the text, and the vertical spacing between legend entries.

XtNmargin

The spacing (in pixels) of the plot with the border of the widget.

XtNmonochrome

Ignores any colors specified in any lists, and draws only in the foreground and background colors of the widget.

XtNplotTitle

This is the title of the plot that is drawn along the lower border of the widget.

XtNshowLegend

If True, the legend block is drawn.

XtNshowTitle

If True, the plot title is drawn.

XtNshowXLabel

If True, the X axis (or the polar axis) label is drawn.

XtNshowYLabel

If True, the Y axis label is drawn.

XtNtitleFont

This font is used for the title of the plot.

XtNtitleMargin

Spacing (in pixels) between the plot and the title.

XtNxLabel

XtNyLabel

(Cartesian only.)

Sets the label for each axis.

XtNxAxisNumbers

XtNyAxisNumbers

(Cartesian only.)

Controls whether the axis numbers are displayed for the corresponding axis. XtNxAxisNumbers also controls the display of the radial numbers in a polar plot.

XtNxLog

XtNyLog

(Cartesian only.)

Controls the logarithmic scales of the X and Y axes. If either of the resources is set to True, the corresponding axis will display in logarithmic units. Note that log axes cannot display numbers less than or equal to zero, so only points with values on that axis greater than zero will be plotted.

XtNyNumbersHorizontal

(Cartesian only.)

If True, then the y axis numbers will be drawn horizontally, somewhat decreasing the area available for showing the plot, but more like a standard scientific plot.

Public Functions

The SciPlot widget uses an abstracted type "real" for its internal representation of floating point values. By default, it is typedeffed to float. Some of the convenience functions may depend on this real data type, but in general, separate functions will be provided depending upon a data type of float or double.

Note that any changes to the widget are not reflected until a call to the public function SciPlotUpdate(). This includes any of the functions that add or remove lists, or change plot styles. Any changes accomplished through XtVaSetValues, however, automatically updates the widget.

• Refresh Functions

  void SciPlotUpdate(w)

  Widget w;

  This function simply causes a recalculation of all internal parameters, and redraws the plot. Call this function after adding, deleting, or changing lists to force the Widget to redraw itself.

  Boolean SciPlotQuickUpdate(w)

  Widget w;

  This is an alternate function to redraw the widget. It is provided mainly as a tool to use the SciPlot as a realtime display, because it does not clear the entire widget. Some flicker may still appear, but only in the graph region. The static areas (labels and legend) will not flicker.

  This function does not adjust the axis ranges, unlike SciPlotUpdate(). It returns a boolean that indicates if all points are within the current axis ranges.

• Color Functions

  int SciPlotAllocNamedColor(w,name)

  Widget w;

  char *name;

  Attempts to allocate a color in the widget's colormap by using the standard X color name database.

  Returns a unique integer color ID greater than 1 if successful in allocating the named color. If unsuccessful, it returns a 1, which is the default foreground color black.

  int SciPlotAllocRGBColor(w,r,g,b)

  Widget w;

  int r,g,b;

  Tries to allocate the color named by the r, g, and b parameters. Note that these are integers ranging from 0 to 255, not 0 to 65535 as in X functions.

  As the previous function, it returns a number greater than 1 indicating that it found and allocated the new color. If it returns 1, it could not allocate the color, and returned the value for the default foreground.

  int SciPlotStoreAllocatedColor(w,p)

  Widget w;

  Pixel p;

  Stores the previously allocated color p and returns the SciPlot color index corresponding to this color.

  void SciPlotSetBackgroundColor(w,color)

  Widget w;

  int color;

  Sets the background color of the widget to the color specified. Note that the color ID number is obtained from one of the two functions SciPlotAllocNamedColor or SciPlotAllocRGBColor.

  void SciPlotSetForegroundColor(w,color)

  Widget w;

  int color;

  Sets the default foreground color to the color specified. (See the note about color IDs above.) This color is used as the default for the axis and legend box lines, as well as all of the text that appears in the widget. PostScript output remains in monochrome, however.

• Data Manipulation Functions

  Remember, you must call SciPlotUpdate() before your changes will be visible in the widget!

  int SciPlotListCreateDouble(w,num,xlist,ylist,legend)

  Widget w;

  int num;

  double *xlist,*ylist;

  char *legend;

  Creates a list from the data given in the arrays xlist and ylist. Both arrays must have num entries. The parameter legend is the name of this list, and is drawn in the legend box. The initial colors (for both the points and the line) are set to black, the initial point style is set to a square, and the initial line style is solid.

  Returns an ID number for the newly created list.

  int SciPlotListCreateFloat(w,num,xlist,ylist,legend)

  Widget w;

  int num;

  float *xlist,*ylist;

  char *legend;

  Same as SciPlotListCreateDouble, except takes arrays of type float.

  int SciPlotListAddDouble(w,list_id,num,xlist,ylist)

  Widget w;

  int list_id,num;

  double *xlist,*ylist;

  Appends the new data contained in the arrays xlist and ylist to the data in the list referenced by list_id. Both xlist and ylist must be arrays of type double, and have num parameters.

  Note that the list to be updated may have been originally created with any of the creation convenience functions, not only with the functions that require type double. It is the type of the new data that matters.

  int SciPlotListAddFloat(w,list_id,num,xlist,ylist)

  Widget w;

  int list_id,num;

  float *xlist,*ylist;

  char *legend;

  Same as SciPlotListAddDouble, but takes arrays of type float.

  void SciPlotListUpdateDouble(w,list_id,num,xlist,ylist)

  Widget w;

  int list_id,num;

  double *xlist,*ylist;

  Replaces the data in the list referenced by list_id with the new data contained in the arrays xlist and ylist. Both xlist and ylist must be arrays of type double, and have num parameters. Note that the list to be updated may have been originally created with any of the creation convenience functions, not only with the functions that require type double.

  void SciPlotListUpdateFloat(w,list_id,num,xlist,ylist)

  Widget w;

  int list_id,num;

  float *xlist,*ylist;

  Same as SciPlotListUpdateDouble, but takes arrays of type float.

  int SciPlotListDelete(w,list_id)

  Widget w;

  int list_id;

  Deletes the list referenced by the ID number list_id.

  void SciPlotListSetStyle(w,list_id,pcolor,pstyle,lcolor,lstyle)

  Widget w;

  int list_id;

  int pstyle,pcolor,lstyle,lcolor;

  Sets the styles of the list with an ID number of list_id. See the sections Color , Point Styles and Line Styles for descriptions of the available options.

• Graph Control Functions

  Remember, you must call SciPlotUpdate() before your changes will be visible in the widget!

  void SciPlotSetXAutoScale(w)

  Widget w;

  (Cartesian only.)

  Forces the widget to automatically scale the X axis based on the minimum and maximum values determined from all of the lists.

  void SciPlotSetXUserScale(w,min,max)

  Widget w;

  double min,max;

  (Cartesian only, and not in logarithmic mode.)

  Forces the widget to display the X axis range based on the specified minimum and maximum values.

  void SciPlotSetYAutoScale(w)

  Widget w;

  (Cartesian only.)

  Forces the widget to automatically scale the Y axis based on the minimum and maximum values determined from all of the lists.

  void SciPlotSetYUserScale(w,min,max)

  Widget w;

  double min,max;

  (Cartesian only, and not in logarithmic mode.)

  Forces the widget to display the Y axis range based on the specified minimum and maximum values.

• Hardcopy/Output Functions

  Boolean SciPlotPSCreate(w,filename)

  Widget w;

  char *filename;

  This function generates an Encapsulated PostScript file of the current contents of the plot widget, sized to fit on an entire page. Colors are ignored, producing a PostScript file that is black and white only.

  The filename parameter should include the pathname, if required.

  Returns True indicating that the file was successfully created. Any error in file creation or in the subsequent writes to the file will cause the subroutine to return False.

  Boolean SciPlotPSCreateColor(w,filename)

  Widget w;

  char *filename;

  Similar to SciPlotPSCreate, but creates a color Encapsulated PostScript file instead of black and white.

  void SciPlotExportData(w,fd)

  Widget w;

  FILE *fd;

  Writes to the file (must already by opened) referenced by fd a summary of the state of the SciPlot widget. The columns of data are separated by tab characters, so with minor editing, the file generated should be importable by many commercial graphing programs.

Bugs