mrroiui__define.pro


Name:
mrRoiUI
Methods:
Constructor
mrRoiUI::init                 : Constructor, the main part

Public variables (get)
mrRoiUI::roiGroup             : return the current mrroigroup

Public methods
mrRoiUI::setRoiGroup          : set mrroigroup for this object
mrRoiUI::addRoi               : add a roi to the roigroup by program
mrRoiUI::deleteRoi            : delete a roi from the roigroup
mrRoiUI::showRois             : display the rois in the mrdisplay object
mrRoiUI::hideRois             : do not display the rois
mrRoiUI::calcAreaImg          : recalculate the rois - necessary after mrRoiUI::setRoi
mrRoiUI::palette              : get the used palette, meant for read-only!
mrRoiUI::roiColor             : returns rgb color-vector of a certain roi
mrRoiUI::print                : print some info on the current rois

Notification
mrRoiUI::notify               : see mrNotify::notify
mrRoiUI::enableNotify         : see mrNotify::enableNotify
mrRoiUI::disableNotify        : see mrNotify::disableNotify

Communication with mrDisplay, user part
mrRoiUI::selfregister         : automatically register with a mrdisplay object
mrRoiUI::unregister           : and unregister again (see the tips page!)
mrRoiUI::activate             : activate the roi button window
mrRoiUI::deactivate           : or deactivate the buttons
mrRoiUI::setLoadMethod        : link a user defined load method to the load button
mrRoiUI::setSaveMethod        : link a user defined save method to the save button

Communication with mrDisplay, internal part
mrRoiUI::mrdisplayEvtHandler  : callback method for the display object
mrRoiUI::buttonMotionEvt      : handles motion events
mrRoiUI::buttonPressEvt       : handles button press events
mrRoiUI::buttonReleaseEvt     : handles button release events

Event handling for the button window
mrRoiUI::updatewidgets        : update button widget (highlighting)
mrRoiUI_evthandler            : the event handler for the button window
mrRoiUI::evthandler           : and the object version of the handler

Private methods
mrRoiUI::load                 : load a roigroup from file
mrRoiUI::save                 : save a roigroup
mrRoiUI::updateAreaImg        : update only the active roi's area
mrRoiUI::resetRoiColor        : i.e. make a roi non-active
mrRoiUI::findClosestRoi       : find the closest roi to a certain point
mrRoiUI::findTxtObj           : find a txt object with specified uvalue
mrRoiUI::findFreeRoiNumber    : find a roinumber not in use
mrRoiUI::definePalette        : define the palette colors
mrRoiUI__define               : Constructor part I
mrRoiUI::cleanup              : Destructor

Description:
This object provides complete ROI definition and evaluation
functionality. See below for some examples on how to use.
Events
Objects may be notified upon modification of existing ROIs or change
of the roi set (i.e. ROIs are added or removed). mrRoiUI knows two
event types: 'modify' and 'change'. 'modify' notifications are sent
continuously, while a new ROI is created or an existing ROI
is modified. 'change' notifications are only sent once after
creation or modification of an ROI (i.e. upon mouse button release).
The event structure passed during call to the objects notification
handler is of the following form:
> x = { mrroiuievt                ,$
>       type    :    0            ,$ ;
>       top     :    0L           ,$ ; the top widget id (see below)
>       roi     :    obj_new()    ,$ ; the currently active roi
> }
where type equals '1' for modify and '2' for change events. The currently active
roi is NULL (resp. obj_new()) for change events.

To provide a value for the top widget is not straight forward as mrRoiUI self
receives IDL events only indirectly via callback from mrDisplay. Nevertheless
it is needed as the structure holding global variables might be attached
to the uvalue of the top-widget. Usually this should be ok, as events are
only created after selfregistration and activation of mrdisplay, but it might
nevertheless be a good idea to check for a value of 0L.
Loading and saving of ROIs
Loading and saving is now done via the (new) mrRoiGroup class and its
load/save methods which read/write xml and will store one single
roigroup to file, resp. read one single roigroup from file.
This might be inappropriate in cases where e.g. rois may be defined
in several slices and should be stored/retrieved together.
Use the load/save hook in these cases by linking user defined methods
via setLoadMethod, setSaveMethod, thus overriding the built-in
functionality. mrRoiGroup contains some example code for that case.

