Torque Game Engine Documentation
TGE Version 1.5.2

GuiCanvas Class Reference

#include <guiCanvas.h>

Inheritance diagram for GuiCanvas:

[legend]

Detailed Description

A canvas on which rendering occurs.

What a GUICanvas Can Contain...

Content Control

A content control is the top level GuiControl for a screen. This GuiControl will be the parent control for all other GuiControls on that particular screen.

Dialogs

A dialog is essentially another screen, only it gets overlaid on top of the current content control, and all input goes to the dialog. This is most akin to the "Open File" dialog box found in most operating systems. When you choose to open a file, and the "Open File" dialog pops up, you can no longer send input to the application, and must complete or cancel the open file request. Torque keeps track of layers of dialogs. The dialog with the highest layer is on top and will get all the input, unless the dialog is modeless, which is a profile option.

See also:: GuiControlProfile

Dirty Rectangles

The GuiCanvas is based on dirty regions.

Every frame the canvas paints only the areas of the canvas that are 'dirty' or need updating. In most cases, this only is the area under the mouse cursor. This is why if you look in guiCanvas.cc the call to glClear is commented out. If you want a really good idea of what exactly dirty regions are and how they work, un-comment that glClear line in the renderFrame method of guiCanvas.cc

What you will see is a black screen, except in the dirty regions, where the screen will be painted normally. If you are making an animated GuiControl you need to add your control to the dirty areas of the canvas.

Mouse Input

SimObjectPtr< GuiControl > mMouseCapturedControl

All mouse events will go to this ctrl only.

SimObjectPtr< GuiControl > mMouseControl

the control the mouse was last seen in unless some other one captured it

bool mMouseControlClicked

whether the current ctrl has been clicked - used by helpctrl

U32 mPrevMouseTime

this determines how long the mouse has been in the same control

U32 mNextMouseTime

used for onMouseRepeat()

U32 mInitialMouseDelay

also used for onMouseRepeat()

bool mMouseButtonDown

Flag to determine if the button is depressed.

bool mMouseRightButtonDown

bool to determine if the right button is depressed

bool mMouseMiddleButtonDown

Middle button flag.

GuiEvent mLastEvent

U8 mLastMouseClickCount

S32 mLastMouseDownTime

bool mLeftMouseLast

bool mMiddleMouseLast

virtual void findMouseControl (const GuiEvent &event)

virtual void refreshMouseControl ()

Public Member Functions

DECLARE_CONOBJECT (GuiCanvas)

GuiCanvas ()

virtual ~GuiCanvas ()

virtual void setRenderFront (bool front)

This turns on/off front-buffer rendering.

Point2I getCursorExtent ()

used by the tooltip resource

Rendering methods

virtual void renderFrame (bool preRenderOnly, bool bufferSwap=true)

Repaints the dirty regions of the canvas.

virtual void paint ()

Repaints the entire canvas by calling resetUpdateRegions() and then renderFrame().

virtual void addUpdateRegion (Point2I pos, Point2I ext)

Adds a dirty area to the canvas so it will be updated on the next frame.

virtual void resetUpdateRegions ()

Resets the update regions so that the next call to renderFrame will repaint the whole canvas.

void maintainSizing ()

Resizes the content control to match the canvas size.

virtual void buildUpdateUnion (RectI *updateUnion)

This builds a rectangle which encompasses all of the dirty regions to be repainted.

virtual void swapBuffers ()

This will swap the buffers at the end of renderFrame.

Canvas Content Management

virtual void setContentControl (GuiControl *gui)

This sets the content control to something different.

virtual GuiControl * getContentControl ()

Returns the content control.

virtual void pushDialogControl (GuiControl *gui, S32 layer=0)

Adds a dialog control onto the stack of dialogs.

virtual void popDialogControl (S32 layer=0)

Removes a specific layer of dialogs.

virtual void popDialogControl (GuiControl *gui)

Removes a specific dialog control.

Cursor commands

A cursor can be on, but not be shown.
If a cursor is not on, than it does not process input.

virtual void setCursor (GuiCursor *cursor)

Sets the cursor for the canvas.

virtual bool isCursorON ()

Returns true if the cursor is on.

virtual void setCursorON (bool onOff)

Turns the cursor on or off.

virtual void setCursorPos (const Point2I &pt)

Sets the position of the cursor.

virtual Point2I getCursorPos ()

Returns the point, in screenspace, at which the cursor is located.

virtual void showCursor (bool state)

Enable/disable rendering of the cursor.

virtual bool isCursorShown ()

Returns true if the cursor is being rendered.

Input Processing

virtual bool processInputEvent (const InputEvent *event)

Processes an input event.

