PLCore::FrontendImpl Class Reference

Abstract frontend implementation base class. More...

#include <FrontendImpl.h>

Inheritance diagram for PLCore::FrontendImpl:

List of all members.

Protected Member Functions
virtual PLCORE_API void	OnCreate () override
	Called directly after the object has been created.
virtual PLCORE_API void	OnRestart () override
	Called directly before a stopped object is going to start again (always followed by "OnStart()")
virtual PLCORE_API bool	OnStart () override
	Called when the object becoming visible to the user.
virtual PLCORE_API void	OnResume () override
	Called when the object has the focus (keep the implementation lightweight)
virtual PLCORE_API void	OnPause () override
	Called when the object has no longer the focus (keep the implementation lightweight)
virtual PLCORE_API void	OnStop () override
	Called when the object is no longer visible to the user.
virtual PLCORE_API void	OnDestroy () override
	Called before the object is going to be finally destroyed.
virtual PLCORE_API void	OnSize () override
	Called when the window size has been changed.
virtual PLCORE_API void	OnFullscreenMode () override
	Called when the fullscreen mode was changed.
virtual PLCORE_API void	OnDraw () override
	Called to let the frontend draw into it's window.
virtual PLCORE_API void	OnUpdate () override
	Called to let the frontend update it's states.
virtual PLCORE_API void	OnDrop (const Container< String > &lstFiles) override
	Called when string data has been dropped onto the frontend window.
virtual PLCORE_API void	OnRun (const String &sExecutableFilename, const Array< String > &lstArguments)
	Called when the frontend is run.
virtual PLCORE_API int	Run (const String &sExecutableFilename, const Array< String > &lstArguments)
	Called when the frontend should run.
virtual handle	GetNativeWindowHandle () const =0
	Get native window handle.
virtual void	Redraw ()=0
	Redraw frontend.
virtual void	Ping ()=0
	Give the frontend a chance to process OS messages.
virtual String	GetTitle () const =0
	Get frontend title.
virtual void	SetTitle (const String &sTitle)=0
	Set frontend title.
virtual int	GetX () const =0
	Get the x position of the frontend (in screen coordinates)
virtual int	GetY () const =0
	Get the y position of the frontend (in screen coordinates)
virtual uint32	GetWidth () const =0
	Get frontend width.
virtual uint32	GetHeight () const =0
	Get frontend height.
virtual void	GetWindowPositionSize (int &nX, int &nY, uint32 &nWidth, uint32 &nHeight) const =0
	Returns frontend window position and size.
virtual void	SetWindowPositionSize (int nX, int nY, uint32 nWidth, uint32 nHeight)=0
	Set frontend window position and size.
virtual bool	GetToggleFullscreenMode () const =0
	Gets whether it's allowed to toggle the fullscreen mode using hotkeys.
virtual void	SetToggleFullscreenMode (bool bToggleFullscreenMode)=0
	Sets whether it's allowed to toggle the fullscreen mode using hotkeys.
virtual bool	GetFullscreenAltTab () const =0
	Gets whether it's allowed to use Alt-Tab if fullscreen mode is used.
virtual void	SetFullscreenAltTab (bool bAllowed)=0
	Sets whether it's allowed to use Alt-Tab if fullscreen mode is used.
virtual bool	IsFullscreen () const =0
	Returns whether the frontend is in fullscreen mode or not.
virtual void	SetFullscreen (bool bFullscreen)=0
	Sets the frontend's fullscreen mode.
virtual void	RefreshFullscreen ()=0
	Something related to fullscreen mode has been changed (e.g. the display resolution)
virtual bool	IsMouseOver () const =0
	Check if the mouse is currently over the frontend.
virtual int	GetMousePositionX () const =0
	Get current mouse cursor X position inside the frontend.
virtual int	GetMousePositionY () const =0
	Get current mouse cursor Y position inside the frontend.
virtual bool	IsMouseVisible () const =0
	Check if the mouse cursor is visible.
virtual void	SetMouseVisible (bool bVisible)=0
	Set mouse cursor visibility.
virtual void	SetTrapMouse (bool bTrap)=0
	Trap mouse inside the frontend.
Static Protected Member Functions
static PLCORE_API Frontend *	CreateFrontend (const FrontendContext &cFrontendContext, FrontendImpl &cFrontendImpl)
	Creates a frontend instance.
static PLCORE_API void	CorrectPositionSize (int &nX, int &nY, uint32 &nWidth, uint32 &nHeight, int nScreenLeft, int nScreenTop, int nScreenWidth, int nScreenHeight, uint32 nMinWidth=200, uint32 nMinHeight=200)
	Correct frontend position and size settings.
Protected Attributes
Frontend *	m_pFrontend

