|
|
Back to Table of contents |
| General information |
type: class
inherits: GlowComponent
module: glowWidgetGlowWidget is the base class of all GLOW widgets. Note that it inherits from GlowComponent rather than GlowSubwindow. Although it understands many of the same concepts as a subwindow, there are some subwindow methods not understood by a widget. Implementation-wise, a widget does not correspond to a GLUT subwindow. Normally, you do not create a GlowWidget directly, but instead use a subclass.
Like a subwindow, a widget defines two coordinate systems: a pixel coordinate system, and a drawing coordinate system. The pixel coordinate system is measured in pixels, with (0,0) at the upper left, increasing down and to the right. This coordinate system is used to position subwindows within the subwindow, and to locate events such as mouse clicks. Drawing coordinates operate similarly to but not the same as subwindows. Because a widget does not use a true subwindow, you should not rely on glViewport() when drawing a widget. Instead, set the view frustum and use scissoring. Many of the methods on widgets operate in the pixel coordinate system.
Widgets are components and occupy places in a component hierarchy. Because they are not subwindows, however, you cannot find the parent widget using ParentWindow(). Instead, the parent widget is assumed to be the immediate parent component, found using the Parent() method. Many methods of GlowWidget, such as those involving position of the widget, operate in the pixel coordinates of the parent widget.
At the top of a widget hierarchy is a widget root, represented by a GlowWidgetRoot. This is a special subwindow that manages the widgets underneath it and routes events.
All GLOW programs that use widgets will need to deal with the GlowWidget API.
| Constants |
AutoPack error codes
enum GlowWidget::AutoPackError noAutoPackError
AutoPack completed successfullyenum GlowWidget::AutoPackError hAutoPackError
AutoPack encountered an error packing horizontally.enum GlowWidget::AutoPackError vAutoPackError
AutoPack encountered an error packing vertically.AutoPack sizing and positioning options
enum GlowWidget::AutoPackOptions noReshape
Don't reshape the widgetenum GlowWidget::AutoPackOptions preferredSize
Use widget's preferred size.enum GlowWidget::AutoPackOptions expandPreferredSize
Use widget's preferred size, but request that it expand to fill the space.enum GlowWidget::AutoPackOptions forcedSize
Attempt to force the widget to fill the space.enum GlowWidget::AutoPackOptions noMove
Don't move the widgetenum GlowWidget::AutoPackOptions leftPos
Align the widget with the left limit.enum GlowWidget::AutoPackOptions rightPos
Align the widget with the right limit.enum GlowWidget::AutoPackOptions topPos
Align the widget with the top limit.enum GlowWidget::AutoPackOptions bottomPos
Align the widget with the bottom limit.enum GlowWidget::AutoPackOptions centerPos
Center the widget between or around the limits.Special AutoPack positioning and sizing values
enum { unspecifiedSize }
Constant passed to OnAutoPack() to indicate that no size limit is imposed.enum { unspecifiedPos }
Indicates that one of the limits given to AutoPack() is unspecified.
| Methods |
Constructors and destructor
GlowWidget(GlowWidget* parent, const GlowWidgetParams& params)
Creates a new GlowWidget using the given params and adds it to parent's children. The new widget now lives underneath parent in the hierarchy.GlowWidget(GlowWidgetRoot* root, const GlowWidgetParams& params)
Creates a new GlowWidget using the given params and adds it to the top level under root.GlowWidget(void)
Creates a new GlowWidget but does not initialize it. A widget created in this way may not be used until its Init() method is called.void Init(GlowWidget* parent, const GlowWidgetParams& params)
Initializes a new GlowWidget using the given params and adds it to parent's children. The new widget now lives underneath parent in the hierarchy.void Init(GlowWidgetRoot* root, const GlowWidgetParams& params)
Initializes a new GlowWidget using the given params and adds it to the top level under root.virtual ~GlowWidget(void)
The destructor for GlowWidget also recursively deletes the widget's children in the hierarchy.Methods involving position
Widgets occupy a specific area of the screen. You can set and query the position information using these methods. These methods also may cause widget move 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 moved twice in succession before GLOW regains control, only one event is sent with the final position. However, the widget state as reported by methods like PositionX() and PositionY() will reflect changes immediately.void Move(int x, int y)
Moves a widget so that its upper left corner lands at the given pixel coordinates in its parent widget's coordinate system.int PositionX(void) const
Returns the pixel position of the left edge of the widget, in the coordinates of the parent widget.int PositionY(void) const
Returns the pixel position of the top edge of the widget, in the coordinates of the parent widget.int RootPositionX(void) const
Returns the pixel position of the left edge of the widget, in the coordinates of the widget root.int RootPositionY(void) const
Returns the pixel position of the top edge of the widget, in the coordinates of the widget root.int GlobalPositionX(void) const
Returns the pixel position of the left edge of the widget, in screen coordinates.int GlobalPositionY(void) const
Returns the pixel position of the top edge of the widget, in screen coordinates.Methods involving size
Widgets occupy a specific area of the screen. You can set and query the size information using these methods. These methods also may cause widget reshape 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 resized twice in succession before GLOW regains control, only one event is sent with the final size. However, the widget state as reported by methods like Width() and Height() will reflect changes immediately.void Reshape(int width, int height)
Resizes a widget.int Width(void) const
Returns the width of the widget.int Height(void) const
Returns the height of the widget.Methods involving autopacking
GlowWidget::AutoPackError AutoPack(int leftLimit, int rightLimit, int topLimit, int bottomLimit, GlowWidget::AutoPackOptions hOption, GlowWidget::AutoPackOptions vOption, int& leftMargin, int& rightMargin, int& topMargin, int& bottomMargin)
GlowWidget::AutoPackError AutoPack(int leftLimit, int rightLimit, int topLimit, int bottomLimit, GlowWidget::AutoPackOptions hOption, GlowWidget::AutoPackOptions vOption)Causes a widget to attempt to move and resize itself to fit within the given limits. The exact behavior is defined by the widget's OnAutoPack() method. Some widgets may also resize and rearrange their children in the process. This is often useful for systems that automatically lay out widgets in a window, such as the GlowQuickPalette API. hOption and vOption give the packing policy to use. There are two sets of constants from GlowWidget that should be or'ed together to form the policy. The following are the sizing constants. noReshape indicates do not reshape in the given direction. forcedSize indicates attempt to force the widget to fit snugly in the given limits. preferredSize indicates to allow the widget to choose a preferred size for itself, as long as it does not exceed the given limits. expandPreferredSize is the same as preferredSize, but also requests that the widget expand itself to fill the given limits. A widget may or may not choose to honor the request. The following are the positioning constants. noMove indicates do not move in the given direction. topPos indicates align the widget with the top of the given vertical limits. bottomPos indicates align the widget with the bottom of the given vertical limits. leftPos indicates align the widget with the left side of the given horizontal limits. rightPos indicates align the widget with the right side of the given horizontal limits. centerPos indicates center the widget within the given limits. In this last case, passing unspecifiedPos for the second limit (right or bottom) will cause the widget to be centered around the first limit. The method will return an error code, also defined in GlowWidget, indicating success or failure. The first version of the overloaded method also returns information about how much margin the widget chose to keep around itself while packing. Normally, these values are 0, but they may be nonzero in labeled widgets such as GlowLabeledPopupMenuWidget. You may pass unspecifiedPos in the limits fields, as long as there is enough information for AutoPack() to execute. For example, if you specify leftPos to align left but give unspecifiedPos for the left limit, AutoPack() will throw an assertion.GlowWidget::AutoPackError AutoReshape(int& leftMargin, int& rightMargin, int& topMargin, int& bottomMargin)
GlowWidget::AutoPackError AutoReshape()Causes a widget to attempt to resize itself to its preferred size. Does not move the widget. Equivalent to calling AutoPack with unspecifiedPos for all four limits, and preferredSize | noMove for both options.Methods involving visibility
You can show and hide widgets, and test for visibility using these methods. These methods also may cause widget visibility 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 made invisible and then re-made visible before GLOW regains control, no event is sent. However, the widget state as reported by methods like IsVisible() will reflect changes immediately.void Hide(void)
Hides the widget if it is visible. Note that this also hides any widgets under this one in the hierarchy. Execution is deferred.void Show(void)
Shows the widget if it is invisible. Execution is deferred.bool IsVisible(void) const
Returns true if and only if the widget is visible.bool IsInvisible(void) const
Returns true if and only if the widget has been explicitly hidden.bool IsVisibleMasked(void) const
Returns true if and only if the widget has not been explicitly hidden but is invisible because one of its ancestors has been hidden.Methods involving drawing
void Refresh(void)
Notifies GLOW that the widget needs to be redrawn. This causes the entire widget root subwindow to redraw. The actual redraw is queued and will be initiated by GLOW once the system has control. Note that multiple Refresh() calls can be issued without harm; the widget root will only be redrawn once, regardless of the number of requests in the queue.void SetRefreshEnabled(bool enabled)
Sets whether refresh is currently enabled for this widget. If refresh is not enabled, calls to Refresh() will have no effect. Normally, this should be left set at true, but it may be useful to disable refresh temporarily in special cases, such as if you need to change the state of a widget during a redraw callback (which would otherwise cause a second refresh request to be queued.)bool IsRefreshEnabled(void) const
Returns whether refresh is currently enabled for this widget. If refresh is not enabled, calls to Refresh() will have no effect.void SetClipping(bool clip)
Sets the clipping attribute. If clipping is on, the scissor rectangle will be intersected with the widget's rectangle prior to drawing. This will cause the widget, and any of its children, to be clipped to its rectangle.bool IsClipping(void)
Returns the current clipping attribute.Methods involving keyboard focus
Widgets may receive keyboard events. Keyboard events occurring within the entire widget root are routed to a single widget, which is said to have the keyboard focus. A widget may request or relinquish the keyboard focus.void GrabKeyboardFocus(void)
Attempts to grab the keyboard focus for this widget root.void RelinquishKeyboardFocus(void)
Relinquishes the keyboard focus for this widget root. The focus will shift to the next widget under the current root which can accept keyboard focus.bool HasKeyboardFocus(void)
Returns true if and only if this widget has the keyboard focus.Other information
GlowWidgetRoot* Root(void)
Returns a pointer to the widget root containing this widget.void SetRefCon(long refcon)
Sets a reference constant for this widget. The reference constant may be used by your application.long GetRefCon(void)
Returns the reference constant for this widget.Inherited methods
These methods are inherited from GlowComponent.void Close(void)
GlowComponent* Parent(void) const
GlowSubwindow* WhichWindow(void)
GlowSubwindow* ParentWindow(void) const
GlowWindow* ToplevelWindow(void)
bool IsToplevel(void) const
GlowComponent* Next(void) const
GlowComponent* Prev(void) const
int NumChildren(void) const
GlowComponent* FirstChild(void) const
GlowComponent* LastChild(void) const
void ReorderChild(GlowComponent* child, GlowComponent* pos)
void KillChildren(void)
void Activate(void)
void Deactivate(void)
bool IsActive(void)
bool IsInactive(void)
bool IsActiveStandby(void)
void Paint(void)
| Protected methods for subclasses |
Initialization
void Init(GlowWidgetRoot* root, GlowWidget* parent, const GlowWidgetParams& params)
Initializes a new GlowWidget using the given params and adds it to root's hierarchy under parent. parent must be present in root's hierarchy.Drawing tools
void NormalizeCoordinates(int x, int y, GLfloat& xn, GLfloat& yn) const
Translates pixel coordinates into normalized drawing coordinates, in which (0,0) is at the center of the widget rectangle, and the edges are all +/-1. Often useful during drawing.Registering to receive events
void RegisterMouseEvents(void)
Informs the root that this widget wants to receive widget mouse events.void RegisterKeyboardEvents(void)
Informs the root that this widget wants to receive widget keyboard events. The widget will be made eligible to get keyboard focus.void UnegisterMouseEvents(void)
Informs the root that this widget no longer wants to receive widget mouse events.void UnregisterKeyboardEvents(void)
Informs the root that this widget no longer wants to receive widget keyboard events. The widget will be made ineligible to get keyboard focus. If it has the keyboard focus already, it will automatically relinquish it.
| Overrideable methods |
Drawing methods
Subclasses should override this method to perform drawing.virtual void OnWidgetPaint(void)
Override this method to draw a widget. It is called whenever this widget needs to be redrawn.User interface events
Subclasses should override these methods to respond to user interface events such as mouse clicks or keypresses. Remember that you must also be sure to notify GLOW that the subwindow wishes to receive such events by setting the event mask appropriately. If you do not set the event mask, you may still override these methods, but they will not be called.virtual void OnWidgetMouseDown(Glow::MouseButton mouseButton, int x, int y, Glow::Modifiers modifiers)
Override this method to respond to a mouse button press. When the method is called, button is set to the mouse button involved, x and y are set to the location of the click in the widget's pixel coordinates, and modifiers is set to the keyboard modifiers that are down at the time of the event. See the constants in Glow for values for these parameters. The default method does nothing.virtual void OnWidgetMouseUp(Glow::MouseButton mouseButton, int x, int y, Glow::Modifiers modifiers)
Override this method to respond to a mouse button release. When the method is called, button is set to the mouse button involved, x and y are set to the location of the release in the widget's pixel coordinates, and modifiers is set to the keyboard modifiers that are down at the time of the event. See the constants in Glow for values for these parameters. The default method does nothing.virtual void OnWidgetMouseDrag(int x, int y)
Override this method to respond to a mouse move while a button is depressed. When the method is called, x and y are set to the location of the pointer in the widget's pixel coordinates. This location may be outside the widget if the button was initially pressed inside the widget but was dragged outside. The default method does nothing.virtual void OnWidgetKeyboard(Glow::KeyCode key, int x, int y, Glow::Modifiers modifiers)
Override this method to respond to the a key being pressed. key contains the character hit, as a value between 0 and 255. If the value of key is greater than Glow::specialKeyOffset, then it will be one of the non-ascii keyboard codes defined in Glow. modifiers specifies keyboard modifiers that were down during the event. See the constants in Glow for modifier flags. x and y give the x and y coordinates of the pointer in widget pixel coordinates at the time of the event. The default method does nothing.Other events
Subclasses should override these methods to respond to other events such as resizing, keyboard focus and activation. These events may be raised because of window manager activity, or activity further up the hierarchy (for example, moving a parent widget causes its children to receive widget move events). Normally, widgets do not need to do anything, because typical widgets only need to be redrawn in such cases, which happens automatically. However, if a widget needs to perform special processing such as manipulating an embedded subwindow, it should override the appropriate methods to receive these events.virtual void OnWidgetMove(int x, int y)
Override this method to respond to a widget move. The default method does nothing.virtual void OnWidgetReshape(int width, int height)
Override this method to respond to a widget reshape. The default method does nothing.virtual void OnWidgetInvisible(void)
Override this method to respond to a widget being made invisible, either because it has been made invisible, or because an ancestor widget was hidden. The default method does nothing.virtual void OnWidgetVisible(void)
Override this method to respond to a widget being made visible. The default method does nothing.virtual void OnWidgetDeactivate(void)
Override this method to respond to a widget being made inactive, either because it has been deactivated, or because an ancestor widget was deactivated. The default method does nothing. Use this method instead of GlowComponent::OnDeactivate().virtual void OnWidgetActivate(void)
Override this method to respond to a widget being activated. The default method does nothing. Use this method instead of GlowComponent::OnActivate().virtual void OnGotKeyboardFocus(void)
Override this method to respond to a widget receiving the keyboard focus. The default method does nothing.virtual void OnLostKeyboardFocus(void)
Override this method to respond to a widget losing the keyboard focus. The default method does nothing.Miscellaneous
virtual GlowWidget::AutoPackError OnAutoPack(int hSize, int vSize, GlowWidget::AutoPackOptions hOption, GlowWidget::AutoPackOptions vOption, int& leftMargin, int& rightMargin, int& topMargin, int& bottomMargin)
Override this method to provide a preferred behavior for the AutoPack() system. A subclass should override this method to allow widgets to be automatically sized and positioned. hOption and vOption give the sizing option to use. GlowWidget::noReshape means leave the size alone. GlowWidget::forcedSize means attempt to force the size to the given hSize or vSize. If the given size is unacceptable to the widget, the method should return an error. GlowWidget::preferredSize means to use the widget's preferred size. In this case, hSize/vSize will give a maximum allowed size. If the given size is not GlowWidget::unspecifiedSize, and it is too small for the preferred size to fit, the method should return an error. GlowWidget::expandPreferredSize means to use the widget's preferred size, but issues a request to expand the size to fill the given maximum allowed size hSize/vSize. The widget may choose whether or not to honor the request. Again, if the given maximum size is too small, the method should return an error. Error codes to return are GlowWidget::hAutoPackError for a problem with horizontal packing, GlowWidget::vAutoPackError for a problem with vertical packing, or GlowWidget::noAutoPackError for successful packing.Inherited methods
These methods are inherited from GlowComponent, but are used by GlowWidget and should not be overridden again.virtual void OnActivate(void)
virtual void OnDeactivate(void)
virtual void OnBeginPaint(void)
virtual void OnEndPaint(void)
|
|
Back to Table of contents |
The GLOW Toolkit