This page was created by the IDL library routine `mk_html_help2`.

Last modified: Tue Aug 5 18:17:40 2025.

# Directory Listing of Routines

# spedas_gui/utilities

- CDF_VERSION_TEST
- CENTERTLB
- COLORBAR[2]
- ERROR_MESSAGE
- FORMATANNOTATION
  This routine is used as a callback for axis labeling by IDLgrAxis
- FSC_COLOR
- FSC_FIELD
- GET_INTRO_DIR
- GET_MAX_MEMBLOCK.PRO
  Returns size of largest contiguous block of memory available to IDL in
- GET_MAX_MEMBLOCK2.PRO
  Returns size of largest contiguous block of memory available to IDL in
- GETCTPATH
  gets the path of the color table on the file system
- GETHELPPATH
  gets the path of the help directory in a cross platform way
- GETPLUGINPATH
  gets the path of the plugins directory in a cross platform way
- GETRESOURCEPATH
  gets the path of the resource directory in a cross platform way
- LOAD_DATA
- LOADDATA
- MAKECOLORTABLE
  makes the color table file for the spedas gui
- NUM_TO_STR_PAD
- OPEN_SPEDAS_DOCUMENT
- OPEN_SPEDAS_TEMPLATE
- PICKCOLOR
- PICKCOLORNAME
- PROGRESSBAR__DEFINE
- SAVE_DOCUMENT
- SAVE_SPEDAS_TEMPLATE
- SAVEAS_ASCII.PRO
  Saves SPEDAS Loaded Data variables in ASCII format.
- SOURCEPATH
- SOURCEROOT
- SPD_ADDSLASH
  Adds a trailing slash to a string, (usually a directory name) if it
- SPD_ARRANGE_PLOTS
- SPD_BSHOCK
- SPD_CDF_COMPRESS
  Compresses a cdf file using the CDF utility cdfconvert
- SPD_CHECK_TVAR (FUNCTION)
  This routine check whether the given tplot variable TVAR exists in the
- SPD_FIND_FILE
- SPD_GRAPHICS_CONFIG
- SPD_MPAUSE
- SPD_NEW_COORDS
  sets coordinate systems in the dlimits structure of input
- SPD_NEW_UNITS
  sets units in the dlimits structure of input tplot variables from
- SPD_SMOOTH_TIME
  Smooths a tplot variable in time using a simple boxcar average
- SPD_STR_SPLIT
- SPD_STRING_REPLACEN
  Find and replace for strings.
- SPD_TPLOT_TRANGE
- SPD_UI_CALENDAR.PRO
  Calendar selection widget for the GUI
- SPD_UI_CALL_PLUGIN
- SPD_UI_CHECK_OVERLAP
  Determins if any panels on the current
- SPD_UI_CHECK_OVERWRITE_DATA
- SPD_UI_CLEANUP_TPLOT
  Abstracts the oft-repeated operation which identifies new tplot variables,
- SPD_UI_COMBOBOX
  IDL combobox doesn't actually support null strings('') as entries
- SPD_UI_DATA_MINMAX
  Returns a two-element array containing the mininum and maximum values
- SPD_UI_DIALOG_PICKFILE_SAVE_WRAPPER
- SPD_UI_DO_NUDGE
  Abstracted nudge data operation
- SPD_UI_FIX_PERFORMANCE
  This fixes issue IDL-68782:
- SPD_UI_GET_COMBOBOX_SELECT
- SPD_UI_GET_PANELS
  Generic GUI function for returning the panel names and panel objects given a window
- SPD_UI_GETLENGTHVARS
- SPD_UI_INTERPOLATE
  Interpolates over x-axis of active data and adds new data to
- SPD_UI_LOGIN_WIDGET
  Prompt the user for their login information
- SPD_UI_MATCH_BACKGROUND
- SPD_UI_MESSAGE
- SPD_UI_MULTICHOICE_HISTORY
- SPD_UI_OPEN_URL
  Open an url in the default web browser.
- SPD_UI_PART_GETSPEC_REPLAY
- SPD_UI_PLUGIN_MENU
- SPD_UI_PLUGIN_REPLAY
- SPD_UI_PROMPT_WIDGET.PRO
  Simple standardized popup, for yes/no,yes_to_all,no_to_all,cancel
- SPD_UI_PWRSPC
  Creates power spectra from GUI variables that are active in the Process Data
- SPD_UI_RUN_CALC
  Function that interprets program for spd_ui_calculate
- SPD_UI_SBAR_HWIN_UPDATE
- SPD_UI_SET_CURSOR
  Replaces the cursor on non-windows machines
- SPD_UI_SPDF_REPLAY
- SPD_UI_SPINNER
  A compound 'spinner' widget for editing numerical values.
- SPD_UI_SPLASH_WIDGET
  Widget for the SPEDAS GUI splash screen
- SPD_UI_TIME_WIDGET.PRO
  Compound widget used to generate standardized time selection ui,
- TEST_LEAP_YR
  Determines whether a given year is a leap year, and
- SPD_UI_TIMEFIX
  Will fix an input time string of yyyy-mm-dd hh:mm:ss.xxxx if there
- SPD_UI_TRACK_ONE
- SPD_UI_UPDATE_PROGRESS
  Write a string into the progress widget for the THEMIS GUI
- SPD_UI_USINGEXPONENT
- SPD_UI_VALIDATE_FILE
- SPD_UI_WAVELET
  wavelet transform of the input tplot variables, fist calls split_vec
- SPD_UI_WV_MEMORY_TEST
  Estimate of memory used by a wavelet transform. The estimated memory
- SPD_UNIQ
- STRINGISNUM
- TVIMAGE
  This purpose of TVIMAGE is to enable the TV command in IDL
- TVREAD

# Routine Descriptions

## CDF_VERSION_TEST

[Next Routine] [List of Routines]

     Procedure:
         cdf_version_test

     Purpose:
         Check that the patched version the CDF library (3.4+) is installed

     Note:
         The crash due to an unpatched CDF library is usually due to a
         change in the number of arguments of the function CDF_EPOCH_COMPARE.
         The change was introduced in version 3.4 of the CDF library:
            http://cdaweb.sci.gsfc.nasa.gov/pub/software/cdf/dist/cdf35_0_2/idl/CDF_EPOCH_COMPARE.txt

     $LastChangedBy: egrimes $
     $LastChangedDate: 2014-10-31 09:11:43 -0700 (Fri, 31 Oct 2014) $
     $LastChangedRevision: 16091 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/cdf_version_test.pro $