---

Detailed Description

Abstract frontend implementation base class.

Remarks:

This base class provides the backend interface for concrete implementations. Just think of the frontend implementation as a puppet master, while the puppet is the "Frontend"-class. The frontend implementation is e.g. a simple native OS window or a browser such as MS Internet Explorer or Mozilla Firefox.

---

Member Function Documentation

virtual PLCORE_API void PLCore::FrontendImpl::OnCreate

(

)

[override, protected, virtual]

Called directly after the object has been created.

Implements PLCore::AbstractLifecycle.

virtual PLCORE_API void PLCore::FrontendImpl::OnRestart

(

)

[override, protected, virtual]

Called directly before a stopped object is going to start again (always followed by "OnStart()")

Implements PLCore::AbstractLifecycle.

virtual PLCORE_API bool PLCore::FrontendImpl::OnStart

(

)

[override, protected, virtual]

Called when the object becoming visible to the user.

Returns:

'true' if all went fine, else 'false' (on failure, no "OnResume()", "OnPause()" or "OnStop()" will be called)

Implements PLCore::AbstractLifecycle.

virtual PLCORE_API void PLCore::FrontendImpl::OnResume

(

)

[override, protected, virtual]

Called when the object has the focus (keep the implementation lightweight)

Implements PLCore::AbstractLifecycle.

virtual PLCORE_API void PLCore::FrontendImpl::OnPause

(

)

[override, protected, virtual]

Called when the object has no longer the focus (keep the implementation lightweight)

Implements PLCore::AbstractLifecycle.

virtual PLCORE_API void PLCore::FrontendImpl::OnStop

(

)

[override, protected, virtual]

Called when the object is no longer visible to the user.

Implements PLCore::AbstractLifecycle.

virtual PLCORE_API void PLCore::FrontendImpl::OnDestroy

(

)

[override, protected, virtual]

Called before the object is going to be finally destroyed.

Implements PLCore::AbstractLifecycle.

virtual PLCORE_API void PLCore::FrontendImpl::OnSize

(

)

[override, protected, virtual]

Called when the window size has been changed.

Implements PLCore::AbstractFrontend.

virtual PLCORE_API void PLCore::FrontendImpl::OnFullscreenMode

(

)

[override, protected, virtual]

Called when the fullscreen mode was changed.

Remarks:

This method just says "something related to fullscreen mode has been changed". Whether we changed from window mode into fullscreen mode or changed e.g. the resolution used in fullscreen mode is not really interesting in here.

Implements PLCore::AbstractFrontend.

virtual PLCORE_API void PLCore::FrontendImpl::OnDraw

(

)

[override, protected, virtual]

Called to let the frontend draw into it's window.

Implements PLCore::AbstractFrontend.

virtual PLCORE_API void PLCore::FrontendImpl::OnUpdate

(

)

[override, protected, virtual]

Called to let the frontend update it's states.

Remarks:

You can use this method to do work you have to perform on a regular basis. It's recommended to keep the work done within the implementation as compact as possible. Don't use this function to perform 'polling'-everything, use events or if required for example timers or threads instead.

Implements PLCore::AbstractFrontend.

virtual PLCORE_API void PLCore::FrontendImpl::OnDrop

(

const Container< String > &

lstFiles

)

[override, protected, virtual]

Called when string data has been dropped onto the frontend window.

Parameters:

[in]

lstFiles

List of file names

Implements PLCore::AbstractFrontend.

virtual PLCORE_API void PLCore::FrontendImpl::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.

Note:

• Automatically called from within "Frontend::Run()"

virtual PLCORE_API int PLCore::FrontendImpl::Run	(	const String &	sExecutableFilename,
		const Array< String > &	lstArguments
	)		[protected, virtual]

Called when the frontend should run.

Parameters:

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

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)

Note:

• The default implementation does nothing at all
• Automatically called from within "Frontend::Run()"

virtual handle PLCore::FrontendImpl::GetNativeWindowHandle

(

)

const [protected, pure virtual]

Get native window handle.

Returns:

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

virtual void PLCore::FrontendImpl::Redraw

(

)

[protected, pure virtual]

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()"

virtual void PLCore::FrontendImpl::Ping

(

)

[protected, pure virtual]

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

virtual String PLCore::FrontendImpl::GetTitle

(

)

const [protected, pure virtual]

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.

virtual void PLCore::FrontendImpl::SetTitle

(

const String &

sTitle

)

[protected, pure virtual]

Set frontend title.

Parameters:

[in]

sTitle

Frontend title

See also:

• GetTitle()

virtual int PLCore::FrontendImpl::GetX

(

)

const [protected, pure virtual]

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

Returns:

