AtAxisCore(3X)

NAME
AtAxisCore -- the guts of all the Axis widget classes

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

DESCRIPTION
The AtAxisCore widget class is the root of all axis widget classes in the AtPlotter widget set. It is a meta-class and should not be instantiated by applications. Instead, one of the subclasses should be used. The subclass provides all the calculation of XtNmin, XtNmax and XtNticInterval resources, as well as deciding the (user-space) position of the tics and subtics and the labels associated with each tic. The AtAxisCore code then handles all the conversions to pixel locations as well as drawing the axis on the screen and in PostScript. Hence all the resources that determine the appearance of the axis are part of the AtAxisCore class. Each axis object consists of the following components:

-   A line that represents the actual axis. This line is drawn using the resources inherited from the AtPlot class. The "inside" of the axis is the side that faces the main plotting area; the other side (towards the edge of the graph widget) is called the "outside". And who said computers were confusing?

-   An optional line that represents the frame of the actual axis. This line is drawn using the resources from the axis line on the opposite side of the axis on the plotting area.

-   An optional line that represents the origin of the axis. This line also is drawn using the resources from the axis line. Of course, this line can only be drawn if the origin (0.0) is located within the axis range.

-   An optional label associated with the axis. This label is displayed outside the axis, and outside the tic labels (if any). The color and style information for the axis is independently set.

-   A set of tics. Each tic can be marked on the inside and/or outside of the axis line, and is drawn in the same style and color as the axis.

-   A set of labels associated with each tic. The color, size and style of these labels can be set. These labels are known as numbers in the resource names (i.e. XtNdrawNumbers et al.). They can be either inside or outside the axis, or hidden completely.

-   A grid and optionally a subgrid. These are drawn in the same color as the main axis but with dotted lines. A grid line is drawn at each tic position if the XtNdrawGrid resource is True. A subgrid line is drawn at each subtic position if the XtNdrawSubgrid resource is True.

-   There may be subtics associated with each tic that divides the interval between tics (if the axis subclass supports them). Like tics, they are drawn in the same color as the main axis, and may be inside and/or outside the axis. All axis widget classes must be children of an AtPlotter widget; it is a fatal error to create them as children of another class.

CLASSES
The class pointer is atAxisCoreWidgetClass, and the class name is AtAxisCore. It is a subclass of AtPlot and Object.

RESOURCES
The AtAxisCore widget inherits all the resources from the AtPlot and Object widget classes. In addition, AtAxisCore has the following new resources:
AtAxis Resources
Name | Class | Type | Default
XtNaxisColor | XtCForeground | XtRPixel | XtDefaultForeground
XtNaxisWidth | XtCAxisWidth | XtRDimension | 1
XtNdrawFrame | XtCDrawFrame | XtRBoolean | True
XtNdrawGrid | XtCDrawGrid | XtRBoolean | True
XtNdrawNumbers | XtCDrawNumbers | XtRBoolean | True
XtNdrawOrigin | XtCDrawOrigin | XtRBoolean | True
XtNdrawSubgrid | XtCDrawSubgrid | XtRBoolean | False
XtNfontFamily | XtCFontFamily | XtRString | dynamic
XtNlabel | XtCLabel | XtRString | NULL
XtNlabelColor | XtCForeground | XtRPixel | XtDefaultForeground
XtNlabelSize | XtCFontSize | XtRFontSize | AtFontNORMAL
XtNlabelStyle | XtCFontStyle | XtRFontStyle | AtFontPLAIN
XtNmax | XtCMax | XtRDouble | 1.0
XtNmin | XtCMin | XtRDouble | 0.0
XtNmirror | XtCMirror | XtRBoolean | False
XtNnumberColor | XtCForeground | XtRPixel | XtDefaultForeground
XtNnumberSize | XtCFontSize | XtRFontSize | AtFontSMALL
XtNnumberStyle | XtCFontStyle | XtRFontStyle | AtFontPLAIN
XtNnumberWidth | XtCNumberWidth | XtRDimension | 0
XtNnumbersOutside | XtCNumbersOutside | XtRBoolean | True
XtNrangeCallback | XtCCallback | XtRCallback | NULL
XtNsubticLength | XtCTicLength | XtRDimension | 2
XtNticInterval | XtCTicInterval | XtRDouble | 1.0
XtNticLength | XtCTicLength | XtRDimension | 5
XtNticsInside | XtCTicsInside | XtRBoolean | False
XtNticsOutside | XtCTicsOutside | XtRBoolean | True
XtNvertical | XtCVertical | XtRBoolean | False

