Programming Reference:GraphObject Class

From BCI2000 Wiki
Jump to navigation Jump to search

Location

src/shared/gui

Synopsis

The GraphObject class defines an interface for graphical objects displayed by a BCI2000 application. GraphObjects are tied to a GraphDisplay, which typically represents an application window.

GraphObjects possess a z-order position that determines how they are drawn on top of each other. You do not instantiate GraphObjects directly; rather, you create objects of classes that inherit the GraphObject interface.

The GraphObject class is contained within the GUI namespace. To use it, either qualify its name: GUI::GraphObject (recommended for header files); or put a using statement on top of the file (recommended for cpp files):

using namespace GUI;

Methods

GraphObject(GraphDisplay, int zOrder)

The constructor of a graph object requires a reference to a GraphDisplay, and an integer that specifies the object's z order, where lower values correspond to objects that are drawn on top of objects with larger z order values.

Show()

Makes the object visible. Initially, objects are created in visible state.

Hide()

Makes the object invisible.

Invalidate()

Invalidates the object's bounding rectangle, i.e. marks it as needing to be repainted. Typically, this function is called from a derived class, indicating that a change in object properties has occurred that requires a repaint.

Paint()

Asks an object to paint itself by calling its OnPaint event handler.

Change()

Notifies an object of a change in display properties by calling its OnChange event handler.

bool Click(GUI::Point)

Tests whether the specified point is inside an object's bounding rectangle, and calls its OnClick event handler if this is the case.

Properties

GraphDisplay Display (r)

The GraphDisplay object that was specified when the object was created.

bool Visible (r)

True if the object is visible, false if it is hidden. Use the Hide() and Show() methods to set this property.

float ZOrder (rw)

Determines the order in which GraphObjects are drawn. GraphObjects with smaller values of ZOrder are drawn on top of those with larger values, hiding these.

enum AspectRatioMode (rw)

One of the following options:

AdjustNone
No adjustment is made.
AdjustWidth
The object's width is adapted to its contents, while keeping its height constant.
AdjustHeight
The object's height is adapted to its contents, keeping its width constant.
AdjustBoth
Both the object's height and width are adjusted to its content.

The exact behavior of aspect ratio adjustment depends on the object's type. E.g., for bitmap images, AdjustBoth will size the image such that one image pixel corresponds to one screen pixel; AdjustHeight and AdjustWidth will adjust such that the original aspect ratio is preserved.

GUI::Rect DisplayRect (rw)

The bounding rectangle of the space that is occupied by the object. This is given in coordinates relative to the size of the object's GraphDisplay; there, the upper left corner corresponds to (0,0), the lower right corner to (1,1). When a GraphObject is created, its display rectangle is empty.

Events

OnPaint(GUI::DrawContext)

From its OnPaint event handler, a GraphObject renders itself into a device context and rectangle specified in its DrawContext argument. The DrawContext consists of an OS device context handle, and a rectangle in device coordinates. Implementing this function is mandatory for classes inheriting from GraphObject.

OnChange(GUI::DrawContext)

The OnChange event handler is called to notify the object that a change in size, position, or output device has occurred. E.g., if the object maintains an internal bitmap buffer that it uses to speed up paint operations, it should delete and re-create that buffer from its OnChange handler to ensure consistency with the output draw context. Objects that render themselves directly do not need to override the (empty) default handler.

bool OnClick(GUI::Point)

The OnClick event handler receives a point in normalized coordinates, and returns whether it considers itself clicked. The default handler does nothing, and returns true.

Descendants

The GraphObject class is parent to the following class hierarchy:

GraphObject |-> Shape |-> RectangularShape
            |         |-> EllipticShape
            |-> StatusBar
            |-> ImageStimulus
            |-> TextField
            |-> Scene

See also

Programming Reference:GraphDisplay Class