Programming Reference:ApplicationBase Class: Difference between revisions

Revision as of 17:45, 4 July 2011

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.

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;

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.

@@ Line 5: / Line 5: @@
 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,
+*maintaining an application log file, and application log messages to the operator user.
-*parameterization of application screen position and dimensions,
-*display of a small copy of the application screen in an [[User_Reference:Operator_Module#Visualization_Windows|operator visualization window]].
 ==Usage==
@@ Line 37: / Line 35: @@
 Operator log window messages have ''APLG'' as their [[Technical Reference:BCI2000 Messages|visualization source ID]].
-==Display Parameterization and Visualization==
-Typically, a BCI2000 application module displays feedback or other stimuli in an application window. In the GUI abstraction layer of the BCI2000 framework, the application window's drawing area is represented as an object that inherits the [[Programming Reference:GraphDisplay Class|<tt>GUI::GraphDisplay</tt>]] interface.
-When a derived class provides its underlying <tt>ApplicationBase</tt> with a <tt>GUI::GraphDisplay</tt> pointer at construction time, the <tt>ApplicationBase</tt> class will handle display visualization transparently.
-The <tt>ApplicationBase</tt> class uses the <tt>GraphDisplay</tt>'s <tt>BitmapData</tt> method to obtain a copy of its contents, and to send these to the operator module for display in a visualization window using a message source ID of ''APSC''.
-==Parameters==
-===Application Window Properties===
-{{ApplicationBaseParams}}
-===Application Window Visualization===
-Visualization parameters are available only if the descendant class provides a <tt>GUI::GraphDisplay</tt> pointer at construction time.
-====VisualizeApplicationWindow====
-Switches visualization display of a miniature copy of the application window on or off.
-==== AppWindowSpatialDecimation====
-A factor that determines resolution of visualized data in relation to the original window's size.
-Enlarging the factor reduces the visualization window's resolution, and its initial size, and improves system timing by reducing the amount of data transferred.
-====AppWindowTemporalDecimation====
-A factor that determines the visualization window's update rate. A value of ''n'' results in each ''n''th sample being transferred.
 ==Remarks==