MGHGRAXIS__DEFINE Class Name
MGHgrAxis Purpose
An MGHgrAxis is an axis specialised for use by objects of the
MGHgrGraph class and its subclasses. The class is based on the
IDLgrAxis, but with several differences:
- The TITLE and TICKTEXT properties are strings. Behind the
scenes, corresponding IDLgrText objects are created
and modified as necessary.
- The following properties are passed to the axis's title and
tick-text objects: ENABLE_FORMATTING (default 1), FONT and
RECOMPUTE_DIMENSIONS (default 2). These properties are applied
to *both* objects. (This loses a lot of generality, but it also
simplifies the interface & coding.)
- A new property, NORM_RANGE, specifies the end points of the
axis in normal coordinates. When the axis is changed in a way
that affects its range in data coordinates, the
coordinate conversion is changed to keep the normalised range
constant. The [X,Y,Z]COORD_CONV properties are retained but
are read-only.
- It can participate in master-slave relationships (see below).
MASTER-SLAVE RELATIONSHIPS
An MGHgrAxis can participate in master-slave relationships with
axes, atoms and symbols. When changes are made that affect the
scaling and/or position of a master axis, it passes on those
changes to its slaves.
In relationships with atoms and symbols, an MGHgrAxis is always
a master. For atoms it passes on changes in the relevant
[X,Y,Z]COORD_CONV property. For symbols it adjusts the relevant
component of SIZE so as to preserve the normalised size of the
symbol. There are no restrictions on the class of the atoms or
symbols, provided they support the required properties.
The master-slave relationship between axes is intended to support
situations where there are two more-or-less identical axes on a
graph. Both parties in such a relationship must be instances of
MGHgrAxis and there are various restrictions, e.g. a slave axis
may not itself have slaves (of any sort) and a slave axis cannot
have two masters. These rules are enforced to keep dependencies
very simple (there being no good reason to allow complicated ones)
and avoid circular dependencies and other subtle effects that
depend on the order in which changes are passed on.
Each MGHgrAxis has a property called MS_STATUS; it is an integer
that can take three values: -1 (I am a slave), 1 (I am a master),
0 (I am neither). The MS_STATUS property is used to enforce the
above restrictions on the master-slave relationships. It can only
be acessed via by the axis itself, or via the FriendGetProperty &
FriendSetProperty methods. When these methods are called an object
reference must be supplied and it must refer to an MGHgrAxis
object. This provides a barrier (though a very weak one) to
setting the property inappropriately.
A slave axis cannot have more than one master but an atom or
symbol can. Normally each atom or symbol will have 2 or 3 masters,
one each for the X, Y and (maybe) Z directions. It would not make
sense for an atom or symbol to have two masters with the same
direction, but no attempt is made to test for this state (because
doing so would require code in every atom & symbol class).
Background
The central concept behind the MGHgrGraph class is that the axes
in a graph define coordinate conversions, which are then adopted by
atoms and symbols as they are added to the graph (or in the case of
animations, fitted to the graph and added or removed during playback).
The MGHgrAxis class takes this concept a step further in that
axes keep references to the objects (slaves) that have been fitted
to them and update their slaves if any of the axis's relevant
properties is changed.
Properties
In addition to the properties inherited from MGHgrAxis:
ATOM_RANGE (Get)
This keyword to GEtProperty retruns the envelope of the slave
atoms' XRANGE, YRANGE or ZRANGE properties (depending on the
axis direction. Note that this property may be undefined or
unchanged on output from GetProperty, if the axis has no slave
atoms, or if none of the slave atoms supports the required
RANGE property.
###########################################################################
This software is provided subject to the following conditions:
1. NIWA makes no representations or warranties regarding the
accuracy of the software, the use to which the software may
be put or the results to be obtained from the use of the
software. Accordingly NIWA accepts no liability for any loss
or damage (whether direct of indirect) incurred by any person
through the use of or reliance on the software.
2. NIWA is to be acknowledged as the original author of the
software where the software is used or presented in any form.
###########################################################################
Modification History
Mark Hadfield, 1999-05:
Written.
Mark Hadfield, 2000-08:
Revisited and generally revised
Mark Hadfield, 2001-07:
Keyword inheritance updated for IDL 5.5.
Mark Hadfield, 2004-07:
The MGHgrAxis class incorporates master-slave functionality from the
MGHgrMSaxis class, now obsolete.
Mark Hadfield, 2006-03:
Fixed a long-standing bug: initialisation fails when no font is specified.