XtNaxisColor
    Specifies the color of the axis, origin and frame lines.

XtNaxisWidth
    Specifies the width of the axis, origin and frame lines in pixels.

XtNdrawFrame
    Specifies whether a frame line should be drawn at the opposite side of the axis line on the plotting area.

XtNdrawGrid
    Specifies whether dotted lines should be drawn at each tic mark perpendicular to the axis across the plotting region. If True, it creates a "graph paper" effect.

XtNdrawNumbers
    Specifies whether the axis tic labels should be displayed.

XtNdrawOrigin
    Specifies whether a line should be drawn at the origin of the axis.

XtNdrawSubgrid
    Specifies whether dotted lines should be drawn at each subtic mark perpendicular to the axis across the plotting region.

XtNfontFamily
    Specifies the font family to use for the axis. All strings on this axis come from this family. The default value is the value of the XtNfontFamily resource of the parent AtPlotter widget.

XtNlabel
    Specifies the string to display as the axis label. Specifying an empty string (or NULL) will disable the label on the axis, reclaiming the space for the main graph area.

XtNlabelColor
    Specifies the color of the axis label.

XtNlabelSize
    Specifies the initial font size for the axis label.

XtNlabelStyle
    Specifies the initial font style for the axis label.

XtNmax
    Specifies the maximum value to be displayed on the axis.

XtNmin
    Specifies the minimum value to be displayed on the axis.

XtNmirror
    Specifies whether the axis should be drawn as a mirror image of its "normal" configuration. A "normal" axis is drawn on the left or bottom of the plotting region (i.e. an X or Y axis). An axis with this resource set to True would be appropriate for the top or right of a a plotting area (i.e. an X2 axis or a Y2 axis). The AtPlotter widget requires the value of this resource to be set as appropriate. Once the widget is created, this resource cannot be changed.

XtNnumberColor
    Specifies the color of the tic labels.

XtNnumberSize
    Specifies the initial font size used for the tic labels.

XtNnumberStyle
    Specifies the initial font style used for the tic labels.

XtNnumberWidth
    Specifies the number of pixels that should be reserved for the numbers. The default value 0 means the number width will be calculated automatically.

XtNnumbersOutside
    If True, this resource specifies that the tic labels will be drawn "outside" the axis. Otherwise, they will be drawn inside the axis (and hence overwrite (or be overwritten by) the main graph elements). If the XtNdrawNumbers resource is False, this resource has no effect.

XtNrangeCallback
    This callback routine is called as the last stage of determining the min and max resource for this axis. The called routine can change the calculated min and max values if required. See the section on CALLBACKS below.

XtNsubticLength
    Specifies the length in pixels of the subtic marks. This many pixels are drawn on the "outside" or "inside" of the axis, or both, or neither depending on the state of the XtNticsOutside and XtNticsInside resources.

XtNticInterval
    Specifies the interval (in the user coordinate system, not pixels) between tics.

XtNticLength
    Specifies the length in pixels of the tic marks. This many pixels are drawn on the "outside" or "inside" of the axis, or both, or neither depending on the state of the XtNticsOutside and XtNticsInside resources.

XtNticsInside
    Specifies whether tic and subtic marks should be drawn on the "inside" of the axis.

XtNticsOutside
    Specifies whether tic and subtic marks should be drawn on the "outside" of the axis.

