Dial_ScheduleNotification (function reference)

Troi Dialog Plug-in > Functions reference > Dial_ScheduleNotification
Troi Dialog Plug-in for FileMaker Pro

Dial_ScheduleNotification

Schedules the display of a notification dialog on screen (and in the notification center)

SyntaxFunction badge

Dial_ScheduleNotification( switches ; notificationID ; delay ; title ;
                           message ; buttonLabel ; fileName ; scriptName ;
                           scriptParameter )

Parameters

switches(optional) this changes the behavior of the notification
notificationIDa unique id for the notification that you can supply
delaythe number of seconds to wait before displaying the notification
titlethe title of the notification
messagethe message of the notification
buttonLabel(optional) the text of an action button
fileName(optional) the file name where the optional trigger script is located
scriptName(optional) the name of the script to be triggered when the user interacts with the notification
scriptParameter(optional) script parameter

Switches

Switches can be empty or one of these:

-NoSoundshows the notification without a sound
-ShowNotRequiredthe OS may decide not to show it when FileMaker is in front (macOS only)

Returned Result

Data type returned

Error code

Result

If successful it returns 0. If unsuccessful it returns an error code starting with $$ and the error code. Returned error codes can be:

$$-50paramErrparameter error
$$-4221invalidOSVersionnotifications are not supported on this OS version
$$-4291notificationsNotEnablednotifications are not enabled in the preferences
$$-4292InitializeErrnotifications could not be initialized
$$-4293scriptWontTrigger(warning only) the script will not be triggered but the notification will be shown

Originated in

Troi Dialog Plug-in 7.5

Compatibility

FileMaker Pro 14 to 17

Considerations

You may need to allow FileMaker to show notifications and specify the alert style in the system preferences.

The optional trigger script is run *after* the notification was clicked (on the notification itself or the action button).
Note that on Windows the script will only be triggered when the notification is shown directly (with delay set to zero). When the delay is not zero the notification will still be shown and a warning code $$-4293 will be returned as a result.

If you specify a script to trigger, a multiline parameter is passed to the script, which will be formatted like this:
line 1 the id of the notification
line 2 <button label> or the status*
line 3 1 = if FileMaker was in the foreground ; 0 = in the background
line 4..n the optional script parameter

*status can be NotificationSelected, NotificationNotDisplayed or NotificationNotAllowed.

Notifications require macOS 10.8 and higher or Windows 8 and higher.

Example

Set Variable [ $ErrorCode ; Dial_ScheduleNotification ( 
                    "-Unused" ; "note123" ; 10 ; "Time is up" ; "Your egg is ready!" ) ]

This will show this notification after 10 seconds.

Example 2

Create the following script:

# First fill in what you want in variables:
Set Variable [ $NotificationID ; Get ( UUID ) // set this to an a Universally Unique Identifier (UUID) ] 
Set Variable [ $DelaySecs ; 5 ]
Set Variable [ $Title ; "Notification with Troi Dialog" ]
Set Variable [ $MessageBody ; "The notification with Troi Dialog was a success!" ]
Set Variable [ $ActionButtonLabel ; "Show me" // is optional ]

# Set the trigger script, which is run *after* the notification was clicked.
# If notifications are disabled for FileMaker, the script still runs at the scheduled time.
Set Variable [ $FileName ; Get ( FileName ) ]
Set Variable [ $ScriptName ; "TRIGGERSCRIPT1" ]

# Now Schedule the notification:
Set Variable [ $ErrorCode ; Dial_ScheduleNotification ( "-Unused" ; $NotificationID ; $DelaySecs ; $Title ; 
                     $MessageBody ; $ActionButtonLabel ; $FileName ; $ScriptName ) ]

This will show this notification after a 5 seconds delay. The script “TRIGGERSCRIPT1” will be triggered after the user clicks on the notification or the “Show me” button. In the trigger script you can for example show the user a specific layout.

Example 3

This example is for macOS only.

Set Variable [ $ErrorCode ; Dial_ScheduleNotification ( "-ShowNotRequired" ; "note345" ; 15 ; 
           "Time is up" ; "Your report is ready!", "Show it" ; Get ( FileName ) ; "ScriptToTrigger" ) ]

By adding the switch “-ShowNotRequired”, this notification will be shown after 15 seconds, but only when FileMaker is in the background. The notification will always be added to the notification center. The script will still trigger and have as second line in the ScriptParameter the status: “NotificationNotDisplayed”.

Related functionFunction badge

Dial_RemoveNotification

Related script stepScript step badge

Schedule Notification

Related topics

Troi Dialog Plug-in online help (overview)


Online Help Page for Troi Dialog Plug-in for 14 to 17 –> Dial_ScheduleNotification (dialp4320) 2018-1114 15:08:07