|
MERIS IDL General Purpose Tools |
Last modified: Wed Dec 05 10:45:18 2001.
NAME:
ARRDELETE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Remove a portion of an existing array.
CALLING SEQUENCE:
NEWARR = ARRDELETE(INIT, [AT=POSITION,] [LENGTH=NELEM])
DESCRIPTION:
ARRDELETE will remove or excise a portion of an existing array,
INIT, and return it as NEWARR. The returned array will never be
larger than the initial array.
By using the keywords AT and LENGTH, which describe the position
and number of elements to be excised respectively, any segment of
interest can be removed. By default the first element is removed.
INPUTS:
INIT - the initial array, which will have a portion deleted. Any
data type, including structures, is allowed. Regardless of
the dimensions of INIT, it is treated as a one-dimensional
array. If OVERWRITE is not set, then INIT itself is
unmodified.
KEYWORDS:
AT - a long integer indicating the position of the sub-array to be
deleted. If AT is non-negative, then the deleted portion
will be NEWARR[AT:AT+LENGTH-1]. If AT is negative, then it
represents an index counting from then *end* of INIT,
starting at -1L.
Default: 0L (deletion begins with first element).
LENGTH - a long integer indicating the number of elements to be
removed.
OVERWRITE - if set, then INIT will be overwritten in the process of
generating the new array. Upon return, INIT will be
undefined.
COUNT - upon return, the number of elements in the resulting array.
If all of INIT would have been deleted, then -1L is
returned and COUNT is set to zero.
EMPTY1 - if set, then INIT is assumed to be empty (i.e., to have
zero elements). The actual value passed as INIT is
ignored.
RETURNS:
The new array, which is always one-dimensional. If COUNT is zero,
then the scalar -1L is returned.
SEE ALSO:
STORE_ARRAY in IDL Astronomy Library
MODIFICATION HISTORY:
Written, CM, 02 Mar 2000
Added OVERWRITE and EMPTY1 keyword, CM 04 Mar 2000
$Id: arrdelete.pro,v 1.2 2001/06/28 09:10:10 chr Exp $
(See $IDL_LOCAL\Utilities\arrdelete.pro)
NAME:
ARRINSERT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Insert one array into another
CALLING SEQUENCE:
NEWARR = ARRINSERT(INIT, INSERT, [AT=POSITION] )
DESCRIPTION:
ARRINSERT inserts the contents of one array (INSERT) into
another (INIT), and returns the new array (NEWARR).
ARRINSERT will handle empty lists, which are represented as
undefined variables. If both input arrays are empty, then the
scalar -1L is returned, and the keyword COUNT is set to 0L.
INPUTS:
INIT - the initial array, into which INSERT will be inserted. Any
data type, including structures, is allowed. Regardless of
the dimensions of INIT, it is treated as a one-dimensional
array. If OVERWRITE is not set, then INIT itself is
unmodified.
INSERT - the array to be inserted into INIT, which must be of the
same or similar type to INIT. If INSERT is empty, then
INIT is returned unchanged. Regardless of the dimensions
of INSERT, it is treated as a one-dimensional array.
KEYWORDS:
AT - a long integer indicating the position of the newly inserted
sub-array. If AT is non-negative, then INSERT will appear
at NEWARR[AT]. If AT is negative, then INSERT will appear
at NEWARR[AT + (N+1)] where N is the number of elements in
INIT.
Default: 0L (INSERT appears at beginning of INIT)
OVERWRITE - if set, then the initial array INIT will be
overwritten by the new array. Upon exit INIT becomes
undefined.
COUNT - upon return, the number of elements in the resulting
array.
EMPTY1, EMPTY2 - if set, then INIT (for EMPTY1) or INSERT (for
EMPTY2) are assumed to be empty (i.e., to have
zero elements). The actual values passed as INIT
or INSERT are then ignored.
RETURNS:
The new array, which is always one-dimensional. If COUNT is zero,
then the scalar -1L is returned.
SEE ALSO:
ARRDELETE, STORE_ARRAY in IDL Astronomy Library
MODIFICATION HISTORY:
Written, CM, 02 Mar 2000
Added OVERWRITE and EMPTY keywords, CM, 04 Mar 2000
Improved internal docs, and AT keyword docs, CM, 28 Sep 2000
$Id: arrinsert.pro,v 1.2 2001/06/28 09:10:10 chr Exp $
(See $IDL_LOCAL\Utilities\arrinsert.pro)
NAME:
CENTERTLB
PURPOSE:
Positions a widget program on the display at an arbitrary location.
By default the widget is centered on the display.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Utilities
CALLING SEQUENCE:
CenterTLB, tlb, [x, y, /NOCENTER]
REQUIRED INPUTS:
tlb: The top-level base identifier of the widget program.
OPTIONAL INPUTS:
x: Set this equal to a normalized position for the center
of the widget as measured from the left-hand side of the screen.
The default value is 0.5 (the center) Setting this equal to 1.0
places the widget at the far right-hand side of the screen.
y: Set this equal to a normalized position for the center
of the widget as measured from the bottom of the screen.
The default value is 0.5 (the center) Setting this equal to 1.0
places the widget at the top of the screen.
KEYWORDS:
NOCENTER: By default, the center of the widget is positioned at the
location specified by the x and y parameters. If NOCENTER is set
to a non-zero value, then the upper left corner of the widget
is postioned at the specifed location.
PROCEDURE:
The program should be called after all the widgets have
been created, but just before the widget hierarchy is realized.
It uses the top-level base geometry along with the display size
to calculate offsets for the top-level base that will center the
top-level base on the display.
COMMENT:
Regardless of the values set for x, y and NOCENTER, the widget
is not permitted to run off the display.
MODIFICATION HISTORY:
Written by: Dick Jackson, 12 Dec 98.
Modified to use device-independent Get_Screen_Size
function. 31 Jan 2000. DWF.
Added x, y, NOCENTER and run-off protection. 26 Jan 2001. BT.
###########################################################################
LICENSE
This software is OSI Certified Open Source Software.
OSI Certified is a certification mark of the Open Source Initiative.
Copyright  1998-2000 Fanning Software Consulting
This software is provided "as-is", without any express or
implied warranty. In no event will the authors be held liable
for any damages arising from the use of this software.
Permission is granted to anyone to use this software for any
purpose, including commercial applications, and to alter it and
redistribute it freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must
not claim you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation
would be appreciated, but is not required.
2. Altered source versions must be plainly marked as such, and must
not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
For more information on Open Source Software, visit the Open Source
web site: http://www.opensource.org.
###########################################################################
(See $IDL_LOCAL\Utilities\centertlb.pro)
NAME:
CMAPPLY
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Applies a function to specified dimensions of an array
MAJOR TOPICS:
Arrays
CALLING SEQUENCE:
XX = CMAPPLY(OP, ARRAY, DIMS, [/DOUBLE], [TYPE=TYPE])
DESCRIPTION:
CMAPPLY will apply one of a few select functions to specified
dimensions of an array. Unlike some IDL functions, you *do* have
a choice of which dimensions that are to be "collapsed" by this
function. Iterative loops are avoided where possible, for
performance reasons.
The possible functions are: (and number of loop iterations:)
+ - Performs a sum (as in TOTAL) number of collapsed dimensions
AND - Finds LOGICAL "AND" (not bitwise) same
OR - Finds LOGICAL "OR" (not bitwise) same
* - Performs a product LOG_2[no. of collapsed elts.]
MIN - Finds the minimum value number of output elements
MAX - Finds the maximum value same
INPUTS:
OP - The operation to perform, as a string. May be upper or lower
case.
ARRAY - An array of values to be operated on. Must not be of type
STRING (7) or STRUCTURE (8).
OPTIONAL INPUTS:
DIMS - An array of dimensions that are to be "collapsed", where
the the first dimension starts with 1 (ie, same convention
as IDL function TOTAL). Whereas TOTAL only allows one
dimension to be added, you can specify multiple dimensions
to CMAPPLY. Order does not matter, since all operations
are associative and transitive. NOTE: the dimensions refer
to the *input* array, not the output array. IDL allows a
maximum of 8 dimensions.
DEFAULT: 1 (ie, first dimension)
KEYWORDS:
DOUBLE - Set this if you wish the internal computations to be done
in double precision if necessary. If ARRAY is double
precision (real or complex) then DOUBLE=1 is implied.
DEFAULT: not set
TYPE - Set this to the IDL code of the desired output type (refer
to documentation of SIZE()). Internal results will be
rounded to the nearest integer if the output type is an
integer type.
DEFAULT: same is input type
RETURN VALUE:
An array of the required TYPE, whose elements are the result of
the requested operation. Depending on the operation and number of
elements in the input array, the result may be vulnerable to
overflow or underflow.
EXAMPLES:
Shows how CMAPPLY can be used to total the second dimension of the
array called IN. This is equivalent to OUT = TOTAL(IN, 2)
IDL> IN = INDGEN(5,5)
IDL> OUT = CMAPPLY('+', IN, [2])
IDL> HELP, OUT
OUT INT = Array[5]
Second example. Input is assumed to be an 5x100 array of 1's and
0's indicating the status of 5 detectors at 100 points in time.
The desired output is an array of 100 values, indicating whether
all 5 detectors are on (=1) at one time. Use the logical AND
operation.
IDL> IN = detector_status ; 5x100 array
IDL> OUT = CMAPPLY('AND', IN, [1]) ; collapses 1st dimension
IDL> HELP, OUT
OUT BYTE = Array[100]
(note that MIN could also have been used in this particular case,
although there would have been more loop iterations).
Third example. Shows sum over first and third dimensions in an
array with dimensions 4x4x4:
IDL> IN = INDGEN(4,4,4)
IDL> OUT = CMAPPLY('+', IN, [1,3])
IDL> PRINT, OUT
408 472 536 600
MODIFICATION HISTORY:
Mar 1998, Written, CM
Changed usage message to not bomb, 24 Mar 2000, CM
Signficant rewrite for *, MIN and MAX (inspired by Todd Clements
); FOR loop indices are now type
LONG; copying terms are liberalized, CM, 22, Aug 2000
$Id: cmapply.pro,v 1.2 2001/06/28 09:10:11 chr Exp $
(See $IDL_LOCAL\Utilities\cmapply.pro)
NAME:
CMPRODUCT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
CMPRODUCT() is the multiplicative equivalent of TOTAL().
CALLING SEQUENCE:
Result = CMPRODUCT(ARRAY)
DESCRIPTION:
Calculates the product of all the elements of an array. Vector
multiplication in groups of powers of two make this operation
faster than a simple FOR loop. The number of actual
multiplications is still N_ELEMENTS(ARRAY). Double precision
should be used for the highest accuracy when multiplying many
numbers.
INPUTS:
ARRAY - Array of elements to multiply together. For instance,
ARRAY could contain the dimensions of another array--then
CMPRODUCT(ARRAY) would be the total number of elements of
that other array.
RETURNS:
The result of the function is the total product of all the elements
of ARRAY.
EXAMPLE:
SEE ALSO:
TOTAL, PRODUCT (from Astronomy User's Library)
MODIFICATION HISTORY:
Written, CM, 28 Mar 2000
(based on outline of PRODUCT by William Thompson)
$Id: cmproduct.pro,v 1.2 2001/06/28 09:10:11 chr Exp $
(See $IDL_LOCAL\Utilities\cmproduct.pro)
NAME:
CMREPLICATE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Replicates an array or scalar into a larger array, as REPLICATE does.
CALLING SEQUENCE:
ARRAY = CMREPLICATE(VALUE, DIMS)
DESCRIPTION:
The CMREPLICATE function constructs an array, which is filled with
the specified VALUE template. CMREPLICATE is very similar to the
built-in IDL function REPLICATE. However there are two
differences:
* the VALUE can be either scalar or an ARRAY.
* the dimensions are specified as a single vector rather than
individual function arguments.
For example, if VALUE is a 2x2 array, and DIMS is [3,4], then the
resulting array will be 2x2x3x4.
INPUTS:
VALUE - a scalar or array template of any type, to be replicated.
NOTE: These two calls do not produce the same result:
ARRAY = CMREPLICATE( 1, DIMS)
ARRAY = CMREPLICATE([1], DIMS)
In the first case the output dimensions will be DIMS and
in the second case the output dimensions will be 1xDIMS
(except for structures). That is, a vector of length 1 is
considered to be different from a scalar.
DIMS - Dimensions of output array (which are combined with the
dimensions of the input VALUE template). If DIMS is not
specified then VALUE is returned unchanged.
RETURNS:
The resulting replicated array.
EXAMPLE:
x = [0,1,2]
help, cmreplicate(x, [2,2])
INT = Array[3, 2, 2]
Explanation: The 3-vector x is replicated 2x2 times.
x = 5L
help, cmreplicate(x, [2,2])
LONG = Array[2, 2]
Explanation: The scalar x is replicated 2x2 times.
SEE ALSO:
REPLICATE
MODIFICATION HISTORY:
Written, CM, 11 Feb 2000
Fixed case when ARRAY is array of structs, CM, 23 Feb 2000
Apparently IDL 5.3 can't return from execute(). Fixed, CM, 24 Feb
2000
Corrected small typos in documentation, CM, 22 Jun 2000
(See $IDL_LOCAL\Utilities\cmreplicate.pro)
NAME:
CMSET_OP
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Performs an AND, OR, or XOR operation between two sets
CALLING SEQUENCE:
SET = CMSET_OP(A, OP, B)
DESCRIPTION:
SET_OP performs three common operations between two sets. The
three supported functions of OP are:
OP Meaning
'AND' - to find the intersection of A and B;
'OR' - to find the union of A and B;
'XOR' - to find the those elements who are members of A or B
but not both;
Sets as defined here are one dimensional arrays composed of
numeric or string types. Comparisons of equality between elements
are done using the IDL EQ operator.
The complements of either set can be taken as well, by using the
NOT1 and NOT2 keywords. For example, it may be desireable to find
the elements in A but not B, or B but not A (they are different!).
The following IDL expressions achieve each of those effects:
SET = CMSET_OP(A, 'AND', /NOT2, B) ; A but not B
SET = CMSET_OP(/NOT1, A, 'AND', B) ; B but not A
Note the distinction between NOT1 and NOT2. NOT1 refers to the
first set (A) and NOT2 refers to the second (B). Their ordered
placement in the calling sequence is entirely optional, but the
above ordering makes the logical meaning explicit.
NOT1 and NOT2 can only be set for the 'AND' operator, and never
simultaneously. This is because the results of an operation with
'OR' or 'XOR' and any combination of NOTs -- or with 'AND' and
both NOTs -- formally cannot produce a defined result.
The implementation depends on the type of operands. For integer
types, a fast technique using HISTOGRAM is used. However, this
algorithm becomes inefficient when the dynamic range in the data
is large. For those cases, and for other data types, a technique
based on SORT() is used. Thus the compute time should scale
roughly as (A+B)*ALOG(A+B) or better, rather than (A*B) for the
brute force approach. For large arrays this is a significant
benefit.
INPUTS:
A, B - the two sets to be operated on. A one dimensional array of
either numeric or string type. A and B must be of the same
type. Empty sets are permitted, and are either represented
as an undefined variable, or by setting EMPTY1 or EMPTY2.
OP - a string, the operation to be performed. Must be one of
'AND', 'OR' or 'XOR' (lower or mixed case is permitted).
Other operations will cause an error message to be produced.
KEYWORDS:
NOT1, NOT2 - if set and OP is 'AND', then the complement of A (for
NOT1) or B (for NOT2) will be used in the operation.
NOT1 and NOT2 cannot be set simultaneously.
EMPTY1, EMPTY2 - if set, then A (for EMPTY1) or B (for EMPTY2) are
assumed to be the empty set. The actual values
passed as A or B are then ignored.
INDEX - if set, then return a list of indices instead of the array
values themselves. The "slower" set operations are always
performed in this case.
The indices refer to the *combined* array [A,B]. To
clarify, in the following call: I = CMSET_OP(..., /INDEX);
returned values from 0 to NA-1 refer to A[I], and values
from NA to NA+NB-1 refer to B[I-NA].
COUNT - upon return, the number of elements in the result set.
This is only important when the result set is the empty
set, in which case COUNT is set to zero.
RETURNS:
The resulting set as a one-dimensional array. The set may be
represented by either an array of data values (default), or an
array of indices (if INDEX is set). Duplicate elements, if any,
are removed, and element order may not be preserved.
The empty set is represented as a return value of -1L, and COUNT
is set to zero. Note that the only way to recognize the empty set
is to examine COUNT.
SEE ALSO:
SET_UTILS.PRO by RSI
MODIFICATION HISTORY:
Written, CM, 23 Feb 2000
Added empty set capability, CM, 25 Feb 2000
Documentation clarification, CM 02 Mar 2000
Incompatible but more consistent reworking of EMPTY keywords, CM,
04 Mar 2000
Minor documentation clarifications, CM, 26 Mar 2000
Corrected bug in empty_arg special case, CM 06 Apr 2000
Add INDEX keyword, CM 31 Jul 2000
Clarify INDEX keyword documentation, CM 06 Sep 2000
Made INDEX keyword always force SLOW_SET_OP, CM 06 Sep 2000
Added CMSET_OP_UNIQ, and ability to select FIRST_UNIQUE or
LAST_UNIQUE values, CM, 18 Sep 2000
Removed FIRST_UNIQUE and LAST_UNIQUE, and streamlined
CMSET_OP_UNIQ until problems with SORT can be understood, CM, 20
Sep 2000 (thanks to Ben Tupper)
Still trying to get documentation of INDEX and NOT right, CM, 28
Sep 2000 (no code changes)
$Id: cmset_op.pro,v 1.2 2001/06/28 09:10:11 chr Exp $
(See $IDL_LOCAL\Utilities\cmset_op.pro)
NAME:
CW_FORM
PURPOSE:
CW_FORM is a compound widget that simplifies creating
small forms which contain text, numeric fields, buttons,
lists and droplists. Event handling is also simplified.
CATEGORY:
Compound widgets.
CALLING SEQUENCE:
widget = CW_FORM([Parent,] Desc)
INPUTS:
Parent: The ID of the parent widget. Omitted for a top level
modal widget.
Desc: A string array describing the form. Each element of the
string array contains two or more comma-delimited fields. The
character '\' may be used to escape commas that appear within fields.
To include the backslash character, escape it with a second
backslash. Field names are case insensitive.
The fields are defined as follows:
Field 1: Depth: the digit 0, 1, 2, or 3. 0 continues the current
level, 1 begins a new level, 2 denotes the last element of the
current level, and 3 both begins a new level and is the last entry of
the current level. Nesting is used primarily with row or column
bases for layout. See the example below.
Field 2: Item type: BASE, BUTTON, DROPLIST, FLOAT, INTEGER, LABEL, LIST,
or TEXT.
The items return the following value types:
BUTTON - For single buttons, 0 if clear, 1 if set.
For multiple buttons, also called button groups, that are
exclusive, the index of the currently set button is returned.
For non-exclusive button groups, the value is an array
with an element for each button, containing 1
if the button is set, 0 otherwise.
DROPLIST, LIST - a 0 based index indicating which item is selected.
FLOAT, INTEGER, TEXT - return their respective data type.
Field 3: Initial value. Omitted for bases.
For BUTTON and DROPLIST items, the value field contains one
or more item names, delimited by the | character.
For FLOAT, INTEGER, LABEL, and TEXT items the value field contains the
initial value of the field.
Fields 4 and following: Keywords or Keyword=value pairs that specify
optional attributes or options. Keywords are case insensitive
and an optional leading '/' character is discarded.
Possibilities include:
COLUMN If present, specifies column layout for bases or multiple
buttons.
EXCLUSIVE If present makes an exclusive set of buttons. The
default is nonexclusive.
EVENT= specifies the name of a user-written event function that
is called whenever the element is changed. The function
is called with one parameter, the event structure. It may
return an event structure or zero to indicate that no
further event processing is desired.
FONT= If present, the font for the item is specified.
FRAME: If present, a frame is drawn around the item. May be used
with all items.
LABEL_LEFT= (See $IDL_LOCAL\Utilities\cw_form.pro)
NAME:
ERROR_MESSAGE
PURPOSE:
The purpose of this function is to have a device-independent
error messaging function. The error message is reported
to the user by using DIALOG_MESSAGE if widgets are
supported and MESSAGE otherwise.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
Utility.
CALLING SEQUENCE:
ok = Error_Message(the_Error_Message)
INPUTS:
the_Error_Message: This is a string argument containing the error
message you want reported. If undefined, this variable is set
to the string in the !Error_State.Msg system variable.
KEYWORDS:
NONAME: If this keyword is set the name of the calling routine
is not printed along with the message.
TRACEBACK: Setting this keyword results in an error traceback
being printed to standard output with the PRINT command.
In addition, any keyword appropriate for the MESSAGE or DIALOG_MESSAGE
routines can also be used.
OUTPUTS:
Currently the only output from the function is the string "OK".
RESTRICTIONS:
The "Warning" Dialog_Message dialog is used by default. Use keywords
/ERROR or /INFORMATION to select other dialog behaviors.
EXAMPLE:
To handle an undefined variable error:
IF N_Elements(variable) EQ 0 THEN $
ok = Error_Message('Variable is undefined', /Traceback)
MODIFICATION HISTORY:
Written by: David Fanning, 27 April 1999.
Added the calling routine's name in the message and NoName keyword. 31 Jan 2000. DWF.
Added _Extra keyword. 10 February 2000. DWF.
Forgot to add _Extra everywhere. Fixed for MAIN errors. 8 AUG 2000. DWF.
Adding call routine's name to Traceback Report. 8 AUG 2000. DWF.
Switched default value for Dialog_Message to "Error" from "Warning". 7 OCT 2000. DWF.
(See $IDL_LOCAL\Utilities\error_message.pro)
NAME: GETUNIQ (former UNIQ IDL function) PURPOSE: Return the subscripts of the unique elements in an array. Note that repeated elements must be adjacent in order to be found. This routine is intended to be used with the SORT function. See the discussion of the IDX argument below. This command is inspired by the Unix uniq(1) command. CATEGORY: Array manipulation. CALLING SEQUENCE: GETUNIQ(Array [, Idx]) INPUTS: Array: The array to be scanned. The type and number of dimensions of the array are not important. The array must be sorted into monotonic order unless the optional parameter Idx is supplied. OPTIONAL INPUT PARAMETERS: IDX: This optional parameter is an array of indices into Array that order the elements into monotonic order. That is, the expression: Array(Idx) yields an array in which the elements of Array are rearranged into monotonic order. If the array is not already in monotonic order, use the command: GETUNIQ(Array, SORT(Array)) The expression below finds the unique elements of an unsorted array: Array(GETUNIQ(Array, SORT(Array))) OUTPUTS: An array of indicies into ARRAY is returned. The expression: ARRAY(UNIQ(ARRAY)) will be a copy of the sorted Array with duplicate adjacent elements removed. COMMON BLOCKS: None. MODIFICATION HISTORY: 1988, AB, Written. 29 July 1992, ACY - Corrected for case of all elements the same. Nov, 1995. DMS, Return a 0 if argument is a scalar. may 2001 vfs@acri-st.fr corrected for case where first/last numbers are the same
(See $IDL_LOCAL\Utilities\getuniq.pro)
NAME:
OWINDOW
PURPOSE:
The purpose of this program is to create an object window.
I use it mostly when I am creating and testing object graphics
programs, but it is also a nice template for larger object
graphics programs. The window is resizeable and it destroys
its objects when it is destroyed.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
2642 Bradbury Court
Fort Collins, CO 80521 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Widgets, IDL 5 Object Graphics.
CALLING SEQUENCE:
thisWindow = OWindow(thisView)
REQUIRED INPUTS:
None. A default view object is created with a gray background and
a viewplane rectangle defined as [0,0,1,1].
OPTIONAL INPUTS:
thisView: A view or scene object that you wish to be displayed
in the window.
RETURN VALUE:
thisWindow: The window graphics object associated with this window.
OPTIONAL KEYWORD PARAMETERS:
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
TITLE: A string used as the title of the graphics window.
XSIZE: The X Size of the graphics window in device coordinates. The
default value is 300.
YSIZE: The Y Size of the graphics window in device coordinates. The
default value is 300.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To display a view object in this window, type:
IDL> thisWindow = OWindow(thisView)
Later, after you have modified the view object, you can type:
IDL> thisWindow->Draw, modifiedView
MODIFICATION HISTORY:
Written by David Fanning, 19 June 97.
Set RETAIN=1 on draw widget. 6 Oct 97. DWF.
(See $IDL_LOCAL\Utilities\owindow.pro)
NAME:
PARSELINE
PURPOSE:
This function accepts a string as an argument and returns an
array which contains the numerical values in that string. It can
handle space or comma delimited numerical values. It returns
a value of -1 if non-numerical stuff is found in the line.
CALLING SEQUENCE:
array_out = PARSELINE(string_in, desired_data)
OPTIONAL INPUTS:
DESIRED_DATA -- An array which specifies the desired columns of data
from the string. It is zero based. Column numbers can be repeated in
the array. If this is not specified the default is to return an array
containing each value in the string once in the order they appear in
the string.
KEYWORD PARAMETERS:
DOUBLE -- The default behavior. The returned array will be a double
precision floating point array.
FLOAT -- The returned array will be a single precision floating point
array.
INTEGER -- The returned array will be an array of short integers.
RETURN VALUE:
array_out = dblarr(n_data) N_DATA is either the number of columns in
the string or the number of elements in the DESIRED_DATA array.
USAGE:
The calling procedure will look something like:
IDL> text=''
IDL> openr,1,'input.dat'
IDL> readf,1,text
IDL> data=parseline(text,[0,1,5,4,6,7])
IDL> print,data
0.10000000 3.4000000 2.4000000e-06 5.0000000 2.0080000 0.0000000
MAJOR FUNCTIONS and PROCEDURES:
None.
MODIFICATION HISTORY:
Written by: Alan Munter, munter@uiuc.edu, May 1997.
(See $IDL_LOCAL\Utilities\parseline.pro)
NAME:
PSWINDOW
PURPOSE:
This function is used to calculate the size of a PostScript
window that has the same aspect ratio (ratio of height to
width) as the current display graphics window. It creates
the largest possible PostScript output window with the
desired aspect ratio. This assures that graphics output
looks similar, if not identical, to PostScript output.
CATEGORY:
Graphics.
CALLING SEQUENCE:
pageInfo = PSWINDOW()
INPUTS:
None.
KEYWORD PARAMETERS:
CM: Normally the structure value that is returned from this
function reports its values in inches. Setting this keyword
causes the return values to be in units of centimeters.
LANDSCAPE: Normally this function assumes a PostScript window
in Portrait mode. Setting this keyword assumes you want
the graphic in Landscape mode.
MARGIN: Normally this function creates the largest possible
PostScript window of the specified aspect ratio that can fit
on an 8.5 x 11 inch PostScript page. The margin is an amount
subtracted from the page size before the output window is sized.
A default margin of 0.5 is used to assure that the page can be
printed on most PostScript printers. The value should be
specified in the same units the function returns.
OUTPUTS:
pageInfo: The output value is a named structure defined like
this:
pageInfo = {PSWINDOW_STRUCT, XSIZE:0.0, YSIZE:0.0, $
XOFSET:0.0, YOFFSET:0.0, INCHES:0, PORTRAIT:0, LANDSCAPE:0}
The units of the four size fields are inches unless the CM
keyword is set.
RESTRICTIONS:
The aspect ratio of the current graphics window is calculated
like this:
aspectRatio = FLOAT(!D.Y_VSIZE) / !D.X_VSIZE
A PostScript page of 8.5 x 11.0 inches is assumed.
EXAMPLE:
To create a PostScript output window with the same aspect
ratio as the curently active display window, type:
sizes = PSWINDOW()
SET_PLOT, 'PS'
DEVICE, XSIZE=sizes.xsize, YSIZE=sizes.ysize, $
XOFFSET=sizes.xoffset, YOFFSET=sizes.yoffset, INCHES=sizes.inches
MODIFICATION HISTORY:
Written by: David Fanning, November 1996.
Fixed a bug in which the YOFFSET was calculated incorrectly
in Landscape mode. 12 Feb 97.
Took out a line of code that wasn't being used. 14 Mar 97.
Added correct units keyword to return structure. 29 JUN 98. DWF
Fixed a bug in how landscape offsets were calculated. 19 JUL 99. DWF.
Fixed a bug in the way margins were used to conform to my
original conception of the program. 19 JUL 99. DWF.
Added Landscape and Portrait fields to the return structure. 19 JUL 99. DWF.
(See $IDL_LOCAL\Utilities\pswindow.pro)
NAME:
PS_FORM
PURPOSE:
This function displays a form the user can interactively manipulate
to configure the PostScript device driver (PS) setup. The function returns
a structure of keywords that can be sent directly to the DEVICE command
via its _EXTRA keyword
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
2642 Bradbury Court
Fort Collins, CO 80521 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
MAJOR TOPICS:
Device Drivers, Hardcopy Output, PostScript Output
PROCEDURE:
This is a pop-up form widget. It is a modal or blocking widget.
Keywords appropriate for the PostScript (PS) DEVICE command are returned.
The yellow box in the upper right hand corner of the form represents the
PostScript page. The green box represents the "window" on the PostScript
page where the graphics will be drawn.
Use your LEFT mouse button to move the plot "window" around the page.
Use your RIGHT mouse button to draw your own plot window on the page.
The CREATE FILE and ACCEPT buttons are meant to indicate slightly
different operations, although this is sometimes confusing. My idea
is that PS_FORM is a *configuration* dialog, something the user displays
if he or she wants to change the way the PostScript device is configured.
Thus, in many of my widget programs if the user clicks a "Write PostScript File"
button, I just go ahead and write a PostScript file without displaying the
form. (I can do this because I always keep a copy of the current device
configuration in my info structure.) To get to the form, the user must
select a "Configure PostScript Device" button.
At that time, the user might select the ACCEPT button to just change
the PostScript device configurations. Or the user can select the
CREATE FILE button, which both accepts the configuration *and* creates
a PostScript file. If you find the CREATE FILE button confusing, you
can just edit it out of the form and use the ACCEPT button for the
same purpose.
HELP:
formInfo = PS_FORM(/Help)
USAGE:
The calling procedure for this function in a widget program will look something
like this:
info.ps_config = PS_FORM(/Initialize)
...
formInfo = PS_FORM(Cancel=canceled, Create=create, $
Defaults=info.ps_config, Parent=event.top)
IF NOT canceled THEN BEGIN
IF create THEN BEGIN
thisDevice = !D.Name
Set_Plot, "PS"
Device, _Extra=formInfo
Enter Your Graphics Commands Here!
Device, /Close
Set_Plot, thisDevice
ENDIF
info.ps_config = formInfo
ENDIF
OPTIONAL INPUT PARAMETERS:
XOFFSET -- Optional xoffset of the top-level base of PS_Form. Default is
to try to center the form on the display.
YOFFSET -- Optional yoffset of the top-level base of PS_Form. Default is
to try to center the form on the display.
INPUT KEYWORD PARAMETERS:
BITS_PER_PIXEL -- The initial configuration of the bits per pixel button.
BLOCKING -- Set this keyword to make this a blocking widget under IDL 5.0.
(All widget programs block under IDL 4.0.)
COLOR -- The initial configuration of the color switch.
DEFAULTS -- A stucture variable of the same type and structure as the
RETURN VALUE of PS_FORM. It will set initial conditions. This makes
it possible to start PS_FORM up again with the same values it had the
last time it was called. For example:
mysetup = PS_FORM()
newsetup = PS_FORM(Defaults=mysetup)
NOTE: Using the DEFAULTS keyword will nullify any of the other
DEVICE-type keywords listed above (e.g., XSIZE, ENCAPSULATED, etc.)
ENCAPSULATED -- The initial configuration of the encapsulated switch.
FILENAME -- The initial filename to be used on the form.
HELP -- Prints a helpful message in the output log.
INCHES -- The initial configuration of the inches/cm switch.
INITIALIZE -- If this keyword is set, the program immediately returns the
"localdefaults" structure. This gives you the means to configue the
PostScript device without displaying the form to the user. I use this
to write a PostScript file directly and also to initialize my info
structure field that contains the current PostScript form setup. Passing
the setup structure into PS_FORM via the DEFAULTS keyword gives my PS_FORM
a program "memory".
info.ps_setup = PS_FORM(/Initialize)
LANDSCAPE -- The initial configuration of the landscape/portrait switch.
LOCALDEFAULTS -- A structure like the DEFAULTS structure. Used if the
"Local Defaults" button is pressed in the form. This gives you the
opportunity to have a "local" as well as "system" default setup.
If this keyword is not used, the procedure PS_Form_Set_Personal_Local_Defaults
is called. Use this procedure (see below) to define your own local
defaults.
XOFFSET -- The initial XOffSet of the PostScript window.
YOFFSET -- The initial YOffSet of the PostScript window.
XSIZE -- The initial XSize of the PostScript window.
YSIZE -- The initial YSize of the PostScript window.
OUTPUT KEYWORD PARAMETERS
CANCEL -- This is an OUTPUT keyword. It is used to check if the user
selected the "Cancel" button on the form. Check this variable rather
than the return value of the function, since the return value is designed
to be sent directly to the DEVICE procedure. The varible is set to 1 if
the user selected the "Cancel" button. Otherwise, it is set to 0.
CREATE -- This output keyword can be used to determine if the user
selected the 'Create File' button rather than the 'Accept' button.
The value is 1 if selected, and 0 otherwise.
RETURN VALUE:
formInfo = { PS_FORM_INFO, $
xsize:0.0, $ ; The x size of the plot
xoff:0.0, $ ; The x offset of the plot
ysize:0.0, $ ; The y size of the plot
yoff:0.0 $ ; The y offset of the plot
filename:'', $ ; The name of the output file
inches:0 $ ; Inches or centimeters?
color:0, $ ; Color on or off?
bits_per_pixel:0, $ ; How many bits per image pixel?
encapsulated:0,$ ; Encapsulated or regular PostScript?
landscape:0 } ; Landscape or portrait mode?
MAJOR FUNCTIONS and PROCEDURES:
None. Designed to work originally in conjunction with XWindow,
a resizable graphics window.
MODIFICATION HISTORY:
Written by: David Fanning, RSI, March 1995.
Given to attendees of IDL training courses.
Modified to work when grapics device set to PostScript: 6 May 95.
Modified to configure initial conditions via keywords: 13 October 95.
Modified to load personal local defaults if LocalDefaults keyword not
used: 3 Nov 95.
Found and fixed bits_per_pixel error in Local Defaults setting
procedure: 3 Nov 95.
Modified to produce initial plot box with the same aspect ratio as
the current graphics window. (XSIZE or YSIZE keywords overrule this
behavior.) 22 Apr 96.
Fixed annoying behavior of going to default-sized plot box when selecting
the Landscape or Portrait option. Now keeps current plot box size.
22 Apr 96.
Made the size and offset text widgets a little bigger and changed the
size and offset formatting from F4.2 to F5.2 to accomodate larger plot
box sizes. 29 Apr 96.
Fixed a bug in the filename text widget that caused a crash when a CR
was hit. 3 Sept 96.
Added the Initialize keyword to immediately return the "localdefaults"
structure. 27 Oct 96.
Fixed another problem with the BITS_PER_PIXEL keyword. 27 Oct 96.
Made the return value a named structure of the name PS_FORM_INFO.
3 Nov 96.
Discovered and fixed a problem whereby YOFFSET was set incorrectly if
LOCALDEFAULTS was used instead of DEFAULTS keyword. 3 Nov 96.
Fixed bug in how Portrait mode was set using YSIZE and XSIZE keywords.
25 Nov 96.
Fixed a bug in how YOFFSET was calculated when in Landscape mode. 27 Nov 96.
Fixed a memory leak with the local defaults pointer. 25 Jan 97.
Added the CREATE keyword and modified the appearance of the form. 22 Apr 97.
Modifed subroutine names to avoid confusion. 22 Apr 97.
Fixed a bug I introduced when I added the CREATE keyword. 23 Apr 97.
Modified the program for IDL 5. 30 May 97, DWF.
Fixed Inches to CM exclusive button problem. 30 May 97, DWF.
Fixed a problem when the widget is killed with the mouse. 30 May 97. DWF
Added a Select Filename button. 12 Oct 97.
Modified program layout slightly. 12 Oct 97.
Added valid directory/file error checking for the filename. 12 Oct 97. DWF
Added further support for IDL 5 modal functionality. 20 Oct 97. DWF
(See $IDL_LOCAL\Utilities\ps_form.pro)
NAME:
RELEASE_STRUCT_MEM
PURPOSE:
releases memory from all pointer tags of a structure
CATEGORY:
memory
CALLING SEQUENCE:
struct=RELEASE_STRUCT_MEM(struct)
INPUTS:
struct - any king of structure
OPTIONAL INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
structure with pointer tags all set to NULL
OPTIONAL OUTPUTS:
None
COMMON BLOCKS:
None
SIDE EFFECTS:
Unknown
RESTRICTIONS:
Unknown
PROCEDURE:
All tags of the structure are scanned, if the tag is of pointer
type than its memory is released.
EXAMPLE:
data=indgen(100,200)
struct={comment:'Building a structure w/ a tag comment', $
data:ptr_new(data)}
struct=RELEASE_STRUCT_MEM(struct)
MODIFICATION HISTORY:
Created June 2000 by Vincent Fournier-Sicre - vfs@acri.fr
(See $IDL_LOCAL\Utilities\release_struct_mem.pro)
NAME:
ROUTINE_NAMES (DOCUMENTATION ONLY)
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Examine variables and parameters of procedures and call stack (OBSOLETE)
CALLING SEQUENCE:
Various, see USAGE VARIATIONS.
DESCRIPTION:
ROUTINE_NAMES obtains information about routines, and their
variables and keywords. Using these functions, a subroutine can
interrogate, and in some cases change, the values and names of
variables and parameters in its calling routine, or at the $MAIN$
level. Some functionality of ROUTINE_NAMES is also in the IDL
system function ROUTINE_INFO, and other functionality is exclusive
to ROUTINE_NAMES.
ROUTINE_NAMES has been designated as "OBSOLETE" by RSI, although
it will probably not disappear soon since their own software
appears to use it.
ROUTINE_NAMES can be invoked in several different ways, which are
detailed below, under USAGE VARIATIONS.
ROUTINE_NAMES uses a notion of the current IDL "call level," which
is the numerical stack depth of the currently executing routine.
At each procedure or function call, the call level becomes one
*deeper*, and upon each RETURN, the call level becomes one
*shallower*. The call stack always begins at the $MAIN$ level.
The current call stack can always be printed by executing HELP.
When specifying the call level to ROUTINE_NAMES, one can use one
of two numbering systems, depending on whichever is most
convenient. In the *absolute* numbering system, the $MAIN$ level
starts at number 1, and becomes deeper with increasing numbers.
In the *relative* numbering system, the current (deepest) call
level is number 0, and becomes shallower with more negative
numbers. Hence, if the deepest level is N, then the
correspondence is thus:
VALUE MEANING
--------------------------------
1 or -N+1 $MAIN$ level
2 or -N+2 NEXT deeper level
... ...
N or 0 DEEPEST (currently executing) level
USAGE VARIATIONS:
PROCS = ROUTINE_NAMES( [/UNRESOLVED])
PROCS = ROUTINE_NAMES(/PROCEDURES [,/UNRESOLVED])
FUNCS = ROUTINE_NAMES(/FUNCTIONS [,/UNRESOLVED])
The currently compiled procedures and functions are
returned, respectively, as a string array. Functions
declared via FORWARD_FUNCTION are also returned. If the
UNRESOLVED keyword is set then the currently unresolved
procedures and functions are returned. These are known
routines which have not yet been compiled.
PROCS = ROUTINE_NAMES(/S_PROCEDURES)
FUNCS = ROUTINE_NAMES(/S_FUNCTIONS)
The lists of system procedures and functions is returned,
as a string array.
LEVNUM = ROUTINE_NAMES(/LEVEL)
The call level of the calling routine is returned.
NAMES = ROUTINE_NAMES(ARG0, ARG1, ..., ARGN, ARG_NAME=LEVEL)
The names of variables ARGi at call level LEVEL are
returned, as a string array. Note that ARGi are the
actual parameters, not strings containing their names.
ARGi must be parameters that have been passed to the
calling procedure. Variables that are unnamed at the
specified call level will return the empty string.
[IDL v5.0 and above only]
VARS = ROUTINE_NAMES(VARIABLES=LEVEL)
The names of variables at call level LEVEL are returned,
as a string array.
VARS = ROUTINE_NAMES(PROC, /P_VARIABLES, /P_PARAMETERS)
VARS = ROUTINE_NAMES(FUNC, /F_VARIABLES, /F_PARAMETERS)
The names of the variables and parameters, respectively,
defined in compiled procedure PROC, or compiled function
FUNC, are returned as a string array.
VALUE = ROUTINE_NAMES(NAME, FETCH=LEVEL)
The value of the named variable NAME at call level LEVEL
is returned. If the value is undefined, then the
assignment will cause an error. Therefore, the only safe
way to retrieve a value is by using a variant of the
following:
IF N_ELEMENTS(ROUTINE_NAMES(NAME, FETCH=LEVEL)) GT 0 THEN $
VALUE = ROUTINE_NAMES(NAME, FETCH=LEVEL)
DUMMY = ROUTINE_NAMES(NAME, VALUE, STORE=LEVEL)
The value VALUE is stored into the named variable NAME at
call level LEVEL. Note that there is no way to cause the
named variable to become undefined. The value returned
in DUMMY can be ignored.
[IDL v5.2 and earlier: new variables cannot be created]
[IDL v5.3 and later: new variables can be created]
SEE ALSO:
ROUTINE_INFO, ARG_PRESENT, DXDEBUG (Markwardt Debug Library)
MODIFICATION HISTORY:
Written, 20 Jul 2000
Documented differences between IDL versions, 21 Sep 2000, CM
$Id: routine_names.pro,v 1.2 2001/06/28 09:10:15 chr Exp $
(See $IDL_LOCAL\Utilities\routine_names.pro)
NAME:
SHOWPROGRESS__DEFINE
PURPOSE:
An object for creating a progress bar.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
2642 Bradbury Court
Fort Collins, CO 80521 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Utilities
CALLING SEQUENCE:
progressBar = Obj_New("SHOWPROGRESS")
INPUTS:
parent: A widget identifier of the widget that will be the
group leader for this program. It is *required* for modal
operation. If missing, you are on your own. :-(
KEYWORDS:
CANCELBUTTON: Set this keyword if a Cancel button is desired.
DELAY: The total time the widget should be on the display in AutoUpDate
mode. The keyword applies only to AutoUpDate mode. Default is 5 seconds.
STEPS: The number of steps to take in AutoUpDate mode. The keyword applies only
to AutoUpDate mode.
MESSAGE: The text of the label above the progress bar. Default is "Operation
in Progress...".
TITLE: ; The text of the top-level base title bar. Default is ""
COLOR: The color to draw the progress bar.
XSIZE: The XSize of the progress bar in Device coordinates. Default is 150.
YSIZE: The YSize of the progress bar in Device coordinates. Default is 10.
AUTOUPDATE: Set this keyword to be in AutoUpDate mode.
PROCEDURE:
There are two modes. In AutoUpDate mode, a delay and number of steps is
required. The modal widget stays on the display until the total time
exceeds the DELAY or the requested number of steps is taken. A TIMER
widget is used to generate update events. Nothing can be going on
concurrently in AutoUpDate mode. To enter AutoUpDate mode, type this:
progressBar = Obj_New("SHOWPROGRESS", /AutoUpDate, Delay=2, Steps=10)
progressBar->Start
Obj_Destroy, progressBar
The program will update and destroy itself automatically. (The object
itself is not destroyed. You must do this explicitly, as in the example
above.)
In normal mode, the user is responsible for starting, updating, and
destroying the progress indicator. The sequence of commands might look
like this:
progressBar = Obj_New("SHOWPROGRESS")
progressBar->Start
FOR j=0,9 DO BEGIN
Wait, 0.5 ; Would probably be doing something ELSE here!
progressBar->Update, (j+1)*10
ENDFOR
progressBar->Destroy
Obj_Destroy, progressBar
Normal mode gives you the opportunity to update the Progress Bar
in a loop while something else is going on. See the example program
at the end of this file.
Note that the object itself is not destroyed when calling the DESTROY
method. You must explicitly destroy the object, as in the example above.
METHODS:
CHECKCANCEL: This function method returns a 1 if the user has clicked
the CANCEL button. Otherwise, it returns a 0.
cancelled = progressBar->CheckCancel()
IF cancelled THEN progressBar->Destroy
DESTROY: Destroys the ShowProgress widgets. It does NOT destroy the object.
progressBar->Destroy
GETPROPERTY: Gets the properties that can be set in the INIT method, including
the parent widget ID.
progressBar->GetProperty, Steps=currentNSteps, Delay=currentDelay
SETCOLOR: Changes the color of the progress bar.
progressBar->SetColor, !P.Color
SETLABEL: Changes the text on the widget label.
progressBar->SetLabel, 'This text instead'
SETPROPERTY: Allows the user to set the INIT parameter via keywords.
progressBar->SetProperty, Color=244, XSize=200, Message='Please Wait...'
START: Puts the ShowProgress bar on the display. In AutoUpDate mode, the
widget starts to automatically update.
progressBar->Start
UPDATE: Updates the progress bar. Requires on argument, a number between 0
and 100 that indicates the percent of progress bar that should be filled
with a color.
progressBar->Update, 50
EXAMPLE:
See the example program at the bottom of this file.
RESTRICTIONS:
In contradiction to the IDL documentation, making the parent widget
insensitive in normal mode does NOT prevent the parent widgets from
receiving events on my Windows NT 4.0, SP 4 system running IDL 5.2,
IDL 5.2.1, or IDL 5.3 (beta).
Note that if you specify a CANCEL button the Show Progress program CANNOT
run as a MODAL widget program. Thus, user *may* be able to generate events
in the calling program while this program is running.
MODIFICATION HISTORY:
Written by: David Fanning, 26 July 1999.
Added code so that the current graphics window doesn't change. 1 September 1999. DWF.
Added yet more code for the same purpose. 3 September 1999. DWF.
Added a CANCEL button and made other minor modifications. 12 Oct 1999. DWF.
(See $IDL_LOCAL\Utilities\showprogress__define.pro)
NAME:
STRUCT_FREE (PROCEDURE)
PURPOSE:
Given an input structure, free all pointer data members.
WARNING: this function does not recursively free pointers - only
first level structure pointers are freed.
This procedure can be used, for example, from within an object
CLEANUP method to free object member data. Define object member
data as named structure, then from within the CLEANUP method
FREE_STRUCT_FREE, self.dataStruct
If new structure elements are added to dataStruct, the CLEANUP
method will not have to be altered.
INPUTS:
Any IDL variable
KEYWORD PARAMETERS:
VERBOSE
Set this keyword to print the structure tag names as
they are released
OUTPUTS:
NONE
RESTRICTIONS:
does not free arrays of pointers yet
MODIFICATION HISTORY:
1999 November, written, Robert.Mallozzi@msfc.nasa.gov
2001 added EXCEPT keyword vfs@acri-st.fr
2001 October added recursivity vfs@acri-st.fr
(See $IDL_LOCAL\Utilities\struct_free.pro)
NAME:
STR_SEP
PURPOSE:
This routine cuts a string into pieces which are separated by the
separator string.
CATEGORY:
String processing.
CALLING SEQUENCE:
arr = STR_SEP(str, separator)
INPUTS:
str - The string to be separated.
separator - The separator.
KEYWORDS:
ESC = escape character. Only valid if separator is a single character.
Characters following the escape character are treated
literally and not interpreted as separators.
For example, if the separator is a comma,
and the escape character is a backslash, the character
sequence 'a\,b' is a single field containing the characters
'a,b'.
REMOVE_ALL = if set, remove all blanks from fields.
TRIM = if set, remove only leading and trailing blanks from fields.
OUTPUT:
An array of strings as function value.
COMMON BLOCKS:
None
SIDE EFFECTS:
No known side effects.
RESTRICTIONS:
None.
EXAMPLE:
array = STR_SEP ("ulib.usca.test", ".")
MODIFICATION HISTORY:
July 1992, AH, CreaSo Created.
December, 1994, DMS, RSI Added TRIM and REMOVE_ALL.
(See $IDL_LOCAL\Utilities\str_sep.pro)
NAME:
STR_SIZE
PURPOSE:
The purpose of this function is to return the proper
character size to make a specified string a specifed
width in a window. The width is specified in normalized
coordinates. The function is extremely useful for sizing
strings and labels in resizeable graphics windows.
CATEGORY:
Graphics Programs, Widgets.
CALLING SEQUENCE:
thisCharSize = STR_SIZE(thisSting, targetWidth)
INPUTS:
thisString: This is the string that you want to make a specifed
target size or width.
OPTIONAL INPUTS:
targetWidth: This is the target width of the string in normalized
coordinates in the current graphics window. The character
size of the string (returned as thisCharSize) will be
calculated to get the string width as close as possible to
the target width. The default is 0.25.
KEYWORD PARAMETERS:
INITSIZE: This is the initial size of the string. Default is 1.0.
STEP: This is the amount the string size will change in each step
of the interative process of calculating the string size.
The default value is 0.05.
OUTPUTS:
thisCharSize: This is the size the specified string should be set
to if you want to produce output of the specified target
width. The value is in standard character size units where
1.0 is the standard character size.
EXAMPLE:
To make the string "Happy Holidays" take up 30% of the width of
the current graphics window, type this:
XYOUTS, 0.5, 0.5, ALIGN=0.5, "Happy Holidays", $
CHARSIZE=STR_SIZE("Happy Holidays", 0.3)
MODIFICATION HISTORY:
Written by: David Fanning, 17 DEC 96.
Added a scaling factor to take into account the aspect ratio
of the window in determing the character size. 28 Oct 97. DWF
(See $IDL_LOCAL\Utilities\str_size.pro)
NAME:
TODAY
PURPOSE:
Returns an IDLDT date/time structure containing the current
system date and time.
CATEGORY:
Misc
CALLING SEQUENCE:
result = TODAY()
INPUTS:
NONE
OPTIONAL INPUTS:
NONE
KEYWORD PARAMETERS:
NONE
OUTPUTS:
returns an IDLDT date/time structure containing the current
system date and time.
OPTIONAL OUTPUTS:
NONE
COMMON BLOCKS:
NONE
SIDE EFFECTS:
The named structure IDLDT is defined and the named common
block IDLDT_COMMON is created.
RESTRICTIONS:
PROCEDURE:
Uses VAR_TO_DT and SYSTIME.
EXAMPLE:
PRINT, TODAY()
resulted in
{ 1997 12 7 12 10 25.0000 2450790.0 0}
on the day this was written.
MODIFICATION HISTORY:
Dec 1997, Dr. G. Scott Lett, RSI, Written
(See $IDL_LOCAL\Utilities\today.pro)
NAME:
UNDEFINE
PURPOSE:
The purpose of this program is to delete or undefine
an IDL program variable from within an IDL program or
at the IDL command line. It is a more powerful DELVAR.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
2642 Bradbury Court
Fort Collins, CO 80521 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Utilities.
CALLING SEQUENCE:
UNDEFINE, variable
REQUIRED INPUTS:
variable: The variable to be deleted.
SIDE EFFECTS:
The variable no longer exists.
EXAMPLE:
To delete the variable "info", type:
IDL> Undefine, info
MODIFICATION HISTORY:
Written by David Fanning, 8 June 97, from an original program
given to me by Andrew Cool, DSTO, Adelaide, Australia.
(See $IDL_LOCAL\Utilities\undefine.pro)
NAME:
VAR_TO_DT
PURPOSE:
Convert values representing date and time to an IDLDT date/time
variable.
CATEGORY:
Misc
CALLING SEQUENCE:
dtvar = VAR_TO_DT( yyyy, mm, dd, hh, min, ss)
INPUTS:
OPTIONAL INPUTS:
yyyy: A scalar or array containing integer year(s).
mm: A scalar or array containing integer month(s)
dd: A scalar or array containing integer day(s) of the month.
hh: A scalar or array containing integer hour(s) of the day.
min: A scalar or array containing integer minute(s).
ss: A scalar or array containing the float seconds.
KEYWORD PARAMETERS:
OUTPUTS:
VAR_TO_DT returns the IDLDT date/time structure containing the
converted date(s).
OPTIONAL OUTPUTS:
COMMON BLOCKS:
NONE
SIDE EFFECTS:
The result is a named IDLDT date/time structure. If the
structure named IDLDT has not been defined, IDL invokes the
IDLDT__DEFINE procedure to create it. IDLDT__DEFINE creates
a number of system variables.
RESTRICTIONS:
If any of the inputs are arrays, all of the inputs, if present,
must be arrays of the same dimension.
PROCEDURE:
EXAMPLES:
date = VAR_TO_DT( 1997, 12, 21 ) ; Create an IDLDT with default
; Values for hh, mm, ss.
PRINT, date
The result is
{ 1997 12 21 0 0.00000 0.0000000 0 }
date = VAR_TO_DT( [1997, 1998], [12, 1], [1, 1] )
MODIFICATION HISTORY:
(See $IDL_LOCAL\Utilities\var_to_dt.pro)
NAME:
xcd
PURPOSE:
Change current directory via mouse.
Two lists are displayed side by side. The one on the left shows
directories. Click on a directory to cd there. The list
on the right shows files to help you see where you are.
(The list on the right does not respond to mouse clicks.)
CATEGORY:
Utility.
CALLING SEQUENCE:
xcd
INPUTS:
None.
KEYWORD PARAMETERS:
None
OUTPUTS:
None.
SIDE EFFECTS:
Your current directory can be changed.
RESTRICTIONS:
Windows & OpenVMS platforms only. Originally written on Windows95.
Should work on other Windows platforms, but I (Paul) havn't tried it.
With a little effort, one probably could port Xcd to other platforms
(i.e. Unix or Mac).
Note that drive names (e.g. "a:", "c:", etc.) are hardcoded in
xcd::init. Change that line of code to show drive letters
appropriate for your system.
PROCEDURE:
Xcd creates an object that has a reference to a DirListing, and
widgets for displaying that DirListing. If the user clicks on a
sub-directory (or "..\") in the xcd object, or droplist-selects
a different drive via the xcd object, the xcd object changes
IDL's current directory to that location, and refreshes with a
new current-directory DirListing.
MODIFICATION HISTORY:
Paul C. Sorenson, July 1997. paulcs@netcom.com.
Written with IDL 5.0. The object-oriented design of Xcd is
based in part on an example authored by Mark Rivers.
Jim Pendleton, July 1997. jimp@rsinc.com
Modified for compatability with OpenVMS as a basis for
platform independent code
Paul C. Sorenson, July 13 1997. Changes so that DirListing class
methods do not return pointers to data members. (Better
object-oriented design that way.)
(See $IDL_LOCAL\Utilities\xcd.pro)
NAME:
XWINDOW
PURPOSE:
This routine implements a "smart" resizeable graphics window.
It is used as a wrapper for built-in IDL graphics procedures
such as SURFACE, CONTOUR, PLOT, SHADE_SURF, etc. In additon,
it can be used to display any user-written graphics procedure
so long as that procedure follows three simple rules: (1) It
does not open it's own graphics windows, (2) It is defined with
no more than three positional arguments (an unlimited number
of keyword arguments are allowed), and (3) It is defined
with an _EXTRA keyword.
Keyword arguments permit the window to have its own portion
of a color table and to be able to change the colors loaded in
that portion of the color table. Colors are updated
automatically on both 8-bit and 24-bit color displays. In
addition, the window colors can "protect" themselves. I mean
by this that the window can re-load its own colors into the
color table when the cursor is moved over the window (X device)
or the user clicks in the window (all other devices). This
prevents other applications from changing the colors used to
display data in this window. (This is an issue mainly in
IDL 5 applications where widget applications can run
concurrently with commands from the IDL command line.)
Keyword arguments also permit the window to create output
files of its contents. These files can be color and
gray-scale PostScript, GIF, TIFF, or JPEG files.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
2642 Bradbury Court
Fort Collins, CO 80521 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Widgets, Graphics.
CALLING SEQUENCE:
XWINDOW, command, P1, P2, P3
REQUIRED INPUTS:
COMMAND: The graphics procedure command to be executed. This parameter
must be a STRING. Examples are 'SURFACE', 'CONTOUR', 'PLOT', etc.
OPTIONAL INPUTS:
P1: The first positional parameter appropriate for the graphics
command.
P2: The second positional parameter appropriate for the graphics
command.
P3: The third positional parameter appropriate for the graphics
command.
INPUT KEYWORD PARAMETERS:
BACKGROUND: The background color index for the window. Setting this color
along with the ERASE keyword causes the window to be erased with
this color.
CPMENU: Setting this keyword adds a "Color Protection" button to the
"Controls" menu. Color protection can then be turned ON or OFF for the
window. Otherwise, the color protection scheme used to open the window
cannot be changed once the window is open. (See the PROTECT keyword.)
The default is to have this keyword OFF.
ERASE: Setting this keyword "erases" the contents of the current
graphics window before re-executing the graphics command. For example,
this keyword might need to be set if the graphics "command" is TVSCL.
The default is to NOT erase the display before reissuing the graphics
command.
_EXTRA: This keyword forms an anonymous structure of any unrecognized
keywords passed to the program. The keywords must be appropriate
for the graphics command being executed.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
OUTPUT: Set this keyword if you want a "File Output" menu on
the menu bar. The default is to have this item turned OFF. File output
will allow you to create GIF, JPEG, TIFF, and PostScript output from
what you see in the display window.
JUST_REGISTER: If this keyword is set, the XWINDOW program is just
registered with XMANAGER, but XMANAGER doesn't run. This is
useful, for example, if you want to open an XWINDOW window in
the widget definition module of another widget program.
NO_CHANGE_CONFIG: Normally as the XWINDOW graphics window is resized
the size (or aspect ratio, in the case of PostScript) of the
hardware configuration dialogs change to reflect the new size of
the graphics window. This results in file output that resembles
the current graphics window in size and aspect ratio. If you want
the file output dialogs to remember their current configuration
even as the window is resized, set this keyword.
NOMENU: Setting this keyword results in a graphics window without
menu items. The default is to have a "Controls" menu item in the
window menu bar with a "Quit" button. Setting this keyword
automatically turns of the COLORS, OUTPUT, and CPMENU menu
choices. (Note that the values specified by the COLORS keyword
will still be valid for color protection, but no "Change Colors..."
menu item will appear.)
PROTECT: If this keyword is set, color protection for the draw
widget is turned ON. What this means is that the window colors
(see the XCOLOR keyword) will be restored when the cursor enters
the draw widget window (on X devices) or when the user clicks in
the draw widget window (other devices). This prevents someone at
the IDL command line in IDL 5 from changing the window display
colors permanently.
WTITLE: This is the window title. It is the string "Resizeable
COMMAND Window (1)" by default, where COMMAND is the input
parameter. And the number (1 in this case) is the window
index number of the draw widget.
WXPOS: This is the initial X offset of the window. Default is to
position the window in the approximate middle of the display.
WYPOS: This is the initial Y offset of the window. Default is to
position the window in the approximate middle of the display.
WXSIZE: This is the initial X size of the window. Default is 400
pixels.
WYSIZE: This is the initial Y size of the window. Default is 400
pixels.
XCOLORS: Using this keyword adds a "Change Colors..." button to the
"Controls" menu. Set this keyword to the number of colors available
in the window and the starting index of the first color. For example,
to allow the window access to 100 colors, starting at color index 50
(i.e., color indices 50 to 149), use XColor=[100, 50]. If you use the
keyword syntax "/XColor", all the colors available will be used, not just
one color. If the keyword is set to a scalar value greater than 1, the
starting color index is set to 0. The default value for this keyword
is [(!D.N_COLORS < 256), 0]. Note that color "protection" may be
turned on (via the PROTECT keyword) even if this keyword is NOT used.
OUTPUT KEYWORD PARAMETERS:
DRAWID: This keyword returns the draw widget identifier of the draw
widget created in XWINDOW.
TOP: This keyword returns the identifier of the top-level base widget
created by XWINDOW.
WID: This keyword returns the window index number of the draw widget
created in XWINDOW.
COMMON BLOCKS:
None.
SIDE EFFECTS:
If color protection is ON, the window colors are reloaded when the
cursor enters the XWINDOW graphics windows.
RESTRICTIONS:
This program requires three additional programs from the Fanning
Software Consulting library: PSWINDOW, PS_FORM, and XCOLORS. You
might also want to get the program TVIMAGE if you will be displaying
images in XWINDOW graphics windows.
If the "command" program requires keywords that are also keywords
to XWINDOW, then you must use the keyword twice on the command line.
The program uses the Z-Graphics Buffer to create GIF, TIFF, and JPEG
output. Be sure your program doesn't use commands that are illegal in
the Z-Buffer. Two commands in particular come to mind: Window and
Device, Decomposed=0.
EXAMPLE:
To display a surface in the window, type:
XWINDOW, 'SURFACE', Dist(20), Charsize=1.5
To enable the Change Colors and File Output menu items, type:
XWINDOW, 'SHADE_SURF', Dist(30), /XColors, /Output
MODIFICATION HISTORY:
Written by: David Fanning, October 96.
XSIZE and YSIZE keywords changed to WXSIZE and WYSIZE so as not to
conflict with these keywords on other programs. 14 April 1997, DWF.
Updated as non-blocking widget for IDL 5.0. 14 April 1997, DWF.
Extensively modified to work on either 8-bit or 24-bit displays,
to enable color protection schemes, to send the contents to a
number of different output files, and to give the user choices
about which menu items to enable. 21 April 1997, DWF.
Renamed COLORS keyword to XCOLORS and fixed a problem cancelling
out of File Configuration dialogs. 23 April 1997, DWF.
Updated program to IDL 5 functionality. 20 Oct 1997, DWF.
Changed color protection scheme to widget tracking for X devices
and clicking in the draw widget window for all other devices.
This gets around unreliable tracking events on window machines.
20 Oct 1997, DWF.
Added a BACKGROUND keyword and caused the program to ERASE in the
background color. 1 May 1998.
Added a Device, Decomposed=0 call to make this work on 24-bit
devices. DWF, 29 June 1998.
Fixed a problem with number of colors that RSI introduced in IDL
5.1 for PCs. 15 Aug 1998.
Added more error checking for programs that work on the display
but not in the Z-Graphics Buffer where GIF, TIFF, and JPEG
output is created. DWF. 10 September 1998.
Improved error handling and updated some obsolete commands. 6 May 99. DWF.
(See $IDL_LOCAL\Utilities\xwindow.pro)