[Previous]
[Next]
NAME:
XBM_EDIT
PURPOSE:
This routine allows users to create and edit bitmaps for use with IDL
widgets as icons.
The icons can be saved in two different file formats. IDL "array
definition files" are text files that can be inserted into IDL
programs. "Bitmap array files" are data files that can be read into
IDL programs. Bitmap array files are to be used temporarily until
the final icon design is determined and then they can be saved as
IDL array definitions for inclusion in the final code. This routine
does not check the file types of the files being read in and assumes
that they are of the correct size and type for reading.
CATEGORY:
Widgets.
CALLING SEQUENCE:
XBM_EDIT
KEYWORD PARAMETERS:
FILENAME: A scalar string that contains the file name to be used. If
this argument is not specified, the name "idl.bm" is used.
GROUP: The widget ID of the widget that calls XBM_EDIT. When this
ID is specified, the death of the caller results in the death
of XBM_EDIT.
XSIZE: The number of pixels across the bitmap is in the horizontal
direction. The default value is 16 pixels.
YSIZE: The number of pixels across the bitmap is in the vertical
direction. The default value is 16 pixels.
BLOCK: Set this keyword to have XMANAGER block when this
application is registered. By default the Xmanager
keyword NO_BLOCK is set to 1 to provide access to the
command line if active command line processing is available.
Note that setting BLOCK for this application will cause
all widget applications to block, not only this
application. For more information see the NO_BLOCK keyword
to XMANAGER.
CALLS: ***
DRAW_PIXEL, UPDATE_DISPLAY, XBM_EDIT_EV, XLOADCT, XMANAGER, XMTOOL, XPALETTE, XPDMENU
XREGISTERED
SIDE EFFECTS:
Initiates the XManager if it is not already running.
Note that rotating an XSIZE x YSIZE bitmap by 90 net degrees
changes it to a YSIZE x XSIZE bitmap.
RESTRICTIONS:
XBM_EDIT maintains its state in a common block so it is restricted
to one working copy at a time.
PROCEDURE:
Create and register the widget and then exit.
MODIFICATION HISTORY:
Created from a template written by: Steve Richards, January, 1991
1/96, RPM - fixed bugs so non-square bitmaps can be rotated;
fixed bug so doesn't hang if draw a single pixel "line";
fixed bugs so can read bitmap array files that are not
square and don't end on byte boundaries;
added FREE_LUN and made several other minor fixes.
[Previous]
[Next]
NAME:
XDISPLAYFILE
PURPOSE:
Display an ASCII text file using widgets and the widget manager.
CATEGORY:
Widgets.
CALLING SEQUENCE:
XDISPLAYFILE, Filename
INPUTS:
Filename: A scalar string that contains the filename of the file
to display. The filename can include a path to that file.
KEYWORD PARAMETERS:
BLOCK: Set this keyword to have XMANAGER block when this
application is registered. By default the Xmanager
keyword NO_BLOCK is set to 1 to provide access to the
command line if active command line processing is available.
Note that setting BLOCK for this application will cause
all widget applications to block, not only this
application. For more information see the NO_BLOCK keyword
to XMANAGER.
DONE_BUTTON: the text to use for the Done button. If omitted,
the text "Done with <filename>" is used.
EDITABLE: Set this keyword to allow modifications to the text
displayed in XDISPLAYFILE. Setting this keyword also
adds a "Save" button in addition to the Done button.
FONT: The name of the font to use. If omitted use the default
font.
GROUP: The widget ID of the group leader of the widget. If this
keyword is specified, the death of the group leader results in
the death of XDISPLAYFILE.
GROW_TO_SCREEN: If TRUE, the length of the display area is grown
to show as much of the text as possible without being too
large to fit on the screen. In this case, HEIGHT sets the
lower bound on the size instead of setting the size itself.
HEIGHT: The number of text lines that the widget should display at one
time. If this keyword is not specified, 24 lines is the
default.
RETURN_ID : A variable to be set to the widget ID of the top level
base of the resulting help application.
TEXT: A string or string array to be displayed in the widget
instead of the contents of a file. This keyword supercedes
the FILENAME input parameter.
TITLE: A string to use as the widget title rather than the file name
or "XDisplayFile".
WIDTH: The number of characters wide the widget should be. If this
keyword is not specified, 80 characters is the default.
WTEXT: Output parameter, the id of the text widget. This allows
setting text selections and cursor positions programmatically.
OUTPUTS:
No explicit outputs. A file viewing widget is created.
CALLS: ***
XDISPLAYFILEGROWTOSCREEN, XDISPLAYFILE_EVENT, XDISPLAYFILE_WRITE, XMANAGER
get_screen_size
CALLED BY:
ANNOTATE, CW_ANIMATE, EFONT, PREF_MIGRATE, SLICER3, XFONT, XLOADCT, XPALETTE, XPCOLOR
dicomex_net_startup
SIDE EFFECTS:
Triggers the XMANAGER if it is not already in use.
RESTRICTIONS:
None.
PROCEDURE:
Open a file and create a widget to display its contents.
MODIFICATION HISTORY:
Written By Steve Richards, December 1990
Graceful error recovery, DMS, Feb, 1992.
12 Jan. 1994 - KDB
If file was empty, program would crash. Fixed.
4 Oct. 1994 MLR Fixed bug if /TEXT was present and /TITLE was not.
2 jan 1997 DMS Added DONE_BUTTON keyword, made Done
button align on left, removed padding.
19 Nov 2004, GROW_TO_SCREEN and RETURN_ID keywords. Allow for
user to resize display. General updating.
[Previous]
[Next]
NAME:
XFONT
PURPOSE:
XFONT is a modal widget for selecting and viewing an X Windows font.
CATEGORY:
Widgets, Fonts
CALLING SEQUENCE:
Selected_font = XFONT()
INPUTS:
No explicit inputs.
KEYWORD PARAMETERS:
GROUP: The widget ID of the widget that calls XFONT. When this
ID is specified, a death of the caller results in a death
of XFONT.
PRESERVE: If set, XFONT saves the server font directory in common
blocks so that subsequent calls to XFONT start-up much
faster. If not set, the common block is cleaned.
OUTPUTS:
A string containing the font name. If nothing is selected, or
the CANCEL button is pressed, a null string is returned.
CALLS: ***
FILEPATH, UNIQ, XDISPLAYFILE, XFONT_EVENT, XFONT_SCAL_FNAME, XFONT_SELECT, XMANAGER
XREGISTERED
COMMON BLOCKS:
XFONT_COM.
SIDE EFFECTS:
Initiates the XManager if it is not already running.
Resets the current X Window font.
RESTRICTIONS:
The current X window font is manipulated without being restored.
This routine does not work on non-X Windows platforms (i.e., Windows
and Macintosh).
PROCEDURE:
Create and register the widget and then exit.
MODIFICATION HISTORY:
Modified from a template written by: Hans-Joachim Bothe, CreaSo GmbH,
November, 1991, by DMS, RSI, November, 1992.
1 July 1995, AB, Fixed sizing of toggle buttons.
6 July 1995, MWR, Added platform check to return to caller if
running on Windows or Macintosh.
[Previous]
[Next]
NAME:
XINTERANIMATE
PURPOSE:
Display an animated sequence of images using X-windows Pixmaps.
The speed and direction of the display can be adjusted using
the widget interface.
CATEGORY:
Image display, widgets.
CALLING SEQUENCE:
To initialize:
XINTERANIMATE, SET = [Sizex, Sizey, Nframes]
To load a single image:
XINTERANIMATE, IMAGE = Image, FRAME = Frame_Index
To load a single image that is already displayed in an existing window:
XINTERANIMATE, FRAME = Frame_index, $
WINDOW = [Window_Number [, X0, Y0, Sx, Sy]]
(This technique is much faster than reading back from the window.)
To display the animation after all the images have been loaded:
XINTERANIMATE [, Rate]
To close and deallocate the pixmap/buffer (which also takes place
automatically when the user presses the "Done With Animation"
button or closes the window with the window manager):
XINTERANIMATE, /CLOSE
OPTIONAL INPUTS:
Rate: A value between 0 and 100 that represents the speed of the
animation as a percentage of the maximum display rate.
The fastest animation is with a value of 100 and the slowest
is with a value of 0. The default animation rate is 100.
The animation must be initialized using the SET
keyword before calling XINTERANIMATE with a rate value.
KEYWORD PARAMETERS:
CLOSE: Set this keyword to delete the offscreen pixwins and Widget,
freeing storage.
CYCLE: If set, cycle. Normally, frames are displayed going either
forward or backwards. If CYCLE is set, reverse direction
after the last frame in either direction is displayed.
Provide this keyword with the SET keyword.
FRAME: The frame number when loading frames. This keyword only has
an effect when used in conjunction with the SET keyword.
FRAME must be set to a number in the range 0 to Nframes-1.
GROUP: The widget ID of the widget that calls XINTERANIMATE. When
this ID is specified, the death of the caller results in the
death of XINTERANIMATE.
IMAGE: A single image to be loaded at the animation position given
by FRAME. The keyword parameter FRAME must also be specified.
KEEP_PIXMAPS: If TRUE, XINTERANIMATE doesn't destroy the animation
pixmaps when it is killed. Calling it again without
going through the SET and LOAD steps will cause the same
animation to play without the overhead of creating
the pixmaps.
BLOCK: Set this keyword to have XMANAGER block when this
application is registered. By default the Xmanager
keyword NO_BLOCK is set to 1 to provide access to the
command line if active command line processing is available.
Note that setting BLOCK for this application will cause
all widget applications to block, not only this
application. For more information see the NO_BLOCK keyword
to XMANAGER.
ORDER: Set this keyword to display images from the top down instead
of the default bottom up. This keyword is only used when
loading images.
MODAL: If set, then XINTERANIMATE runs in "modal" mode, meaning that
all other widgets are blocked until the user quits
XINTERANIMATE.
MPEG_OPEN: Set this keyword to open an MPEG file.
MPEG_FILENAME: Set this keyword equal to a string for the desired
MPEG filename. If not set, idl.mpg is used.
MPEG_QUALITY : Set this keyword to a value between 0 (low quality)
and 100 (high quality) to control the quality of the movie file.
MPEG_BITRATE, MPEG_IFRAME_GAP, MPEG_MOTION_VEC_LENGTH : See the
documentation for the IDLgrMPEG object for information on
using these keywords for finer control of the MPEG quality.
In most situations, the MPEG_QUALITY keyword should be
sufficient.
MPEG_CLOSE: Set this keyword to write the MPEG file.
SHOWLOAD: Set this keyword (in conjunction with the SET keyword) to
display each frame and update the frame slider as frames are
loaded.
SET: This keyword initializes XINTERANIMATE. SET should be equated
to a 3-element integer vector containing the following
parameters:
Sizex, Sizey: The width and height of the images to be
displayed, in pixels.
Nframes: The number of frames in the animated sequence
(since XINTERANIMATE is an animation routine,
Nframes must be at least 2 frames).
TITLE: A string to be used as the title of the widget. If this
keyword is not specified, the title is set to "XInterAnimate"
This keyword has an effect only when used in conjunction with
the SET keyword).
TRACK: If set, the frame slider tracks the current frame. Default
is not to track. Provide this keyword with the SET keyword.
WINDOW: When this keyword is specified, an image is copied from an
existing window to the animation pixmap. When using X
windows, this technique is much faster than reading
from the display and then calling XINTERANIMATE with a 2D
array.
The value of this parameter is either an IDL window
number (in which case the entire window is copied),
or a vector containing the window index and the rectangular
bounds of the area to be copied, for example:
WINDOW = [Window_Number, X0, Y0, Sx, Sy]
XOFFSET: The horizontal offset, in pixels from the left of the frame,
of the image in the destination window.
YOFFSET: The vertical offset, in pixels from the bottom of the frame,
of the image in the destination window.
OUTPUTS:
No explicit outputs.
CALLS: ***
CW_ANIMATE, CW_ANIMATE_GETP, CW_ANIMATE_LOAD, CW_ANIMATE_RUN, MPEG_CLOSE, MPEG_PUT
MPEG_SAVE, XINTANIM_EVENT, XINTANIM_KILL_PIX, XMANAGER, XREGISTERED
COMMON BLOCKS:
XINTERANIMATE_COM: a private common block.
SIDE EFFECTS:
A pixmap and widget are created.
RESTRICTIONS:
Only a single copy of XINTERANIMATE can run at a time.
PROCEDURE:
When initialized, this procedure creates an approximately square
pixmap or memory buffer, large enough to contain Nframes of
the requested size. Once the images are loaded, using the
IMAGE and FRAME keywords, they are displayed by copying the images
from the pixmap or buffer to the visible draw widget.
EXAMPLE:
Enter the following commands to open the file ABNORM.DAT (a series
of images of a human heart) and animate the images it contains using
XINTERANIMATE. For a more detailed example of using XINTERANIMATE,
see the example in the "Using IDL Widgets" chapter of "IDL Basics".
Read the images into the variable H by entering:
OPENR, 1, FILEPATH('abnorm.dat', SUBDIR = 'examples/data')
H = BYTARR(64, 64, 16)
READU, 1, H
CLOSE, 1
H = REBIN(H, 128, 128, 16)
Initialize XINTERANIMATE with the command:
XINTERANIMATE, SET=[128, 128, 16], /SHOWLOAD
Load the images into XINTERANIMATE and play the animation by entering:
FOR I=0,15 DO XINTERANIMATE, FRAME = I, IMAGE = H[*,*,I]
XINTERANIMATE
MODIFICATION HISTORY:
DMS, April, 1990.
SMR, December, 1990. Modified the XANIMATE code to work
interactively with widgets.
DMS, March, 1991. Modified the routine to use individual pixmaps
for each frame of the animation. Also added
the ability to read in from current IDL
windows directly into offscreen bitmap.
SMR, March, 1991. Modified to use new XMANAGER keyword CLEANUP
to clean up the offscreen pixmaps when dying.
SMR, Jan, 1992. Modified the /CLOSE portion to check for a
valid widget before using WIDGET_CONTROL
and /DESTROY.
AB, June 1992 Rewrite using the new CW_ANIMATE compound
widget. Added the KEEP_PIXMAPS keyword.
DJE, April, 1996 Replaced XANNOUNCE with DIALOG_MESSAGE
SJL, December, 1997 Added MPEG capability.
LP, 6/16/98 Added MODAL keyword.
[Previous]
[Next]
NAME:
XLOADCT
PURPOSE:
A graphical interface to the LOADCT user library procedure.
XLOADCT displays the current color map and provides
an array of buttons, one per availible predefined color
table. Using the mouse to press these buttons causes
the corresponding color map to be loaded.
CATEGORY:
Widgets
CALLING SEQUENCE:
XLOADCT
INPUTS:
None.
KEYWORDS:
FILE: If this keyword is set, the file by the given name is used
instead of the file colors1.tbl in the IDL directory. This
allows multiple IDL users to have their own color table file.
GROUP = The widget ID of the widget that calls XLoadct. When
this ID is specified, a death of the caller results in a
death of XLoadct
NCOLORS = number of colors to use. Use color indices from BOTTOM
to the smaller of !D.TABLE_SIZE-1 and NCOLORS-1.
Default = !D.TABLE_SIZE = all available colors.
BOTTOM = first color index to use. Use color indices from BOTTOM to
BOTTOM+NCOLORS-1. Default = 0.
SILENT - Normally, no informational message is printed when
a color map is loaded. If this keyword is present and
zero, this message is printed.
USE_CURRENT: If set, use the current color tables, regardless of
the contents of the COMMON block COLORS.
MODAL: If set, then XLOADCT runs in "modal" mode, meaning that
all other widgets are blocked until the user quits XLOADCT.
A group leader must be specified (via the GROUP keyword)
for the MODAL keyword to have any effect. The default
is to not run in modal mode.
BLOCK: Set this keyword to have XMANAGER block when this
application is registered. By default the Xmanager
keyword NO_BLOCK is set to 1 to provide access to the
command line if active command line processing is available.
Note that setting BLOCK for this application will cause
all widget applications to block, not only this
application. For more information see the NO_BLOCK keyword
to XMANAGER.
UPDATECALLBACK: Set this keyword to a string containing the name of
a user-supplied procedure that will be called when the color
table is updated by XLOADCT. The procedure may optionally
accept a keyword called DATA, which will be automatically
set to the value specified by the optional UPDATECBDATA
keyword.
UPDATECBDATA: Set this keyword to a value of any type. It will be
passed via the DATA keyword to the user-supplied procedure
specified via the UPDATECALLBACK keyword, if any. If the
UPDATECBDATA keyword is not set the value accepted by the
DATA keyword to the procedure specified by UPDATECALLBACK
will be undefined.
OUTPUTS:
None.
CALLS: ***
COLORMAP_APPLICABLE, CW_BGROUP, FILEPATH, LOADCT, REVERSE, XDISPLAYFILE
XLCT_ALERT_CALLER, XLCT_DRAW_CPS, XLCT_PSAVE, XLCT_SHOW, XLCT_TRANSFER
XLOADCT_EVENT, XMANAGER, XREGISTERED
CALLED BY:
CW_ANIMATE, SLICER3, XBM_EDIT, XMNG_TMPL, XPALETTE, XSURFACE
COMMON BLOCKS:
None.
SIDE EFFECTS:
One of the predefined color maps may be loaded.
RESTRICTIONS:
This routine uses the LOADCT user library procedure to
do the actual work.
MODIFICATION HISTORY:
24, August, 1990, Written by AB, RSI.
March 1, 1992 Mark Rivers added Reverse Table to options menu.
7/92, DMS, Added new color tables (allows more than 16).
9/92, ACY, Add FILE keyword.
10/1/96, AB, Removed the PICK_ONE keyword. It was broken for 4 years
without anyone noticing, and the idea doesn't really fit
XLOADCT anymore.
1/10/97, DJC - Fixed color bar display bug, and added "MODAL" keyword.
1/13/96, AB, Improved the saving and restoring of the current
graphics window to prevent other applications from drawing
on this applications windows.
1/17/97, DJC - Moved group_leader keyword from "XManager" to
"WIDGET_BASE". Added check to ignore "MODAL" keyword
if a group leader is not specified.
8/20/98, ACY - Added UPDATECALLBACK and UPDATECBDATA keywords.
[Previous]
[Next]
NAME:
XMANAGER
PURPOSE:
Provide management for widgets client applications created using IDL.
CATEGORY:
Widgets.
CALLING SEQUENCE:
XMANAGER [, Name, ID]
OPTIONAL INPUTS:
NAME: A string giving the name of the application that is being
registered.
ID: The widget ID of the top level base of the new client.
KEYWORD PARAMETERS:
BACKGROUND:
-------------------------------------------------------------
| PLEASE NOTE: This keyword is OBSOLETE. It's functionality |
| is provided by the TIMER keyword to the WIDGET_CONTROL |
| procedure. |
-------------------------------------------------------------
CATCH: If TRUE, tells XMANAGER to use CATCH when dispatching
widget events. If FALSE, CATCH is not used and execution
halts on error. The default is TRUE. If CATCH is specified,
the internal state of XMANAGER is updated and it returns
immediately without taking any further action. CATCH
is only effective if XMANAGER is blocking to dispatch
errors. If active command line event dispatching is in
use, it has no effect.
CLEANUP: This keyword contains a string that is the name of the
routine called when the widget dies. If not specified,
no routine is called. The cleanup routine must accept one
parameter which is the widget id of the dying widget. This
routine is set as the KILL_NOTIFY routine for the widget.
EVENT_HANDLER: The name of the event handling routine that is to be
called when a widget event occurs in the registered
application. If this keyword is not supplied, the Xmanager
will construct a default name by adding the "_EVENT" suffix
to the NAME argument. See below for a more detailed
explanation.
GROUP_LEADER: The widget id of the group leader for the application
being registered. When the leader dies, all widgets that have
that leader will also die.
For example, a widget that views a help file for a demo
widget would have that demo widget as it's leader. When
the help widget is registered, it sets the keyword
GROUP_LEADER to the widget id of the demo widget. If
the demo widget is destroyed, the help widget led by
the it would be killed by the XMANAGER.
JUST_REG:
This keyword tells the manager to just register the widget
but not to start doing the event processing. This is useful
when you want to register a group of related top level widgets
but need to regain control immediately afterwards.
NOTE: JUST_REG does not do the same thing as NO_BLOCK. This is
explained in detail below under "SIDE EFFECTS".
MODAL:
--------------------------------------------------------------
| PLEASE NOTE: This keyword is OBSOLETE. It's functionality |
| is provided by the MODAL keyword to the WIDGET_BASE |
| procedure. |
--------------------------------------------------------------
When this keyword is set, the widget that is being registered
traps all events and desensitizes all the other widgets. It
is useful when input from the user is necessary before
continuing. Once the modal widget dies, the others are
resensitized and the normal event processing is restored.
XMANAGER is therefore using sensitivity to provide the
illusion of modality. The WIDGET_BASE keyword is a newer
IDL feature that provides the real thing.
NO_BLOCK: If set, tells XMANAGER that the registering client
does not require XMANAGER to block if active command line
event processing is available. If active command line
event processing is available *AND* every current XMANAGER
client specifies NO_BLOCK, then XMANAGER will not block
and the user will have access to the command line while
widget applications are running.
NOTE: NO_BLOCK does not do the same thing as JUST_REG. This is
explained in detail below under "SIDE EFFECTS".
OUTPUTS:
No outputs.
CALLS: ***
ADDMANAGEDWIDGET, LOOKUPMANAGEDWIDGET, VALIDATEMANAGEDWIDGETS
XMANAGERPRINTERROR, XMANAGER_EVLOOP_FAKE_MODAL, XMANAGER_EVLOOP_REAL_MODAL
XMANAGER_EVLOOP_STANDARD, XUNREGISTER
CALLED BY:
ANNOTATE, ASCII_TEMPLATE, BINARY_TEMPLATE, CREATEPROPSHEET, CREATETREE, CW_ARCBALL
CW_FORM, CW_PANES [1], CW_PANES_DASHED_BAR, CW_PANES_DISPLAY_SLIDER_BAR
CW_PANES_DRAW_SLIDER_BAR, CW_PANES_EVENT, CW_PANES_GET, CW_PANES_KILL
CW_PANES_LINE_EVENT, CW_PANES_NULL_EVENT, CW_PANES_REALIZE_LINE
CW_PANES_RIGHT_BUTTON, CW_PANES_SET, DIALOG_READ_IMAGE, DIALOG_WIZARD
DIALOG_WRITE_IMAGE, EFONT, H5_BROWSER, IDLITWDBROWSER_EVENT
IDLITWDBROWSER_SET_EVENT, IDLitWdToolSplash, IDLitwdAbout, IDLitwdBrowser
IDLitwdBrowserPrefs, IDLitwdBrowserPrefs_EVENT, IDLitwdCLExport
IDLitwdConvolKernel, IDLitwdCurveFitting, IDLitwdDataBottomTop
IDLitwdIsovalues, IDLitwdMacroEditor, IDLitwdOperationPreview
IDLitwdPaletteEditor, IDLitwdPromptText, IDLitwdPropertyPreview
IDLitwdPropertySheet, IDLitwdRotateByAngle, IDLitwdStyleApply
IDLitwdStyleCreate, IDLitwdStyleEditor, IDLitwdSubVolume, IDLitwdTextdisplay
IDLitwdTool, IDLitwdToolbar [1], IDLitwdToolbar_Destroy, ONLINE_HELP_PDF_INDEX
PREF_MIGRATE, SLICER3, SLIDE_IMAGE, XBM_EDIT, XDISPLAYFILE, XFONT, XINTERANIMATE
XLOADCT, XMNG_TMPL, XMTOOL, XPALETTE, XPCOLOR, XROI, XSURFACE, XVAREDIT, cw_panes [2]
dicomex_net_startup, idlitwdtoolbar [2], xobjview, xplot3d
COMMON BLOCKS:
MANAGED
XMANAGER_LOCAL:
Common blocks used for module state maintenance. These common
blocks are considered private to this module and should not
be referenced outside RSI supplied routines. They are
subject to change without notice.
SIDE EFFECTS:
JUST_REG vs NO_BLOCK
--------------------
Although their names imply a similar function, the JUST_REG and
NO_BLOCK keywords perform very different services. It is important
to understand what they do and how they differ.
JUST_REG tells XMANAGER that it should simply register a client
and then return immediately. The result is that the client becomes
known to XMANAGER, and that future calls to XMANAGER will take this
client into account. Therefore, JUST_REG only controls how the
registering call to XMANAGER should behave. The registered client
can still be registered as requiring XMANAGER to block by not setting
NO_BLOCK. In this case, future calls to XMANAGER will block.
NO_BLOCK tells XMANAGER that the registered client does not
require XMANAGER to block if the command processing front end
is able to support active command line event processing (described
below). XMANAGER remembers this attribute of the client until
the client exits, even after the call to XMANAGER that registered the
client returns. NO_BLOCK is just a "vote" on how XMANAGER should
behave. The final decision is made by XMANAGER by considering the
NO_BLOCK attributes of all of its current clients as well as the
ability of the command front end in use to support the active command
line.
Blocking vs Non-blocking
------------------------
The issue of blocking in XMANAGER requires some explanation.
IDL places incoming widget events into a queue of pending events.
The only way to get these events processed and dispatched is to
call the WIDGET_EVENT function. Arranging for WIDGET_EVENT to be
called properly is the primary job of XMANAGER. XMANAGER offers
two different modes of operation:
- The first (outermost) XMANAGER processes events by calling
WIDGET_EVENT as necessary until no managed clients remain on
the screen. This is referred to as "blocking", because XMANAGER
does not return to the caller until it is done, and the IDL
command line is not available.
- XMANAGER does not block, and instead, the part of IDL
that reads command input also watches for widget events
and calls WIDGET_EVENT as necessary while also reading
command input. This is referred to as "non-blocking" or
"active command line" mode.
The default is to block. However, if every currently active
application specified the NO_BLOCK keyword to XMANAGER, non-blocking
mode is used, if possible.
There are currently 5 separate IDL command input front end
implementations:
- Apple Macintosh IDE
- Microsoft Windows IDE
- Motif IDE (Unix and VMS)
- Unix plain tty
- VMS plain tty
Except for the VMS plain tty, all of these front ends are able to
support the non-blocking active command line. VMS users can have
an active command line by using the IDLde interface. The decision
on whether XMANAGER blocks to process widget events is determined
by the following rules, in order of precedence:
- Use of the MODAL keyword will cause XMANAGER to block.
- Setting JUST_REG to 1 ensures that XMANAGER will not block.
- If using the VMS plain tty interface, XMANAGER will block.
- If none of the previous rules apply, XMANAGER will block
if any of its currently active clients were registered without
specifying NO_BLOCK. If NO_BLOCK is specified for every client,
XMANAGER will not block and will instead return and allow
active command line processing to take place.
When possible, applications should set the NO_BLOCK keyword.
This allows the IDL command line to be active while events are
being processed, which is highly desirable.
RESTRICTIONS:
The implementation of XMANAGER may change in the future. Details
of its internal implementation must not be relied upon --- only
its external definition can be considered stable.
XMANAGER uses several undocumented features provided by the
internal WIDGET routines. These features are private to RSI, and
are not guaranteed to remain in IDL or to remain unchanged. They
exist only to support XMANAGER and should not be used elsewhere:
WIDGET_CONTROL, /XMANAGER_ACTIVE_COMMAND
WIDGET_CONTROL, /MODAL
WIDGET_EVENT, /BREAK_ON_EXPOSE
WIDGET_EVENT, /EVENT_BREAK
WIDGET_EVENT, /XMANAGER_BLOCK
WIDGET_INFO, /XMANAGER_BLOCK
These features are undocumented because they are not considered
permanent. Research Systems reserves the right to remove or alter
these features at any time.
EXAMPLE USE:
To create a widget named Example that is just a base widget with a done
button using the XMANAGER you would do the following:
;------ first - the event handler routine ------;
PRO example_event, ev ;this is the routine that
;deals with the events in the
;example widget.
WIDGET_CONTROL, ev.id, GET_UVALUE = uv ;the uservalue is retrieved
;from the widget where the
;event occurred
if(uv eq 'DONE') then $ ;if the event occurred in the
WIDGET_CONTROL, ev.top, /DESTROY ;done button then kill the
END ;widget example
;------ second - the main routine ------;
PRO example ;this is the main routine
;that builds the widget and
;registers it with the Xmanager
base = WIDGET_BASE(TITLE = 'Example') ;first the base is created
done = WIDGET_BUTTON(base, $ ;next the done button is
TITLE = 'DONE', $ ;created and it's user value
UVALUE = 'DONE') ;set to "DONE"
WIDGET_CONTROL, base, /REALIZE ;the widget is realized
XManager, 'example', base ;finally the example widget
;is registered with the
;Xmanager
END
notes: First the event handler routine is listed. The handler
routine has the same name as the main routine with the
characters "_event" added. If you would like to use another
event handler name, you would need to pass it's name in as
a string to the EVENT_HANDLER keyword. Also notice that the
event routine is listed before the main routine. This is
because the compiler will not compile the event routine if
it was below the main routine. This is only needed if both
routines reside in the same file and the file name is the same
as the main routine name with the ".pro" extension added.
PROCEDURE:
When the first widget is registered, initialize the lists and then
start processing events. Continue registering widgets and dispatching
events until all the widgets have been destroyed. When a widget is
killed, destroy all widgets that list the destroyed widget as their
leader, if any.
RELATED FUNCTIONS AND PROCEDURES:
XREGISTERED, XMTOOL
MODIFICATION HISTORY: Written by Steve Richards, November, 1990
SMR, Mar, 1991 Added a cleanup routine keyword to allow dying
widgets to clean themselves up when dying.
SMR, May, 1991 Fixed a bug found by Diane Parchomchuk where an error
occurred when registering a widget ight after destroying another.
SMR & ACY, July, 1991
Fixed a bug found by Debra Wolkovitch where lone widgets being
destroyed and new ones created caused problems.
SMR, Sept, 1991 Changed cleanup to use the new WIDGET_INFO routine.
SMR & ACY, Oct, 1991
Fixed a bug where a background event that unregistered itself
after a time would result in an XMANAGER error.
SMR, Mar. 1992 Changed XMANAGER to use enhanced widget functions for
event processing.
SMR, Nov. 1992 Changed modal widget handling allowing nesting of
modal widgets. The first modal desensitizes all current widgets
and subsequent modals only desensitize the modal that called them.
JIY, Apr. 1993 Changed modal widget handling process to not run the
event loop for nested modal widgets. Allowed for multiple modal
widgets.
AB & SMR, 17 November 1993
Added ID validity checking to desensitizing of modal widgets to
fix a bug where already dead widgets were being accessed.
DJE, Feb, 1995
Made it so that non-modal widgets created from a modal widget have
events processed in the modal widget's event loop. This fixes a
bug where xmanager wouldn't return immediately if there was a
modal widget somewhere in the nesting, even though a non-modal
widget was being added. The nesting level could get _very_ deep.
DJE, Apr 1995
Pass a local variable to WIDGET_EVENT in the MODAL case, instead
of passing the common block variable modalList. This avoids a bug
where modalList gets changed behind WIDGET_EVENT's back.
DJE, Apr 1996
Changes for handling asynchronous widget event dispatching.
Complete rewrite. Background tasks are no longer supported. The
MODAL keyword is now obsolete. Added CATCH and BLOCK keywords.
AB, May 1996
Made changes so that XMANAGER always blocks under VMS with the
non-GUI interface. This is due to the fact that the SMG$ system
routines used by IDL in the plain tty case cannot support
interleaving of X events with tty input.
AB, 9 January 1997
Changed the meaning of the CATCH keyword so that catching is the
default. Removed BLOCK and replaced with NO_BLOCK. Switched
default action back to blocking from unblocking based on feedback
from the IDL 5 beta. Added the ability to block only as long as a
client without NO_BLOCK is running, and then revert to the active
command line.
AB, 10 February 1997
Cleaned up code to make it easier to understand and maintain.
Also cleaned up the distinction between real modality (MODAL
keyword to WIDGET_BASE) and XMANAGER's older fake modality
(MODAL keyword to XMANAGER), and fixed bugs in the current
implementation of fake modality.
[Previous]
[Next]
NAME:
XMNG_TMPL
PURPOSE:
This routine is a template for widgets that use the XManager. Use
this template instead of writing your widget applications from
"scratch".
This documentation should be altered to reflect the actual
implementation of the XMNG_TMPL widget. Use a global search and
replace to replace the word "Xmng_tmpl" with the name of the routine
you would like to use.
All the comments with a "***" in front of them should be read, decided
upon and removed for your final copy of the XMng_tmpl widget
routine.
CATEGORY:
Widgets.
CALLING SEQUENCE:
XMNG_TMPL
INPUTS:
OPTIONAL INPUT PARAMETERS:
KEYWORD PARAMETERS:
GROUP: The widget ID of the widget that calls XMng_tmpl. When this
ID is specified, the death of the caller results in the death
of Xmng_tmpl.
BLOCK: Set this keyword to have XMANAGER block when this
application is registered. By default the Xmanager
keyword NO_BLOCK is set to 1 to provide access to the
command line if active command line processing is available.
Note that setting BLOCK for this application will cause
all widget applications to block, not only this
application. For more information see the NO_BLOCK keyword
to XMANAGER.
OUTPUTS:
OPTIONAL OUTPUT PARAMETERS:
CALLS: ***
CW_PDMENU, XLOADCT, XMANAGER, XMNG_TMPL_EV, XMTOOL, XPALETTE, XREGISTERED
COMMON BLOCKS:
SIDE EFFECTS:
Initiates the XMANAGER if it is not already running.
RESTRICTIONS:
PROCEDURE:
Create and register the widget and then exit.
MODIFICATION HISTORY:
Created from a template written by: Steve Richards, January, 1991.
[Previous]
[Next]
NAME:
XMTOOL
PURPOSE:
Provide a tool for viewing Widgets currently being managed by the
XMANAGER.
CATEGORY:
Widgets.
CALLING SEQUENCE:
XMTOOL
KEYWORD PARAMETERS:
GROUP: The widget ID of the group leader that the XMANAGERTOOL
is to live under. If the group is destroyed, the
XMANAGERTOOL is also destroyed.
BLOCK: Set this keyword to have XMANAGER block when this
application is registered. By default the Xmanager
keyword NO_BLOCK is set to 1 to provide access to the
command line if active command line processing is available.
Note that setting BLOCK for this application will cause
all widget applications to block, not only this
application. For more information see the NO_BLOCK keyword
to XMANAGER.
CALLS: ***
UPDATEXMTOOLLIST, VALIDATEMANAGEDWIDGETS, XMANAGER, XMANTOOL_EVENT, XREGISTERED
CALLED BY:
XBM_EDIT, XMNG_TMPL, XSURFACE
SIDE EFFECTS:
This procedure creates a widget that has the ability to destroy other
widgets being managed by the XManager.
RESTRICTIONS:
Only one instance of the XMANAGERTOOL can run at one time.
PROCEDURE:
Initiate the widget and then let the timer routine update the
lists as the widgets being managed by the XMANAGER are changed.
MODIFICATION HISTORY:
Written by Steve Richards, Dec, 1990.
SMR - 6/93 Modified the routine to work with a timer instead
of the obsolete background tasks.
[Previous]
[Next]
FILE:
xobjview.pro
CALLING SEQUENCE:
xobjview, oObj
INPUTS:
Argument oObj is a reference to an atomic graphics object, a
reference to an IDLgrModel, or an array of such references.
INPUT KEYWORDS:
XSIZE Pixels. Size of drawable.
YSIZE Pixels. Size of drawable.
STATIONARY Non-moveable objects (e.g. lights) to be viewed.
GROUP Group leader widget.
BLOCK If set, block IDL command line.
JUST_REG If set, register and return (XMANAGER)
MODAL If set, block other IDL widgets from receiving
events.
SCALE Size factor for initial view. Default: 1/sqrt(3).
TITLE String to appear in Xobjview's title bar.
TEST If set, don't require oObj arg. Draw a blue
sinusoidal surface instead.
DOUBLE_VIEW Set this keyword for high precision (i.e.
"double precision") graphics.
BACKGROUND Three-element [r,g,b] color vector.
REFRESH Set this keyword to a Top-level base of an XOBJVIEW
to force a redraw of that XOBJVIEW's graphics.
XOFFSET Pixels. Horzontal postion of XOBJVIEW on the screen.
YOFFSET Pixels. Vertical postion of XOBJVIEW on the screen.
USE_INSTANCING Set this keyword to enable "instancing." XOBJVIEW
will use IDL's CREATE_INSTANCE functionality when
drawing graphics, and will use DRAW_INSTANCE if
and when the current graphic is hidden and then
exposed by the user. See IDLLgrWindow::Draw
documentation for definitions of CREATE_INSTANCE
and DRAW_INSTANCE.
DEBUG Set this keyword to disable error catching and
recovery. With this keyword set, execution
of XOBJVIEW and/or its supporting routines
will stop where and if an error occurs (unless
other routines with error handling are overriding
this behavior). This stop-at-error behavior
is often helpful for troubleshooting.
OUTPUT KEYWORD:
TLB Top-level base widget.
PURPOSE:
Provide a quick way to see graphics objects on the screen.
CATEGORY:
Object Graphics.
REFERENCE: IDL Reference Guide, IDL User's Guide
A note about calling XOBJVIEW with the MODAL keyword set:
To be modal, XOBJVIEW does not require that its caller specify
a group leader. This is unlike other IDL widget procedures
such as XLOADCT, which, to be modal, do require that their
caller specify a group leader. In those other procedures,
the requirement exists to encourage the caller to create
a modal widget that will be well-behaved with respect to
Layering and Iconizing. (See WIDGET_BASE in the IDL Reference
Guide for explanations of "layering" and "iconizing".) For
the same reason the requirement exists in those procedures,
supplying an appropriate group leader when invoking
XOBJVIEW, /MODAL is good programming practice. Sometimes,
however, it is desirable to invoke XOBJVIEW, /MODAL in a
program that uses no other IDL widgets. For this reason,
XOBJVIEW allows itself to be invoked MODAL with no group leader.
EXAMPLE 1:
IDL> oObj = obj_new('IDLgrSurface', dist(30))
IDL> xobjview, oObj, /bloc
IDL> obj_destroy, oObj
EXAMPLE 2:
oObj = obj_new('IDLgrSurface', dist(30))
xobjview, oObj, tlb=tlb
...
oObj->SetProperty, color=[255, 0, 0]
xobjview, refresh=tlb
...
obj_destroy, oObj
CALLS: ***
DIST, UNIQ, XMANAGER, XOBJVIEW_CLEANUP, XOBJVIEW_EVENT, XOBJVIEW__FREE
MODIFICATION HISTORY:
9/1999 PCS - created.
11/1999 PCS - added Update method and related changes.
01/2000 PCS - added TITLE keyword and functionality.
07/2000 DMS - added REFRESH, TLB and BACKGROUND keywords.
[Previous]
[Next]
NAME:
XPALETTE
PURPOSE:
Interactively create color tables using the RGB, CMY, HSV, and
HLS color systems using the mouse, three sliders, and a cell
for each color index. Single colors can be defined or multiple
color indices between two endpoints can be interpolated.
CATEGORY:
Color tables, widgets.
CALLING SEQUENCE:
XPALETTE
INPUTS:
No explicit inputs. The current color table is used as a starting
point.
KEYWORD PARAMETERS:
BLOCK: Set this keyword to have XMANAGER block when this
application is registered. By default the Xmanager
keyword NO_BLOCK is set to 1 to provide access to the
command line if active command line processing is available.
Note that setting BLOCK for this application will cause
all widget applications to block, not only this
application. For more information see the NO_BLOCK keyword
to XMANAGER.
UPDATECALLBACK: Set this keyword to a string containing the name of
a user-supplied procedure that will be called when the color
table is updated by XLOADCT. The procedure may optionally
accept a keyword called DATA, which will be automatically
set to the value specified by the optional UPDATECBDATA
keyword.
UPDATECBDATA: Set this keyword to a value of any type. It will be
passed via the DATA keyword to the user-supplied procedure
specified via the UPDATECALLBACK keyword, if any. If the
UPDATECBDATA keyword is not set the value accepted by the
DATA keyword to the procedure specified by UPDATECALLBACK
will be undefined.
OUTPUTS:
None.
CALLS: ***
COLORMAP_APPLICABLE, CT_LUMINANCE, CW_BGROUP, CW_COLORSEL, CW_FIELD, CW_RGBSLIDER
FILEPATH, XDISPLAYFILE, XLOADCT, XMANAGER, XPALETTE_KILLNOTIFY, XP_ALERT_CALLER
XP_BUTTON_EVENT, XP_CHANGE_COLOR, XP_CURRENT_COLOR, XP_EVENT, XP_NEW_COLORS
XP_REDRAW, XP_REPLOT, XP_XLCTCALLBACK, XREGISTERED
CALLED BY:
XBM_EDIT, XMNG_TMPL, XSURFACE
COMMON BLOCKS:
COLORS: Contains the current RGB color tables.
XP_COM: Private to this module.
SIDE EFFECTS:
XPALETTE uses two colors from the current color table as
drawing foreground and background colors. These are used
for the RGB plots on the left, and the current index marker on
the right. This means that if the user set these two colors
to the same value, the XPALETTE display could become unreadable
(like writing on black paper with black ink). XPALETTE minimizes
this possibility by noting changes to the color map and always
using the brightest available color for the foreground color
and the darkest for the background. Thus, the only way
to make XPALETTE's display unreadable is to set the entire color
map to a single color, which is highly unlikely. The only side
effect of this policy is that you may notice XPALETTE redrawing
the entire display after you've modified the current color.
This simply means that the change has made XPALETTE pick new
drawing colors.
The new color tables are saved in the COLORS common and loaded
to the display.
PROCEDURE:
The XPALETTE widget has the following controls:
Left: Three plots showing the current Red, Green, and Blue vectors.
Center: A status region containing:
1) The total number of colors.
2) The current color. XPALETTE allows changing
one color at a time. This color is known as
the "current color" and is indicated in the
color spectrum display with a special marker.
3) The current mark index. The mark is used to
remember a color index. It is established by
pressing the "Set Mark Button" while the current
color index is the desired mark index.
4) The current color. The special marker used in
color spectrum display prevents the user from seeing
the color of the current index, but it is visible
here.
A panel of control buttons, which do the following when
pressed:
Done: Exits XPALETTE.
Predefined: Starts XLOADCT to allow selection of one of the
predefined color tables.
Help: Supplies help information similar to this header.
Redraw: Completely redraws the display using the current
state of the color map.
Set Mark: Set the value of the mark index to the
current index.
Switch Mark: Exchange the mark and the current index.
Copy Current: Every color lying between the current
index and the mark index (inclusive) is given
the current color.
Interpolate: The colors lying between the current
index and the mark index are interpolated linearly
to lie between the colors of two endpoints.
Three sliders (R, G, and B) that allow the user to modify the
current color.
Right: A display which shows the current color map as a series of
squares. Color index 0 is at the upper left. The color index
increases monotonically by rows going left to right and top
to bottom. The current color index is indicated by a special
marker symbol. There are 4 ways to change the current color:
1) Press any mouse button while the mouse
pointer is over the color map display.
2) Use the "By Index" slider to move to
the desired color index.
3) Use the "Row" Slider to move the marker
vertically.
4) Use the "Column" Slider to move the marker
horizontally.
MODIFICATION HISTORY:
July 1990, AB. Based on the PALETTE procedure, which does
similar things using only basic IDL graphics
commands.
7 January 1991, Re-written for general use.
1 April 1992, Modified to use the CW_RGBSLIDER and CW_COLORSEL
compound widgets. The use of color systems other than
RGB is now supported.
15 June 1992, Modified to use the CW_FIELD and CW_BGROUP compound
widgets.
7 April 1993, Removed state caching. Fixed a bug where switching
the current index and the mark would fail to update the
current index label.
10 March 1997, Added !X.TYPE and !Y.TYPE to saved state.
20 Aug 1998, ACY - Added UPDATECALLBACK and UPDATECBDATA keywords.
29 Nov 2000, DD
Force all visuals to honor indexed colors; temporarily set
DEVICE, DECOMPOSED=0 as needed. Maintain a backing
store for the drawn plots and current color area. Update
the plots and current color swatch whenever the color table
changes. Only display 2 tickmarks (using an exact range) on
the X axis of the plots to avoid clutter. Do not attempt to
copy or interpolate if the current index and the marked index
are the same.
October 2002, CT, RSI: Add KillNotify so we can restore !P and the
original color table if the user cancels the dialog.
Also, be sure to always load the initial color table.
[Previous]
[Next]
NAME:
XPCOLOR
PURPOSE:
The primary purpose of this routine is to serve as an example for
the Widgets chapter of the IDL User's Guide.
XPCOLOR allows the user to adjust the value of the current foreground
plotting color, !P.COLOR. For a more flexible color editor,
try the XPALETTE User Library Procedure.
CATEGORY:
Color tables, widgets.
CALLING SEQUENCE:
XPCOLOR
INPUTS:
No explicit inputs. The current color table and the value of !P.COLOR
are used.
KEYWORD PARAMETERS:
GROUP - Group leader, as passed to XMANAGER.
OUTPUTS:
None.
CALLS: ***
COLORMAP_APPLICABLE, CW_BGROUP, CW_RGBSLIDER, XDISPLAYFILE, XMANAGER
XPCOLOR_EVENT
COMMON BLOCKS:
COLORS: Contains the current RGB color tables.
SIDE EFFECTS:
The new plotting foreground color is saved in the COLORS common
and loaded to the display.
PROCEDURE:
Three sliders (R, G, and B) allow the user to modify the
current color.
MODIFICATION HISTORY:
20 October 1993, AB, RSI
[Previous]
[Next]
NAME:
xplot3d
PURPOSE:
Provide an interactive version of IDL's plot_3dbox
command.
CATEGORY:
Widgets, Object Graphics. Plotting.
CALLING SEQUENCE:
xplot3d, x, y, z
REQUIRED INPUTS:
None. Fake data will be used if no data is supplied in call.
OPTIONAL INPUTS
x: A vector of X data values.
y: A vector of Y data values.
z: A vector of Z data values.
OPTIONAL KEYWORD PARAMETERS:
GROUP: Widget group_leader. When the group leader
is destroyed, this program will be destroyed.
MODAL: If set, block other IDL widgets from receiving events.
BLOCK: If set, block IDL command line.
TITLE: String. A title for the plot.
[XYZ]TITLE: String. Title for x, y or z axis.
NAME: A string. This is a name for the data curve being plotted.
The name is displayed on xplot3d's toolbar if/when
the curve is selected with the mouse. (To select
the curve with the mouse, xplot3d must
be in select mode. You can put xplot3d in select mode
by clicking on the rightmost button in xplot3d's
toolbar.)
[XYZ]RANGE: Two element array specifying axis range. [min, max]
OVERPLOT: Draw the curve in the most recently created view.
Title keywords, range keywords and the modal keyword are
ignored if we are overplotting.
LINESTYLE: Same as IDLgrPolyline::init keyword.
THICK: Same as IDLgrPolyline::init keyword.
COLOR: [r, g, b] triplet. Color of curve. Same as IDLgrPolyline.
SYMBOL: Same as IDLgrPolyline::init keyword.
TEST: If set, do not require input arguments. Plot an example
sinusoidal curve instead.
EXAMPLE 1:
IDL> x = indgen(20)
IDL> y = sin(x/3.)
IDL> z = x
IDL> xplot3d, x, y, z, thick=2, name='interesting curve'
EXAMPLE 2:
IDL> x = indgen(20)
IDL> y = sin(x/3.)
IDL> z = x
IDL> oOrb = obj_new('orb', color=[0, 0, 255])
IDL> oOrb->Scale, .75, .1, .5
IDL> oSymbol = obj_new('IDLgrSymbol', oOrb)
IDL> xplot3d, x, y, z, thick=2, symbol=oSymbol
KNOWN PROBLEMS:
Symbols (specified via the SYMBOL keyword) are not drawn in
a suitably muted color when projected (via the
"2D Projection..." menu functionality).
Heap variables may not be cleaned up properly if an error
occurs in procedure xplot3d.
CALLS: ***
DIALOG_WRITE_IMAGE, FILEPATH, LOOKUPMANAGEDWIDGET, NORM_COORD, XMANAGER
XPLOT3D_CLEANUP, XPLOT3D_EVENT, XPLOT3D__DRAW, XPLOT3D__FREE
XPLOT3D__SET_AXES_PROP, XPLOT3D__SET_BACKG_COLOR
XPLOT3D__SET_PROP_ON_CHILDREN, XPLOT3D__UPDATE_BUTTON_BMPS
[Previous]
[Next]
NAME:
XREGISTERED
PURPOSE:
This function returns non-zero if the widget named as its argument
is currently registered with the XMANAGER as an exclusive widget,
otherwise this routine returns false.
CATEGORY:
Widgets.
CALLING SEQUENCE:
Result = XREGISTERED(Name)
INPUTS:
Name: A string containing the name of the widget in question.
KEYWORD PARAMETERS:
NOSHOW: If the widget in question is registered, it is brought
to the front of all the other windows by default. Set this
keyword to keep the widget from being brought to the front.
OUTPUTS:
If the named widget is registered, XREGISTERED returns the number
of instances of that name in the list maintained by XMANAGER.
Otherwise, XREGISTERED returns 0.
CALLS: ***
LOOKUPMANAGEDWIDGET
CALLED BY:
EFONT, ONLINE_HELP_PDF_INDEX, PREF_MIGRATE, XBM_EDIT, XFONT, XINTERANIMATE, XLOADCT
XMNG_TMPL, XMTOOL, XPALETTE, XSURFACE
COMMON BLOCKS:
MANAGED
SIDE EFFECTS:
Brings the widget to the front of the desktop if it finds one.
RESTRICTIONS:
None.
PROCEDURE:
Searches the list of exclusive widget names and if a match is found
with the one in question, the return value is modified.
MODIFICATION HISTORY:
Written by Steve Richards, November, 1990
Jan, 92 - SMR Fixed a bug where an invalid widget
was being referenced with
WIDGET_CONTROL and the /SHOW keyword.
17 November 1993 - AB and SMR. Added ID validity checking to
fix a bug where already dead widgets were being
accessed.
Apr, 96 - DJE Rewrite for asynchronous widget event handling.
[Previous]
[Next]
NAME:
XROI
PURPOSE:
This procedure serves as utility for generating, displaying, and
manipulating regions of interest.
CATEGORY:
Utilites. Object graphics.
CALLING SEQUENCE:
XROI, [ImageData] [,r] [,g] [,b]
OPTIONAL INPUT/OUTPUT:
ImageData: An array representing an image to be displayed. Can be:
[m,n] -- 8-bit image.
[3,m,n] -- 24-bit image
[m,3,n] -- 24-bit image
[m,n,3] -- 24-bit image
If ImageData is not supplied, the user will be prompted for
a file via dialog_pickfile. On output, ImageData will be
set to the current image data. (The current image data
can be different than the input image data if the
user Imported an image via XROI's "Import Image..."
menu button.)
R: An array of bytes representing red color table values. On
input, these values are applied to the image if the image
is 8-bit. To get the red color table values for the image
on output from XROI, set this argument to a named variable.
(If the image is 24-bit, this argument will output a 256-
element byte array containing the values given at input,
or bindgen(256) if R was undefined on input.)
G: An array of bytes representing green color table values. On
input these values are applied to the image if the image
is 8-bit. To get the green color table values for the image
on output from XROI, set this argument to a named variable.
(If the image is 24-bit, this argument will output a 256-
element byte array containing the values given at input,
or bindgen(256) if G was undefined on input.)
B: An array of bytes representing blue color table values. On
input these values are applied to the image if the image
is 8-bit. To get the blue color table values for the image
on output from XROI, set this argument to a named variable.
(If the image is 24-bit, this argument will output a 256-
element byte array containing the values given at input,
or bindgen(256) if B was undefined on input.)
INPUT KEYWORD PARAMETERS:
BLOCK: If set, block IDL command line.
MODAL: If set, block other IDL widgets from receiving events.
GROUP: Group leader widget.
FLOATING: Set this keyword -- along with the GROUP_LEADER
keyword -- to create a "floating" top-level base widget.
If the windowing system provides Z-order control, floating
base widgets appear above the base specified as their group
leader. If the windowing system does not provide Z-order
control, the FLOATING keyword has no effect.
RENDERER: Set this keyword to an integer value to indicate which
graphics renderer to use when drawing objects within
the window. Valid values are:
0 = Platform native OpenGL
1 = IDL's software implementation (the default)
REGIONS_IN: Array of IDLgrROI references. This keyword also accepts
-1, or OBJ_NEW() (Null object) to indicate that there are no
regions_in.
TOOLS: Set this keyword to a string (or vector of strings) from the
list below to indicate which types of ROI manipulation tools
should be supported when the ROI example is run. If more than
one string is specified, a series of bitmap buttons will appear
at the top of the ROI example widget (to the right of the
fixed set of bitmap buttons used for saving regions, displaying
region information, and copying to clipboard). If only one
string is specified, no additional bitmap buttons will appear,
and the manipulation mode is implied by the given string. The
default is to activate all types of manipulation tools.
Valid strings:
'Translate-Scale' Translation and scaling. Mouse down selects
a region, mouse motion either scales or translates (depending
upon where the mouse down occurred).
'Rectangle' Rectangle ROI drawing. Mouse down begins a
rectangular region, mouse motion repositions a corner of the
rectangle, mouse up finishes the region.
'Ellipse' Ellipse ROI drawing. Mouse down begins an
elliptical region, mouse motion sizes the ellipse, mouse up
finishes the region.
'Freehand Draw' Freehand ROI drawing. Mouse down begins a
region, mouse motion adds vertices to the region (following
the path of the mouse), mouse up finishes the region.
'Polygon Draw' Polygon ROI drawing. Mouse down begins a
region, mouse motion temporarily locates the next vertex,
mouse up fixes the location of that vertex, double click finishes
the region.
'Selection' ROI selection. Mouse down/up selects the nearest
region. The nearest vertex in that region is identified with a
yellow crosshair symbol.
X_SCROLL_SIZE: Set this keyword to the width of the drawing area.
The default (and also the maximum) is the width of the image.
Y_SCROLL_SIZE: Set this keyword to the height of the drawing area.
The default (and also the maximum) is the height of the image.
OUTPUT KEYWORD PARAMETERS:
REGIONS_OUT: Array of IDLgrROI references. This keyword is assigned
the null object refernce if there are no regions_out.
REJECTED: Those regions_in that are not in regions_out. This keyword
is assigned the null object reference if no regions_in are rejected
by the user.
STATISTICS: Set this argument to a named variable to receive an array
of anonymous structures, one for each ROI that is valid when this
routine returns. The structures will contain: {
count: 0UL, $ ; Number of pixels in region.
minimum: 0.0, $ ; Pixel value.
maximum: 0.0, $ ; Pixel value.
mean: 0.0, $ ; Mean pixel value.
stddev: 0.0 $ ; Standard deviation of pixel values.
}
When this routine exits, if ImageData is 24-bit at that time,
or if there are no valid regions of interest at that time,
parameter STATISTICS will be undefined.
ROI_GEOMETRY: Set this argument to a named variable to receive an array
of anonymous structures, one for each ROI that is valid when this
routine returns. The structures will contain: {
area: 0.0, $
centroid: FLTARR(3), $
perimeter: 0.0 $
}
If there are no valid regions of interest when this routine returns,
ROI_GEOMETRY will be undefined.
INPUT/OUTPUT KEYWORD PARAMETERS:
ROI_SELECT_COLOR: A 3-element byte array indicating the color of
ROI outlines when they are selected. [r,g,b]
ROI_COLOR: A 3-element byte array indicating the color of
ROI outlines when they are not selected. [r,g,b]
CALLS: ***
CW_FIELD, CW_PALETTE_EDITOR, CW_RGBSLIDER, DIALOG_READ_IMAGE, FILEPATH, IPLOT
REGION_GROW, XMANAGER, XROIGROWPROPS, XROIGROWPROPS_EVENT, XROIHISTPLOT_EVENT
XROIINFO, XROIINFO_EVENT, XROIINFO__SETSTATS, XROILOADCT, XROILOADCT_EVENT
XROILOADCT__CLEANUP, XROIPICKCOLOR, XROIPICKCOLOR_EVENT
XROIPICKCOLOR__CLEANUP, XROI_EVENT, XROI__BASERESIZE, XROI__BUTTONPRESS
XROI__BUTTONRELEASE, XROI__CLEANUP, XROI__COPY, XROI__CREATEPICKVISUAL
XROI__CREATETRANSSCALEVISUAL, XROI__DELETESELECTEDROI, XROI__EXPOSE
XROI__GENERATENAME, XROI__GROWSELECTEDROI, XROI__HISTOGRAMSELECTEDROI
XROI__MOTION, XROI__QUIT, XROI__RESHAPESELECTIONVISUAL, XROI__SAVE
XROI__SCALEROI, XROI__SETROI, XROI__SETSELECTIONVISUALCOLOR
XROI__TRANSLATEROI, XROI__VIEWPORT, _IDLitsys_GetSystem
EXAMPLE:
To sweep through a series of images, maintaining a single list of
regions as we go:
images = randomu(seed, 5, 5, 2)
images = bytscl(congrid(images, 400, 400, 5))
for i=0,4 do begin
xroi, $
images[*, *, i], $
r, g, b, $
regions_in=regions, $
regions_out=regions, $
roi_select_color=roi_select_color, $
roi_color=roi_color, $
rejected=rejected, $
/bloc
obj_destroy, rejected
endfor
obj_destroy, regions
MODIFICATION HISTORY:
Written by: DD, Aug 1999
6/2000, PCS - Added features and changed from example to XROI command.
7/2001, DLD - Added rectangle, ellipse, and translate-scale tools.
Added support for region growing.
Added support for histogram plots for RGB images.
Improve support for RGB image interleaving.
DLD, Sept 2002: Cleanup LIVE tools environment if necessary.
CT, Sept 2002: Add tooltips. Change to exclusive buttons.
Disable context menu for segmented polygon ROI.
Add X_SCROLL_SIZE and Y_SCROLL_SIZE.
Use APP_SCROLL so we can handle huge images.
SM, June 2003: For histograms change LIVE_PLOT to iPlot
CT, Sept 2003: Destroy iPlots when widget exits
[Previous]
[Next]
NAME:
XSQ_TEST
PURPOSE:
This function computes the chi-squared goodness-of-fit test
between observed frequencies and the expected frequencies of
a theoretical distribution. The result is a two-element vector
containing the chi-squared test statistic X2 and probability
of obtaining a value of X2 or greater.
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = XSQ_TEST(OBFREQ, EXFREQ)
INPUTS:
OBFREQ: An n-element vector of type integer, float or double
containing observed frequencies.
EXFREQ: An n-element vector of type integer, float or double
containing expected frequencies.
KEYWORD PARAMETERS:
OBCELL: Use this keyword to specify a named variable which returns
a vector of observed frequencies used to formulate the chi-
squared test statistic. The elements of this vector are
often refered to as the "cells" of the observed frequencies.
The length of this vector is determined by the length of
EXCELL described below.
EXCELL: Use this keyword to specify a named variable which returns
a vector of expected frequencies used to formulate the chi-
squared test statistic. If each of the expected frequencies
contained in the n-element input vector, EXFREQ, has a
magnitude of 5 or greater, then this vector is identical to
EXFREQ. If EXFREQ contains elements of magnitude less than 5,
adjacent expected frequencies are combined. The identical
combinations are performed on the corresponding elements of
OBFREQ.
RESIDUAL: Use this keyword to specify a named variable which returns
a vector of signed differences between corresponding cells
of observed frequencies and expected frequencies.
RESIDUAL(i) = OBCELL(i) - EXCELL(i). The length of this
vector is determined by the length of EXCELL described
above.
CALLS: ***
CHISQR_PDF, FREQ_CELL
EXAMPLE:
Define the vectors of observed and expected frequencies.
obfreq = [2, 1, 4, 15, 10, 5, 3]
exfreq = [0.5, 2.1, 5.9, 10.3, 10.7, 7.0, 3.5]
Test the hypothesis that the given observed frequencies are
an accurate approximation to the expected frequency distribution.
result = $
xsq_test(obfreq, exfreq, obcell = obcell, excell = excell)
The result should be the two-element vector [3.05040, 0.383920].
Since the vector of expected frequencies contains elements of
magnitude less than 5, adjacent expected frequencies are combined
resulting in fewer cells. The identical combinations are performed
on the corresponding elements of observed frequencies.
The cells used to formulate the chi-squared test statistic are
contained in the keyword parameters, obcell and excell.
They should contain the values, [7, 15, 10, 8] and
[8.5, 10.3, 10.7, 10.5], respectively.
The computed value of 0.383920 indicates that there is no reason to
reject the proposed hypothesis at the 0.05 significance level.
PROCEDURE:
XSQ_TEST computes chi-squared goodness-of-fit test between observed
frequencies and the expected frequencies of a theoretical distribution.
Expected frequencies of magnitude less than 5 are combined with
adjacent elements resulting in a reduction of cells used to formulate
the chi-squared test statistic. If the observed frequencies differ
significantly from the expected frequencies, the chi-squared test
statistic will be large and the fit is poor. This situation requires
the rejection of the hypothesis that the given observed frequencies
are an accurate approximation to the expected frequency distribution.
REFERENCE:
PROBABILITY and STATISTICS for ENGINEERS and SCIENTISTS (3rd edition)
Ronald E. Walpole & Raymond H. Myers
ISBN 0-02-424170-9
MODIFICATION HISTORY:
Written by: GGS, RSI, August 1994
[Previous]
[Next]
NAME:
XSURFACE
PURPOSE:
This routine provides a graphical interface to the SURFACE and
SHADE_SURFACE commands. Different controls are provided to change
the viewing angle and other plot parameters. The command used to
generate the resulting surface plot is shown in a text window.
CATEGORY:
Widgets.
CALLING SEQUENCE:
XSURFACE, Data
INPUT PARAMETERS:
Data: The two-dimensional array to display as a wire-mesh or
shaded surface.
KEYWORD PARAMETERS:
GROUP: The widget ID of the widget that calls XSURFACE. When this
keyword is specified, the death of the caller results in the
death of XSURFACE.
BLOCK: Set this keyword to have XMANAGER block when this
application is registered. By default the Xmanager
keyword NO_BLOCK is set to 1 to provide access to the
command line if active command line processing is available.
Note that setting BLOCK for this application will cause
all widget applications to block, not only this
application. For more information see the NO_BLOCK keyword
to XMANAGER.
CALLS: ***
CW_PDMENU, XLOADCT, XMANAGER, XMTOOL, XPALETTE, XREGISTERED, XSURFACE_DRAW
XSURFACE_EV
SIDE EFFECTS:
The XMANAGER is initiated if it is not already running.
RESTRICTIONS:
XSURFACE does not accept any of the keywords that the IDL command
SURFACE does.
PROCEDURE:
Create and register the widget with the XMANAGER and then exit.
MODIFICATION HISTORY:
Created from a template written by: Steve Richards, January, 1991.
[Previous]
[Next]
NAME:
XVAREDIT
PURPOSE:
This routine provides an editor for any IDL variable.
CATEGORY:
Widgets
CALLING SEQUENCE:
XVAREDIT, VAR
INPUTS:
VAR = The variable that is to be edited.
KEYWORD PARAMETERS:
NAME = The NAME of the variable. This keyword is overwritten with the
structure name if the variable is a structure.
GROUP = The widget ID of the widget that calls XVarEdit. When this
ID is specified, a death of the caller results in a death of
XVarEdit.
X_SCROLL_SIZE = The X_SCROLL_SIZE keyword allows you to set
the width of the scrolling viewport in columns.
Default is 4.
Y_SCROLL_SIZE = The Y_SCROLL_SIZE keyword allows you to set
the height of the scrolling viewport in rows.
Default is 4.
OUTPUTS:
VAR= The variable that has been edited, or the original if the user
selects the "Cancel" button.
CALLS: ***
CW_BGROUP, XMANAGER, XVAREDITFIELD, XVAREDIT_EVENT, XVAREDIT__ADDEDITENTRY
XVAREDIT__N_ELEMENTS
COMMON BLOCKS:
None.
SIDE EFFECTS:
Initiates the XManager if it is not already running.
RESTRICTIONS:
None known.
PROCEDURE:
Display a table widget, a "cancel" button, and an "accept" button.
If the user clicks "accept", values in the table widget are
written to the variable being edited.
Note: Pointers and Object References are shown as blank cells. To
edit Pointer or Object References, enter valid IDL expressions
such as OBJ_NEW('IDLgrModel'), PTR_VALID(123, /CAST), etc. To
leave Ponters and Object References unchanged, leave their
corresponding cells blank.
MODIFICATION HISTORY:
Written by: Steve Richards, February, 1991
Modified: September 96, LP - rewritten with TABLE widget
Modified: March 2000, PCS - Added support for new data types
such as Unsigned Integer. Made Pointers and Object References
editable.
CT, RSI, April 2005: Disable editing in the IDL Virtual Machine.