X position of the frontend

virtual int PLCore::FrontendImpl::GetY

(

)

const [protected, pure virtual]

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

Returns:

Y position of the frontend

virtual uint32 PLCore::FrontendImpl::GetWidth

(

)

const [protected, pure virtual]

Get frontend width.

Returns:

Width of the frontend

virtual uint32 PLCore::FrontendImpl::GetHeight

(

)

const [protected, pure virtual]

Get frontend height.

Returns:

Height of the frontend

virtual void PLCore::FrontendImpl::GetWindowPositionSize	(	int &	nX,
		int &	nY,
		uint32 &	nWidth,
		uint32 &	nHeight
	)		const [protected, pure virtual]

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.).

virtual void PLCore::FrontendImpl::SetWindowPositionSize	(	int	nX,
		int	nY,
		uint32	nWidth,
		uint32	nHeight
	)		[protected, pure virtual]

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"()

virtual bool PLCore::FrontendImpl::GetToggleFullscreenMode

(

)

const [protected, pure virtual]

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'

virtual void PLCore::FrontendImpl::SetToggleFullscreenMode

(

bool

bToggleFullscreenMode

)

[protected, pure virtual]

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

virtual bool PLCore::FrontendImpl::GetFullscreenAltTab

(

)

const [protected, pure virtual]

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

virtual void PLCore::FrontendImpl::SetFullscreenAltTab

(

bool

bAllowed

)

[protected, pure virtual]

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()

virtual bool PLCore::FrontendImpl::IsFullscreen

(

)

const [protected, pure virtual]

Returns whether the frontend is in fullscreen mode or not.

Returns:

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

virtual void PLCore::FrontendImpl::SetFullscreen

(

bool

bFullscreen

)

[protected, pure virtual]

Sets the frontend's fullscreen mode.

Parameters:

[in]

bFullscreen

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

virtual void PLCore::FrontendImpl::RefreshFullscreen

(

)

[protected, pure virtual]

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

virtual bool PLCore::FrontendImpl::IsMouseOver

(

)

const [protected, pure virtual]

Check if the mouse is currently over the frontend.

Returns:

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

virtual int PLCore::FrontendImpl::GetMousePositionX

(

)

const [protected, pure virtual]

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

virtual int PLCore::FrontendImpl::GetMousePositionY

(

)

const [protected, pure virtual]

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

virtual bool PLCore::FrontendImpl::IsMouseVisible

(

)

const [protected, pure virtual]

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!

virtual void PLCore::FrontendImpl::SetMouseVisible

(

bool

bVisible

)

[protected, pure virtual]

Set mouse cursor visibility.

Parameters:

[in]

bVisible

Shall the mouse cursor be visible?

See also:

• IsMouseVisible()

virtual void PLCore::FrontendImpl::SetTrapMouse

(

bool

bTrap

)

[protected, pure virtual]

Trap mouse inside the frontend.

Parameters:

[in]

bTrap

'true' if the mouse should be trapped inside the frontend, else 'false'

static PLCORE_API Frontend* PLCore::FrontendImpl::CreateFrontend	(	const FrontendContext &	cFrontendContext,
		FrontendImpl &	cFrontendImpl
	)		[static, protected]

Creates a frontend instance.

Parameters:

[in]	cFrontendContext	Frontend context to use
[in]	cFrontendImpl	Frontend implementation instance

Returns:

Frontend instance, null pointer on error

static PLCORE_API void PLCore::FrontendImpl::CorrectPositionSize	(	int &	nX,
		int &	nY,
		uint32 &	nWidth,
		uint32 &	nHeight,
		int	nScreenLeft,
		int	nScreenTop,
		int	nScreenWidth,
		int	nScreenHeight,
		uint32	nMinWidth = 200,
		uint32	nMinHeight = 200
	)		[static, protected]

Correct frontend position and size settings.

Parameters:

[in,out]	nX	X position of the frontend (in screen coordinates)
[in,out]	nY	Y position of the frontend (in screen coordinates)
[in,out]	nWidth	Width of the frontend
[in,out]	nHeight	Height of the frontend
[in]	nScreenLeft	Screen left side
[in]	nScreenTop	Screen top side
[in]	nScreenWidth	Screen width
[in]	nScreenHeight	Screen height
[in]	nMinWidth	Minimum allowed frontend width
[in]	nMinHeight	Minimum allowed frontend height

Note:

• Corrects: The frontend position shouldn't be negative
• Corrects: The frontend position shouldn't be outside the visible screen
• Corrects: The size of the frontend shouldn't leave the visible screen

---

Member Data Documentation

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

Pointer to frontend, can be a null pointer

---

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

• FrontendImpl.h
• FrontendImpl.inl