mrmultidisplay__define.pro


Name:
mrmultidisplay
Methods:
Constructor
mrmultidisplay::init             : constructor, 2nd part

Public variables (get)
mrmultidisplay::palette          : returns the currently used palette object
mrmultidisplay::imgXsize         : returns the image size in x in pixels
mrmultidisplay::imgYsize         : returns the image size in y in pixels
mrmultidisplay::nx               : returns number of images in x direction
mrmultidisplay::ny               : returns number of images in y direction
mrmultidisplay::contrast         : as the mrdisplay function
mrmultidisplay::gamma            ; return the currently used gamma value
mrmultidisplay::screenXsize      : return visible canvas size in x in pixels
mrmultidisplay::screenYsize      : return visible canvas size in y in pixels
mrmultidisplay::imgMinval        : return the minimum and maximum absolute (i.e.
mrmultidisplay::imgMaxval        : unscaled) values of all images

Public variables (set)
mrmultidisplay::setContrast      : set contrast for all displayed images
mrmultidisplay::setGamma         ; set the gamma value of the used palette
mrmultidisplay::setPalette       : set the palette to use
mrmultidisplay::setPaletteRGB    ; set palette RGB values or load from predefined colortables

General
mrmultidisplay::display          : display object content on screen

Image handling
mrmultidisplay::setImg           : x, y, ptr  : set image at position x,y
mrmultidisplay::deleteImg        : x, y       : delete image at position x,y
mrmultidisplay::label            : x,y,text,/set,/delete,color=c
mrmultidisplay::frame            : x,y,/set,/delete,color=c

Event handling
mrmultidisplay::requestDisplay   ; display after all event handlers are done
mrmultidisplay::activate         : generate events
mrmultidisplay::deactivate       : no events no more
mrmultidisplay::registerEvt      : register an event
mrmultidisplay::unregisterEvt    : unregister an event
mrmultidisplay::unregisterObj    : unregister a whole object
mrmultidisplay::unregisterAll    : remove all entries from callback tables

Private
mrmultidisplay::labelView        : obsolete?
mrmultidisplay_evthandler        : non-object event handler calls the object handler
mrmultidisplay::evthandler       : the object handler
mrmultidisplay::resolveTypeStr   : translate an event string into an event type
mrmultidisplay__define           : constructor, 1st part
mrmultidisplay::cleanup          : the destructor
Description:
An object to display a set of images in an array like fashion, while
automatically scaling the images to the correct size
Many properties are similar to the ones of 'mrdisplay' as we want
to be able to use the same callback objects where possible. Actually
mrdisplay and mrmultidisplay call the same event handler on the object side.
Event handling:
mrDisplay issues events on different conditions. The following event types are
presently defined - objects may register for one or more event types:

Event types:
Type (number)     string             occurence
0                'press'             any button press event
1                'dblclick'          any button double click event
2                'release'           any button release event
3                'motion'            mouse has been moved inside window
4                'keypress'          a key has been pressed inside window
5                'imgchange'         an image has been set or deleted
6                'palettechange'     the used palette has been changed (setpalette)

The event structure
> x = { mrdisplayEvt          ,$
>     type      :   0           ,$ ; (all) an integer denoting the event type, see below
>     top       :   0L          ,$ ; (0-4) the top widget id
>     display   :   obj_new()   ,$ ; (0-4) the display object itself
>     grWindow  :   obj_new()   ,$ ; (0-4) the IDLgrWindow object within the draw widget
>     lblView   :   obj_new()   ,$ ; (0-4) this objects label view window
>     x         :   0           ,$ ; x position of the event, device coordinates
>     y         :   0           ,$ ; y position of the event, device coordinates
>     dx        :   0           ,$ ; x difference since last event
>     dy        :   0           ,$ ; y difference since last event
>     nx        :   0           ,$ ; image number in x
>     ny        :   0           ,$ ; img number in y, origin is upper left (reading dir)
>     key       :   0L          ,$ ; key off an ASCII key press
>     modifiers :   0L          ,$ ; bitmask: 1 = shift, 2 = control
>     button    :   0           ,$ ; bitmap, left, middle right mouse button, pressed/released
>                                $ ; button for press/release events, current status in motion evts
>     buttonstatus: 0            $ ; current status of pressed/released mouse buttons, bitmap
> }

