This page is a listing of the entire contents of this library for IDL. This listing is the long version. Viewing the much more compact listing may be handier.
NAME:
break_file
PURPOSE:
Given a file name, break the filename into the parts
of disk/logical, the directory, the filename, the
extension, and the file version (for VMS)
INPUT:
file - The file name
OUTPUT:
disk_log- The disk or logical (looks for a ":")
This is generally only valid on VMS machines
dir - The directory
filnam - The filename (excluding the ".")
ext - The filename extension (including the ".")
fversion- The file version (only VMS)
node - The Node name (only VMS)
RESTRICTIONS:
VMS:
Assumes that : always precedes []
ULTRIX:
Right now it has trouble with the ultrix option of use
of "." or ".."
HISTORY:
Written 1988 by M.Morrison
Aug-91 (MDM) Changed to handle Unix filename convensions
28-Feb-92 (MDM) * Adjusted to handle arrays
11-Mar-92 (MDM) - Perform a STRTRIM(x,2) on input string before
doing the "break-up"
1-Dec-92 (MDM) - Moved code to do filename, extension and version
number for both VMS and Unix (previously it
did not do version number code for Unix)
29-Jan-93 (DMZ/MDM) - checked for node in file name
11-Nov-83 (DMZ) - checked for ".][" and "[000000" in VMS concealed directory names
5-Apr-95 (RSM) - didn't work for Windows. Easiest fix was to put old
code in an IF block, and then add the Windows code:
IF (!VERSION.OS NE 'WINDOWS') THEN BEGIN
...old code...
ENDIF ELSE BEGIN
...new Windows code...
ENDELSE
12-Jul-96 (RSM) - Good old IDL changed the !VERSION.OS string for
Window95 to 'Win32'. Added this to the IF block
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/break_file.pro)
NAME:
CREATE_ARRAY
PURPOSE:
Given the number of elements and the minumim and maximum values,
creates an array. The most complex datatype of the two
values MINV, MAXV will set the type of array.
The type of array is set by the most complex datatype of MINV, MAXV.
For example, the call X = CREATE_ARRAY(100, 0, 10.0) will return a
floating point array.
TYPE:
FUNCTION
CATEGORY:
Arrays
CALLING SEQUENCE:
RESULT = CREATE_ARRAY(NPTS, MINV, MAXV)
INPUTS:
NPTS = total number of array elements
MINV = the minimum value of the array
MAXV = the maximum value of the array
INPUT PARAMETERS:
NONE.
KEYWORD PARAMETERS:
NONE.
OUTPUTS:
RESULT = an array with the desired characteristics
COMMON BLOCKS:
NONE
SIDE EFFECTS:
NONE
RESTRICTIONS:
Does not work for arrays of structures, objects, or pointers
DEPENDENCIES:
NONE
MODIFICATION HISTORY:
Written by Robert.Mallozzi@msfc.nasa.gov, February, 1995.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/create_array.pro)
NAME:
CREATE_STRING
PURPOSE:
Create a STRING of a requested byte length, and optionally
initialize the string.
CATEGORY:
Arrays
CALLING SEQUENCE:
myString = CREATE_STRING (nBytes [, value, REPLICATE = replicate])
INPUTS:
nBytes (INTEGER) : number of bytes in the string (the string length)
value (STRING) : optional initial value for the string
INPUT PARAMETERS:
NONE
KEYWORD PARAMETERS:
REPLICATE (INTEGER): Create an array of STRINGS of length REPLICATE
OUTPUTS:
myString (STRING) : string of the requested length
COMMON BLOCKS:
NONE
SIDE EFFECTS:
NONE
RESTRICTIONS:
If value is set, its length must be LE to nBytes
MODIFICATION HISTORY:
RSM, 1998 August, added REPLICATE keyword.
Written, Robert.Mallozzi@msfc.nasa.gov, 1998 July.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/create_string.pro)
NAME:
DIALOG_CHECKLIST
PURPOSE:
A modal (blocking) dialog widget to display a selectable checklist
of exclusive (radio) or non-exclusive buttons. The dialog must be
dismissed by selecting an item before execution of the calling program
can continue.
TYPE:
FUNCTION
CATEGORY:
WIDGETS
CALLING SEQUENCE:
result = DIALOG_CHECKLIST (menu_items)
INPUTS:
menu_items : STRARR of choices
KEYWORD PARAMETERS:
TITLE : The menu title. Use STRARR for multi-line titles.
XSIZE : The x size of the widget.
YSIZE : The y size of the widget.
XPOSITION : The x position of the upper left corner of the widget.
XPOSITION : The y position of the upper left corner of the widget.
SCROLL : Adds a scroll bar.
X_SCROLL_SIZE : Size of x scroll region, if /SCROLL is set.
Y_SCROLL_SIZE : Size of y scroll region, if /SCROLL is set.
EXCLUSIVE : Only a single choice can be selected (DEFAULT).
NONEXCLUSIVE : Multiple, simultaneous choices can be selected.
INITIAL : INTARR denoting which buttons should be selected
when the widget is mapped. The array elements are
indices into MENU_ITEMS denoting the buttons to set
to on.
DIALOG_PARENT : Set this keyword to the widget ID of a widget over
which the message dialog should be positioned. When
displayed, the dialog will be positioned over the
specified widget. Dialogs are often related to a
non-dialog widget tree. The ID of the widget in that
tree to which the dialog is most closely related should
be specified.
If this keyword is not specified, the default placement
of the menu is the center of the screen (window manager
dependent).
OUTPUTS:
result: INTARR of length STRLEN (menu_items). Elements of the array
are 1 if the item was selected, otherwise 0. For an EXCLUSIVE
base (DEFAULT), only a single element will be set to 1.
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Creates a modal widget.
RESTRICTIONS:
None known.
DEPENDENCIES:
NONE
EXAMPLES:
result = DIALOG_CHECKLIST (['Item 1', 'Item 2', 'Item3'], $
TITLE = 'Select an Item')
result = DIALOG_CHECKLIST (['Item 1', 'Item 2', 'Item3'], $
TITLE = 'Select Some Items', /NONEXCLUSIVE)
MODIFICATION HISTORY:
v1.0: Written, Robert.Mallozzi@msfc.nasa.gov, July 1998.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/dialog_checklist.pro)
NAME:
DIALOG_INPUT
PURPOSE:
A modal (blocking) dialog widget to input a line of text.
The dialog must be dismissed, by entering text and pressing the
Return key, or by clicking on the 'Ok' or 'Cancel' button before
execution of the calling program can continue.
TYPE:
FUNCTION
CATEGORY:
WIDGETS
CALLING SEQUENCE:
result = DIALOG_INPUT ()
INPUTS:
NONE
KEYWORD PARAMETERS:
PROMPT: Optional STRING or STRARR displayed on the widget.
If the keyword NFIELDS is set, then PROMPT must be a
STRARR of length NFIELDS. If NFIELDS is not set, and PROMPT is
a STRARR, each element of the array will appear on a separate line.
If not supplied, default = 'Enter Text'
TITLE: Window title [default = 'dialog_input']
INITIAL: Initial value to show in the input area. If PROMPT is
supplied, this must be a array of length FIELDS.
XSIZE, YSIZE: The width and height of the dialog
WIDTH: Set the width of the input field IN CHARACTERS.
NFIELDS: Show multiple input fields. If PROMPT and/or INITIAL are
supplied, they must be STRARR of length FIELDS.
DIALOG_PARENT: Set this keyword to the widget ID of a widget over
which the message dialog should be positioned. When displayed,
the DIALOG_INPUT dialog will be positioned over the specified
widget. Dialogs are often related to a non-dialog widget tree.
The ID of the widget in that tree to which the dialog is most
closely related should be specified.
OK: STRING label for the 'Ok' button (default = 'Ok')
CANCEL: STRING label for the 'Cancel' button (default = 'Cancel')
OUTPUTS:
result: STRING or STRARR of input text, or '' if dialog is cancelled
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Creates a modal widget
RESTRICTIONS:
NONE
DEPENDENCIES:
NONE
MODIFICATION HISTORY:
v1.03: RSM, Aug 1998, Added WIDTH keyword to set the width of the
input field IN CHARACTERS. Fixed layout bug when using NFIELDS.
v1.02: RSM, May 1998, Non-backward compatible changes to allow multiple
input fields.
v1.01: RSM, Mar 1998, fixed error when used with a modal toplevel base.
v1.0: Written, Robert.Mallozzi@msfc.nasa.gov, July 1997.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/dialog_input.pro)
NAME:
DIALOG_LIST
PURPOSE:
A modal (blocking) dialog widget to display a selectable list.
The dialog must be dismissed by selecting a menu item before
execution of the calling program can continue.
TYPE:
FUNCTION
CATEGORY:
WIDGETS
CALLING SEQUENCE:
result = DIALOG_LIST (list_items)
INPUTS:
list_items: STRARR of list items
KEYWORD PARAMETERS:
TITLE: The list title
MULTIPLE: Allow multiple list selections
XSIZE: Width of the widget in PIXELS
YSIZE: Height of the list widget in LINES
DIALOG_PARENT: Set this keyword to the widget ID of a widget over
which the message dialog should be positioned. When displayed,
the DIALOG_MENU dialog will be positioned over the specified
widget. Dialogs are often related to a non-dialog widget tree.
The ID of the widget in that tree to which the dialog is most
closely related should be specified.
If this keyword is not specified, the default placement of the
menu is the center of the screen (window manager dependent).
INDEX: Optionally return the index of the selected item(s) instead of
the item text. The index of the first list_item is zero.
OUTPUTS:
result: STRARR of selected list items, or INTARR if INDEX keyword
is used, starting at index = 0. If no selections are made,
returns '' (or -1 if INDEX keyword is set)
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Creates a modal widget
RESTRICTIONS:
NONE
DEPENDENCIES:
NONE
EXAMPLES:
result = DIALOG_LIST(['Item 1', 'Item 2', 'Item 3'], $
TITLE = 'Select Items', /MULTIPLE)
MODIFICATION HISTORY:
v0.12: RSM, September 1998:
Allow multi-line titles.
v0.11: RSM, August 1998:
Added 'Cancel' button.
v0.10: Written, Robert.Mallozzi@msfc.nasa.gov, May 1998.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/dialog_list.pro)
NAME:
DIALOG_MENU
PURPOSE:
A modal (blocking) dialog widget to display a selectable menu.
The dialog must be dismissed by selecting a menu item before
execution of the calling program can continue.
TYPE:
FUNCTION
CATEGORY:
WIDGETS
CALLING SEQUENCE:
result = DIALOG_MENU (menu_items)
INPUTS:
menu_items: STRARR of menu items
KEYWORD PARAMETERS:
TITLE: The menu title. Use STRARR for multi-line titles.
XSIZE, YSIZE: x, y size of the widget.
XPOSITION, YPOSITION: The position of the upper left corner of the
dialog, relative to the upper left corner of the screen.
SCROLL: Adds a scroll bar
X_SCROLL_SIZE: Size of x scroll region, if /SCROLL is set
Y_SCROLL_SIZE: Size of y scroll region, if /SCROLL is set
DIALOG_PARENT: Set this keyword to the widget ID of a widget over
which the message dialog should be positioned. When displayed,
the DIALOG_MENU dialog will be positioned over the specified
widget. Dialogs are often related to a non-dialog widget tree.
The ID of the widget in that tree to which the dialog is most
closely related should be specified.
If this keyword is not specified, the default placement of the
menu is the center of the screen (window manager dependent).
INDEX: Optionally return the index of the selected item instead of
the item's text. The index of the first menu_item is zero.
OUTPUTS:
result: String of selected menu_item, or integer index if INDEX keyword
is used, starting at index = 0
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Creates a modal widget.
RESTRICTIONS:
None known.
DEPENDENCIES:
NONE
EXAMPLES:
result = DIALOG_MENU (['Item 1', 'Item 2', 'Item3'], $
TITLE = 'Select an Item')
MODIFICATION HISTORY:
v1.04: RSM, May 1998
Added XPOSITION, YPOSITION keywords. Removed the UL, LL, UR, LR
keywords. Changed WIDTH keyword to XSIZE, and added YSIZE
keyword. These bring the widget in line with common IDL widget
size and position keywords.
THESE CHANGES WILL BREAK OLD CODE THAT USED ANY OF THESE KEYWORDS!
v1.03: RSM, Mar 1998
If not using /SCROLL, removed the sub-base for the menu buttons
so that they span the full width of the top level base.
v1.02: RSM, Mar 1998
Changed to return selected item's text, not index (index can
now be returned with the INDEX keyword).
v1.01: RSM, Mar 1998
Fixed error when used with a modal toplevel base.
v1.0: Written, Robert.Mallozzi@msfc.nasa.gov, November 1997.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/dialog_menu.pro)
NAME:
DIALOG_PLACE
PURPOSE:
Place a widget at a specified location.
CATEGORY:
WIDGETS
CALLING SEQUENCE:
DIALOG_PLACE, base_id [, /CENTER, XPOS = , YPOS = ]
INPUTS:
base_id: Id of the widget to place
KEYWORDS:
CENTER : Place the widget at the center of the current screen.
XPOS, YPOS : If specified, place the upper left corner of the
widget at XPOS, YPOS. Overrides keyword CENTER.
OUTPUTS:
NONE
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Maps the widget BASE_ID to the screen.
RESTRICTIONS:
When the widget base is created, it should use the keyword MAP = 0
so that when DIALOG_PLACE is called, the widget does not flash on the
screen. See example below.
EXAMPLES:
base = WIDGET_BASE (MAP = 0)
.
.
.
WIDGET_CONTROL, base, /REALIZE
DIALOG_PLACE, base, /CENTER
MODIFICATION HISTORY:
Written, 1999 January, Robert.Mallozzi@msfc.nasa.gov
This routine supercedes PLACE_MENU.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/dialog_place.pro)
NAME:
DIALOG_PLOT
PURPOSE:
A modal (blocking) dialog widget to display a plot.
The dialog must be dismissed with the 'Dismiss' button before
execution of the calling program can continue.
TYPE:
FUNCTION
CATEGORY:
WIDGETS
CALLING SEQUENCE:
result = DIALOG_PLOT (XDATA = xData, YDATA = yData)
INPUTS:
XDATA and YDATA (via keyword, see below)
KEYWORD PARAMETERS:
XDATA: Array of independent data.
YDATA: Array of dependent data.
EXECUTE: STRARR containing one or more IDL statements to execute.
The first command in the string must be a PLOT command.
The parameters xData, yData are available for use in the
EXECUTE string. See below for an example.
PS_OPTION: Add optional button to create a Postscript file
GIF_OPTION: Add optional button to create a gif image
WINTITLE: Window title [default = 'dialog_plot']
XSIZE: The width of the plot region (pixels) [default = 500]
YSIZE: The height of the plot region (pixels) [default = 400]
DIALOG_PARENT: Set this keyword to the widget ID of a widget over
which the message dialog should be positioned. When
displayed, the DIALOG_PLOT dialog will be positioned over
the specified widget. Dialogs are often related to a
non-dialog widget tree. The ID of the widget in that
tree to which the dialog is most closely related should
be specified.
All PLOT keywords also accepted.
OUTPUTS:
result: 1, or 0 for failure (missing parameters, or EXECUTE failed)
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Creates a modal widget
RESTRICTIONS:
NONE
DEPENDENCIES:
NONE
EXAMPLE:
xData = [0, 100]
yData = [-100, 100]
; Create a simple plot, with an option to print to Postscript file.
;
result = DIALOG_PLOT (XDATA = xData, YDATA = yData, $
winTitle = 'Demo', /PS_OPTION)
; Create a custom plot, with an option to print to gif file. Note
; that EXECUTE can utilize the XDATA, YDATA keywords.
;
result = DIALOG_PLOT (XDATA = xData, YDATA = yData, EXECUTE = [ $
'PLOT, /NODATA, XDATA, YDATA', $
'OPLOT, [50, 50], !Y.CRANGE', $
'OPLOT, [70, 70], !Y.CRANGE, LINESTYLE = 1' ], $
XTITLE = 'xTitle', YTITLE = 'yTitle', winTitle = 'Demo', /GIF_OPTION)
MODIFICATION HISTORY:
v0.1: written, Robert.Mallozzi@msfc.nasa.gov, March 1998.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/dialog_plot.pro)
NAME:
DIALOG_SLIDER
PURPOSE:
A modal (blocking) dialog widget to select a value from a slider.
The dialog must be dismissed, by activating the slider and pressing the
Return key, or by clicking on the 'Ok' or 'Cancel' button before
execution of the calling program can continue.
TYPE:
FUNCTION
CATEGORY:
WIDGETS
CALLING SEQUENCE:
result = DIALOG_SLIDER (range)
INPUTS:
range: Two element array giving the range for slider.
KEYWORD PARAMETERS:
PROMPT: Text prompt for the slider [default = 'Select Value']
FLOAT: Set this keyword to use a floating point slider (default is
an integer slider. Note that the floating point slider, which
uses CW_FSLIDER, does not update the slider label when the slider
is moved. It does, however, allow entering of the slider value
through keyboard input.
VERTICAL: Use a vertical slider [default = horizontal]
VALUE: Initial starting value [default = midpoint]
DIALOG_PARENT: Set this keyword to the widget ID of a widget over
which the message dialog should be positioned. When displayed,
the DIALOG_INPUT dialog will be positioned over the specified
widget. Dialogs are often related to a non-dialog widget tree.
The ID of the widget in that tree to which the dialog is most
closely related should be specified.
OUTPUTS:
result: Selected value of the slider
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Creates a modal widget
RESTRICTIONS:
NONE
DEPENDENCIES:
NONE
MODIFICATION HISTORY:
v1.02: RSM, May 1998 changed TEXT keyword to PROMPT.
NOT BACKWARD COMPATIBLE!
v1.01: RSM, Mar 1998, fixed error when used with a modal toplevel base.
v1.0: written, Robert.Mallozzi@msfc.nasa.gov, November 1997.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/dialog_slider.pro)
NAME:
DIALOG_TEXT
PURPOSE:
A modal (blocking) dialog widget to display a STRARR of text, or an
ASCII text file. The dialog must be dismissed 'Dismiss' button before
execution of the calling program can continue.
TYPE:
FUNCTION
CATEGORY:
WIDGETS
CALLING SEQUENCE:
result = DIALOG_TEXT(text)
INPUTS:
text: STRARR to be displayed on the widget.
KEYWORD PARAMETERS:
TITLE: Window title [default = 'dialog_text']
FILE: Set this keyword to an ASCII filename to display the file contents
in the widget. If this keyword is set, the 'text' parameter,
if supplied, is ignored.
XSIZE: The width of the dialog (characters) [default = 80]
YSIZE: The height of the dialog (characters) [default = 20]
DIALOG_PARENT: Set this keyword to the widget ID of a widget over
which the message dialog should be positioned. When displayed,
the DIALOG_TEXT dialog will be positioned over the specified
widget. Dialogs are often related to a non-dialog widget tree.
The ID of the widget in that tree to which the dialog is most
closely related should be specified.
OUTPUTS:
result: 1 (or 0 for failure, i.e., missing parameters)
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Creates a modal widget
RESTRICTIONS:
NONE
DEPENDENCIES:
NONE
MODIFICATION HISTORY:
v1.04: RSM, Dec 1998, added WRAP keyword to the call to WIDGET_TEXT()
v1.03: RSM, Mar 1998, converted obsolete !ERR_STRING to !ERROR_STATE.
v1.02: RSM, Mar 1998, added SAVE_OPTION keyword to allow saving to file.
v1.01: RSM, Mar 1998, fixed error when used with a modal toplevel base.
v1.0: written, Robert.Mallozzi@msfc.nasa.gov, October 1997.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/dialog_text.pro)
NAME:
file
PURPOSE:
An object for filename manipulation.
TYPE:
OBJECT
CALLING SEQUENCE:
file = OBJ_NEW ('file', filename)
INPUTS:
filename (OPTIONAL): Scalar filename, or STRARR of filenames
KEYWORDS:
GET: Select filenames interactively when the object is instantiated
COMMON BLOCKS:
NONE
SIDE EFFECTS:
None known
RESTRICTIONS:
None known
DEPENDENCIES:
NONE
METHODS:
set (PROCEDURE) - Set the filename
Inputs: Scalar STRING or STRARR containing the filename(s)
Outputs: NONE
Keywords: INTERACTIVE: Select filenames from a dialog box
DIALOG_PARENT: If INTERACTIVE is set, specifies the widget
ID over which the file dialog should be positioned.
get (FUNCTION) - Retrieve the filename properties
Inputs: NONE
Outputs: STRARR containing the requested property (default = full name)
Keywords:
NOT ALL KEYWORDS APPLY FOR ALL OS. For example, DEVICE
and VERSION do not apply under UNIX, and are returned as null.
BASENAME : Filename with leading path removed
PATH : Filename path
UNIX : path + basename is the full filename
VMS : device + path + basename is the full filename
WINDOWS : device + path + basename is the full filename
MACOS : device + path + basename is the full filename
DIRECTORY : Filename directory (same as PATH)
ROOT : Filename with leading path and file extension removed.
An extension consists of all characters after and
including the last "."
EXTENSION : Filename extension. An extension consists of all
characters after and including the last "."
DEVICE : Filename device
NODE : VMS only: The node name
VERSION : VMS only: Filename version. A version consists of
all characters after and including the last ";"
EXAMPLE:
; Create an instance of a file object
;
file = OBJ_NEW ('file', '/path/to/file/root.ext')
; Obtain some file properties
;
basename = file->get (/BASENAME)
path = file->get (/PATH)
root = file->get (/ROOT)
ext = file->get (/EXTENSION)
version = file->get (/VERSION) ; null for UNIX
; All done
;
OBJ_DESTROY, file
MODIFICATION HISTORY:
v1.0 : Written, 1999 January, Robert.Mallozzi@msfc.nasa.gov
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/file__define.pro)
NAME:
FINDFILES
PURPOSE:
Find all files matching a file filter. Replacement for the
IDL builtin routine FILEFILE, which does not handle recursive
search of directories correctly.
Currently implemented for UNIX and VMS systems only. For Windows
and MacOS, this routine is a wrapper for FINDFILE.
TYPE:
FUNCTION
CATEGORY:
FILES
CALLING SEQUENCE:
result = FINDFILES (fileFilter [, /RECURSE, ROOT = root, COUNT = count])
INPUTS:
fileFilter: Optional STRING denoting the file filter used in the search.
Any valid system command interpreter wildcards can be used.
If not supplied, one of the following is used:
UNIX: '*'
MACOS: '*'
VMS: '*.*'
WINDOWS: '*.*'
KEYWORD PARAMETERS:
RECUSE: Set this keyword to search recursively for matching files.
ROOT: Set this keyword to a STRING denoting the directory from which
to start the search. If not supplied, the current directory
is used.
COUNT: A named variable into which the number of files found is placed.
If no files are found, a value of 0 is returned.
OUTPUTS:
result: STRARR of matching files, or NULL string if no files are found.
COMMON BLOCKS:
NONE
SIDE EFFECTS:
None known
RESTRICTIONS:
None known
DEPENDENCIES:
NONE
MODIFICATION HISTORY:
Written, 1998 May, Robert.Mallozzi@msfc.nasa.gov
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/findfiles.pro)
Generic method to return instance data from any object. By default, object internal pointers are dereferenced and returned since returning a pointer into an object breaks encapsulation. Set the keyword RETURN_POINTERS to override this behavior. This might be desired, for example, to avoid copying large datasets on return. In this case, one should ensure that the data to which the pointer refers is not altered. Returns instance_data on success, or 0 on error. Based on a routine written by D. Fanning, with some improvements. Robert.Mallozzi@msfc.nasa.gov, 1998 May * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * UNCTION generic::get, instance_data, RETURN_POINTERS = return_pointers ; Ensure request is a string variable ;
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/generic__get.pro)
NAME:
GET_AXIS_RANGE
PURPOSE:
Returns range of a line that spans the full plotted range.
Handles both linear and log scales transparently.
CATEGORY:
Plotting
CALLING SEQUENCE:
RANGE = GET_AXIS_RANGE(AXIS)
INPUTS:
AXIS: single character string denoting the axis to span
('x' or 'y' or 'z')
KEYWORDS:
NONE
OUTPUTS:
RANGE: two element FLTARR of the range of the line
Returns -1 on error
COMMON BLOCKS:
NONE
SIDE EFFECTS:
NONE
RESTRICTIONS:
NONE
DEPENDENCIES:
NONE
EXAMPLE:
; Overplot a line at x0 that spans the plotted y-range
OPLOT, [1, 1] * x0, GET_AXIS_RANGE('y'), LINESTYLE = 1
MODIFICATION HISTORY:
v1.0: Written, 1997 September, Robert.Mallozzi@msfc.nasa.gov
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/get_axis_range.pro)
NAME:
HEX
PURPOSE:
Given an input number, returns a hexadecimal string
CALLING SEQUENCE:
result = HEX(value)
INPUTS:
value: LONG number. If any other type is supplied, it is converted to LONG
KEYWORDS:
NONE
OUTPUTS:
result: string representing the input number in hexidecimal
COMMON BLOCKS:
NONE
SIDE EFFECTS:
NONE
RESTRICTIONS:
No error checking for overflow
DEPENDENCIES:
NONE
EXAMPLE:
IDL> PRINT, HEX(500)
1F4
MODIFICATION HISTORY:
v1.0: Written, 1997 September, Robert.Mallozzi@msfc.nasa.gov
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/hex.pro)
NAME:
oDoc
PURPOSE:
Utility to parse object definition files and create HTML documentation
of the object methods. Similar to, but less sophisticated than
the java documentation facility 'javadoc'.
CATEGORY:
Objects: documentation
CALLING SEQUENCE:
oDoc [, objName]
INPUTS:
objName (optional): STRING or STRARR denoting object(s) to parse.
The array elements are the names of the objects; do not include
the "__define.pro" portion of the object file name.
If not supplied, objects are selected interactively from a list.
KEYWORDS:
VERBOSE : Print information on the objects as they are parsed.
BGCOLOR : HTML color string denoting the background color for
the HTML page (DEFAULT = '#C0C0C0')
TEXT : HTML text color (DEFAULT = '#000000')
LINK : HTML link color (DEFAULT = '#0000E8')
ALINK : HTML visited link color (DEFAULT = '#501888')
NOTE: Changing the background color from the default will not change
the background color of the bullet image that is used. This is
due to a limitation of IDL's WRITE_GIF routine, which does not
preserve transparency in GIFs. I suggest you use the default
colors.
COMMON BLOCKS:
NONE
SIDE EFFECTS:
None known.
RESTRICTIONS:
None known.
DEPENDENCIES:
dialog_list.pro
break_file.pro
write_image.pro (included)
MODIFICATION HISTORY:
v0.11 : RSM, 1998 June
IF test error when selecting multiple objects
Added keywords to set the colors of the HTML:
BGCOLOR
TEXT
LINK
ALINK
v0.1 : Written, 1998 May, Robert.Mallozzi@msfc.nasa.gov
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/odoc.pro)
NAME:
PLACE_MENU
PURPOSE:
Place a widget at a specified location. Note: placement is only a
hint to the windowing toolkit, and might be ignored by the window
manager.
CATEGORY:
WIDGETS
CALLING SEQUENCE:
PLACE_MENU, BASE_ID [, /CENTER, XPOS = , YPOS = ]
INPUTS:
BASE_ID: Id of the widget to place.
KEYWORD PARAMETERS:
CENTER: Place the widget at the center of the current screen.
XPOS, YPOS: If specified, place the upper left corner of the
widget at XPOS, YPOS. Overrides keyword CENTER.
OUTPUTS:
NONE
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Maps the widget BASE_ID to the screen.
RESTRICTIONS:
When the widget base is created, it should use the keyword MAP = 0
so that when PLACE_MENU is called, the widget does not flash on the
screen.
PROCEDURE:
Procedure call.
EXAMPLES:
BASE = WIDGET_BASE(MAP = 0)
.
.
.
WIDGET_CONTROL, BASE, /REALIZE
PLACE_MENU, BASE, /CENTER
MODIFICATION HISTORY:
RSM: Changed to use the GET_SCREEN_SIZE function.
Written, Robert.Mallozzi@msfc.nasa.gov, Oct 1995.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/place_menu.pro)
NAME:
POINTER_HELP
PURPOSE:
Prints help on a dereferenced pointer. Checks for pointer validity.
TYPE:
PROCEDURE
CATEGORY:
POINTERS
CALLING SEQUENCE:
POINTER_HELP, *pointer
INPUTS:
pointer: An IDL pointer
KEYWORD PARAMETERS:
NONE
OUTPUTS:
IDL output of command "HELP, *pointer" is printed to stdout.
COMMON BLOCKS:
NONE
SIDE EFFECTS:
NONE
RESTRICTIONS:
NONE
DEPENDENCIES:
NONE
MODIFICATION HISTORY:
Written, Robert.Mallozzi@msfc.nasa.gov, 1998 March.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/pointer_help.pro)
NAME:
queue
PURPOSE:
An object that implements a simple queue algorithm. Data are stored
in first-in-first-out (FIFO) order. Any IDL datatype can be added
to the queue, and types can be mixed within a single instance of
the queue.
TYPE:
OBJECT
CATEGORY:
Data structures
CALLING SEQUENCE:
myQueue = OBJ_NEW ('queue')
INPUTS:
NONE
KEYWORDS:
QUIET: Do not print a warning on attempting to process() an empty queue.
COMMON BLOCKS:
NONE
SIDE EFFECTS:
None known.
RESTRICTIONS:
None known.
DEPENDENCIES:
NONE
METHODS:
add (PROCEDURE) - Add data to the queue
Inputs: data = any datatype to add to the queue
Outputs: NONE
Keywords: NONE
process (FUNCTION) - Retrieve data from the queue
Inputs: NONE
Outputs: Oldest data item in the queue, or !VALUES.F_NAN on
queue underflow.
Keywords: NONE
size (FUNCTION) - Retrieve the current size of the queue
Inputs: NONE
Outputs: Current size of the queue
Keywords: NONE
flush (PROCEDURE) - Empty the queue
Inputs: NONE
Outputs: NONE
Keywords: NONE
MODIFICATION HISTORY:
v1.0: Written, 1998 May, Robert.Mallozzi@msfc.nasa.gov
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/queue__define.pro)
NAME:
RINGBELL
PURPOSE:
Ring the system bell.
TYPE:
PROCEDURE
CATEGORY:
UTILITIES
CALLING SEQUENCE:
RINGBELL [, numRings]
INPUTS:
numRings (OPTIONAL): Integer number of times to ring bell.
KEYWORD PARAMETERS:
NONE
OUTPUTS:
NONE
COMMON BLOCKS:
NONE
SIDE EFFECTS:
None known.
RESTRICTIONS:
None known.
DEPENDENCIES:
NONE
MODIFICATION HISTORY:
Written, Robert.Mallozzi@msfc.nasa.gov, 1998 July
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/ringbell.pro)
NAME:
SEARCH_ARRAY
PURPOSE:
Searches a one-dimensional array to find the first occurrence
of a value closest to a scalar value
TYPE:
FUNCTION
CATEGORY:
Arrays
CALLING SEQUENCE:
RESULT = SEARCH_ARRAY(INARR, TARGET)
INPUTS:
INARR = the one-dimensional array to be searched.
TARGET = the value to find in INARR (scalar or vector).
INPUT PARAMETERS:
NONE
KEYWORD PARAMETERS:
NONE
OUTPUTS:
RESULT = index of INARR where INARR is closest to TARGET.
If TARGET is a vector, RESULT will be a vector of indices.
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Finds only first occurance of TARGET. If INARR is, for example, a
parabola and one desires to search beyond the maximum, pass in a
temporary array that is only the appropriate portion of INARR.
RESTRICTIONS:
NONE
DEPENDENCIES:
NONE
MODIFICATION HISTORY:
Written, Robert.Mallozzi@msfc.nasa.gov, October, 1994.
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/search_array.pro)
NAME:
silo
PURPOSE:
An object that implements a random access data storage mechanism.
Any IDL datatype can be added, and types can be mixed within a
single instance of the silo.
TYPE:
OBJECT
CATEGORY:
Data structures
CALLING SEQUENCE:
mySilo = OBJ_NEW ('silo')
INPUTS:
NONE
KEYWORDS:
NONE
COMMON BLOCKS:
NONE
SIDE EFFECTS:
None known
RESTRICTIONS:
None known
DEPENDENCIES:
NONE
METHODS:
set (PROCEDURE) - Add data to the silo
Inputs: KEY : STRING name denoting the data
DATA : data to add to the silo (can be any IDL datatype)
Outputs: NONE
Keywords: NONE
get (FUNCTION) - Retrieve data from the silo
Inputs: KEY : STRING name denoting the data
Outputs: DATA corresponding to the specified KEY
Keywords: NUMBER : Set this keyword to return the number
of data elements currently in the silo. No input argument
is required in this case.
NAMES : Set this keyword to return a STRARR that holds the
names of the data elements currently in the silo. No
input argument is required in this case.
ERROR : Set to a named variable to return the status of
the GET. If data could not be extracted, ERROR is set
to 1, else ERROR = 0.
print (PROCEDURE) - Print all keys currently stored
Inputs: NONE
Outputs: NONE
Keywords: NONE
delete (PROCEDURE) - Delete data from the silo
Inputs: KEY : STRING name denoting the data
Outputs: NONE
Keywords: NONE
EXAMPLE:
; Create an instance of a data silo
;
silo = OBJ_NEW ('silo')
; Add some data to the silo. The data names are not case-sensitive.
;
silo->set, 'intData', 1
silo->set, 'floatData', 1.0
silo->set, 'structData', { DATA, x: 0, y: PTR_NEW (), z: OBJ_NEW () }
; Print the current entries
;
silo->print
; Retrieve some data from the silo
;
myInt = silo->get ('intData')
myStruct = silo->get ('structData', ERROR = error)
IF (error) THEN $
PRINT, 'Could not find data in silo: structData'
; Delete an entry from the silo
;
silo->delete, 'floatData'
; All done
;
OBJ_DESTROY, silo
MODIFICATION HISTORY:
1.02: RSM, fixed NULL pointer reference in cleanup and print methods for
the case where no data were in the silo (thanks to R. Dejus).
Added ERROR keyword to the GET method (see EXAMPLE).
1.01: RSM, added NUMBER keyword to get() method to return number
of data elements currently in the silo.
1.0 : Written, 1998 July, Robert.Mallozzi@msfc.nasa.gov
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/silo__define.pro)
NAME:
stack
PURPOSE:
An object that implements a simple stack algorithm. Data are stored
in last-in-first-out (LIFO) order. Any IDL datatype can be pushed
onto the stack, and types can be mixed within a single instance of
the stack.
TYPE:
OBJECT
CATEGORY:
Data structures
CALLING SEQUENCE:
myStack = OBJ_NEW ('stack')
INPUTS:
NONE
KEYWORDS:
QUIET: Do not print a warning on attempting to pop() an empty stack.
COMMON BLOCKS:
NONE
SIDE EFFECTS:
None known.
RESTRICTIONS:
None known.
DEPENDENCIES:
NONE
METHODS:
push (PROCEDURE) - Push data onto the stack
Inputs: data = any datatype to push onto the stack
Outputs: NONE
Keywords: NONE
pop (FUNCTION) - Pop data from the stack
Inputs: NONE
Outputs: Current data item on the top of the stack, or !VALUES.F_NAN
on stack underflow.
Keywords: NONE
size (FUNCTION) - Retrieve the current size of the stack
Inputs: NONE
Outputs: Current size of the stack
Keywords: NONE
flush (PROCEDURE) - Empty the stack
Inputs: NONE
Outputs: NONE
Keywords: NONE
MODIFICATION HISTORY:
v1.0: Written, 1998 May, Robert.Mallozzi@msfc.nasa.gov
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/stack__define.pro)
NAME:
SWITCH_COLORS
PURPOSE:
Inverts the background and foreground colors
CATEGORY:
Plotting
CALLING SEQUENCE:
SWITCH_COLORS
INPUTS:
NONE
INPUT PARAMETERS:
NONE
KEYWORD PARAMETERS:
NONE
OUTPUTS:
NONE
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Switches foreground and background plotting colors
RESTRICTIONS:
NONE
DEPENDENCIES:
NONE
MODIFICATION HISTORY:
Written: mallozzi@gibson.msfc.nasa.gov, Oct, 1996
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/switch_colors.pro)
NAME:
TABLE
PURPOSE:
Create a table widget object
CATEGORY:
Object Widgets
CALLING SEQUENCE:
myTableObj = OBJ_NEW ('table', VALUE = tableStructure)
NOTE: The object is automatically destroyed when the table
widget is dismissed.
REQUIRED INPUTS:
tableStructure: Array of structures of the table data, set
via the VALUE keyword
OPTIONAL INPUTS:
NONE
KEYWORD PARAMETERS:
VALUE: structure containing user data
TITLE: STRING denoting the title of the table widget
Most other IDL WIDGET_TABLE keywords are valid (see Restrictions, below)
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Creates a new widget
RESTRICTIONS:
IDL v5.0 or later.
If you use the following WIDGET_TABLE keywords, you will have to
write the event handler for the table events:
ALL_EVENTS
EVENT_PRO
EVENT_FUNC
FUNC_GET_VALUE
KBRD_FOCUS_EVENTS
PRO_SET_VALUE
TRACKING
If the EDITABLE keyword is set, editting of cells is allowed, but
a handler must be supplied to execute a routine when an edit event
is generated.
EXAMPLE:
; Create a table object
;
aTable = OBJ_NEW ('table', VALUE = myData, TITLE = 'aTable', $
ROW_LABELS = '', COLUMN_LABELS = TAG_NAMES (myData))
MODIFICATION HISTORY:
Written, Robert.Mallozzi@msfc.nasa.gov, 1998 March, v0.1
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/table__define.pro)
NAME:
timer
PURPOSE:
An object that implements a simple timer. The timer can be arbitrarily
started, stopped, and reset, or queried for the current elapsed time,
or the timer active state.
TYPE:
OBJECT
CATEGORY:
Data structures
CALLING SEQUENCE:
myTimer = OBJ_NEW ('timer')
INPUTS:
NONE
KEYWORDS:
NONE
COMMON BLOCKS:
NONE
SIDE EFFECTS:
None known.
RESTRICTIONS:
None known.
DEPENDENCIES:
NONE
METHODS:
start (PROCEDURE) - Start the timer. If the timer is already active,
calling START again results in an implicit timer reset.
Inputs: NONE
Outputs: NONE
Keywords: NONE
halt (PROCEDURE) - Stop the timer (using a method called "stop"
generates an IDL internal error - v5.1).
Inputs: NONE
Outputs: NONE
Keywords: NONE
reset (PROCEDURE) - Reset the timer
Inputs: NONE
Outputs: NONE
Keywords: NONE
active (FUNCTION) - Return active state of the timer
Inputs: NONE
Outputs: 1 if the timer is active, else 0
Keywords: NONE
elapsed (FUNCTION) - Return, as a double precision floating point value,
the current elapsed time in seconds from a previous call to the
either the START or RESET methods (i.e., the elapsed time is not
cumulative across multiple calls to START (or RESET) and HALT).
Inputs: NONE
Outputs: NONE
Keywords: NONE
MODIFICATION HISTORY:
v1.0: Written, 1998 June, Robert.Mallozzi@msfc.nasa.gov
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/timer__define.pro)
NAME:
TRACK_MOUSE
VERSION:
0.1
PURPOSE:
Tracks the mouse cursor in a DRAW_WIDGET, and returns coordinates
of a selected region
TYPE:
Function
CATEGORY:
Widgets
CALLING SEQUENCE:
HAVE_SELECTION = TRACK_MOUSE(drawWidgetID, REGION, COORDINATES)
REQUIRED INPUTS:
drawWidgetID: Widget ID of a valid WIDGET_DRAW()
OPTIONAL INPUTS:
NONE
OUTPUTS:
HAVE_SELECTION: INTEGER specifying if selection was completed: 0 if
selection was aborted, 1 if it was completed
REGION: INTEGER specifying the plot region in which the mouse was
clicked to exit TRACK_MOUSE()
4
----------------
| |
| |
1 | 0 | 2
| |
----------------
3
COORDINATES: FLTARR(2, 2) = coordinates of the selection
COORDINATES[0, *] = [X0, X1]
COORDINATES[1, *] = [Y0, Y1]
If a selection is aborted midway through (i.e., only one mouse
click), COORDINATES is returned as scalar zero.
KEYWORD PARAMETERS:
GET_BOX: Select a box (rubberbanding). This is the default.
GET_XRANGE: Select an interval from the x-axis
GET_YRANGE: Select an interval from the y-axis
Only one GET keyword can be specified, else an error
is generated.
LEFT_TEXT: Text displayed when mouse enters left margin (D = 'EXIT')
RIGHT_TEXT: Right margin text (D = 'RESET')
TOP_TEXT: Top margin text (D = '')
BOTTOM_TEXT: Bottom margin text (D = 'Numerical Entry')
NOTE: The default text values expect you to perform
certain actions when TRACK_MOUSE() exits in order to
make sense. For example, when clicking in the right margin
(RESET), you might reset the plot axes, and replot. For
the left margin (EXIT), you might replot the zoomed region.
NOWAIT: By default, TRACK_MOUSE() waits for a margin click before
exiting. Set NOWAIT to return immediately after a selection
is completed (i.e., after the second mouse click). REGION
is returned as 0 in this case. Use this to make multiple
selections by calling TRACK_MOUSE() again.
XTOLERANCE: Allow selections slightly outside the left and right
axes, in normalized units (D = 0.0)
YTOLERANCE: Allow selections slightly outside the top and bottom
axes, in normalized units (D = 0.0)
WARNING: Large tolerance values (i.e., more than about
0.05) may prevent you from accessing the plot margins.
COLOR: Color index of the plotted selections.
_EXTRA: Any valid OPLOT keywords.
COMMON BLOCKS:
NONE
SIDE EFFECTS:
NONE
RESTRICTIONS:
IDL v5.0 or later
You must trap WIDGET_DRAW events in your event handler, since
TRACK_MOUSE() enables BUTTON and MOTION events in the DRAW widget.
EXAMPLE:
See TRACK_MOUSE_EXAMPLE.PRO
MODIFICATION HISTORY:
Written, Robert.Mallozzi@msfc.nasa.gov, March, 1998.
Idea based on TRACK() for direct graphics windows
written by Rob.Preece@msfc.nasa.gov
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/track_mouse.pro)
Examples of TRACK_MOUSE usage. RSM, 1998 March. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * This is the event handler RO TRACK_MOUSE_EVENT, EVENT
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/track_mouse_example.pro)
NAME:
widget_logger
PURPOSE:
An object that implements a logging widget.
TYPE:
OBJECT
CATEGORY:
Widgets
CALLING SEQUENCE:
myLogger = OBJ_NEW ('widget_logger')
INPUTS:
NONE
KEYWORDS:
XSIZE : xsize of the log text area (characters, DEFAULT = 60)
YSIZE : ysize of the log text area (characters, DEFAUTL = 10)
MAP : 0 to prohibit mapping of the widget when the logger object is
instantiated, or 1 to map the widget (DEFAULT = 1)
TITLE : Logger widget window title (DEFAULT = 'Logger')
COMMON BLOCKS:
NONE
SIDE EFFECTS:
None known.
RESTRICTIONS:
None known.
DEPENDENCIES:
NONE
METHODS:
append (PROCEDURE) - Append text to the logger widget
Inputs: text: STRING or STRARR of text to append to the logger
Outputs: NONE
Keywords: NONE
clear (PROCEDURE) - Clear the text area of the logger widget
Inputs: NONE
Outputs: NONE
Keywords: NONE
getText (FUNCTION) - Return the current text displayed in the logger
Inputs: NONE
Outputs: STRARR of text currently displayed
Keywords: NONE
hide (PROCEDURE) - Hide (MAP = 0) the widget
Inputs: NONE
Outputs: NONE
Keywords: NONE
setClearButton (PROCEDURE) - Change the label of the "Clear" button
Inputs: STRING specifying new label for the button
Outputs: NONE
Keywords: NONE
setHideButton (PROCEDURE) - Change the label of the "Hide" button
Inputs: STRING specifying new label for the button
Outputs: NONE
Keywords: NONE
setLineNumber (PROCEDURE) - Set the zero-based line number of the
line to be positioned on the topmost visible line in the text
widget's viewport. No horizontal scrolling is performed. Note
that this is a line number, not a character offset.
Inputs: INTEGER specifying the topmost visible line number
Outputs: NONE
Keywords: NONE
setSize (PROCEDURE) - Set the XSIZE and/or YSIZE of the log text area
Inputs: NONE
Outputs: NONE
Keywords: XSIZE : xsize of the log text area (characters)
YSIZE : ysize of the log text area (characters)
show (PROCEDURE) - Show (MAP = 1) the widget
Inputs: NONE
Outputs: NONE
Keywords: NONE
getWidgetIDs (FUNCTION) - Return a stucture containing the widget ids
of the logger components. The following structure tags are returned:
top : Top level base ID
text : Text area widget ID
clear : Clear button widget ID
hide : Hide button widget ID
DO NOT CHANGE THE UVALUES OF ANY OF THE LOGGER WIDGET COMPONENTS, AS
THEY ARE USED INTERNALLY BY THE OBJECT. This method is not
recommended for use; manipulating the logger widget from outside
the object can compromise the internal object state.
Inputs: NONE
Outputs: STRUCTURE containing the logger widget component IDs
Keywords: NONE
EXAMPLE:
; Create a logger widget
;
logger = OBJ_NEW ('widget_logger', MAP = 0, TITLE = 'myLogger')
; Change the label of the 'Clear' button to 'Clear Log Text'
;
logger->setClearButton, 'Clear Log Text'
; Show the widget
;
logger->show
; Add some text
;
logger->append, ['A line of text.', 'Another line of text.']
; Clear the logger programatically
;
logger->clear
; Add a lot of text, then make the 300th line visible
;
logger->append, 'Line number ' + STRTRIM (SINDGEN (500) + 1, 2)
logger->setLineNumber, 300
; All done
;
OBJ_DESTROY, logger
MODIFICATION HISTORY:
v1.0: Written, 1998 June, Robert.Mallozzi@msfc.nasa.gov
(See /host/bluemoon/usr2/idllib/contrib/mallozzi/widget_logger__define.pro)