OpenGUI::Screen Class Reference

#include <OpenGUI_Screen.h>

Inheritance diagram for OpenGUI::Screen:

Detailed Description

Every GUI is built into a screen.

Screens are the base of every GUI display, and it's often best to think of them as a sort of virtual monitor. They contain widgets and windows, and they accept input on an individual basis. They draw their output to Viewport objects, which are created and managed by the Renderer implementation. The active Viewport for a Screen can be set via the setViewport() function.

Each Screen has it's own cursor, which can be shown or hidden and enabled or disabled individually from all other screens. While the cursor is disabled it is not rendered, all cursor based input injections are skipped (no state updates, no input consumption), and the cursor is considered non-existent so it will not interact with the GUI in any way.

Public Member Functions

Widget * getWidgetAt (const FVector2 &position, bool recursive=false)

Returns a pointer to the topmost Widget at the given location, or 0 (NULL) if no match found.

void getWidgetsAt (const FVector2 &position, WidgetPtrList &outList, bool recursive=false)

Returns a list of all widgets at the given location, sorted by depth from top to bottom.

Widget * getPath (const String &path) const

Returns a pointer to the widget at the given path, 0 if no widget is found.

const String & getName () const

returns the name of this Screen

const FVector2 & getSize () const

returns the size/resolution of this Screen

void setSize (const FVector2 &newSize)

changes the size/resolution of this Screen

const FVector2 & getPPU () const

returns the PPU (pixels per unit) of this Screen

const FVector2 & getUPI () const

Returns the UPI (units per inch) of this Screen.

void setUPI (const FVector2 &newUPI)

Changes the UPI (units per inch) of this Screen.

void update ()

renders this Screen to it's Viewport, if possible

bool isAutoUpdating () const

returns true if this screen is automatically updated

void setAutoUpdating (bool autoUpdate=true)

sets if this screen is automatically updated

void setViewport (Viewport *viewport)

bind this Screen to draw to the given viewport

Viewport * getViewport () const

returns the Viewport this Screen renders into

void invalidateAll ()

Invalidates all contained Widgets, causing a complete redraw on next update().

float statsGetUpdateTime ()

Returns the time spent performing Screen::update(), averaged over the past 5 frames.

void statsResetUpdateTime ()

Resets the UpdateTime statistic.

void setActive (bool active)

Sets this screen active or disabled according to the given active flag.

bool isActive ()

returns the active status for this Screen

virtual ObjectAccessorList * getAccessors ()

returns this object's ObjectAccessorList head

virtual unsigned int getObjectType () const

Returns an integer identifying the type of object.

Cursor Functions (Input Injection & Utility)

bool injectCursorMovement (float x_rel, float y_rel)

Injects cursor movement by providing the relative movement from the last position.

bool injectCursorPosition (float x_pos, float y_pos)

Injects cursor movement by providing the absolute cursor position on the screen.

bool injectCursorPosition_Percent (float x_perc, float y_perc)

Injects cursor movement by providing the absolute cursor position as a percentage of the screen.

bool injectCursorPress ()

Injects cursor press at the last known cursor position.

bool injectCursorRelease ()

Injects cursor release at the last known cursor position.

bool injectCursorPress_State (bool pressed)

Injects cursor press/release at the last known cursor position using built in state logic.

const FVector2 & getCursorPos () const

gets the current cursor position

FVector2 getCursorPos_Percent () const

gets the current cursor position as a percentage of the screen

void setCursor (CursorPtr cursor)

sets the default Cursor for this Screen.

void enableCursor ()

Enables the cursor if it is currently disabled.

void disableCursor ()

Disables the cursor if it is currently enabled.

bool cursorEnabled ()

Returns true if the cursor is enabled, false otherwise.

void showCursor ()

Shows the cursor if it is currently hidden.

void hideCursor ()

Hides the cursor if it is currently shown.

bool cursorVisible ()

Returns true if the cursor is shown, false if it is hidden.

Widget * getCursorFocusedWidget ()

Returns a pointer to the current Widget that has cursor focus, or 0 if none.

Keyboard Input Injection

bool injectCharacter (char character)

Injects the given character as text input from the user.

Widget * getKeyFocusedWidget ()

Returns a pointer to the current Widget that has key focus, or 0 if none.

Time Functions

bool isAutoTiming () const

Returns true if this Screen gets its timing from System.

void setAutoTiming (bool doAutoTime=true)