Name:
mrRoiUI::init
Syntax:
obj = obj_new('mrroiui', parent, row=row, column=column, /no_iobuttons,
spacing=spacing, path=path )
Arguments:
parent
Widget id of the parent widget in which to place the mrroiui buttons. If parent
is not given, a separate window holding the buttons will be created.
row
may equal 1, 2 or 4 and defines the number of button rows to use
column
as row, defining the number of columns. Only one of the row and column
keywords may be used (the use of column overrides any row setting).
row=4 and column=4 yield the same layout.
no_iobuttons
If set, do not display the load and save button.
spacing
Number of pixels between the button groups. Default is 5.
(only for row=1 or column=1)
path
Initial path - the object will remember the last used path at subsequent
calls to load and save.
extra
Any additional keywords are passed on to the base widget which contains
the ROI buttons.
Description:
Instanciates an mrroiui object, creates the button window and registers with
xmanager.

Name:
mrRoiUI::cleanup
Syntax:
obj_destroy, obj
Description:
There's still (minor) memory leaks

Name:
mrRoiUI_evthandler
Syntax:
mrRoiUI_evthandler, evt
Calls:
mrRoiUI::evthandler
Arguments:
evt
A button evt structure
Description:
Get the mrRoiUI object from the buttons uvalue and call this
mrRoiUI object's event handler

Name:
mrRoiUI::evthandler
Syntax:
obj->evthandler, button_id
Arguments:
button_id
The widget id of the pressed button (as evaluated by mrRoiUI_evthandler)
Description:
The object's event handler, handling the roi button events. Mouse
events from the canvas are handled via mrdisplay call back.
There's still a little bit of functionality in here, but it's
almost all gone now.

Name:
mrRoiUI::updatewidgets
Syntax:
obj->updatewidgets
Description:
Set sensitivity and bitmaps of all widgets according to the
internal status, described by self.mode, self.filled and self.solid.

Name:
mrRoiUI::roiGroup
Syntax:
roigroup = obj->roiGroup()
Return value:
returns the mrroigroup object currently displayed in mrRoiUI. The
obtained roigroup object should not be changed while being displayed,
or unexpected side-effects may occur.

Name:
mrRoiUI::setRoiGroup
Syntax:
obj->setRoiGroup, roigroup, /destroy_current
Calls:
mrRoiUI::calcAreaImg
Arguments:
roigroup
An object of class mrRoiGroup
destroy_current
If set, the currently used roigroup is destroyed (and with it all
rois contained therein). Default is '0'.
Description:
Replaces the current roigroup by a new one.
If argument roigroup is not provided, a new and empty roigroup object
is created.
The method calls mrRoiUI::calcAreaImg and thus implicitly creates
roichange events, if notification is switched on.
Example code:
The method call
 obj->setRoiGroup, /destroy_current 
is similar to
 obj->deleteRoi, /all 
except that in the former case, a new object of class mrRoiGroup is
created, while the latter would conserve the old one (thus preserving
possible references to the existing object).

Name:
mrRoiUI::selfregister
Syntax:
obj->selfregister, display, button=button
Arguments:
display
The mrdisplay object to register with. The object must have been
realized on screen and an image must be loaded at the time of
registration.
button
Mouse button to use. 1 = left (default), 2 = middle, 3 = right.
Description:
Self-registration must only be done after an image has been
loaded in mrdisplay because some internal variables of mrRoiUI depend
on the image size.
You also have to unregister and reregister, if the image size is
changed in mrdisplay, that is before and after the call to
mrdisplay::setImgmrRoiUI catches image set events from the display:
If the image size changes unexpectedly, mrRoiUI creates an error
window and unregisters itself.
Important: registering basically means a 'reset' of the mrRoiUI
object - that means among other things that a new roigroup is created
with each call to 'register'.
To avoid memory leaks, 'old' roigroups need to be manually destroyed
after unregistering.
Hah! And who would understand the setting of the blendfunction? (Evil
grin) It's either [1,1] or [1,4].

