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).
Category
Widgets, Object Graphics.
POSITIONAL PARAMETERS FOR INIT METHOD:
picture
A synonym for the GRAPHICS_TREE property.
Properties
The following properties (ie keywords to the Init, GetProperty &
SetProperty methods) are supported:
BACKGROUND_COLOR (Init, Get, Set)
A 3-element byte array specifying the RGB colour to which the
window will be erased before every draw. The default is
[127,127,127].
COLOR_MODEL (Init, Get)
This property is inherited from the embedded IDLgrWindow. The
default is 0 (RGB) and the code has never been tested and
probably will not work with a value of 1 (indexed).
BACKGROUND_COLOR (Init, Get, Set)
A 3-element byte array specifying the RGB colour to which the
window will be erased before every draw. The default is
[127,127,127]. NB: for a window with COLOR_MODEL=1 the use of
an RGB colour will probably fail. But I have never 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).
HIGH_RESOLUTION (Init, Get, Set)
Default resolution for PNG and TIFF files produced by the
"high-res" menu items. The default is 2.54/240.
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.)
###########################################################################
Copyright (c) 2013 NIWA:
http://www.niwa.co.nz/
Licensed under the MIT open source license:
http://www.opensource.org/licenses/mit-license.php
###########################################################################
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.
Mark Hadfield, 2009-09:
- Fixed cosmetic bug in EventMenuBar messages.
Mark Hadfield, 2009-10:
The RENDERER, RETAIN & EXPOSE_EVENTS settings for non-Windows
platforms were changed again to work on Thotter. It all remains a
bit of a mystery, however.
Mark Hadfield, 2009-11:
I added a new property, BACKGROUND_COLOR, that's used when the
Draw method is called without a valid picture and also when drawing
to buffers. (I still haven't sorted this out fully.) The Draw method
used to pass inherited keywords to the IDLgrWindow--the only valid
ones being CREATE_INSTANCE and DRAW_INSTANCE. This functionality
has been disabled for the time being.
Mark Hadfield, 2011-05:
Default RENDERER now determined with PREF_GET.
Mark Hadfield, 2011-08:
- Fixed a very long-standing and major bug in PickReport(!): wrong index
supplied to the vector of targets.
- Further adjustment to the resolution for "hi-res" images. To limit
image size the RESOLUTION was increased from 2.54/360 to 2.54/240. The
image now produced from the window displayed by MGH_EXAMPLE_PLOT on
Windows is now 1912x1912.
Mark Hadfield, 2013-04:
- The extension for Windows metafiles has been changed from WMF to EMF.
Mark Hadfield, 2013-06:
- Bitmap PDFs are now at high resolution (2.54/600, or 600 dpi).
Mark Hadfield, 2014-09:
- The resolution for "hi-res" images is now set by a keyword/property
called HIGH_RESOLUTION (clever eh?). The default value is unchanged
at 2.54/240. The image now produced from the window displayed by
MGH_EXAMPLE_PLOT on Windows is now 2102x2102.