INCO item triggers documentation

INCO item triggers provide a kind of INIX notification mechanism. Only some of all the available INCO items in an INIX application support them. The list of available trigger items can be found here: List of all items that provides triggers. Triggers are executed when an INCO item value changes. What happens when a trigger is executed is defined in the trigger command, see Trigger syntax.

A simple trigger example

Let's start with an easy example: Assume you have the following IGD structure:

x:\MyINIXApplication
  |
  ---> Main                          (= Toplevel frame plugin instance)
     |
     ---> Label                      (= Label plugin instance showing a text)
        |
        ---> Prop.Text               (= The displayed text)
        |
        ---> Events.OnPluginCreated  (= Executed after plugin creation)

Now you want to get informed whenever the value of Prop.Target changes and display that new target name as text of your label plugin instance (Main.Label.Prop.Text). In order to achieve this, you have to "add" a trigger to the Prop.Target variable that puts (by PutVariable) any new value to the labels text Main.Label.Prop.Text. One possiblity to add such a trigger is to use the Main.Label.Events.OnPluginCreated event. Thus, set the following value for the mentioned event:

Prop.Target!Triggers = "Add;!=;Main.Label.Prop.Text=\"Target name has changed\""

Save the changes (by changing to the edit mode and back to running with Main.Label.Cmd.SetState) and restart the INIX application. Then, every time the Prop.Target value changes, the labels text will be set to "Target name has changed" (without the quotes).

To visualize the target name instead of the 'static' text above, we must change the trigger to something like this:

Prop.Target!Triggers = "Add;!=;Main.Label.Prop.Text=\"Target name has changed to: \" ##{{NEW_VALUE}}"

Have a look at Constants provided by INCO item triggers below to understand the ##{{NEW_VALUE}} part of the trigger command text. Important: In this sample, we add the trigger by the help of the OnPlguinCreated event. Events do execute their Commands by the help of the incoservice (sinco plugin). The sinco service does resolve all known constants and redirections within a command before processing it, as long as the keys '#', '$' and '%' are not doubled. In this case we don't want to have the #{NEW_VALUE} constant resolved when the trigger is added. Instead, the constant should be replaced with the 'new value' later wenn the trigger will be executed. Thats the reason why we prepended a second '#' to it. Finally, what the Prop.Target trigger really receives is the following:

Add;!=;Main.Label.Prop.Text="Target name has changed to: " #{{NEW_VALUE}}

Becasue the incoservice has removed one of the '#'.

Constants provided by INCO item triggers

Triggers provide the following constants:

More about constants is written here: Constants.

Technical background

This section explains the technical details of triggers.

Trigger syntax

A trigger can be added to or removed from an INCO item. Doing this is always done by a PutVariable access to the !Triggers propery of that certain INCO item. The value you have to put to this property has the following syntax definition: 

<trigger command> = <trigger modifier>;<trigger event>;<command>

where: 

<trigger modifier> = "Add"
                   | "Remove"

<trigger event> = "!="  // the <command> will be executed if the value has changed
                 | "="  // the <command> will be executed if a PutVariable happens

See Commands for the definition of <command>.

The list of all registered triggers of a specific INCO item can be get by a GetVariable to the !Triggers property.

Trigger execution

Everytime a PutVariable happens to a certain INCO item that provides triggers support, it goes throught the list of all registered triggers. For every trigger that matches the <trigger event> (where "=" matches on every PutVariable), the specified <command> will be passed to the incoservice (sinco). The incoservice, does then resolve all the redirections, constants and so on and finally executes the <command>.

Trickier trigger examples

Now let's examine some trickier trigger samples.

Tricky sample 1

Say we have an IGD file structure like this: 

x:\MyINIXApplication
  |
  ---> _Dialogs_
  |     |
  |     ---> OkDialog                (= Contains a whole IGD structure)
  |
  ---> Main                          (= Toplevel frame plugin instance)
     |
     ---> Label                      (= Label plugin instance showing a text)
        |
        ---> Events.OnPluginCreated  (= Executed after plugin creation)

If Prop.Target changes, we want to create an instance of the OkDialog IGD structure. In fact we are doing nothing more than showing a kind of messagebox (although there are better ways for doing such things, see Dialog Service Plugin User Documentation).

To shorten things, here's the final command that we may put to Main.Label.Events.OnPluginCreated:

Prop.Target!Triggers = "Add;!=;#{PARENT_PATH}.Cmd.CreateSubPlugin
($${{Prop.AppBaseDir}} \"_Dialogs_\\\\OkDialog\",\"Dialog\", 0:l)"

${{Prop.AppBaseDir}} has an additional '$' prepended to it. This is needed, because this redirection should be resolved when the trigger command is executed. This is necessary because the resulting string must then be concatenated with the "_Dialogs_..." string. If we wouldn't have doubled the '$', then the directory name would have been resolved by the incoservice when adding the trigger and this would have resulted in this:

Prop.Target!Triggers = "Add;!=;#{PARENT_PATH}.Cmd.CreateSubPlugin(
"x:\MyINIXApplication" \"_Dialogs_\\\\OkDialog\",\"Dialog\", 0:l)"

The problem here is that the string parser does now stop parsing after the second occurence of " just before the x:. If we really want to resolve the redirection when adding the trigger, we would have to write this:

Prop.Target!Triggers = "Add;!=;#{PARENT_PATH}.Cmd.CreateSubPlugin("
${{{Prop.AppBaseDir}}} " \"_Dialogs_\\\\OkDialog\",\"Dialog\", 0:l)"

This solution and the one presented first (with the doubled '$') are both perfectly correct.

Finally, when the trigger command will be executed and all the constants and redirections are resolved, the following CallProcedure will be executed by the incoservice:

TheParentPluginName.Cmd.CreateSubPlugin(
"x:\\MyINIXApplication\\_Dialogs_\\OkDialog","Dialog", 0:l)

Tricky sample 2

The second tricky sample looks like this:

Prop.Target!Triggers = "Add;!=;#{PARENT_PATH}.ChangeLabel.Prop.Text = \"Value of
Prop.Target has changed from: \" ##{{OLD_VALUE}} \" to \" ##{{NEW_VALUE}}"

Here again, its important to write two '#' in front of the OLD_VALUE and NEW_VALUE constants, because we want them to be resolved at the time when the trigger command is executed and not at the time when we are adding the trigger command to the Prop.Target variable.

List of all items that provides triggers

Here's a complete list of all trigger INCO items that support triggers.

All plugins and INIX.exe

All graphical plugins

Cmd.CreateVariable and triggers

By default, as described above, none of the inco items provide trigger support. Thus, the items created at runtime by the help of Cmd.CreateVariable do also not have triggers. Though, by the flag argument, it is possible to create runtime variable supporting triggers. This is done by passing 1:l instead of the default value 0:l (see also INCO tree combobox).

Generated by doxygen 1.8.8