Programming Reference:Stimulus Class

From BCI2000 Wiki
Jump to: navigation, search

Stimulus Class

Location

src/shared/modules/application/stimuli

Synopsis

The Stimulus class is a virtual base class which defines an event handling interface for stimuli. There, a "Stimulus" is defined as "an object that can present (and possibly conceal) itself."

The Stimulus class is purely virtual; descendant classes need to implement its OnPresent() and OnConceal() event handlers. An application uses the public Stimulus::Present() and Stimulus::Conceal() functions to control its behavior; these, in turn, call the virtual event handlers.

The SetOfStimuli class allows to define sets of stimuli, and to present or conceal all of the stimuli it contains.

Properties

int Tag (rw)

An arbitrary integer that may be used to encode information about a given stimulus (e.g., its corresponding row in a configuration matrix).

Methods

Present()

Prompts a stimulus to present itself by calling its OnPresent() event handler.

Conceal()

Prompts a stimulus to conceal itself by calling its OnConceal() event handler.

Events

OnPresent()

In its OnPresent event handler, a stimulus is supposed to present itself, e.g., to make itself visible, play itself if it is a sound or a movie, or highlight itself if it is a P300 matrix element.

OnConceal()

In its OnConceal event handler, a stimulus is supposed to conceal itself, e.g., make itself invisible, or switch back to normal mode. For non-visual stimuli, this handler is typically empty.

This event is called Conceal rather than Hide because "Hide" is already used as a name for a GraphObject's function that makes it invisible.

Descendants

The Stimulus class is parent to a class hierarchy containing a number of auditory and visual stimuli:

Stimulus |-> VisualStimulus |-> ImageStimulus
         |                  |-> TextStimulus
         |-> AudioStimulus
         |-> SpeechStimulus
         |-> SoundStimulus

SetOfStimuli Class

Location

SetOfStimuli is declared in the Stimulus class header file.

Synopsis

SetOfStimuli is a helper class that allows to prompt presentation, concealing, and destruction of a group of stimuli.

Methods

Add(Stimulus pointer)

Adds a stimulus object to the set.

Remove(Stimulus pointer)

Removes a given stimulus object from the set; nothing happens when the specified stimulus is not a member of the set.

Clear()

Clears the set. Stimuli that were represented in the set in form of pointers are unaffected.

DeleteObjects()

Deletes all stimulus objects that are in the set, and clears the set. To avoid dangling pointers, and multiple deletion, you should make sure that the set's members are not part of any other SetOfStimuli by the time you call SetOfStimuli::DeleteObjects().

bool Contains(Stimulus pointer)

Returns true if the specified stimulus object is part of the set, and false otherwise.

bool Intersects(SetOfStimuli)

Returns true if any of the elements of the specified set is part of the set on which Intersects is called, and false otherwise.

Present()

Prompts each element of the set to present itself by calling its Present() method.

Conceal()

Prompts each element of the set to conceal itself by calling its Conceal() method.

See also

Programming Reference:AssociationMap Class, Programming Reference:Target Class, Programming Reference:StimulusTask Class

Programming Reference:AudioStimulus Class, Programming Reference:ImageStimulus Class, Programming Reference:TextStimulus Class, Programming Reference:VisualStimulus Class,

Programming Reference:GraphObject Class