XtNvertical
    Specifies whether the axis is to be drawn vertically. If this resource is set to False, the axis will be drawn horizontally. The AtPlotter widget required the correct value of this resource as appropriate if the axis is one of the currently used axes. It cannot be changed after the widget is created.

PUBLIC ROUTINES
These routines are intended primarily for use by other elements of the AtPlotter widget set, but may be of use to application writers.

void AtAxisGetBounds(w, minp, maxp);
AtScale *AtAxisGetScale(w);
Dimension AtAxisGetNumberWidth(w);
AtTransform AtAxisGetTransform(w);
	AtAxisCoreWidget w;
	double *minp, *maxp;

AtAxisGetBounds()
    Returns in the pointed-to doubles the min and max of this axis as it is currently displayed. Is the equivalent of doing XtGetValues for the XtNmin and XtNmax resources.

AtAxisGetNumberWidth()
    Calculates and returns the width of the numbers.

AtAxisGetScale()
    Returns the AtScale object that this axis is using to scale plots on the screen.

AtAxisGetTransform()
    Returns the type of transform for this axis. Is the equivalent of
    AtScaleGetTransform(AtAxisGetScale(widget)).

PLOTTER ROUTINES
These routines are globally accessible, but are designed for use between elements of the AtPlotter widget set only (primarily by the parent AtPlotter widget.) They probably should not be called from applications.

void AtAxisAskRange(w,  minp, *maxp);
void AtAxisDrawPS(w, fp, scale, x1, y1, x2,  y2,  grid_len);
Boolean AtAxisSetPosition(w, x1, y1, x2, y2, grid_len);
int AtAxisWidth(w);
int AtAxisWidthPS(w);
	AtAxisCoreWidget w;
	int x1, y1, x2, y2, grid_len;
	FILE *fp;
	AtScale *scale;

AtAxisAskRange()
    This is the procedure that the AtPlotter calls to pass the min and max from the plots to the axis. It calls the AtAxisCore range class method, calls the XtNrangeCallback function, then accepts the min and max as determined. It then calculates and stores the axis width.

AtAxisDrawPS()
    Dumps the PostScript version of this axis on the file specified. This cannot be done using the AtPlot draw_ps class member function because the AtScale set up with the PostScript dimensions needs to be passed in.

AtAxisSetPosition()
    The AtPlotter calls this routine to set the pixel location of the axis after the layout has been determined. Returns True if the axis length has changed enough that a recalc is required because the number of tics might have changed.

AtAxisWidth()
    Returns the stored axis width so the AtPlotter can layout the pixel locations of all the graph elements.

AtAxisWidthPS()
    returns the width of the axis in PostScript units so the PostScript version of the graph can be laid out.

USAGE
The AtAxisCore widget should never be created by applications. Rather, use one of the subclasses.

CALLBACK INFORMATION
The XtNrangeCallback list is called by the AtAxisAskRange member function, which is in turn called whenever the parent AtPlotter widget considers that the axis bounds may have changed (usually, when plot data has changed, but some resources changes fill force a recalc). The call_data argument to this callback is of type AtAxisRangeArgs:

typedef struct {
	double *minp, *maxp, *tic_intervalp;
	int *max_widthp;
} AtAxisRangeArgs;

The called function is free to modify the pointed-to values as required; the values will be used to scale plots attached to this axis with no further modification.

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

AUTHORS
David Flanagan (MIT Project Athena) and Chris Craig (MIT Project Athena) wrote the code for version V4. The version V5-beta was completely re-written using some code and many algorithms from that version by Gregory Bond, Burdett, Buckeridge & Young Ltd. (gnb@bby.oz.au). A log of changes and additions for this version V6.0 were done by Peter Klingebiel, University of Paderborn (klin@iat.uni-paderborn.de).

NOTES
PostScript is a trademark of Adobe Systems Incorporated.

COPYRIGHT
Copyright 1990,1991 by the Massachusetts Institute of Technology
Copyright 1991 by Burdett, Buckeridge and Young Ltd.
Copyright 1992 by University of Paderborn 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.