Torque3D Documentation / _generateds / PlatformWindow

PlatformWindow

Engine/source/windowManager/platformWindow.h

Abstract representation of a native OS window.

More...

Event Handlers

Various events that this window receives.

These are all subclasses of JournaledSignal, so you can subscribe to them and receive notifications per the documentation for that class.

AppEvent

appEvent 

MouseEvent

mouseEvent 

MouseWheelEvent

wheelEvent 

ButtonEvent

buttonEvent 

LinearEvent

linearEvent 

KeyEvent

keyEvent 

CharEvent

charEvent 

DisplayEvent

displayEvent 

ResizeEvent

resizeEvent 

IdleEvent

idleEvent

GFX State Management

GFXDevice *

getGFXDevice()

Return a pointer to the GFX device this window is bound to.

GFXWindowTarget *

getGFXTarget()

Return a pointer to this window's render target.

void

setVideoMode(const GFXVideoMode & mode)

Set the video mode for this window.

const GFXVideoMode &

getVideoMode()

Get our current video mode - if the window has been resized, it will reflect this.

bool

clearFullscreen()

If we're fullscreen, this function returns us to desktop mode.

bool

isFullscreen()

void

setFullscreen(const bool fullscreen)

Acquire the entire screen.

void

setBackground(bool val)

Set Idle State (Background)

bool

getBackground()

Get Idle State (Background)

void

setOffscreenRender(bool val)

Set whether this window is intended for offscreen rendering An offscreen window will never be shown or lose focus.

bool

getOffscreenRender()

Set whether this window is intended for offscreen rendering.

void

setDisplayWindow(bool val)

Set whether this window is should display as normal.

void

setFocus()

Set Focused State (Foreground)

Caption

bool

setCaption(const char * cap)

Set the window's caption.

const char *

getCaption()

Get the window's caption.

Visibility

Control how the window is displayed

void

minimize()

Minimize the window on screen.

void

maximize()

Maximize the window on screen.

void

hide()

Hide the window on screen.

void

show()

Show the window on screen.

void

close()

Destroy the window on screen.

void

restore()

Restore the window from a Maximized or Minimized state.

Window Bounds

void

setClientExtent(const Point2I newExtent)

The Client Rectangle or "Render Area" of a window is the area that is occupied by a given client that is rendering to that window.

const Point2I

getClientExtent()

Get the Client Area Extent (Resolution) of this window.

Public User Defined

void

setBounds(const RectI & newBounds)

The bounds of a Window are defined as the entire area occupied by that Window.

const RectI

getBounds()

Get the position and size (fullscreen windows are always at (0,0)).

Public User Defined

void

setPosition(const Point2I newPosition)

The Position of a window is always in relation to the very upper left of the window.

const Point2I

getPosition()

Get the position of this window.

void

centerWindow()

bool

setSize(const Point2I & newSize)

Resize the window to have a new size (but be in the same position).

Coordinate Space Conversion

Point2I

clientToScreen(const Point2I & point)

Convert the coordinate given in this window space to screen coordinates.

Point2I

screenToClient(const Point2I & point)

Convert the given screen coordinates to coordinates in this window space.

Windowed state

This is only really meaningful if the window is not fullscreen.

bool

isOpen()

Returns true if the window is instantiated in the OS.

bool

isVisible()

Returns true if the window is visible.

bool

isFocused()

Returns true if the window has input focus.

bool

isMinimized()

Returns true if the window is minimized.

bool

isMaximized()

Returns true if the window is maximized.

Keyboard Translation

When keyboard translation is on, keypress events that correspond to character input should be send as character input events rather than as raw key events except if shouldNotTranslate() returns true for a specific keypress event.

This enables the platform layer to perform platform-specific character input mapping.

void

setKeyboardTranslation(const bool enabled)

Set if relevant keypress events should be translated into character input events.

bool

getKeyboardTranslation()

Returns true if keyboard translation is enabled.

bool

shouldNotTranslate(U32 modifiers, U32 keyCode)

Returns true if the given keypress event should not be translated.

Window Cursor

Accessors to control a windows cursor shape and visibility

Get the CursorController that this window owns.

PlatformCursorController *

getCursorController()

void

setCursorPosition(S32 x, S32 y)

Set the cursor position based on logical coordinates from the upper-right corner.

