Object quick-reference

The following define the main types of objects within Experimentor and their properties.

Experiment flow and timers

The following variables are always available:

Keyboard The current keyboard object (see below).
Screen The current screen object (see below).
TargetDuration The target duration of the session (used by some functions, such as the waitOrCancelTrial function). If this is not set it defaults to (effectively) infinity and beyond so that it will not have any impact on your session unless you explicitly set it.

If it is set, this is the “target” duration – not an absolute maximum duration. That is, the current trial will not be stopped immediately in the middle of a trial or phase when the session has been running for this long; instead the phase or trial will run its course and end normally (unless you are using a function like waitOrCancelTrial).

Trial

IsTrialCorrect This value is either true or false, and it defaults to false when the trial starts.
This value can be set within any phase.

Note that this value is very important, as it is used as one of the primary columns in the session views and is saved in the database as a column on the Trials table (making it easy to search and filter trials using this property).

Additionally, when examining the details of a session, this property indicates if the Trial is given a check mark overlay or an X overlay.

IsTrialAbandoned This value is either true or false, and it defaults to false when the trial starts.
This value can be set within any phase.

Note that this value is very important, as it is used as one of the primary columns in the session views and is saved in the database as a column on the Trials table (making it easy to search and filter trials using this property).

Phase

IsPhaseCorrect This value is either true or false, and it defaults to false. Note that this value is saved in the database as a column on the Trials table (making it easy to search and filter trials using this property).

Additionally, when examining the details of a session, this property indicates if the Phase is given a check mark overlay or an X overlay.

Timer

Milliseconds The current duration recorded by the timer in milliseconds.

Animation

Completed The number of times the animation has completed; this variable is only incremented if the animation finishes (that is, it is not incremented when using the “stop” keyword).

Shapes

All shapes share a common set of properties:

IsVisible Either true or false, this property controls if the shape is visible on the screen or is hidden. The default is false, allowing you to more easily create shapes and only show them in the phase where you want them.
Colour The colour of the shape.
LineColour The colour of the line that surrounds the shape.
LineThickness A number that defines the thickness of the line around the shape.

The default value is 0.

X A number (or a percent) that defines the x/horizontal position of the centre of the shape on the screen. If this is a percent then it is a percentage of the width of the screen.
Y A number (or a percent) that defines the y/vertical position of the centre of the shape on the screen. If this is a percent then it is a percentage of the height of the screen.
Z A number that defines the “depth” of the shape relative to other shapes. A shape with a higher z value will be placed above shapes with lower z values if they overlap.
XAbsolute The absolute horizontal position of this shape relative to the primary screen. If X is not a percent this property will be the same as the X property. However, when the X property is a percent, this property is the X percent value translated into concrete/absolute co-ordinates relative to the primary screen.

This property is read-only.

YAbsolute The absolute vertical position of this shape relative to the primary screen. If Y is not a percent this property will be the same as the Y property. However, when the Y property is a percent, this property is the Y percent value translated into concrete/absolute co-ordinates relative to the primary screen.

This property is read-only.

ClickCount The number of times this shape instance has been clicked; this property is writeable, so you can set it to whatever number you like, and the next click will simply increment this variable from there.
WithPersistence Either true or false; this property controls if events from this shape are saved into the database. The default value is true.
EventSourceName The value of this variable is saved in the EventSource column of the Events table. Thus, setting this value can help you easily identify all the events on a particular share instance.

Note that for convenience, this property is automatically set to the variable name where you are storing the shape when you create your shape instance.

The individual shapes have the following properties:

Circle

All of the properties from shapes (defined above) plus:

Radius A number or a percent that defines the radius of the circle. If this is a percent then it is a percent of the height of the screen.

Rectangle

All of the properties from shapes (defined above) plus:

Width A number or a percent that defines the width of the rectangle. If this is a percent then it is a percent of the width of the screen.
Height A number or a percent that defines the height of the rectangle. If this is a percent then it is a percent of the height of the screen.

Text

All of the properties from shapes (defined above) plus:

Value The actual string of text to display on the screen.
Font The name of the font on your system to use; the default value is “Times New Roman”.
FontSize A number that represents the size of font. The default value is 12.
FontWeight One of the following strings:

  • Light
  • Thin
  • Normal
  • Medium
  • SemiBold
  • Bold
  • ExtraBold

The default is “Normal”.

Image

All of the properties from shapes (defined above) plus:

Source The full path (on your hard drive) to the actual image.
Width A number or a percent that defines the width of the image. If this is a percent then it is a percent of the width of the screen.
Height A number or a percent that defines the height of the image. If this is a percent then it is a percent of the height of the screen.

User interaction objects

Screen

The screen controls the entire screen background and has the following properties:

Width READ ONLY – the width of the screen inside the margins
Height READ ONLY – the height of the screen inside the margins
TotalWidth READ ONLY – the total width of the screen
TotalHeight READ ONLY – the total height of the screen
Colour The colour of the screen
MouseCursor A string value – “None” is the default but the following values are supported:

  • None – A value indicating that no cursor should be displayed.
  • Arrow – A standard arrow cursor.
  • AppStarting – A standard arrow with small hourglass cursor.
  • Cross – A cross-hair cursor.
  • Help – A help cursor.
  • IBeam – A text I-Beam cursor.
  • SizeAll – A cursor with arrows pointing north, south, east, and west.
  • SizeNESW – A cursor with arrows pointing north-east and south-west.
  • SizeNS – A cursor with arrows pointing north and south.
  • SizeNWSE – A cursor with arrows pointing north-west and south-east.
  • SizeWE – A cursor with arrows pointing west and east.
  • UpArrow – A vertical arrow cursor.
  • Wait – An hourglass cursor.
  • Hand – A hand cursor.
  • Pen – A pen cursor.
  • ScrollNS – A scroll cursor with arrows pointing north and south.
  • ScrollWE – A scroll cursor with arrows pointing west and east.
  • ScrollAll – A scroll cursor with arrows pointing every direction.
  • ScrollN – A scroll cursor with an arrow pointing north.
  • ScrollS – A scrolling cursor with an arrow pointing south.
  • ScrollW – A scrolling cursor with an arrow pointing west.
  • ScrollE – A scrolling cursor with an arrow pointing east.
  • ScrollNW – A scrolling cursor with arrows pointing north and west.
  • ScrollNE – A scrolling cursor with arrows pointing north and east.
  • ScrollSW – A scrolling cursor with arrows pointing south and west.
  • ScrollSE – A scrolling cursor with arrows pointing south and east.
  • ArrowCD – An arrow cd cursor.
ClickCount The number of times the screen has been clicked; this property is writeable, so you can set it to whatever number you like, and the next click will simply increment this variable from there.
MarginTop The margin at the top of the screen; either a percent or an absolute value.
MarginBottom The margin at the bottom of the screen; either a percent or an absolute value.
MarginLeft The margin at the left of the screen; either a percent or an absolute value.
MarginRight The margin at the right of the screen; either a percent or an absolute value.


Keyboard

KeyPressed The last key that was pressed, or
the empty string (“”) if no key has been pressed yet.
KeyReleased The last key that was released,
or the empty string (“”) if no key has been pressed yet.

Sound

Source The full file path (or a URL) of the sound file.
Speed The speed at which the sound will be played; 0 is stopped, 1 is normal speed, and 2 is double speed
Length The length (in milliseconds) of the sound if it was played at normal speed. This property will be incorrectly zero until the sound file has finished loading into memory.
Completed A count of how many times the sound has either finished playing to the end, or was stopped (using the stop keyword described below).