Purpose
Displays a dialog box with a Cancel button and a horizontal progress bar.
Syntax
ProgressBar status_message
Calling handler
[ Range n ] status_message is a string value displayed as a message in the dialog box.
handler is the name of a Sub procedure.
n is a number at which the job is finished.
Restrictions
You cannot issue the ProgressBar statement through the MapBasic window.
Description
The ProgressBar statement displays a dialog box with a horizontal progress bar and a Cancel button. The bar indicates the percentage of completion of a lengthy operation. The user can halt the operation by clicking the Cancel button. Following the ProgressBar statement, a MapBasic program can call CommandInfo(CMD_INFO_DLG_OK) to determine whether the operation finished or whether the user cancelled first (see below). Where CMD_INFO_DLG_OK (1).
The status_message parameter is a string value, such as "Processing data...", which is displayed in the dialog box.
The handler parameter is the name of a sub procedure in the same MapBasic program. As described below, the sub procedure must perform certain actions in order for it to interact with the ProgressBar statement.
The n parameter is a number, representing the count value at which the operation will be finished. For example, if an operation needs to process 7,000 rows of a table, the ProgressBar statement might specify 7000 as the n parameter. If no Range n clause is specified, the n parameter has a default value of 100.
When a program issues a ProgressBar statement, MapBasic calls the specified handler sub procedure. The sub procedure should perform a small amount of processing, specifically a few seconds' worth of processing at most, and then it should end. At that time, MapBasic checks to see if the user clicked the Cancel button. If the user did click Cancel, MapBasic removes the dialog box, and proceeds with the statements which follow the ProgressBar statement (and thus, the lengthy operation is never completed). Alternately, if the user did not click Cancel, MapBasic automatically calls the handler sub procedure again. If the user never clicks Cancel, the ProgressBar statement repeatedly calls the procedure until the operation is finished.
The handler procedure must be written in such a way that each call to the procedure performs only a small percent of the total job. Once a ProgressBar statement has been issued, MapBasic will repeatedly call the handler procedure until the user clicks Cancel or until the handler procedure indicates that the procedure is finished. The handler indicates the job status by assigning a value to the special MapBasic variable, also named ProgressBar.
If the handler assigns a value of negative one to the ProgressBar variable (ProgressBar = -1) then MapBasic detects that the operation is finished, and accordingly halts the ProgressBar loop and removes the dialog box. Alternately, if the handler procedure assigns a value other than negative one to the ProgressBar variable (ProgressBar = 50) then MapBasic re-displays the dialog box's "percent complete" horizontal bar, to reflect the latest figure of percent completion. MapBasic calculates the current percent of completion by dividing the current value of the ProgressBar variable by the Range setting, n. For example, if the ProgressBar statement specified the Range clause Range 400 and if the current value of the ProgressBar variable is 100, then the current percent of completion is 25%, and MapBasic will display the horizontal bar as being 25% filled.
The statements following the ProgressBar statement often must determine whether the ProgressBar loop halted because the operation was finished, or because the user clicked the Cancel button. Immediately following the ProgressBar statement, the function call CommandInfo(CMD_INFO_DLG_OK) returns TRUE if the operation was complete, or FALSE if the operation halted because the user clicked cancel. Where CMD_INFO_DLG_OK (1).
Example
The following example demonstrates how a procedure can be written to work in conjunction with the ProgressBar statement. In this example, we have an operation involving 600 iterations; perhaps we have a table with 600 rows, and each row must be processed in some fashion. The main procedure issues the ProgressBar statement, which then automatically calls the sub procedure, write_out. The write_out procedure processes records until two seconds have elapsed, and then returns (so that MapBasic can check to see if the user pressed Cancel). If the user does not click Cancel, MapBasic will repeatedly call the write_out procedure until the entire task is done.
Include "mapbasic.def"
Declare Sub Main
Declare Sub write_out
Global next_row As Integer
Sub Main
next_row = 1
ProgressBar "Writing data..." Calling write_out Range 600
If CommandInfo(CMD_INFO_STATUS) Then
Note "Operation complete! Thanks for waiting."
Else
Note "Operation interrupted!"
End If
End Sub
Sub write_out
Dim start_time As Float
start_time = Timer( )
' process records until either (a) the job is done,
' or (b) more than 2 seconds elapse within this call
Do While next_row <= 600 And Timer( ) - start_time < 2
''''''''''''''''''''''''''''''''''''''''''
''' Here, we would do the actual work '''
''' of processing the file. '''
''''''''''''''''''''''''''''''''''''''''''
next_row = next_row + 1
Loop
' Now figure out why the Do loop terminated: was it
' because the job is done, or because more than 2
' seconds have elapsed within this iteration?
If next_row > 600 Then
ProgressBar = -1 'tell caller "All Done!"
Else
ProgressBar = next_row 'tell caller "Partly done"
End If
End Sub See Also:
CommandInfo( ) function, Note statement, Print statement