Sets if this Screen should receive its timing from System.

void injectTime (unsigned int milliseconds)

Injects time into this Screen, in milliseconds ( 1/1000th of a second ).

void injectTime (float seconds)

Injects time into this Screen as a float value of a whole second.

Public Attributes

WidgetCollection Children

The public collection of child widgets.

Member Function Documentation

bool OpenGUI::Screen::cursorEnabled ( )

Returns true if the cursor is enabled, false otherwise.

bool OpenGUI::Screen::cursorVisible ( )

Returns true if the cursor is shown, false if it is hidden.

void OpenGUI::Screen::disableCursor ( )

Disables the cursor if it is currently enabled.
Multiple calls have no ill effect.

void OpenGUI::Screen::enableCursor ( )

Enables the cursor if it is currently disabled.
Cursor starts disabled, so you will need to call this to enable it before you can realistically use it. Multiple calls have no ill effect.
Note:
You cannot enable a visible cursor until the default cursor for the Screen has been set. If no default cursor is set when this is called, the cursor will be immediately hidden via hideCursor().

ObjectAccessorList * OpenGUI::Screen::getAccessors ( ) [virtual]

returns this object's ObjectAccessorList head

Reimplemented from OpenGUI::Object.

Widget * OpenGUI::Screen::getCursorFocusedWidget ( )

Returns a pointer to the current Widget that has cursor focus, or 0 if none.

const FVector2 & OpenGUI::Screen::getCursorPos ( ) const

gets the current cursor position

FVector2 OpenGUI::Screen::getCursorPos_Percent ( ) const

gets the current cursor position as a percentage of the screen

Widget * OpenGUI::Screen::getKeyFocusedWidget ( )

Returns a pointer to the current Widget that has key focus, or 0 if none.

const String & OpenGUI::Screen::getName ( ) const

returns the name of this Screen

unsigned int OpenGUI::Screen::getObjectType ( ) const [virtual]

Returns an integer identifying the type of object.

See also:
Object_Type

Implements OpenGUI::Object.

Widget * OpenGUI::Screen::getPath ( const String & path ) const

Returns a pointer to the widget at the given path, 0 if no widget is found.

See also:
Widget::getPath() for a more in-depth explanation of paths

const FVector2& OpenGUI::Screen::getPPU ( ) const [inline]

returns the PPU (pixels per unit) of this Screen
PPU is different from DPI. PPU is the number of pixels per Screen size unit, and is calculated from the Screen size divided by the pixel size of the Screen's render target.
Basically: PPU_Axis = ScreenSize_Axis / TargetSize_Axis
(where Axis is uniformly replaced with the X and Y axis)

const FVector2 & OpenGUI::Screen::getSize ( ) const

returns the size/resolution of this Screen

const FVector2& OpenGUI::Screen::getUPI ( ) const [inline]

Returns the UPI (units per inch) of this Screen.

See also:
setUPI()

Viewport * OpenGUI::Screen::getViewport ( ) const

returns the Viewport this Screen renders into

Widget * OpenGUI::Screen::getWidgetAt ( const FVector2 & position,

bool recursive = false

)

Returns a pointer to the topmost Widget at the given location, or 0 (NULL) if no match found.

void OpenGUI::Screen::getWidgetsAt ( const FVector2 & position,

WidgetPtrList & outList,

bool recursive = false

)

Returns a list of all widgets at the given location, sorted by depth from top to bottom.

void OpenGUI::Screen::hideCursor ( )

Hides the cursor if it is currently shown.
Multiple calls have no ill effect.

bool OpenGUI::Screen::injectCharacter ( char character )

Injects the given character as text input from the user.

Note:
this is a temporary implementation that will be replaced with a more useful system

bool OpenGUI::Screen::injectCursorMovement ( float x_rel,

float y_rel

)

Injects cursor movement by providing the relative movement from the last position.
Positive values causes right or downward movement depending on axis. Values of 0.0f on both axis are ignored. If the cursor is disabled, this will always return false.

bool OpenGUI::Screen::injectCursorPosition ( float x_pos,

float y_pos

)

Injects cursor movement by providing the absolute cursor position on the screen.
0.0 x 0.0 is the upper left corner of the screen. If the cursor is disabled, this will always return false. If the given position is the same as the previous position, this will return false with no event generated.

bool OpenGUI::Screen::injectCursorPosition_Percent ( float x_perc,

float y_perc

)