Name:
mrmultidisplay::init
Type:
Function
Arguments:
long int baseid   : widget id of the base widget in which to realize
int      xsize    : widget size in x in pixels on screen
int      ysize    : widget size in y in pixels on screen
int      imgxsize : size in x of a single image
int      imgysize : size in y of a single image
int      nx       : number of images in x direction
int      ny       : number of images in y direction
Return value:
1 or 0, thus object pointer or null pointer
Description:
Instanciate an mrmultidisplay object in the base widget with the given
size. If imgxsize * nx (imgysize*y) should be larger than xsize,
scrollbars are automatically added to the widget.
All arguments are mandatory.
Rendering limits are checked for IDL versions 5.5 and greater

Name:
mrmultidisplay::cleanup
Type:
Private procedure (destructor)
Description:
undone - thus memory leak

Name:
mrmultidisplay::setImg
Syntax:
obj->setImg, xpos, ypos, image_pointer, top=int, /no_contrastupdate
Arguments:
xpos
x position of the image in the range [0, nx-1]
ypos
y position of the image in the range [0, ny-1]
image_pointer
pointer to the image data
top
top byte value to which to scale the image in the range [0,255].
default is 255.
no_contrastupdate
All images are scaled relative to the maximum value of all images,
such that identical grey scale values represent identical image
values. When setting an image with a higher maximum or lower minimum
value than the currently displayed images, the present images need
to be recalculated. This takes time of course - when setting many
images at once, recalculation is only necessary when setting the
very last image.
Description:
Set the image at position xpos, ypos. Coordinate system origin is at
the upper left and values range from 0 to nx-1 and ny-1 respectively.
The image will be downscaled to the size given in mrmultidisplay::init
Like mrdisplaymrmultidisplay stores a local copy of the downsized
image data, so the user may delete the original data after setImg.
As of now ractangular images are resized to square format and thus
deformed.

Name:
mrmultidisplay::deleteImg
Syntax:
obj->deleteImg, xpos, ypos, /no_contrastupdate
obj->deleteImge, /all
Arguments:
xpos
x position of the image in the matrix in range [0, nx-1]
ypos
y position of the image in the matrix in range [0, ny-1]
all
If set, all images are removed from the object
no_contrastupdate
All images are scaled relative to the maximum value of all images,
such that identical grey scale values represent identical image
values. Deleting an image might change the overall maximum and
minimum of course, which makes a recalculation necessary. Since
this takes time, it can be omitted if several images are deleted
at once and only be done with the last image.
Description:
Delete one image, i.e. the corresponding image model
Deleting an image does not delete possibly existing labels or
frames - use the corresponding functions to remove those as well.

Name:
mrmultidisplay::contrast
Syntax:
ctr = obj->contrast()
Return value:
float[2] contrast
Current contrast center and width (both in range [0.,1.])

Name:
mrmultidisplay::setContrast
Syntax:
obj->setContrast, center, width
Arguments:
center
Relative center of contrast, 0. < center < 1.
width
Relative contrast width, 0. < width < 1.
Description:
Contrast settings are such that identical greyscale values (or colors)
correspond to identical image values (for equal 'top' settings).

mrmultidisplay::setGamma
Syntax:
obj->setGamma, gamma
Arguments:
gamma
Gamma value for the image's palette 0.1 < gamma < 10.
Description:
Set the gamma value for the image's palette

mrmultidisplay::gamma
Syntax:
gamma = obj->gamma()
Description:
Return the current gamma value of the image palette

mrmultidisplay::label
Syntax:
obj->label, x, y, label, /set, /delete, /all, color=color
Arguments:
x
x position of the image
y
y position of the image to label
label
the label text
set
set the label, this is default, if a label text is given
delete
delete the label, this is default, if no label text is given
or the label text equals an empty string
all
set or delete labels for all images
color
3 element integer array [r,g,b] denoting the label color.
Default is lime.
Description:
Set or remove a label

mrmultidisplay::frame
Syntax:
obj->frame, x, y, /set, /delete, /all, color=color
Arguments:
x
x position of the image in the matrix (not pixels, but images!)
y
y position of the image in the matrix
set
set a frame, this is the default
delete
remove a frame
all
if set, all frames will be set or removed
color
a 3 element integer array denoting the frame color as [r,g,b]
default is lime.
Description:
Creates a thin frame around the corresponding image