virtual void processMouseMoveEvent (const MouseMoveEvent *event)

Processes a mouse movement event.

Mouse Methods

virtual void mouseLock (GuiControl *lockingControl)

When a control gets the mouse lock this means that that control gets ALL mouse input and no other control recieves any input.

virtual void mouseUnlock (GuiControl *lockingControl)

Unlocks the mouse from a control.

virtual GuiControl * getMouseControl ()

Returns the control which the mouse is over.

virtual GuiControl * getMouseLockedControl ()

Returns the control which the mouse is locked to if any.

virtual bool mouseButtonDown (void)

Returns true if the left mouse button is down.

virtual bool mouseRightButtonDown (void)

Returns true if the right mouse button is down.

virtual void checkLockMouseMove (const GuiEvent &event)

Mouse input methods

These events process the events before passing them down to the controls they effect.
This allows for things such as the input locking and such.
Each of these methods corosponds to the action in it's method name and processes the GuiEvent passd as a parameter

virtual void rootMouseUp (const GuiEvent &event)

virtual void rootMouseDown (const GuiEvent &event)

virtual void rootMouseMove (const GuiEvent &event)

virtual void rootMouseDragged (const GuiEvent &event)

virtual void rootRightMouseDown (const GuiEvent &event)

virtual void rootRightMouseUp (const GuiEvent &event)

virtual void rootRightMouseDragged (const GuiEvent &event)

virtual void rootMiddleMouseDown (const GuiEvent &event)

virtual void rootMiddleMouseUp (const GuiEvent &event)

virtual void rootMiddleMouseDragged (const GuiEvent &event)

virtual void rootMouseWheelUp (const GuiEvent &event)

virtual void rootMouseWheelDown (const GuiEvent &event)

Keyboard input methods

First responders
A first responder is a the GuiControl which responds first to input events before passing them off for further processing.

virtual bool tabNext (void)

Moves the first responder to the next tabable controle.

virtual bool tabPrev (void)

Moves the first responder to the previous tabable control.

virtual void addAcceleratorKey (GuiControl *ctrl, U32 index, U32 keyCode, U32 modifier)

Setups a keyboard accelerator which maps to a GuiControl.

virtual void setFirstResponder (GuiControl *firstResponder)

Sets the first responder.

Protected Types

typedef GuiControl Parent

typedef SimObject Grandparent

Protected Attributes

Rendering

RectI mOldUpdateRects [2]

RectI mCurUpdateRect

F32 rLastFrameTime

Cursor Properties

F32 mPixelsPerMickey

This is the scale factor which relates mouse movement in pixels (one unit of mouse movement is a mickey) to units in the GUI.

bool cursorON

bool mShowCursor

bool mRenderFront

Point2F cursorPt

Point2I lastCursorPt

GuiCursor * defaultCursor

GuiCursor * lastCursor

bool lastCursorON

Keyboard Input

GuiControl * keyboardControl

All keyboard events will go to this ctrl first.

U32 nextKeyTime

Vector< AccKeyMap > mAcceleratorMap

U32 hoverControlStart

GuiControl * hoverControl

Point2I hoverPosition

bool hoverPositionSet

U32 hoverLeftControlTime

Data Structures

struct AccKeyMap

Accelerator key map. More...

Member Typedef Documentation

typedef GuiControl GuiCanvas::Parent [protected]

Reimplemented from GuiControl.

Reimplemented in GuiEffectCanvas.

typedef SimObject GuiCanvas::Grandparent [protected]

Constructor & Destructor Documentation

GuiCanvas::GuiCanvas ( )

virtual GuiCanvas::~GuiCanvas ( ) [virtual]

Member Function Documentation

virtual void GuiCanvas::findMouseControl ( const GuiEvent & event ) [protected, virtual]

virtual void GuiCanvas::refreshMouseControl ( ) [protected, virtual]

GuiCanvas::DECLARE_CONOBJECT ( GuiCanvas )

virtual void GuiCanvas::renderFrame	(	bool	preRenderOnly,
		bool	bufferSwap = `true`
	)			`[virtual]`

Repaints the dirty regions of the canvas.

Parameters:

	preRenderOnly	If set to true, only the onPreRender methods of all the GuiControls will be called
	bufferSwap	If set to true, it will swap buffers at the end. This is to support canvas-subclassing.

Reimplemented in GuiEffectCanvas.

virtual void GuiCanvas::paint ( ) [virtual]

Repaints the entire canvas by calling resetUpdateRegions() and then renderFrame().

virtual void GuiCanvas::addUpdateRegion	(	Point2I	pos,
		Point2I	ext
	)			`[virtual]`

