Programming Reference:ApplicationBase Class

2012-02-10T18:39:36Z

Zfreudenburg: /* Application Log */

==Location==
<tt>BCI2000/src/shared/modules/application</tt>

==Synopsis==
The <tt>ApplicationBase</tt> class bundles base functionality which is useful for any BCI2000 application module. This base functionality comprises
*generation of random numbers,
*maintaining an application log file, and application log messages to the operator user.

==Usage==
An application module uses the <tt>ApplicationBase</tt> class by deriving its [[BCI2000 Glossary#Task|task filter]] from <tt>ApplicationBase</tt> rather than <tt>GenericFilter</tt> directly. It has then access to the facilities explained below.

==Access to Application Windows==
The <tt>ApplicationBase</tt> class inherits from the [[Programming Reference:ApplicationWindowClient Class|<tt>ApplicationWindowClient</tt> class]], and thus provides access to framework-managed [[Programming Reference:ApplicationWindow Class|application windows]].
To access, and possibly create, the main application window from your <tt>ApplicationBase</tt>-derived application filter class, initialize an <tt>ApplicationWindow</tt> reference in its constructor with the <tt>ApplicationWindowClient::Window()</tt> function:
<pre>
class MyTaskFilter : public ApplicationBase
{
...
private:
ApplicationWindow& mrWindow;
...
};

MyTaskFilter::MyTaskFilter()
: mrWindow( ApplicationWindowClient::Window() )
{
...
}

MyTaskFilter::Initialize( ... )
{
...
ImageStimulus* pImageStimulus = new ImageStimulus( mrWindow );
...
}
</pre>
You may also test windows for existence from the <tt>Preflight()</tt> function, and only use them when they already exist. This way, your code can adapt to the presence of certain filters in the application module. For more details, see the [[Programming Reference:ApplicationWindowClient Class|<tt>ApplicationWindowClient</tt> class]] reference page.

==RandomNumberGenerator==
The <tt>ApplicationBase</tt> class provides an object of type [[Programming Reference:RandomGenerator Class|<tt>RandomGenerator</tt>]] which may be used to obtain integer pseudo-random numbers uniformly distributed over a specified range:
int rnd = RandomNumberGenerator(10);
will assign a number between 0 and 9 to the variable named "rnd".
Compared with other options to obtain pseudo-random numbers, the advantage of using <tt>ApplicationBase::RandomNumberGenerator</tt> object is that its behavior is governed by a global random seed value; this allows consistent, predictable BCI2000 behavior, e.g. for testing purposes.
For more information, refer to the [[Programming Reference:RandomGenerator Class|<tt>RandomGenerator</tt>]] reference page.

==Application Log==
Typically, a BCI2000 application module displays messages to the operator user to indicate that a new trial has started, a target has been hit or missed, or to display statistics about the current run. Often, this is information, in conjunction with additional, more detailed information is written into a log file, and that log file is maintained side-by-side with recorded data in the current session directory.

The <tt>ApplicationBase</tt> class provides an object named <tt>AppLog</tt> as a convenient interface to write messages to screen, log file, or both at the same time. That <tt>AppLog</tt> object uses a [[Programming Reference:LogFile Class|<tt>LogFile</tt>]] object to write into a log file; it uses a [[Programming Reference:GenericVisualization Class|<tt>GenericVisualization</tt>]] object to write messages into an operator window.

The <tt>AppLog</tt> object is a <tt><std::ostream></tt>, and may be used as in the following examples:
// Write a message to the log file only
AppLog.File << "This message goes into the log file." << endl;

// Write a message to the screen only
AppLog.Screen << "This message goes into an operator window." << endl;

// Write a message to both screen and file:
AppLog << "This message is displayed by the operator module, and written into the log file." << endl;

Make sure to include the "endl" as nothing is written until the AppLog receives a newline command.

The application log file is located in the current session directory, and named after the current session; it carries an '''.applog''' extension.

Operator log window messages have ''APLG'' as their [[Technical Reference:BCI2000 Messages|visualization source ID]].

==Remarks==
Typically, a BCI2000 application module will implement a paradigm that belongs to one of two categories:
*evoking responses using stimulus presentation,
*continuously presenting feedback of brain activity.
A BCI2000 task filter implementing one of these paradigms will not inherit from the <tt>ApplicationBase</tt> directly but either from the [[Programming Reference:StimulusTask Class|StimulusTask]] or [[Programming Reference:FeedbackTask Class|FeedbackTask]].
Still, such a task filter has access to all functionality provided by <tt>ApplicationBase</tt>.

==See also==
[[Programming Reference:StimulusTask Class]], [[Programming Reference:FeedbackTask Class]], [[Programming Reference:ApplicationWindowClient Class]]

[[Category:Framework API]][[Category:Development]]

BCI2000 Wiki - User contributions [en]

Programming Reference:ApplicationBase Class