Troi
Boliviastraat 11
2408 MX Alphen aan den Rijn
The Netherlands

You can visit the Troi web site at: www.troi.com

Troi Dialog Plug-in is copyright 1998-2019 of Troi Automatisering. All rights reserved.

Table of Contents

• Installing plug-ins
• If you have problems
• What can this plug-in do?
• Software requirements
• Getting started
• • Using external functions
  • Where to add the external functions?
  • Using script steps
  • Simple example
  • You can use globals or variables
  • Using icons
• Using the Dial_Progressbar function
• • Phase 1: Showing the progress bar
  • Phase 2: Updating the progress bar
  • Phase 3: Removing the progress bar
  • Example script with progress bar
• Function and script step reference

Installing plug-ins

Starting with FileMaker Pro 12 a plug-in can be installed directly from a container field. Installation is therefore very easy: just open the "All Dialog Examples.fmp12" example file and the startup script will install the plug-in for you. See also the EasyInstallTroiPlugins.fmp12 example file which contains the actual plug-in and install script.

TIP You can check which plug-ins you have loaded by going to the plug-in preferences: choose Preferences from the Edit menu, and then choose Plug-ins.

You can now open the file "All Dialog Examples.fmp12" to see how to use the plug-in's functions. There is also a function and script step reference available.

If you have problems

This user guide tries to give you all the information necessary to use this plug-in. So if you have a problem please read this user guide first. You can also visit our support web page:

            www.troi.com/support

This page contains FAQ's (Frequently Asked Questions), help on registration and much more. If that doesn't help you can get free support by email. Send your questions to support@troi.com with a full explanation of the problem. Also give as much relevant information (version of the plug-in, which platform, version of the operating system, version of FileMaker Pro) as possible. Note that due to spam we have to filter incoming email. It might happen that non-spam email is filtered out too. If you have sent an email and you don't get an answer, try to send another email, slightly differently formulated and include the word "FileMaker" in the body text.

If you find any mistakes in this manual or have a suggestion please let us know. We appreciate your feedback!

TIP You can get more information on returned error codes from the OSErrrs database on our web site. This free FileMaker database lists all error codes for Windows and macOS!

What can this plug-in do?

Troi Dialog Plug-in is a very powerful tool for adding dynamic dialog functions to FileMaker Pro. With it you can show several types of dialogs from a FileMaker script, where the dialog text and the buttons are generated dynamically. All from within FileMaker you can:

• show sophisticated (input) dialogs
• show password dialogs
• show flash dialogs
• show list dialogs
• show big input dialogs
• and more...

Software requirements

System requirements for macOS

Mac OS X 10.11 (El Capitan), macOS 10.12 (Sierra), macOS 10.13 (High Sierra), macOS 10.14 (Mojave) and macOS 10.15 (Catalina).

NOTE Troi Dialog Plug-in 8 will probably run on OS X 10.9 (Mavericks) and OS X 10.10 (Yosemite), but we have not tested this and no longer provide support for this.

System requirements for Windows

Windows 7
Windows 8, Windows 8.1
Windows 10 including Creators Update, Fall Creators Update, April 2018 Update, October 2018 Update and May 2019 Update.

FileMaker Pro requirements

FileMaker Pro 14 or FileMaker Pro Advanced 14.
FileMaker Pro 15 or FileMaker Pro Advanced 15.
FileMaker Pro 16 or FileMaker Pro Advanced 16.
FileMaker Pro Advanced 17.
FileMaker Pro Advanced 18.

FileMaker Server

You can use FileMaker Server 14-18 to serve databases that use functions of Troi Dialog Plug-in (client-side): you need to have the plug-in installed at the clients that use these functions.

Getting started

Using external functions

Troi Dialog Plug-in adds new functions to the standard functions that are available in FileMaker Pro. The functions added by a plug-in are called external functions. You can see those extra functions for all plug-ins at the top right of the Specify Calculation box:

You use special syntax with external functions: FunctionName ( parameter1 ; parameter 2 ) where FunctionName is the name of an external function. A function can have zero or more parameters. Each parameter is separated by a semi-colon. Plug-ins don't work directly after installation. To access a plug-in's function, you need to add the calls to the function in a calculation, for example in a Set Field or Set Variable script step in Script Workspace (formaly called ScriptMaker).

Where to add the external functions?

External functions for this plug-in are intended to be used in a script step using a calculation. For most functions of this plug-in it makes no sense to add them to a define field calculation, as the functions will have side effects.

Using script steps

Starting with FileMaker 16 plug-ins can also add script steps. You can select these script steps in the script steps pane in Script Workspace, or you can begin typing the script step name, then choose the script step from the list that appears. The script steps expand the possible actions you can perform with FileMaker Pro.

NOTE only steps that perform an action have been added as a script step. Functions that just manipulate data and have no side effects (like for example Dial_GetButton) are only available as an external function.

Simple example

This example shows how to begin using Troi Dialog Plug-in. Say you have a database Persons.fmp12, with a text field called NameTotal. You want to display a dialog where you display this name from the current record. In Script Workspace create a script "Display current name". Add the following script step to this script:

  Set Field [ myResultField ; Dial_Dialog ( "-NoteIcon" ; "The current person has this name: ¶¶" & NameTotal ; "OK" ) ]

This will show you a dialog with the text and an OK button, similar to this:

NOTE Function names, like Dial_Dialog, are not case sensitive.

Please take a close look at the included example files, as they provide a great starting point. From there you can move on, using the functions of the plug-in as building blocks. Together they give you all the tools you need to show your users sophisticated dialogs.

You can use globals or variables

With the release of FileMaker Pro 8 and later it is possible to use variables in calculations. Our example files in the download now both use global fields and variables to pass parameters and store the results of a plug-in function.

As this release of Troi Dialog is intended for FileMaker Pro 14 and higher, we continue to move the scripts to use variables wherever possible. Note that not all examples are using variables yet.

All plug-in functions work with variables just fine. For example if you have this script step

  Set Field [ myResultField ; Dial_Dialog ( "-NoteIcon" ; "The current person has this name: ¶¶" & NameTotal ; "OK" ) ]

With variables you can alternatively use:

  Set Variable [ $myResult ; Dial_Dialog ( "-NoteIcon" ; "The current person has this name: ¶¶" & NameTotal ; "OK" ) ]

The main advantage of variables is that you don't need to define global fields that clutter your database definitions. The variables can stay local to the script.

Using icons

You can specify which icon to add to a dialog. This can be one of the standard icons or a custom icon. See below for the standard icons which can be shown:

Using the Dial_ProgressBar function

Troi Dialog Plug-in adds the Dial_ProgressBar function, which 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" ; increase value ; newtext )

The parameter increase value 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:

  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:

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" ; ) ]

Function and script step reference

For a description of all External Functions and External Script Steps added by Troi Dialog Plug-in please see the separate Reference.fmp12 file. For each function and script step you will find:

• the correct syntax
• the parameters/options to be used
• the returned result
• special considerations
• an example usage

The same information is also available as online help on Troi's web site.

You can easily consult the online help directly from FileMaker, by clicking the Help button (the small question mark button) next to the function description in the functions pane or the script step description in the script steps pane.