|
|
Back to Table of contents |
| General information |
type: class
inherits: GlowComponent
module: glowGlowSubwindow is the base class of all window and subwindow objects. It extends GlowComponent by adding the concepts of size and location on the screen, user and window manager events, and associated cursors and contextual menus. Objects of this class represent GLUT windows and subwindows.
A subwindow 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. The drawing coordinate system is the OpenGL coordinate system and is defined by calls to glViewport() and setting of the view frustum. Normally, x and y increase up and to the right in this coordinate system. Many of the methods on subwindows operate in the pixel coordinate system.
Subwindows are components and occupy places in a component hierarchy. Note that the component hierarchy also defines the GLUT subwindow hierarchy. A subwindow which is a descendant of another subwindow in the component hierarchy will also be contained within that subwindow in the window manager. Many methods of GlowSubwindow, such as those involving position of the subwindow, operate in the pixel coordinates of the parent window in the window hierarchy. This window can be found by calling ParentWindow().
All GLOW programs must make use of subwindows, or at least toplevel windows, which inherit from subwindows.
| Constants |
Special subwindow size
enum { parentWindowSize }
Use the width or height of the parent window.
| Methods |
Constructors and destructor
GlowSubwindow(GlowComponent* parent, const GlowSubwindowParams& params)
Creates a new GlowSubwindow with options specified by the given params, and adds it to parent's children. Also creates the corresponding GLUT subwindow.GlowSubwindow(GlowComponent* parent, int x, int y, int width, int height, Glow::BufferType mode, Glow::EventMask eventMask)
Creates a new GlowSubwindow with options specified by the given params, and adds it to parent's children. x and y denote the pixel location of the top left corner of the subwindow, in its parent window's coordinates. width and height specify the width and height in pixels. The constant GlowSubwindow::parentWindowSize may be used instead to specify the same size as the parent window. mode describes the type of frame buffer to use. eventMask specifies which events the subwindow wishes to receive when active. Use the event constants described in Glow for the event mask.GlowSubwindow(void)
Creates a new GlowSubwindow but does not initialize it. A subwindow created in this way may not be used until its Init() method is called.void Init(GlowComponent* parent, const GlowSubwindowParams& params)
Initializes the GlowSubwindow with options specified by the given params, and adds it to parent's children.void Init(GlowComponent* parent, int x, int y, int width, int height, Glow::BufferType mode, Glow::EventMask eventMask)
Initializes the GlowSubwindow with options specified by the given params, and adds it to parent's children. x and y denote the pixel location of the top left corner of the subwindow, in its parent window's coordinates. width and height specify the width and height in pixels. The constant GlowSubwindow::parentWindowSize may be used instead to specify the same size as the parent window. mode describes the type of frame buffer to use. eventMask specifies which events the subwindow wishes to receive when active. Use the event constants described in Glow for the event mask.virtual ~GlowSubwindow(void)
The destructor for GlowSubwindow removes the GLUT subwindow and recursively deletes its children in the hierarchy.Position and size information
Subwindows occupy a specific area of the screen. You can query this information using these methods.int PositionX(void) const
Returns the pixel position of the left edge of the subwindow, in the coordinates of ParentWindow().int PositionY(void) const
Returns the pixel position of the top edge of the subwindow, in the coordinates of ParentWindow().int GlobalPositionX(void) const
Returns the pixel position of the left edge of the subwindow, in screen coordinates.int GlobalPositionY(void) const
Returns the pixel position of the top edge of the subwindow, in screen coordinates.int Width(void) const
Returns the width of the subwindow.int Height(void) const
Returns the height of the subwindow.Setting position and size
You can set the position, size, stacking and visibility of a subwindow using these methods. Note that these methods do not typically affect the window's appearance immediately; instead, the task is queued and executed when control is given back to the GLOW system. (This is similar to the mechanism employed by GLUT.) This allows GLOW to combine operations and perform them simultaneously; i.e. the window will be redisplayed just once, and only one refresh and/or visibility event will be issued. However, the window state as reported by methods like Width() and Height() will reflect the change immediately.void Move(int x, int y)
Moves a subwindow so that its upper left corner lands at the given pixel coordinates in ParentWindow()'s coordinate system.void Reshape(int width, int height)
Resizes a subwindow.void Raise(void)
Brings the subwindow to the front in stacking order.void Lower(void)
Sends the subwindow to the back in stacking order.void Hide(void)
Hides the subwindow if it is visible. Note that this also hides any components and subwindows under this subwindow in the component hierarchy.void Show(void)
Shows the subwindow if it is invisible.Calls involving drawing
void Refresh(void)
Notifies GLOW that the subwindow needs to be redrawn. 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 subwindow will only be redrawn once, regardless of the number of requests in the queue. Again, this is the same mechanism employed by GLUT.void SetRefreshEnabled(bool enabled)
Sets whether refresh is currently enabled for this subwindow. 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 perform an operation, during a redraw callback, that would otherwise cause a second refresh request to be queued.bool IsRefreshEnabled(void) const
Returns whether refresh is currently enabled for this subwindow. If refresh is not enabled, calls to Refresh() will have no effect.void SetAutoSwapBuffersEnabled(bool enabled)
Sets whether automatic swapping of buffers is currently enabled for this subwindow. If this setting is false, GLOW will not automatically swap buffers after finishing drawing to a double-buffered subwindow. In that case, you'll need to do it manually by calling Glow::SwapBuffers(). Normally, this should be left set at true. Has no effect if the window is single buffered (but the default setting is still true).bool IsAutoSwapBuffersEnabled(void) const
Returns whether automatic swapping of buffers is currently enabled for this subwindow.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 subwindow, and the edges are all +/-1. Often useful durings drawing.Glow::BufferType GetBufferType(void) const
Returns the buffer type used by this subwindow. This is for your information only; you cannot change the buffer type once the window has been created.Calls involving menus and cursors
GlowMenu* GetMenu(Glow::MouseButton mouseButton) const
Returns a pointer to the menu attached to the specified mouse button. If no menu is attached to that button, returns 0. Use the button constants described in Glow to specify the button.void SetMenu(Glow::MouseButton mouseButton, GlowMenu* menu = 0)
Attaches the given menu to the specified mouse button. Pressing that button will pop up the menu as a contextual menu. Pass 0 for the menu to return the button to normal behavior. Use the button constants described in Glow to specify the button.void UnsetMenu(Glow::MouseButton mouseButton)
Returns the specified button to normal behavior (no menus). Identical to calling SetMenu() with menu set to 0. Use the button constants described in Glow to specify the button.int GetCursor(void) const
Returns the GLUT cursor associated with this subwindow.void SetCursor(int cursor)
Associates the given GLUT cursor with this subwindow.Examining and changing the event masks
The event masks denote which events the subwindow wants to receive. For best performance, you should set these masks to describe only those events in which your subwindow is interested. This will cut down on the number of GLUT callbacks that are registered for the subwindow. Normally, you specify these masks when you create the window, but you can change them at any time. The constants used are given in the class Glow.Glow::EventMask GetEventMask(void) const
Returns the event mask used when the subwindow is active.Glow::EventMask GetInactiveEventMask(void) const
Returns the event mask used when the subwindow is inactive.void SetEventMask(Glow::EventMask mask)
Sets the event mask to be used when the subwindow is active.void SetInactiveEventMask(Glow::EventMask mask)
Sets the event mask to be used when the subwindow is inactive.Interfacing with GLUT
These advanced routines are for occasions when you need to interface with the underlying GLUT window.int GlutWindowNum(void) const
Returns the GLUT window number associated with this window.void MakeCurGlutWindow(void)
Makes this window the current GLUT window.int GlutInfo(int whichInfo) const
Returns GLUT info about this window gotten using glutGet().Inherited methods
These methods are inherited from GlowComponent.void Close(void)
GlowComponent* Parent(void) const
GlowSubwindow* WhichWindow(void)
Note: For a subwindow, WhichWindow() returns this.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)
| Overrideable methods |
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 OnMouseDown(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 subwindow'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 OnMouseUp(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 subwindow'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 OnMenuDown(int x, int y)
Override this method to respond to a click using a button with an attached menu. When the method is called, x and y are set to the location of the click in the subwindow's pixel coordinates. Note that the menu is considered "in use" at the time of this callback, so you may not modify the menu or attempt to reassign a different menu to the button. The default method does nothing.virtual void OnMenuUp()
Override this method to respond to a release of the contextual menu. The default method does nothing.virtual void OnMouseMotion(int x, int y)
Override this method to respond to a mouse move inside a subwindow while no buttons are depressed. When the method is called, x and y are set to the location of the pointer in the subwindow's pixel coordinates. The default method does nothing.virtual void OnMouseDrag(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 subwindow's pixel coordinates. This location may be outside the subwindow if the button was initially pressed inside the subwindow but was dragged outside. The default method does nothing.virtual void OnMouseEnter(void)
Override this method to respond to the pointer entering the subwindow. Under some windowing systems, this also has the effect of the subwindow gaining keyboard focus. The default method does nothing. Note that this callback is window system dependent. It is guaranteed to work under the X window system, but not under all window systems.virtual void OnMouseExit(void)
Override this method to respond to the pointer exiting the subwindow. Under some windowing systems, this also has the effect of the subwindow losing keyboard focus. The default method does nothing. Note that this callback is window system dependent. It is guaranteed to work under the X window system, but not under all window systems.virtual void OnKeyboard(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 subwindow pixel coordinates at the time of the event. The default method does nothing.virtual void OnDirectMenuHit(const GlowMenuMessage& message)
Override this method to respond to a chosen menu item from a contextual menu attached to this subwindow. A GlowMenu object can be configured to notify its supporting subwindow of a choice made. If this configuration is made, the subwindow will receive this event. The default method does nothing.Window manager events
Subclasses should override these methods to respond to window manager events such as resizing. These events may be raised because the user explicitly manipulated a window through the window manager, or because a call to one of the window manipulation methods such as Reshape() caused a change in the window's state.virtual void OnReshape(int width, int height)
Override this method to respond to a window reshape. Normally, you should respond by adjusting the glViewPort for the window, or otherwise dealing with a new window size. The default method does nothing.virtual void OnInvisible(void)
Override this method to respond to a window being made invisible, often because it has been hidden, iconified, or moved completely under another window. It is often a good idea to set a flag indicating that the contents do not need to be drawn. The default method does nothing.virtual void OnVisible(void)
Override this method to respond to a window being made visible, often because it has been shown, deiconified, or moved out from under another window. It is often a good idea to clear any flag set during OnInvisible(). The default method does nothing.Inherited methods
These overrideable methods are inherited from GlowComponent. One has changed default behaviorvirtual bool OnBeginPaint(void)
For a subwindow, the default method clears the subwindow to black.virtual void OnEndPaint(void)
virtual void OnActivate(void)
virtual void OnDeactivate(void)
|
|
Back to Table of contents |
The GLOW Toolkit