Programming Reference:ApplicationBase Class

Location

BCI2000/src/shared/modules/application

Synopsis

The ApplicationBase 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 ApplicationBase class by deriving its task filter from ApplicationBase rather than GenericFilter directly. It has then access to the facilities explained below.

Access to Application Windows

The ApplicationBase class inherits from the ApplicationWindowClient class, and thus provides access to framework-managed application windows. To access, and possibly create, the main application window from your ApplicationBase-derived application filter class, initialize an ApplicationWindow reference in its constructor with the ApplicationWindowClient::Window() function:

 class MyTaskFilter : public ApplicationBase
 {
    ...
   private:
    ApplicationWindow& mrWindow;
    ...
 };

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

 MyTaskFilter::Initialize( ... )
 {
   ...
   ImageStimulus* pImageStimulus = new ImageStimulus( mrWindow );
   ...
 }

You may also test windows for existence from the Preflight() 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 ApplicationWindowClient class reference page.

RandomNumberGenerator

The ApplicationBase class provides an object of type RandomGenerator 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 ApplicationBase::RandomNumberGenerator 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 RandomGenerator 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 ApplicationBase class provides an object named AppLog as a convenient interface to write messages to screen, log file, or both at the same time. That AppLog object uses a LogFile object to write into a log file; it uses a GenericVisualization object to write messages into an operator window.

The AppLog object is a <std::ostream>, 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 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 ApplicationBase directly but either from the StimulusTask or FeedbackTask. Still, such a task filter has access to all functionality provided by ApplicationBase.

See also

Programming Reference:StimulusTask Class, Programming Reference:FeedbackTask Class, Programming Reference:ApplicationWindowClient Class