Programming Reference:ApplicationWindow Class

Location

BCI2000/src/shared/modules/application/gui

Synopsis

Objects of type ApplicationWindow class represent windows of application modules. Typically, one such window exists, but more may be present in a single application module.

The ApplicationWindow class provides the following functionality:

• parameterization of application screen position and dimensions,
• display of a small copy of the application screen in an operator visualization window,
• refreshing the window, and writing a time stamp into the StimulusTime state variable once processing has been done in the Application Module,
• maintaining a list of application windows which may be accessed using the Environment::Window() and Environment::Windows() accessor functions.

ApplicationWindowpublicly inherits from DisplayWindow, and from EnvironmentExtension privately.

Application windows are identified by name; the default name is "Application".

Usage

Objects of type ApplicationWindow are created by calling Environment::Window( name ) from a filter's constructor. Typically, this is done in the constructor initializer of an ApplicationWindow reference:

#include "ApplicationWindow"
...
class MyTaskFilter : public GenericFilter
{
  ...
 private:
   ApplicationWindow& mrWindow;
  ...
};

...

MyTaskFilter::MyTaskFilter()
: mrWindow( Environment::Window( "Application" ) ),
  mNumber( 0 )
{
...
}

When multiple filters do this, specifying the same name, no duplicate windows are created; rather, a single ApplicationWindow instance will be shared among them. This implies that other filters in an application module may access existing windows via the Window( name ) accessor function provided by the Environment class. This allows filters to add specific information to existing windows. When no window creation is desired but access to an existing window only, call Environment::Window( name ) from your filter's Preflight() function rather than its constructor. This makes sure that a window of that name exists, and is later accessible through the Environment::Window() function during other phases of filter execution.

To enumerate existing windows, there is a second function, Environment::Windows() which takes no argument, and returns a pointer to a ApplicationWindowList which provides functions as described below.

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 GUI::GraphDisplay interface.

ApplicationWindow objects will handle display visualization transparently, using the GraphDisplay's BitmapData 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 <name>Window.

Properties

string Name (r)

A window's name is set when the window is created, and may not be changed afterwards. The name property defaults to "Application".

string VisualizationID (r)

The visualization source ID used when transmitting the window's content to the Operator module. The visualization ID is derived from the window's name by appending "Window" to the name.

Inheritance

ApplicationWindow inherits a number of methods and properties from the DisplayWindow class.

ApplicationWindowList Class

This class is a helper class, providing access to existing ApplicationWindow instances. There is only a single instance of ApplicationWindowList, and a pointer to this single instance is provided in Environment::Windows.

Methods

ApplicationWindow* operator[]( string )

A pointer to the ApplicationWindow instance with the given name, or NULL when no such instance exists.

bool Exists( string )

Returns true when an ApplicationWindow instance with the given name exists, false otherwise.

ApplicationWindow* operator[]( int )

A pointer to the ApplicationWindow instance with the given index in the list, or NULL when the index equals or exceeds Size().

int Size()

The number of ApplicationWindow instances.

Parameters

Parameter names are derived from the Application Window's name. For the default name of "Application", special parameter names apply; these are given first.

Application Window Properties

<name>WindowWidth, <name>WindowHeight

The width and height of the subject-visible application window, in pixels.

<name>WindowLeft, <name>WindowTop

The screen position of the application window's top left corner, in pixels.

<name>WindowBackgroundColor

The color of the window's background (area which is not covered by objects) in RGB format: 0xRRGGBB.

<name>WindowFullscreen

Put the window into full screen mode. Depending on the OS, this may improve timing.

<name>HideCursor

Hide the mouse cursor whenever it is located above the application window.

<name>WindowInfo

A matrix describing properties of the window, such as OpenGL version, window size and position in mm, screen size in mm, and logical resolution in pixels per mm. Each property's value is provided in a single row, and property names are provided as row labels.

Application Window Visualization

Visualize<name>Window

Switches visualization display of a miniature copy of the application window on or off.

<name>WindowSpatialDecimation

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.

<name>WindowTemporalDecimation

A factor that determines the visualization window's update rate. A value of n results in each nth frame being transferred.

States

StimulusTime

A 16-bit time stamp in the same format as the SourceTime state. This time stamp is set immediately after the application module has updated the stimulus/feedback display. In conjunction with the SourceTime state, the StimulusTime stamp may be used to infer the time of stimulus presentation with greater accuracy than when only using the StimulusCode and StimulusBegin states, which have an accuracy of one data block. To obtain meaningful values in the StimulusTime stamp, Source Module and Application Module need to run on the same machine.

See also

Programming Reference:ApplicationBase Class, Programming Reference:DisplayWindow Class, Programming Reference:EnvironmentExtension Class