GLOW API version 1.0 reference

Back to
Table of contents


class GlowComponent

General information

type: class
inherits: (none)
module: glow

GlowComponent is the base class of all drawable objects. GlowSubwindow, GlowWindow, GlowWidget, and all other drawable components inherit from GlowComponent. The component level understands three concepts: redraw, activation and hierarchy. To perform drawing, a subclass should override one or both of the methods OnBeginPaint() and OnEndPaint(). GLOW components may be arranged in a hierarchy similar to a scene graph. Several functions, such as drawing and activation, when applied to a component in the hierarchy, also recursively apply to all its descendents. Deleting a component also deletes its descendents.

All GLOW programs must make use of components at one time or another. Normally, you do not use GlowComponents directly, but instead subclass a GlowComponent.

Methods

Constructors and destructor

GlowComponent(GlowComponent* parent)

Creates a new GlowComponent and adds it to parent's children. The new component now lives underneath parent in the hierarchy.

GlowComponent(void)

Creates a new GlowComponent but does not initialize it. A component created in this way may not be used until its Init() method is called.

void Init(GlowComponent* parent)

Initializes a GlowComponent by adding it to parent's children. The new component now lives underneath parent in the hierarchy.

virtual ~GlowComponent(void)

The destructor for GlowComponent also recursively deletes the component's children in the hierarchy.

void Close(void)

Requests a deferred deletion of the component. The component won't actually be deleted until you've finished handling the current event and control is passed back to GLOW. This should be useful, for example, for destroying a window from within one of its methods or a method of one of its children, as it is safer than delete this.

Examining a component's ancestors
You can gather information about components further up in the hierarchy.

GlowComponent* Parent(void) const

Returns the immediate parent of this component. If this component is the root of a heirarchy, returns 0.

GlowSubwindow* WhichWindow(void)

If this component is a GlowSubwindow, returns this, otherwise, returns the nearest GlowSubwindow containing this component.

GlowSubwindow* ParentWindow(void) const

Returns Parent()->WhichWindow().

GlowWindow* ToplevelWindow(void)

Returns a pointer to the object at the top of the hierarchy, which is always a GlowWindow.

bool IsToplevel(void) const

Returns true if and only if this component is at the top of a hierarchy.

Examining a component's siblings
You can get information on a component's siblings using these methods.

GlowComponent* Next(void) const

Returns a pointer to the next component in its parents children list, or NULL if this is the last component.

GlowComponent* Prev(void) const

Returns a pointer to the previous component in its parents children list, or NULL if this is the first component.

Examining a component's children
You can manipulate a component's children using these methods.

int NumChildren(void) const

Returns the number of children under this component.

GlowComponent* FirstChild(void) const

Returns a pointer to the first child component, or NULL if this component has no children.

GlowComponent* LastChild(void) const

Returns a pointer to the last child component, or NULL if this component has no children.

void ReorderChild(GlowComponent* child, GlowComponent* pos)

Reorders the children, moving the given child immediately before the given position in the child component list. To move the child to the end of the list, pass NULL for the position. Throws an assertion if either component is not a child of this component.

void KillChildren(void)

Deletes all children of this component.

Component activation and deactivation
Components may be activated or deactivated. Deactivation propagates down the hierarchy to all children, so deactivating a component deactivates all its descendents. Reactivating the component reactivates its descendents unless they have also been explicitly deactivated. There are three states for activation: active, inactive, and activeStandby. Active means the component is active. Inactive means the component has been explicitly deactivated. ActiveStandby means the component is inactive because one of its ancestors was explicitly deactivated, but the component has not been explicitly deactivated itself. These methods also may cause activation events, described below, to be raised; however, those events are not raised immediately. Instead, they are queued and then raised when control is given back to the GLOW system. (This is similar to the mechanism employed by GLUT.) This allows GLOW to combine or eliminate events where possible; e.g. if a component is deactivated and then re-activated immediately before GLOW regains control, no event is sent. However, the activation state as reported by methods like IsActive() will reflect changes immediately.

void Activate(void)

Activates this component. Also changes any descendants from activeStandby to active if appropriate.

void Deactivate(void)

Deactivates this component. Also changes any descendants from active to activeStandby if appropriate.

bool IsActive(void)

Returns true if and only if this component is in the active state.

bool IsInactive(void)

Returns true if and only if this component is in the inactive state.

bool IsActiveStandby(void)

Returns true if and only if this component is in the activeStandby state.

Drawing methods

void Paint(void)

This advanced routine draws this component and all its children by recursively calling the respective OnBeginPaint() and OnEndPaint() methods. Normally, you do not need to draw components explicitly in this mannner, because GLOW will call the appropriate Paint() methods when it handles a refresh event. However, if you ever need a component to draw itself without going through the refresh mechanism, you can use this routine.

Overrideable methods

Drawing methods
Subclasses should override these methods to perform drawing. They are called whenever a component needs to be redrawn, either in response to a window manager event or in response to an explicit call to the Refresh() method of a window. Drawing propagates down the component hierarchy as follows. The window manager first informs a window or a subwindow that it needs to be redrawn. A redraw then begins at that point in the hierarchy and propagates downward towards the descendents. The recursion kernel is as follows. First, the component's OnBeginPaint() method is called. If OnBeginPaint() returns true, each of the component's children is recursively redrawn. Finally, after all children have finished, the component's OnEndPaint() method is called. If OnBeginPaint() returns false, the children are ignored, but OnEndPaint() is still called. Recursion stops when a subwindow is encountered. If a component has a child which is a subwindow, the subwindow is not recursively redrawn. Instead, if that subwindow needs redrawing, the window manager will send it a separate redraw request, and another recursive redraw will begin at that subwindow.

virtual bool OnBeginPaint(void)

Override this method to perform any drawing that must be done before drawing is propagated to children. If the method returns true, the children will be redrawn; if false, the children will not be redrawn. The default method does nothing and returns true.

virtual void OnEndPaint(void)

Override this method to perform any drawing that must be done after drawing has finished propogating to children. The default method does nothing.

Activation events
Subclasses may override these methods to respond to changes in activation. Specifically, if a component is activated-- that is, its state is changed from inactive to active as a result of being explicitly activated, or from activeStandby to active as a result of an ancestor being explicitly activated, then OnActivate() is called. If a component is deactivated-- that is, its state is changed from active to inactive as a result of being explicitly deactivated, or from active to activeStandby as a result of an ancestor being explicitly deactivated, then OnDeactivate() is called.

virtual void OnActivate(void)

Override this method to perform any task in response to a component being activated. The default method does nothing.

virtual void OnDeactivate(void)

Override this method to perform any task in response to a component being deactivated. The default method does nothing.

Back to
Table of contents


The GLOW Toolkit