Injects cursor movement by providing the absolute cursor position as a percentage of the screen.
0.0 x 0.0 is the upper left corner of the screen, 1.0 x 1.0 is the lower right of the screen. If the cursor is disabled, this will always return false.

bool OpenGUI::Screen::injectCursorPress ( )

Injects cursor press at the last known cursor position.
If the cursor is disabled, this will always return false.

bool OpenGUI::Screen::injectCursorPress_State ( bool pressed )

Injects cursor press/release at the last known cursor position using built in state logic.
If the cursor is disabled, this will always return false.

bool OpenGUI::Screen::injectCursorRelease ( )

Injects cursor release at the last known cursor position.
If the cursor is disabled, this will always return false.

void OpenGUI::Screen::injectTime ( float seconds )

Injects time into this Screen as a float value of a whole second.

void OpenGUI::Screen::injectTime ( unsigned int milliseconds )

Injects time into this Screen, in milliseconds ( 1/1000th of a second ).

void OpenGUI::Screen::invalidateAll ( )

Invalidates all contained Widgets, causing a complete redraw on next update().

bool OpenGUI::Screen::isActive ( )

returns the active status for this Screen

See also:
setActive()

bool OpenGUI::Screen::isAutoTiming ( ) const [inline]

Returns true if this Screen gets its timing from System.

bool OpenGUI::Screen::isAutoUpdating ( ) const [inline]

returns true if this screen is automatically updated

void OpenGUI::Screen::setActive ( bool active )

Sets this screen active or disabled according to the given active flag.
A Screen cannot be truly active unless it is both set active, and has a valid Viewport assigned. All Screens are created with the "active" flag set initially to true regardless of if they are created already attached to a Viewport or not. This flag can be freely toggled regardless of the presence or lack of a Viewport, but the Screen will never evaluate as "renderable" unless it is both marked active and has an assigned Viewport.

void OpenGUI::Screen::setAutoTiming ( bool doAutoTime = true ) [inline]

Sets if this Screen should receive its timing from System.
All new Screens are auto timing by default, and must be individually set not to be if that is not desired. All time injections from System occur directly before Screen::update() would be called.

void OpenGUI::Screen::setAutoUpdating ( bool autoUpdate = true ) [inline]

sets if this screen is automatically updated
All new Screens are auto updating by default, and must be individually set not to be if that is not desired.

void OpenGUI::Screen::setCursor ( CursorPtr cursor )

sets the default Cursor for this Screen.
If you assign a null pointer as the new cursor and the cursor is enabled, this will cause the cursor to become hidden automatically.

void OpenGUI::Screen::setSize ( const FVector2 & newSize )

changes the size/resolution of this Screen

void OpenGUI::Screen::setUPI ( const FVector2 & newUPI )

Changes the UPI (units per inch) of this Screen.
UPI is used to determine font scaling. The default of 96x96 is a copy of the standard used under common operating systems. What this does is cause your Screen to behave much like your desktop display when doing common tasks like word processing, etc. This means that unless you change the UPI of your Screen, you should really use a Screen resolution that is common, such as 800x600 or similar. Smaller Screen resolutions makes fonts look bigger and larger Screen resolutions make them look smaller, just like your computer already does.
This system (combined with getPPU) allows us to render Screens with consistent font sizes and consistent Widget sizes (basically uniformly scaling everything), while still preserving pixel alignment where requested.

void OpenGUI::Screen::setViewport ( Viewport * viewport )

bind this Screen to draw to the given viewport

void OpenGUI::Screen::showCursor ( )

Shows the cursor if it is currently hidden.
Cursor starts shown, so you do not need to call this unless you've previously hidden the cursor. Multiple calls have no ill effect.
Note:
As stated in enableCursor(), you cannot show the cursor until a default cursor for the Screen has been set. You can toggle cursor visibility freely while the cursor is disabled, but attempting to force showing of the cursor while it is enabled and there is no default will throw an exception.

float OpenGUI::Screen::statsGetUpdateTime ( )

Returns the time spent performing Screen::update(), averaged over the past 5 frames.

void OpenGUI::Screen::statsResetUpdateTime ( )

Resets the UpdateTime statistic.

void OpenGUI::Screen::update ( )

renders this Screen to it's Viewport, if possible
If the Screen is not marked active, or does not have a valid Viewport assigned, this function will return immediately with no error.

Member Data Documentation

WidgetCollection OpenGUI::Screen::Children

