Implementing the Dial_ProgressBar function of Troi Dialog Plug-in

By October 12, 2019 October 13th, 2019 Additional info

Troi Dialog Plug-in adds the Dial_ProgressBar function to FileMaker Pro. This function manages the display of a progress bar dialog box. With this function you can indicate to a user that a script is doing a lengthy operation, and provide feedback on how long this operation will last. Below you see an example progress bar:

The Dial_ProgressBar function should be implemented in 3 phases:

  1. Showing the progress bar: make the progress bar visible.
  2. Updating the progress bar: increases the progress bar (multiple times, usually in a loop).
  3. Removing the progress bar: the progress bar dialog is removed.

Phase 1: Showing the progress bar

The purpose of this phase is to tell the plug-in to start showing the progress bar and to specify the maximum value the progress bar should go to and to give an initial text. Here is the syntax for this phase:

  Dial_ProgressBar( "-Unused" ; "show" ; maxval ; "textToShow" )

The parameter maxval should be the result of a calculation of the number of steps. This can be for example based on the number of found records on which the script is working. Use the Get( FoundCount ) function for this.

An example script step can be:

  Set Variable [ $Result ; Dial_ProgressBar( "-Unused" ; "show" ; 
                                            Get( FoundCount ) ; "Starting..." ) ]

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

Phase 2: Updating the progress bar

This phase usually occurs in a loop. When FileMaker has performed a number of actions, like for example processed 10 records, you need to give feedback to the user by updating the display of the progress bar. Here is the syntax for this:

  Dial_ProgressBar ( "-Unused" ; "incr" ; increaseValue ; newtext )

The parameter  increaseValue should be the result of a calculation of the number of steps that have been handled. You can also give an optional new text to be shown.
So an example script step can be:

  Set Variable [ $Result ; Dial_ProgressBar ( "-Unused" ; "incr" ; 10 ; "Still working..." ) ]

Phase 3: Removing the progress bar

If you no longer want to show the progress bar dialog you need to remove the progress bar. This step usually occurs just after the end of the loop. This phase has only “stop” as parameter:

  Set Variable [ $Result ; Dial_ProgressBar ( "-Unused" ; "stop" ; ) ]

Example script with progress bar

Below you see an example script which combines the 3 phases. We use two variables in this example:

    $NumberOfStepsnumber
    $Resulttext

Use these script steps:

# Calculate the number of steps
Set Variable [ $NumberOfSteps ; Get ( FoundCount ) ]
# Make the progress bar visible with the initial text
# The 2nd parameter indicates the total number of steps:
Set Variable [ $Result ; Dial_ProgressBar ( "-Unused" ;
                        "show" ; $NumberOfSteps ;
                        "Showing a simple progress bar...¶¶Please wait." ) ]
Go to Record [ First ]
Loop
  # Increase the progress bar by 1
  Set Variable [ $Result ; Dial_ProgressBar ( "-Unused" ; "incr" ; 1 ; ) ]
  ...
  You should do your time consuming stuff here!
  ...
  Go to Record [ Next ; Exit after last ]
End Loop
# Remove the progress bar
Set Variable [ $Result ; Dial_ProgressBar ( "-Unused" ; "stop" ; ) ]

How to proceed further

In the download of the Troi Dialog-in we provide the Progress.fmp12 example file to help you get started quickly. You can download the demo of Troi Dialog Plug-in here.