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

 NAME:
       PROGRESSBAR__DEFINE

 PURPOSE:

       Creates a simple progress bar for indicating the progess of a looping
       operation in IDL.

 AUTHOR:

       FANNING SOFTWARE CONSULTING
       David Fanning, Ph.D.
       1645 Sheely Drive
       Fort Collins, CO 80526 USA
       Phone: 970-221-0438
       E-mail: david@idlcoyote.com
       Coyote's Guide to IDL Programming: http://www.idlcoyote.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 cgColor:

                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 cgColor, 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 cgColor from the Coyote Library:

          http://www.idlcoyote.com/programs/cgColor.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.
       Modifed the RETAIN keyword to set the value based on OS type. 22 May 2012. DWF.

(See progressbar__define.pro)

