Abstract frontend base class. More...

#include <Frontend.h>

Inheritance diagram for PLCore::Frontend:

[legend]

Public Member Functions
PLCORE_API	Frontend (const FrontendContext &cFrontendContext, FrontendImpl &cFrontendImpl)
	Run the frontend.
virtual PLCORE_API	~Frontend ()
	Destructor.
const FrontendContext &	GetContext () const
	Get frontend context.
FrontendImpl *	GetImpl () const
	Get frontend implementation.
handle	GetNativeWindowHandle () const
	Get native window handle.
void	Redraw ()
	Redraw frontend.
void	Ping () const
	Give the frontend a chance to process OS messages.
void	RedrawAndPing ()
	Redraw frontend and give the frontend a chance to process OS messages.
String	GetTitle () const
	Get frontend title.
void	SetTitle (const String &sTitle)
	Set frontend title.
int	GetX () const
	Get the x position of the frontend (in screen coordinates)
int	GetY () const
	Get the y position of the frontend (in screen coordinates)
uint32	GetWidth () const
	Get frontend width.
uint32	GetHeight () const
	Get frontend height.
void	GetWindowPositionSize (int &nX, int &nY, uint32 &nWidth, uint32 &nHeight) const
	Returns frontend window position and size.
void	SetWindowPositionSize (int nX, int nY, uint32 nWidth, uint32 nHeight)
	Set frontend window position and size.
bool	GetToggleFullscreenMode () const
	Gets whether it's allowed to toggle the fullscreen mode using hotkeys.
void	SetToggleFullscreenMode (bool bToggleFullscreenMode)
	Sets whether it's allowed to toggle the fullscreen mode using hotkeys.
bool	GetFullscreenAltTab () const
	Gets whether it's allowed to use Alt-Tab if fullscreen mode is used.
void	SetFullscreenAltTab (bool bAllowed)
	Sets whether it's allowed to use Alt-Tab if fullscreen mode is used.
bool	IsFullscreen () const
	Returns whether the frontend is in fullscreen mode or not.
void	SetFullscreen (bool bFullscreen)
	Sets the frontend's fullscreen mode.
void	RefreshFullscreen ()
	Something related to fullscreen mode has been changed (e.g. the display resolution)
bool	IsMouseOver () const
	Check if the mouse is currently over the frontend.
int	GetMousePositionX () const
	Get current mouse cursor X position inside the frontend.
int	GetMousePositionY () const
	Get current mouse cursor Y position inside the frontend.
bool	IsMouseVisible () const
	Check if the mouse cursor is visible.
void	SetMouseVisible (bool bVisible)
	Set mouse cursor visibility.
void	SetTrapMouse (bool bTrap)
	Trap mouse inside the frontend.
virtual bool	IsRunning () const =0
	Returns whether or not the frontend is currently running.
Protected Member Functions
virtual PLCORE_API void	OnRun (const String &sExecutableFilename, const Array< String > &lstArguments)
	Called when the frontend is run.
Protected Attributes
const FrontendContext &	m_cFrontendContext
FrontendImpl *	m_pFrontendImpl

Detailed Description

Abstract frontend base class.

Remarks:: This base class provides an abstract frontend API which is used to develop an actual PixelLight frontend class. Concrete wrappers for certain browsers, such as MS Internet Explorer or Mozilla Firefox are used to map the browser specific frontend API to this general base class.

