This page was created by the IDL library routine
mk_html_help2.
Last modified: Fri Nov 2 10:24:04 2012.
NAME:
CENTERTLB
PURPOSE:
This is a utility routine to position 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, /DEVICE]
REQUIRED INPUTS:
tlb: The top-level base identifier of the widget program. This must
be a valid widget ID.
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:
DEVICE: Normally, the x and y parameters are specified in normalized
coordinates. If this keyword is set, they are taken to be in DEVICE
coordinates.
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.
Added a maximum value of 1280 for X screen size. This helps
center the widget on a single monitor when using dual
monitor settings with some graphics cards. 3 Feb 2003. DWF.
Added DEVICE keyword. 4 January 2006. DWF.
(See themis/thm_ui_new/utilities/centertlb.pro)
NAME:
COLOR24
PURPOSE:
The purpose of this function is to convert a RGB color triple
into the equivalent 24-bit long integer. The 24-bit integer
can be decomposed into the appropriate color by interpreting
the lowest 8 bits as red, the middle 8 bits as green, and the
highest 8 bits as blue.
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:
Graphics, Color Specification.
CALLING SEQUENCE:
color = COLOR24(rgb_triple)
INPUTS:
RGB_TRIPLE: A three-element column or row array representing
a color triple. Or an N-by-three element array of color triples.
The values of the elements must be between 0 and 255.
KEYWORD PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To convert the color triple for the color YELLOW,
(255, 255, 0), to the hexadecimal value '00FFFF'x
or the decimal number 65535, type:
color = COLOR24([255, 255, 0])
This routine was written to be used with device-independent
color programs like GETCOLOR.
MODIFICATION HISTORY:
Written by: David Fanning, 3 February 96.
Completely revised the algorithm to accept color arrays. 19 October 2000. DWF.
(See themis/thm_ui_new/utilities/color24.pro)
NAME:
COLORBAR
PURPOSE:
The purpose of this routine is to add a color bar to the current
graphics window.
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:
Graphics, Widgets.
CALLING SEQUENCE:
COLORBAR
INPUTS:
None.
KEYWORD PARAMETERS:
BOTTOM: The lowest color index of the colors to be loaded in
the bar.
CHARSIZE: The character size of the color bar annotations. Default is 1.0.
COLOR: The color index of the bar outline and characters. Default
is !P.Color..
DIVISIONS: The number of divisions to divide the bar into. There will
be (divisions + 1) annotations. The default is 6.
FONT: Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.
FORMAT: The format of the bar annotations. Default is '(I5)'.
INVERTCOLORS: Setting this keyword inverts the colors in the color bar.
MAXRANGE: The maximum data value for the bar annotation. Default is
NCOLORS.
MINRANGE: The minimum data value for the bar annotation. Default is 0.
MINOR: The number of minor tick divisions. Default is 2.
NCOLORS: This is the number of colors in the color bar.
POSITION: A four-element array of normalized coordinates in the same
form as the POSITION keyword on a plot. Default is
[0.88, 0.10, 0.95, 0.90] for a vertical bar and
[0.10, 0.88, 0.90, 0.95] for a horizontal bar.
;
RANGE: A two-element vector of the form [min, max]. Provides an
alternative way of setting the MINRANGE and MAXRANGE keywords.
RIGHT: This puts the labels on the right-hand side of a vertical
color bar. It applies only to vertical color bars.
TICKNAMES: A string array of names or values for the tick marks.
TITLE: This is title for the color bar. The default is to have
no title.
TOP: This puts the labels on top of the bar rather than under it.
The keyword only applies if a horizontal color bar is rendered.
VERTICAL: Setting this keyword give a vertical color bar. The default
is a horizontal color bar.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Color bar is drawn in the current graphics window.
RESTRICTIONS:
The number of colors available on the display device (not the
PostScript device) is used unless the NCOLORS keyword is used.
EXAMPLE:
To display a horizontal color bar above a contour plot, type:
LOADCT, 5, NCOLORS=100
CONTOUR, DIST(31,41), POSITION=[0.15, 0.15, 0.95, 0.75], $
C_COLORS=INDGEN(25)*4, NLEVELS=25
COLORBAR, NCOLORS=100, POSITION=[0.15, 0.85, 0.95, 0.90]
MODIFICATION HISTORY:
Written by: David W. Fanning, 10 JUNE 96.
10/27/96: Added the ability to send output to PostScript. DWF
11/4/96: Substantially rewritten to go to screen or PostScript
file without having to know much about the PostScript device
or even what the current graphics device is. DWF
1/27/97: Added the RIGHT and TOP keywords. Also modified the
way the TITLE keyword works. DWF
7/15/97: Fixed a problem some machines have with plots that have
no valid data range in them. DWF
12/5/98: Fixed a problem in how the colorbar image is created that
seemed to tickle a bug in some versions of IDL. DWF.
1/12/99: Fixed a problem caused by RSI fixing a bug in IDL 5.2. Sigh... DWF.
3/30/99: Modified a few of the defaults. DWF.
3/30/99: Used NORMAL rather than DEVICE coords for positioning bar. DWF.
3/30/99: Added the RANGE keyword. DWF.
3/30/99: Added FONT keyword. DWF
5/6/99: Many modifications to defaults. DWF.
5/6/99: Removed PSCOLOR keyword. DWF.
5/6/99: Improved error handling on position coordinates. DWF.
5/6/99. Added MINOR keyword. DWF.
5/6/99: Set Device, Decomposed=0 if necessary. DWF.
2/9/99: Fixed a problem caused by setting BOTTOM keyword, but not NCOLORS. DWF.
8/17/99. Fixed a problem with ambiguous MIN and MINOR keywords. DWF
8/25/99. I think I *finally* got the BOTTOM/NCOLORS thing sorted out. :-( DWF.
10/10/99. Modified the program so that current plot and map coordinates are
saved and restored after the colorbar is drawn. DWF.
3/18/00. Moved a block of code to prevent a problem with color decomposition. DWF.
4/28/00. Made !P.Font default value for FONT keyword. DWF.
9/26/00. Made the code more general for scalable pixel devices. DWF.
1/16/01. Added INVERTCOLORS keyword. DWF.
5/11/04. Added TICKNAME keyword. DWF.
(See themis/thm_ui_new/utilities/colorbar.pro)
NAME:
COLORBAR__DEFINE
PURPOSE:
The purpose of this routine is to implement a COLORBAR object
class. The ColorBar is rendered in the direct graphics system.
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:
Graphics.
CALLING SEQUENCE:
colorbar = Obj_New("COLORBAR")
INPUTS:
All inputs to the program are via keyword parameters.
KEYWORD PARAMETERS:
Background: Background color. This is the color with which the colorbar is
erased. The default color is !P.Background.
Bottom: Bottom color index of colors allocated to colorbar.
Charsize: Character size of annotation. Default is 1.0.
Color: Color of annotation and outline. Default is !P.Color.
Font: Font to use for annotation. Default is -1, Hershey fonts.
Format: Format of annotation. Default is "(F8.2)".
Major: The number of major tick intervals. Default is 5.
Minor: The number of minor tick intervals. Default is 2.
MinusOne: Set this keyword to choose MinusOne keyword on the Congrid command
that resizes the colorbar into the window.
NColors: The number of colors allocated to colorbar. Default is (256 <
!D.N_Colors).
Neighbor: Set to indicate Nearest Neighbor sampling for Congrid. Default is
0 (Bilinear).
Position: The position of colorbar in normalized coordinates. Default for a
horizontal colorbar is [0.15, 0.88, 0.85, 0.95]. Default for a
vertical colorbar is [0.88, 0.15, 0.95, 0.85]. These defaults are
designed for a 400 by 400 window.
Range: The data range on colorbar. Default is [0, 255].
TickLen: The length of tick marks. Default is -0.1
TickV: Locations for the tick marks in data units. This is the same as
the [XY]TickV keyword. Default is to do what IDL would do
normally.
Vertical: Set this keyword if you want a vertical colorbar. Default is
horizontal.
XEraseBox: A five-element vector of X points (normalized) for erasing the
colorbar plot. Normally this keyword will not have to be used.
The program uses the plot REGION for erasing. But larger
character sizes can result in annotation going outside the
region enclosed by the plot. If that is the case, then use this
keyword along with YEraseBox to specify a larger-than-normal
erasure area. The points are sent to the POLYFILL command for
erasing.
POLYFILL, xEraseBox, yEraseBox, /Normal, Color=background
YEraseBox: A five-element vector of Y points (normalized) for erasing the
colorbar plot.
OBJECT METHODS:
Clamp: This procedure method allows the color bar range to be "clamped"
to a particular data range.
Draw: This procedure method draws the colorbar in the display window. The
ERASE keyword to this method will erase the current colorbar (by
calling the ERASE method) before drawing the colorbar in the display
window.
colorbar->Draw
Erase: This procedure method erases the colorbar object in the window. It
accomplishes this by performing a POLYFILL in the background color.
This method is primarily useful for interactive graphics display
devices.
colorbar->Erase
GetProperty: This procedure method allows one to obtain the current state
of the object via the keyword parameters listed above.
colorbar->GetProperty, Range=currentRange, Title=currentTitle
Print, currentRange, currentTitle
SetProperty: This procedure method allows one to set the properties of the
colorbar object via the keywords described above. In addition,
a DRAW and ERASE keyword are provided so that the colorbar can
be immediately drawn when the new property is set.
colorbar->SetProperty, Range=[500, 15000], /Erase, /Draw
COMMON BLOCKS:
None.
SIDE EFFECTS:
The display window is not erased first.
RESTRICTIONS:
None.
EXAMPLE:
To create a colorbar, use it, then destroy it, type:
colorbar = Obj_New("COLORBAR", Title='Colorbar Values', Range=[0,1000],$
Format='(I4)')
Window
LoadCT, 5
colorbar->Draw
colorbar->SetProperty, Range=[0,500], /Erase, /Draw
Obj_Destroy, colorbar
MODIFICATION HISTORY:
Written by: David Fanning, Fanning Software Consulting,
26 November 1998.
Added Horizontal keyword to SetProperty method and fixed problem in
going from Vertical to Horizontal color bars. 29 Nov 1998. DWF.
Added LoadCT method and current color table index to object.
6 December 1998.
Fixed a bug dealing with nearest neighbor resampling. 30 Mar 1999. DWF.
Fixed a bug with how NCOLORS and BOTTOM keywords interacted.
29 Aug 1999. DWF.
10 Oct 99. Modified the program so that current plot and map coordinates
are saved and restored after the colorbar is drawn. DWF.
26 May 2000 Added {XY}TICKV capability to the draw method. This
required adding TickV to the object data structure, and to the
INIT, GetProperty and SetProperty methods.
Changed default tick length to -0.1. DWF (and Jack Saba)
18 Nov 2001. Added Clamp method. DWF.
(See themis/thm_ui_new/utilities/colorbar__define.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.
In general, the ERROR_MESSAGE function is not called directly.
Rather, it is used in a CATCH error handler. Errors are thrown
to ERROR_MESSAGE with the MESSAGE command. A typical CATCH error
handler is shown below.
Catch, theError
IF theError NE 0 THEN BEGIN
Catch, /Cancel
ok = Error_Message(/Traceback, /Error)
RETURN
ENDIF
Error messages would get into the ERROR_MESSAGE function by
throwing an error with the MESSAGE command, like this:
IF test NE 1 THEN Message, 'The test failed.'
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:
ERROR: Set this keyword to cause Dialog_Message to use the ERROR
reporting dialog. Note that a bug in IDL causes the ERROR dialog
to be used whether this keyword is set to 0 or 1!
INFORMATIONAL: Set this keyword to cause Dialog_Message to use the
INFORMATION dialog instead of the WARNING dialog. Note that a bug
in IDL causes the ERROR dialog to be used if this keyword is set to 0!
TITLE: Set this keyword to the title of the DIALOG_MESSAGE window. By
default the keyword is set to 'System Error' unless !ERROR_STATE.NAME
equals "IDL_M_USER_ERR", in which case it is set to "Trapped Error'.
TRACEBACK: Setting this keyword results in an error traceback
being printed to standard output with the PRINT command. Set to
1 (ON) by default. Use TRACEBACK=0 to turn this functionality off.
OUTPUTS:
Currently the only output from the function is the string "OK".
RESTRICTIONS:
The WARNING Dialog_Message dialog is used by default.
EXAMPLE:
To handle an undefined variable error:
IF N_Elements(variable) EQ 0 THEN $
ok = Error_Message('Variable is undefined', /Traceback)
NOTES: This version has a systen variable called !GUIDEBUG that has been added for usage with
the THEMIS GUI, it is used to disable windowing with this error routine. If !GUIDEBUG = 1
this routine will only print to command line. To set GUIDEBUG call: defsysv,'!GUIDEBUG',1
MODIFICATION HISTORY:
Written by: David W. 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.
Added ERROR, INFORMATIONAL, and TITLE keywords. 19 SEP 2002. DWF.
Removed the requirement that you use the NONAME keyword with the MESSAGE
command when generating user-trapped errors. 19 SEP 2002. DWF.
Added distinctions between trapped errors (errors generated with the
MESSAGE command) and IDL system errors. Note that if you call ERROR_MESSAGE
directly, then the state of the !ERROR_STATE.NAME variable is set
to the *last* error generated. It is better to access ERROR_MESSAGE
indirectly in a Catch error handler from the MESSAGE command. 19 SEP 2002. DWF.
Change on 19 SEP 2002 to eliminate NONAME requirement did not apply to object methods.
Fixed program to also handle messages from object methods. 30 JULY 2003. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Made a traceback the default case without setting TRACEBACK keyword. 19 Nov 2004. DWF.
Added !GUIDEBUG keyword support. Patrick Cruce 2008-09-17
(See themis/thm_ui_new/utilities/error_message.pro)
FUNCTION:
formatannotation
PURPOSE:
This routine is used as a callback for axis labeling by IDLgrAxis
Because it is a callback routine, IDL requires it to have this specific form.
It is probably useful as a general purpose formatting routine, as well.
Inputs:
Axis:Required by IDL, but ignored
Index: Required by IDL, but ignored
Value: Required The value to be formatted.
Data: Keyword,Required
The data struct holds the important information and has the following format:
data = {timeAxis:0B, $ ;Should we format as time data?
formatid:0L, $ ;Precision of returned value in sig figs
scaling:0B, $ ;0:Linear,1:Log10,2:LogN
exponent:0B, $ ;(REQUIRED for non-time data)0:Auto-Format(see description),1:Numerical(double),2:Sci-Notation(1.2x10^3)
range:[0D,0D],$ ; The range field is optional. If it is present in the struct, value will be interpreted a multiplier over the specified range.(generally this is used if the data is being stored as a proportion)
noformatcodes:0b} ; Optional, set to 1 to disable IDL formatting codes like !U
Auto-Format:
If the number being formatted is too large or small to be displayed with the requested number of
significant figures then the number will be automatically displayed in scientific notation
(e.g. for 3 sig. figs '1234.5' will be shown as '1.23x10^3' and '.00012345' will be shown as '1.23x10^-4')
Values in log_10() space will be displayed as '10^1.2'
Values in ln() space will be displayes as 'e^1.2'
Integer formatting is not effected.
Formatting Codes:
Formatting codes are utilized to create superscripts and unicode characters that are displayd
by IDLgraxis:
!z(00d7): Unicode multiplication symbol
!U : Superscripts the following substring
Example:
print,formatannotation(0,0,1,data={timeaxis:0,formatid:7,scaling:0,exponent:0})
1.000000
print,formatannotation(0,0,.5,data={timeaxis:1,formatid:12,scaling:0,range:[time_double('2007-03-23'),time_double('2007-03-24')]})
082/12:00:00.000
print,formatannotation(0,0,4,data={timeaxis:0,formatid:5,scaling:2,exponent:0})
e!U4.0000
print,formatannotation(0,0,.25,data={timeaxis:0,formatid:5,scaling:1,range:[1,2],exponent:0})
10!U1.2500
print,formatannotation(0,0,1234,data={timeaxis:0,formatid:7,scaling:0,exponent:2})
1.234000!z(00d7)10!U3
$LastChangedBy: aaflores $
$LastChangedDate: 2012-03-08 11:33:47 -0800 (Thu, 08 Mar 2012) $
$LastChangedRevision: 9997 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/formatannotation.pro $
(See themis/thm_ui_new/utilities/formatannotation.pro)
NAME:
FSC_COLOR
PURPOSE:
The purpose of this function is to obtain drawing colors
by name and in a device/decomposition independent way. The
color names and values may be read in as a file, or 88
color names and values are supplied from the program. These
were obtained from the file rgb.txt, found on most X-Window
distributions. Representative colors were chose from across
the color spectrum. To see a list of colors available, type:
Print, FSC_Color(/Names), Format='(6A15)'.
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:
Graphics, Color Specification.
CALLING SEQUENCE:
color = FSC_COLOR(theColor, theColorIndex)
NORMAL CALLING SEQUENCE FOR DEVICE-INDEPENDENT COLOR:
If you write your graphics code *exactly* as it is written below, then
the same code will work in all graphics devices I have tested.
These include the PRINTER, PS, and Z devices, as well as X, WIN, and MAC.
In practice, graphics code is seldom written like this. (For a variety of
reasons, but laziness is high on the list.) So I have made the
program reasonably tolerant of poor programming practices. I just
point this out as a place you might return to before you write me
a nice note saying my program "doesn't work". :-)
axisColor = FSC_COLOR("Green", !D.Table_Size-2)
backColor = FSC_COLOR("Charcoal", !D.Table_Size-3)
dataColor = FSC_COLOR("Yellow", !D.Table_Size-4)
thisDevice = !D.Name
Set_Plot, 'toWhateverYourDeviceIsGoingToBe', /Copy
Device, .... ; Whatever you need here to set things up properly.
IF (!D.Flags AND 256) EQ 0 THEN $
POLYFILL, [0,1,1,0,0], [0,0,1,1,0], /Normal, Color=backColor
Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData, $
NoErase= ((!D.Flags AND 256) EQ 0)
OPlot, Findgen(11), Color=dataColor
Device, .... ; Whatever you need here to wrap things up properly.
Set_Plot, thisDevice
OPTIONAL INPUT PARAMETERS:
theColor: A string with the "name" of the color. To see a list
of the color names available set the NAMES keyword. This may
also be a vector of color names. Colors available are these:
Almond Antique White Aquamarine Beige Bisque Black
Blue Blue Violet Brown Burlywood Charcoal Chartreuse
Chocolate Coral Cornsilk Cyan Dark Goldenrod Dark Gray
Dark Green Dark Khaki Dark Orchid Dark Salmon Deep Pink Dodger Blue
Firebrick Forest Green Gold Goldenrod Gray Green
Green Yellow Honeydew Hot Pink Indian Red Ivory Khaki
Lavender Lawn Green Light Coral Light Cyan Light Gray Light Salmon
Light Yellow Lime Green Linen Magenta Maroon Medium Gray
Medium Orchid Moccasin Navy Olive Olive Drab Orange
Orange Red Orchid Pale Goldenrod Pale Green Papaya Peru
Pink Plum Powder Blue Purple Red Rose
Rosy Brown Royal Blue Saddle Brown Salmon Sandy Brown Sea Green
Seashell Sienna Sky Blue Slate Gray Snow Spring Green
Steel Blue Tan Thistle Tomato Turquoise Violet
Violet Red Wheat White Yellow
Also, these system color names are available in IDL 5.6 and higher: Frame, Text, Active,
Shadow, Highlight, Edge, Selected, Face.
The color WHITE is used if this parameter is absent or a color name is mis-spelled. To see a list
of the color names available in the program, type this:
Print, FSC_COLOR(/Names), Format='(6A15)'
theColorIndex: The color table index (or vector of indices the same length
as the color name vector) where the specified color is loaded. The color table
index parameter should always be used if you wish to obtain a color value in a
color-decomposition-independent way in your code. See the NORMAL CALLING
SEQUENCE for details. If theColor is a vector, and theColorIndex is a scalar,
then the colors will be loaded starting at theColorIndex.
RETURN VALUE:
The value that is returned by FSC_COLOR depends upon the keywords
used to call it, on the version of IDL you are using,and on the depth
of the display device when the program is invoked. In general,
the return value will be either a color index number where the specified
color is loaded by the program, or a 24-bit color value that can be
decomposed into the specified color on true-color systems. (Or a vector
of such numbers.)
If you are running IDL 5.2 or higher, the program will determine which
return value to use, based on the color decomposition state at the time
the program is called. If you are running a version of IDL before IDL 5.2,
then the program will return the color index number. This behavior can
be overruled in all versions of IDL by setting the DECOMPOSED keyword.
If this keyword is 0, the program always returns a color index number. If
the keyword is 1, the program always returns a 24-bit color value.
If the TRIPLE keyword is set, the program always returns the color triple,
no matter what the current decomposition state or the value of the DECOMPOSED
keyword. Normally, the color triple is returned as a 1 by 3 column vector.
This is appropriate for loading into a color index with TVLCT:
IDL> TVLCT, FSC_Color('Yellow', /Triple), !P.Color
But sometimes (e.g, in object graphics applications) you want the color
returned as a row vector. In this case, you should set the ROW keyword
as well as the TRIPLE keyword:
viewobj= Obj_New('IDLgrView', Color=FSC_Color('charcoal', /Triple, /Row))
If the ALLCOLORS keyword is used, then instead of a single value, modified
as described above, then all the color values are returned in an array. In
other words, the return value will be either an NCOLORS-element vector of color
table index numbers, an NCOLORS-element vector of 24-bit color values, or
an NCOLORS-by-3 array of color triples.
If the NAMES keyword is set, the program returns a vector of
color names known to the program.
If the color index parameter is not used, and a 24-bit value is not being
returned, then colorIndex is typically set to !D.Table_Size-1. However,
this behavior is changed on 8-bit devices (e.g., the PostScript device,
or the Z-graphics buffer) and on 24-bit devices that are *not* using
decomposed color. On these devices, the colors are loaded at an
offset of !D.Table_Size - ncolors - 2, and the color index parameter reflects
the actual index of the color where it will be loaded. This makes it possible
to use a formulation as below:
Plot, data, Color=FSC_Color('Dodger Blue')
on 24-bit displays *and* in PostScript output! Note that if you specify a color
index (the safest thing to do), then it will always be honored.
INPUT KEYWORD PARAMETERS:
ALLCOLORS: Set this keyword to return indices, or 24-bit values, or color
triples, for all the known colors, instead of for a single color.
DECOMPOSED: Set this keyword to 0 or 1 to force the return value to be
a color table index or a 24-bit color value, respectively.
FILENAME: The string name of an ASCII file that can be opened to read in
color values and color names. There should be one color per row
in the file. Please be sure there are no blank lines in the file.
The format of each row should be:
redValue greenValue blueValue colorName
Color values should be between 0 and 255. Any kind of white-space
separation (blank characters, commas, or tabs) are allowed. The color
name should be a string, but it should NOT be in quotes. A typical
entry into the file would look like this:
255 255 0 Yellow
NAMES: If this keyword is set, the return value of the function is
a ncolors-element string array containing the names of the colors.
These names would be appropriate, for example, in building
a list widget with the names of the colors. If the NAMES
keyword is set, the COLOR and INDEX parameters are ignored.
listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
ROW: If this keyword is set, the return value of the function when the TRIPLE
keyword is set is returned as a row vector, rather than as the default
column vector. This is required, for example, when you are trying to
use the return value to set the color for object graphics objects. This
keyword is completely ignored, except when used in combination with the
TRIPLE keyword.
SELECTCOLOR: Set this keyword if you would like to select the color name with
the PICKCOLORNAME program. Selecting this keyword automaticallys sets
the INDEX positional parameter. If this keyword is used, any keywords
appropriate for PICKCOLORNAME can also be used. If this keyword is used,
the first positional parameter can be either a color name or the color
table index number. The program will figure out what you want.
TRIPLE: Setting this keyword will force the return value of the function to
*always* be a color triple, regardless of color decomposition state or
visual depth of the machine. The value will be a three-element column
vector unless the ROW keyword is also set.
In addition, any keyword parameter appropriate for PICKCOLORNAME can be used.
These include BOTTOM, COLUMNS, GROUP_LEADER, INDEX, and TITLE.
OUTPUT KEYWORD PARAMETERS:
CANCEL: This keyword is always set to 0, unless that SELECTCOLOR keyword is used.
Then it will correspond to the value of the CANCEL output keyword in PICKCOLORNAME.
COLORSTRUCTURE: This output keyword (if set to a named variable) will return a
structure in which the fields will be the known color names (without spaces)
and the values of the fields will be either color table index numbers or
24-bit color values. If you have specified a vector of color names, then
this will be a structure containing just those color names as fields.
NCOLORS: The number of colors recognized by the program. It will be 88 by default.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
ADDITIONAL PROGRAMS REQUIRED:
PICKCOLORNAME: This file can be found in the Coyote Library:
http://www.dfanning.com/programs/pickcolorname.pro
EXAMPLE:
To get drawing colors in a device-decomposed independent way:
axisColor = FSC_COLOR("Green", !D.Table_Size-2)
backColor = FSC_COLOR("Charcoal", !D.Table_Size-3)
dataColor = FSC_COLOR("Yellow", !D.Table_Size-4)
Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData
OPlot, Findgen(11), Color=dataColor
To set the viewport color in object graphics:
theView = Obj_New('IDLgrView', Color=FSC_Color('Charcoal', /Triple))
To change the viewport color later:
theView->SetProperty, Color=FSC_Color('Antique White', /Triple)
To load the drawing colors "red", "green", and "yellow" at indices 100-102, type this:
IDL> TVLCT, FSC_Color(["red", "green", and "yellow"], /Triple), 100
MODIFICATION HISTORY:
Written by: David W. Fanning, 19 October 2000. Based on previous
GetColor program.
Fixed a problem with loading colors with TVLCT on a PRINTER device. 13 Mar 2001. DWF.
Added the ROW keyword. 30 March 2001. DWF.
Added the PICKCOLORNAME code to the file, since I keep forgetting to
give it to people. 15 August 2001. DWF.
Added ability to specify color names and indices as vectors. 5 Nov 2002. DWF.
Fixed a problem with the TRIPLE keyword when specifying a vector of color names. 14 Feb 2003. DWF.
Fixed a small problem with the starting index when specifying ALLCOLORS. 24 March 2003. DWF.
Added system color names. 23 Jan 2004. DWF
Added work-around for WHERE function "feature" when theColor is a one-element array. 22 July 2004. DWF.
Added support for 8-bit graphics devices when color index is not specified. 25 August 2004. DWF.
Fixed a small problem with creating color structure when ALLCOLORS keyword is set. 26 August 2004. DWF.
Extended the color index fix for 8-bit graphics devices on 25 August 2004 to
24-bit devices running with color decomposition OFF. I've concluded most of
the people using IDL don't have any idea how color works, so I am trying to
make it VERY simple, and yet still maintain the power of this program. So now,
in general, for most simple plots, you don't have to use the colorindex parameter
and you still have a very good chance of getting what you expect in a device-independent
manner. Of course, it would be *nice* if you could use that 24-bit display you paid
all that money for, but I understand your reluctance. :-) 11 October 2004. DWF.
Have renamed the first positional parameter so that this variable doesn't change
while the program is running. 7 December 2004. DWF.
Fixed an error I introduced on 7 December 2004. Sigh... 7 January 2005. DWF.
(See themis/thm_ui_new/utilities/fsc_color.pro)
NAME:
FSC_FIELD
PURPOSE:
The purpose of this compound widget is to provide an alternative
to the CW_FIELD widget offered in the IDL distribution. One weakness
of the CW_FIELD compound widget is that the text widgets do not
look editable to the users on Windows platforms. This program
corrects that deficiency and adds some features that I think
will be helpful. For example, you can now assign an event handler
to the compound widget, ask for positive numbers only, and limit
the number of digits in a number, or the number of digits to the
right of a decimal point. The program is written as a widget object,
which allows the user to call object methods directly, affording
even more flexibility in use. This program replaces the earlier
programs FSC_INPUTFIELD and COYOTE_FIELD.
The program consists of a label widget next to a one-line text widget.
The "value" of the compound widget is shown in the text widget. If the
value is a number, it will not be possible (generally) to type
alphanumeric values in the text widget. String values behave like
strings in any one-line text widget.
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:
General programming.
TYPICAL CALLING SEQUENCE:
fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3)
INPUT PARAMETERS:
parent -- The parent widget ID of the compound widget. Required.
INPUT KEYWORDS:
COLUMN Set this keyword to have the Label widget above the Text widget.
The default is to have the Label widget in a row with the Text widget.
CR_ONLY Set this keyword if you only want Carriage Return events returned to
your event handler. If this keyword is not set, all events are returned.
Setting this keyword has no effect unless either the EVENT_PRO or
EVENT_FUNC keyword is used.
DECIMAL Set this keyword to the number of digits to the right of the decimal
point in floating point or double precision numbers. Ignored for STRING values.
DIGITS Set this keyword to the number of digits permitted in integer numbers.
EVENT_FUNC Set this keyword to the name of an event handler function. If this
keyword is undefined and the Event_Pro keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.
EVENT_PRO Set this keyword to the name of an event handler procedure. If this
keyword is undefined and the Event_Func keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.
FIELDFONT The font name for the text in the text widget.
FRAME Set this keyword to put a frame around the compound widget.
FOCUS_EVENTS Set this keyword to enable event generation for keyboard focus
events. Ignored unless EVENT_FUNC or EVENT_PRO keywords are specified.
HIGHLIGHT Set this keyword to highlight the existing text if the widget gain
the keyboard focus. This keyword MUST be set for tabbing to work naturally
in IDL 6.2 and higher.
LABEL_LEFT Set this keyword to align the text on the label to the left.
LABEL_RIGHT Set this keyword to align the text on the label to the right.
LABELFONT The font name for the text in the label widget.
LABELSIZE The X screen size of the label widget.
NAME A string containing the name of the object. The default is ''.
NOEDIT Set this keyword to allow no user editing of the input text widget.
NONSENSITIVE Set this keyword to make the input text widget non-sensitive.
POSITIVE Set this keyword if you want only positive numbers allowed.
SCR_XSIZE The X screen size of the compound widget.
SCR_YSIZE The Y screen size of the compound widget.
TITLE The string text placed on the label widget.
UNDEFINED Set this keyword to the value to use for "undefined" values. If
not set, then !Value.F_NAN is used for numerical fields and a
NULL string is used for string fields. This applies to values
obtained with the GET_VALUE method or the GET_VALUE function.
UVALUE A user value for any purpose.
VALUE The "value" of the compound widget. Any type of integer, floating, or string
variable is allowed. The data "type" is determined automatically from the
value supplied with this keyword. Be sure you set the type appropriately for
your intended use of the value.
XSIZE The X size of the text widget in the usual character units.
OUTPUT KEYWORDS:
OBJECT Set this keyword to a named variable to receive the compound widget's
object reference. This is required if you wish to call methods on the object.
Note that the object reference is also available in the event structure
generated by the widget object. Note that the object reference will be
necessary if you want to get or set values in the compound widget.
COMMON BLOCKS:
None.
RESTRICTIONS:
Requires DBLTOSTR from the Coyote Library:
http://www.dfanning.com/programs/dbltostr.pro
EVENT STRUCTURE:
All events are handled internally unless either the Event_Pro or Event_Func
keywords are used to assign an event handler to the compound widget. By
default all events generated by the text widget are passed to the assigned
event handler. If you wish to receive only Carriage Return events, set the
CR_Only keyword.
event = { FSC_FIELD_EVENT, $ ; The name of the event structure.
ID: 0L, $ ; The ID of the compound widget's top-level base.
TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
OBJECT: Obj_New(), $ ; The "self" object reference. Provided so you can call methods.
VALUE: Ptr_New(), $ ; A pointer to the widget value.
TYPE:"" ; A string indicating the type of data in the VALUE field.
}
Note that if the field is "empty", the VALUE will be a pointer
to an undefined variable. You should check this value before you
use it. You code will look something like this:
IF N_Elements(*event.value) EQ 0 THEN $
Print, 'Current Value UNDEFINED.' ELSE $
Print, 'Current Value: ', *event.value
GETTING and SETTING VALUES:
Almost all the properties of the widget can be obtained or set via
the object's GetProperty and SetProperty methods (described below).
Traditional compound widgets have the ability to get and set the "value"
of the compound widget identifier (e.g., fieldID in the calling
sequence above). Unfortunately, it is impossible to retreive a variable
in this way when the variable is undefined. In practical terms, this
means that the undefined variable must be set to *something*. You can
determine what that something is with the UNDEFINED keyword, or I will set
it to !VALUES.F_NAN for numerical fields and to the null string for string
fields. In any case, you will have to check for undefined variables before
you try to do something with the value. For a numerical field, the code
might look something like this:
fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3)
currentValue = fieldObject->Get_Value()
IF Finite(currentValue) EQ 0 THEN Print, 'Value is Undefined' ELSE Print, currentValue
Additional examples are provided in the numerical example fields in Example Program below.
Setting the value of the compound widget is the same as calling the Set_Value
method on the object reference. In other words, these two statements are equivalent.
fieldObject->Set_Value, 45.4
Widget_Control, fieldID, Set_Value=45.4
The data type of the value is determined from the value itself. Be sure you set it appropriately.
OBJECT PROCEDURE METHODS:
GetProperty -- This method allows various properties of the widget to be
returned via output keywords. The keywords that are available are:
CR_Only -- A flag, if set, means only report carriage return events.
DataType -- The data type of the field variable.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
Event_Func -- The name of the event handler function.
Event_Pro -- The name of the event handler function.
Has_Focus -- Set to 1 if the text widget currently has the keyboard focus.
Highlight -- The highlight flag.
NoEdit -- The NoEdit flag.
NonSensitive -- The NonSensitive flag.
Undefined -- The "value" of any undefined value.
UValue -- The user value assigned to the compound widget.
Value -- The "value" of the compound widget.
Name -- A scalar string name of the object.
Resize -- This method allows you to resize the compound widget's text field.
The value parameter is an X screen size for the entire widget. The text
widget is sized by using the value obtained from this value minus the
X screen size of the label widget.
objectRef->Resize, screen_xsize_value
Set_Value -- This method allows you to set the "value" of the field. It takes
one positional parameter, which is the value.
objectRef->Set_Value, 5
SetProperty -- This method allows various properties of the widget to be
set via input keywords. The keywords that are available are:
CR_Only -- Set this keyword if you only want Carriage Return events.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOAT and DOUBLE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGER and LONG numbers.
Event_Func -- Set this keyword to the name of an Event Function.
Event_Pro -- Set this keyword to the name of an Event Procedure.
Highlight -- Set this keyword to highlight the existing text
when the widget gets the keyboard focus
LabelSize -- The X screen size of the Label Widget.
Name -- A scalar string name of the object. (default = '')
NoEdit -- Set this keyword to make the text widget uneditable
NonSensitive -- Set this keyword to make the widget nonsensitive
Scr_XSize -- The X screen size of the text widget.
Scr_YSize -- The Y screen size of the text widget.
Title -- The text to go on the Label Widget.
UValue -- A user value for any purpose.
Value -- The "value" of the compound widget.
XSize -- The X size of the Text Widget.
SetTabNext -- This method allows you to specify which field to go to when a TAB character
is typed in the text widget. See the Example program below for an example of how to
use this method.
OBJECT FUNCTIONS METHODS:
Get_Value -- Returns the "value" of the field. No parameters. Will be undefined
if a "number" field is blank. Should be checked before using:
IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value()
GetID -- Returns the widget identifier of the compound widget's top-level base.
(The first child of the parent widget.) No parameters.
GetLabelSize -- Returns the X screen size of the label widget. No parameters.
GetTextID -- Returns the widget identifier of the compound widget's text widget.
No parameters.
GetTextSize -- Returns the X screen size of the text widget. No parameters.
PRIVATE OBJECT METHODS:
Although there is really no such thing as a "private" method in IDL's
object implementation, some methods are used internally and not meant to
be acessed publicly. Here are a few of those methods. I list them because
it may be these private methods are ones you wish to override in subclassed
objects.
MoveTab -- This method moves the focus to the widget identified in the "next" field,
which must be set with the SetTabNext method. No parameters. Called automatically
when a TAB character is typed in the text widget.
Text_Events -- The main event handler method for the compound widget. All
text widget events are processed here.
ReturnValue -- This function method accepts a string input value and converts
it to the type of data requested by the user.
Validate -- This function method examines all text input and removes unwanted
characters, depending upon the requested data type for the field. It makes it
impossible, for example, to type alphanumeric characters in an INTEGER field.
EXAMPLE:
An example program is provided at the end of the FSC_FIELD code. To run it,
type these commands:
IDL> .Compile FSC_Field
IDL> Example
MODIFICATION HISTORY:
Written by: David W. Fanning, 18 October 2000. Based heavily on an earlier
FSC_INPUTFIELD program and new ideas about the best way to write
widget objects.
Added LABEL_LEFT, LABEL_RIGHT, and UNDEFINED keywords. 29 Dec 2000. DWF.
Modified the way the value is returned in the GET_VALUE method and the
GET_VALUE function. Modified Example program to demonstrate. 30 Dec 2000. DWF.
Added NOEDIT and NONSENSITIVE keywords, with corresponding SETEDIT and SETSENNSITIVE
methods. 19 Jan 2001. DWF.
Actually followed through with the changes I _said_" I made 29 Dec 2000. (Don't ask....) 13 June 2001. DWF.
Added GetTextSize and GetLabelSize methods for obtaining the X screen
size of the text and label widgets, respectively. 21 July 2001. DWF.
Fixed a problem in SetProperty method where I was setting self.xsize, which doesn't exist. 24 April 2002. DWF.
Small modification to the SetEdit method. 6 August 2003. DWF.
Added Highlight keyword. Ported Focus_Events keyword from
fsc_inputfield.pro. Updated documentation. 17 November
2004. DWF and Benjamin Hornberger
Added Has_Focus keyword to the GetProperty method. 18 November
2004. Benjamin Hornberger
Fixed bug in GetProperty method (set value to *self.undefined if
*self.value is undefined. 24 Feb 2004. Benjamin Hornberger
Modified FOCUS_EVENTS keyword handling so that *all* focus events are now
passed to specified event handlers. Check event.select to see if the
widget is gaining or losing focus. 10 August 2005. DWF.
Added new tabbing functionality, introduced in IDL 6.2. To use tabbing
functionality natually, the HIGHTLIGHT keywords must be set.
See included EXAMPLE program for details. 10 August 2005. DWF.
Added functionality to covert double precision values to strings properly. 30 Nov 2005. DWF.
(See themis/thm_ui_new/utilities/fsc_field.pro)
NAME:
GETCOLOR
PURPOSE:
The original purpose of this function was to enable the
user to specify one of the 16 colors supported by the
McIDAS color map by name. Over time, however, the function
has become a general purpose function for handling and
supporting drawing colors in a device-independent way.
In particular, I have been looking for ways to write color
handling code that will work transparently on both 8-bit and
24-bit machines. On 24-bit machines, the code should work the
same where color decomposition is turned on or off. The program
now supports 88 colors.
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:
Graphics, Color Specification.
CALLING SEQUENCE:
result = GETCOLOR(color, index)
OPTIONAL INPUT PARAMETERS:
COLOR: A string with the "name" of the color. Valid names are:
black
magenta
cyan
yellow
green
red
blue
navy
pink
aqua
orchid
sky
beige
charcoal
gray
white
The color YELLOW is returned if the color name can't be resolved.
Case is unimportant.
If the function is called with just this single input parameter,
the return value is either a 1-by-3 array containing the RGB values of
that particular color, or a 24-bit integer that can be "decomposed" into
that particular color, depending upon the state of the TRUE keyword and
upon whether color decomposition is turned on or off. The state of color
decomposition can ONLY be determined if the program is being run in
IDL 5.2 or higher.
INDEX: The color table index where the specified color should be loaded.
If this parameter is passed, then the return value of the function is the
index number and not the color triple. (If color decomposition is turned
on AND the user specifies an index parameter, the color is loaded in the
color table at the proper index, but a 24-bit value is returned to the
user in IDL 5.2 and higher. This assumes the INDEXED keyword is NOT set.)
If no positional parameter is present, then the return value is either a 16-by-3
byte array containing the RGB values of all 16 colors or it is a 16-element
long integer array containing color values that can be decomposed into colors.
The 16-by-3 array is appropriate for loading color tables with the TVLCT command:
Device, Decomposed=0
colors = GetColor()
TVLCT, colors, 100
INPUT KEYWORD PARAMETERS:
NAMES: If this keyword is set, the return value of the function is
a 88-element string array containing the names of the colors.
These names would be appropriate, for example, in building
a list widget with the names of the colors. If the NAMES
keyword is set, the COLOR and INDEX parameters are ignored.
listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
INDEXED: If this keyword is set, the return value is always an index
into the color table. In the absence of a color table INDEX
parameter, the color is loaded at !P.COLOR < (!D.Table_Size-1).
LOAD: If this keyword is set, all 88 colors are automatically loaded
starting at the color index specified by the START keyword.
Note that setting this keyword means that the return value of the
function will be a structure, with each field of the structure
corresponding to a color name. The value of each field will be
an index number (set by the START keyword) corresponding to the
associated color, or a 24-bit long integer value that creates the
color on a true-color device. What you have as the field values is
determined by the TRUE keyword or whether color decomposition is on
or off in the absense of the TRUE keyword. It will either be a 1-by-3
byte array or a long integer value.
START: The starting color index number if the LOAD keyword is set. This keyword
value is ignored unless the LOAD keyword is also set. The keyword is also
ignored if the TRUE keyword is set or if color decomposition in on in
IDL 5.2 and higher. The default value for the START keyword is
!D.TABLE_SIZE - 89.
TRUE: If this keyword is set, the specified color triple is returned
as a 24-bit integer equivalent. The lowest 8 bits correspond to
the red value; the middle 8 bits to the green value; and the
highest 8 bits correspond to the blue value. In IDL 5.2 and higher,
if color decomposition is turned on, it is as though this keyword
were set.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The TRUE keyword causes the START keyword to be ignored.
The NAMES keyword causes the COLOR, INDEX, START, and TRUE parameters to be ignored.
The COLOR parameter is ignored if the LOAD keyword is used.
On systems where it is possible to tell the state of color decomposition
(i.e., IDL 5.2 and higher), a 24-bit value (or values) is automatically
returned if color decomposition is ON.
EXAMPLE:
To load a yellow color in color index 100 and plot in yellow, type:
yellow = GETCOLOR('yellow', 100)
PLOT, data, COLOR=yellow
or,
PLOT, data, COLOR=GETCOLOR('yellow', 100)
To do the same thing on a 24-bit color system with decomposed color on, type:
PLOT, data, COLOR=GETCOLOR('yellow', /TRUE)
or in IDL 5.2 and higher,
DEVICE, Decomposed=1
PLOT, data, COLOR=GETCOLOR('yellow')
To load all 88 colors into the current color table, starting at
color index 100, type:
TVLCT, GETCOLOR(), 100
To add the color names to a list widget:
listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
To load all 88 colors and have the color indices returned in a structure:
DEVICE, Decomposed=0
colors = GetColor(/Load, Start=1)
HELP, colors, /Structure
PLOT, data, COLOR=colors.yellow
To get the direct color values as 24-bit integers in color structure fields:
DEVICE, Decomposed=1
colors = GetColor(/Load)
PLOT, data, COLOR=colors.yellow
Note that the START keyword value is ignored if on a 24-bit device,
so it is possible to write completely device-independent code by
writing code like this:
colors = GetColor(/Load)
PLOT, data, Color=colors.yellow
MODIFICATION HISTORY:
Written by: David Fanning, 10 February 96.
Fixed a bug in which N_ELEMENTS was spelled wrong. 7 Dec 96. DWF
Added the McIDAS colors to the program. 24 Feb 99. DWF
Added the INDEX parameter to the program 8 Mar 99. DWF
Added the NAMES keyword at insistence of Martin Schultz. 10 Mar 99. DWF
Reorderd the colors so black is first and white is last. 7 June 99. DWF
Added automatic recognition of DECOMPOSED=1 state. 7 June 99. DWF
Added LOAD AND START keywords. 7 June 99. DWF.
Replaced GOLD with CHARCOAL color. 28 Oct 99. DWF.
Added INDEXED keyword to force indexed color mode. 28 Oct 99. DWF.
Fixed problem of "aqua" and "pink" being mixed up. 18 Mar 00. DWF.
Changed ON_ERROR from 1 to 2, and improved error handling. 2 Aug 00. DWF.
Increased the known colors from 16 to 88. 19 October 2000. DWF.
(See themis/thm_ui_new/utilities/getcolor.pro)
NAME: getctpath PURPOSE: gets the path of the color table on the file system CALLING SEQUENCE: getctpath,color_table_path OUTPUT: color_table_path: the path to the color table $LastChangedBy: pcruce $ $LastChangedDate: 2009-01-13 17:58:38 -0800 (Tue, 13 Jan 2009) $ $LastChangedRevision: 4457 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/getctpath.pro $
(See themis/thm_ui_new/utilities/getctpath.pro)
NAME: gethelppath PURPOSE: gets the path of the help directory in a cross platform way CALLING SEQUENCE: gethelppath,path OUTPUT: path: the path to the resource directory $LastChangedBy: pcruce $ $LastChangedDate: 2009-05-29 09:27:40 -0700 (Fri, 29 May 2009) $ $LastChangedRevision: 5990 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/gethelppath.pro $
(See themis/thm_ui_new/utilities/gethelppath.pro)
NAME: getresourcepath PURPOSE: gets the path of the resource directory in a cross platform way CALLING SEQUENCE: getresourcepath,path OUTPUT: path: the path to the resource directory $LastChangedBy: cgoethel_new $ $LastChangedDate: 2009-03-12 14:23:23 -0700 (Thu, 12 Mar 2009) $ $LastChangedRevision: 5268 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/getresourcepath.pro $
(See themis/thm_ui_new/utilities/getresourcepath.pro)
Call this function to return the absolute file path to the
<b>introduction</b> directory (used to store files for the
<i>Introduction to IDL</i> class) on your computer.
<p>
This routine replaces SET_TRAINING_DIRECTORY, which is now obsolete.
<p>
@pre This file must reside in the same directory as the course files.
@returns The path to the directory where the course files reside.
@examples
<pre>
IDL> dir = get_intro_dir()
IDL> print, filepath('hello.pro', root=dir)
/home/mpiper/IDL/introduction/hello.pro
</pre>
@uses SOURCEROOT or SOURCEPATH
@requires IDL 5.2
@author Mark Piper, RSI, 2005
(See themis/thm_ui_new/utilities/get_intro_dir.pro)
NAME: get_max_memblock.pro PURPOSE: Returns size of largest contiguous block of memory available to IDL in megabytes. This function is intended to be used as a guide to determine how much data can be stored in a single operation without IDL returning an "Unable to allocate memory" error. The block size returned is not necessarily the largest block in RAM. It might be partially or completely located in virtual memory/disk swap space, in which case performance might suffer if that block is used. Note that the returned value is only a snapshot in time. Since other things can be going on with the OS and other applications, the size of the largest free memory block can increase or decrease in the time between calling this function and attempting to fill that block with data. It is up to the programmer to decide what percentage of the returned value is safe to use. CALLING SEQUENCE: maxBlockSize = get_max_memblock() INPUT: None OUTPUT: Size of largest contiguous memory block available to IDL in megabytes.
(See themis/thm_ui_new/utilities/get_max_memblock.pro)
NAME:
get_max_memblock2.pro
PURPOSE:
Returns size of largest contiguous block of memory available to IDL in
megabytes.
This function is intended to be used as a guide to determine how much data
can be stored in a single operation without IDL returning an "Unable to
allocate memory" error. The block size returned is not necessarily the
largest block in RAM. It might be partially or completely located in virtual
memory/disk swap space, in which case performance might suffer if that block
is used.
Note that the returned value is only a snapshot in time. Since other things
can be going on with the OS and other applications, the size of the largest
free memory block can increase or decrease in the time between calling this
function and attempting to fill that block with data. It is up to the
programmer to decide what percentage of the returned value is safe to use.
CALLING SEQUENCE:
maxBlockSize = get_max_memblock()
INPUT:
None
KEYWORDS:
maxblock_in = the size of the initial value of the max blocksize in
bytes, the default is 12 Gigabytes worth. Note that a
long64 integer is needed if the value is larger than 2
gBytes.
OUTPUT:
Size of largest contiguous memory block available to IDL in
megabytes.
Modification HISTORY:
jmm, 3-feb-2009, hacked get_max_memblock--changed method to bisection
(See themis/thm_ui_new/utilities/get_max_memblock2.pro)
Name: is_num
Purpose: determines if input string is a validly formatted number. Does
Inputs: s: the string to be checked
Outputs: 1: if it is validly formatted
0: if it is not
Notes: Does not consider numbers in complex notation or numbers with trailing type codes to be valid.
Examples:
print,is_numeric('1')
1
print,is_numeric('1.23e45')
1
print,is_numeric('1.2c34')
0
print,is_numeric('1B')
0
print,is_numeric('-1.23d-3')
1
print,is_numeric('5e+4')
1
print,is_numeric('5.e2')
1
print,is_numeric('5.e3.2')
0
$LastChangedBy: pcruce $
$LastChangedDate: 2009-01-09 16:58:39 -0800 (Fri, 09 Jan 2009) $
$LastChangedRevision: 4402 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/is_numeric.pro $
(See themis/thm_ui_new/utilities/is_numeric.pro)
NAME:
LOADDATA
PURPOSE:
The purpose of this function is to read a selection of standard
data sets that are found in the normal IDL distribution in the
subdirectory $IDL_DIR/examples/data. At least 17 data sets are
available in all categories of data. The user selects one of the
possible data sets with the mouse.
CATEGORY:
File I/O.
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/
CALLING SEQUENCE:
If calling from the IDL command line:
data = LoadData()
If calling from within a widget program:
data = LoadData(Cancel=cancelled, Group_Leader=event.top)
If you know which data set you want, you can load it directly:
data = LoadData(7)
OPTIONAL INPUTS:
selection : The number of the data selection. Values start at 1,
and go up to the number of data sets available (currently 17).
KEYWORD PARAMETERS:
CANCEL : An output keyword that is 1 of the use clicked the CANCEL
button and 0 otherwise.
data = Loaddata(Cancel=cancelled)
IF cancelled THEN RETURN
GROUP_LEADER: The group leader of the widget. This keyword
is required if you wish LOADDATA to be a modal widget program.
(Which you *always* do when calling it from a widget program.)
IMAGES: Set this keyword if you only want to select 2D image
data sets. Note that the selection number does *not* change
just because fewer data sets are available in the selection
widget.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To load the world elevation data set:
image = LoadData(7)
MODIFICATION HISTORY:
Written by: David W. Fanning, 5 March 1999.
Added some additonal random data capability. 29 April 99. DWF
Added IMAGES keyword. 31 March 2000. DWF.
Fixed a problem with the CANCEL button. 25 Oct 2002. DWF.
Added new JPEG, DICOM, TIFF, and PGN images. 30 Oct 2002. DWF.
Modified old program units to work with IDL strict arrays. 29 June 2003. DWF
(See themis/thm_ui_new/utilities/loaddata.pro)
A program for loading data files used in the ITT VIS course
<i>Introduction to IDL</i>.
@param name {in}{required}{type=string} The name of a dataset, entered
as a string.
@keyword list {optional}{type=boolean} Set this keyword to return a list
of available datasets.
@returns A requested dataset.
@examples
<pre>
IDL> dem = load_data('lvdem')
IDL> isurface, dem
</pre>
@pre This file must be in the same directory as the course files.
@uses READ_ASOS, GET_INTRO_DIR
@requires IDL 5.3
@author Mike Galloy and Mark Piper, RSI, 2003
@history
2004-08, MP: Uses SOURCEROOT instead of SET_TRAINING_DIRECTORY
2005-10, MP: Added 'ladem' and 'laimage'
2005-10, MP: Replaced SOURCEROOT and <i>!training</i> with
GET_INTRO_DIR function
(See themis/thm_ui_new/utilities/load_data.pro)
NAME: makecolortable PURPOSE: makes the color table file for the themis gui CALLING SEQUENCE: makecolortable EFFECTS: overwrites the file themis/thm_ui_new/utilities/thm_gui_colors.tbl $LastChangedBy: pcruce $ $LastChangedDate: 2009-03-25 16:21:16 -0700 (Wed, 25 Mar 2009) $ $LastChangedRevision: 5417 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/makecolortable.pro $
(See themis/thm_ui_new/utilities/makecolortable.pro)
PRO: open_themis_document PURPOSE: opens a themis document Inputs: info: info struct from main gui event handler filename:name of the file nodelete:indicates that preexisting data should not be deleted during read Outputs: statuscode: negative value indicates failure, 0 indicates success statusmsg: a message to be returned in the event of an error $LastChangedBy: pcruce $ $LastChangedDate: 2010-02-16 13:33:25 -0800 (Tue, 16 Feb 2010) $ $LastChangedRevision: 7282 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/open_themis_document.pro $
(See themis/thm_ui_new/utilities/open_themis_document.pro)
PRO: open_themis_template PURPOSE: opens a themis template Inputs: filename:name of the file Outputs: statuscode: negative value indicates failure, 0 indicates success statusmsg: a message to be returned in the event of an error template: the template object $LastChangedBy: pcruce $ $LastChangedDate: 2009-09-14 15:08:45 -0700 (Mon, 14 Sep 2009) $ $LastChangedRevision: 6723 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/open_themis_template.pro $
(See themis/thm_ui_new/utilities/open_themis_template.pro)
NAME:
PICKCOLOR
PURPOSE:
A modal dialog widget allowing the user to select
the RGB color triple specifying a color. The return
value of the function is the color triple specifying the
color or the "name" of the color if the NAME keyword is set.
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
NOTE: This software has been heavily modified for usage by the THEMIS GUI. Please direct any errors to the TDAS software team
team and we will contact David Fanning, as necessary.
CATEGORY:
Graphics, Color Specification. See related program FSC_COLOR.
CALLING SEQUENCE:
color = PickColor(colorindex)
RETURN VALUE:
The return value of the function is a 1-by-3 array containing
the values of the color triple that specifies the selected color.
The color can be loaded, for example, in any color index:
color = PickColor(240)
TVLCT, color, 240
The return value is the original color triple if the user
selects the CANCEL button.
IF the NAMES keyword is set, the return value of the function is
the "name" of the selected color. This would be appropriate for
passing to the FSC_COLOR program, for example.
OPTIONAL INPUT POSITIONAL PARAMETERS:
COLORINDEX: The color index of the color to be changed. If not
specified the color index !D.Table_Size - 2 is used.
The Current Color and the Color Sliders are set to the
values of the color at this color index.
OPTIONAL INPUT KEYWORD PARAMETERS:
GROUP_LEADER: The group leader for this widget program. This
keyword is required for MODAL operation. If not supplied
the program is a BLOCKING widget. Be adviced, however, that
the program will NOT work if called from a blocking widget
program, unless a GROUP_LEADER is supplied.
NAMES: Set this keyword to return the "name" of the selected color
rather than its color triple.
STARTINDEX: 88 pre-determined colors are loaded The STARTINDEX
is the index in the color table where these 88 colors will
be loaded. By default, it is !D.Table_Size - 89.
TITLE: The title on the program's top-level base. By default the
title is "Pick a Color".
OPTIONAL INPUT KEYWORD PARAMETERS:
CANCEL: A keyword that is set to 1 if the CANCEL button is selected
and to 0 otherwise.
COMMON BLOCKS:
None.
MODIFICATION HISTORY:
Written by: David Fanning, 28 Oct 99.
Added NAME keyword. 18 March 2000, DWF.
Fixed a small bug when choosing a colorindex less than !D.Table_Size-17. 20 April 2000. DWF.
Added actual color names to label when NAMES keyword selected. 12 May 2000. DWF.
Modified to use 88 colors and FSC_COLOR instead of 16 colors and GETCOLOR. 4 Dec 2000. DWF.
Now drawing small box around each color. 13 March 2003. DWF.
Added CURRENTCOLOR keyword. 3 July 2003. DWF.
Switched to object graphics, eliminated side-effects. 25 Jan 2011 pcruce.
(See themis/thm_ui_new/utilities/pickcolor.pro)
NAME:
PICKCOLORNAME
PURPOSE:
The purpose of this program is to provide a blocking
or modal widget interface for selecting a color "name".
The program uses colors familiar to the FSC_COLOR program,
and is often used to select a color name for passing to FSC_COLOR.
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:
Graphics, Color Specification.
CALLING SEQUENCE:
colorName = PickColorName(startColorName)
OPTIONAL INPUT PARAMETERS:
startColorName: A string with the "name" of the color. Colors available are these:
Almond Antique White Aquamarine Beige Bisque Black
Blue Blue Violet Brown Burlywood Charcoal Chartreuse
Chocolate Coral Cornsilk Cyan Dark Goldenrod Dark Gray
Dark Green Dark Khaki Dark Orchid Dark Salmon Deep Pink Dodger Blue
Firebrick Forest Green Gold Goldenrod Gray Green
Green Yellow Honeydew Hot Pink Indian Red Ivory Khaki
Lavender Lawn Green Light Coral Light Cyan Light Gray Light Salmon
Light Yellow Lime Green Linen Magenta Maroon Medium Gray
Medium Orchid Moccasin Navy Olive Olive Drab Orange
Orange Red Orchid Pale Goldenrod Pale Green Papaya Peru
Pink Plum Powder Blue Purple Red Rose
Rosy Brown Royal Blue Saddle Brown Salmon Sandy Brown Sea Green
Seashell Sienna Sky Blue Slate Gray Snow Spring Green
Steel Blue Tan Thistle Tomato Turquoise Violet
Violet Red Wheat White Yellow
The color WHITE is used if this parameter is absent.
INPUT KEYWORD PARAMETERS:
BOTTOM: The colors used in the program must be loaded somewhere
in the color table. This keyword indicates where the colors
start loading. By default BOTTOM is set equal to !D.Table_Size-NCOLORS-1.
COLUMNS: Set this keyword to the number of columns the colors should
be arranged in.
FILENAME: The string name of an ASCII file that can be opened to read in
color values and color names. There should be one color per row
in the file. Please be sure there are no blank lines in the file.
The format of each row should be:
redValue greenValue blueValue colorName
Color values should be between 0 and 255. Any kind of white-space
separation (blank characters, commas, or tabs) are allowed. The color
name should be a string, but it should NOT be in quotes. A typical
entry into the file would look like this:
255 255 0 Yellow
GROUP_LEADER: This identifies a group leader if the program is called
from within a widget program. Note that this keyword MUST be provided
if you want to guarantee modal widget functionality. (If you don't know
what this means, believe me, you WANT to use this keyword, always.)
INDEX: This keyword identifies a color table index where the selected color
is to be loaded when the program exits. The default behavior is to restore
the input color table and NOT load a color.
TITLE: This keyword accepts a string value for the window title. The default
is "Select a Color".
OUTPUT KEYWORD PARAMETERS:
CANCEL: On exit, this keyword value is set to 0 if the user selected
the ACCEPT button. IF the user selected the CANCEL button, or
closed the window in any other way, this keyword value is set to 1.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Colors are loaded in the current color table. The input color table
is restored when the program exits. This will only be noticable on
8-bit displays. The startColorName is returned if the user cancels
or destroys the widget before a selection is made. Users should
check the CANCEL flag before using the returned color.
EXAMPLE:
To call the program from the IDL comamnd line:
IDL> color = PickColorName("red") & Print, color
To call the program from within a widget program:
color = PickColorName("red", Group_Leader=event.top) & Print, color
MODIFICATION HISTORY:
Written by: David Fanning, 31 August 2000.
Modified program to read colors from a file and to use more
colors on 24-bit platforms. 16 October 2000. DWF.
Added the COLUMNS keyword. 16 October 2000. DWF.
Fixed a small problem with mapping a modal widget. 2 Jan 2001. DWF
Now drawing small box around each color. 13 March 2003. DWF.
(See themis/thm_ui_new/utilities/pickcolorname.pro)
NAME:
PROGRESSBAR__DEFINE
PURPOSE:
Creates a simple progress bar for indicating the progess of a looping
operation in IDL.
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:
progressBar = Obj_New("PROGRESSBAR")
ARGUMENTS:
None.
KEYWORDS:
BACKGROUND: The name of the background color of the progress bar. By default, "black".
COLOR: The name of the color for the progress bar. By default: "red".
Possible color names are those defined by FSC_COLOR:
Almond Antique White Aquamarine Beige Bisque Black
Blue Blue Violet Brown Burlywood Charcoal Chartreuse
Chocolate Coral Cornsilk Cyan Dark Goldenrod Dark Gray
Dark Green Dark Khaki Dark Orchid Dark Salmon Deep Pink Dodger Blue
Firebrick Forest Green Gold Goldenrod Gray Green
Green Yellow Honeydew Hot Pink Indian Red Ivory Khaki
Lavender Lawn Green Light Coral Light Cyan Light Gray Light Salmon
Light Yellow Lime Green Linen Magenta Maroon Medium Gray
Medium Orchid Moccasin Navy Olive Olive Drab Orange
Orange Red Orchid Pale Goldenrod Pale Green Papaya Peru
Pink Plum Powder Blue Purple Red Rose
Rosy Brown Royal Blue Saddle Brown Salmon Sandy Brown Sea Green
Seashell Sienna Sky Blue Slate Gray Snow Spring Green
Steel Blue Tan Thistle Tomato Turquoise Violet
Violet Red Wheat White Yellow
FAST_LOOP: Set this keyword if what you are doing in the loop doesn't involve
any color operations and you want the progress bar to update as fast
as possible. With this keyword set, the program will eliminate extra
calls to FSC_COLOR, which can be slow if you are calling it, say,
10,000 times!
GROUP_LEADER: The group leader for the progress bar.
NOCANCEL: Set this keyword to eliminate the CANCEL button from the progres bar.
PERCENT: The initial percent on the progress bar. Used only if the START keyword is
also set.
START: Set this keyword if you wish to call the START method immediately upon initialization.
TEXT: The textual message that goes above the progress bar. By default:
"Operation in progress..."
TITLE: The title of the progress bar window. By default: "Progress Bar".
XSIZE: The X size of the progress bar itself. By default, 150 pixels.
YSIZE: The Y size of the progress bar itself. By default, 10 pixels.
PROCEDURE:
The user is responsible for starting, updating, checking for CANCEL events, and
destroying the progress indicator. The sequence of commands might look
like this:
progressBar = Obj_New("PROGRESSBAR")
progressBar -> Start
FOR j=0,9 DO BEGIN
IF progressBar -> CheckCancel() THEN BEGIN
ok = Dialog_Message('The user cancelled operation.')
RETURN
ENDIF
Wait, 0.5 ; Would probably be doing something ELSE here!
progressBar -> Update, (j+1)*10
ENDFOR
progressBar -> Destroy
See the example program at the end of this file for a working example of code.
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 progress bar widgets as well as the object.
progressBar -> Destroy
GETPROPERTY: Gets certain properties of the object.
progressBar -> GetProperty, Color=currentColor
SETPROPERTY: Allows the user to set certain properties of the object.
progressBar -> SetProperty, Color='green'
START: Puts the progress bar on the display and enables it to receive events.
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. Can optional specify TEXT that is displayed above the progress
bar.
progressBar -> Update, 50
progressBar -> Update, 50, Text='Operation 50% completed...'
EXAMPLE:
See the example program at the bottom of this file.
RESTRICTIONS:
Note that the progress bar cannot be run as a MODAL widget program and
still capture CANCEL button events. Thus, the user *may* be able to generate events
in the calling program while this progress bar is in operation.
DEPENDENCIES:
This program requires FSC_COLOR from the Coyote Library:
http://www.dfanning.com/programs/fsc_color.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 19 September 2002.
Added TEXT keyword to Update method. 12 Nov 2002. DWF.
Added FAST_LOOP keyword. 19 Dec 2002. DWF.
Fixed a problem in where I was checking for CANCEL button event. 2 April 2003. DWF.
Removed the XMANAGER call in the START method, since it wasn't needed. 7 October 2003. DWF.
General maintenance updates. Added START keyword to INIT method to allow immediate
starting upon initialization. Added better error handling and checking. 10 October 2003. DWF.
Added ACCEPT button and CheckButton method. Modified Example program to demonstrate new
functionality. 1 December 2003. DWF.
Added XOFFSET and YOFFSET keywords. 4 March 2004. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Added keyword keyword TITLE to Update method. 23 Feb 2005. Benjamin Hornberger
Added BACKGROUND keyword. 22 Dec 2006. DWF.
Added RETAIN=1 keyword to Widget_Draw command. 9 Dec 2007. DWF.
(See themis/thm_ui_new/utilities/progressbar__define.pro)
NAME:
saveas_ascii.pro
PURPOSE:
Saves THEMIS Loaded Data variables in ASCII format.
INPUT & KEYWORDS:
loadedData: THEMIS GUI loaded data object
timefmt: Index specifying which format to use for time quantities.
(passed to formatannotation.pro)
fmt_code: Index specifying which format to use for data.
; (passed to formatannotation.pro)
timeStringFmt: String specifying a custom time format.
See TFORMAT keyword for time_string.pro for usage.
This keyword will override TIMEFMT.
local_time: Flag to use local time instead of UTC, only valid if
used with TIMESTRINGFMT
OTHER:
Documentation for this procedure is incomplete.
(See themis/thm_ui_new/utilities/saveas_ascii.pro)
PRO: save_document PURPOSE: saves a themis document Inputs: windowstorage: windowstorage object storing the draw tree to be save filename:name of the file Outputs: statuscode: negative value indicates failure, 0 indicates success statusmsg: a message to be returned in the event of an error $LastChangedBy: pcruce $ $LastChangedDate: 2009-09-14 14:58:32 -0700 (Mon, 14 Sep 2009) $ $LastChangedRevision: 6722 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/save_document.pro $
(See themis/thm_ui_new/utilities/save_document.pro)
PRO: save_themis_template PURPOSE: saves a themis template Inputs: template:the template object to be saved filename:name of the file Outputs: statuscode: negative value indicates failure, 0 indicates success statusmsg: a message to be returned in the event of an error $LastChangedBy: pcruce $ $LastChangedDate: 2009-09-14 14:58:32 -0700 (Mon, 14 Sep 2009) $ $LastChangedRevision: 6722 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/save_themis_template.pro $
(See themis/thm_ui_new/utilities/save_themis_template.pro)
This procedure returns the directory path associated with
the routine calling this function. This is useful for
building applications that need to bootstrap resource and
configuration files when the installation directory may not
be known until run time. Use this function in conjunction
with FILEPATH to build platform-independent file path strings
to your resources. <br>
For example, <pre>
b = WIDGET_BUTTON(tlb, /BITMAP, $
VALUE=FILEPATH('up.bmp', ROOT = SourcePath(), SUBDIR = ['resource'])</pre>
This will search for a file named "up.bmp" in the subdirectory named
"resource" below the directory in which is located the source code
(or SAVE file) for the routine containing the above statement.
@Keyword
Base_Name {out}{optional}{type=string}
Set this keyword to a named variable to retrieve the
base file name of the routine's source.
@Returns
The return value is the root directory path to
the calling routine's source file or SAVE file.
@Examples <pre>
Create a file myapp.pro with the contents and run it.
PRO MYAPP
PRINT, SourcePath()
END
The printed output will be the full path to the
directory in which abc.pro was created, regardless of
IDL's current working directory.</pre>
@History
03/18/2005 JLP, RSI - Original version
(See themis/thm_ui_new/utilities/sourcepath.pro)
The SOURCEROOT function, in combination with
FILEPATH, allows a program to locate other
files within a routine source file's related
directory tree.
<p>
For example, an IDL routine file named
C:\myapp\abc.pro calls SOURCEROOT as in
<p>
<pre>
PRO ABC
PRINT, SOURCEROOT()
END
</pre>
the resulting output will be the string "C:\myapp".
<p>
If data associated with the application are in
C:\myapp\mydata, a data file in this directory
can be located via
<p>
<pre>
IDL> datafile = FilePath('data.dat',$
IDL> ROOT=SourceRoot(), $
IDL> SUBDIR=['data'])
</pre>
The programmer can distribute the application
to another user who may install the original directory tree
into "D:\app".
No code modifications would be required for this
user to successfully locate the data.dat file.
<p>
If the routine ABC were compiled and saved to
an IDL SAVE file and distributed, the SOURCEROOT
function will return the path to the SAVE file
instead.
@author Jim Pendleton
(See themis/thm_ui_new/utilities/sourceroot.pro)
Function: stringIsNum
Purpose: Determines if a given string is a number or not.
Inputs: str : the string to be checked
Output: Returns 1 if yes, or if no
EXAMPLES:
if stringIsNum(s) then print, strtrim(double(s),2)
% Compiled module: STRINGISNUM.
THEMIS> print,stringisnum('hello')
0
THEMIS> print,stringisnum('1.234')
1
THEMIS> print,stringisnum('1.234e4')
1
THEMIS> print,stringisnum('1B')
1
THEMIS> print,stringisnum(' 1 ')
1
THEMIS> print,stringisnum(' 1Hello ')
0
THEMIS> print,stringisnum(' 1D ')
1
THEMIS> print,stringisnum(' Hello ')
0
Notes: String must be only a numerical string and leading or trailing whitespace
if true is to be returned. Strings that include other non-numerical characters
will return false even if they have numerical sub-strings.
$LastChangedBy: pcruce $
$LastChangedDate: 2008-11-18 09:39:45 -0800 (Tue, 18 Nov 2008) $
$LastChangedRevision: 3994 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/stringisnum.pro $
(See themis/thm_ui_new/utilities/stringisnum.pro)
NAME: thm_ui_check_overlap PURPOSE: Determins if any panels on the current page are overlapping. Prints message notifying user of those panels. CALLING SEQUENCE: bool = thm_ui_check_overlap( panels, cwindow ) INPUT: panels: Array of current panel objects cwindow: Current window(page) object OUTPUT: 1 if overlaps are found, 0 otherwise HISTORY:
(See themis/thm_ui_new/utilities/thm_ui_check_overlap.pro)
NAME: thm_ui_cleanup_tplot
PURPOSE:
Abstracts the oft-repeated operation which identifies new tplot variables,
and identifies variables that should be deleted
CALLING SEQUENCE:
tnames_before = tnames('*',create_time=cn_before)
thm_load_state ;some operation
thm_ui_cleanup_tplot,tnames_before,create_time_before=cn_before,del_vars=del_vars,new_vars=new_vars
Inputs:
tnames_before: a list of tplot names from before the operation in question
Keywords:
create_time_before(optional,input): This is an array of the create times associated with tnames_before
This argument is only required if you want the list of new_vars
new_vars(output): This will output an array of new tplot variable names, if create_time_before was specified
del_vars(output): This will output an array of tplot variable names to delete.
Note:
The list of new variables and delete variables is generally not the same. Delete variables contains only names
that did not exist before the operation, whereas new variables may contain names that pre-existed but were overwritten
$LastChangedBy: pcruce $
$LastChangedDate: 2009-06-11 12:04:38 -0700 (Thu, 11 Jun 2009) $
$LastChangedRevision: 6135 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_cleanup_tplot.pro $
(See themis/thm_ui_new/utilities/thm_ui_cleanup_tplot.pro)
NAME:
THM_UI_COMBOBOX
PURPOSE:
IDL combobox doesn't actually support null strings('') as entries
in the combobox. Entering a null string will generate an error that halts
execution. This is a simple wrapper compound widget to fix this problem
by making the box appear empty when it is not.
CALLING SEQUENCE:
Result = THM_UI_COMBOBOX
KEYWORD PARAMETERS:
Exactly the same as normal combobox
EVENT STRUCTURE:
The same as normal combobox, with the exception that the
event structure is called 'THM_UI_COMBOBOX'
(See themis/thm_ui_new/utilities/thm_ui_combobox.pro)
NAME:
thm_ui_data_minmax
PURPOSE:
Returns a two-element array containing the mininum and maximum values
contained in the loadedData quantity specified by the NAME positional
parameter.
CALLING SEQUENCE:
minmax = thm_ui_data_minmax(loadedData, options)
INPUT:
loadedData: The loadedData object.
name: The name of the variable (a string).
KEYWORDS:
none
OUTPUT:
[minRange, maxRange]: A two-element array containing the mininum and maximum
values of the quantity specified by the NAME parameter.
(See themis/thm_ui_new/utilities/thm_ui_data_minmax.pro)
Name: THM_UI_DIALOG_PICKFILE_SAVE_WRAPPER
Purpose: Wrapper for the IDL routine dialog_pickfile. Checks for invalid characters in the filename.
Inputs: Any keywords that need to be passed on to dialog_pickfile (see note 1 below for special cases)
Output: Filename ('' if dialog is cancelled)
NOTE:
1. This routine should not be used if the multiple_files keyword is being passed to dialog_pickfile
as ';' will be flagged as invalid if used to separate file names.
2. This routine doesn't check for all characters that can cause problems on windows. A large number of cases
are already screened by dialog_pickfile on windows (cases that cause no problems on linux).
$LastChangedBy: lphilpott $
$LastChangedDate: 2012-03-08 15:18:36 -0800 (Thu, 08 Mar 2012) $
$LastChangedRevision: 10004 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_dialog_pickfile_save_wrapper.pro $
(See themis/thm_ui_new/utilities/thm_ui_dialog_pickfile_save_wrapper.pro)
NAME: thm_ui_do_nudge PURPOSE: Abstracted nudge data operation CALLING SEQUENCE: thm_ui_do_nudge, INPUT: gui_id = widget id of the widget that called this program info = the info structure of the Main GUI OUTPUT: fail=fail HISTORY: $LastChangedBy: jwl $ $LastChangedDate: 2011-02-16 15:15:02 -0800 (Wed, 16 Feb 2011) $ $LastChangedRevision: 8231 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_do_nudge.pro $
(See themis/thm_ui_new/utilities/thm_ui_do_nudge.pro)
FUNCTION: thm_ui_getlengthvars PURPOSE: helper function for formatannotation Inputs: Example: $LastChangedBy: pcruce $ $LastChangedDate: 2009-04-13 14:51:02 -0700 (Mon, 13 Apr 2009) $ $LastChangedRevision: 5609 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_getlengthvars.pro $
(See themis/thm_ui_new/utilities/thm_ui_getlengthvars.pro)
NAME:
thm_ui_interpolate
PURPOSE:
Interpolates over x-axis of active data and adds new data to
loaded data object. Intended to be called from thm_ui_new_dproc.
CALLING SEQUENCE:
thm_ui_interpolate, result, loadedData, historywin, statusbar
INPUT:
loadedData: Loaded data object.
historywin: History window reference.
statusbar: Status bar reference.
guiid: If set and valid, will make user queries part of GUI widget hierarchy.
result: Anonymous structure returned by thm_ui_interpol_options:
{
num: Number of points for the result when not matching.
cad: Cadence of the result when using that option
match: Flag indicating to interpolate to another variable's abcissa.
matchto: Group name of variable to match to.
extrap: Flags for extrapolation type: [none, last value, NaN]
suffix: Suffix to create new data group with.
limit: Flag indicating time limits.
trange: Time range array containing desired time limits.
type: Flags for interpolation type: [linear,quadratic,lsquadratic,spline]
ntype: Flag to use number or cadence (0,1 respectively)
ok: (not used) Indicates thm_ui_interpol_options was successful
}
HISTORY:
(See themis/thm_ui_new/utilities/thm_ui_interpolate.pro)
A procedure to match the background color of a bitmap to that of the OS GUI. Will be used to match icon backgrounds INPUT bitmap_array : three dimensional byte array representing an RGB bitmap image; read_bmp(<img>,/rgb) topbase : the top base widget of window housing the bitmap/widget
(See themis/thm_ui_new/utilities/thm_ui_match_background.pro)
NAME: thm_ui_newline PURPOSE: Returns a cross-platform newline character. Specifically, used in the dialog_message boxes, which tend to print junk characters if character 13 is used on non-windows platforms CALLING SEQUENCE: newline = thm_ui_newline() string = line1 + thm_ui_newline() + line2 INPUT: none OUTPUT: Newline character HISTORY: $LastChangedBy: lphilpott $ $LastChangedDate: 2011-05-31 14:16:44 -0700 (Tue, 31 May 2011) $ $LastChangedRevision: 8713 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_newline.pro $
(See themis/thm_ui_new/utilities/thm_ui_newline.pro)
This program creates a string for the history array when multiple datatypes, spacecraft or stations are chosen, for use in the themis_w_event routine $LastChangedBy: bckerr $ $LastChangedDate: 2008-10-03 11:35:33 -0700 (Fri, 03 Oct 2008) $ $LastChangedRevision: 3615 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_new_multichoice_history.pro $
(See themis/thm_ui_new/utilities/thm_ui_new_multichoice_history.pro)
NAME:
thm_ui_new_pwrspc
PURPOSE:
Creates power spectra from GUI variables that are active in the Process Data
window and loads the spectra into the loadedData object. Directly calls
PWRSPC and DPWRSPC to create the spectra. Intended to be called from
THM_UI_NEW_DPROC.
CALLING SEQUENCE:
thm_ui_new_pwrspc, options,invars, loadedData, historyWin, statusBar,guiID
INPUT:
options: Structure that is output from THM_UI_PWRSPC_OPTIONS containing
keyword options for PWRSPC and DPWRSPC.
loadedData: The loadedData object.
historyWin: The history window object.
statusBar: The status bar object for the Data Processing window.
guiid: The widget id for the GUI so that it can display prompts with the correct layering.
KEYWORDS:
OUTPUT:
none
(See themis/thm_ui_new/utilities/thm_ui_new_pwrspc.pro)
Purpose: To make mission overview plots of all instruments
Inputs: PROBES: spacecraft ('a','b','c','d','e')
DATE: the date string or seconds since 1970 ('2007-03-23')
DUR: duration (default units are days)
DAYS: redundant keyword to set the units of duration (but its comforting to have)
HOURS: keyword to make the duration be in units of hours
DEVICE: sets the device (x or z) (default is x)
MAKEPNG: keyword to generate 5 png files
DIRECTORY: sets the directory where the above pngs are placed (default is './')
DONT_DELETE_DATA: keyword to not delete all existing tplot variables before loading data in for
the overview plot (sometimes old variables can interfere with overview plot)
WARNING:
Any code that requires windowStorage or loadedData should be put in the "~keyword_set(no_draw)" block.
thm_ui_overplot is called without valid values for these parameters during document load
Example: thm_gen_overplot,probe='a',date='2007-03-23',dur=1
The above example will produce a full day plot in the X window.
Version:
$LastChangedBy: pcruce $
$LastChangedDate: 2012-01-27 15:41:20 -0800 (Fri, 27 Jan 2012) $
$LastChangedRevision: 9643 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_overplot.pro $
(See themis/thm_ui_new/utilities/thm_ui_overplot.pro)
Purpose: Wrapper to thm_part_getspec, to be called during replay by thm_ui_call_sequence Modularizes
some operations.
Inputs: probe,$ ;standard getspec arguments
dtype,$
trange, $
start_angle,$
suffix,$
angle, $
phi,$
theta,$
pitch,$
gyro, $
erange,$
energy,$
regrid, $
other_dim,$
normalize,$
datagap, $
mask_remove,$
method_sunpulse_clean, $
limit_sunpulse_clean, $
fillin_method, $
statusbar,$
historyWin,$
loadedData
Version:
$LastChangedBy: pcruce $
$LastChangedDate: 2009-06-12 15:48:10 -0700 (Fri, 12 Jun 2009) $
$LastChangedRevision: 6185 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_part_getspec_replay.pro $
(See themis/thm_ui_new/utilities/thm_ui_part_getspec_replay.pro)
NAME:
thm_ui_prompt_widget.pro
PURPOSE:
Simple standardized popup, for yes/no,yes_to_all,no_to_all,cancel
Like dialog_message, but allows additional options, and automatically logs/prompts
CALLING SEQUENCE:
result = thm_ui_prompt_widget(parent,statusbar,historywin,"Continue?")
INPUT:
parent: Widget Id of parent widget(Note that if parent is invalid, it will block until a response is received. See documentation for XMANAGER:NO_BLOCK keyword)
statusBar: The statusbar object to which output should be sent, if unavailable pass null object(obj_new())
historywin: The historywin object to which output should be sent if unavailable pass null object(obj_new())
promptText=promptText: The text of the prompt to be displayed to the user.
no=no :Include "No" Button
yes=yes: Include "Yes" Button
allno=allno: Include "No To All" button.
allyes=allyes: Include "Yes To All" button.
cancel=cancel: Include "Cancel" button.
ok=ok: Include "Ok" button.
maxwidth=maxwidth: Control the width at which the prompt starts wrapping prompt text.
defaultValue=defaultValue: Set to string to return as default. (Occurs during error or close by clicking "X")
Normally default is value of right-most button.
title=title: Set window title to string.
traceback=traceback: Do a trace to calling location
OUTPUT:
Returns an all lower case string with the response text:
"no","yes","yestoall","notoall","cancel","ok"
NOTES:
1. If no button keywords are set, "ok" is used.
2. Based heavily on deprecated gui load subroutine: thm_ui_load_clob_prompt:
3. If a parent widget is unavailable, statusbar, or historywin unavailable, you can pass null values
result = thm_ui_prompt_widget(0l,obj_new(),obj_new(),prompt="Continue?")
This call will interact with other widgets in a way that is similar to a call to error_message
HISTORY:
(See themis/thm_ui_new/utilities/thm_ui_prompt_widget.pro)
NAME:
thm_ui_req_slp
PURPOSE:
Determines availablity of solar/lunar ephemeris data.
CALLING SEQUENCE:
General:
bool = thm_ui_req_spin(inCoord,outCoord,trange,loadedData)
Example:
if thm_ui_req_spin(inCoord,outCoord,trange,loadedData) then begin
thm_load_slp,datatype='all',trange=trange
endif
INPUT:
inCoord: string storing the destination coordinate system (e.g. 'gse')
outCoord: string storing the destination coordinate system (e.g. 'sse')
trange: two element arraw storing the time range
loadedData: gui loadedData object reference
OUTPUT:
Returns boolean: 1 if required data is not present or does not cover
the time range, 0 otherwise.
NOTES:
This code assumes that only explicit transformations into the
coordinates in question will require slp data.
(See themis/thm_ui_new/utilities/thm_ui_req_slp.pro)
NAME: thm_ui_req_spin PURPOSE: Determines availability of parameters for spin model. CALLING SEQUENCE: if thm_ui_req_spin((coordSys,value,probe,trange,loadedData) then begin thm_load_state,probe=probe,trange=trange,/get_support endif INPUT: value: a string storing the destination coordinate system active: the set of variables to be transformed loadedData: the loadedData object sobj: the status bar object to which messages should be sent silent(optional): set this keyword to suppress popup messages.(Used during replay) OUTPUT: none SIDE EFFECT: New active variable for each prior active stored in loaded data and transformed into the new coordinate system with suffix added/changed HISTORY: $LastChangedBy: jwl $ $LastChangedDate: 2011-05-09 11:27:59 -0700 (Mon, 09 May 2011) $ $LastChangedRevision: 8659 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_req_spin.pro $
(See themis/thm_ui_new/utilities/thm_ui_req_spin.pro)
NAME: thm_ui_run_calc PURPOSE: Function that interprets program for thm_ui_calculate CALLING SEQUENCE: thm_ui_run_calc,programtext,loadeddata,historywin,statusbar,fail=fail INPUT: programText: array of strings, text of program loadeddata: the loaded data object historywin: the historywin object statusbar: the statusbar object OUTPUT: fail=fail: set to named variable, will be 1 if an error occurs during processing. HISTORY: $LastChangedBy: pcruce $ $LastChangedDate: 2009-06-11 13:47:09 -0700 (Thu, 11 Jun 2009) $ $LastChangedRevision: 6146 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_run_calc.pro $
(See themis/thm_ui_new/utilities/thm_ui_run_calc.pro)
NAME:
thm_ui_set_cursor
PURPOSE:
Replaces the cursor on non-windows machines
CALLING SEQUENCE:
thm_ui_set_cursor,win
INPUT:
win: an IDLgrWindow
OUTPUT:
HISTORY:
$LastChangedBy: pcruce $
$LastChangedDate: 2009-04-21 09:43:43 -0700 (Tue, 21 Apr 2009) $
$LastChangedRevision: 5703 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_set_cursor.pro $
(See themis/thm_ui_new/utilities/thm_ui_set_cursor.pro)
Procedure: thm_ui_set_symbol
Purpose:
1) Set the user defined plotting symbol to be used with psym=8,
or
2) Return a graphics object of the desired symbol
Calling Sequence:
thm_ui_set_symbol, index [,fill=fill] [,size=size] [,fail=fail]
[,object=object, [,obj_size=obj_size] [,color=color]]
Arguments:
INDEX: Number of the symbol that is desired:
1: Plus sign
2: Star
3: Circle
4: Diamond
5: Triangle
6: Square
7: X
FILL: Flag to fill the symbol (solid)
SIZE: Number specifying the size of the symbol (default=1.0)
(not valid if used with OBJECT)
OBJECT: If called this keyword will return an IDLgrSymbol object
of the requested type
OBJ_SIZE: Two element array specifying symbol obj's x and y size
COLOR: The color used to draw the symbol; may be specified as an
index or as a three-element vector [red, green, blue].
FAIL: This keword will contain a message if any errors are encountered
Examples:
Set to a filled circle:
thm_ui_set_symbol, 3, /fill
Set to an large, unfilled triangle:
thm_ui_set_symbol, 5, size = 5
Get IDLgrSymbol for a filled diamond:
thm_ui_set_symbol, 4, obj=obj, /fill
Caveats:
Non-fillable symbols such as Asterisks and Plus Signs will not
return graphics objects if /fill is set.
Other:
This routine was primarily developed as a method of drawing
filled symbols; however, any number of custom symbols may be added
by specifying the x and y variables in the main case statment.
(See themis/thm_ui_new/utilities/thm_ui_set_symbol.pro)
NAME:
THM_UI_SPINNER
PURPOSE:
A compound 'spinner' widget for editing numerical values.
Consists of up and down buttons and a text field for display
and direct editing.
CALLING SEQUENCE:
Result = SPINNER(parent)
KEYWORD PARAMETERS:
INCREMENT: Numerical ammount spinner value is incremented/decremented
LABEL: Text label for spinner
SPIN_TIME: Delay before 'spinning'
UNITS: Units (text) to appear to the right of the value
VALUE: Initial value
XLABELSIZE: Size of the text label
TEXT_BOX_SIZE: Size (in char) of the text box
TOOLTIP: Tooltip (text)
MAX_VALUE: The maximum allowed value for the spinner (optional)
MIN_VALUE: The minimum allowed value for the spinner (optional)
EVENT STRUCTURE:
When the field is modified (either directly) or by the
up/down buttons, the following event is returned:
{ID: id, TOP: top, HANDLER: handler, VALUE: value, VALID: valid}
VALUE: formatted, double precision number from widget's text field;
value is NaN when the text widget contains an unrecognizable
or unconvertable number
VALID: 0 if value is not a recogizable/convertable number, or if buttons
attempt to go outside min/max range, 1 otherwise
GETTING/SETTINGS VALUES
Using get_value from widget_control will return the same as the VALUE
field in the event structure.
The set_value procedure expects numerical input (e.g. doubles, floats, ints).
Use thm_ui_spinner_set_max_value/thm_ui_spinner_set_min_value to change max_value, min_value.
thm_ui_spinner_get_max_value/thm_ui_spinner_get_min_value return MAX_VALUE, MIN_VALUE
NOTES:
(lphilpott 06/10/11)
Setting the max_value and min_value will restrict the use of the up and down buttons
to reach values outside that range.
They do not impact on values that are typed into the text field (these
should be handled by the calling function) or any values simply passed to the set_value procedure.
(lphilpott 06/15/11)
Use of VALID: VALID=0 if the event is not valid. This includes non-recognizable
numbers but ALSO cases where the user tries to go outside the allowed min-max range using up and down buttons.
If the user clicks the up/down button and reaches the limit, the value returned is the limit value and valid=0.
If the user enters a non numerical value the value returned is NAN and valid=0
This allows the calling procedure to issue messages to the user such as invalid entry based on both VALUE and VALID.
Note: valid = 0 only if the starting value of the spinner is at the bounds. If the user holds down the buttons and reaches
the bounds valid = 1. This avoids problems where existing code processes events only if event.valid = 1.
I have not used max and min to restrict values typed into the field due to the difficulty of knowing when the user
has finished typing - do not want to reset the value while the user is still entering it.
When using a spinner cases where the user types in a value outside the allowed range need to be handled, also
invalid entries. If necessary warning messages should be issued to user when they use the up/down buttons and have
reached the allowed limits.
Added get and set procedures for min and max designed to be called externally, eg. thm_ui_spinner_set_max_value
Idea is to allow max and min to be set in case they need to be changed after spinner is created (e.g for range spinners where allowed values
depend on whether scaling is linear or log)
(See themis/thm_ui_new/utilities/thm_ui_spinner.pro)
NAME:
thm_ui_time_widget.pro
PURPOSE:
Compound widget used to generate standardized time selection ui,
for all tabs in the load data window.
CALLING SEQUENCE:
widgetid = thm_ui_time_widget(parent,statusBar,historyWin,timeRangeObj=timeRangeObj,uvalue=uvalue,uname=uname, oneday=oneday)
INPUT:
parent: ID of base in which compound widget will sit
statusBar: statusBar Object for reporting errors and user info
historywin: historywin object for reporting errors and user info
timeRangeObj: a thm_ui_time_range storing the range that will be used.
If provided, the compound widget will mutate this object
uvalue: Assign a user value to this widget
uname: assign a user name to this widget
oneday: flag to determine whether the range is fixed to one day
OUTPUT:
This widget's id
NOTES:
1. Returns events of the form:
return_struct = {time_widget,id:0l,top:0l,handler:0l,timerange:obj_new(),error:0}
2. Can use get_value and set_value keywords with widget control, to return the time range object
that this compound widget mutates.
HISTORY:
(See themis/thm_ui_new/utilities/thm_ui_time_widget.pro)
FUNCTION: thm_ui_usingexponent PURPOSE: Used to determine if any of a set of inputs will be put into exponential notation Inputs: The data struct is an input to format annotation data.exponent values: 0: autoformat 1: decimal 2: scientific 3: base^x Outputs: Determine format type:
(See themis/thm_ui_new/utilities/thm_ui_usingexponent.pro)
PRO: thm_ui_validate_file PURPOSE: Verifies file read/write permissions and file availability Inputs: filename:name of the file Outputs: statuscode: negative value indicates failure, 0 indicates success statusmsg: a message to be returned in the event of an error Keywords: write: validate for save $LastChangedBy: pcruce $ $LastChangedDate: 2009-09-14 14:58:32 -0700 (Mon, 14 Sep 2009) $ $LastChangedRevision: 6722 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_validate_file.pro $
(See themis/thm_ui_new/utilities/thm_ui_validate_file.pro)
NAME:
thm_ui_wavelet
PURPOSE:
wavelet transform of the input tplot variables, fist calls split_vec
to split up any multi-component vectors.
CALLING SEQUENCE:
thm_ui_wavelet, vnames, new_names, polar=polar,_extra=_extra
INPUT:
vnames = the tplot variable names to transform
OUTPUT:
new_names = new variable names generated by the process
KEYWORDS:
polar = if set, passes the /polar keyword into the split_vec
procedure, new variable names for 3-d data will be polar,
and not '_x','_y','_z'
gui_id = the main GUI widget ID, for messages
messw_id = the dproc widget id, for messages
temp_names = the names of temporary variables create by the process
so that they can be reliably removed
maxpoints = the maximum number of time samples in the original data
(default = 2^15 if not set)
HISTORY:
12-mar-2007, jmm, jimm@ssl.berkeley.edu
5-jun-2007, jmm, no longer handles history
7-may-2008, W. Michael Feuerstein, Test for >= 2 finite points.
11-may-2009,prc(pcruce@igpp.ucla.edu) added keyword to return the names of temporary variables created in process
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-26 15:01:41 -0800 (Thu, 26 Jan 2012) $
$LastChangedRevision: 9619 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_ui_wavelet.pro $
(See themis/thm_ui_new/utilities/thm_ui_wavelet.pro)
NAME:
TVIMAGE
PURPOSE:
This purpose of TVIMAGE is to enable the TV command in IDL
to be a completely device-independent and color-decomposition-
state independent command. On 24-bit displays color decomposition
is always turned off for 8-bit images and on for 24-bit images.
The color decomposition state is restored for those versions of
IDL that support it (> 5.2). Moreover, TVIMAGE adds features
that TV lacks. For example, images can be positioned in windows
using the POSITION keyword like other IDL graphics commands.
TVIMAGE also supports the !P.MULTI system variable, unlike the
TV command. TVIMAGE was written to work especially well in
resizeable graphics windows. Note that if you wish to preserve
the aspect ratio of images in resizeable windows, you should set
the KEEP_ASPECT_RATIO keyword, described below. TVIMAGE works
equally well on the display, in the PostScript device, and in
the Printer and Z-Graphics Buffer devices. The TRUE keyword is
set automatically to the correct value for 24-bit images, so you
don't need to specify it when using TVIMAGE.
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:
Graphics display.
CALLING SEQUENCE:
TVIMAGE, image
INPUTS:
image: A 2D or 3D image array. It should be byte data.
x : The X position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
If the Y position is not used, X is taken to be the image
"position" in the window. See the TV command documenation
for details.
y : The Y position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
KEYWORD PARAMETERS:
BACKGROUND: This keyword specifies the background color. Note that
the keyword ONLY has effect if the ERASE keyword is also
set or !P.MULTI is set to multiple plots and TVIMAGE is
used to place the *first* plot.
ERASE: If this keyword is set an ERASE command is issued
before the image is displayed. Note that the ERASE
command puts the image on a new page in PostScript
output.
_EXTRA: This keyword picks up any TV keywords you wish to use.
HALF_HALF: If set, will tell CONGRID to extrapolate a *half* row
and column on either side, rather than the default of
one full row/column at the ends of the array. If you
are interpolating images with few rows, then the
output will be more consistent with this technique.
This keyword is intended as a replacement for
MINUS_ONE, and both keywords probably should not be
used in the same call to CONGRID.
KEEP_ASPECT_RATIO: Normally, the image will be resized to fit the
specified position in the window. If you prefer, you can
force the image to maintain its aspect ratio in the window
(although not its natural size) by setting this keyword.
The image width is fitted first. If, after setting the
image width, the image height is too big for the window,
then the image height is fitted into the window. The
appropriate values of the POSITION keyword are honored
during this fitting process. Once a fit is made, the
POSITION coordiates are re-calculated to center the image
in the window. You can recover these new position coordinates
as the output from the POSITION keyword.
MARGIN: A single value, expressed as a normalized coordinate, that
can easily be used to calculate a position in the window.
The margin is used to calculate a POSITION that gives
the image an equal margin around the edge of the window.
The margin must be a number in the range 0.0 to 0.333. This
keyword is ignored if the POSITION or OVERPLOT keywords are
used. It is also ignormed when TVImage is executed in a
multi-plot window, EXCEPT if it's value is zero. In this
special case, the image will be drawn into its position in
the multi-plot window with no margins whatsoever. (The
default is to have a slight margin about the image to separate
it from other images or graphics.
MINUS_ONE: The value of this keyword is passed along to the CONGRID
command. It prevents CONGRID from adding an extra row and
column to the resulting array, which can be a problem with
small image arrays.
NOINTERPOLATION: Setting this keyword disables the default bilinear
interpolation done to the image when it is resized. Nearest
neighbor interpolation is done instead. This is preferred
when you do not wish to change the pixel values of the image.
This keyword must be set, for example, when you are displaying
GIF files that come with their own non-IDL color table vectors.
NORMAL: Setting this keyword means image position coordinates x and y
are interpreted as being in normalized coordinates. This keyword
is only valid if the TV keyword is set.
OVERPLOT: Setting this keyword causes the POSITION keyword to be ignored
and the image is positioned in the location established by the
last graphics command. For example:
Plot, Findgen(11), Position=[0.1, 0.3, 0.8, 0.95]
TVImage, image, /Overplot
POSITION: The location of the image in the output window. This is
a four-element floating array of normalized coordinates of
the type given by !P.POSITION or the POSITION keyword to
other IDL graphics commands. The form is [x0, y0, x1, y1].
The default is [0.0, 0.0, 1.0, 1.0]. Note that this can
be an output parameter if the KEEP_ASPECT_RATIO keyword is
used.
TV: Setting this keyword makes the TVIMAGE command work much
like the TV command, although better. That is to say, it
will still set the correct DECOMPOSED state depending upon
the kind of image to be displayed (8-bit or 24-bit). It will
also allow the image to be "positioned" in the window by
specifying the coordinates of the lower-left corner of the
image. The NORMAL keyword is activated when the TV keyword
is set, which will indicate that the position coordinates
are given in normalized coordinates rather than device
coordinates.
Setting this keyword will ensure that the keywords
KEEP_ASPECT_RATIO, MARGIN, MINUS_ONE, MULTI, and POSITION
are ignored.
OUTPUTS:
None.
SIDE EFFECTS:
Unless the KEEP_ASPECT_RATIO keyword is set, the displayed image
may not have the same aspect ratio as the input data set.
RESTRICTIONS:
If the POSITION keyword and the KEEP_ASPECT_RATIO keyword are
used together, there is an excellent chance the POSITION
parameters will change. If the POSITION is passed in as a
variable, the new positions will be returned in the same variable
as an output parameter.
If a 24-bit image is displayed on an 8-bit display, the
24-bit image must be converted to an 8-bit image and the
appropriate color table vectors. This is done with the COLOR_QUAN
function. The TVIMAGE command will load the color table vectors
and set the NOINTERPOLATION keyword if this is done. Note that the
resulting color table vectors are normally incompatible with other
IDL-supplied color tables. Hence, other graphics windows open at
the time the image is display are likely to look strange.
EXAMPLE:
To display an image with a contour plot on top of it, type:
filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat')
image = BYTARR(360,360)
OPENR, lun, filename, /GET_LUN
READU, lun, image
FREE_LUN, lun
TVIMAGE, image, POSITION=thisPosition, /KEEP_ASPECT_RATIO
CONTOUR, image, POSITION=thisPosition, /NOERASE, XSTYLE=1, $
YSTYLE=1, XRANGE=[0,360], YRANGE=[0,360], NLEVELS=10
To display four images in a window without spacing between them:
!P.Multi=[0,2,2]
TVImage, image, Margin=0
TVImage, image, Margin=0
TVImage, image, Margin=0
TVImage, image, Margin=0
!P.Multi = 0
MODIFICATION HISTORY:
Written by: David Fanning, 20 NOV 1996.
Fixed a small bug with the resizing of the image. 17 Feb 1997. DWF.
Removed BOTTOM and NCOLORS keywords. This reflects my growing belief
that this program should act more like TV and less like a "color
aware" application. I leave "color awareness" to the program
using TVIMAGE. Added 24-bit image capability. 15 April 1997. DWF.
Fixed a small bug that prevented this program from working in the
Z-buffer. 17 April 1997. DWF.
Fixed a subtle bug that caused me to think I was going crazy!
Lession learned: Be sure you know the *current* graphics
window! 17 April 1997. DWF.
Added support for the PRINTER device. 25 June 1997. DWF.
Extensive modifications. 27 Oct 1997. DWF
1) Removed PRINTER support, which didn't work as expected.
2) Modified Keep_Aspect_Ratio code to work with POSITION keyword.
3) Added check for window-able devices (!D.Flags AND 256).
4) Modified PostScript color handling.
Craig Markwart points out that Congrid adds an extra row and column
onto an array. When viewing small images (e.g., 20x20) this can be
a problem. Added a Minus_One keyword whose value can be passed
along to the Congrid keyword of the same name. 28 Oct 1997. DWF
Changed default POSITION to fill entire window. 30 July 1998. DWF.
Made sure color decomposition is OFF for 2D images. 6 Aug 1998. DWF.
Added limited PRINTER portrait mode support. The correct aspect ratio
of the image is always maintained when outputting to the
PRINTER device and POSITION coordinates are ignored. 6 Aug 1998. DWF
Removed 6 August 98 fixes (Device, Decomposed=0) after realizing that
they interfere with operation in the Z-graphics buffer. 9 Oct 1998. DWF
Added a MARGIN keyword. 18 Oct 1998. DWF.
Re-established Device, Decomposed=0 keyword for devices that
support it. 18 Oct 1998. DWF.
Added support for the !P.Multi system variable. 3 March 99. DWF
Added DEVICE, DECOMPOSED=1 command for all 24-bit images. 2 April 99. DWF.
Added ability to preserve DECOMPOSED state for IDL 5.2 and higher. 4 April 99. DWF.
Added TV keyword to allow TVIMAGE to work like the TV command. 11 May 99. DWF.
Added the OVERPLOT keyword to allow plotting on POSITION coordinates
estabished by the preceding graphics command. 11 Oct 99. DWF.
Added automatic recognition of !P.Multi. Setting MULTI keyword is no
longer required. 18 Nov 99. DWF.
Added NOINTERPOLATION keyword so that nearest neighbor interpolation
is performed rather than bilinear. 3 Dec 99. DWF
Changed ON_ERROR condition from 1 to 2. 19 Dec 99. DWF.
Added Craig Markwardt's CMCongrid program and removed RSI's. 24 Feb 2000. DWF.
Added HALF_HALF keyword to support CMCONGRID. 24 Feb 2000. DWF.
Fixed a small problem with image start position by adding ROUND function. 19 March 2000. DWF.
Updated the PRINTER device code to take advantage of available keywords. 2 April 2000. DWF.
Reorganized the code to handle 24-bit images on 8-bit displays better. 2 April 2000. DWF.
Added BACKGROUND keyword. 20 April 2000. DWF.
Fixed a small problem in where the ERASE was occuring. 6 May 2000. DWF.
Rearranged the PLOT part of code to occur before decomposition state
is changed to fix Background color bug in multiple plots. 23 Sept 2000. DWF.
Removed MULTI keyword, which is no longer needed. 23 Sept 2000. DWF.
Fixed a small problem with handling images that are slices from 3D image cubes. 5 Oct 2000. DWF.
Added fix for brain-dead Macs from Ben Tupper that restores Macs ability to
display images. 8 June 2001. DWF.
Fixed small problem with multiple plots and map projections. 29 June 2003. DWF.
Converted all array subscripts to square brackets. 29 June 2003. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Small modification at suggestion of Karsten Rodenacker to increase size of
images in !P.MULTI mode. 8 December 2004. DWF.
Minor modifications on Karsten Rodenacker's own account concerning margination
and TV behaviour. 8 December 2004. KaRo
(See themis/thm_ui_new/utilities/tvimage.pro)
NAME:
TVREAD
PURPOSE:
To get accurate screen dumps with the IDL command TVRD on 24-bit
PC and Macintosh computers, you have to be sure to set color
decomposition on. This program adds that capability automatically.
In addition, the program will optionally write BMP, GIF, JPEG,
PICT, PNG, and TIFF color image files of the screen dump.
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:
Graphics
CALLING SEQUENCE:
image = TVREAD(xstart, ystart, ncols, nrows)
The returned image will be a 2D image on 8-bit systems and
a 24-bit pixel interleaved true-color image on 24-bit systems.
A -1 will be returned if a file output keyword is used (e.g., JPEG, TIFF, etc.).
OPTIONAL INPUTS:
XSTART -- The starting column index. By default, 0.
YSTART -- The starting row index. By default, 0.
NCOLS -- The number of columns to read. By default, !D.X_Size - XSTART
NROWS -- The number of rows to read. By default, !D.Y_Size - YSTART.
KEYWORD PARAMETERS:
BMP -- Set this keyword to write the screen dump as a color BMP file.
CANCEL -- An output keyword set to 1 if the user cancels out of a
filename dialog. Set to 0 otherwise.
COLORS -- If a 24-bit image has to be quantized, this will set the number
of colors in the output image. Set to 256 by default. Applies to BMP,
GIF, PICT, and PNG formats written from 24-bit displays.(See the
COLOR_QUAN documentation for details.)
CUBE -- If this keyword is set to a value between 2 and 6 the color
quantization will use a cubic method of quantization. Applies to BMP,
GIF, PICT, and PNG formats written from 24-bit displays.(See the
COLOR_QUAN documentation for details.)
DITHER -- If this keyword is set the quantized image will be dithered.
Applies to BMP, GIF, PICT, and PNG formats written from 24-bit displays.
(See the COLOR_QUAN documentation for details.)
FILENAME -- The base name of the output file. (No file extensions;
they will be added automatically.) This name may be changed by the user.
image = TVREAD(Filename='myfile', /JPEG)
No file will be written unless a file output keyword is used
(e.g., JPEG, TIFF, etc.) in the call. By default the FILENAME is
set to "idl". The file extension will be set automatically to match
the type of file created.
GIF -- Set this keyword to write the screen dump as a color GIF file.
JPEG -- Set this keyword to write the screen dump as a color JPEG file.
NODIALOG -- Set this keyword if you wish to avoid the DIALOG_PICKFILE
dialog that asks you to name the output file. This keyword should be
set, for example, if you are processing screens in batch mode.
ORDER -- Set this keyword to determine the image order for reading the
display. Corresponds to !Order and set to such as the default.
PICT -- Set this keyword to write the screen dump as a color PICT file.
PNG -- Set this keyword to write the screen dump as a color PNG file.
TIFF -- Set this keyword to write the screen dump as a color TIFF file.
TRUE -- Set this keyword to the type of interleaving you want. 1 = Pixel
interleaved, 2 = row interleaved, 3 = band interleaved.
QUALITY -- This keyword sets the amount of compression for JPEG images.
It should be set to a value between 0 and 100. It is set to 75 by default.
(See the WRITE_JPEG documentation for details.)
WID -- The index number of the window to read from. The current graphics window
(!D.Window) is selected by default. An error is issued if no windows are
currently open on a device that supports windows.
_EXTRA -- Any keywords that are appropriate for the WRITE_*** routines are
also accepted via keyword inheritance.
COMMON BLOCKS:
None
RESTRICTIONS: Requires IDL 5.2 and higher.
MODIFICATION HISTORY:
Written by David W. Fanning, 9 AUG 2000.
Added changes to make the program more device independent. 16 SEP 2000. DWF.
Removed GIF file support for IDL 5.4 and above. 18 JAN 2001. DWF.
Added NODIALOG keyword. 28 MAR 2001. DWF.
Added an output CANCEL keyword. 29 AUG 2001. DWF.
Added ERROR_MESSAGE code to file. 17 DEC 2001. DWF.
Added ORDER keyword. 25 March 2002. DWF.
Now create 24-bit PNG files if reading from a 24-bit display. 11 May 2002. DWF.
Now create 24-bit BMP files if reading from a 24-bit display. 23 May 2002. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
(See themis/thm_ui_new/utilities/tvread.pro)
NAME: thm_gui_new_init PURPOSE: the very beginnings of global configuration info for thm_gui_new CALLING SEQUENCE: themis_gui_new_init INPUT: none OUTPUT: none HISTORY: $LastChangedBy: pcruce $ $LastChangedDate: 2012-01-27 16:05:04 -0800 (Fri, 27 Jan 2012) $ $LastChangedRevision: 9645 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01_test/idl/themis/thm_ui_new/utilities/thm_gui_new_init.pro $
(See themis/thm_ui_new/utilities/thm_gui_new_init.pro)