Adds a dirty area to the canvas so it will be updated on the next frame.

Parameters:

	pos	Screen-coordinates of the upper-left hand corner of the dirty area
	ext	Width/height of the dirty area

virtual void GuiCanvas::resetUpdateRegions ( ) [virtual]

Resets the update regions so that the next call to renderFrame will repaint the whole canvas.

void GuiCanvas::maintainSizing ( )

Resizes the content control to match the canvas size.

virtual void GuiCanvas::buildUpdateUnion ( RectI * updateUnion ) [virtual]

This builds a rectangle which encompasses all of the dirty regions to be repainted.

Parameters:

updateUnion

(out) Rectangle which surrounds all dirty areas

virtual void GuiCanvas::swapBuffers ( ) [virtual]

This will swap the buffers at the end of renderFrame.

It was added for canvas sub-classes in case they wanted to do some custom code before the buffer flip occured.

virtual void GuiCanvas::setContentControl ( GuiControl * gui ) [virtual]

This sets the content control to something different.

Parameters:

gui

New content control

Reimplemented in GuiEffectCanvas.

virtual GuiControl* GuiCanvas::getContentControl ( ) [virtual]

Returns the content control.

virtual void GuiCanvas::pushDialogControl	(	GuiControl *	gui,
		S32	layer = `0`
	)			`[virtual]`

Adds a dialog control onto the stack of dialogs.

Parameters:

	gui	Dialog to add
	layer	Layer to put dialog on

virtual void GuiCanvas::popDialogControl ( S32 layer = 0 ) [virtual]

Removes a specific layer of dialogs.

Parameters:

layer

Layer to pop off from

virtual void GuiCanvas::popDialogControl ( GuiControl * gui ) [virtual]

Removes a specific dialog control.

Parameters:

gui

Dialog to remove from the dialog stack

virtual void GuiCanvas::setRenderFront ( bool front ) [inline, virtual]

This turns on/off front-buffer rendering.

Parameters:

front

True if all rendering should be done to the front buffer

virtual void GuiCanvas::setCursor ( GuiCursor * cursor ) [virtual]

Sets the cursor for the canvas.

Parameters:

cursor

New cursor to use.

virtual bool GuiCanvas::isCursorON ( ) [inline, virtual]

Returns true if the cursor is on.

virtual void GuiCanvas::setCursorON ( bool onOff ) [virtual]

Turns the cursor on or off.

Parameters:

onOff

True if the cursor should be on.

virtual void GuiCanvas::setCursorPos ( const Point2I & pt ) [virtual]

Sets the position of the cursor.

Parameters:

Point, in screenspace for the cursor

virtual Point2I GuiCanvas::getCursorPos ( ) [inline, virtual]

Returns the point, in screenspace, at which the cursor is located.

virtual void GuiCanvas::showCursor ( bool state ) [inline, virtual]

Enable/disable rendering of the cursor.

Parameters:

state

True if we should render cursor

virtual bool GuiCanvas::isCursorShown ( ) [inline, virtual]

Returns true if the cursor is being rendered.

Point2I GuiCanvas::getCursorExtent ( ) [inline]

used by the tooltip resource

virtual bool GuiCanvas::processInputEvent ( const InputEvent * event ) [virtual]

Processes an input event.

See also:: InputEvent

Parameters:

event

Input event to process

virtual void GuiCanvas::processMouseMoveEvent ( const MouseMoveEvent * event ) [virtual]

Processes a mouse movement event.

See also:: MouseMoveEvent

Parameters:

event

Mouse move event to process

virtual void GuiCanvas::mouseLock ( GuiControl * lockingControl ) [virtual]

When a control gets the mouse lock this means that that control gets ALL mouse input and no other control recieves any input.

Parameters:

lockingControl

Control to lock mouse to

Reimplemented from GuiControl.

virtual void GuiCanvas::mouseUnlock ( GuiControl * lockingControl ) [virtual]

Unlocks the mouse from a control.

Parameters:

lockingControl

Control to unlock from

virtual GuiControl* GuiCanvas::getMouseControl ( ) [inline, virtual]

Returns the control which the mouse is over.

virtual GuiControl* GuiCanvas::getMouseLockedControl ( ) [inline, virtual]

Returns the control which the mouse is locked to if any.

virtual bool GuiCanvas::mouseButtonDown ( void ) [inline, virtual]

Returns true if the left mouse button is down.

virtual bool GuiCanvas::mouseRightButtonDown ( void ) [inline, virtual]

Returns true if the right mouse button is down.

virtual void GuiCanvas::checkLockMouseMove ( const GuiEvent & event ) [virtual]

virtual void GuiCanvas::rootMouseUp ( const GuiEvent & event ) [virtual]