(See spedas_gui/utilities/cdf_version_test.pro)

## CENTERTLB

[Previous Routine] [Next Routine] [List of Routines]

     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 spedas_gui/utilities/centertlb.pro)

## COLORBAR[2]

[Previous Routine] [Next Routine] [List of Routines]

     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 spedas_gui/utilities/colorbar.pro)

## ERROR_MESSAGE

[Previous Routine] [Next Routine] [List of Routines]

     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 SPEDAS 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 spedas_gui/utilities/error_message.pro)

## FORMATANNOTATION

[Previous Routine] [Next Routine] [List of Routines]

    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
            maxexplen:0L,$ ; Optional, if present and not equal -1 then exponents will be formatted to this length
            negexp:0B} ; Optional, if present 1 indicates presence of a negative exponent on axis (only considered if maxexplen is also set and not -1)
    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: egrimes $
    $LastChangedDate: 2014-06-05 10:01:44 -0700 (Thu, 05 Jun 2014) $
    $LastChangedRevision: 15308 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/formatannotation.pro $

(See spedas_gui/utilities/formatannotation.pro)

## FSC_COLOR

[Previous Routine] [Next Routine] [List of Routines]

     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 spedas_gui/utilities/fsc_color.pro)

## FSC_FIELD

[Previous Routine] [Next Routine] [List of Routines]

     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 spedas_gui/utilities/fsc_field.pro)

## GETCTPATH

[Previous Routine] [Next Routine] [List of Routines]

    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: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/getctpath.pro $

(See spedas_gui/utilities/getctpath.pro)

## GETHELPPATH

[Previous Routine] [Next Routine] [List of Routines]

    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: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/gethelppath.pro $

(See spedas_gui/utilities/gethelppath.pro)

## GETPLUGINPATH

[Previous Routine] [Next Routine] [List of Routines]

    NAME: getpluginpath

    PURPOSE:
      gets the path of the plugins directory in a cross platform way

    CALLING SEQUENCE:
       getpluginpath,path

    OUTPUT:
       path:  the path to the plugins directory

    $LastChangedBy: egrimes $
    $LastChangedDate: 2015-01-09 09:30:19 -0800 (Fri, 09 Jan 2015) $
    $LastChangedRevision: 16608 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/getpluginpath.pro $

(See spedas_gui/utilities/getpluginpath.pro)

## GETRESOURCEPATH

[Previous Routine] [Next Routine] [List of Routines]

    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: nikos $
    $LastChangedDate: 2015-06-25 11:06:01 -0700 (Thu, 25 Jun 2015) $
    $LastChangedRevision: 17971 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/getresourcepath.pro $

(See spedas_gui/utilities/getresourcepath.pro)

## GET_INTRO_DIR

[Previous Routine] [Next Routine] [List of Routines]

     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 spedas_gui/utilities/get_intro_dir.pro)

## GET_MAX_MEMBLOCK.PRO

[Previous Routine] [Next Routine] [List of Routines]

    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 spedas_gui/utilities/get_max_memblock.pro)

## GET_MAX_MEMBLOCK2.PRO

[Previous Routine] [Next Routine] [List of Routines]

    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 spedas_gui/utilities/get_max_memblock2.pro)

## LOADDATA

[Previous Routine] [Next Routine] [List of Routines]

     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 spedas_gui/utilities/loaddata.pro)

## LOAD_DATA

[Previous Routine] [Next Routine] [List of Routines]

     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 spedas_gui/utilities/load_data.pro)

## MAKECOLORTABLE

[Previous Routine] [Next Routine] [List of Routines]

    NAME: makecolortable

    PURPOSE:
      makes the color table file for the spedas gui

    CALLING SEQUENCE:
       makecolortable

    EFFECTS:
      overwrites the file spedas/spd_ui/utilities/spd_gui_colors.tbl

    $LastChangedBy: nikos $
    $LastChangedDate: 2016-10-18 16:31:28 -0700 (Tue, 18 Oct 2016) $
    $LastChangedRevision: 22141 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/makecolortable.pro $

(See spedas_gui/utilities/makecolortable.pro)

## NUM_TO_STR_PAD

[Previous Routine] [Next Routine] [List of Routines]

    Procedure: num_to_str_pad

    Purpose:
      This is a very basic operation that gets repeated a lot in date file output.
      This takes a number as input and pads zeros on the front so that the number outputs
      at fixed field width.

    Inputs:
      val:  The number to be converted
      len: The final length requested

    Keywords:
      pad:  Select a character other than '0' with which to pad
      integral: Normally, if val is a floating point type, if will add a .00, If this keyword is set, forces no decimal points.

    Notes:
      1. For a while I resisted putting this in the distribution as it seemed too specific an operation,
      but at the point when I was considering implementing this routine for a 4th time in a separate
      namespace, I just decided to go ahead and add this instead.

      2. There is no error checking to determine if the input is wider than 'len'

      3. Currently floating point inputs will produce unreliable results.

    Example:

      date_str = num_to_str_pad(year,4)+num_to_str_pad(mon,2)+num_to_str_pad(day,2)

     $LastChangedBy: nikos $
     $LastChangedDate: 2016-10-19 15:27:17 -0700 (Wed, 19 Oct 2016) $
     $LastChangedRevision: 22151 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/num_to_str_pad.pro $

(See spedas_gui/utilities/num_to_str_pad.pro)

## OPEN_SPEDAS_DOCUMENT

[Previous Routine] [Next Routine] [List of Routines]

    PRO:
      open_spedas_document

    PURPOSE:

     opens a spedas 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: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/open_spedas_document.pro $

(See spedas_gui/utilities/open_spedas_document.pro)

## OPEN_SPEDAS_TEMPLATE

[Previous Routine] [Next Routine] [List of Routines]

    PRO:
      open_spedas_template

    PURPOSE:

     opens a spedas 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: egrimes $
    $LastChangedDate: 2015-04-09 11:52:06 -0700 (Thu, 09 Apr 2015) $
    $LastChangedRevision: 17264 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/open_spedas_template.pro $

(See spedas_gui/utilities/open_spedas_template.pro)

## PICKCOLOR

[Previous Routine] [Next Routine] [List of Routines]

     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 SPEDAS GUI.  Please direct any errors to the SPEDAS 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 spedas_gui/utilities/pickcolor.pro)

## PICKCOLORNAME

[Previous Routine] [Next Routine] [List of Routines]

     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 spedas_gui/utilities/pickcolorname.pro)

## PROGRESSBAR__DEFINE

[Previous Routine] [Next Routine] [List of Routines]

     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 spedas_gui/utilities/progressbar__define.pro)

## SAVEAS_ASCII.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     saveas_ascii.pro

    PURPOSE:
     Saves SPEDAS Loaded Data variables in ASCII format.

    INPUT & KEYWORDS:
      loadedData:  SPEDAS 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 spedas_gui/utilities/saveas_ascii.pro)

## SAVE_DOCUMENT

[Previous Routine] [Next Routine] [List of Routines]

    PRO:
      save_document

    PURPOSE:

     saves a spedas 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: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/save_document.pro $

(See spedas_gui/utilities/save_document.pro)

## SAVE_SPEDAS_TEMPLATE

[Previous Routine] [Next Routine] [List of Routines]

    PRO:
      save_spedas_template

    PURPOSE:

     saves a spedas 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: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/save_spedas_template.pro $

(See spedas_gui/utilities/save_spedas_template.pro)

## SOURCEPATH

[Previous Routine] [Next Routine] [List of Routines]

     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 spedas_gui/utilities/sourcepath.pro)

## SOURCEROOT

[Previous Routine] [Next Routine] [List of Routines]

     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 spedas_gui/utilities/sourceroot.pro)

## SPD_ADDSLASH

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_addslash

    PURPOSE:
     Adds a trailing slash to a string, (usually a directory name) if it
     does not already have one. This is used to insure that local and
     remote directory names passed into load programs have the trailing
     slash. Note that even for windows, a '/' works, no need to use '\'

    CALLING SEQUENCE:
     dirslash = spd_addslash(dir)

    INPUT:
     dir = A string, usually a directory name.

    OUTPUT:
     dirslash = dir+'/', if there is no slash, otherwise dir is unchanged

    HISTORY:
     2012-08-15, jmm, jimm@ssl.berkeley.edu

     $LastChangedBy: nikos $
     $LastChangedDate: 2016-10-06 15:10:51 -0700 (Thu, 06 Oct 2016) $
     $LastChangedRevision: 22057 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_addslash.pro $

(See spedas_gui/utilities/spd_addslash.pro)

## SPD_ARRANGE_PLOTS

[Previous Routine] [Next Routine] [List of Routines]

     NAME: ARRANGE_PLOTS

     PURPOSE:  Returns normal coordinates of plot position box, suitable for
              passing to PLOT, when you want to put many plots on one
              page. Differs from setting !p.multi, because plots can be
              put against one another with no space between. You can
              specify the outer margins through keywords, as well as the
              gaps between plots. By default, the margins are 0.1 left,
              0.05 right, 0.1 bottom, 0.07 top, and there is no gap
              between plots in either direction.

     INPUTS:

     KEYWORD PARAMETERS:
                         NX - the number of plots in the x direction

                         NY - the number of plots in the y direction

                         NPLOTS - the total number of plots

                         X0MARGIN, Y0MARGIN,
                          X1MARGIN, Y1MARGIN - the plot margins, in
                          normalized coordinates.

                         SQUARE - if set, the resulting plots are
                                  square. The larger dimension is shrunk to
                                  make squares.
     OUTPUTS:
              x0, y0, x1, y1: These are named variables in which the
              left, lower, right, and upper boundaries, respectively of
              each plot are returned.

     EXAMPLE:
       arrange_plots, x0, y0, x1, y1, nx=3
       erase
       for i=0,2 do plot,my_data,position=[x0[i],y0[i],x1[i],y1[i]],/noerase

     MODIFICATION HISTORY:
     Original from Li-Jen Chen at GSFC (forked for SPEDAS, 3/15/2016)

(See spedas_gui/utilities/spd_arrange_plots.pro)

## SPD_BSHOCK

[Previous Routine] [Next Routine] [List of Routines]

    ro spd_bshock,xsh,ysh ,ysh_west=ysh_west,short=short,xsh_max=xsh_max

    gse or gsm does not matter because bow shock is  assumed  to be
                         ;rotationally symmetric

     This subroutine calculates the bow shock (X,Y) locations based on
     the Fairfield model (JGR, 1971 Vol 76 Oct-Dec p.6700). It outputs the location of the bow
     shock down to a very large distance (xmp_max=-300 Re)
     Aberration of 4 degrees is assumed
     Modification: calculates ysh for given xsh and returns only abs(ysh)
                   Note, this provides flexibility with xsh_max
     $LastChangedBy: jimm $
     $LastChangedDate: 2015-07-24 12:07:30 -0700 (Fri, 24 Jul 2015) $
     $LastChangedRevision: 18247 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_bshock.pro $

(See spedas_gui/utilities/spd_bshock.pro)

## SPD_CDF_COMPRESS

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:
      spd_cdf_compress

    PURPOSE:
      Compresses a cdf file using the CDF utility cdfconvert

    PARAMETERS:
      file_in: (string) Input cdf file. Full path.

    KEYWORDS:
      file_out: (string) Output cdf file. Full path. Optional if replace=1.
      replace: if set, replace original file (file_out is ignored)
      cdfconvert: (string) Full path to cdfconvert executable
      cdfparams: (string) Parameters for cdfconvert
      cdf_tmp_dir: (string) Directory for temp files
      cdf_compress_error: (string) Returns error

    OUTPUT:
      A compressed cdf file

    NOTES:
      The default (optimal) options used with cdfconvert are available only with CDF 3.6.1 and later.

    EXAMPLE:
      spd_cdf_compress, '/data/tha_l2_fgm_20110101_v01.cdf', file_out='/data/tha_l2_fgm_20110101_v01_temp.cdf', replace=1, cdf_compress_error=cdf_compress_error

      on windows:
      spd_cdf_compress, 'c:\temp\in.cdf', file_out='c:\temp\out.cdf', cdfconvert='C:\CDF_Distribution\cdf36_3-dist\bin\cdfconvert.exe', replace=1, $
             cdf_tmp_dir='c:\temp\', cdf_compress_error=cdf_compress_error

    $LastChangedBy: jimm $
    $LastChangedDate: 2022-03-01 12:52:56 -0800 (Tue, 01 Mar 2022) $
    $LastChangedRevision: 30634 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_cdf_compress.pro $

(See spedas_gui/utilities/spd_cdf_compress.pro)

## SPD_CHECK_TVAR (FUNCTION)

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
         spd_check_tvar (FUNCTION)

     PURPOSE:
         This routine check whether the given tplot variable TVAR exists in the
         memory. If not, return 0. Otherwise, then check whether it contains data
         of the current date. If yes, return 1. If not, return 0.

     ARGUMENTS:
         tvar: (INPUT, REQUIRED) The name of a tplot variable to be checked.

     KEYWORDS:
         None.

     HISTORY:
         2009-05-10: written by Jianbao Tao, in CU/LASP.

     $LastChangedBy: nikos $
     $LastChangedDate: 2016-10-06 15:10:51 -0700 (Thu, 06 Oct 2016) $
     $LastChangedRevision: 22057 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_check_tvar.pro $

(See spedas_gui/utilities/spd_check_tvar.pro)

## SPD_FIND_FILE

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      spd_find_file

    Purpose:
      Check for the existence of a file in the current path.

    Calling Sequence:
      bool = spd_find_file(file_name)

    Input:
      name: (string) Name of file including type appendix

    Output:
      Return Value: (bool) true if one or more copies of the file found in your path, false if not

    Notes:

    $LastChangedBy: pcruce $
    $LastChangedDate: 2015-01-12 12:57:20 -0800 (Mon, 12 Jan 2015) $
    $LastChangedRevision: 16646 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_find_file.pro $

(See spedas_gui/utilities/spd_find_file.pro)

## SPD_GRAPHICS_CONFIG

[Previous Routine] [Next Routine] [List of Routines]

      PRO spd_graphics_config

      This routine does just the graphics configuration for SPEDAS plug-ins.  It can be called from routines that
      need to have a guaranteed graphics configuration without forcing the rest of the plug-in initialization
      to be run.  This is done to avoid overwriting settings that may have been set by users later in their
      session.

      Keywords:
       colortable: overwrite the default colortable initialization

     $LastChangedBy: egrimes $
     $LastChangedDate: 2019-01-16 13:34:22 -0800 (Wed, 16 Jan 2019) $
     $LastChangedRevision: 26470 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_graphics_config.pro $

(See spedas_gui/utilities/spd_graphics_config.pro)

## SPD_MPAUSE

[Previous Routine] [Next Routine] [List of Routines]

    ro spd_mpause,xmp,ymp,ymp_west=ymp_west,short=short,xmp_max=xmp_max
    gse or gsm does not matter because mpause assumed
                         ;rotationally symmetric

     This subroutine calculates the magnetopause (X,Y) locations based on
     the Fairfield model (JGR, 1971). It outputs the location of the ma-
     gnetopause down to a very large distance (xmp_max=-300 Re)
     Aberation of 4 degrees is assumed
     $LastChangedBy: jimm $
     $LastChangedDate: 2015-07-24 12:07:30 -0700 (Fri, 24 Jul 2015) $
     $LastChangedRevision: 18247 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_mpause.pro $

(See spedas_gui/utilities/spd_mpause.pro)

## SPD_NEW_COORDS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_new_coords

    PURPOSE:
     sets coordinate systems in the dlimits structure of input
     tplot variables from the CDF attributes, or alternatively, input
     keywords

    CALLING SEQUENCE:
     spd_new_coords,vars,coords_in=coords_in

    INPUT:
     vars = variable names

    OUTPUT:
     none explicit, the dlimits structure of the variables are changed

    KEYWORDS:
     coords_in = if set, then the coords for all vars will be set to this
                 value (this is a scalar input)

    HISTORY:
     12-feb-2008, jmm, jimm@ssl.berkeley.edu

    $LastChangedBy: jwl $
    $LastChangedDate: 2025-07-30 17:43:20 -0700 (Wed, 30 Jul 2025) $
    $LastChangedRevision: 33516 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_new_coords.pro $

(See spedas_gui/utilities/spd_new_coords.pro)

## SPD_NEW_UNITS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_new_units

    PURPOSE:
     sets units in the dlimits structure of input tplot variables from
     the CDF attributes, or alternatively, input keywords

    CALLING SEQUENCE:
     spd_new_units,vars,units_in=units_in

    INPUT:
     vars = variable names

    OUTPUT:
     none explicit, the dlimits structure of the variables are changed

    KEYWORDS:
     units_in = if set, then the units for all vars will be set to this
                value (this is a scalar input)

    HISTORY:
     12-feb-2008, jmm, jimm@ssl.berkeley.edu

    $LastChangedBy: nikos $
    $LastChangedDate: 2016-10-07 12:01:16 -0700 (Fri, 07 Oct 2016) $
    $LastChangedRevision: 22068 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_new_units.pro $

(See spedas_gui/utilities/spd_new_units.pro)

## SPD_SMOOTH_TIME

[Previous Routine] [Next Routine] [List of Routines]

     PROCEDURE:
             spd_smooth_time

     PURPOSE:
             Smooths a tplot variable in time using a simple boxcar average
             This routine is essentially just a wrapper around the IDL smooth
             function that allows the /NAN keyword, unlike tsmooth_in_time

     KEYWORDS:
            newname: name of the tplot variable to store the data in; default is input_name+"_smth"
            nan: ignore NaNs in the input (treat as missing data)

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-07-27 09:01:57 -0700 (Thu, 27 Jul 2017) $
    $LastChangedRevision: 23712 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_smooth_time.pro $

(See spedas_gui/utilities/spd_smooth_time.pro)

## SPD_STRING_REPLACEN

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_string_replacen

    PURPOSE:
     Find and replace for strings.

    KEYWORDS:
     inString {in} {type=string}
                input string.
     findString {in} {type=string}
                find string. It can be a regular expression.
     replaceString {in} {type=string}
                replace string.

    HISTORY:

    $LastChangedBy:  $
    $LastChangedDate:$
    $LastChangedRevision:  $
    $URL: $

(See spedas_gui/utilities/spd_string_replacen.pro)

## SPD_STR_SPLIT

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      spd_str_split

    Purpose:
      Splits strings and arrays of strings.
      Returns a string or an array of strings.

    Calling Sequence:
      result = spd_str_split(str, pattern, /extract)

    Input:
      str: (string) A string to be splitted
      pattern: (optional string) A patern to find and split (usually a single character).
                       If not given,
                       If the /extract keyword is used, the patern is not included in the result.

    Output:
      Return Value: (string) An array of strings

    Notes:
      Use spd_str_split instead of the IDL strsplit to split string arrays in SPEDAS.
      In IDL 8.x the strsplit function, when applied to an array of strings returns a LIST.
      LIST is a new type of variable that was introduced in IDL 8.0.
      SPEDAS has to be compatible with IDL 6.4 and IDL 7.x, so it cannot use LIST variables.

    $LastChangedBy: nikos $
    $LastChangedDate: 2016-04-25 10:54:54 -0700 (Mon, 25 Apr 2016) $
    $LastChangedRevision: 20909 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_str_split.pro $

(See spedas_gui/utilities/spd_str_split.pro)

## SPD_TPLOT_TRANGE

[Previous Routine] [Next Routine] [List of Routines]

    Function:
      spd_tplot_trange

    Purpose:
      Return the full or current tplot time range without
      unnecessary calls to other time procedures.

    Calling Sequence:
      trange = spd_tplot_trange( [/current] )

    Input:
      current:  Flag to return currently plotted time range.

    Output:
      return value:  Two element double-prec. time range as stored by tplot.

    Notes:
      This routine should not modify any variables in the tplot common block.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2015-02-20 13:46:54 -0800 (Fri, 20 Feb 2015) $
    $LastChangedRevision: 17020 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_tplot_trange.pro $

(See spedas_gui/utilities/spd_tplot_trange.pro)

## SPD_UI_CALENDAR.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_ui_calendar.pro

    PURPOSE:
     Calendar selection widget for the GUI

    CALLING SEQUENCE:
     spd_ui_calendar,title, otime, gui_id, startyear

    INPUT:
     title: Title of the calendar window
     otime: Time object
     gui_id: Widget ID of the widget that called the calendar
     startyear: Start year in 'Year' list

    HISTORY:

     $LastChangedBy: $
     $LastChangedDate: $
     $LastChangedRevision: $
     $URL: $

(See spedas_gui/utilities/spd_ui_calendar.pro)

## SPD_UI_CALL_PLUGIN

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      spd_ui_call_plugin

    Purpose:
      Opens specified GUI plugin window.

    Calling Sequence:
      spd_ui_call_plugin, event, info

    Input:
      event: event structure from plugin menu
      info: Main storage structure from GUI

    Output:
      none

    Notes:

    $LastChangedBy: nikos $
    $LastChangedDate: 2014-07-25 10:45:13 -0700 (Fri, 25 Jul 2014) $
    $LastChangedRevision: 15610 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_call_plugin.pro $

(See spedas_gui/utilities/spd_ui_call_plugin.pro)

## SPD_UI_CHECK_OVERLAP

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      spd_ui_check_overlap

    PURPOSE:
      Determins if any panels on the current
       page are overlapping.
      Prints message notifying user of those panels.

    CALLING SEQUENCE:
      bool = spd_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 spedas_gui/utilities/spd_ui_check_overlap.pro)

## SPD_UI_CHECK_OVERWRITE_DATA

[Previous Routine] [Next Routine] [List of Routines]

     Name:
        spd_ui_check_overwrite_data

     Purpose:
        Used to check if data is already loaded in the GUI and queries the
        user to see if they want to overwrite data if it is already loaded.

        This code was originally repeated in basically every load routine, so the
        purpose for this routine is to avoid repeated code

     Input:
        new_var: the new variable
        loadedData: the loadedData object
        gui_id: widget ID of the parent widget
        statusBar: status bar object
        historyWin: history window object
        overwrite_selection: user's selection for the current query
        overwrite_count: tracking the number of overwrites for saving/replaying SPEDAS documents

     Keywords:
        replay: set by the calling routine if the user is replaying a SPEDAS document
        overwrite_selections: an array containing the user's selections

    ;$LastChangedBy: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_check_overwrite_data.pro $

(See spedas_gui/utilities/spd_ui_check_overwrite_data.pro)

## SPD_UI_CLEANUP_TPLOT

[Previous Routine] [Next Routine] [List of Routines]

    NAME: spd_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
       spd_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: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_cleanup_tplot.pro $

(See spedas_gui/utilities/spd_ui_cleanup_tplot.pro)

## SPD_UI_COMBOBOX

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
       SPD_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 = SPD_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 'SPD_UI_COMBOBOX'

(See spedas_gui/utilities/spd_ui_combobox.pro)

## SPD_UI_DATA_MINMAX

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      spd_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 = spd_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 spedas_gui/utilities/spd_ui_data_minmax.pro)

## SPD_UI_DIALOG_PICKFILE_SAVE_WRAPPER

[Previous Routine] [Next Routine] [List of Routines]

      Name: SPD_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: egrimes $
    $LastChangedDate: 2014-07-10 15:57:22 -0700 (Thu, 10 Jul 2014) $
    $LastChangedRevision: 15553 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_dialog_pickfile_save_wrapper.pro $

(See spedas_gui/utilities/spd_ui_dialog_pickfile_save_wrapper.pro)

## SPD_UI_DO_NUDGE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_ui_do_nudge

    PURPOSE:
     Abstracted nudge data operation

    CALLING SEQUENCE:
     spd_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: aaflores $
    $LastChangedDate: 2015-04-29 13:24:31 -0700 (Wed, 29 Apr 2015) $
    $LastChangedRevision: 17451 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_do_nudge.pro $

(See spedas_gui/utilities/spd_ui_do_nudge.pro)

## SPD_UI_FIX_PERFORMANCE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_ui_fix_performance

    PURPOSE:
     This fixes issue IDL-68782:
     in Linux, some drawing operations are very slow for IDL 8.3
     another solution would be win = obj_new("idlgrwindow", LINE_QUALITY=0)
     it might be useful for windows, too

    HISTORY:

    $LastChangedBy: $
    $LastChangedDate: $
    $LastChangedRevision: $
    $URL: $

(See spedas_gui/utilities/spd_ui_fix_performance.pro)

## SPD_UI_GETLENGTHVARS

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:
      spd_ui_getlengthvars

    PURPOSE:

      helper function for formatannotation

    Inputs:

    Example:

    $LastChangedBy: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_getlengthvars.pro $

(See spedas_gui/utilities/spd_ui_getlengthvars.pro)

## SPD_UI_GET_COMBOBOX_SELECT

[Previous Routine] [Next Routine] [List of Routines]

     Purpose:
       Return the index of specified combobox widget's current selection.

     Arguments:
       BASE:  Widget ID of base existing above the combobox in the widget heirarchy
       UNAME: Uname of the combobox widget

     Return Value:
       Index of the specified combobox widget's current selection.

     Usage:
       idx = spd_ui_get_combobox_select(top_base, 'my_combobox')

     Notes:

(See spedas_gui/utilities/spd_ui_get_combobox_select.pro)

## SPD_UI_GET_PANELS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      spd_ui_get_panels

    PURPOSE:
      Generic GUI function for returning the panel names and panel objects given a window

    CALLING SEQUENCE:
      panel_names = spd_ui_get_panels(window, panelObjs = panelObjs)

    INPUT:
      window: current active window, see the following example:

    EXAMPLE:
      window = windowStorage->getActive()
      panel_names = spd_ui_get_panels(window, panelObjs=panelObjs)

    OUTPUT:
      names of the panels on the current page, or a single element array
      with 'No Panels' if there aren't any panels on the current page

    $LastChangedBy: egrimes $
    $LastChangedDate: 2014-07-24 12:19:29 -0700 (Thu, 24 Jul 2014) $
    $LastChangedRevision: 15603 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_get_panels.pro $

(See spedas_gui/utilities/spd_ui_get_panels.pro)

## SPD_UI_INTERPOLATE

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      spd_ui_interpolate

    PURPOSE:
      Interpolates over x-axis of active data and adds new data to
      loaded data object.  Intended to be called from spd_ui_dproc.

    CALLING SEQUENCE:
      spd_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 spd_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 spd_ui_interpol_options was successful
               }

    HISTORY:

(See spedas_gui/utilities/spd_ui_interpolate.pro)

## SPD_UI_LOGIN_WIDGET

[Previous Routine] [Next Routine] [List of Routines]

     FUNCTION:
             spd_ui_login_widget

     PURPOSE:
             Prompt the user for their login information

     KEYWORDS:
             title: title of the login window
             group_leader: widget ID of the leader widget
             note: add a note to the bottom of the widget

     OUTPUT:
             Returns a structure containing the username, password,
             and a tag 'save' that specifies whether the user wants
             to save the login information

     NOTES:
             Written by Doug Lindholm at LASP, forked for SPEDAS on 8/20/2015.
             Minor modifications by Aaron Flores @ IGPP
             3/15/2016: updated to accept 'note' keyword - allows for
               adding a note to the bottom of the widget

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-02-15 15:48:51 -0800 (Wed, 15 Feb 2017) $
    $LastChangedRevision: 22793 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_login_widget.pro $

(See spedas_gui/utilities/spd_ui_login_widget.pro)

## SPD_UI_MATCH_BACKGROUND

[Previous Routine] [Next Routine] [List of Routines]

    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 spedas_gui/utilities/spd_ui_match_background.pro)

## SPD_UI_MESSAGE

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      spd_ui_message

    Purpose:
      Output messages to the history window, status bar, and/or dialog message pop-up.

    Calling sequence:
      spd_ui_message, message [,sb=sb] [,hw=hw] [,dialog=dialog]

    Inputs:
      message: output message string
      sb: GUI status bar object reference (optional)
      hw: GUI history window object reference (optional)
      dialog: flag to pop-up dialog message (optional)

    Notes:
      _extra can be used to pass keywords to:
         -history window
         -dialog_message

    $LastChangedBy: aaflores $
    $LastChangedDate: 2014-02-14 12:17:24 -0800 (Fri, 14 Feb 2014) $
    $LastChangedRevision: 14382 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_message.pro $

(See spedas_gui/utilities/spd_ui_message.pro)

## SPD_UI_MULTICHOICE_HISTORY

[Previous Routine] [Next Routine] [List of Routines]

     This program creates a string for the history array when multiple
     datatypes, spacecraft or stations are chosen, for use in the
     spedas_w_event routine
    $LastChangedBy: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_multichoice_history.pro $

(See spedas_gui/utilities/spd_ui_multichoice_history.pro)

## SPD_UI_OPEN_URL

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_ui_open_url

    PURPOSE:
     Open an url in the default web browser.
     If a browser executable is specified in the Configuration Settings, then prefer that.
     On UNIX platforms, the script tries to find an appropriate browser.

    CALLING SEQUENCE:
     spd_ui_open_url, url

    INPUT:
        url : string, the full url, for example http://spedas.org

    $LastChangedBy:        $
    $LastChangedDate:      $
    $LastChangedRevision:    $
    $URL:    $

(See spedas_gui/utilities/spd_ui_open_url.pro)

## SPD_UI_PART_GETSPEC_REPLAY

[Previous Routine] [Next Routine] [List of Routines]

     Purpose: Wrapper to thm_part_products, to be called during replay by spd_ui_call_sequence  Modularizes
     some operations.

     Inputs:    probe,$
                dtype,$
                trange, $
                start_angle,$
                suffix,$
                outputs, $
                phi,$
                theta,$
                pitch,$
                gyro, $
                energy,$
                regrid, $
                fac_type,$
                sst_cal, $
                sst_method_clean, $
                statusbar,$
                historyWin,$
                loadedData

    Version:
     $LastChangedBy: jimm $
     $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
     $LastChangedRevision: 14326 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_part_getspec_replay.pro $

(See spedas_gui/utilities/spd_ui_part_getspec_replay.pro)

## SPD_UI_PLUGIN_MENU

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      spd_ui_plugin_menu

    Purpose:
      Builds GUI plugin menu.

    Calling Sequence:
      spd_ui_plugin_menu, menu_id [,plugin_menu_items]

    Input:
      menu_id: Widget ID of the parent menu into which plugin buttons will be placed.
      plugin_menu_items: an array of structures containing the plugin menu items; loaded via pluginManager->getPluginMenus()
      uname: (optional) Specified uname of widget buttons (default='GUI_PLUGIN')

    Output:

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2015-04-24 18:45:02 -0700 (Fri, 24 Apr 2015) $
    $LastChangedRevision: 17429 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_plugin_menu.pro $

(See spedas_gui/utilities/spd_ui_plugin_menu.pro)

## SPD_UI_PLUGIN_REPLAY

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      spd_ui_plugin_replay

    Purpose:
      Replays data modification operations performed by GUI plugins when loading GUI documents.

    Calling Sequence:
      spd_ui_plugin_replay, procedure, parameters, loaded_data, history_window, status_bar

    Input:
      procedure: (string) name of plugin routine to be called
      parameters: (stuct/int) Anonymous struct conforming to keywords for named routine
                              or 0 if no keywords specified.
      loaded_data: (obj) reference to loaded_data object
      history_window: (obj) reference to history window object
      status_bar: (obj) reference to status bar object

    Output:
      none

    Notes:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2014-05-05 13:39:26 -0700 (Mon, 05 May 2014) $
    $LastChangedRevision: 15050 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_plugin_replay.pro $

(See spedas_gui/utilities/spd_ui_plugin_replay.pro)

## SPD_UI_PROMPT_WIDGET.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_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 = spd_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

      frame_attr=frame_attr: Control the window appearance via TLB_FRAME_ATTR.  Values:
      1 Base cannot be resized, minimized, or maximized.
      2 Suppress display of system menu.
      4 Suppress title bar.
      8 Base cannot be closed.
      16 Base cannot be moved.
      For multiple effects add values together.
      There are differences between Linux and Windows, so test before using. TLB_FRAME_ATTR=8 seems to work everywhere.

    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: spd_ui_load_clob_prompt:
      3. If a parent widget is unavailable, statusbar, or historywin unavailable, you can pass null values
        result = spd_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:
    $LastChangedBy: aaflores $
    $LastChangedDate: 2015-03-12 17:12:52 -0700 (Thu, 12 Mar 2015) $
    $LastChangedRevision: 17128 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_prompt_widget.pro $

(See spedas_gui/utilities/spd_ui_prompt_widget.pro)

## SPD_UI_PWRSPC

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      spd_ui_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
      SPD_UI_DPROC.

    CALLING SEQUENCE:
      spd_ui_pwrspc, options,invars, loadedData, historyWin, statusBar,guiID

    INPUT:
      options: Structure that is output from SPD_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 spedas_gui/utilities/spd_ui_pwrspc.pro)

## SPD_UI_RUN_CALC

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_ui_run_calc

    PURPOSE:
     Function that interprets program for spd_ui_calculate

    CALLING SEQUENCE:
     spd_ui_run_calc,programtext,loadeddata,historywin,statusbar,error=error

    INPUT:
     programText: array of strings, text of program
     loadeddata: the loaded data object
     historywin: the historywin object
     statusbar: the statusbar object

    OUTPUT:
     error=error: set to named variable, will be 0 on success, will be set to error struct returned by calc.pro on failure

    HISTORY:
    $LastChangedBy: pcruce $
    $LastChangedDate: 2014-05-27 16:29:10 -0700 (Tue, 27 May 2014) $
    $LastChangedRevision: 15236 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_run_calc.pro $

(See spedas_gui/utilities/spd_ui_run_calc.pro)

## SPD_UI_SBAR_HWIN_UPDATE

[Previous Routine] [Next Routine] [List of Routines]

     Name
         spd_ui_sbar_hwin_update

     Purpose:
         Wrapper routine for updating the status bar and history window objects
         also handles dialog messages from error handlers

     Arguments:
         state: state structure from the top level widget, contains the history window and status bar objects
         message: string or array of strings to write to the history window and status bar objects
         /nohistoryWin: flag to turn off updating the history window object
         /nostatusBar: flag to turn off updating the status bar object
         /error: flag indicating an error sent us here
         err_msgbox_title: title to be displayed in the error msgbox

    $LastChangedBy: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_sbar_hwin_update.pro $

(See spedas_gui/utilities/spd_ui_sbar_hwin_update.pro)

## SPD_UI_SET_CURSOR

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_ui_set_cursor

    PURPOSE:
      Replaces the cursor on non-windows machines

    CALLING SEQUENCE:
     spd_ui_set_cursor,win

    INPUT:
     win: an IDLgrWindow

    OUTPUT:

    HISTORY:
    $LastChangedBy: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_set_cursor.pro $

(See spedas_gui/utilities/spd_ui_set_cursor.pro)

## SPD_UI_SPDF_REPLAY

[Previous Routine] [Next Routine] [List of Routines]

      spdfcdawebchooser GUI load code is structured in such a way that it would be very difficult to abstract.
      Instead just rewriting the load process in a way that isn't so dependent on pseudo-globals(via state)
      and gui elements, this way we can replay the data without needing the UI to be instantiated.

      In the future, we may want to consider replacing the cdawebchooser GUI code with this.
      as I'm forking a little bit here.

    $LastChangedBy: nikos $
    $LastChangedDate: 2024-05-30 15:22:29 -0700 (Thu, 30 May 2024) $
    $LastChangedRevision: 32663 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_spdf_replay.pro $

(See spedas_gui/utilities/spd_ui_spdf_replay.pro)

## SPD_UI_SPINNER

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
       SPD_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:
        VALUE: Initial value (float/double)
        INCREMENT: Numerical ammount spinner value is incremented/decremented
        LABEL: String to be used as the widget's label
        UNITS: String containing the units to appear to the right of the value
        SPIN_TIME: Delay before 'spinning' when clicking up/down buttons
        XLABELSIZE: Size of the text label in points
        getXLabelSize: Set to a named variable to pass back the length of the
                       spinner's label in points
        TEXT_BOX_SIZE: Size of the text box in # of characters
        TOOLTIP: String to be used at the buttons' tooltip
        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 spd_ui_spinner_set_max_value/spd_ui_spinner_set_min_value to change max_value, min_value.
       spd_ui_spinner_get_max_value/spd_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. spd_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)

    HISTORY:

    $LastChangedBy:  $
    $LastChangedDate:  $
    $LastChangedRevision:  $
    $URL: $

(See spedas_gui/utilities/spd_ui_spinner.pro)

## SPD_UI_SPLASH_WIDGET

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
             spd_ui_splash_widget

    PURPOSE:
             Widget for the SPEDAS GUI splash screen

    OUTPUT:
             ID of the widget, so it can be destroyed by the GUI
             on load

    $LastChangedBy: egrimes $
    $LastChangedDate: 2015-07-20 14:44:54 -0700 (Mon, 20 Jul 2015) $
    $LastChangedRevision: 18181 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_splash_widget.pro $

(See spedas_gui/utilities/spd_ui_splash_widget.pro)

## SPD_UI_TIMEFIX

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_ui_timefix
    PURPOSE:
     Will fix an input time string of yyyy-mm-dd hh:mm:ss.xxxx if there
     is only 1 digit in the day or hour or second, etc.
     Will also return an error message, if the months, days, hours,
     seconds are not valid.
     2011-07-20, added comment to test post-commit emails, jmm
     2011-11-04, added comment to test post-commit emails, jmm
    $LastChangedBy: egrimes $
    $LastChangedDate: 2015-03-12 11:46:50 -0700 (Thu, 12 Mar 2015) $
    $LastChangedRevision: 17121 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_timefix.pro $
    unction spd_ui_timefix, time_in, progobj = progobj, _extra = _extra

(See spedas_gui/utilities/spd_ui_timefix.pro)