Name:
mrRoiUI::unregister
Syntax:
obj->unregister
Description:
Unregisters with a mrdisplay object. It is a good idea to unregister
before destroying the mrdisplay object or setting an image with a
different size (s.a.)
Unregistering automatically deactivates the roi buttons.
Unregistering will not destroy the roigroup.

Name:
mrRoiUI::activate
Syntax:
obj->activate
Description:
Activate roi widget buttons, reset roi system

Name:
mrRoiUI::deactivate
Syntax:
obj->deactivate
Description:
Disable internal callback and all buttons

Name:
mrRoiUI::mrdisplayEvtHandler
Syntax:
obj->mrdisplayEvtHandler, evt
Arguments:
evt
An event structure (pointer) from mrdisplay
Description:
The event dispatcher for events from the mrdisplay object
We also fill our own evt.top here to be used in mrRoiUI events.

Name:
mrRoiUI::buttonPressEvt
Syntax:
obj->buttonPressEvt, evt
Description:
A button press event makes sense under two conditions:
adding:
dot: draw dot, but don't save it yet (happens @ button 1 release)
circ: draw circle with radius '0'
rect: draw rectangle with start point @ mouse x/y
poly: start drawing a polygon
editing:
- find closest object (conditions differ for the different forms)
- set the roi active and remember its number
- redraw screen with active roi marked red

Name:
mrRoiUI::buttonMotionEvt
Syntax:
obj->buttonMotionEvt, evt
Description:
Handles motion event, i.e. resizing, drawing, rotating, etc.

Name:
mrRoiUI::buttonReleaseEvt
Syntax:
obj->buttonReleaseEvt
Description:
Releasing the button while adding a roi fixes this roi and makes
it nonactive. In edit mode, the currently active roi is set inactive.

Name:
mrRoiUI::showRois
Syntax:
obj->showRois
Description:
Display the ROIs in the associated mrdisplay object

Name:
mrRoiUI::hideRois
Syntax:
obj->hideRois
Description:
Do not display the ROIs in the associated mrdisplay object (i.e.
hide them)

Name:
mrRoiUI::calcAreaImg
Syntax:
obj->calcAreaImg, /no_notify
Arguments:
no_notify
set to inhibit notifications for just this call
Description:
Recalculates the masks for all rois. The masks of the non active rois
are saved in our intermediate storage, so we don't need to recalculate
them when updating later.
Calling this routine will possibly cause a roichange event.

Name:
mrRoiUI::updateAreaImg
Syntax:
obj->updateAreaImg
Description:
As opposed to mrRoiUI::calcAreaImg this method will only recalculate
the currently active roi's masks. This along with the fact that
active rois are not accessible from the outside makes this method
purely 'private' (whatever that means in IDL)
A call to this method causes a 'roiupdate' event.

Name:
mrRoiUI::print
Syntax:
obj->print
Description:
Print a couple of roi properties - meant for debugging mostly

Name:
mrRoiUI::palette
Syntax:
palette = obj->palette()
Description:
Returns an object reference to the palette used for roi display.
This should be regarded as read-only, as the ROI colors are determined
from other sources - thus changing this palette has no effect!

Name:
mrRoiUI::roiColor
Syntax:
rgb = obj->roiColor( number )
Arguments:
number
The roi number
Description:
Returns a 3-dim RGB-vector which holds the color of roi number
'number'. It plays no role, whether a roi with that number actually
exists on screen. Only the lower 8 bit of number are used (i.e. 0-255)

Name:
mrRoiUI::addRoi
Syntax:
obj->addroi, type, x, y, r, /no_update
Arguments:
type
One of 'dot', 'circ', 'rect' and 'poly'
x, y, [r]
x and y coordinates and radius for circles (see below)
no_update
If set to '1', roi areas are not recalculated after setting - this
might save time when setting many rois at once.
Description:
Add a MRroiDot/Rect/Circ/Poly object at the specified coordinates
to the roigroup. The arguments for the different roitypes need
to be specified as follows:
'dot'  : x, y define x and y position of the dot roi
'rect' : x, y two elements each for two opposing edges of the roi
'circ' : x, y define the center, r the radius
'poly' : x, y both have the same number of 'n' elements denoting the
.        n edges of the roi
This method does not interfere with any rois defined via the user-
interface and can thus be used as a complement.
This method does not call mrdisplay::display
If you use the /no_update flag for faster setting of several rois,
don't forget to either call mrRoiUI::calcAreaImg yourself after setting
the last roi, or add the last roi without this flag.
Note that /no_update also implies no notifications send

