Proxy Variables

Modified on 2016/06/19 10:46 by Administrator — Categorized as: Main concepts, Special Concepts

Proxy variables is a core mechanism in EventIDE, that provides an interface between user code and EventIDE objects (and their functions). The proxy variables are reference labels that can be created for selected properties of the EventIDE design objects: experiment,events and elements. Once a proxy variable is created, it becomes accessible as a global variable in all code snippets. The proxy variables allow to control any EventIDE object at runtime and read its state in code. Also, the proxy variables can be monitored on the status screen and in the debug window at runtime.


Why do you need the proxy variables?

Imagine that at some moment of an experiment you need to assign a new color for one of the text blocks shown in your experiment. You may program it, but since there are can be many text blocks, a particular one has to be addressed explicitly in the verbose object-based notation: 
[Main_Experiment_Event].[Feedback_Event].[Message_Text_Element].[Font_Color]=new stColor(255,0,0);
To avoid such long names, in EventIDE you can create a short-named proxy variable for the ‘Font Color’ property of the selected Text Element. Then, the same line of code from above turns in a simpler expression: 
FontColor12="Red";
or even shorter if you prefer the 'spartan' variable naming: 
fc="Red";
Thus, the proxy variables provide a simplified way to manipulate the EventIDE objects in the runtime code. All proxy variables have generic data types (the same as the underlying property) and behave as conventional global variables in the code.

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 class. 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, via a single proxy variable, called proxy 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 now 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 automatically becomes a proxy variable (after the header is compiled). 

// Header code
int A=0; /// this is a global variable accessible in all snippets AND in the Proxy Panel. The initial zero value can be overwritten in the Proxy Panel before running the experiment.

There are two main goals in converting the user-defined global variables to the proxy variables: 1) The proxy variable support change notifications and, therefore, automatically kept updated on the Status Screen, when they used in XAML data binding 

<Textblock Text="{Binding B}"/>
and in the debug window.

2) the user-defined proxy variables are automatically added into the Proxy Panel, where they can be modified just before the start of experiment. The modified values overwrite the initial values defined in the code. That can be used to create a run-specific parameter, like participant's name, which can be then set in GUI rather than be changed in the code.

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

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

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

Removing the proxy variable via the proxy panel


Managing the existing proxy variables

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

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.

Using the proxy variables in the snippets

All proxy variables can be accessed and modified in any code snippet, similar to global variables, however, there is an important bound for the property-based proxy variables (ones that are linked to events and elements). Inside snippets, such proxy variables are presented by virtual copies. Thus, if a proxy variable is changed in a snippet, the actual modification of the linked property occurs only after execution of the snippet is completed. For example, if you have the following snippet code:


/// ImagePosition is a proxy linked to the position property of the Renderer element
ImagePosition.X=100;
ImagePosition.X=ImagePosition.X+100; // makes 200

the actual position of the image will be set to 200 at once, skipping the intermediate position at 100. Remember that when the property-based proxy variable is used inside of a snippet, only the last assigned value matters.

Default proxy variables

When a new experiment is created, the program automatically adds two default proxy variables- Report and ScreenClone, attached to the corresponding properties of the Experiment object. The former variable provides an access to data collection mechanism in EventIDE, whereas the latter returns a clone of the presentation screen, which can be shown on the Status Screen at runtime. These proxy variables can not be removed.

Other facts about the proxy variables