virtual void GuiCanvas::rootMouseDown ( const GuiEvent & event ) [virtual]

virtual void GuiCanvas::rootMouseMove ( const GuiEvent & event ) [virtual]

virtual void GuiCanvas::rootMouseDragged ( const GuiEvent & event ) [virtual]

virtual void GuiCanvas::rootRightMouseDown ( const GuiEvent & event ) [virtual]

virtual void GuiCanvas::rootRightMouseUp ( const GuiEvent & event ) [virtual]

virtual void GuiCanvas::rootRightMouseDragged ( const GuiEvent & event ) [virtual]

virtual void GuiCanvas::rootMiddleMouseDown ( const GuiEvent & event ) [virtual]

virtual void GuiCanvas::rootMiddleMouseUp ( const GuiEvent & event ) [virtual]

virtual void GuiCanvas::rootMiddleMouseDragged ( const GuiEvent & event ) [virtual]

virtual void GuiCanvas::rootMouseWheelUp ( const GuiEvent & event ) [virtual]

virtual void GuiCanvas::rootMouseWheelDown ( const GuiEvent & event ) [virtual]

virtual bool GuiCanvas::tabNext ( void ) [virtual]

Moves the first responder to the next tabable controle.

virtual bool GuiCanvas::tabPrev ( void ) [virtual]

Moves the first responder to the previous tabable control.

virtual void GuiCanvas::addAcceleratorKey	(	GuiControl *	ctrl,
		U32	index,
		U32	keyCode,
		U32	modifier
	)			`[virtual]`

Setups a keyboard accelerator which maps to a GuiControl.

Parameters:

	ctrl	GuiControl to map to.
	index
	keyCode	Key code.
	modifier	Shift, ctrl, etc.

virtual void GuiCanvas::setFirstResponder ( GuiControl * firstResponder ) [virtual]

Sets the first responder.

Parameters:

firstResponder

Control to designate as first responder

Reimplemented from GuiControl.

Field Documentation

RectI GuiCanvas::mOldUpdateRects[2] [protected]

RectI GuiCanvas::mCurUpdateRect [protected]

F32 GuiCanvas::rLastFrameTime [protected]

F32 GuiCanvas::mPixelsPerMickey [protected]

This is the scale factor which relates mouse movement in pixels (one unit of mouse movement is a mickey) to units in the GUI.

bool GuiCanvas::cursorON [protected]

bool GuiCanvas::mShowCursor [protected]

bool GuiCanvas::mRenderFront [protected]

Point2F GuiCanvas::cursorPt [protected]

Point2I GuiCanvas::lastCursorPt [protected]

GuiCursor* GuiCanvas::defaultCursor [protected]

GuiCursor* GuiCanvas::lastCursor [protected]

bool GuiCanvas::lastCursorON [protected]

SimObjectPtr<GuiControl> GuiCanvas::mMouseCapturedControl [protected]

All mouse events will go to this ctrl only.

SimObjectPtr<GuiControl> GuiCanvas::mMouseControl [protected]

the control the mouse was last seen in unless some other one captured it

bool GuiCanvas::mMouseControlClicked [protected]

whether the current ctrl has been clicked - used by helpctrl

U32 GuiCanvas::mPrevMouseTime [protected]

this determines how long the mouse has been in the same control

U32 GuiCanvas::mNextMouseTime [protected]

used for onMouseRepeat()

U32 GuiCanvas::mInitialMouseDelay [protected]

also used for onMouseRepeat()

bool GuiCanvas::mMouseButtonDown [protected]

Flag to determine if the button is depressed.

bool GuiCanvas::mMouseRightButtonDown [protected]

bool to determine if the right button is depressed

bool GuiCanvas::mMouseMiddleButtonDown [protected]

Middle button flag.

GuiEvent GuiCanvas::mLastEvent [protected]

U8 GuiCanvas::mLastMouseClickCount [protected]

S32 GuiCanvas::mLastMouseDownTime [protected]

bool GuiCanvas::mLeftMouseLast [protected]

bool GuiCanvas::mMiddleMouseLast [protected]

GuiControl* GuiCanvas::keyboardControl [protected]

All keyboard events will go to this ctrl first.

U32 GuiCanvas::nextKeyTime [protected]

Vector<AccKeyMap> GuiCanvas::mAcceleratorMap [protected]

U32 GuiCanvas::hoverControlStart [protected]

GuiControl* GuiCanvas::hoverControl [protected]

Point2I GuiCanvas::hoverPosition [protected]

bool GuiCanvas::hoverPositionSet [protected]

U32 GuiCanvas::hoverLeftControlTime [protected]