GLOW API version 1.0 reference

Back to Table of contents

class GlowWidgetRoot

General information

type: base
inherits: (none)
module: glowWidget

GlowWidgetRoot occupies the root of a widget hierarchy. It manages event delivery, keyboard focus and other widget issues. You do not instantiate a GlowWidgetRoot directly, but instead use one of the classes derived from it, such as GlowWidgetWindow.

To create a widget root class, you should generally inherit both from GlowWidgetRoot and from GlowSubwindow or one of its subclasses. The subwindow should come first, to ensure that the widget root is destructed before the subwindow. You'll also need to pass a pointer to the subwindow, to GlowWidgetRoot::Init(), and override the subwindow's mouse and keyboard methods to call the appropriate widget root methods.

GLOW programs that use widgets must deal with GlowWidgetRoots.

Methods

Destructor

virtual ~GlowWidgetRoot(void)

The destructor for GlowWidgetRoot cleans up event delivery and keyboard focus information. The appropriate widgets should still exist, so make sure this destructor is called before any corresponding subwindow destructor deletes the widgets.

Widget root operations
You can perform special widget root operations using these methods.

GlowSubwindow* Subwindow(void) const

Returns a pointer to the subwindow receiving events for this widget root.

GlowColor GetBackColor(void) const

Returns the current background color for the widget root.

void SetBackColor(GlowColor c)

Sets the current background color for the widget root.

void SetKeyboardFocus(GlowWidget* widget)

Sets the keyboard focus to the given widget. Throws an assertion if the given widget cannot accept keyboard focus.

GlowWidget* GetKeyboardFocus(void)

Returns the widget with the keyboard focus, or 0 if no widget has keyboard focus.

void AdvanceKeyboardFocus(void)

Advances keyboard focus to the next eligible widget.

GlowWidget* FindWidget(int& x, int& y)

Determines which widget owns the given coordinates in the widget root-- e.g., if the mouse were clicked in that point, which widget would be hit. Returns a pointer to the widget, or null if no widget is hit. Also modifies the passed parameters to give the point in that widget's local coordinates.

Managing event filters
Event filters can be set up to pre-filter keyboard events before they are delivered. They can modify the parameters of the event, or even handle the event themselves and consume the event so it is not passed on to the receiving widget.

static void RegisterFilter(GlowWidgetKeyboardFilter* filter)

Adds the given keyboard event filter to the list of filters. Has no effect if the filter is already registered.

static void UnregisterFilter(GlowWidgetKeyboardFilter* filter)

Removes the given keyboard event filter from the list of filters. Has no effect if the filter is not registered.

static void UnregisterAllFilters(void)

Unregisters all keyboard event filters.

static unsigned int NumRegisteredFilters(void)

Returns the number of registered keyboard event filters.

static bool IsFilterRegistered(GlowWidgetKeyboardFilter* filter)

Reports whether the given keyboard event filter is registered.

Methods for subclasses

Constructor and initializer

GlowWidgetRoot(void)

Creates a new GlowWidgetRoot but does not initialize it. The widget root may not be used until its Init() method is called.

void Init(GlowSubwindow* subwindow, GlowColor backColor)

Initializes a GlowWidgetRoot with options specified by the given params. subwindow specifies the subwindow that will enclose these widgets. backColor gives the color of the background for the widgets.

Event handlers
These methods are analogous to the corresponding GlowSubwindow methods. For proper event delivery to widgets, the subwindow should override its event handling methods and call these.

void WRMouseDown(Glow::MouseButton mouseButton, int x, int y, Glow::Modifiers modifiers)

void WRMouseUp(Glow::MouseButton mouseButton, int x, int y, Glow::Modifiers modifiers)

void WRMouseDrag(int x, int y)

void WRKeyboard(Glow::KeyCode key, int x, int y, Glow::Modifiers modifiers)

bool WRBeginPaint(void)

void WREndPaint(void)

Back to Table of contents