mixed fm_new_progress_bar ( string $progress_bar_name, int $number_of_steps, string $message [, int $left [, int $top [, bool $enable_cancel_button [, string $cancel_button_label ]]]] )
Description
Allows you to display a progress bar dialog.
Notes regarding the cancel button:
- Use fm_user_cancelled to determine if the cancel button has been pressed.
- Use fm_get_last_error or PHP_GetLastError to check for error 203 (user cancelled).
- You can set the number of seconds the plug-in will wait before exiting by using PHP_Configure to set the CancelSeconds setting.
Parameters
progress_bar_name (required)
The name to be used when referencing the progress bar.
number_of_steps (required)
The number of steps that the progress bar will display. Use 0 for a “barber pole” type progress bar.
message (required)
The message to be displayed on the progress bar.
left (optional)
The left position of the progress bar dialog. The default position is the center of the screen.
top (optional)
The top position of the progress bar dialog. The default position is the center of the screen.
enable_cancel_button (optional)
Adds a cancel button to the progress bar allowing the user to cancel execution. Use fm_user_cancelled to determine if the cancel button was pressed. Also reference fm_get_last_error or PHP_GetLastError and check for error 203 (user cancelled).
cancel_button_label (optional)
Allows you to customize the cancel button label. The default is “Cancel”.
Return
Returns true if the progress bar was created, false if a progress bar with the same name already exists or null if progress bars are disabled.
Errors
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
$name = 'Test';
$steps = 10;
$message = 'Testing, one moment please...';
$left = 25;
$top = 50;
$enableCancelButton = true;
$cancelButtonLabel = 'Stop';
fm_new_progress_bar($name, $steps, $message, $left, $top, $enableCancelButton, $cancelButtonLabel);
for ($i = 0; $i < $steps ; $i++) {
sleep(1); // this is where you would do your processing
fm_update_progress_bar($name, 1, $message . " step " . ($i + 1));
if (fm_user_cancelled() === true) break;
}
// Make sure to close the progress bar.
fm_close_progress_bar($name); |
Change Log
| Version | Description |
|---|---|
| 3.0.0 | Added parameters: enable_cancel_button, cancel_button_label. |