MGHGRGRAPH_

MGHGRGRAPH__DEFINE

Class Name

MGHgrGraph

Purpose

An MGHgrGraph is an IDLgrView with extra facilities that make it
useful as a container for general-purpose scientific graphs. These
include:
- Containers to hold resources (fonts, symbols, palettes)
required by graphics atoms.
- Methods to create axes and fit them to the view dimensions.
- Methods to create or add graphics atoms and scale them to the
axes.
- By default, there is a fixed relationship between the
viewplane dimensions in normalised and physical
coordinates. (This means that you can assume that a graphics
atom that is "square" in normalised coordinates will be square
on the destination device.)
An MGHgrGraph does not assume anything in particular about the
layout of the graph. The default axis location and length (centred
in the viewplane with length 1 in normalised coordinates) makes
sure that the axes will be seen but will need to be modified for
actual graphs. Thus this class be useful mainly for "free-form"
graphs; for most purposes it be used via a subclass such as
MGHgrGraph2D or MGHgrGraph3D.

Superclasses

IDLgrView.

Properties

The following properties (ie keywords to the Init, GetProperty &
SetProperty methods) are supported in addition to those inherited
from IDLgrView:
ALL (Get)
This property wraps the object's other properties in a structure.
DELTAZ (Get)
This is a real number specifying the minimum spacing, in
normalised coordinates, needed in the Z direction to ensure
that graphic atoms overlap cleanly. The value is calculated
from the ZCLIP property (inherited from IDLgrView).
DIMENSIONS (Init, Get, Set)
As IDLgrView, but by default an MGHgrGraph object is created
with explicit dimensions calculated from the VIEWPLANE_RECT
and SCALE properties. Thereafter, if the VIEWPLANE_RECT is
altered then DIMENSIONS are also altered so as to preserve
SCALE.
FONTSIZE (Init, Get, Set)
The default size in points for font objects created by the
NewFont method. Default value is 12 for IDL version 7.1
or later, otherwise 10.
N_MODELS (Init, Get)
The number of IDLgrModel objects directly attached to the
graph.
SCALE (Init, Get, Set)
This is a 2-element vector specifying the size in physical
dimensions of a unit square on the viewplane. The GetProperty
method always returns a 2-element vector for SCALE, but in
calls to Init and SetProperty it should normally be specified
as a scalar, indicating that the scale is the same in X & Y
dimensions. The default value of SCALE depends on the UNITS
property: for UNITS = 2 it is 7.5 cm. A SCALE of 0 or [0,0]
indicates that the graph's dimensions are not specified
explicitly (i.e. UNITS = 3 or DIMENSIONS = [0,0]).
SYMSIZE (Init, Get, Set)
The default size in normalised coordinates for symbols created
by the NewSymbol method. Default value is 0.02D0.
TICKLEN (Init, Get, Set)
The default tickmark length in normalised coordinates for axes
created by the NewAxis method. Default value is 0.03.
UNITS (Init, Get, Set)
As IDLgrView, but default is 2 (dimensions specified in cm).

Methods

Most of the methods that create new objects can be called as
functions (returning the object reference(s)) or procedures
(references discarded).
NewFont
Create a new font object and add it to a container attached to
the view. Fonts can be retrieved with the GetFont method and
are destroyed with the view. Several of the methods below use
the first font in the container when creating text objects.
AddFont
Like NewFont, but use an existing font. Obsolete.
GetFont
Retrieve object references from the fonts container. Similar
syntax to IDL_Container::Get.
NewSymbol
Create a new symbol object and add it to a container attached
to the view. Symbols can be retrieved with the GetSymbol
method and are destroyed with the view. The default symbol
size, taken from the SYMSIZE property, can be overriden via
the SIZE keyword.
GetSymbol
Retrieve object references from the symbols container. Similar
syntax to IDL_Container::Get.
Dispose
Add an object (eg a palette) to a container for disposal with
the graph.
NewAtom
Create a graphics atom (or atom-like object) and add it to the
graph. NewAtom is either invoked directly or via a wrapper
method (below); it takes care of associating the new object
with the right model & axes. The object type is specified via
the first parameter & NewAtom can accept up to 3 further
positional parameters, which are passed to the object's Init
method.
AddAtom
Take an existing graphics atom, add it to the graph and
associate it with the right model & axes. This is not used as
often as NewAtom, but is appropriate, for example, when the
size of a graphics atom will not be known until after it is
created.
###########################################################################
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, 2000-08:
- Replaced existing classes MGHgrView, MGHgrGraph,
MGHgrFixedGraph & MGHgrGraph3D with MGHgrGraph (similar to the
old MGHgrView), MGHgrGraph2D (merges the old MGHgrGraph &
MGHgrFixedGraph) and MGHgrGraph3D (similar to the old class of
the same name but much of the logic has been moved to the
superclass MGHgrGraph).
- Added a facility for graphs to use master-slave axes, enabled
by the property USE_MSAXIS, which defaults to 0. In sorting
this out I introduced a significant backward-incompatible
change: the GetScaling method picks up its scaling from the
first suitable axis it finds, not the last. The new convention
makes the implementation of master-slave graphs much simpler
and more logical, but the preparation of multi-scaled graphs
becomes less convenient.
Mark Hadfield, 2001-01:
- NewText method now sets the text object's RECOMPUTE_DIMENSIONS
property to 2 by default.
Mark Hadfield, 2001-05:
- Models created by the view are now instances of
MGHgrModel. Each MGHgrModel keeps track of the axes that have
been added to it, which this allows the MGHgrGraph code to be
simpler.
Mark Hadfield, 2002-06:
- Default value for USE_MSAXIS changed from 0 to 1.
Mark Hadfield, 2004-05:
- Revised GetScaling code, removing calls to MGH_GET_PROPERTY.
Mark Hadfield, 2004-07:
- The NewAtom method now sets the REGISTER_PROPERTY keyword by
default for all atoms.
- Modified to accommodate the changes in the axis classes.
Property USE_MSAXIS is no longer supported; master-slave
behaviour can be suppressed in various methods by setting
SLAVE to 0.
Mark Hadfield, 2005-09:
- Default scale (in cm) increased from 6 to 9.
Mark Hadfield, 2006-08:
- Default scale (in cm) decreased from 9 to 8 to suit my new
monitor better.
Mark Hadfield, 2007-08:
- Generalised NormPosition method so it accepts [2,n] or [3,n]
arrays as input. DataPosition method should also be (but hasn't
been) generalised in this way.
Mark Hadfield, 2008-08:
- Added a NewColorBar method (function and procedure). The
method of the same name in the MGHgrGraph2D class, now calls
this one.
Mark Hadfield, 2009-04:
A couple of changes have been made to accommodate the change in
IDLgrWindow resolution in IDL version 7.1. (The value was queried
from the OS but is now set to a fixed 72 dpi). Code to set the default
SCALE property is now version-dependent and a FONTSIZE property has
been added, with a version-dependent default value.