MGH_WINDOW_

MGH_WINDOW__DEFINE

Class

MGH_Window

Purpose

This class encapsulates a widget application containing an object
graphics window. The window displays a single picture (ie a
IDLgrView, IDLgrViewGroup or IDLgrScene).

Properties

The following properties (ie keywords to the Init, GetProperty &
SetProperty methods) are supported:
BITMAP_RESOLUTION (Init, Get, Set)
Default resolution for off-screen bitmaps, used by methods
WritePictureToImageFile, WritePictureToClipboard and
WritePictureToClipboard (non-vector formats). By default, this
property is set to a non-finite value, which means that the
resolution of the IDLgrWindow object is used.
DIMENSIONS (Init, Get, Set)
A 2-element array specifying the width & height of the
graphics window. If the picture and the window are both
"fittable" (see FITTABLE keyword) then UNITS & DIMENSIONS are
taken from the picture.
CHANGEABLE (Init, Get)
This property determines whether the GRAPHICS_TREE property
can be changed once it has been first set. It is 1 (on) by
default but should be set to 0 if the MGH_Window is to be used
in a composite application which needs to ensure that the
GRAPHICS_TREE is not changed behind its back.
EXPAND_STATUS_BAR (Init, Get, Set)
This property determines whether the the "status bar" beneath
the draw widget is expanded or collapsed. Default is 1
(expanded).
FITTABLE (Init, Get)
This property determines whether the window will try to resize
itself to fit the GRAPHICS_TREE picture. Default is 1 (try to
fit) by default. For a fit to occur, the picture must also be
fittable, as determined by the MGH_PICTURE_IS_FITTABLE
function.
GRAPHICS_TREE (Init, Get, Set)
This property is passed to the embedded draw widget. Setting
the GRAPHICS_TREE triggers other changes including resetting
the window title and creating an "undo" stack. The
CHANGEABLE property determines whether the GRAPHICS_TREE
property can be changed once it has been first set.
MOUSE_ACTION (Init, Get, Set)
A 3-element string array specifying the mouse handler object
to be associated with each mouse button. Mouse press, release
& motion events that originate from the draw widget are sent
to "mouse handler" objects, one handler per mouse
button. These handlers are created and destroyed by the
SetUpMouseHandler method, which is called by SetProperty. Each
time MOUSE_ACTION is changed this method destroys all existing
mouse handlers then creates a new set according to rules
hard-wired into the code.
MOUSE_LIST (Init, Get)
This property is a string array that defines the set of values
available from the "mouse action" droplists on the status
bar. Note that this property affects the user interface
only. It does not affect the range of permissible values for
the elements of MOUSE_ACTION--these values are determined
implicitly by the code in the SetUpMouseHandler method.
RESIZEABLE (Init, Get, Set)
This property detrmines whether the window or picture
dimensions are changed in response to base resize events. The
resizing of the window interacts with the automatic fitting of
the window to the picture, in a way that depends on whether
the picture is fittable (i.e. function MGH_PICTURE_IS_FITTABLE
returns 1) and whether the window is fittable (FITTABLE
property is 1).
RESIZE_PRESERVE (Init, Get, Set)
This property determines whether the aspect ratio of the
window or picture is preserved when the window or picture
is resized. It is ignored if RESIZEABLE is 0.
RESOLUTION (Get)
Taken from the graphics window.
TITLE (Get)
The title, which appears in the base widget's title bar, is
calculated from the picture name.
TOOLTIP (Get)
The tooltip which appears when the cursor hovers over the draw
widget, is calculated from the picture name.
UNITS (Init, Get, Set)
Units for the DIMENSIONS. Default is 2 (cm).
VECTOR_RESOLUTION (Init, Get, Set)
Default resolution for off-screen vector buffers, used by
methods WritePictureToClipboard, WritePictureToClipboard
(vector formats) and WritePictureToVRML. By default, this
property is set to a non-finite value, which means that the
resolution of the IDLgrWindow object is used.
VISIBLE (Init, Get, Set)
Set this property to 1 to make the window visible, 0 to make
it invisible.
... and many more.
KNOWN PROBLEMS:
- On Windows, if the RESIZEABLE property is set, then flashing
occurs when a top-level MGH_Window object is created because the
Draw method is called twice. The first draw occurs when the
object is realised (which causes the NotifyRealize method to be
called, which calls Update, which calls Draw.) The second draw
occurs when the OS sends a resize event to the newly created
base (which calls Resize, which calls Draw) as mentioned
somewhere in the IDL documentation. I have considered various
ways to suppress this, but decided it is simpler to set the
default value of RESIZEABLE to 0.

To Do

Have repertoire of mouse handlers (MOUSE_LIST) depend on the type
of graphics tree? Query the graphics tree for the mouse actions it
supports?? (No, probably not a good idea.)
###########################################################################
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, 2001-06:
Written.
Mark Hadfield, 2001-10:
Added support for a context menu associated with the draw
widget.
Mark Hadfield, 2002-01:
Changed default RETAIN setting from 2 to 1. This has no effect
on Windows but leads to a dramatic improvement in speed and
appearance on Linux.
Mark Hadfield, 2002-10:
Updated for IDL 5.6. Added tool tips and check-box menus.
Mark Hadfield, 2002-12:
Further changes to default RETAIN & EXPOSE_EVENTS settings on
Unix, for better results on Rangi, a DEC Alpha machine.
Mark Hadfield, 2004-05:
- Added code to export graphics using new formats & facilities
in IDL 6.1: EPS with CMYK colour space and JPEG 2000.
- Limited the draw widget's tooltip length to work around IDL
bug.
Mark Hadfield, 2004-07:
- Moved code that sets window title from the SetupGraphicsTree
method to the Update method, to allow for the possibility that
the graph name has been changed by the user. Remainder of
Mark Hadfield, 2005-08:
- Changed resolution for "hi-res" PNGs from 0.005 to 0.01. The
former was, as I recall, intended as a very low value that would
not normally be reached because of IDL's limits on buffer sizes.
However these limits have been relaxed (in version 6.2?) meaning
it can now generate really big images.
Mark Hadfield, 2008-09:
- Resolution for "hi-res" PNGs is now 0.0075.