Actions - Overview
Overview
An Action is a control function in Polybench that can change the appearance of your application, or that can change the behavior of your measurement configuration. Examples of Actions are: switching between pages, starting data acquisition, changing parameters of mathematical operators, calling functions, etc.This section of the Polybench documentation describes which actions are available and what they do.
Details
You may look at an action as something that you would normally do by clicking with your mouse, but that you would like to automate. Some actions can be performed from the menus of Polybench Designer. But actions will usually be performed from within an application that was designed in Polybench.For example, a project consists of multiple pages, and in Polybench you can switch from one page to another by clicking on the Page Bar ("Page Bar"). However, you could also switch to another page by using an Action like this: You could add an Action Button ("Action Button") to one of your pages and let it perform the SHOWPAGE Action. By pressing the button, the project would switch to another page. The users of your application can now navigate through pages, by clicking this button (see the SHOWPAGE Action ("SHOWPAGE") for more details).
It is even possible to perform some Action as a result of calculation of signal data. By using an Action Trigger operator ("Action Trigger") in your measurement configuration, you can make your signals control your project.
Examples
The following figure shows a configuration with a Constant Button ("Constant Button") and two Action Trigger operators ("Action Trigger"). The Action Trigger operator executes an action if at its input a signal changes from the value 0 to the value 1 (called a trigger). If the Constant Button is pressed, its output changes from 0 to 1, thus inducing a trigger for the upper Action Trigger. Because the lower Action Trigger operator gets the value from an Inverter operator (1 - S, "1 - S"), it will not trigger since its input changes from 1 to 0.Now, the Constant Button is set as Toggle button. If a user presses the button again, its output changes from 1 to 0 again, thus inducing a trigger on the lower Action Trigger.
Both Action Triggers are set to use the SET_PARAMETER action, with the address of the Input Field written in the Address property and a text written in the Value property.
Action sequences
Polybench offers the possibility to execute a series of actions at once. This is called an action sequence. An action sequence uses special operators and can be started using the action ACTIONSEQUENCE ("ACTIONSEQUENCE"). An important property of action sequences is that the actions are executed in the order they appear in the sequence.The next figure shows an example of two action sequences. An action that would call the second action sequence would have the following settings:
Action = ACTIONSEQUENCE
Value = (empty)
Address = $Design.Init Sequence
Properties of an Action
An action is something that is initiated by one object, and that has an effect on one or more other objects, or on the complete application. There are two kinds of actions: actions to execute some kind of function, and actions to change or read a value of another object.An object that needs to initiate an action, should offer three properties to specify the action: Action, Address and Value:
Action
In the properties of an object that uses actions, one property item is called Action. A list of pre-defined actions is available. These actions are documented further on in this section of the manual. The choice of an action determines how Address and Value are to be used.Three actions are used most often, they are highlighted here. The first is SET_PARAMETER ("SET_PARAMETER"). This action makes it possible to change a Variable Parameter of another object. Read more about Variable Parameters here: "Variable Parameters". The second is FUNCTION ("FUNCTION"). This action is used if a special function of an object in your application should be called. Refer to the documentation of operators and other objects to find out which functions they offer. For general information read more about functions here: "Operator Functions". The third is the ACTIONSEQUENCE ("ACTIONSEQUENCE"). This is a call to a sequence of actions, so that you can perform multiple actions in one call. There is only one operator that listens to an ACTIONSEQUENCE call, which is the Action operator ("Action").
Address
Some Actions can be directed to one or more specific operators in your project. If the Action allows for this, you should specify the exact items that are affected by the action by writing an address in the Address field as follows:$[component locator].[parameter name in the component]
where [component locator] is the component name (this is commonly called Caption), with optionally specified the page on which the component resides, separated with a dot:
[component locator] = page name.component caption
You do not have to specify the page in the address! If you omit the page name, then all objects with the same name on any page will be addressed. If you address a specific Variable Parameter, then you always have to specify the object caption before it. For example:
$Design Page.Constant1.Value is correct.
$Constant1.Value is also correct.
$Value is also correct, but does not refer to the Value parameter of a constant! In this case, $Value is a user defined global variable ("Free Global and Namespace Variables").
On most places where you can enter an address, the Address Searcher dialog ("Address Constructor") is offered as a tool, so that it is easy to construct an address.
Alternatively you may copy the address of a Function or a Variable Parameter from the Functions dialog ("Functions Viewer") or the Variable Parameters dialog ("Variable Parameter Viewer") of the object that you want to refer to.
See also "Address - how to address objects and variable parameters".
Value
The Value property is an optional value of a specified type that is send along with the Action. Refer to the documentation of the goal object of the action, to understand exactly what can be filled out for Value.Note that the Properties Dialog ("Properties Viewer") in many cases helps you fill out the Value property. Press the arrow-button right of the Value field to open a list of options and hints.
The Value may also contain addresses of variables. The variable is parsed before the value is used in the action. For example, if the value is $Design Page.Constant1.Value$, and the constant that this addresses contains the value 7, then the action is performed using the Value '7'. If you require the Value to be an address, then you can prevent the parsing of the address by writing a double-dollar, for example $$Design Page.Constant1.Value$$. Take care using squared brackets [$address$], because these have a special meaning.
For example:
Define an Action Button ("Action Button") to set the time preparation component on the Design page for a Y-T viewer to 20 seconds:Action = SET_PARAMETER
Value = 0:0:20
Address = $Design.Prepare Time Range.TimeRange
The page name is not required; it just better specifies which operator was meant. So the following would also work, but would also change other Prepare Time Range operators with the same Caption:
Action = SET_PARAMETER
Value = 0:0:20
Address = $Prepare Time Range.TimeRange
Property helpers
The properties dialog often helps you by stating what can be specified. For Action and Value, on the right side of the properties table, an arrow button appears if you select the property. Clicking the arrow will show a list of information. For Address, a small button appears on the right side. Click that to open the Address Searcher dialog.The Actions are displayed in one long list. The number of actions is limited. Actions that are used most often are listed first: SET_PARAMETER and FUNCTION. Every action has very specific functionality and behavior; please refer to the documentation of each action.
Notes on action logging and action listeners
In Polybench Designer a log of actions can be viewed (see Debug menu). In that log, all actions that have been executed are listed in the order they were executed, so you can check and debug your action control.Please note that the action ACTIONSEQUENCE itself is never written to the log, because it is not really an action. Instead, all the actions that were executed in an action sequence are written to the log.
Polybench offers a few components that listen to actions, like the Action to One Shot ("Action To One Shot"). Also, these components do not react on the action ACTIONSEQUENCE; only on the actions in the sequence.
Timing of actions
Actions are divided in synchronized and non-synchronized actions. Synchronized actions are executed in line with signal data processing, whereas non-synchronized actions are executed in parallel. Why is this? Well, some actions influence data processing, while others do application control where timing is not so much an issue. Synchronized actions have a higher priority to execute them quickly.For example: SET_PARAMETER is synchronized, because it sets a value in another component that could be part of signal processing. Moreover, it is a light and quick operation for the software to execute. SHOWPAGE is not synchronized, because it switches the visible page, which has nothing to do with signal processing. This is a heavy operation for the software, because all kinds of components need to be redrawn on screen. Continuous signal processing is more important in Polybench then drawing the user interface, and therefore SHOWPAGE should not interfere with signal processing and is executed at its own pace.
But beware: actions are always late, also if they are synchronized. If you trigger an action on sample time T, then a synchronized action does not necessarily have to be executed on sample T + 1. The action is then executed after processing the last block of samples is ready. But how large a block of samples is, is difficult to predict. A non-synchronized action (like SHOWPAGE or START_EXTERN) is executed when the software is ready executing the last synchronized actions (if those were started before that action), and then only if the computer has enough time. You cannot predict when the software is ready executing a non-synchronized action.
To make this a little more understandable, please remember the next two rules:
1. Synchronized actions have a priority over non-synchronized actions
2. In an action sequence all actions are executed exactly in the order they appear in the sequence. Synchronized or not synchronized is not an issue here.
In this example three Action Triggers are triggered in parallel, so you cannot tell the order of execution. In reality they are triggered one after the other, but you cannot predict which one is triggered first, second or last. Both SET_PARAMETER actions are executed in line with signal data processing. The SHOWPAGE action may come at any time. If you view these actions in a log, you will see that SHOWPAGE sometimes comes before one of the SET_PARAMETERS and sometimes after it.
In this example the same three Action Triggers are triggered. This time they are triggered one after another, because the second and third one are executed after 1 and 2 samples delay. As a result, you can be certain that SET_PARAMETER 1 is executed before SET_PARAMETER 2. However, SHOWPAGE can still be executed at any time. It may even come before SET_PARAMETER 1, but also in between or after SET_PARAMETER 2.
In this example the same three actions are executed from Action operators in an action sequence. The Action Trigger operator starts the action sequence. In this case, the order of execution is predictable: first comes SET_PARAMETER 1, then SHOWPAGE, and then SET_PARAMETER 2. Always.