E-STUDIO: Button Device [24411]

Overview

The Button device (ButtonDevice) allows input on a Slide or FeedbackDisplay object via the SlideButton sub-object. The Button device is available by default when a new experiment file is created, but may be enabled/disabled or added/removed via the Devices tab in the Experiment Object properties. Double click the Experiment Object in the Structure view to display the Experiment Object Properties, and select the Devices tab to display the available devices. See E-STUDIO: Experiment Object [22698] for information pertaining to Adding/Removing Devices in an experiment. When the Button device is available in the Devices list, a SlideButton may then be added to individual objects (i.e., TextDisplay, Slide, etc.) to enable input.

Button device properties set at the experiment level apply to all buttons used on all objects accepting input via buttons. To edit the Button device properties, select the Button device in the Devices list and select Edit… to display the ButtonDevice Properties pages.

Field	Possible Values	Description
Name	Stringvalues	Defines the string by which the device is identified.
Input Device to Filter	(none), Devices as named in the Experiment Object (e.g., Keyboard, Mouse, Joystick, Celeritas)	Defines the device through which the button receives information. Available devices are limited to those listed on the Devices tab in the Experiment Object, and which support input filtering.
Response Types	Down, Click, Double Click, Hover, Long Press, Fixation, Check	Defines the types of responses that will be recognized by the device (See Logging of Response Types section below for information pertaining to how the response types appear in the data file).
Flags	Secondary, Inactive, Disabled	Specifies whether or not responses will be processed for Secondary, Inactive, or Disabled buttons (See below for more information concerning Flag settings).
Visual Options for Circumstance	Show Hover, Show Down, Show Fixated	Specifies whether or not the device will visually indicate specific states. This functionality offers flexibility in design.
Double Click Time	Integer values (0 – 120000)	The maximum time interval, in milliseconds, allowable between clicks for a double-click response to be generated (default = 500).
Long Press Time	Integer values (0 – 120000)	The time period, in milliseconds, after which ButtonDevice generates a long press response for a button if that button was the active button for the entire period (default = 1000).
Fixation Time	Integer values (0 – 120000)	The time period, in milliseconds, after which ButtonDevice generates a fixation response for a button if that button was the hover button for the entire period (default = 3000).
Display Device to Restrict Buttons	(none), Display Devices available in the Experiment Object	Specifies whether to restrict button input to a specific Display Device. This functionality is primarily applicable to efficiency in experiment design.
Use Start Time	No, Yes	Indicates whether the generated responses will use StartTime for assignment of the RTTime value. A positive setting (Yes) indicates use of StartTime (timestamp of input that initiated the response). A negative setting (No) indicates use of EndTime (timestamp of input that completed the response) for the RTTime value (default = No).
Emulate Device	(none), Keyboard, Mouse, Chronos, SRBox, Joystick, Parallel Port, Port	Defines the device through which the Button device receives information. Available devices are limited to those listed on the Devices tab in the Experiment Object, and which support emulation.
RT Adjustment	Integer values (-2,147,483,648 to 2,147,483,648)	Value by which to adjust the RT value (in msec).

Flag Settings

Primary and Secondary Keys

Primary and secondary keys are used to differentiate between how response input is reported, and the origin of the response. Primary keys will identify the button through which the response occurred (i.e., Name or Response as configured on the General tab of the SlideButton sub-object), while secondary keys identify the specific key through which the response was entered (e.g., left or right mouse button). For example, if input is received via a SlideButton named “Button1,” a response received via that button will be logged (i.e., Stimulus.RESP value) as “Button1” unless a separate Response value is specified. The secondary key for the same response identifies the key from which the response was detected (e.g., left mouse button). For a left mouse button click, Stimulus.RESP would receive a value of “Button1@1” (i.e., the left mouse button maps to key “1”).

Primary keys are enabled by default, and take precedence over secondary keys, but may be disabled through script if secondary response logging is desired. Secondary keys do NOT appear in the data file (i.e., are not logged) unless primary keys are disabled. In most cases, the Secondary flag in the ButtonDevice Properties should remain checked. Uncheck the Secondary flag checkbox if you are manipulating primary keys in script and want to disable ALL secondary responses.