The focus of this class is on applications with just one window (if there's a window at all, this depends on the used frontend implementation). This focus makes application development somewhat easier because you only have to concentrate our realizing your project and not how it will be presented (in a window with border, without border, just rendering into an image etc.) to the user.

The PixelLight technology is designed to be as flexible as possible and so, although this class has a clear focus, it can also be used to develop multi-window applications as well.

Please note that the frontend system is not designed to be a replacement for a decent GUI system. In here, only primitive and commonly used GUI related feature are offered with a limited feature set. For more complex stuff one has to use a real GUI system.

Note:

Do only interact with the frontend when it really makes sense because it's not guaranteed that every frontend implementation provides every feature exposed by this interface
Stuff like window border, window title bar etc. isn't interesting for the frontend, therefore methods like "GetNativeWindowHandle()" or "GetWidth()" return only information relevant for e.g. rendering into the frontend

Constructor & Destructor Documentation

PLCORE_API PLCore::Frontend::Frontend	(	const FrontendContext &	cFrontendContext,
		FrontendImpl &	cFrontendImpl
	)

Run the frontend.

Parameters:

[in]	cFrontendContext	Frontend context to use (just shared, the given instance must stay valid as long as this frontend lives)
[in]	bUrgentMessageAllowed	Is this method allowed to show an urgent message to the user in case of a failure?

Returns:: Exit code (usually 0 means no error), usually <0 when there was an error (e.g. an embedded frontend implementation is run and controlled by another application and can't be run by using this method)

Constructor

Parameters:

[in]	cFrontendContext	Frontend context to use (just shared, the given instance must stay valid as long as this frontend lives)
[in]	cFrontendImpl	Frontend implementation instance

virtual PLCORE_API PLCore::Frontend::~Frontend ( ) [virtual]

Destructor.

Member Function Documentation

const FrontendContext & PLCore::Frontend::GetContext ( ) const [inline]

Get frontend context.

Returns:: Frontend context

FrontendImpl * PLCore::Frontend::GetImpl ( ) const [inline]

Get frontend implementation.

Returns:: Pointer to the implementation backend, can be a null pointer

handle PLCore::Frontend::GetNativeWindowHandle ( ) const [inline]

Get native window handle.

Returns:: Native window handle for the frontend window, can be a null pointer

void PLCore::Frontend::Redraw ( ) [inline]

Redraw frontend.

Remarks:: There are situations were an application may do some heavy work without letting the frontend a chance to redraw. In such situations, it may be wise to call this method from time to time to give the frontend a chance to do redraw itself.

Note:

Whenever possible, don't use this method, do heavy work within e.g. threads
Depending on the frontend implementation, the redraw may not be immediate
Doesn't include "Ping()"

void PLCore::Frontend::Ping ( ) const [inline]

Give the frontend a chance to process OS messages.

Remarks:: There are situations were an application may do some heavy work without letting the frontend a chance to process OS messages. In such situations, it may be wise to call this method from time to time to give the frontend a chance to do some message processing.

Note:

Whenever possible, don't use this method, do heavy work within e.g. threads
Doesn't include "Redraw()"

void PLCore::Frontend::RedrawAndPing ( ) [inline]

Redraw frontend and give the frontend a chance to process OS messages.

Remarks:: Calls "Redraw()", then "Ping()".

Note:

Whenever possible, don't use this method, do heavy work within e.g. threads

String PLCore::Frontend::GetTitle ( ) const [inline]

Get frontend title.

Returns:: Frontend title

Remarks:: When the frontend has a window, this title can be seen within the window title bar. Please note that there's no guarantee that there's a window title bar or even a window. By default, the title is set to the frontend context name ("GetContext().GetName()") which is usually sufficient. So, unless you have a good reason to explicitly set an individual frontend title, just use the default setting and don't touch the frontend.

void PLCore::Frontend::SetTitle ( const String & sTitle ) [inline]

Set frontend title.

Parameters:

[in] sTitle Frontend title

See also:

GetTitle()

int PLCore::Frontend::GetX ( ) const [inline]

Get the x position of the frontend (in screen coordinates)

Returns:: X position of the frontend

int PLCore::Frontend::GetY ( ) const [inline]

Get the y position of the frontend (in screen coordinates)

Returns:: Y position of the frontend

uint32 PLCore::Frontend::GetWidth ( ) const [inline]

Get frontend width.

Returns:: Width of the frontend

uint32 PLCore::Frontend::GetHeight ( ) const [inline]

Get frontend height.

Returns:: Height of the frontend

void PLCore::Frontend::GetWindowPositionSize	(	int &	nX,
		int &	nY,
		uint32 &	nWidth,
		uint32 &	nHeight
	)		const `[inline]`

Returns frontend window position and size.

Parameters:

[out]	nX	Receives the x position of the frontend window (in screen coordinates)
[out]	nY	Receives the y position of the frontend window (in screen coordinates)
[out]	nWidth	Receives the width of the frontend window
[out]	nHeight	Receives the height of the frontend window

Remarks:: The primary argument to allow the user to request a frontend window position and size change is, that it should be possible to restore the frontend window position and size of a previous session (may be important for the usability). Do not misuse this method to frequently manipulate the frontend window appearance. Please note that, as for all other frontend methods, this is only considered to be a request. A frontend implementation may deny the request in general or just improper settings (e.g. a too small size, position outside the visible screen etc.).

void PLCore::Frontend::SetWindowPositionSize	(	int	nX,
		int	nY,
		uint32	nWidth,
		uint32	nHeight
	)		`[inline]`

Set frontend window position and size.

Parameters:

[in]	nX	X position of the frontend window (in screen coordinates)
[in]	nY	Y position of the frontend window (in screen coordinates)
[in]	nWidth	Width of the frontend window
[in]	nHeight	Height of the frontend window

See also:

"GetWindowPositionSize"()

bool PLCore::Frontend::GetToggleFullscreenMode ( ) const [inline]

Gets whether it's allowed to toggle the fullscreen mode using hotkeys.

Returns:: 'true' if it's possible to toggle the fullscreen mode using hotkeys, else 'false'

void PLCore::Frontend::SetToggleFullscreenMode ( bool bToggleFullscreenMode ) [inline]

Sets whether it's allowed to toggle the fullscreen mode using hotkeys.

Parameters:

[in] bToggleFullscreenMode Is it allowed to toggle the fullscreen mode using hotkeys?

Note:

By default, it's allowed to switch widgets into fullscreen mode using Alt-Return or AltGr-Return

bool PLCore::Frontend::GetFullscreenAltTab ( ) const [inline]

Gets whether it's allowed to use Alt-Tab if fullscreen mode is used.

Returns:: 'true' if it's possible to use Alt-Tab if fullscreen mode is used, else 'false'

Note:

Widgets only

void PLCore::Frontend::SetFullscreenAltTab ( bool bAllowed ) [inline]

Sets whether it's allowed to use Alt-Tab if fullscreen mode is used.

Parameters:

[in] bAllowed Is it allowed to use Alt-Tab within fullscreen mode?

Note:

By default, it's allowed to use Alt-Tab

See also:

GetFullscreenAltTab()

bool PLCore::Frontend::IsFullscreen ( ) const [inline]

Returns whether the frontend is in fullscreen mode or not.

Returns:: 'true' if the frontend is in fullscreen mode, else 'false'

void PLCore::Frontend::SetFullscreen ( bool bFullscreen ) [inline]

Sets the frontend's fullscreen mode.

Parameters:

[in] bFullscreen 'true' if the frontend should be in fullscreen mode, else 'false'

void PLCore::Frontend::RefreshFullscreen ( ) [inline]

Something related to fullscreen mode has been changed (e.g. the display resolution)

bool PLCore::Frontend::IsMouseOver ( ) const [inline]

Check if the mouse is currently over the frontend.

Returns:: 'true' if mouse-over, else 'false'

int PLCore::Frontend::GetMousePositionX ( ) const [inline]

Get current mouse cursor X position inside the frontend.

Returns:: Current mouse cursor X position inside the frontend, negative value if the mouse cursor isn't currently over the frontend

int PLCore::Frontend::GetMousePositionY ( ) const [inline]

Get current mouse cursor Y position inside the frontend.

Returns:: Current mouse cursor Y position inside the frontend, negative value if the mouse cursor isn't currently over the frontend

bool PLCore::Frontend::IsMouseVisible ( ) const [inline]

Check if the mouse cursor is visible.

Returns:: 'true' if the mouse cursor is visible, else 'false'

Note:

If the mouse cursor is visible in general, it's still possible that it's invisible over some special widgets.
If the mouse cursor is invisible in general, it will NEVER be visible!
Do only hide the mouse cursor when it really makes sense (e.g. during the period the mouse is used to control a "camera look around")

void PLCore::Frontend::SetMouseVisible ( bool bVisible ) [inline]

Set mouse cursor visibility.

Parameters:

[in] bVisible Shall the mouse cursor be visible?

See also:

IsMouseVisible()

void PLCore::Frontend::SetTrapMouse ( bool bTrap ) [inline]

Trap mouse inside the frontend.

Parameters:

[in] bTrap 'true' if the mouse should be trapped inside the frontend, else 'false'

Note:

Do only trap the mouse cursor when it really makes sense (e.g. during the period the mouse is used to control a "camera look around")

virtual bool PLCore::Frontend::IsRunning ( ) const [pure virtual]

Returns whether or not the frontend is currently running.

Returns:: 'true' if the frontend is currently running, else 'false'

Implemented in PLCore::FrontendPixelLight, and PLCore::FrontendOpenGL.

virtual PLCORE_API void PLCore::Frontend::OnRun	(	const String &	sExecutableFilename,
		const Array< String > &	lstArguments
	)		`[protected, virtual]`

Called when the frontend is run.

Parameters:

[in]	sExecutableFilename	Absolute application executable filename
[in]	lstArguments	List of arguments to the program

Remarks:: This frontend method is called just before the frontend calls it's run-method in order to enter it's main-loop. This means that this method is called between "AbstractLifecycle::OnCreate()" and "AbstractLifecycle::OnStart()". Use this method for instance to pre-process command line arguments.

The default implementation does the following tasks:

none (implement in derived classes)

Reimplemented in PLCore::FrontendPixelLight.

Member Data Documentation

const FrontendContext& PLCore::Frontend::m_cFrontendContext [protected]

Frontend context to use (just shared, the given instance must stay valid as long as this frontend lives)

FrontendImpl* PLCore::Frontend::m_pFrontendImpl [protected]

Pointer to implementation backend, can be a null pointer

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

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation