This page was created by the IDL library routine
MK_HTML_HELP
. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? MK_HTML_HELP
at the IDL command line prompt. Last modified: Wed Nov 21 11:57:17 2001.
NAME: AdjustPosition PURPOSE: This is a program for interactively adjusting the plot position coordinates. The result of the function is a four-element floating point array of normalized coordinates, suitable for passing to the POSITION keyword of most IDL graphics commands. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com CATEGORY: Graphics CALLING SEQUENCE: position = AdjustPosition(startingPosition) OPTIONAL INPUTS: startingPosition - A four-element array of normalized coordinates of the form [x0, y0, x1, y1]. OUTPUTS: position - The adjusted plot position. A four-element array of normalized coordinates. INPUT KEYWORDS: GROUP_LEADER - The group leader of this program. This keyword is required to ensure modal operation when calling from another widget program. TITLE - The title of the window. "Adjust Plot Position in Window..." by default. XOFFSET - The X offset of the program on the display. Calculated from the upper left-hand corner of the display. YOFFSET - The Y offset of the program on the display. Calculated from the upper left-hand corner of the display. OUTPUT KEYWORDS: CANCEL - Returns a 1 if the user selects the Cancel button. Returns 0 otherwise. Note that if the use cancels, the "position" parameter is set to the value of the "startingPosition" parameter. DEPENDENCIES: Reqires FSC_FIELD and FSC_PLOTWINDOW from the Coyote Library: http://www.dfanning.com/programs/fsc_field.pro http://www.dfanning.com/programs/fsc_plotwindow.pro MODIFICATION HISTORY: Written by David Fanning, March 2001.
(See adjustposition.pro)
NAME: ASPECT PURPOSE: This function calculates and returns the normalized position coordinates necessary to put a plot with a specified aspect ratio into the currently active graphics window. It works on the display output window as well as in a PostScript output window. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: Graphics CALLING SEQUENCE: position = ASPECT(aspectRatio) INPUTS: aspectRatio: A floating point value that is the desired aspect ratio (ratio of heigth to width) of the plot in the current graphics output window. If this parameter is missing, an aspect ratio of 1.0 (a square plot) is assumed. KEYWORD PARAMETERS: MARGIN: The margin around the edges of the plot. The value must be a floating point value between 0.0 and 0.5. It is expressed in normalized coordinate units. The default margin is 0.15. WINDOWASPECT: The aspect ratio of the target window. If not provided, the value is obtained from the current graphics window. OUTPUTS: position: A four-element floating array of normalized coordinates. The order of the elements is [x0, y0, x1, y1], similar to the !P.POSITION system variable or the POSITION keyword on any IDL graphic command. EXAMPLE: To create a plot with an aspect ratio of 1:2 and a margin of 0.10 around the edge of the output window, do this: plotPosition = ASPECT(0.5, Margin=0.10) PLOT, Findgen(11), POSITION=plotPosition Notice this can be done in a single IDL command, like this: PLOT, Findgen(11), POSITION=ASPECT(0.5, Margin=0.10) MODIFICATION HISTORY: Written by: David Fanning, November 1996. Added better error checking, 18 Feb 1997, DWF. Added WindowAspect keyword. 10 Feb 2000. DWF Added double precision tolerance for aspectRatio. 9 NOV 2001 BT
(See aspect.pro)
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:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com CATEGORY: Utilities CALLING SEQUENCE: CenterTLB, tlb, [x, y, /NOCENTER] REQUIRED INPUTS: tlb: The top-level base identifier of the widget program. OPTIONAL INPUTS: x: Set this equal to a normalized position for the center of the widget as measured from the left-hand side of the screen. The default value is 0.5 (the center) Setting this equal to 1.0 places the widget at the far right-hand side of the screen. y: Set this equal to a normalized position for the center of the widget as measured from the bottom of the screen. The default value is 0.5 (the center) Setting this equal to 1.0 places the widget at the top of the screen. KEYWORDS: NOCENTER: By default, the center of the widget is positioned at the location specified by the x and y parameters. If NOCENTER is set to a non-zero value, then the upper left corner of the widget is postioned at the specifed location. PROCEDURE: The program should be called after all the widgets have been created, but just before the widget hierarchy is realized. It uses the top-level base geometry along with the display size to calculate offsets for the top-level base that will center the top-level base on the display. COMMENT: Regardless of the values set for x, y and NOCENTER, the widget is not permitted to run off the display. MODIFICATION HISTORY: Written by: Dick Jackson, 12 Dec 98. Modified to use device-independent Get_Screen_Size function. 31 Jan 2000. DWF. Added x, y, NOCENTER and run-off protection. 26 Jan 2001. BT. ########################################################################### LICENSE This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative. Copyright © 1998-2000 Fanning Software Consulting This software is provided "as-is", without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions: 1. The origin of this software must not be misrepresented; you must not claim you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated, but is not required. 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source distribution. For more information on Open Source Software, visit the Open Source web site: http://www.opensource.org. ###########################################################################
(See centertlb.pro)
NAME: CHGCOLOR PURPOSE: The purpose of this routine is to allow the user to change the color at a particular color index. The user is able to mix their own color by manipulating red, green, and blue sliders. This routine is ideal for changing axes or background colors of a plot, for example. The routine works on 8-bit, 16-bit, and 24-bit displays. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com CATEGORY: Widgets, Colors. CALLING SEQUENCE: CHGCOLOR, index REQUIRED INPUTS: INDEX: The color index to be changed. It must be a value between 0 and 255. KEYWORD PARAMETERS: LABEL: Text that goes next to the color window. The default is "Resulting Color". GROUP_LEADER: The group leader for this program. When the group leader is destroyed, this program will be destroyed. NOTIFYID: A a 2 column by n row array that contains the IDs of widgets that should be notified when CHGCOLOR changes a color. The first column of the array contains widgets that should be notified. The second column contains IDs of widgets that are at the top of the hierarch in which the corresponding widgets in the first column are located. (The purpose of the top widget IDs is to make it possible for the widget in the first column to get the "info" structure of the widget program.) An CHGCOLOR_LOAD event will be sent to the widget identified in the first column. The event structure is defined like this: event = {CHGCOLOR_LOAD, ID:0L, TOP:0L, HANDLER:0L, $ r:(!D.N_COLORS < 256), g:(!D.N_COLORS < 256), b:(!D.N_COLORS < 256)} The ID field will be filled out with NOTIFYID(0, n) and the TOP field will be filled out with NOTIFYID(1, n). TITLE: This is the window title. It is "Modify Drawing Color" by default. The program is registered with the name "chgcolor " plus the TITLE string. The register name is checked before the widgets are defined. This gives you the opportunity to have multiple copies of CHGCOLOR operating simultaneously. (For example, one will change the background color and one will change the plotting color.) XOFFSET: This is the X offset of the program on the display. The program will be placed approximately in the middle of the display by default. YOFFSET: This is the Y offset of the program on the display. The program will be placed approximately in the middle of the display by default. COMMON BLOCKS: None. SIDE EFFECTS: Color at the specified index is changed. Events are sent to widgets if the NOTIFYID keyword is used. RESTRICTIONS: None. EXAMPLE: To change the background color of a plot, type: CHGCOLOR, !P.Background To see a more complete example, look at the program SLICE in the Coyote Software Library: ftp://ftp.frii.com/pub/dfanning/outgoing/idl_examples MODIFICATION HISTORY: Written by David Fanning, 23 April 97. 12 May 97, Fixed a bug in the way colors were loaded when a tracking event occurred. DWF 13 May 97, Added a JUST_REGISTER keyword and set it up for running in IDL 5.0 as a non-blocking widget. 27 Sept 98. Fixed problems caused by IDL 5.1 color changes. 27 Sept 98. Removed JUST_REGISTER keyword. Made widget non-blocking. 03 Nov 98. Modified layout and added slider ganging. DWF.
(See chgcolor.pro)
NAME: CIndex PURPOSE: This is a program for viewing the current colors in the colortable with their index numbers overlayed on each color. On 24-bit systems you must click the cursor in the graphics window to see the colors in the current color table. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com CATEGORY: Graphics CALLING SEQUENCE: CIndex INPUTS: None. Optional Inputs: None OUTPUTS: None OPTIONAL OUTPUTS: None KEYWORD Parameters: None COMMON BLOCKS: None SIDE EFFECTS: None RESTRICTIONS: Reqires XCOLORS and TVIMAGE from the Coyote Library: http://www.dfanning.com/programs/xcolors.pro http://www.dfanning.com/programs/xtvimage.pro PROCEDURE: Draws a 31x25 set of small rectangles in 256 different colors. Writes the color index number on top of each rectangle. MODIFICATION HISTORY: Written by David Fanning, May 1995 Widgetized and made it work in 24-bit color. Colors are updated by clicking in window. 22 Oct 98. DWF Replace POLYFILL with TV command to avoid underflow error in Z-buffer. 8 March 99. DWF Fixed a problem with 24-bit devices with color decomposition ON. 15 Feb 2000. DWF.
(See cindex.pro)
NAME: CLIPBOARD PURPOSE: The purpose of this program is to copy the contents of a graphics window to the clipboard for subsequent pasting into applications such as Photoshop or Powerpoint. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: Graphics. CALLING SEQUENCE: CLIPBOARD, window_index OPTIONAL INPUTS: window_index: The window index number of the graphics window to copy. If absent, the current graphics window is used by default. OUTPUTS: None. COMMON BLOCKS: None. DEPENDENCIES: Uses the IDLgrClipboard object introduced in IDL 5.2(?). PROCEDURE: Copies the window contents to a clipboard object. EXAMPLE: IDL> Window IDL> Plot, Findgen(11) IDL> CLIPBOARD RESTRICTIONS: May not work for all applications. Applications tested successfully include: Framemaker, Powerpoint, Photoshop, Excel, Microsoft Word. Converts 24-bit images to 2D images with color tables. MODIFICATION HISTORY: Written by: David W. Fanning, 24 October 2001.
(See clipboard.pro)
NAME: COLOR24 PURPOSE: The purpose of this function is to convert a RGB color triple into the equivalent 24-bit long integer. The 24-bit integer can be decomposed into the appropriate color by interpreting the lowest 8 bits as red, the middle 8 bits as green, and the highest 8 bits as blue. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: Graphics, Color Specification. CALLING SEQUENCE: color = COLOR24(rgb_triple) INPUTS: RGB_TRIPLE: A three-element column or row array representing a color triple. Or an N-by-three element array of color triples. The values of the elements must be between 0 and 255. KEYWORD PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None. EXAMPLE: To convert the color triple for the color YELLOW, (255, 255, 0), to the hexadecimal value '00FFFF'x or the decimal number 65535, type: color = COLOR24([255, 255, 0]) This routine was written to be used with device-independent color programs like GETCOLOR. MODIFICATION HISTORY: Written by: David Fanning, 3 February 96. Completely revised the algorithm to accept color arrays. 19 October 2000. DWF.
(See color24.pro)
NAME: COLORBAR PURPOSE: The purpose of this routine is to add a color bar to the current graphics window. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>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.15, 0.95, 0.95] for a vertical bar and [0.15, 0.88, 0.95, 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. 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.  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 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.
(See colorbar.pro)
NAME: COLORBAR__DEFINE PURPOSE: The purpose of this routine is to implement a COLORBAR object class. The ColorBar is rendered in the direct graphics system. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com CATEGORY: Graphics. CALLING SEQUENCE: colorbar = Obj_New("COLORBAR") INPUTS: All inputs to the program are via keyword parameters. KEYWORD PARAMETERS: Background: Background color. This is the color with which the colorbar is erased. The default color is !P.Background. Bottom: Bottom color index of colors allocated to colorbar. Charsize: Character size of annotation. Default is 1.0. Color: Color of annotation and outline. Default is !P.Color. Font: Font to use for annotation. Default is -1, Hershey fonts. Format: Format of annotation. Default is "(F8.2)". Major: The number of major tick intervals. Default is 5. Minor: The number of minor tick intervals. Default is 2. MinusOne: Set this keyword to choose MinusOne keyword on the Congrid command that resizes the colorbar into the window. NColors: The number of colors allocated to colorbar. Default is (256 < !D.N_Colors). Neighbor: Set to indicate Nearest Neighbor sampling for Congrid. Default is 0 (Bilinear). Position: The position of colorbar in normalized coordinates. Default for a horizontal colorbar is [0.15, 0.88, 0.85, 0.95]. Default for a vertical colorbar is [0.88, 0.15, 0.95, 0.85]. These defaults are designed for a 400 by 400 window. Range: The data range on colorbar. Default is [0, 255]. TickLen: The length of tick marks. Default is -0.1 TickV: Locations for the tick marks in data units. This is the same as the [XY]TickV keyword. Default is to do what IDL would do normally. Vertical: Set this keyword if you want a vertical colorbar. Default is horizontal. XEraseBox: A five-element vector of X points (normalized) for erasing the colorbar plot. Normally this keyword will not have to be used. The program uses the plot REGION for erasing. But larger character sizes can result in annotation going outside the region enclosed by the plot. If that is the case, then use this keyword along with YEraseBox to specify a larger-than-normal erasure area. The points are sent to the POLYFILL command for erasing. POLYFILL, xEraseBox, yEraseBox, /Normal, Color=background YEraseBox: A five-element vector of Y points (normalized) for erasing the colorbar plot. OBJECT METHODS: Clamp: This procedure method allows the color bar range to be "clamped" to a particular data range. Draw: This procedure method draws the colorbar in the display window. The ERASE keyword to this method will erase the current colorbar (by calling the ERASE method) before drawing the colorbar in the display window. colorbar->Draw Erase: This procedure method erases the colorbar object in the window. It accomplishes this by performing a POLYFILL in the background color. This method is primarily useful for interactive graphics display devices. colorbar->Erase GetProperty: This procedure method allows one to obtain the current state of the object via the keyword parameters listed above. colorbar->GetProperty, Range=currentRange, Title=currentTitle Print, currentRange, currentTitle SetProperty: This procedure method allows one to set the properties of the colorbar object via the keywords described above. In addition, a DRAW and ERASE keyword are provided so that the colorbar can be immediately drawn when the new property is set. colorbar->SetProperty, Range=[500, 15000], /Erase, /Draw COMMON BLOCKS: None. SIDE EFFECTS: The display window is not erased first. RESTRICTIONS: None. EXAMPLE: To create a colorbar, use it, then destroy it, type: colorbar = Obj_New("COLORBAR", Title='Colorbar Values', Range=[0,1000],$ Format='(I4)') Window LoadCT, 5 colorbar->Draw colorbar->SetProperty, Range=[0,500], /Erase, /Draw Obj_Destroy, colorbar MODIFICATION HISTORY: Written by: David Fanning, Fanning Software Consulting, 26 November 1998. Added Horizontal keyword to SetProperty method and fixed problem in going from Vertical to Horizontal color bars. 29 Nov 1998. DWF. Added LoadCT method and current color table index to object. 6 December 1998. Fixed a bug dealing with nearest neighbor resampling. 30 Mar 1999. DWF. Fixed a bug with how NCOLORS and BOTTOM keywords interacted. 29 Aug 1999. DWF. 10 Oct 99. Modified the program so that current plot and map coordinates are saved and restored after the colorbar is drawn. DWF. 26 May 2000 Added {XY}TICKV capability to the draw method. This required adding TickV to the object data structure, and to the INIT, GetProperty and SetProperty methods. Changed default tick length to -0.1. DWF (and Jack Saba) 18 Nov 2001. Added Clamp method. DWF.
(See colorbar__define.pro)
NAME: CONTRASTZOOM PURPOSE: The purpose of this program is to demonstrate how to zoom an image "in place" and how to window and level (set "contrast and brightness") an image using object graphics functionality. The exercise involves using multiple views in an object graphics scene, and being able to interact with different views in different ways. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com CATEGORY: Widgets, Object Graphics. CALLING SEQUENCE: ContrastZoom, image REQUIRED INPUTS: None. The image "mr_knee.dcm" from the examples/data directory is used if no data is supplied in call. OPTIONAL INPUTS image: A 2D image array of any data type. OPTIONAL KEYWORD PARAMETERS: COLORTABLE: The number of a color table to use as the image palette. Color table 0 (grayscale) is used as a default. GROUP_LEADER: The group leader for this program. When the group leader is destroyed, this program will be destroyed. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None. The Coyote Library program VCOLORBAR is included. EXAMPLE: To use this program with your 8-bit image data and a red-temperature color scale, type: IDL> ContrastZoom, image, Colortable=3 NOTES: The left image is used to "zoom" into a portion of the image. The aspect ratio of the sub-image is always preserved. To see the entire image, click and release the mouse button in this window. The center image is used to adjust the contrast and brightness (sometimes called the "window" and "level" of the image. Click and drag the mouse vertically to set contrast. Click and drag the mouse horizontally to set brightness. To return to original values (25% contrast and 75% brightness), click and release in the center image. The color bars shows the image values of the image. MODIFICATION HISTORY: Written by David Fanning, 18 November 2001. Added second colorbar to show the relationship of the clamped colors to the overall image values. 19 November 2001. DWF.
(See contrastzoom.pro)
NAME: COYOTE_FIELD PURPOSE: The purpose of this compound widget is to provide an alternative to the CW_FIELD widget offered in the IDL distribution. What has always annoyed me about CW_FIELD 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 would be helpful. For example, you can now assign an event handler to the compound widget. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: General programming. CALLING SEQUENCE: fieldID = COYOTE_Field(parent, Title='X Size: ", Value=256, /IntegerValue) 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. CR_Only -- Set this keyword if you only want Carriage Return events. If this keyword is not set, all events are returned. No events are returned unless the EVENT_PRO or EVENT_FUNC keywords are used. DoubleValue -- Set this keyword if you want DOUBLE values returned. 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 -- Set this keyword to the name of an Event 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 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. FloatValue -- Set this keyword for FLOAT values. Frame -- Set this keyword to put a frame around the compound widget. IntegerValue -- Set this keyword for INTEGER values. LabelFont -- The font name for the text in the Label Widget. LabelSize -- The X screen size of the Label Widget. LongValue -- Set this keyword for LONG values. Row=row -- Set this keyword to have the Label beside the Text Widget. (The default.) Scr_XSize -- The X screen size of the compound widget. Scr_YSize -- The Y screen size of the compound widget. StringValue -- Set this keyword for STRING values. (The default.) 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. COMMON BLOCKS: None. RESTRICTIONS: None. 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 = { COYOTE_FIELD, $ ; 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. Value: Ptr_New(), $ ; A pointer to the widget value. Type:"" ; A string indicating the type of data in the VALUE field. } ; Values are "INT", "LONG", "FLOAT", "DOUBLE", or "STRING". EXAMPLE: An example program is provided at the end of the COYOTE_FIELD code. To run it, type these commands: IDL> .Compile COYOTE_Field IDL> Example MODIFICATION HISTORY: Written by: David Fanning, 17 NOV 1999. Added check to make float and double values finite. 18 NOV 1999. DWF. Fixed a bug when selecting and deleting all numerical text. 19 NOV 1999. DWF. Added DECIMAL and DIGITS keywords. 2 Jan 2000. DWF. Added the POSITIVE keyword. 12 Jan 2000. DWF. Fixed a few minor bugs with delete and digits. 12 Jan 2000. DWF. Made GET_VALUE function return pointer to data, instead of data. 12 Jan 2000. DWF. Fixed a small typo: "aveDecimal" to "haveDecimal". 10 March 2000. DWF. Fixed a small problem with the Example program. 7 Oct 2000. DWF.
(See coyote_field.pro)
NAME: DRAWCOLORS FILENAME: drawcolors__define.pro PURPOSE: The purpose of this object program is provide a flexible way to handle and select drawing colors. The program combines features of two previous programs: GetColor and PickColor, as well as adding features of its own. Sixteen original colors are supplied, but users can create any color they wish using the tools provided. By default, these 16 colors are defined: Black, Magenta, Cyan, Yellow, Green, Red, Blue, Navy, Aqua, Pink, Orchid, Sky, Beige, Charcoal, Gray, White. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 2642 Bradbury Court Fort Collins, CO 80521 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: General programming. CALLING SEQUENCE: colors = Obj_New('DRAWCOLORS') OPTIONAL INPUT PARAMETERS: IDL> colors = Obj_New('DRAWCOLORS', red, green, blue, names) RED -- A 16-element byte vector of red values for the drawing colors. GREEN -- A 16-element byte vector of green values for the drawing colors. BLUE -- A 16-element byte vector of blue values for the drawing colors. NAMES -- A 16-element string vector of names for the drawing colors. By default, these colors are defined: Black, Magenta, Cyan, Yellow, Green, Red, Blue, Navy, Aqua, Pink, Orchid, Sky, Beige, Charcoal, Gray, White. COMMON BLOCKS: None. RESTRICTIONS: If you are going to use the XCOLORS method, you will need the XColors program from the Coyote library: http://www.dfanning.com/programs/xcolors.pro The program is set up to handle 16 drawing colors. You may modify the program to have a different number, but you will have to modify the code in two places: (1) in the drawcolors__define module and (2) in the INIT method. FUNCTION METHODS: COLOR24 *************************************************************************** Purpose: Turns a color triple into the equivalent 24-bit color integer value that can be decomposed into the color. Definition: FUNCTION DrawColors::Color24, theColor Parameters: theColor -- A 3-element vector, representing a color triple. Example: yellow = colors->GetColor("yellow") yellow24 = colors->Color24(yellow) GETCOLOR *************************************************************************** Purpose: Returns the color triple, color index number, or the 24-bit integer representation, of the asked for color. In normal operation, the colors are: Black, Magenta, Cyan, Yellow, Green, Red, Blue, Navy, Aqua, Pink, Orchid, Sky, Beige, Charcoal, Gray, and White. Definition: FUNCTION DrawColors::GetColor, theColor, startIndex, INDEXNUMBER=indexnumber, $ TRUECOLOR=truecolor, AutoDetermine=autodetermine Parameters: theColor -- A string representing the "name" of the color. If the name can't be resolved or found, the first color is returned. startIndex -- If present, and INDEXNUMBER is set, the colors are loaded at this index number. Otherwise, the self.startIndex is used. Keywords: AUTODETERMINE -- If this keyword is set. the state of DECOMPOSITION is determined (IDL 5.2 and higher) and either the INDEXNUMBER or TRUECOLOR keyword is set appropriately. If the decomposition state cannot be determined, the INDEXNUMBER keyword is set. INDEXNUMBER -- If this keyword is set the colors are loaded and the index number of the color is returned. TRUECOLOR -- If this keyword is set, the color triple is converted into a 24-bit integer before being returned. This keyword is ignored if the INDEXNUMBER keyword is set. Examples: drawColor = colors->GetColor("yellow") drawColor = colors->GetColor("blue", /Indexnumber) drawColor = colors->GetColor("sky", /Truecolor) GETCOLORS ************************************************************************** Purpose: Returns the color triples, the color index numbers of, or the 24-bit integer representations of, all the colors. Definition: FUNCTION DrawColors::GetColors, startindex, INDEXNUMBER=indexnumber, $ TRUECOLOR=truecolor, Structure=structure Parameters: startIndex -- If present, and INDEXNUMBER is set, the colors are loaded at this index number. If absent, startIndex = self.startIndex. Keywords: INDEXNUMBER -- If this keyword is set the colors are loaded and the index numbers of all the colors are returned. STRUCTURE -- If this keyword is set, the return value is a structure, where each field of the structure is a color name and the value of each field is either a color triple, an index number, or a 24-bit color value, depending upon the state of other keywords. TRUECOLOR -- If this keyword is set, the color triples are converted to 24-bit integers before being returned. This keyword is ignored if the INDEXNUMBER keyword is set. Examples: drawColors = colors->GetColors() ; drawColors is a 16-by-3 byte array. drawColors = colors->GetColors(/IndexNumber) ; drawColors is a 16-element array of color indices. drawColors = colors->GetColors(/TrueColor) ; drawColors is a 16-element array of 24-bit integers. drawColors = colors->GetColors(/IndexNumber, /Structure) ; drawColors is a structure of index numbers. Plot, data, Color=drawColors.yellow, Background=drawColors.charcoal SELECT ************************************************************************** Purpose: Puts up a blocking or modal widget dialog, allowing the user to select from one of the 16 predefined colors available, or to mix their own color. The user-defined color triple is returned as a result of the function. Definition: FUNCTION DrawColors::Select, Color=currentColor, StartIndex=startIndex, $ Title=title, Group_Leader=groupLeader, Cancel=cancelled, TrueColor=truecolor Keywords: CANCEL -- An output keyword that will return a value of 1 if the CANCEL button is selected or if program operation is interrupted in any way. COLOR -- The index number in the color table, where the current color will be mixed. In other words, this color index will change when the program is on the display. It will be restored to its previous or entry color when the program exits. GROUP_LEADER -- The group leader for the program. This keyword *must* be set if calling this method from within a widget program if you expect MODAL program operation. NAME -- If this keyword is set, the return value of the function is the "name" of the color. STARTINDEX -- This is the starting index in the color table where the 16 predetermined colors will be loaded. The original colors will be restored when the program exits. By default, this is set to !D.Table-Size - (NCOLORS + 1). TITLE -- The title of the program. By default: "Pick a Color" TRUECOLOR -- If this keyword is set, the return value of the function is a 24-bit eqivalent integer rather than the color triple. Examples: newColor = colors->Select() ; A blocking widget. newColor = color->Select(Group_Leader=event.top, Cancel=cancelled) IF NOT cancelled THEN TVLCT, newColor, info.dataColor PROCEDURE METHODS: GETPROPERTY *********************************************************************** Purpose: Allows the user to obtain the current properties of the object. Definition: PRO DrawColors::GetProperty, NAMES=names, RED=red, GREEN=green, BLUE=blue, $ STARTINDEX=startindex, NCOLORS=ncolors Keywords: NAMES -- Returns the current names of the colors as a string array. RED -- Returns the current red values of the colors. GREEN -- Returns the current green values of the colors. BLUE -- Returns the current blue values of the colors. STARTINDEX -- Returns the current starting index in the color table. NCOLORS -- Returns the number of colors. Example: colors->GetProperty, Names=colorNames Print, colorNames LOADCOLORS ************************************************************************ Purpose: Loads the predefined colors at a starting index. Definition: PRO DrawColors::LoadColors, startindex Parameters: STARTINDEX -- The starting color index in the color table. If not provided, is set to !D.Table_Size - (self.ncolors + 1). Example: colors->LoadColors, 16 ORIGINALCOLORS ********************************************************************* Purpose: Reloads the original 16 colors and their names Definition: PRO DrawColors::OriginalColors Parameters: None Example: colors->OriginalColors REFRESH *************************************************************************** Purpose: Refreshes the modal GUI with the current drawing colors. Definition: PRO DrawColors::Refresh Parameters: None Example: colors->Refresh SETPROPERTY *********************************************************************** Purpose: Allows the user to set the current properties of the object. Definition: PRO DrawColors::SetProperty, NAMES=names, RED=red, GREEN=green, BLUE=blue, $ STARTINDEX=startindex, NCOLORS=ncolors Keywords: NAMES -- The current names of the colors as a string array. RED -- The current red values of the colors. GREEN -- The current green values of the colors. BLUE -- The current blue values of the colors. STARTINDEX -- The current starting index in the color table. NCOLORS -- The number of colors. Example: colorNames = 'Color ' + StrTrim(SIndGen(16),2) colors->SetProperty, Names=colorNames XCOLORS *************************************************************************** Purpose: Allows the user to select 16 new colors for the program by using the XCOLORS program. The XColors program must be somewhere in your !PATH. Definition: PRO DrawColors::XColors Parameters: None Example: colors->XColors TUTORIAL: Here is a short tutorial in how this object can be used. Note that this doesn't exhaust all the possibilities. 1. Create the object. IDL> colors = Obj_New("DrawColors") 2. Find out what colors it knows about. IDL> colors->GetProperty, Names=colorNames IDL> Print, colorNames 3. Ask for a color by name and load it at a color index. Draw a plot in that color. IDL> yellow = colors->GetColor("yellow") IDL> TVLCT, yellow, 200 IDL> Device, Decomposed=0 IDL> Plot, Findgen(11), Color=200 4. Do the same thing, but in DECOMPOSED color. IDL> Device, Decomposed=1 IDL> green = colors->GetColor("green", /TrueColor) IDL> Plot, Findgen(11), Color=green 5. Find the color index number of the sky blue color. IDL> Device, Decomposed=0 IDL> skyIndex = colors->GetColor("sky", /IndexNumber) IDL> Plot, Findgen(11), Color=skyIndex 6. Load all 16 drawing colors at color index 32. IDL> colors->LoadColors, 32 IDL> CIndex ; If them, if you have CINDEX from my library. 7. Get a structure of colors, with each field set to the appropriate index number of its associated color. IDL> Device, Decomposed=0 IDL> col = colors->GetColors(/IndexNumber, /Structure) IDL> Plot, Findgen(11), Color=col.yellow, Background=col.charcoal 8. Allow the user to select a color from a GUI, then load it and use it. IDL> Device, Decomposed=0 IDL> theColor = colors->Select(Cancel=cancelled) IDL> IF NOT cancelled THEN TVLCT, theColor, 10 IDL> Plot, Findgen(11), Color=10 9. Allow the user to choose 16 new drawing colors. (Requires my XCOLORS program.) IDL> colors->XColors IDL> theseColors = colors->Select() 10. Let the object decide according to the device decomposition state whether to return an index number or 24-bit value for the color. IDL> Plot, Findgen(11), Color=colors->GetColor('beige', /Autodetermine) 11. Call the GUI from within a widget program and load the new color. newcolor = info.colors->Select(Group_Leader=event.top, $ Cancel=cancelled) IF NOT cancelled THEN TVLCT, newcolor, info.drawColor 12. Destroy the object. IDL> Obj_Destroy, colors MODIFICATION HISTORY: Written by: David Fanning, 9 NOV 1999. Added AUTODETERMINE keyword to the GetColor method. 10 NOV 1999. DWF. Added NAME keyword to SELECT method. 18 MAR 2000. DWF. Fixed a small bug in choosing the current color. 20 April 2000. DWF.
(See drawcolors__define.pro)
NAME: ERROR_MESSAGE PURPOSE: The purpose of this function is to have a device-independent error messaging function. The error message is reported to the user by using DIALOG_MESSAGE if widgets are supported and MESSAGE otherwise. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: Utility. CALLING SEQUENCE: ok = Error_Message(the_Error_Message) INPUTS: the_Error_Message: This is a string argument containing the error message you want reported. If undefined, this variable is set to the string in the !Error_State.Msg system variable. KEYWORDS: NONAME: If this keyword is set the name of the calling routine is not printed along with the message. TRACEBACK: Setting this keyword results in an error traceback being printed to standard output with the PRINT command. In addition, any keyword appropriate for the MESSAGE or DIALOG_MESSAGE routines can also be used. OUTPUTS: Currently the only output from the function is the string "OK". RESTRICTIONS: The "Warning" Dialog_Message dialog is used by default. Use keywords /ERROR or /INFORMATION to select other dialog behaviors. EXAMPLE: To handle an undefined variable error: IF N_Elements(variable) EQ 0 THEN $ ok = Error_Message('Variable is undefined', /Traceback) MODIFICATION HISTORY: Written by: David Fanning, 27 April 1999. Added the calling routine's name in the message and NoName keyword. 31 Jan 2000. DWF. Added _Extra keyword. 10 February 2000. DWF. Forgot to add _Extra everywhere. Fixed for MAIN errors. 8 AUG 2000. DWF. Adding call routine's name to Traceback Report. 8 AUG 2000. DWF. Switched default value for Dialog_Message to "Error" from "Warning". 7 OCT 2000. DWF.
(See error_message.pro)
NAME: FSC_COLOR PURPOSE: The purpose of this function is to obtain drawing colors by name and in a device-decomposition independent way. The color names and values may be read in as a file, or 88 color names and values are supplied from the program. These were obtained from the file rgb.txt, found on most X-Window distributions. Representative colors were chose from across the color spectrum. To see a list of colors available, type: Print, FSC_Color(/Names). AUTHOR: FANNING SOFTWARE CONSULTING: David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>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: 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 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. Valid names depend on the colors loaded in the program, but typically include such these colors as these: Black Pink Magenta Aqua Cyan SkyBlue Yellow Beige Green Charcoal Red Gray Blue Orchid Navy White The color WHITE is used if this parameter is absent. To see a list of the color names available in the program, type this: Print, FSC_COLOR(/Names) TheColorIndex: The color table index 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. RETURN VALUE: The value that is returned by FSC_COLOR depends upon the keywords used to call it and on the version of IDL you are using. 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. 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. 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. 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) MODIFICATION HISTORY: Written by: David 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.
(See fsc_color.pro)
NAME: FSC_DROPLIST PURPOSE: The purpose of this compound widget is to provide an alternative to the DROPLIST widget offered in the IDL distribution. What has always annoyed me about a droplist is that you can't get the current "value" of a droplist easily. This compound widget makes this and other tasks much easier. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: General programming. CALLING SEQUENCE: droplistObj = FSC_Droplist(parent, Title='Animals: ", Value=['Dog'. 'Cat', 'Coyote'], Index=2) The return value of the FSC_Droplist (droplistObj in this example) is an object reference. Interaction with the droplist will occur through object methods. INPUT PARAMETERS: parent -- The parent widget ID of the compound widget. Required. INPUT KEYWORDS: Any keyword that is appropriate for the Widget_Droplist function can be used. In addition, these keywords are explicitly defined. EVENT_FUNC -- Set this keyword to the name of an Event Handler Function. EVENT_PRO -- Set this keyword to the name of an Event Handler Procedure. FORMAT -- A format specifier for the "format" of the values in the droplist. INDEX -- The index number of the current selection. SPACES -- A two-element array that indicates the number of blank spaces to be added to the the beginning and end of the formatted values. If a single number is provided, this number of blank spaces is added to both the beginning and the end of the value. TITLE -- The title of the droplist widget. UNAME -- The user name of the droplist widget. (Only available in IDL 5.2 and higher.) UVALUE -- The normal "user value" of the droplist. VALUE -- An array of the droplist "selections". May be any data type. COMMON BLOCKS: None. DEPENDENCIES: Requires ERROR_MESSAGE from the Coyote Library.. EVENT STRUCTURE: An event is returned each time the droplist value is changed. The event structure is defined like this: event = { FSC_DROPLIST_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. INDEX: 0L, $ ; The index number of the current selection. SELECTION:Ptr_New() $ ; A pointer to the current selection "value". SELF:Obj_New() } ; The object reference of the compound widget. PUBLIC OBJECT METHODS: GetID -- A function with no arguments that returns the widget identifier of the droplist widget. droplistID = droplistObj->GetID() GetIndex -- A function with no arguments that returns the index number of the current droplist selection. currentIndex = droplistObj->GetIndex() GetSelection -- A function with no arguments that returns the current droplist selection. currentSelection = droplistObj->GetSelection() GetUValue -- A function with no arguments that returns the "user value" of the compound widget i.e., the value set with the UVALUE keyword). myUValue = droplistObj->GetUValue() GetValues -- A function with no arguments that returns the "values" or "selections" for the droplist. possibleSelections = droplistObj->GetValues() Resize -- A procedure that sets the X screen size of the droplist. It is defined like this: PRO Resize, newSize, ParentSize=parentSize The "newSize" keyword is the new X screen size. If this argument is missing, the screen X size of the compound widget's parent is used. The parentSize keyword is an output keyword that returns the X screen size of the compound widget's parent. droplistObj->Resize, 400 Note that not all devices (e.g., X Windows devices) support droplist resizing. SetIndex -- A procedure that sets the current droplist selection based on the given index. This is equivalent to Widget_Control, droplistID, Set_Droplist_Select=newIndex droplistObj->SetIndex, newIndex SetSelection -- Whereas a regular droplist widget can only be set by index number, this compound widget can also be set by a "selection". The new selection can be any data type and corresponds to one of the "values" of the droplist. droplistObj->SetSelection, newSelection EXAMPLE: An example program is provided at the end of the FSC_DROPLIST code. To run it, type these commands: IDL> .Compile FSC_DROPLIST IDL> Example MODIFICATION HISTORY: Written by: David Fanning, 17 Jan 2000. DWF. Added FORMAT and SPACES keywords 28 April 2000. DWF. Fixed a small problem with event processing when the EVENT_FUNC keyword was used. 29 Dec 2000. DWF. Attached the UNAME value to the TLB of the compound widget instead of to the droplist widget itself. 11 Jan 2001. DWF.
(See fsc_droplist.pro)
NAME: FSC_FIELD PURPOSE: The purpose of this compound widget is to provide an alternative to the CW_FIELD widget offered in the IDL distribution. One weakness of the CW_FIELD compound widget is that the text widgets do not look editable to the users on Windows platforms. This program corrects that deficiency and adds some features that I think will be helpful. For example, you can now assign an event handler to the compound widget, ask for positive numbers only, and limit the number of digits in a number, or the number of digits to the right of a decimal point. The program is written as a widget object, which allows the user to call object methods directly, affording even more flexibility in use. This program replaces the earlier programs FSC_INPUTFIELD and COYOTE_FIELD. The program consists of a label widget next to a one-line text widget. The "value" of the compound widget is shown in the text widget. If the value is a number, it will not be possible (generally) to type alphanumeric values in the text widget. String values behave like strings in any one-line text widget. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>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. 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: None. 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. Name -- A scalar string name of the object. NoEdit -- A 1 means the widget is non-editable. NonSensitive -- A 1 means the widget is non-sensitive. NonSensitive -- Set this keyword to make the widget non-sensitive. Positive -- Indicates if the Positive number flag is set (1) or not (0). UValue -- The user value assigned to the compound widget. Value -- The "value" of the compound widget. 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. 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 SetEdit -- This procedure turns editing on (value of 1) or off (value of 0). 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 FLOATVALUE and DOUBLEVALUE numbers. Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE 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. 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 widget non-editable. NonSensitive -- Set this keyword to make the widget non-sensitive. Positive -- Set this keyword to indicate only positive numbers are allowed. 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. SetSensitive -- This procedure turns text widget sensitivity on (value of 1) or off (value of 0). OBJECT FUNCTION 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 cursor to end of the text in the widget identified by the nexttab field. (This will be set with the SetTabNext method.) 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 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.
(See fsc_field.pro)
NAME: FSC_FILESELECT PURPOSE: The purpose of this compound widget is to provide a means by which the user can type or select a file name. The program is written as an "object widget", meaning that the guts of the program is an object of class FSC_FILESELECT. This is meant to be an example of the obvious advantages of writing compound widget programs as objects. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: General programming. CALLING SEQUENCE: filenameID = FSC_FileSelect(parent) INPUT PARAMETERS: parent -- The parent widget ID of the compound widget. Required. INPUT KEYWORDS: Event_Pro -- The event handler procedure for this compound widget.By default: "". Event_Func -- The event handler function for this compound widget. By default: "". If neither EVENT_PRO or EVENT_FUNC is defined, program events are handled internally by the compound widget. DirectoryName -- The initial name of the directory. By defaut: current directory. Filename -- The initial file name in the filename text widget. Filter -- The file filter. By default: "*". Frame -- Set this keyword for a frame around the compound widget. LabelFont -- The font for the label widget. By default: "". LabelName -- The text on the label widgt. By default: "Filename: ". LabelSize -- The X screen size of the label widget. By default: 0. MustExist -- A flag that indicates selected files must exist. By default: 0. NoMaxSize -- A flag to prohibit automatic text widget sizing. By default: 0. If this keyword is not set, the compound widget will automatically resize itself to the largest widget in its parent base widget. It will do this by changing the size of the text widgets holding the file and directory names. Read -- Set this keyword to have file selection for reading a file. By default: 1. SelectDirectory -- The default directory for file selection. In other words, this is the default directory for DIALOG_PICKFILE, which is accessed via the BROWSE buttons. SelectFont -- The font for the "Browse" button. By default: "". SelectTitle -- The title bar text on the file selection dialog. By default: "Select a File...". TextFont -- The font for the filename text widget. By default: "". UValue -- User value for any purpose. Write -- Set this keyword to open a file for writing. By default: 0. XSize -- The X size of the text widget holding the filename. By default: StrLen(filename) * 1.5 > 40. OUTPUT KEYWORDS: ObjectRef -- Assign this keyword to an output variable that will hold the internal object reference. With the object reference you can call object methods to easily change many properties of the compound widget. COMMON BLOCKS: None. RESTRICTIONS: Probably doesn't work correctly on VMS systems :-( If you can help, please contact me. I don't have a VMS system to test on. 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. All events generated by the text widgets are passed to the assigned event handler. event = { CW_FILESELECT, $ ; 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. Basename: "", $ ; The base filename without directory specifiers. Filename: "", $ ; The fully qualified filename. Filter: ::, $ ; The currently active file filter. Directory: "", $ ; The name of the current file directory. } EXAMPLE: An example program is provided at the end of the FSC_FILESELECT code. To run it, type these commands: IDL> .Compile fsc_fileselect IDL> Example Or, if you want to obtain the object reference, type this: IDL> Example, theObject Now you can call the object's methods. For example: IDL theObject->SetProperty, XSize=150 GETTING and SETTING VALUES: So as not to disrupt the accepted paradigm in using compound widgets, you can use the return value of the FSC_FILESELECT function with WIDGET_CONTROL to get and set the "value" of the widget. Widget_Control, filenameID, Set_Value='C:\RSI\IDL52\DATA\cyclone.dat' The program will automatically separate the file name portion of the value from the directory portion and put things in the correct text widgets. Similarly, you can get the "value" of the widget: Widget_Control, filenameID, Set_Value=theValue Print, theValue C:\RSI\IDL52\DATA\cyclone.dat The return value is the fully qualified file path to the file. USING OBJECT METHODS to CHANGE PROGRAM PROPERTIES: If you obtain the object reference, you have a great deal more control over the properties of the compound widget. You obtain the object reference by calling the function like this: filenameID = FSC_FILESELECT(parent, ObjectRef=theObject) OBJECT PROCEDURE METHODS: GetProperty -- This method allows various properties of the widget to be returned via output keywords. The keywords that are available are: DirectoryName -- The current directory. Event_Func -- The name of the event handler function for this compound widget. Event_Pro -- The name of the event handler procedure for this compound widget. Filename -- The current base filename. Filter -- The current file filter. LabelName -- The text on the label widget. LabelSize -- The X screen size of the label widget. MustExist -- A flag that indicates selected files must exist to be selected. Parent -- The parent widget of the compound widget. Read=read -- The file selection for reading flag. SelectTitle -- The title bar text on the file selection dialog. TLB -- The top-level base of the compound widget. UValue -- The user value of the compound widget. Write -- The file selection for writing flag. XSize -- The X size of the text widget holding the filename. LabelSize -- This method makes sure that the directory name and file name labels are the same size. Normally, this procedure is called internally. No parameters. MatchSize -- This method resizes the compound widget so that it is as long as the the longest widget in the parent base widget. This is done automatically upon realization unless the NOMAXSIZE keyword is set. The method aids in writing resizeable widget programs. SetProperty -- This method allows various properties of the widget to be set via input keywords. The keywords that are available are: DirectoryName -- The current directory. Event_Func -- The name of the event handler function for this compound widget. Event_Pro -- The name of the event handler procedure for this compound widget. Filename -- The current base filename. Filter -- The current file filter. LabelName -- The text on the label widget. LabelSize -- The X screen size of the label widget. MustExist -- A flag that indicates selected files must exist to be selected. Read -- The file selection for reading flag. SelectTitle -- The title bar text on the file selection dialog. UValue -- The user value of the compound widget. Write -- The file selection for writing flag. XSize -- The X size of the text widget holding the filename. OBJECT FUNCTION METHODS: GetFileName -- Returns the fully qualified filename. No parameters. GetTLB -- Returns the top-level base ID of the compound widget. No Parameters. Inspect_DirectoryName -- Inspects the directory name for correctness. Requires one positional parameter. directoryName -- The name of the directory from the directory text widget. textSelection -- The current text selection position. At the moment all this does is remove any blank characters from either end of the directory name and makes sure the last character of the directory name does not end in a subdirectory specifier (except for VMS). Inspect_Filename -- Inspects the file name for correctness. Requires one positional parameter. filename -- The name of the file from the filename text widget. textSelection -- The current text selection position. At the moment all this does is remove any blank characters from either end of the file name MODIFICATION HISTORY: Written by: David Fanning, 21 NOV 1999. Fixed bug in File Name selection button. 18 MAR 2000. DWF. Fixed an error in which directory the Browse buttons should start searching. 29 SEP 2000. DWF. Previously returned events only for typing in text widgets. Now Browse button events are also returned. 29 SEP 2000. DWF. Fixed a bug in setting the file filter. 29 SEP 2000. DWF.
(See fsc_fileselect.pro)
NAME: FSC_INPUTFIELD PURPOSE: The purpose of this compound widget is to provide an alternative to the CW_FIELD widget offered in the IDL distribution. What has always bothered me about CW_FIELD 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 would be helpful. For example, you can now assign an event handler to the compound widget. The program is written entirely as an object. A companion program, COYOTE_FIELD, has much the same functionality, but is written as a traditional compound widget. The point of writing the same program in two different ways is to give you the opportunity to compare and contrast the two methods. I personally think there is no substitute for the power of object programs. :-) AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: General programming. CALLING SEQUENCE: objectRef = FSC_INPUTFIELD(parent, Title='X Size: ", Value=256, /IntegerValue) 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. CR_Only -- Set this keyword if you only want Carriage Return events. If this keyword is not set, all events are returned. No events are returned unless the EVENT_PRO or EVENT_FUNC keywords are used. 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. DoubleValue -- Set this keyword if you want DOUBLE values returned. Event_Func -- Set this keyword to the name of an Event 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 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. FloatValue -- Set this keyword for FLOAT values. Frame -- Set this keyword to put a frame around the compound widget. IntegerValue -- Set this keyword for INTEGER values. LabelFont -- The font name for the text in the Label Widget. LabelSize -- The X screen size of the Label Widget. LongValue -- Set this keyword for LONG values. Name -- A scalar string name of the object. (default = '') Positive -- Set this keyword if you want only positive numbers allowed. Row=row -- Set this keyword to have the Label beside the Text Widget. (The default.) Scr_XSize -- The X screen size of the compound widget. Scr_YSize -- The Y screen size of the compound widget. StringValue -- Set this keyword for STRING values. (The default.) 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. COMMON BLOCKS: None. RESTRICTIONS: None. 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, $ ; 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. ObjRef: 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. } ; Values are "INT", "LONG", "FLOAT", "DOUBLE", or "STRING". 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). But since traditional compound widgets have the ability to get and set the value of the compound widget, this capability is implemented as special methods. To get the value of the field, do this: value = objectRef->Get_Value() To set the value of the field, so this: objectRef->Set_Value, value, /IntegerValue The proper keyword should be used to set the data type of the value. If a keyword is not used, the data type is determined from the value itself. 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. Positive -- Indicates if the Positive number flag is set (1) or not (0). UValue -- The user value assigned to the compound widget. Value -- The "value" of the compound widget. Name -- A scalar string name of the object. 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. 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 Keywords available are these to set the type of the data. If keywords are not used, the data type is determined from the value. DoubleValue -- Set this keyword if you want DOUBLE values returned. FloatValue -- Set this keyword for FLOAT values. IntegerValue -- Set this keyword for INTEGER values. LongValue -- Set this keyword for LONG values. StringValue -- Set this keyword for STRING values. (The default.) 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 FLOATVALUE and DOUBLEVALUE numbers. Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers. DoubleValue -- Set this keyword if you want DOUBLE values returned. Event_Func -- Set this keyword to the name of an Event Function. Event_Pro -- Set this keyword to the name of an Event Procedure. FloatValue -- Set this keyword for FLOAT values. IntegerValue -- Set this keyword for INTEGER values. LabelSize -- The X screen size of the Label Widget. LongValue -- Set this keyword for LONG values. Name -- A scalar string name of the object. (default = '') Positive -- Set this keyword to indicate only positive numbers are allowed. Scr_XSize -- The X screen size of the text widget. Scr_YSize -- The Y screen size of the text widget. StringValue -- Set this keyword for STRING values. (The default.) 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. 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 cursor to end of the text in the widget identified by the nexttab field. (This will be set with the SetTabNext method.) 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_INPUTFIELD code. To run it, type these commands: IDL> .Compile FSC_InputField IDL> Example MODIFICATION HISTORY: Written by: David Fanning, 23 NOV 1999. Added DECIMAL and DIGITS keywords, 2 Jan 2000, DWF. Changed the calling sequence to that of a function rather than an object creation call. This is more familiar to users of compound widgets. 4 Jan 00. DWF. Added GetID and Resize methods. 7 Jan 00. DWF. Added the Positive keyword and functionality. 12 Jan 00. DWF Modified (slightly) the behavior on deleting characters. 12 Jan 00. DWF. If a number field is blank, the Get_Value method will now return an undefined variable. Be sure you check this value before you use it for something! 17 Jan 00. DWF. Fixed a small typo: "aveDecimal" to "haveDecimal". 10 March 2000. DWF. Added the ability to tab between FSC_INPUTFIELD widgets with the SetTabNext, MoveTab, and GetTextID methods. 31 July 2000. DWF. Added NAME field property, a scalar string name for the object 2 AUG 2000 BT Added ObjRef field to the FSC_FIELD event structure and added field selection for the TAB events added 31 July. 7 AUG 2000. DWF Added GetTextSize and GetLabelSize methods for obtaining the X screen size of the text and label widgets, respectively. 30 Jan 2001. DWF.
(See fsc_inputfield.pro)
NAME: FSC_PLOTWINDOW PURPOSE: The purpose of this compound widget is to create a resizeable "plot window" inside a larger "page window". I'm not sure it has any value except as a utility routine for the PostScript configuration object FSC_PSCONFIG__DEFINE, but it's a neat program anyway. :-) AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: Utility routine for FSC_PSCONFIG__DEFINE. CALLING SEQUENCE: plotwindowObject = CW_PlotWindow(parent) REQUIRED INPUT PARAMETERS: parent - The parent base widget of this compound widget. RETURN VALUE: plotwindowObject - The object reference of the compound widget. KEYWORDS: COLOR - If set, display the window in "color". This is the default on 24-bit devices. DEBUG - Set this keyword to turn traceback error handling on in the error handling code. EVENT_PRO - The event procedure for the widget. Required for events to be generated. Otherwise, all events are handled internally. LANDSCAPE - If set, display the page in landscape mode. Otherwise the page is display in portrait mode. PAGESIZE - The "pagesize" of the widget. Possible values are: "LETTER", "LEDGER", "LEGAL", "A4", and "DISPLAY". UNITS - A string indicating INCHES or CENTIMETER units. DEVICE units represented by a null string, "". UVALUE - A user value for the caller of this program. WINDOWCOLOR - A three-element array specifying the background window color (RGB). WINDOWSIZE - The size of the "window" on the page. A four-element array of normalized coordinates in the form [x0, y0, x1, y1]. EVENT STRUCTURE: The event structure that is returned from this compound widget is defined like this, where the sizes and offsets locate the target "window" on the page in normalized units: event = {ID:0L, TOP:0L, HANDLER:0L, XSize:0.0, YSize:0.0, XOffset:0.0, YOffset:0.0} MODIFICATIONS: Written by David Fanning, 31 January 2000. Fixed a small bug that prevented it working on Macintosh computers. 26 Sept 2000. DWF. Added a "DISPLAY" page size, so the program can be used to position plots and other graphics in a display window. The "page area" will have the same aspect ratio is the current graphics window. 17 March 2001. DWF.
(See fsc_plotwindow.pro)
NAME: FSC_PSCONFIG__DEFINE PURPOSE: The purpose of this program is to implement an object that can keep track of--and allow the user to change--the current configuration of the PostScript device. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: General programming. DOCUMENTATION: Complete documentation for the FSC_PSCONFIG object, including keyword and method descriptions, and example programs using the object can be found on the Coyote's Guide to IDL Programming web page: http://www.dfanning.com/programs/docs/fsc_psconfig.html Or, if you would prefer, you can download a self-contained PDF file: http://www.dfanning.com/programs/docs/fsc_psconfig.pdf KEYWORDS: Any keyword accepted by the FSC_PSCONFIG object can be used with this program. Here are a few of the most popular keywords. Bits_per_Pixel - The number of image bits saved for each image pixel: 2, 4, or 8. The default is 8. Color - Set this keyword to select Color PostScript output. Turned on by default. DefaultSetup - Set this keyword to the "name" of a default style. Current styles (you can easily create and add your own to the source code) are the following: "System (Portrait)" - The normal "default" system set-up. Also, "System". "System (Landscape)" - The normal "default" landscape system set-up. "Centered (Portrait)" - The window centered on the page. Also, "Center" or "Centered". "Centered (Landscape)" - The window centered on the landscape page. Also, "Landscape". "Square (Portrait)" - A square plot, centered on the page. "Square (Landscape)" - A square plot, centered on the landscape page. "Figure (Small)" - A small encapsulated figure size, centered on page. Also, "Encapsulated" or "Encapsulate". "Figure (Large)" - A larger encapsulated figure size, centered on page. Also, "Figure". "Color (Portrait)" - A "centered" plot, with color turned on. Also, "Color". "Color (Landscape)" - A "centered" landscape plot, with color turned on. Directory - Set this keyword to the name of the starting directory. The current directory is used by default. Encapsulate - Set this keyword to select Encapsulated PostScript output. Turned off by default. European - Set this keyword to indicate "european" mode (i.e., A4 page and centimeter units). Turned off by default. Filename - Set thie keyword to the name of the PostScript file. The default is "idl.ps". Inches - Set this keyword to indicate sizes and offsets are in inches as opposed to centimeters. Set by European keyword by default. Landscape - Set this keyword to select Landscape page output. Portrait page output is the default. PageType - Set this keyword to the "type" of page. Possible values are: "Letter" - 8.5 by 11 inches. (Default, unless the European keyword is set.) "Legal" - 8.5 by 14 inches. "Ledger" - 11 by 17 inches. "A4" - 21.0 by 29.7 centimeters. (Default, if the European keyword is set.) XOffset - Set this keyword to the X Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.) XSize - Set this keyword to the X size of the PostScript "window". Uses "System (Portrait)" defaults. YOffset - Set this keyword to the Y Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.) YSize - Set this keyword to the Y size of the PostScript "window". Uses "System (Portrait)" defaults. In addition, the following keywords can be used: CANCEL -- An output keyword that will be set to 1 if the user chooses the Cancel button on the form. It will be 0 otherwise. FONTINFO -- Set this keyword is you wish to have font information appear on the form. The default is to not include font information. FONTTYPE -- Set this keyword to a named variable that will indicate the user's preference for font type. Values will be -1 (Hershey fonts), 0 (hardware fonts), and 1 (true-type fonts). This keyword will always return -1 unless the FONTINFO keyword has also been set. GROUP_LEADER -- Set this keyword to a widget identifier of the widget you wish to be a group leader for this program. EXAMPLE: A simple sequence of using the object would look something like this: psObject = Obj_New("FSC_PSCONFIG") psObject->GUI psKeywords = psObject->GetKeywords() thisDevice = !D.Name Set_Plot, 'PS' Device, _Extra=psKeywords TVImage, image Device, /Close_File Set_Plot, thisDevice Obj_Destroy, psObject Note that the object can also be called from the PS_CONFIG interface: psKeywords = PSConfig() OTHER PROGRAMS NEEDED: The following programs are required to run this one: fsc_droplist.pro fsc_fileselect.pro fsc_field.pro fsc_plotwindow MODIFICATIONS: Written by David Fanning, 31 January 2000. Added capability to call GUI methods when the current graphics device doesn't support windows. Device is restored when the GUI exits. 11 May 2000. DWF. Changed the default value for the Color keyword to 1. 16 May 2000. DWF. Fixed a bug where filename changed when switching Setups. 8 AUG 2000. DWF. Fixed a bug when saving setup in Landscape mode. 8 AUG 2000. DWF. Added the ability to Get and Set the object's name via the SetProperty and a very abbreviated GetProperty method. Also added a GetName method. 26 SEP 2000. DWF. Fixed a problem in which the proper configuration was not restored if in Landscape mode. 20 Nov 2000. DWF. Made a number of modifications at the request of Martin Schultz. 4 Dec 2000. DWF. Fixed a bug when setting file and directory names with the SetProperty method. 18 Dec 2000. DWF. Fixed a small problem in initializing the page size properly. 3 Jan 2001. DWF. Corrected a problem that resulted from a change to FSC_DROPLIST. 6 Jan 2001. DWF. Added the ability to restore the font type instead of always reverting to !P.Font. 7 Jan 2001. DWF. Increased the length of the file/directory name fields. 7 Jan 2001. DWF. Fixed another problem with Landscape mode interacting with A4 paper size. 7 Jan 2001. DWF. Seems I only half fixed the previous problem. :-( 26 April 2001. DWF. Forgot to update program to reflect change in FSC_FIELD. Fixed 26 April 2001. DWF. Changed BOOKMAN keyword to BKMAN to avoid conflict with BOOKSTYLE keyword. 26 April 2001. DWF. Modified the System Defaults to say "None" if none is used. Improved documentation. 10 September 2001. DWF. Added the ability to specify a filename at the same time as a Default Setup. 10 September 2001. DWF.
(See fsc_psconfig__define.pro)
NAME: FSC_SURFACE PURPOSE: The purpose of this program is to demonstrate how to create a rotating surface using object graphics. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com CATEGORY: Widgets, Object Graphics. CALLING SEQUENCE: FSC_SURFACE, data, x, y REQUIRED INPUTS: None. Fake data will be used if no data is supplied in call. OPTIONAL INPUTS data: A 2D array of surface data. x: A vector of X data values. y: A vector of Y data values. OPTIONAL KEYWORD PARAMETERS: COLORTABLE: Set this keyword to a number between 0 and 40 to select one of the pre-selected IDL color tables for elevation shading. ELEVATION_SHADING: Set this keyword to put elevation shading into effect. EXACT: Set this keyword to a one-, two-,or three-element array to set exact axis scaling for the X, Y, and Z axes, respectively. If Exact is a one-element array, all three axes are set to the same value. For example, to set the X axis to exact scaling and the Y and Z axes to normal scaling, type: IDL> FSC_Surface, Exact=[1,0,0] _EXTRA: This keyword collects otherwise undefined keywords that are passed to the IDLgrSURFACE initialization routine. GROUP_LEADER: The group leader for this program. When the group leader is destroyed, this program will be destroyed. LANDSCAPE: Set this keyword if you are printing in landscape mode. The default is Portrait mode. The Landscape keyword on the PRINTER object is set, but not all printers will honor this keyword setting. If yours does not, set Landscape mode in the Printer Setup dialog. SHADED: Set this keyword to set up a shaded surface plot rather than a wire mesh surface, which is the default. TITLE: A string used as the title of the plot. XTITLE: A string used as the X title of the plot. YTITLE: A string used as the Y title of the plot. ZTITLE: A string used as the Z title of the plot. COMMON BLOCKS: None. SIDE EFFECTS: None. DEPENDENCIES: This program requires the following additional files from the Coyote Library: error_message.pro fsc_droplist.pro getcolor.pro loaddata.pro pickcolor.pro xcolors.pro EXAMPLE: To use this program with your data, type: IDL> FSC_Surface, data MODIFICATION HISTORY: Written by David Fanning, 8 June 97. Made axis scaling more robust. 17 Sept 97. DWF. Minor modifications to incorporate better understanding of how objects work. 4 Oct 97. DWF. Fixed error cleaning up all of my created objects. 12 Feb 98. DWF. Changed IDLgrContainer to IDL_Container to fix 5.1 problems. 20 May 98. DWF. Fixed mis-spelling of HELVETICA14. 29 June 98. DWF. Added the EXACT keyword to the X and Y axes to force axis ranging. 27 July 98. DWF Added the ability to select rendering "drag" quality for faster operation. 22 Aug 98. DWF. Added ability to get non-exact axis scaling. 12 May 99. DWF. Improved documentation and readability of code. 12 May 99. DWF. Added VECTOR and LANDSCAPE keywords and improved printing capability. 16 Feb 2000. DWF. Added different lights and a Light Controller option. 28 April 2000. DWF. Added elevation shading. 8 May 2000. DWF. Removed VECTOR keyword. Replaced with VECTOR/BITMAP/COLOR Print buttons. 8 May 2000. DWF. Added HIDDEN_LINE keyword. 8 May 2000. DWF. Added EXACT keyword extensions and changed name from XSURFACE to FSC_SURFACE. 11 May 2000. DWF. Made change to Light Control code to accomodate FSC_DROPLIST changes. 6 Jan 2001. DWF. Removed unused color table vector code from a LONG time ago. 17 Jan 2001. DWF. Added TIFF file output and removed GIF output for IDL 5.4. 11 Feb 2001. DWF. Added short wait before taking image snapshot for JPEG and TIFF files to avoid extraneous text in output files. 22 October 2001. DWF.
(See fsc_surface.pro)
NAME: FSC_WINDOW PURPOSE: This routine implements a "smart" resizeable graphics window. It is used as a wrapper for built-in IDL graphics procedures such as SURFACE, CONTOUR, PLOT, SHADE_SURF, etc. In additon, it can be used to display any user-written graphics procedure so long as that procedure follows three simple rules: (1) It does not open it's own graphics windows, (2) It is defined with no more than three positional arguments (an unlimited number of keyword arguments are allowed), and (3) It uses no device- specific commands, such as "WSet", "Device, Decomposed=1", etc. Keyword arguments permit the window to have its own portion of a color table and to be able to change the colors loaded in that portion of the color table. Colors are updated automatically on both 8-bit and 24-bit color displays. In addition, the window colors will "protect" themselves. I mean by this that the window will re-load its own colors into the color table when the window gains keyboard focus. This prevents other applications from changing the colors used to display data in this window. (This is an issue mainly in IDL 5 applications where widget applications can run concurrently with commands from the IDL command line.) Keyword arguments also permit the window to create output files of its contents. These files can be color and gray-scale PostScript, and color BMP, GIF, JPEG, PICT, PNG, TIFF, or JPEG files. Output can also be sent directly to the default printer. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com CATEGORY: Widgets, Graphics. CALLING SEQUENCE: FSC_WINDOW, command, P1, P2, P3 REQUIRED INPUTS: COMMAND: The graphics procedure command to be executed. This parameter must be a STRING and the the command must be a procedure. Examples are 'SURFACE', 'CONTOUR', 'PLOT', etc. OPTIONAL INPUTS: P1: The first positional parameter appropriate for the graphics command. P2: The second positional parameter appropriate for the graphics command. P3: The third positional parameter appropriate for the graphics command. INPUT KEYWORD PARAMETERS: WBACKGROUND: The background color index for the window. Setting this color along with the WERASEIT keyword causes the window to be erased with this color. Set to !P.Background by default. WERASEIT: Setting this keyword "erases" the contents of the current graphics window before re-executing the graphics command. For example, this keyword might need to be set if the graphics "command" is TVSCL. The default is to NOT erase the display before reissuing the graphics command. _EXTRA: This keyword forms an anonymous structure of any unrecognized keywords passed to the program. The keywords must be appropriate for the graphics command being executed. GROUP_LEADER: The group leader for this program. When the group leader is destroyed, this program will be destroyed. WTITLE: This is the window title. It is the string "COMMAND Window (1)" by default, where COMMAND is the input parameter. And the number (1 in this case) is the window index number of the draw widget. WXPOS: This is the initial X offset of the window. Default is to position the window in the approximate middle of the display. WYPOS: This is the initial Y offset of the window. Default is to position the window in the approximate middle of the display. WPOSTSCRIPT: Set this keyword to 1 to include a PostScript File button under the Save As button. This keyword is set automatically on 24-bit display devices. To turn the button OFF on 24-bit devices, set the keyword value to 0. There is no guaranteed way to create perfect PostScript output when the program is run on 8-bit displays. This will depend entirely on how the "graphics command" is written. Hence the button is turned off automatically on 8-bit devices. WPRINT: Set this keyword to 1 to include a Print button under the File button. This keyword is set automatically on 24-bit display devices. To turn the button OFF on 24-bit devices, set the keyword value to 0. There is no guaranteed way to print output correctly when the program is run on 8-bit displays. This will depend entirely on how the "graphics command" is written. Hence the button is turned off automatically on 8-bit devices. WXSIZE: This is the initial X size of the window. Default is 400 pixels. WYSIZE: This is the initial Y size of the window. Default is 400 pixels. WCOLORS: Using this keyword adds a "Colors..." button to the "File" menu. Set this keyword to the number of colors available in the window and the starting index of the first color. For example, to allow the window access to 100 colors, starting at color index 50 (i.e., color indices 50 to 149), use WColors=[100, 50]. If you use the keyword syntax "/WColors", all the colors available will be used, not just one color. If the keyword is set to a scalar value greater than 1, the starting color index is set to 0. The default value for this keyword is [(!D.Table_Size, 0]. COMMON BLOCKS: None. RESTRICTIONS: This program requires additional programs from the Fanning Software Consulting library: CENTERTLB.PRO ERROR_MESSAGE.PRO FSC_PSCONFIG__DEFINE.PRO FSC_DROPLIST.PRO FSC_FIELD.PRO FSC_FILESELECT.PRO FSC_INPUTFIELD.PRO FSC_PLOTWINDOW.PRO PSCONFIG.PRO PSWINDOW.PRO TVREAD.PRO XCOLORS.PRO If the "command" program requires keywords that are also keywords to FSC_WINDOW, then you must use the keyword twice on the command line. EXAMPLE: If the program is called with no parameters whatsoever, it will load example data. IDL> FSC_WINDOW To use the program with an IDL PLOT command, for example: IDL> FSC_WINDOW, 'PLOT', Findgen(11), Charsize=1.5, Title='Example Plot' To build your own graphics display command, you can do something like this. Here is a command program that takes an image, a column number, and a row number, and plots a column and row profile next to one another: PRO COL_ROW_PLOT, image, column, row, _Extra=extra ; Check parameters. IF N_Elements(image) EQ 0 THEN image = DIST(200) IF N_ELements(column) EQ 0 THEN column = 100 IF N_Elements(row) EQ 0 THEN row = 100 ; Set up plots.; !P.Multi = [0, 2, 1] Plot, image[column, *], Title='Row Profile', YRange=[Min(image), Max(image)], $ XStyle=1, XTitle='At Column No: ' + StrTrim(column,2), _Extra=extra Plot, image[*, row], Title='Column Profile', YRange=[Min(image), Max(image)], $ XStyle=1, XTitle='At Row No: ' + StrTrim(row,2), _Extra=extra !P.Multi = 0 END This command program is used with FSC_WINDOW, like this: IDL> Demo_GetData, image, Filename='ctscan.dat' IDL> FSC_WINDOW, 'COL_ROW_PLOT', image, 30, 185, YTitle='Image Value' MODIFICATION HISTORY: Written by: David Fanning, Sept 2000. Based on previous XWINDOW program. Whoops! Left out the line to resize draw widgets on UNIX machines. Fixed. 12 Oct 2000, DWF. Removed support for GIF files for IDL 5.4. 18 Jan 2001. DWF. Beefed up documentation. 27 March 2001. DWF.
(See fsc_window.pro)
NAME: GETCOLOR PURPOSE: The original purpose of this function was to enable the user to specify one of the 16 colors supported by the McIDAS color map by name. Over time, however, the function has become a general purpose function for handling and supporting drawing colors in a device-independent way. In particular, I have been looking for ways to write color handling code that will work transparently on both 8-bit and 24-bit machines. On 24-bit machines, the code should work the same where color decomposition is turned on or off. The program now supports 88 colors. AUTHOR: FANNING SOFTWARE CONSULTING: David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com CATEGORY: Graphics, Color Specification. CALLING SEQUENCE: result = GETCOLOR(color, index) OPTIONAL INPUT PARAMETERS: COLOR: A string with the "name" of the color. Valid names are: black magenta cyan yellow green red blue navy pink aqua orchid sky beige charcoal gray white The color YELLOW is returned if the color name can't be resolved. Case is unimportant. If the function is called with just this single input parameter, the return value is either a 1-by-3 array containing the RGB values of that particular color, or a 24-bit integer that can be "decomposed" into that particular color, depending upon the state of the TRUE keyword and upon whether color decomposition is turned on or off. The state of color decomposition can ONLY be determined if the program is being run in IDL 5.2 or higher. INDEX: The color table index where the specified color should be loaded. If this parameter is passed, then the return value of the function is the index number and not the color triple. (If color decomposition is turned on AND the user specifies an index parameter, the color is loaded in the color table at the proper index, but a 24-bit value is returned to the user in IDL 5.2 and higher. This assumes the INDEXED keyword is NOT set.) If no positional parameter is present, then the return value is either a 16-by-3 byte array containing the RGB values of all 16 colors or it is a 16-element long integer array containing color values that can be decomposed into colors. The 16-by-3 array is appropriate for loading color tables with the TVLCT command: Device, Decomposed=0 colors = GetColor() TVLCT, colors, 100 INPUT KEYWORD PARAMETERS: NAMES: If this keyword is set, the return value of the function is a 88-element string array containing the names of the colors. These names would be appropriate, for example, in building a list widget with the names of the colors. If the NAMES keyword is set, the COLOR and INDEX parameters are ignored. listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16) INDEXED: If this keyword is set, the return value is always an index into the color table. In the absence of a color table INDEX parameter, the color is loaded at !P.COLOR < (!D.Table_Size-1). LOAD: If this keyword is set, all 88 colors are automatically loaded starting at the color index specified by the START keyword. Note that setting this keyword means that the return value of the function will be a structure, with each field of the structure corresponding to a color name. The value of each field will be an index number (set by the START keyword) corresponding to the associated color, or a 24-bit long integer value that creates the color on a true-color device. What you have as the field values is determined by the TRUE keyword or whether color decomposition is on or off in the absense of the TRUE keyword. It will either be a 1-by-3 byte array or a long integer value. START: The starting color index number if the LOAD keyword is set. This keyword value is ignored unless the LOAD keyword is also set. The keyword is also ignored if the TRUE keyword is set or if color decomposition in on in IDL 5.2 and higher. The default value for the START keyword is !D.TABLE_SIZE - 89. TRUE: If this keyword is set, the specified color triple is returned as a 24-bit integer equivalent. The lowest 8 bits correspond to the red value; the middle 8 bits to the green value; and the highest 8 bits correspond to the blue value. In IDL 5.2 and higher, if color decomposition is turned on, it is as though this keyword were set. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: The TRUE keyword causes the START keyword to be ignored. The NAMES keyword causes the COLOR, INDEX, START, and TRUE parameters to be ignored. The COLOR parameter is ignored if the LOAD keyword is used. On systems where it is possible to tell the state of color decomposition (i.e., IDL 5.2 and higher), a 24-bit value (or values) is automatically returned if color decomposition is ON. EXAMPLE: To load a yellow color in color index 100 and plot in yellow, type: yellow = GETCOLOR('yellow', 100) PLOT, data, COLOR=yellow or, PLOT, data, COLOR=GETCOLOR('yellow', 100) To do the same thing on a 24-bit color system with decomposed color on, type: PLOT, data, COLOR=GETCOLOR('yellow', /TRUE) or in IDL 5.2 and higher, DEVICE, Decomposed=1 PLOT, data, COLOR=GETCOLOR('yellow') To load all 88 colors into the current color table, starting at color index 100, type: TVLCT, GETCOLOR(), 100 To add the color names to a list widget: listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16) To load all 88 colors and have the color indices returned in a structure: DEVICE, Decomposed=0 colors = GetColor(/Load, Start=1) HELP, colors, /Structure PLOT, data, COLOR=colors.yellow To get the direct color values as 24-bit integers in color structure fields: DEVICE, Decomposed=1 colors = GetColor(/Load) PLOT, data, COLOR=colors.yellow Note that the START keyword value is ignored if on a 24-bit device, so it is possible to write completely device-independent code by writing code like this: colors = GetColor(/Load) PLOT, data, Color=colors.yellow MODIFICATION HISTORY: Written by: David Fanning, 10 February 96. Fixed a bug in which N_ELEMENTS was spelled wrong. 7 Dec 96. DWF Added the McIDAS colors to the program. 24 Feb 99. DWF Added the INDEX parameter to the program 8 Mar 99. DWF Added the NAMES keyword at insistence of Martin Schultz. 10 Mar 99. DWF Reorderd the colors so black is first and white is last. 7 June 99. DWF Added automatic recognition of DECOMPOSED=1 state. 7 June 99. DWF Added LOAD AND START keywords. 7 June 99. DWF. Replaced GOLD with CHARCOAL color. 28 Oct 99. DWF. Added INDEXED keyword to force indexed color mode. 28 Oct 99. DWF. Fixed problem of "aqua" and "pink" being mixed up. 18 Mar 00. DWF. Changed ON_ERROR from 1 to 2, and improved error handling. 2 Aug 00. DWF. Increased the known colors from 16 to 88. 19 October 2000. DWF. Fixed typos in which "thisColor" was written as "theColor". 10 AUG 2001. DWF.
(See getcolor.pro)
NAME: GETIMAGE PURPOSE: The purpose of this function is to allow the user to open either regular or XDR binary image files of two or three dimensions. CATEGORY: Widgets, File I/O. CALLING SEQUENCE: image = GETIMAGE(filename) OPTIONAL INPUTS: filename: The name of the file to open for reading. OPTIONAL KEYWORD PARAMETERS: CANCEL: An output variable that can be set to a named variable. The value of the return variable will be 1 if the user clicked the "Cancel" button or if there was a problem reading the file. CATCH: Set this keyword to 0 if you wish to turn error catching OFF. DIRECTORY: The name of the directory the file is located in. By default the program looks in the "coyote" directory under the main IDL directory, if one exists. Otherwise, it defaults to the current directory. FRAMES: The 3rd dimension of a 3D data set. Defaults to 0. HEADER: The size of any header information in the file in BYTES. Default is 0. PARENT: The group leader for this widget program. The PARENT is required if GETIMAGE is called from another widget program in order to make this program a MODAL widget program. XDR: Set this keyword if the binary file is of XDR type. XOFFSET: This is the X offset of the program on the display. The program will be placed approximately in the middle of the display by default. XSIZE: The size of the 1st dimension of the data. YOFFSET: This is the Y offset of the program on the display. The program will be placed approximately in the middle of the display by default. YSIZE: The size of the 2nd dimension of the data. COMMON BLOCKS: None. SIDE EFFECTS: A "CANCEL" operation is indicated by a 0 return value. Any error in reading the file results in a 0 return value. RESTRICTIONS: None. EXAMPLE: To load the image "galaxy.dat" in the $IDL/examples/data directory, type: image = GETIMAGE('galaxy.dat', DIRECTORY=!DIR + '/examples/data', $ XSIZE=256, YSIZE=256, Cancel=cancelled, Parent=event.top) IF NOT cancelled THEN TV, image MODIFICATION HISTORY: Written by: David Fanning, 3 February 96. Fixed bug that prevented reading INTEGER data. 19 Dec 96. Modifed program for IDL 5 MODAL operation. 19 Oct 97. Added CANCEL keyword. 27 Oct 97. DWF. Fixed CANCLE keyword spelling. Sigh... 29 JUN 98. DWF. Added COYOTE_FIELD, improved appearance. 19 NOV 99. DWF. Updated with latest version of COYOTE_FIELD. 18 FEB 2000. DWF. Added CATCH keyword so the program will break when I want it to. :-) 18 MAR 2000. DWF. Added GROUP_LEADER keyword, which is synonymous with PARENT. 31 MAR 2000. DWF. Updated obsolete PICKFILE call to DIALOG_PICKFILE. 17 JAN 2001. DWF.
(See getimage.pro)
NAME: HCOLORBAR FILENAME: hcolorbar__define.pro ; PURPOSE: The purpose of this program is to create a horizontal colorbar object to be used in conjunction with other IDL 5 graphics objects. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: Object Graphics. CALLING SEQUENCE: thisColorBar = Obj_New('HColorBar') REQUIRED INPUTS: None. INIT METHOD KEYWORD PARAMETERS: COLOR: A three-element array representing the RGB values of a color for the colorbar axes and annotation. The default value is white: [255,255,255]. FONTSIZE: A floating value that is the point size of the font used for the axis and title annotations. Set to 8 point by default. NAME: The name associated with this object. NCOLORS: The number of colors associated with the colorbar. The default is 256. MAJOR: The number of major tick divisions on the colorbar axes. The default is 5. MINOR: The number of minor tick marks on the colorbar axes. The default is 4. PALETTE: A palette object for the colorbar. The default palette is a gray-scale palette object. POSITION: A four-element array specifying the position of the colorbar in normalized coordinate space. The default position is [0.10, 0.90, 0.90, 0.95]. RANGE: The range associated with the colorbar axis. The default is [0, NCOLORS]. TITLE: A string containing a title for the colorbar axis annotation. The default is a null string. OTHER METHODS: Clamp (Procedure): Given a two-element array in the data range of the colorbar, the colorbar image is clamped to this range. In other words, the range of colors is clamped to the specified range. Values above or below the range in the colorbar are set to the minimum and maximum range values, respectively. GetProperty (Procedure): Returns colorbar properties in keyword parameters as defined for the INIT method. Keywords allowed are: COLOR MAJOR MINOR NAME PALETTE POSITION RANGE TEXT TITLE TRANSFORM SetProperty (Procedure): Sets colorbar properties in keyword parameters as defined for the INIT method. Keywords allowed are: COLOR MAJOR MINOR NAME PALETTE POSITION RANGE TEXT TITLE TRANSFORM SIDE EFFECTS: A HColorBar structure is created. The colorbar INHERITS IDLgrMODEL. Thus, all IDLgrMODEL methods and keywords can also be used. It is the model that is selected in a selection event, since the SELECT_TARGET keyword is set for the model. RESTRICTIONS: None. EXAMPLE: To create a colorbar object and add it to a plot view object, type: thisColorBarObject = Obj_New('HColorBar') plotView->Add, thisColorBarObject plotWindow->Draw, plotView MODIFICATION HISTORY: Written by David Fanning, from VColorBar code, 20 Sept 98. DWF. Changed a reference to _Ref_Extra to _Extra. 27 Sept 98. DWF. Fixed bug when adding a text object via the TEXT keyword. 9 May 99. DWF. Fixed the same bug when getting the text using the TEXT keyword. :-( 16 Aug 2000. DWF. Fixed a bug with getting the text object via the TEXT keyword. 16 Aug 2000. DWF. Added the TRANSFORM keyword to GetProperty and SetProperty methods. 16 Aug 2000. DWF. Added RECOMPUTE_DIMENSIONS=2 to text objects. 16 Aug 2000. DWF. Added a polygon object around the image object. This allows rotation in 3D space. 16 Aug 2000. DWF. Removed TEXT keyword (which was never used) and improved documentation. 15 AUG 2001. DWF. Added ENABLE_FORMATTING keyword to title objects. 22 October 2001. DWF. Added a CLAMP method. 18 November 2001. DWF.
(See hcolorbar__define.pro)
NAME: IMAGE_BLEND PURPOSE: The purpose of this program is to demonstrate how to use the alpha channel to blend one image into another. The specific purpose is to see a color image on top of a gray-scale image, with the gray-scale image showing through behind the color image. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 2642 Bradbury Court Fort Collins, CO 80521 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com CATEGORY: Widgets, Object Graphics. CALLING SEQUENCE: Image_Blend REQUIRED INPUTS: None. The images "worldelv.dat" and "ctscan.dat" from the examples/data directory are used. OPTIONAL INPUTS: backgroundImage:: A 2D image variable that will be used for the background image. foregroundImage: A 2D image variable that will be used for the foreground image. OPTIONAL KEYWORD PARAMETERS: COLORTABLE: The number of a color table to use for the foreground image. Color table 3 (red temperature) is used as a default. COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: None. The program XCOLORS is required from the Coyote library. EXAMPLE: Image_Blend, Colortable=5 MODIFICATION HISTORY: Written by David Fanning, 30 March 99. Fixed bug where I redefined the image parameter. Duh... 1 April 99. DWF.
(See image_blend.pro)
NAME: LINKEDLIST FILENAME: linkedlist__define.pro PURPOSE: The purpose of this program is to implement a list that is linked in both the forward and backward directions. There is no restriction as to what can be stored in a linked list node. The linked list is implemented as an object. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone:<PHONE_NUMBER> E-mail<EMAIL_ADDRESS>Coyote's Guide to IDL Programming: http://www.dfanning.com/ CATEGORY: General programming. CALLING SEQUENCE: mylist = Obj_New('LINKEDLIST', item) OPTIONAL INPUTS: item: The first item added to the list. Items can be any valid IDL variable type. COMMON BLOCKS: Are you kidding?! RESTRICTIONS: Be sure to destroy the LINKEDLIST object when you are finished with it: Obj_Destroy, mylist Node index numbers start at 0 and go to n-1, where n is the number of items in the list. PUBLIC METHODS: ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; PRO LINKEDLIST::ADD, item, index, AFTER=after, BEFORE=before The ADD method adds a data item to the list. Parameters: item: The data item to be added to the list. Required. index: The location in the list where the data item is to be added. If neither the AFTER or BEFORE keyword is set, the item is added AFTER the item at the index location. If index is missing, the index points to the last item in the list. Optional. Keywords: AFTER: If this keyword is set, the item is added after the item at the current index. BEFORE: If this keyword is set, the item is added before the item at the current index. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; PRO LINKEDLIST::DELETE, index, ALL=all The DELETE method deletes an item from the list. Parameters: index: The location in the list where the data item is to be delete. If index is missing, the index points to the last item in the list. Optional. Keywords: ALL: If this keyword is set, all items in the list are deleted. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; FUNCTION LINKEDLIST::GET_COUNT The GET_COUNT method returns the number of items in the list. Return Value: The number of items stored in the linked list. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; FUNCTION LINKEDLIST::GET_ITEM, index The GET_ITEM_PTR method returns a pointer to the specified data item from the list. Parameters: index: The location in the list from which the data item is to be retrieved. If not present, the last item in the list is retrieved. Optional. Keywords: DEREFERENCE: Set this keyword to return the thing the pointer points to (i.e., the item itself.) Return Value: A pointer to the specified data item stored in the list. IF DEREFERENCE is set, the data item itself is returned. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; FUNCTION LINKEDLIST::GET_NODE, index The GET_NODE method returns a pointer to the specified node from the list. Parameters: index: The location in the list from which the data node is to be retrieved. If not present, the last node in the list is retrieved. The node is a structure with three fields: Previous is a pointer to the previous node in the list. Next is a pointer to the next node in the list. A null pointer in the previous field indicates the first node on the list. A null pointer in the next field indicates the last node on the list. The item field is a pointer to the item stored in the node. Optional. Return Value: A pointer to the specified node structure in the linked list. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; PRO LINKEDLIST::HELP, PRINT=print The HELP method performs a HELP command on each item in the linked list. Keywords: PRINT: If this keyword is set, the PRINT command is used instead of the HELP command on the items in the list. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; PRO LINKEDLIST::MOVE_NODE, nodeIndex, location, BEFORE=before The MOVE_NODE method moves a list node from one location to another. Parameters: nodeIndex: The location in the list of the node you are moving. Required. location: The location (index) you are moving the node to. If location is missing, the location points to the node at the end of the list. Keywords: BEFORE: If this keyword is set, the node is added to the list before the location node. Otherwise, it is added after the location node. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; PRO LINKEDLIST::REPLACE_ITEM, Index, NewItem Use this method to replace any item in the list with any other value. This allows the caller to change an item without stepping through the process of deleting an item then adding a new one. Parameters: Index: The location of the node you are replacing NewItem: Any value of any data type. ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; EXAMPLE: mylist = Obj_New("LINKEDLIST", 5) mylist->Add, 10 mylist->Add, 7.5, 1, /Before mylist->Add, 12.5 mylist->Replace_Item, 1, 'Bob' mylist->Help mylist->Delete mylist->Help, /Print MODIFICATION HISTORY: Written by: David Fanning, 25 August 98. 25 August 99. Fixed several errors in various methods dealing with moving nodes from one place to another. DWF. 13 June 2001. DWF. Added DEREFERENCE to the GET_ITEM method to return the item itself, instead of the pointer to the item. 27 June 2001 BT Added REPLACE_ITEM method.
(See linkedlist__define.pro)