Device	Primary Keys
Mouse	1-8
Joystick	1-8
Keyboard	ENTER=1, SPACE=2

Inactive

A pressed button is designated as “active” until that button is released, and any button that is not the currently active button is considered “inactive.” While a button is inactive, it may still receive response input (e.g., press Button1, hold and drag to Button2, right click Button2). Unchecking the Inactive Flag option disallows the generation of any response on an inactive button if there is a currently active button.

Disabled

The Disabled Flag allows or disallows the generation of responses for buttons that are in the Disabled state. By default, this Flag is unchecked, but may be checked in order, for example, to monitor attempts to press disabled buttons.

Response Types

Element	Description	Appearance in Data File
Down	Generated as a press when the button device receives key press input, and generated as a release when the button receives key release input	{Name.Down} or {Response.Down}
Click (default type)	Generated as a press (only) when the active key is released and the target button is the active button.	{Name} or {Response}
DblClick	Generated for the target button as a press (only) when key press input is received, provided that input is received within a configurable time interval of a click being generated for the same target button with the same key and no other press or release input was received in the interval.	{Name.DblClick} or {Response.DblClick}
Longpress	Generated for the hover button as a press (only) when a configurable time interval has elapsed from a key press input provided that, for the interval, the button has always been the hover button and no release inputs were received.	{Name.Longpress} or {Response.Longpress}
Hover	Optional list of flag values. If post-fixed with a question mark, the pattern will match responses WITH or WITHOUT the flag value. If no question mark is present, the pattern will only match responses WITH the flag value.	{Name.Hover} or Hover {Response.Hover}
Fixation	Optional flag indicating that all types and flags will be accepted as optional.	{Name.Fixation} or {Response.Fixation}
Check	Optional, comma (,) separated list of keys. If omitted, any key will match.	{Name.Check} or {Response.Check}

Input

The Input Device to Filter property in the Button Device settings indicates the input device through which the button will receive information. This property may be set to any input device available within the experiment (i.e., as specified in the Experiment Object Properties).

If the Input Device to Filter property is specified as Keyboard, then different keyboard responses can manipulate each Slide Button Sub-Object. The action of the keys is documented in the table below:

Sub-Object	Action	Key(s)
Button	Move to next button	Tab
Button	Press button	Enter
SlideSlider	Move indicator right	Right arrow, up arrow, page up
SlideSlider	Move indicator left	Left arrow, down arrow, page down
SlideChoice	Go to next item	Tab
	Go to previous item	Shift + Tab
	Select item	Enter

When one or more Buttons are added to a Slide or FeedbackDisplay object, input may be enabled via the Duration/Input tab, as it would for any input device. Note, however, that SlideButton sub-objects remain active only until either the offset time of the parent object (i.e., Slide or FeedbackDisplay) has been reached, or until the parent object no longer has pending input masks.

Response Patterns

Button Device objects collect both press and release events, and use a sequence of response matching patterns for determining allowable responses. Response patterns are composed of combinations of the elements in the table below.

Element	Possible Values	Description
{ }		Braces are required if the response pattern is longer than a single character
- (dash) or ~ (tilde)		A dash indicates the pattern matches only releases. A tilde indicates the pattern matches both presses and releases. If neither is present, the pattern matches only presses.
NAME	String values indicating existing Button names	List of Button names separated by the pipe (\|) character. At least one NAME must be specified. If specifying more than one response TYPE, each type must be within its own set of braces (see Examples below).
.TYPE	Down, Click, DblClick, Longpress, Hover, Fixation, or Check	Indicates the type(s) of response to match. If no types are specified, the pattern matches the response type listed as the default type (i.e., Click).
.FLAG[?]	Secondary, Inactive, Disabled	Optional list of flag values. If post-fixed with a question mark, the pattern will match responses WITH or WITHOUT the flag value. If no question mark is present, the pattern will only match responses WITH the flag value.
.*		Optional flag indicating that all types and flags will be accepted as optional.
@KEY	Integers in the range of 0-31	Optional, comma (,) separated list of keys. If omitted, any key will match.

In addition to the elements in the table, {ANY} and {-ANY} may be used as allowable responses to indicate that the input mask should accept any press or any release respectively. However, due to the number of possible responses associated with buttons, use of {ANY} or {-ANY} is not recommended.

Examples

Combinations of the individual pattern elements above are used to define allowable responses. The table below illustrates use of the elements within commonly used pattern definitions:

Pattern	Result
{*}	Permits input via Click, Inactive, Disabled on any button added to a Slide object. This is a quick method to enable input on all buttons on a Slide.
{Button1}	Permits input via click on Button1. This is the typical method for indicating input via button click.
{Button1.dblclick}	Permits input via double click on Button1. This method restricts input to a specific response type (i.e., other than the click default).
{-Button1.Down}	Permits input via release on Button1.
{Button1\|Button2}	Permits input via click on Button1 OR click on Button2. Individual button names are separated using the pipe (\|) symbol.
{Button1}{Button2.dblclick}	Permits input via click on Button1 OR double-click on Button2. Different response types are contained within their own braces.
{Button1.Inactive}	Permits input via click when another button is pressed down (i.e., active) at the same time.
{Button1.Disabled}	Permits input via click only when Button1 is disabled.
{Button1@2}	Permits input via a right click on Button1 when the primary key value is set to “1” (i.e., using script to restrict primary keys to only the left mouse button).

Allowable and Correct

The Allowable and Correct fields on the Duration/Input tab (i.e., of the object collecting the input) are required to match the value (Name or Response) that is being used for logging. For example, the image below (from the BasicButtonRT sample included with the E-Prime installation) indicates that a SlideButton is being used to collect input on the parent Slide object named “Stimulus.”

The Allowable field specifies response values that will be permitted as valid input. The value “{word|nonword}” indicates that SlideButton sub-objects whose Name or Response property is set to either “word” or “nonword” will be accepted as allowable input. In the BasicButtonRT sample experiment, two response buttons (YESButton and NOButton) exist on the Stimulus object to allow input, and their Response fields are set to “word” and “nonword,” respectively. Note that the individual values of “word” and “nonword” are separated by the pipe symbol (|) and are enclosed within braces ({}) as required by rules for defining Button device response patterns.

Definition of a value for the Correct field follows the general rules for response input (e.g., the value specified must be part of the Allowable response). In the example above, the StimType attribute exists within a List object, and is used to vary the correct answer per response.

Within the data file (e.g., BasicButtonRT.edat3), the value of the response (i.e., Stimulus.RESP), correct response (i.e., Stimulus.CRESP), and the StimType attribute are logged as defined by these fields.

Reaction Time

Assignment of the reaction time associated with input from a Button Device varies depending on the type of object collecting the input.

Object	Defined by
SlideChoice	Reaction time is assigned to the press of the Button
SlideSlider	Reaction time is assigned to the time of the release of the Slider

Custom

The following custom options are supported by the Button Device input mask:

Element	Type	Description
BackspaceResponse	Button response pattern	When the input mask receives a response matching this pattern, it removes the last response item from the response string (rather than appending the response to the response string).
ClearResponse	Button response pattern	When the input mask receives a response matching this pattern it empties the response string.
UndoChecks	Boolean flag (default = False)	If set, when processing the BackspaceResponse or ClearResponse, any time an AutoCheck button's Check-type response is removed from the response string the button's check state is toggled (default = false).
CollapseChecks	Boolean flag (default = False)	If set, any time the input mask receives a check-type response, any previous check-type responses from the same button are removed from the response string (default = false).

Next Article: E-STUDIO: Slide Layout Template [23584]
Previous Article: E-STUDIO: Touch Interface Support [24258]

Articles in this section

Comments

Articles in this section

Related articles