The public collection of child widgets.

The documentation for this class was generated from the following files:

OpenGUI_Screen.h
OpenGUI_Screen.cpp


Public Member Functions
Widget *	getWidgetAt (const FVector2 &position, bool recursive=false)
	Returns a pointer to the topmost Widget at the given location, or 0 (NULL) if no match found.
void	getWidgetsAt (const FVector2 &position, WidgetPtrList &outList, bool recursive=false)
	Returns a list of all widgets at the given location, sorted by depth from top to bottom.
Widget *	getPath (const String &path) const
	Returns a pointer to the widget at the given path, 0 if no widget is found.
const String &	getName () const
	returns the name of this Screen
const FVector2 &	getSize () const
	returns the size/resolution of this Screen
void	setSize (const FVector2 &newSize)
	changes the size/resolution of this Screen
const FVector2 &	getPPU () const
	returns the PPU (pixels per unit) of this Screen
const FVector2 &	getUPI () const
	Returns the UPI (units per inch) of this Screen.
void	setUPI (const FVector2 &newUPI)
	Changes the UPI (units per inch) of this Screen.
void	update ()
	renders this Screen to it's Viewport, if possible
bool	isAutoUpdating () const
	returns true if this screen is automatically updated
void	setAutoUpdating (bool autoUpdate=true)
	sets if this screen is automatically updated
void	setViewport (Viewport *viewport)
	bind this Screen to draw to the given `viewport`
Viewport *	getViewport () const
	returns the Viewport this Screen renders into
void	invalidateAll ()
	Invalidates all contained Widgets, causing a complete redraw on next update().
float	statsGetUpdateTime ()
	Returns the time spent performing Screen::update(), averaged over the past 5 frames.
void	statsResetUpdateTime ()
	Resets the UpdateTime statistic.
void	setActive (bool active)
	Sets this screen active or disabled according to the given `active` flag.
bool	isActive ()
	returns the active status for this Screen
virtual ObjectAccessorList *	getAccessors ()
	returns this object's ObjectAccessorList head
virtual unsigned int	getObjectType () const
	Returns an integer identifying the type of object.
Cursor Functions (Input Injection & Utility)
bool	injectCursorMovement (float x_rel, float y_rel)
	Injects cursor movement by providing the relative movement from the last position.
bool	injectCursorPosition (float x_pos, float y_pos)
	Injects cursor movement by providing the absolute cursor position on the screen.
bool	injectCursorPosition_Percent (float x_perc, float y_perc)
	Injects cursor movement by providing the absolute cursor position as a percentage of the screen.
bool	injectCursorPress ()
	Injects cursor press at the last known cursor position.
bool	injectCursorRelease ()
	Injects cursor release at the last known cursor position.
bool	injectCursorPress_State (bool pressed)
	Injects cursor press/release at the last known cursor position using built in state logic.
const FVector2 &	getCursorPos () const
	gets the current cursor position
FVector2	getCursorPos_Percent () const
	gets the current cursor position as a percentage of the screen
void	setCursor (CursorPtr cursor)
	sets the default Cursor for this Screen.
void	enableCursor ()
	Enables the cursor if it is currently disabled.
void	disableCursor ()
	Disables the cursor if it is currently enabled.
bool	cursorEnabled ()
	Returns `true` if the cursor is enabled, `false` otherwise.
void	showCursor ()
	Shows the cursor if it is currently hidden.
void	hideCursor ()
	Hides the cursor if it is currently shown.
bool	cursorVisible ()
	Returns `true` if the cursor is shown, `false` if it is hidden.
Widget *	getCursorFocusedWidget ()
	Returns a pointer to the current Widget that has cursor focus, or 0 if none.
Keyboard Input Injection
bool	injectCharacter (char character)
	Injects the given `character` as text input from the user.
Widget *	getKeyFocusedWidget ()
	Returns a pointer to the current Widget that has key focus, or 0 if none.
Time Functions
bool	isAutoTiming () const
	Returns `true` if this Screen gets its timing from System.
void	setAutoTiming (bool doAutoTime=true)
	Sets if this Screen should receive its timing from System.
void	injectTime (unsigned int milliseconds)
	Injects time into this Screen, in milliseconds ( 1/1000th of a second ).
void	injectTime (float seconds)
	Injects time into this Screen as a float value of a whole second.
Public Attributes
WidgetCollection	Children
	The public collection of child widgets.