Page History: Proxy Variables
Compare Page Revisions
Page Revision: 2012/05/09 18:58
Proxy variables are short-cut labels that can be created for selected properties of events and elements. Once a proxy variable is created it becomes accessible as a global variable in all code snippets. This allows to read and modify a status of any EventIDE object at runtime. There is also another class of proxy variables that are defined by user in the Header snippet. Both types of proxy variables are only type of variables that can be used for XAML data binding on the status screen in order to create a dynamic content.
Description
At the design-time any
property of EventIDE
events and
elements can be modified in the
property panel, for example, the black can be chosen as the background color of the currently selected event. The property value, shown in the property panel, is used at the start of an experiment. However, in many scenarios it is also necessary to read and to change object properties at runtime, in user code. For example, you may want to show either green or red text depending on correctness of participant's response. Since an experiment can contain many events and elements a virtual path to modify the Font Color property of the particular Text element may look like this:
[Main_Experiment_Event].[Feedback_Event].[Message_Text_Element].[Font_Color]=new stColor(255,0,0);
Such path is too verbose, difficult to read and and even exhausting to type. EventIDE offers a mechanism of the proxy variables to solve this problem - short-cut labels can be created always for a selected properties of events and elements. In code snippets the proxy variables can be automatically accessed as global variable, whose type matches to the type of underlying property. Then the above code string becomes shorter:
FeedbackMessageColor=new stColor(255,0,0);
or even shorter if you prefer a 'spartan' coding style:
fmc=new stColor(255,0,0);
Note that
stColor is a
built-in type in EventIDE for color representation.
All proxy variables have to be created manually at design-time, however, it does not take much time because in a typical experiment only a limited number of proxy variables is required. EventIDE provides some browsing and editing capacities for proxy variables in the
Proxy Panel.
Proxy variables are allowed not for all properties. For example, the proxies can not be created for all properties that have the 'Design-time Only' usage attribute, like the event title. Also, the proxy variables normally cannot be to created for hardware settings properties, because their modifications at runtime can cause undesirable effects.
The other facts about the proxy variables are:
- Only one proxy variable can be created per each property of a particular object.
- Proxy variable always has the same type as its underlying property.
- Proxy variables are automatically removed from an object when its is cut and pasted
- Proxy variables can be grouped into different categories for better browsing. The categories don't affect application of a proxy variable
Classes of Proxy variables
EventIDE allows four different classes of proxy variables.
Single Proxy variable
This type of proxy variables is the most common - a proxy gets linked to a selected property of single EventIDE object.
Proxy array variable
This type of proxy variables is an indexed array that contains several proxy variables, linked to the same property on different objects. The linked objects must be of the same type. The proxy array variable is convenient for enumeration operations in code snippets, e.g. changing the screen positions of multiple targets:
for (int i=0;i<TargetPosition.Length;i++) /// where TargetPosition is an array proxy variable
{
TargetPosition[i].X=i*10;
TargetPosition[i].Y=368;
}
Proxy hub variable
This type of proxy variables allows to modify a property of multiple linked objects at the same time, with a single proxy variable, called hub. The linked objects must be of the same type. The hum proxy variable is convenient when made changes have to be applied to multiple objects, e.g. switching visibility of a group of visual stimuli:
TargetsAreVisible=false; /// TargetsAreVisible is a proxy hub variable linked to multiple objects that change visibility together
Once the proxy hub variable is created, all underling objects reset the linked properties to the same value automatically and keep them synchronized further, both in run-time and design-time. The hub proxies can not be created for the status (read-only) properties because such properties can not share the same value across different objects.
User proxy variable
Users also can create their own proxy variables that are not linked to EventIDE objects. Any global variable, defined in the Header snippet can be turned to the user proxy variable by adding the 'public' keyword:
// Header code
int A=0; /// this is a usual global variable accessible in all snippets but not in UI.
public int B=0; /// this is a user proxy variable accessible in all snippets but also in the Proxy Panel. The initial zero value can be overwritten in the Proxy Panel.
There are two main purposes for creating the user proxy variables
1) The user proxy variable supports change notifications and, therefore, provides self-updating on the Status Screen, when they used in data binding:
<Textblock Text="{Binding B}"/>
This allow allows to monitor the property value in real-time, while an experiment is run. The technique is extremely useful for debugging of snippet code- any variable can be turned into the custom proxy and be monitored on the status screen.
2) the user proxy variables are automatically added into the
Proxy Panel, where they can be modified before the start of experiment. The modified values overwrite the initial values defined in the Header snippet code. That can be used to create a run-specific parameter, like participant's name, which can be then set in GUI, before running an experiment.
In the same time, an read-write access to a user proxy variable is slightly slower in code snippets than an access to a normal variable, due to addition of the change notification mechanism. Therefore, creating a large number of the user proxy variables is not recommended.
Practical Use
Creating a proxy variable
To create a single proxy variable, select the object property in the
Property Panel by clicking on its name. If property can be linked to a proxy variable, the add button will next to the name:
 Creating a proxy variable on the selected property |
Alternatively, a proxy variable can be created a command in the main menu.
When multiple objects of the same type are selected in the Property Panel, the add proxy button will present two options: create a proxy array or create a proxy hub variable.
Once a proxy is created it's shown in the property panel as a label attached to the underlying property.
Removing a proxy variable
Existing proxy variable can be removed by selecting the underling property in the property panel and pressing the remove button:
 Removing the proxy variable via the property panel |
Alternatively, a proxy variable can be removed via the proxy panel:
 Removing the proxy variable via the proxy panel |
Browsing and editing a proxy variable ¶
The proxy panel allows managing the existing proxy variables. For example, the selected proxy variable can be renamed by selecting it and calling the context menu by the right mouse click. Renaming includes an option to change a category of the proxy variables
For example, a list of objects linked to a proxy array variable can be browsed and edited. To expand the list, click on the iconic button on the right to the proxy name:
 Editing a list of linked objects in the proxy panel |
The objects in the list can be removed and reordered. New objects can be added to the list by a drag and drop (then they become linked to the proxy). When the last object is deleted from the list, the proxy variable is automatically removed as well.
Default proxy variables
When a new experiment is created, EventIDE adds two default proxy variables- Report and SnapShot. The former variable provides an access to
Report in EventIDE whereas the latter returns a snapshot of the current experiment screen at runtime. These proxy variables can not be removed.