AtSPlot(3X)

NAME
AtSPlot -- Plot meta-class for disecting structures.

SYNOPSIS
#include <X11/At/SPlot.h>

DESCRIPTION
The AtSPlot class is a placeholder for some code and resources for plot classes that need access to application data. Its main purpose is to provide two public functions that applications use to attach data to the plot widgets, as well as support routines for the widget subclasses.

CLASSES
The class pointer is atSPlotWidgetClass, and the class name is AtSPlot. It is a subclass of the AtPlot and Object widget classes.

RESOURCES
The AtSPlot widget inherits all the resources from the AtPlot and Object widget classes. It defines no new resources.

PUBLIC FUNCTIONS

typedef enum { AtDouble, AtFloat, AtInt } AtDataType;
void AtSPlotAttachData(spw, data, type, stride, start, num);
void AtSPlotExtendData(spw, num);

	AtSPlotWidget spw;
	XtPointer data;
	AtDataType type;
	Cardinal stride, start, num;

Most subclasses of AtSPlot provide #define'd aliases for these routines.

AtSPlotAttachData()
    This routine is used to attach application data to the subclass plot widget. The widget expects num data items in an array, with stride bytes between each one. (In an array of doubles, stride will be sizeof(double); in an array of structures, the stride will be the size of the structure as returned by sizeof().) Data points to the first item in that array. Each item is of the type described in type, an enumerated type. Currently, only float, double and int are supported, but that is easily extended. All values are converted to doubles by the atSPlot routines, so the rest of the widget set works in doubles only. Each of the num items in the array is the Y value of an (X,Y) pair. The X value for the nth item in the array is start + n. This implies that there are no holes in the sequence of data. The data in the array pointed to by data should remain valid and unchanged as it may be accessed any time should PostScript output be generated or should the parent AtPlotter widget resize or change internal layout. If the application data changes, a new call to AtSPlotAttachData must be made (even with the same parameters) so that a new bounding box will be calculated and the axis scales readjusted if necessary.

AtSPlotDataExtended()
    This changes the number of datapoints in the array to num. The existing elements of the array should not have changed. If some extra data has been added to the end of the valid data (for instance because the data represents a time series and the next collection point has just occurred), then this routine will plot the extra data on the existing graph with the minimum possible recalculation and redisplay. Should this not be possible, (because the new data exceeds existing axis bounds in either X or Y axes) then the effect is the same as the equivalent call to AtSPlotAttachData().

PLOTTER ROUTINES
The following routine is mainly intended for use by subclasses of AtSPlot, but applications may find it useful. It may be implemented as a macro in some environments.

double AtSPlotGetValue(p, i)
	AtSPlotWidget p;
	Cardinal i;

Get the ith data item for the AtSPlot widget, as defined by the latest call to AtSPlotAttachData().

USAGE
The AtSPlot widget should not be instantiated. Instead, use one of the subclasses.

SEE ALSO
AtPlotter(3X), AtPlot(3X), AtLinePlot(3X), AtBarPlot(3X)
``Using The AthenaTools Plotter Widget Set''

AUTHORS
Gregory Bond, Burdett, Buckeridge and Young Ltd. (gnb@bby.oz.au) wrote the code for version V5-beta. No changes for version V6.0.

COPYRIGHT
Copyright 1991 by Burdett, Buckeridge & Young Ltd. All rights reserved. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of the firms, institutes or employers of the authors not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. THE AUTHORS AND THEIR FIRMS, INSTITUTES OR EMPLOYERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE AUTHORS AND THEIR FIRMS, INSTITUTES OR EMPLOYERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.