# 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"

To create the SciPlot widget, use the following code as an example:

plotWidget=XtVaCreateManagedWidget("plot2",
  sciplotWidgetClass,parent,
  XtNheight, 250,
  XtNwidth, 250,
  XtNplotTitle, "Demo of Plot Widget",
  XtNxLabel, "X Axis (units)",
  XtNyLabel, "Y Axis (units)",
  XtNchartType, XtPOLAR,
  XtNdegrees, True,
  NULL);

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

The font selection algorithm isn't as robust as it should be when trying to choose a replacement for a font; specifically, when the user requests a font or a size that doesn't exist in the X server.

SciPlot : Programmer's Reference | Demo Programs
ListTree : Programmer's Reference

Web Page Design by Rob McMullen
E-mail: rwmcm@mail.ae.utexas.edu
Updated: 4 Sep 96