void

getCursorPosition(Point2I & point)

Get the cursor position based on logical coordinates from the upper-right corner.

void

setCursorVisible(bool visible)

Set the cursor visibility on this window.

bool

isCursorVisible()

Get the cursor visibility on this window.

void

setMouseLocked(bool enable)

Lock the mouse to this window.

bool

isMouseLocked()

Is the mouse locked ?

bool

shouldLockMouse()

Should the mouse be locked at the next opportunity ?

Public Types

enum
WindowSystem {
  WindowSystem_Unknown = 0
  WindowSystem_Windows 
  WindowSystem_X11 
}

Public Friends

class

PlatformWindowManager

Protected Attributes

PlatformCursorController *

mCursorController

Cursor Controller for this Window.

bool

mDisplayWindow

This is set as part of the canvas being shown, and flags that the windows should render as normal from now on.

bool

mEnableAccelerators

When Torque GuiText input controls have focus they need to disable native OS keyboard accelerator translation.

bool

mEnableKeyboardTranslation

Are we enabling IME or other keyboard input translation services, or concerned about raw input?

bool

mIsBackground

Is Idle?

Point2I

mLockedSize

When the resize is locked, this will be used as both minimum and maximum window size.

Point2I

mMinimumSize

Minimum allowed size for this window.

bool

mOffscreenRender

Offscreen Render.

bool

mResizeLocked

When this is true, resizing is locked.

bool

mSuppressReset

Suppress device resets.

WindowId

mWindowId

An opaque ID used to resolve references to this Window.

WindowInputGenerator *

mWindowInputGenerator

Window Mouse/Key input Controller for this Window.

Protected Static Attributes

ScreenResChangeSignal

smScreenResChangeSignal

Protected Functions

PlatformWindow()

Protected constructor so that the win.
void

_setFullscreen(const bool fullScreen)

void

_setVideoMode(const GFXVideoMode & mode)

Public Functions
~PlatformWindow()

To get rid of a window, just delete it.
bool

getAcceleratorsEnabled()

Returns true if native OS keyboard accelerators are enabled.
WindowInputGenerator *

getInputGenerator()

Point2I

getLockedSize()

Returns the locked window size.
Point2I

getMinimumWindowSize()

Returns the current minimum window size for this window.
PlatformWindow *

getNextWindow()

void *

getPlatformDrawable()

Get the platform specific object needed to create or attach an accelerated graohics drawing context on or to the window Win32 D3D and OpenGL typically needs an HWND Mac Cocoa OpenGL typically needs an NSOpenGLView Mac Carbon OpenGL typically needs a WindowRef.
void *

getSystemWindow(const WindowSystem system)

WindowId

getWindowId()

Get the ID that uniquely identifies this window in the context of its window manager.
bool

isSizeLocked()

Returns true if the window size is locked.
void

lockSize(bool locked)

Locks/unlocks window resizing.
void

setAcceleratorsEnabled(const bool enabled)

Used to disable native OS keyboard accelerators.
void

setInputController(IProcessInput * controller)

Get the WindowController associated with this window.
void

setMinimumWindowSize(Point2I minSize)

Sets a minimum window size.
void

setSuppressReset(bool suppress)

Set the flag that determines whether to suppress a GFXDevice reset.
Public Static Functions
ScreenResChangeSignal &

getScreenResChangeSignal()

Detailed Description
Abstract representation of a native OS window.
Every windowing system has its own representations and conventions as regards the windows on-screen. In order to provide Torque with means for interfacing with multiple windows, tracking their state, etc. we provide this interface.
This interface also allows the app to access the render target for the window it represents, as well as control mode switches, get mode info, and so on.
see:
PlatformWindowManager
Event Handlers
Various events that this window receives.
These are all subclasses of JournaledSignal, so you can subscribe to them and receive notifications per the documentation for that class.
AppEvent appEvent 

MouseEvent mouseEvent 

MouseWheelEvent wheelEvent 

ButtonEvent buttonEvent 

LinearEvent linearEvent 

KeyEvent keyEvent 

CharEvent charEvent 

DisplayEvent displayEvent 

ResizeEvent resizeEvent 

IdleEvent idleEvent 

GFX State Management
getGFXDevice()

