Platform: Not Platform Related
ProgressBar - Description.
What is the ProgressBar statement?
Displays a dialog with a Cancel button and a horizontal progress bar.
[ Range n ]
status_message is a String value displayed as a message in the dialog
handler is the name of a Sub procedure
n is a number at which the job is finished
The ProgressBar statement cannot be issued through the MapBasic window.
The ProgressBar statement displays a dialog 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). The status_message parameter is a String value, such as "Processing data...", which is displayed in the dialog.
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 - 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, 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. Alternately, if the handler procedure assigns a value other than negative one to the ProgressBar variable:
ProgressBar = 50
then MapBasic re-displays the dialog'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:
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:
returns TRUE if the operation was complete, or FALSE if the operation halted because the user clicked cancel.
The following example demonstrates how a procedure can be written to work in conjunction with the ProgressBar statement. In this example, there is an operation involving 600 iterations; perhaps there is 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 press cancel, MapBasic will repeatedly call the write_out procedure until the entire task is done.
Declare Sub Main
Declare Sub write_out
Global next_row As Integer
next_row = 1
ProgressBar "Writing data..." Calling write_out Range 600
If CommandInfo(CMD_INFO_STATUS) Then
Note "Operation complete! Thanks for waiting."
Note "Operation interrupted!"
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, the actual work is done '''
''' of processing the file. '''
next_row = next_row + 1
' 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!"
ProgressBar = next_row 'tell caller "Partly done"
Dialog statements and functions.
Last Modified: 10/10/2001 12:27:27 PM