Programming Reference:Shape Class

Location

src/shared/gui/Shapes

Synopsis

The Shape class is a base class for geometric shapes, inheriting the GraphObject interface and adding its own interface for shape properties, and intersection testing.

Methods

Shape(GraphDisplay, int zOrder = ShapeZOrder)

The constructor takes the usual GraphDisplay reference argument, and an integer indicating the shape's z position.

DeleteObjects()

Removes and deletes all GraphObject instances contained in the GraphDisplay.

Invalidate()

Marks the entire GraphDisplay area for repainting.

InvalidateRect(GUI::Rect)

Marks a rectangle within the GraphDisplay for repainting. The rectangle is given in screen pixel coordinates.

NOTE: The use of pixel coordinates has been introduced in rev 3599 to avoid artifacts from converting forth and back between normalized and pixel coordinates. Originally, the rectangle was specified in normalized coordinates.

Update()

Forces an immediate repaint of all invalidated areas in the GraphDisplay, making sure that changes in GraphObject state are reflected in the device's frame buffer. In BCI2000 application modules, this function should be called immediately before setting the StimulusTime time stamp.

GUI::Rect NormalizedToPixelCoordinates(GUI::Rect)

GUI::Rect PixelToNormalizedCoordinates(GUI::Rect)

These functions are used to convert between pixel/device coordinates, and normalized coordinates. Note that, from application code, GraphObjects are positioned and sized using normalized coordinates relative to the GraphDisplay's screen rectangle; in their OnPaint handlers, they are provided with pixel coordinates.

Paint(RegionHandle=NULL)

Triggers a repaint of the GraphDisplay's contents. When a region handle is specified, it is used as a clip during the paint operation, saving redraw of the entire GraphDisplay area when only a subregion has become invalid.

Change()

Triggers a Change event for all GraphObjects that are part of the display. For modifications in size or draw context, this function is called automatically.

Click(int x, int y)

Triggers a Click event for all GraphObjects that are part of the display. Unlike GraphObject::OnClick(), coordinates are pixel coordinates.

QueueOfGraphObjects ObjectsClicked()

When the user clicks inside a GraphDisplay, all objects' Click events are called to determine which of them were below the mouse pointer when clicking. Objects that consider themselves clicked are added to a queue, which is of type std::queue<GraphObject*>. This queue is accessible from the ObjectsClicked function; from the queue, clicked objects may be retrieved using its pop() member function.

ClearClicks()

Empties the queue of clicked objects.

BitmapImage BitmapData(width=0, height=0)

Returns the display's content, resampled to the specified target resolution, as a BitmapImage. When both width and height are 0 (the default), the image is returned in its original size, and no resampling takes place.

Methods for Intersection Testing

enum TestResult

Intersection test results have one of the following values:

false_: There is no intersection.
true_: There is an intersection.
undetermined: Intersection has not been determined.

TestResult Contains(Point)

Tests whether the specified point is part of the shape. Descendants of Shape should implement this function.

TestResult IntersectsArea(Shape)

Tests for intersection with a second shape's area. New descendants of Shape should use RTTI to test whether the argument is an existing descendant class, and provide intersection testing for all existing Shape descendants. This way, it is ensured that there exists an IntersectsArea() implementation for all pairs of Shape descendants, without modifying existing classes when creating new ones.

static bool AreaIntersection(Shape, Shape)

Tests for intersection between the two shapes specified.

Properties

GUI::Point Center

The shape's center of mass, i.e. what would be considered its "position". For simple shapes, this coincides with the center of the shape's bounding rectangle.

float LineWidth

The shape border's line width, in pixels.

RGBColor FillColor

The shape's filling color.

RGBColor Color

The color of the shape's border.

GUI::DrawContext Context (rw)

The draw context into which a GraphDisplay is supposed to render the GraphObjects it contains. A draw context consists of a handle to an output device context (HDC in Windows), and a rectangle within that device context's area.

RGBColor Color (rw)

The GraphDisplay's background color.

Events

OnPaint(GUI::DrawContext)

This is where the actual shape is drawn. Descendants of Shape must provide their own implementation of the OnPaint event handler.