Return a pointer to the GFX device this window is bound to.
A GFX device may use many windows, but a window can only be used by a single GFX device.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
getGFXTarget()

Return a pointer to this window's render target.
By setting window targets from different windows, we can effect rendering to multiple windows from a single device.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
setVideoMode(const GFXVideoMode & mode)

Set the video mode for this window.
getVideoMode()

Get our current video mode - if the window has been resized, it will reflect this.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
clearFullscreen()

If we're fullscreen, this function returns us to desktop mode.
This will be either the last mode that we had that was not fullscreen, or the equivalent mode, windowed.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
isFullscreen()

return:
true if this window is fullscreen, false otherwise.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
setFullscreen(const bool fullscreen)

Acquire the entire screen.
setBackground(bool val)

Set Idle State (Background)
This is called to put a window into idle state, which causes it's rendering priority to be toned down to prefer performance
getBackground()

Get Idle State (Background)
This is called to poll the window as to it's idle state.
setOffscreenRender(bool val)

Set whether this window is intended for offscreen rendering An offscreen window will never be shown or lose focus.
getOffscreenRender()

Set whether this window is intended for offscreen rendering.
This is called to poll the window as to it's idle state.
setDisplayWindow(bool val)

Set whether this window is should display as normal.
setFocus()

Set Focused State (Foreground)
Claim OS input focus for this window
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
Caption
setCaption(const char * cap)

Set the window's caption.
Reimplemented by: PlatformWindowSDL, Win32Window, MacWindow
getCaption()

Get the window's caption.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
Visibility
Control how the window is displayed
minimize()

Minimize the window on screen.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
maximize()

Maximize the window on screen.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
hide()

Hide the window on screen.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
show()

Show the window on screen.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
close()

Destroy the window on screen.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
restore()

Restore the window from a Maximized or Minimized state.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
Window Bounds
setClientExtent(const Point2I newExtent)

The Client Rectangle or "Render Area" of a window is the area that is occupied by a given client that is rendering to that window.
This does not include the area occupied by a title-bar, menu, borders or other non-client elements. Set the Client Area Extent (Resolution) of this window
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
getClientExtent()

Get the Client Area Extent (Resolution) of this window.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
Public User Defined
setBounds(const RectI & newBounds)

The bounds of a Window are defined as the entire area occupied by that Window.
This includes the area needed for a title-bar, menu, borders, and other non-client elements. Resize the window to have some new bounds.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
getBounds()

Get the position and size (fullscreen windows are always at (0,0)).
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
Public User Defined
setPosition(const Point2I newPosition)

The Position of a window is always in relation to the very upper left of the window.
This means that saying setPosition at 0,0 will put the position of the window title-bar (if one exists) at 0,0 and the Client area will be offset from that point by the space needed for the Non-Client area. Set the position of this window
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
getPosition()

Get the position of this window.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
centerWindow()

Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
setSize(const Point2I & newSize)

Resize the window to have a new size (but be in the same position).
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
Coordinate Space Conversion
clientToScreen(const Point2I & point)

Convert the coordinate given in this window space to screen coordinates.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
screenToClient(const Point2I & point)

Convert the given screen coordinates to coordinates in this window space.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
Windowed state
This is only really meaningful if the window is not fullscreen.
isOpen()

Returns true if the window is instantiated in the OS.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
isVisible()

Returns true if the window is visible.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
isFocused()

Returns true if the window has input focus.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
isMinimized()

Returns true if the window is minimized.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
isMaximized()

Returns true if the window is maximized.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
Keyboard Translation
When keyboard translation is on, keypress events that correspond to character input should be send as character input events rather than as raw key events except if shouldNotTranslate() returns true for a specific keypress event.
This enables the platform layer to perform platform-specific character input mapping.
setKeyboardTranslation(const bool enabled)

Set if relevant keypress events should be translated into character input events.
Reimplemented by: PlatformWindowSDL
getKeyboardTranslation()

Returns true if keyboard translation is enabled.
shouldNotTranslate(U32 modifiers, U32 keyCode)

Returns true if the given keypress event should not be translated.
Window Cursor
Accessors to control a windows cursor shape and visibility
Get the CursorController that this window owns.
getCursorController()

setCursorPosition(S32 x, S32 y)

Set the cursor position based on logical coordinates from the upper-right corner.
Parameters:
x
The X position of the cursor
y
The Y position of the cursor
getCursorPosition(Point2I & point)

