////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Object : u_Dynamic_ProgressBar v3.0
// Method : Constructor!
//
// Author : Shekar C Reddy [PowerObject!]
// Group  : http://groups.yahoo.com/group/powerobject
// Date   : 12/27/2001
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Arg    : 
// Return : long
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Desc   : DynamicProgressBar v3.0 - A light-weight, non-PFC, tiny-footprint object with DYNAMIC capabilities. 
//          It has the ability to display progress of an ongoing retrieval, row-position as well as data-processing
//          such as row-by-row validation logic, data-population...
//
//          A lot of NEW features and functions have been included for Developer-friendliness. Most of the
//          processing/instance-variables/PowerScript on the surface of the Window has now been moved to
//          u_Dynamic_ProgressBar to make scripting on the Window-level MINIMAL - so it looks neater and becomes
//          EASILY maintainable.
//
//    ==========================================================================================================
//                                       END USER LICENCE AGREEMENT
//                                       --------------------------
//
//          THIS IS A FREE UTILITY (See: Copyright Notice below) - EVEN FOR COMMERCIAL USE!
//          USE IT AT YOUR OWN RISK!! NOT LIABLE FOR ANY LOSES OR DAMAGES - WHATSOEVER.
//
//                                                 ---
//		                              Shekar C Reddy
//		                              [PowerObject!]
//    ==========================================================================================================
//
//    FUNCTIONALITY:
//    -------------
//    Retrieves the Count(*) of rows from the db using the dw.Object.Datawindow.Table.Select or a SQL-SELECT
//    statement using DYNAMIC SQL. By default, the Constructor! event makes the Progress-bar invisible; gets
//    visible only Just-in-Time! Progress-bar is represented in 1000's instead of 100's (percentage * 10) for
//    full-text display purposes. Displays as_Message as:
//
//       Message row / rowCount (eg: [Validating: row / rowCount] or [Retrieving: row / rowCount]
//
//
//    However, you may change the Width through of_SetWidth() function; the PROPORTION is maintained internally:
//
//       dw_ProgressBar.of_SetWidth( 500 )
//
//
//    ProgressBar in Retrieval-mode does NOT hang the application - you can FREELY switch back-n-forth between
//       other applications and the PowerBuilder runtime window WITHOUT any delay (you don't have to wait until
//       the retrieval is finished!) by virtue of PowerScript in the dw.RetrieveRow! event.
//
//    ProgressBar offers TOTAL Developer-control over its behavior at every phase of retrieval/processing that is
//       manageable by EXHAUSTIVE/CONSISTENT arguments to all its functions. Do add more MUSCLE to it if required!
//
//
//    MAIN FUNCTIONS (See: the USAGE section below):
//    ---------------------------------------------
//    of_DBCancel( akc_Key, akc_CancelKeys[], as_Message, al_Color, ab_Bold, ab_ResetBar ) -> Cancels DB-Retrieval (win.Key!)
//    of_DWCancel( as_Message, al_Color, ab_Bold, ab_ResetBar ) -> Stops DW-Retrieval (dw.RetrieveRow!)
//    of_End( al_RowCount, as_Message, al_Color, ab_Bold, ab_ResetBar ) -> Re-configures/Refreshes the Progress-bar
//    of_Increment()                   -> Increments the Progress-bar by ii_Increment in a RAW-style
//    of_IsCancelled() -> Status indicating whether Retrieval was Cancelled using of_DBCancel() (dw.RetrieveEnd!)
//    of_Message(  as_Message, al_Color, ab_Bold, ab_ResetBar ) -> Displays as_Message on the Progress-bar
//    of_Progress( al_RelativePosition, as_Message ) -> Shows Progress-bar graphically in proportion to ii_Width
//    of_Progress() -> Re-paints the Progress-bar [See: of_SetWidth()]
//    of_SetBarColor( al_Color ) -> Sets the Progress-bar Color property
//    of_SetIncrement( ai_Increment )  -> Sets the Next-Increment value for RAW-progressing
//    of_SetLimit( al_Limit )          -> Sets a new value for il_Limit (used in dw.RetrieveEnd! event)
//    of_SetWidth( ai_Width )          -> Sets the Width properties of the Progress-bar (now CUSTOMIZEABLE!!)
//    of_Start( adw_Obj,  as_Message ) -> Gets the RowCount(*) of dw using DYNAMIC SQL and configures itself to Ready!
//    of_Start( al_Limit, as_Message ) -> Sets al_Limit to il_Limit and configures itself to Ready!
//    of_Stop() -> Sets il_Limit to 0, st_Progress' Position to 0, Message to "" and makes itself invisible!
//    of_Stop( as_Message, al_Color, ab_Visible, ab_ResetBar ) -> Fore TOTAL Developer-control
//
//
//    OTHER FUNCTIONS (be ADVENTUROUS to try these out!):
//    --------------------------------------------------
//    of_CountStar( adw_Obj ) -> Uses DYNAMIC-SQL to get Count(*) from the db. Called by of_Start() but has PUBLIC scope!
//    of_CountStar( as_SQL )  -> Uses DYNAMIC-SQL to get Count(*) from the db using a raw-SQL.
//    of_GetBarColor()        -> Returns the current Color property-value of the Progress-bar
//    of_GetIncrement()       -> Returns the Next-Increment value
//    of_GetLimit()           -> Returns the value of il_Limit set using of_Start(), of_SetLimit()
//    of_GetPosition()	      -> Returns the Width (NOT: il_Limit) of the st_Progress in ii_Width's [See: of_SetWidth()].
//    of_GetTextColor()       -> Returns the current Text property-value of the Progress-bar
//    of_GetWidth()           -> Returns the Width the Progress-bar (that is now customizeable!)
//    of_IsActive() 		      -> Status indicating if Progress-bar is of_Start()ed or of_Stop()ped.
//    of_IsMessage()          -> Indicates whether the Message is displayed or suppressed [of_Progres()]
//    of_IsStatus()           -> Indicates whether the Status  is displayed or suppressed [row/rowCount] through of_Progress()
//    of_SetMessage( ab_Message )   -> Sets the flag whether to display/suppress Message [through of_Progress()]
//    of_SetPosition( ai_Position ) -> Sets/jumps to the internal-position of the Progress-bar in a RAW-style (Range: 0 - ii_Width)
//    of_SetStatus( ab_Switch )     -> Sets the flag whether to display/suppress Status [row/rowCount] [through of_Progress()]
//    of_SetTextColor( al_Color )   -> Sets the Text Color property for Message & Status
//
//
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Usage  : Usage of this object is pretty simple. Most of all, it works with a very 'few' lines of code!
//    Place the u_Dynamic_ProgressBar object on the window as a uo, first.
//
//    DATA-RETRIEVAL: [Determines Count(*) using DYNAMIC-SQL]. Because of PowerScript in dw.RetrieveRow!, the
//       runtime behaves in asynchronous mode and does not hang the app until the retrieval is over - you can
//       click on other menu items, buttons... and switch back-n-forth to another Windows process freely!
// 	--------------------------------------------------------------------------------------------------------
//    dw.RetrieveStart!
//       Pre-determine the number of rows that are 'going' to be retrieved. 
//       of_Start() determines the Count(*) using DYNAMIC-SQL [of_CountStar()] and sets its il_Limit.
//       You may call of_Start() as many times as required without calling of_Stop(!)
//       For dynamic Argument-Values, see of_Start( as_SQL ) version!
//
//       All Argument-Values are to be resolved by the dw using this version of of_Start():
//       il_Count = dw_ProgressBar.of_Start( adw_Obj, "Initializing..." )     // Store the return-value in an instance-var
//
// OR:   Use this version of of_Start() to resolve/EMBED the Argument-Values using string/other-functions:
// ---
//       Eg: ls_SQL = "... WHERE col1 = '" + var1 + "' and col2 = " + String ( var2 ) ...
//       il_Count = dw_ProgressBar.of_Start( as_SQL,  "Initializing..." )
//
//
//    dw.RetrieveRow!
//       // Flags the internal var: ib_Cancelled to TRUE in dw_ProgressBar uo - if aborted
//       IF dw_ProgressBar.of_DWCancel( "Abort retrieval?", RGB( 255,0,0 ), TRUE, FALSE ) > 0 THEN
//          RETURN 1           // If you want to offer the ability to Stop the dw retrieval
//       END IF
//       //
//       IF il_Count > 0 THEN
//          dw_ProgressBar.of_Progress( row, "Retrieving (Esc/F3 to Cancel):" )     // Show progress
//       END IF
//
//
//    dw.RetrieveEnd!
//       // Re-configure the Progress-bar
//       // Display abortion message - Don't reset/stop the Progress-bar! Leave it Visible!!
//       dw_ProgressBar.of_End( rowCount, "Retrieval Aborted", RGB( 255,0,0 ), TRUE, FALSE )
//       // However, if you want to RESET the Progress-bar, call: of_Stop(!)
//
//
//    dw.RowFocusChanged!
//       // Use of_Message() or nothing in the RetrieveEnd! event [NOT: of_Stop()]
//       // This does NOT work if of_Stop() was used in the dw.RetrieveEnd! event
//       dw_ProgressBar.of_Progress( currentRow, "Row:" )
//
//
//    win.Key!         // If you want to offer the ability to Cancel the retrieval process
//       // The akc_CancelKeys[] argument is an array of keyCodes to treat as Cancel-keys (accepts multiple keys)
//       dw_ProgressBar.of_DBCancel( key, { KeyEscape!, KeyF3! }, "Retrieval Cancelled", RGB( 255,0,0 ), TRUE, FALSE )
//
//
// ----------------------------------------------------------------------------------------
//    DW-SCANNING/NON-RETRIEVAL:
//    Uses of_Start( ll_Count... ) instead of of_Start( dw...)
//    --------------------------------------------------------
//    long	ll_Row, ll_Count
//    //
//    ll_Row = dw.RowCount()
//    dw_ProgressBar.of_Start( ll_Count, "Validating..." )      // Sets its il_Limit and gets Ready!
//    //
//    FOR ll_Row = 1 TO ll_Count
//       Yield()
//       ...
//       dw_ProgressBar.of_Progress( ll_Row, "Validating:" )
//       ...
//    NEXT
//    //
//    dw_ProgressBar.of_Stop()
//
//
// ----------------------------------------------------------------------------------------
//    DW-ROW POSITION:
//    Use of_Message() in the dw.RetrieveEnd! event INSTEAD of of_Stop()
//    ------------------------------------------------------------------
//    dw.RowFocusChanged!       
//       dw_ProgressBar.of_Progress( currentRow, "Row:" )
//
//
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Ref    : 
// Version: 3.0
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Modifications:
//
// Date       Author                   Comments
// --------------------------------------------------------------------------------------------------------------
// 10-23-02   PowerObject! [Shekar]    Added of_End() to simplify code in dw.RetrieveEnd!
//                                     Flags ib_Cancelled to TRUE and refreshes the il_Limit value in the ProgressBar.
//                                     If rowCount [Count(*)] CHANGES during retrieval, this takes care of it.
//
// 10-23-02   PowerObject! [Shekar]    of_DBCancel() now processes ib_Cancelled flag to handle win.Key! event PRECISELY
//
// 06/23/04   PowerObject! [Shekar]    New function of_Progress() to repaint the ProgressBar [used in of_SetWidth()]
//                                     Fixed a glitch in of_SetWidth() (app crash on close); used the new of_Progress()
//
// 06/24/04   PowerObject! [Shekar]    Autosizes the Width to 'design-time' width instead of the default 1000!
// 06/24/04   PowerObject! [Shekar]    ProgressBar now shows the rectangular border - always.
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Copyright  2001-2004 Shekar C. Reddy [PowerObject!]. Unpublished rights reserved.
//
// FREEWARE: Commercial use allowed. If you want to redistribute this object, please include the ReadMe.txt file.
// If you want to use this object in your applications, please retain this Copyright Notice in your work and include
// a message on the About Box saying:
//
//    "Portions Copyright  2001-2004 Shekar C Reddy"
//
// I ask this of you because this work can be used on almost 'every' window inside an application!
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

Good luck!