Dial_ProgressBar (function reference)

By November 1, 2020November 10th, 2020Online Help, Troi Dialog Plug-in
Troi Dialog Plug-in for FileMaker Pro

Dial_ProgressBar

Displays a progress bar dialog box.

SyntaxFunction badge

Dial_ProgressBar ( switches ; command ; maxval/incrval ; text ) ]

Parameters

switches
command the command to be used
maxval the number of steps that should be used
incrval indicates how much steps the progress bar should increase
text the text to be shown

Switches

Switches can be empty or one of these:

-NoteIcon shows a note icon (indicating this dialog gives the user information)
-CautionIcon shows a caution icon (indicating this dialog warns the user)
-StopIcon shows a stop icon (indicating this is something severe which the user needs to address )
-CustomIcon shows a custom icon. This icon needs to be set before with the Dial_IconControl function

You can also add this switch:

-IconSize=48 display the icon at 48×48 pixels

You can also add this switch:

-Floating This will open the progress bar as a floating window (this switch has only effect on Windows)

The ‘command’ parameter indicates the commands, which may be: Show, Incr or Stop. They are to be used as follows:
1- Show command: makes the progress bar dialog box visible.
2- Incr command: increases the progress bar (multiple times, usually in a loop).
3- Stop command: the dialog is removed.

Returned Result

Data type returned

Error code

Result

This function returns 0 as result.

Originated in

Troi Dialog Plug-in 1.2

Compatibility

FileMaker Pro 15 to 19

Considerations

If you specify a zero as maxval, an indefinite progress bar is shown (barber pole).

In some cases the time to perform lengthy scripts might increase, as FileMaker updates the screen after the ProgressBar step. A freeze screen step does not always help.

IMPORTANT Use only in a script. Do not use this function in a calculated field definition, because when FileMaker calculates the fields this will result into a repeated dialog for EACH record. Also note that functions that use the clipboard, like pasting in a container field, will not work, as they try to paste in the progress bar window.

See also the Dial_SetPreference function to change the time of automatic removal of a progress dialog.

You can also suppress the title in all ProgressBar dialogs by adding this to your (startup) script:

Dial_SetPreference ( "-TitlesInProgressBarDialogs" ; "off" )

This will set the Progress bar title to blank for all subsequent calls until FileMaker is restarted.

Version 8.0 added support for (custom) icons.
Version 9.0 added the “-Floating” switch. This will open the progress bar as a floating window. When using this switch the focus is not tied to the front FileMaker window, enabling to use for example the “New Window” step in the script, the progress dialog will float above the new window. This switch has only effect on Windows.

Example

Use this function to indicate to a user that a script is doing a lengthy operation and provide feedback on how long this operation will last.

For a detailed description see the section “Using the Dial_ProgressBar function” in the user guide or on our web site here.

Related functionsFunction badge

Dial_IconControl
Dial_SetPreference

Related topics

Troi Dialog Plug-in online help (overview)


Online Help Page for Troi Dialog Plug-in for 15 to 19 –> Dial_ProgressBar (dialp4310) 2020-1110 10:39:52