NAME: PROGRESSBAR__DEFINE PURPOSE: Creates a simple progress bar for indicating the progess of a looping operation in IDL. AUTHOR: FANNING SOFTWARE CONSULTING David Fanning, Ph.D. 1645 Sheely Drive Fort Collins, CO 80526 USA Phone: 970-221-0438 E-mail: davidf@dfanning.com Coyote's Guide to IDL Programming: http://www.dfanning.com CATEGORY: Utilities CALLING SEQUENCE: progressBar = Obj_New("PROGRESSBAR") ARGUMENTS: None. KEYWORDS: BACKGROUND: The name of the background color of the progress bar. By default, "black". COLOR: The name of the color for the progress bar. By default: "red". Possible color names are those defined by FSC_COLOR: Almond Antique White Aquamarine Beige Bisque Black Blue Blue Violet Brown Burlywood Charcoal Chartreuse Chocolate Coral Cornsilk Cyan Dark Goldenrod Dark Gray Dark Green Dark Khaki Dark Orchid Dark Salmon Deep Pink Dodger Blue Firebrick Forest Green Gold Goldenrod Gray Green Green Yellow Honeydew Hot Pink Indian Red Ivory Khaki Lavender Lawn Green Light Coral Light Cyan Light Gray Light Salmon Light Yellow Lime Green Linen Magenta Maroon Medium Gray Medium Orchid Moccasin Navy Olive Olive Drab Orange Orange Red Orchid Pale Goldenrod Pale Green Papaya Peru Pink Plum Powder Blue Purple Red Rose Rosy Brown Royal Blue Saddle Brown Salmon Sandy Brown Sea Green Seashell Sienna Sky Blue Slate Gray Snow Spring Green Steel Blue Tan Thistle Tomato Turquoise Violet Violet Red Wheat White Yellow FAST_LOOP: Set this keyword if what you are doing in the loop doesn't involve any color operations and you want the progress bar to update as fast as possible. With this keyword set, the program will eliminate extra calls to FSC_COLOR, which can be slow if you are calling it, say, 10,000 times! GROUP_LEADER: The group leader for the progress bar. NOCANCEL: Set this keyword to eliminate the CANCEL button from the progres bar. PERCENT: The initial percent on the progress bar. Used only if the START keyword is also set. START: Set this keyword if you wish to call the START method immediately upon initialization. TEXT: The textual message that goes above the progress bar. By default: "Operation in progress..." TITLE: The title of the progress bar window. By default: "Progress Bar". XSIZE: The X size of the progress bar itself. By default, 150 pixels. YSIZE: The Y size of the progress bar itself. By default, 10 pixels. PROCEDURE: The user is responsible for starting, updating, checking for CANCEL events, and destroying the progress indicator. The sequence of commands might look like this: progressBar = Obj_New("PROGRESSBAR") progressBar -> Start FOR j=0,9 DO BEGIN IF progressBar -> CheckCancel() THEN BEGIN ok = Dialog_Message('The user cancelled operation.') RETURN ENDIF Wait, 0.5 ; Would probably be doing something ELSE here! progressBar -> Update, (j+1)*10 ENDFOR progressBar -> Destroy See the example program at the end of this file for a working example of code. METHODS: CHECKCANCEL: This function method returns a 1 if the user has clicked the CANCEL button. Otherwise, it returns a 0. cancelled = progressBar -> CheckCancel() IF cancelled THEN progressBar->Destroy DESTROY: Destroys the progress bar widgets as well as the object. progressBar -> Destroy GETPROPERTY: Gets certain properties of the object. progressBar -> GetProperty, Color=currentColor SETPROPERTY: Allows the user to set certain properties of the object. progressBar -> SetProperty, Color='green' START: Puts the progress bar on the display and enables it to receive events. progressBar -> Start UPDATE: Updates the progress bar. Requires on argument, a number between 0 and 100 that indicates the percent of progress bar that should be filled with a color. Can optional specify TEXT that is displayed above the progress bar. progressBar -> Update, 50 progressBar -> Update, 50, Text='Operation 50% completed...' EXAMPLE: See the example program at the bottom of this file. RESTRICTIONS: Note that the progress bar cannot be run as a MODAL widget program and still capture CANCEL button events. Thus, the user *may* be able to generate events in the calling program while this progress bar is in operation. DEPENDENCIES: This program requires FSC_COLOR from the Coyote Library: http://www.dfanning.com/programs/fsc_color.pro MODIFICATION HISTORY: Written by: David W. Fanning, 19 September 2002. Added TEXT keyword to Update method. 12 Nov 2002. DWF. Added FAST_LOOP keyword. 19 Dec 2002. DWF. Fixed a problem in where I was checking for CANCEL button event. 2 April 2003. DWF. Removed the XMANAGER call in the START method, since it wasn't needed. 7 October 2003. DWF. General maintenance updates. Added START keyword to INIT method to allow immediate starting upon initialization. Added better error handling and checking. 10 October 2003. DWF. Added ACCEPT button and CheckButton method. Modified Example program to demonstrate new functionality. 1 December 2003. DWF. Added XOFFSET and YOFFSET keywords. 4 March 2004. DWF. Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF. Added keyword keyword TITLE to Update method. 23 Feb 2005. Benjamin Hornberger Added BACKGROUND keyword. 22 Dec 2006. DWF. Added RETAIN=1 keyword to Widget_Draw command. 9 Dec 2007. DWF.