mrmultidisplay::screenXsize
Syntax:
win = obj->screenXsize()
Return value:
Returns the visible canvas size in x in pixels ('x' argument in init)

mrmultidisplay::screenYsize
Syntax:
win = obj->screenYsize()
Return value:
Returns the visible canvas size in y in pixels ('y' argument in init)

mrmultidisplay::grWindow
Type:
Function
Description:
return the IDLgrWindow object associated with the drawing widget

mrmultidisplay::labelView
Type:
Function
Return value:
The object's label view - an IDLgrView object which extends over the
whole display and has normalized coordinates. Meant to add your own
labels.

mrmultidisplay::palette
Type:
Function
Return value:
A pointer to the IDLgrPalette object used to display the images

mrmultidisplay::setPalette
Syntax:
obj->setPalette, palette
Arguments:
palette
An object of class IDLgrPalette
Description:
Copies the RGB values from the passed palette object into the
internal palette object.

mrmultidisplay::setPaletteRGB
Syntax:
obj->setPaletteRGB, red=intarr, green=intarr, blue=intarr, colorTable=int
Arguments:
red, green, blue
Integer arrays with 256 elements holding the red/green/blue values of
the palette
colorTable
An integer value between 0 and 41 indexing one of IDL's predefined
color tables. If set to 42, a logarithmically divided colortable is
loaded. If colorTable is set, keywords red, green and blue are
ignored.
Description:
Sets the red/green/blue values of the image palette used to display
the image.

mrmultidisplay::imgXsize
Type:
Function
Description:
Returns image size in x in pixels

mrmultidisplay::imgYsize
Type:
Function
Description:
Returns image size in y in pixels

mrmultidisplay::nx
Type:
Function
Description:
Returns number of images in x direction

mrmultidisplay::ny
Type:
Function
Description:
Returns number of images in y direction

mrmultidisplay::imgMaxval
Type:
Function
Description:
Returns the real (unscaled) maximum value of all displayed images

mrmultidisplay::imgMinval
Type:
Function
Description:
Returns the real (unscaled) minimum value of all displayed images.

mrmultidisplay::display
Type:
Procedure
Description:
(re-)draw the current image

mrmultidisplay::requestDisplay
Syntax:
obj->requestDisplay
Description:
Request a redisplay, but don't call mrdisplay::display immediately.
Instead, a redisplay of the screen is only performed after all external
event handlers have been called - thus avoiding possible overhead by
multiple calls to mrdisplay::display from each event handler.

mrmultidisplay::activate
Description:
switch on event handling. IDL versions > 5.5 also provide keyboard
events

mrmultidisplay::deactivate
Description:
switch off event handling

mrmultidisplay::unregisterAll
Description:
clear all entries in the callback table

mrmultidisplay::registerEvt
Type:
Procedure
Arguments:
object callBackObject : the object which provides the call back function
string typestr        : string denoting the event type (s.b.)
Description:
register an event
The object which registers with mrmultidisplay has to provide a
method named ::mrmultidisplay_evthandler which will then be called
with a pointer to mrmultidisplay's event structure as an argument.
(See above for the event structure definition).
Usually, the first thing this routine does is to check for the
button field, to find out, whether this event is of interest to
the object.

mrmultidisplay::unregisterEvt
Type:
Procedure
Arguments:
object callBackObject  : the object which is to be removed
string eventType       : a string denoting the event type to remove
Description:
unregister an event from mrmultidisplay callback

mrmultidisplay::unregisterObj
Type:
Procedure
Arguments:
object callBackObject  : the call back object to remove
Description:
unregister a whole object from mrdisplay callback

mrmultidisplay::resolveTypeStr
Type:
Private function
Description:
Convert the type string into an index

mrmultidisplay_evthandler
Type:
Private procedure
Calls:
mrmultidisplay::evtHandler
Description:
call the object's own event dispatcher

mrmultidisplay::evthandler
Type:
Private procedure
Description:
the event handler which does the callbacks

mrmultidisplay__define
Type:
Private Procedure (constructor)

Last modified: Mon Nov 29 13:30:06 2004