This article applies to:
E-Prime Extensions for Tobii Pro 3.2
The purpose of this article is to discuss the 2 methods for controlling Placeholder images seen in the Tobii Pro Lab interface. A Placeholder image is what is seen during times that are not indicated as display events.
For example, if a Procedure has 3 objects (Fixation, Stimulus, and Feedback), and Stimulus is set to be represented in Tobii Pro Lab with the TPLSetDisplayEvent PackageCall, then both Fixation and Feedback would be represented by a Placeholder image. This is because they were specifically not called out as display events. Additionally, any intertrial intervals may be represented by Placeholder images.
2 types of Placeholder images are made: object specific Placeholders and custom Placeholders. In the example above, the Placeholders would be object specific for both Fixation and Feedback. In Tobii Pro Lab, the Placeholders are named Placeholder_Fixation and Placeholder_Feedback. By default, object specific Placeholders are repesented by a gray image indicating the name of the Placeholder (e.g., Placeholder_Fixation).
Custom Placeholders are created automatically for test sessions. They are represented by a gray image that says the word "Placeholder" on it. Unless a user manipulates the PackageCalls discussed below, custom placeholders occur during an experiments intertrial intervals.
The PackageCall TPLSetPlaceholder sets a custom Placeholder image. Setting a Placeholder image with the SetPlaceholder routine results in the specified image being included in the Tobii Pro Lab recording as the Placeholder image. Specifically, the Placeholder image is shown beneath the eye tracking data during the recording playback and a thumbnail representation of the Placeholder display is inserted into the timeline.
The PackageCall TPLCompeteLabEvents must be made on the same procedure as the call to TPLSetPlaceholder in order for the customized Placeholder image to be included in the events that are processed by CompleteLabEvents and for the specified strMediaName to be sent to Tobii Pro Lab.
TPLSetPlaceholder has 4 main parameters:
- The first parameter is c (the experiment context) and is specified as the first parameter for the majority of PackageCall routines.
- The second parameter, strMediaName, identifies the name of the Placeholder image to be created in Tobii Pro Lab.
- The third parameter, vTime, specifies the time in the experiment when the Placeholder image should be shown during recording playback in Tobii Pro Lab. For example, specifying "Feedback.OnsetTime" would show the Placeholder image during the Feedback object.
- The last parameter, vLogLevel, is useful whenever the object that should have a custom Placeholder image is not on the same logging level as the TPLSetPlaceholder PackageCall. For example, the log level of 3 can be specified if TPLSetPlaceholder is on the Block level but the object that needs to have a custom Placeholder is on the Trial level.
The SetPlaceholder routine is not pre-configured in a Tobii Pro Lab Toolbox Shortcut. Therefore, a PackageCall object needs to be added to a Procedure. Then, both the Package and Routine need to be configured in addition to the parameters.
TPLSetPlaceholder works alongside TPLDefineMedia. TPLDefineMedia is responsible for creating a representation of an E-Prime display and sending that representation to Tobii Pro Lab. See EET: Sending media files to Tobii Pro Lab prior to data collection  for more information.
TPLCompleteLabEvents parameter vObjectPlaceholderList:
TPLCompleteLabEvent contains an optional parameter (vObjectPlaceholderList) that identifies objects that will have a uniquely named object placeholder image (e.g., Placeholder_Feedback) in the Tobii Pro Lab recording. This parameter accepts a semi-colon delimited list of object names (e.g., "Fixation;Feeback"). This routine only applies to objects that do not have an associated SetDisplayEvent or SendStimulusEvent.
When this parameter is not specified, any visual object without a SetDisplayEvent or SendStimulusEvent is represented in the Tobii Pro Lab recording with a uniquely named Placeholder image. Therefore, each visual object is uniquely identified in the Tobii Pro Lab recording by default.
When this parameter is specified, only objects identified in the vObjectPlaceholderList are uniquely represented as Placeholders in the Tobii Pro Lab recording. Any visual object that is not listed in vObjectPlaceholderList and is not associated with a SetDisplayEvent or SetStimulusEvent routine is represented in the recording by the current value assigned to the SetPlaceholder call. An object name specified that has a SetDisplayEvent, SendStimulusEvent, or is not on the Procedure is ignored.
To assign the generic Placeholder image to all objects in a Procedure not represented by SetDisplayEvent or SetStimulusEvent, specify vObjectPlaceholderList as a blank string value (i.e., "").