Door 14 - Progress Dialog

Do you know this? You have to go through many records and it takes and takes and takes time? Some users then become frustrated and start hammering on the keyboard or pressing all kinds of buttons because they don't know that there are already processes running in the background that simply need its time.

With the MBS Progress dialog, you can display a dialog to your users so that there is no confusion or panic. To do this, you have the functions from the ProgressDialog component.

Before we can display the progress dialog, we first have to make a few settings for the dialog. The special thing about the dialog is that you can set the content in a script and then call it up at a later time in the different layouts in our solution. For this reason, we must first reset the dialog to its initial state to remove legacy content before we make new settings. To do this, we use the ProgressDialog.Reset function. Now we can give the dialog box a title. We use ProgressDialog.SetTitle for this. In the dialog you can also enter a text above the progress bar and one below. We use the ProgressDialog.SetTopText and ProgressDialog.SetBottomText functions for this. We can also select a font and size for these two texts. We set these values in the ProgressDialog.SetFont function. To make the dialog look nicer, we can also display an icon in the dialog to make it easier to understand. In our case, this is the monkey with the Christmas hat. We set this image, which is in a container, with the ProgressDialog.SetImage. If you use a PNG with transparent background, you don't get the white border around.

Set Variable [ $r ; Value: MBS("ProgressDialog.SetTitle"; DoorFourTeen::Title) ]
Set Variable [ $r ; Value: MBS("ProgressDialog.SetFont"; "Comic Sans MS"  ; 14  ) ]
Set Variable [ $r ; Value: MBS("ProgressDialog.SetTopText"; DoorFourTeen::Text) ]
Set Variable [ $r ; Value: MBS("ProgressDialog.SetBottomText"; "Wait...") ]
Set Variable [ $r ; Value: MBS("ProgressDialog.SetImage"; DoorFourTeen::Container) ]

If we want to display the dialog, we use the ProgressDialog.Show function. This shows the dialog. The dialog is displayed as long as FileMaker is not closed or the ProgressDialog.Hide function is not called.

We see that the dialog still has a button, which is usually used as a cancel button. If we do not want this button to be displayed, we use the ProgressDialog.SetShowButton function and pass a 0 in the parameters. If we want to change the text of the button, we use the ProgressDialog.SetButtonCaption function to which we pass the text to be displayed on the button. If we leave the script as it is and display the dialog, nothing happens when we click on the button. Because we first have to define a script that is called when the button is pressed or specify an expression. If we want to specify a script, we use the Progressdialog.SetScript function. In our example, we use an expression that we specify in the Progressdialog.SetEvaluate function. We want to set the cancel flag in this function to 1. I'll explain what this does for us in more detail later. The flag is set with the ProgressDialog.SetCancel function *.

Set Variable [ $r ; Value: MBS("Progressdialog.SetEvaluate"; "MBS(\"ProgressDialog.SetCancel\"; 1)") ] 

Now our dialog should not only show the standard animation of the bar, but should also show the progress. In our case, we would like to display a bar that runs for approximately a number of seconds, but it could also be the passes with which data records are written to your database, or whatever else you need the bar for. To do this, we first set the progress bar to the value 0, i.e. at the very beginning of the bar. Then we pause for a second because the animation in the progress dialog should run to the end before it starts at 0. The value that we set in ProgressDialog.SetProgress again and again, in the following loop, can have values between 0 and 100. For this reason, we first want to calculate how much the value of the progress increases with each loop run. To do this, we calculate 100/number of loop passes. We then always add this calculated value to the current value in the loop and enter this as the new value to be set. The value for the loop passes originally comes from a field. Here we have to make sure that the field is of type number, otherwise the value is recognized as text and the number of loop passes is usually incorrect.

Within the loop, we also change the text below the progress bar. To do this, we again use the ProgressDialog.SetBottomText function. To ensure that this change, as well as all other changes in the dialog, are displayed reliably, we call the ProgressDialog.Update function, which sets a flag so that the dialog is redrawn when the memory usage allows it.

We exit the loop when we are either done with the runs or when the cancel flag is set. This means when someone has pressed the cancel button in the dialog. We query this flag with ProgressDialog.GetCancel.

After the loop has been exited, we then hide the dialog again with ProgressDialog.Hide

Set Variable [ $r ; Value: MBS("ProgressDialog.SetProgress"; 0) ] 
Pause/Resume Script [ Duration (seconds): 1 ] 
Set Variable [ $TotalLoops ; Value: DoorFourTeen::Time ] 
Set Variable [ $CurrentProgress ; Value: 0 ] 
Set Variable [ $ProgressValue ; Value: 100/$TotalLoops ] 
Set Variable [ $i ; Value: 0 ] 
Loop
	Set Variable [ $CurrentProgress ; Value: $CurrentProgress + $ProgressValue ] 
	Set Variable [ $r ; Value: MBS("ProgressDialog.SetProgress"; $CurrentProgress) ] 
	Set Variable [ $r ; Value: MBS("ProgressDialog.SetBottomText"; $i+1 & " of " & $TotalLoops) ] 
	Exit Loop If [ $i  ≥ $TotalLoops or MBS("ProgressDialog.GetCancel") ] 
	Pause/Resume Script [ Duration (seconds): 1 ] 
	Set Variable [ $r ; Value: MBS("ProgressDialog.Update") ] 
	Set Variable [ $i ; Value: $i+1 ] 
	# 
End Loop
Set Variable [ $r ; Value: MBS("ProgressDialog.Hide") ] 

I hope you enjoyed this door and can't wait to see your progress bars in your solutions.

* The cancel flag is set automatically if you don't add a custom action to the button, but we still like to show you how to do the evaluate.