Get the cursor position based on logical coordinates from the upper-right corner.
Parameters:
point
A reference to a Point2I to store the coordinates
setCursorVisible(bool visible)

Set the cursor visibility on this window.
Parameters:
visible
Whether the cursor should be visible or not
isCursorVisible()

Get the cursor visibility on this window.
return:
true if the cursor is visible or false if it's hidden
setMouseLocked(bool enable)

Lock the mouse to this window.
When this is set, the mouse will always be returned to the center of the client area after every mouse event. The mouse will also be hidden while it is locked.
The mouse cannot be moved out of the bounds of the window, but the window may lose focus (for instance by an alt-tab or other event). While the window lacks focus, no mouse events will be reported.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
isMouseLocked()

Is the mouse locked ?
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
shouldLockMouse()

Should the mouse be locked at the next opportunity ?
This flag is set to the current state of the mouse lock on a window, to specify the preferred lock status of the mouse in a platform window.
This is important for situations where a call is made to setMouseLocked, and the window is not in a state that it can be cleanly locked. Take for example if it was called while the window is in the background, then it is not appropriate to lock the window, but rather the window should query this state at it's next opportunity and lock the mouse if requested.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
Public Types
WindowSystem

Enumerator
WindowSystem_Unknown = 0
WindowSystem_Windows 
WindowSystem_X11 
Public Friends
Protected Attributes
PlatformCursorController * mCursorController 

Cursor Controller for this Window.
bool mDisplayWindow 

This is set as part of the canvas being shown, and flags that the windows should render as normal from now on.
bool mEnableAccelerators 

When Torque GuiText input controls have focus they need to disable native OS keyboard accelerator translation.
bool mEnableKeyboardTranslation 

Are we enabling IME or other keyboard input translation services, or concerned about raw input?
bool mIsBackground 

Is Idle?
Point2I mLockedSize 

When the resize is locked, this will be used as both minimum and maximum window size.
Point2I mMinimumSize 

Minimum allowed size for this window.
When possible, we will communicate this to the OS.
bool mOffscreenRender 

Offscreen Render.
bool mResizeLocked 

When this is true, resizing is locked.
bool mSuppressReset 

Suppress device resets.
WindowId mWindowId 

An opaque ID used to resolve references to this Window.
WindowInputGenerator * mWindowInputGenerator 

Window Mouse/Key input Controller for this Window.
Protected Static Attributes
ScreenResChangeSignal smScreenResChangeSignal 

Protected Functions
PlatformWindow()

Protected constructor so that the win.
_setFullscreen(const bool fullScreen)

Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
_setVideoMode(const GFXVideoMode & mode)

Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
Public Functions
~PlatformWindow()

To get rid of a window, just delete it.
Make sure the GFXDevice is done with it first!
getAcceleratorsEnabled()

Returns true if native OS keyboard accelerators are enabled.
getInputGenerator()

getLockedSize()

Returns the locked window size.
getMinimumWindowSize()

Returns the current minimum window size for this window.
getNextWindow()

Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
getPlatformDrawable()

Get the platform specific object needed to create or attach an accelerated graohics drawing context on or to the window Win32 D3D and OpenGL typically needs an HWND Mac Cocoa OpenGL typically needs an NSOpenGLView Mac Carbon OpenGL typically needs a WindowRef.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
getSystemWindow(const WindowSystem system)

Reimplemented by: PlatformWindowSDL, Win32Window
getWindowId()

Get the ID that uniquely identifies this window in the context of its window manager.
Reimplemented by: MacWindow, PlatformWindowSDL, Win32Window
isSizeLocked()

Returns true if the window size is locked.
lockSize(bool locked)

Locks/unlocks window resizing.
setAcceleratorsEnabled(const bool enabled)

Used to disable native OS keyboard accelerators.
setInputController(IProcessInput * controller)

Get the WindowController associated with this window.
setMinimumWindowSize(Point2I minSize)

Sets a minimum window size.
We'll work with the OS to prevent user from sizing the window to less than this. Setting to (0,0) means user has complete freedom of resize.
setSuppressReset(bool suppress)

Set the flag that determines whether to suppress a GFXDevice reset.
Public Static Functions
getScreenResChangeSignal()