## SPD_UI_TIME_WIDGET.PRO

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_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 = spd_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 spd_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
     startyear: optional keyword to change the start year for the calendar widget
                default start year is 2000

    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:

     $LastChangedBy: jwl $
     $LastChangedDate: 2022-02-24 16:22:15 -0800 (Thu, 24 Feb 2022) $
     $LastChangedRevision: 30616 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_time_widget.pro $

(See spedas_gui/utilities/spd_ui_time_widget.pro)

## SPD_UI_TRACK_ONE

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      spd_ui_track_one

    Purpose:
      Switches on single-panel tracking by setting the appropriate flags
      in the GUI's main storage structure.  This is a temporary solution
      until the tracking options can be re-worked.

    Calling Sequence:
      spd_ui_track_one, info_struct

    Input:
      info_struct:  The GUI's main storage structure.

    Output:
      none

    Notes:
      Moved from call sequence object.
        5/5/2014: Changed input argument from pointer to the main GUI's info struct to the actual struct.

    $LastChangedBy:  $
    $LastChangedDate:  $
    $LastChangedRevision:  $
    $URL:  $

(See spedas_gui/utilities/spd_ui_track_one.pro)

## SPD_UI_UPDATE_PROGRESS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_ui_update_progress
    PURPOSE:
     Write a string into the progress widget for the THEMIS GUI
    CALLING SEQUENCE:
     spd_ui_update_progress, gui_id, input_string
    INPUT:
     gui_id = the widget_id for the GUI
     input_string = a string to be displayed
    OUTPUT:
     None
    KEYWORDS:
     message_wid = id for any other message widgets that you might like
                    to display the messages
    HISTORY:
     jmm, 9-may-2007, jimm@ssl.berkeley.edu
     jmm, 5-mar-2008, added multiple lines, and the ability to show in
                      multiple message widgets.
    $LastChangedBy: nikos $
    $LastChangedDate: 2014-06-17 11:59:06 -0700 (Tue, 17 Jun 2014) $
    $LastChangedRevision: 15392 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_update_progress.pro $

(See spedas_gui/utilities/spd_ui_update_progress.pro)

## SPD_UI_USINGEXPONENT

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:
      spd_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

    4: hexadecimal

    Outputs:
    Determine format type:

(See spedas_gui/utilities/spd_ui_usingexponent.pro)

## SPD_UI_VALIDATE_FILE

[Previous Routine] [Next Routine] [List of Routines]

    PRO:
      spd_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: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_validate_file.pro $

(See spedas_gui/utilities/spd_ui_validate_file.pro)

## SPD_UI_WAVELET

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
     spd_ui_wavelet
    PURPOSE:
     wavelet transform of the input tplot variables, fist calls split_vec
     to split up any multi-component vectors.
    CALLING SEQUENCE:
     spd_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: nikos $
    $LastChangedDate: 2016-03-07 10:51:31 -0800 (Mon, 07 Mar 2016) $
    $LastChangedRevision: 20343 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_wavelet.pro $

(See spedas_gui/utilities/spd_ui_wavelet.pro)

## SPD_UI_WV_MEMORY_TEST

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
    spd_ui_wv_memory_test
    PURPOSE:
    Estimate of memory used by a wavelet transform. The estimated memory
    use is 36.26*n_elements(transformed_data.y). The factor of 36 comes
    from testing different transforms for different types of data, for
    fgm (FGH and FGS) data, 2009-01-14, for ESA L2 density data
    2007-07-07, and for GMAG data for both of those days. Note that this
    is currently only useful for default inputs.
    INPUT:
     t = the time array
    OUTPUT:
     jv = the number of wavelets to eventually be used, jv must be GT 1
          for the wavelet2 routine to work.
     prange = the default period range of the output,
              nyquist period, 5% of time period]
     info_txt = Informational test array, with memory sizes, and jv value
    HISTORY:
     10-jun-2009, jmm, added jv output to test for a reasonable number of
     wavelets later.
     19-Jan-2015, jmm, Changed the name and separated into a new file
     6-feb-2015, jmm, Added frange output, for the default frequency range
    $LastChangedBy: jimm $
    $LastChangedDate: 2015-02-09 13:28:13 -0800 (Mon, 09 Feb 2015) $
    $LastChangedRevision: 16922 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_ui_wv_memory_test.pro $

(See spedas_gui/utilities/spd_ui_wv_memory_test.pro)

## SPD_UNIQ

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      spd_uniq

    Purpose:
      Implement most common usage of IDL uniq() function

    Calling Sequence:
      output = spd_uniq(array)

    Input:
      array: An array

    Return Value:
      Sorted, unique values from input

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2015-08-06 20:01:43 -0700 (Thu, 06 Aug 2015) $
    $LastChangedRevision: 18419 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/spd_uniq.pro $

(See spedas_gui/utilities/spd_uniq.pro)

## STRINGISNUM

[Previous Routine] [Next Routine] [List of Routines]

    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.
    SPEDAS> print,stringisnum('hello')
           0
    SPEDAS> print,stringisnum('1.234')
           1
    SPEDAS> print,stringisnum('1.234e4')
           1
    SPEDAS> print,stringisnum('1B')
           1
    SPEDAS> print,stringisnum(' 1 ')
           1
    SPEDAS> print,stringisnum(' 1Hello ')
           0
    SPEDAS> print,stringisnum(' 1D ')
           1
    SPEDAS> 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: jimm $
    $LastChangedDate: 2014-02-11 10:54:32 -0800 (Tue, 11 Feb 2014) $
    $LastChangedRevision: 14326 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/spedas_gui/utilities/stringisnum.pro $

(See spedas_gui/utilities/stringisnum.pro)

## TEST_LEAP_YR

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           test_leap_yr
     CALLING SEQUENCE:
           lyr=test_leap_yr(iyr,modays=modays)
     PURPOSE:
           Determines whether a given year is a leap year, and
           returns the number of days in every month
     INPUT:
           iyr = The year, as an integer
     OUTPUT:
           lyr= 1 if iyr is a leap year and 0 if not
     KEYWORDS:
           modays= the number of days in each month
           modays= [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31] for
           a leap yr, [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31] otherwise
     HISTORY:
           Written 19-OCt-93 by JM
           Rewritten, 9-jul-2007, jmm

(See spedas_gui/utilities/spd_ui_timefix.pro)

## TVIMAGE

[Previous Routine] [Next Routine] [List of Routines]

     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 spedas_gui/utilities/tvimage.pro)

## TVREAD

[Previous Routine] [List of Routines]

     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 spedas_gui/utilities/tvread.pro)