Name:
mrRoiUI::deleteRoi
Syntax:
obj->deleteRoi, roi, /all, /no_update
Arguments:
roi
The roi object to delete from the currently displayed roigroup
all
If set to '1', delete all rois from the current roigroup
no_update
If set, roi areas are not recalculated, i.e. the 'deleted' ROI
would still be displayed.
Description:
Delete the given roi and the corresponding text object
Note that no_update also implies that no notifications are send.

Name:
mrRoiUI::resetRoiColor
Syntax:
self->resetRoiColor, roi
Arguments:
roi
The roi whose color to change from active to inactive
Description:
Reset the color of the given roi and its text to the default index
(which is roinumber + 1)
Note that dot-like rois always get a label in the same color whereas
for the other rois it depends on the display style (outlined or filled)
For outlined rois, the label has the same color as the roi, for filled
rois the label is black, as it is located in the center of the roi
and, say, a red label on a red roi doesn't make for very good reading.

Name:
mrRoiUI::findClosestRoi
Syntax:
self->findClosestroi, x, y
Description:
return object reference of the ROI closest to a given point
for now we do it the simple way and just use the center point

Name:
mrRoiUI::findFreeRoiNumber
Syntax:
self->findFreeRoiNumber
Return value:
Lowest free roinumber
Description:
Return the next free roi number

Name:
mrRoiUI::findTxtObj
Syntax:
obj = self->findTxtObj, id
Arguments:
id
The uvalue of the text object (i.e. the number it displays)
Description:
Returns the corresponding text object or obj_new(), if not found.

Name:
mrRoiUI::roiInfo
Syntax:
obj = self->roiInfo, roi
Arguments:
roi
The roi to info :)
Description:
Displays a dialog_message with some simple roi information

Name:
mrRoiUI::definePalette
Syntax:
self->definePalette
Description:
Manual definition of the palette used for roi display.
Color index 0 must be black, index 1 is the color for active rois,
index 255 is white. All other colors are only defined with '128'
values - else they would display as white when overlapping

Name:
mrRoiUI::setLoadMethod
Syntax:
obj->setLoadMethod, object, method
Arguments:
object, method
The object instance and the method name to call when the user presses
the 'load' button. Set object to obj_new() to remove a previously
set load method.
Description:
The given method will be called with the 'evt' structure as
defined above, with only elements roi and name (set to 'load') filled.
Note that the user is responsible for all setting of roi groups etc.
The 'load' and 'save' methods of mrRoiUI might serve as a prototype
for the functionality to implement.

Name:
mrRoiUI::setSaveMethod
Syntax:
obj->setSaveMethod, object, method
Arguments:
object, method
The object instance and the method name to call when the user presses
the 'save' button. Set object to obj_new() to remove a previously
set save hook.
Description:
The given method will be called with the 'evt' structure as
defined above, with only elements roi and name (set to 'save') filled.

Name:
mrRoiUI::load
Syntax:
res = self->load, filename, /destroy
Arguments:
filename
the mrroigroup file to load. If no filename is given, the user is
presented a file-selector boxp
destroy
If set, the currently used roigroup is destroyed (and with it all
rois contained therein). Default is '0', i.e. do not destroy
Return value:
1 in case of success, 0 otherwise
If a user method is called, return value is always '1'.
Description:
The method loads the first roigroup found in the given file and
makes it the current roigroup. However, if the user has set a load
method via mrRoiUI::setLoadMethod, this method is called instead.

Name:
mrRoiUI::save
Syntax:
res = self->save( filename )
Arguments:
filename
The file to store to. If no filename is given, the user is presented
a fileselector box
Description:
Saves a mrroigroup via the classes' save method.

Name:
mrRoiUI__define
Type:
Private Procedure (constructor)

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