Platform Class Reference

#include <Platform.h>

Inheritance diagram for Platform:

Public Member Functions
virtual	~Platform ()=default
virtual std::unique_ptr< PlatformWindow >	createWindow ()=0
virtual std::unique_ptr< PlatformEventLoop >	createEventLoop ()=0
virtual std::vector< PlatformGamepad * >	gamepads ()=0
virtual void	setCursorShown (bool cursorShown)=0
virtual bool	isCursorShown () const =0
virtual std::vector< Recti >	displayGeometries () const =0
virtual void	showMessageBox (const std::string &title, const std::string &message) const =0
virtual int64_t	tickCount () const =0

Static Public Member Functions
static std::unique_ptr< Platform >	createStandardPlatform ()

Detailed Description

Platform abstraction layer.

Platform classes can be broadly divided into three categories:

• API handles. These classes don't hold any state and cannot be subclassed in user code.
• Extension points. These classes can hold state and can be subclassed in user code.
• Value types.

API handles exposed by the platform are:

• Platform, which also works as a factory for other API handles.
• PlatformWindow, an API handle for a GUI window.
• PlatformEventLoop, an API handle for running an event loop.
• PlatformOpenGLContext, an API handle for accessing OpenGL API for a window.

Then there are the following extension points:

• PlatformEventHandler, which should be subclassed in user code to handle platform events. An instance is passed to PlatformEventLoop methods, so this is where the calls back into the user code happen.

That's it, there is only one extension point. If you want fancy event handler chains, you can use FilteringEventHandler.

And then there are value types:

• All kinds of enums for keyboard keys, mouse keys, and modifiers.
• PlatformEvent and subclasses for delivering events to PlatformEventHandler.

All platform classes don't throw but write errors to log instead. See per-method docs for details on how errors are reported by each method.

Also platform declares its own main function, so you cannot declare main in your code. Platform expects you to define platformMain instead.

Some guidelines on adding new functionality to platform classes:

• If something can be done at the next abstraction layer, then it should be done at the next abstraction layer. Don't clutter platform API.
• Platform API should be reasonably minimal, and methods should be orthogonal. You can think of orthogonality in terms of information content, "is this method returning bits that can also be accessed through another method?" E.g. compare position + setPosition + framePosition + setFramePosition for a window class, vs position + setPosition + frameMargins. The latter set of methods is orthogonal, the former is not.
• The points above mean that platform API handles shouldn't expose non-virtual methods.
• Platform API should be getter/setter symmetric as long as the underlying OS API is symmetric. E.g. in the example above there is no SetFrameMargins method because this is not how window frames work.
• Platform API handles shouldn't hold state. Don't expose APIs that take ownership of user-allocated data, and don't cache values returned by the OS (if needed, caching should be implemented at the next abstraction layer). Again, you can think about this in terms of information content, "platform API handle doesn't expose any bits of state through its API that cannot be accessed through the underlying OS API".

See also

platformMain

Constructor & Destructor Documentation

~Platform()

virtual Platform::~Platform ( )

virtualdefault

Member Function Documentation

createEventLoop()

virtual std::unique_ptr< PlatformEventLoop > Platform::createEventLoop ( )

pure virtual

Creates a new event loop.

Returns

Newly created event loop, or nullptr on error.

Implemented in ApplicationProxy, NullPlatform, ProxyPlatform, and SdlPlatform.

createStandardPlatform()

std::unique_ptr< Platform > Platform::createStandardPlatform ( )

static

Creates a standard platform.

Returns

A newly created Platform. This method is guaranteed to succeed.

createWindow()

virtual std::unique_ptr< PlatformWindow > Platform::createWindow ( )

pure virtual

Creates a new platform window.

Returns

Newly created window, or nullptr on error.

Implemented in ApplicationProxy, NullPlatform, ProxyPlatform, and SdlPlatform.

displayGeometries()

virtual std::vector< Recti > Platform::displayGeometries ( ) const

pure virtual

Returns

Geometries of all monitors on current system, or an empty vector in case of an error.

Implemented in NullPlatform, ProxyPlatform, and SdlPlatform.

gamepads()

virtual std::vector< PlatformGamepad * > Platform::gamepads ( )

pure virtual

This function lists the gamepads currently connected to the system. The gamepad objects themselves are owned by the platform and are destroyed automatically when disconnected. If you're caching them in your code, then make sure to subscribe to EVENT_GAMEPAD_DISCONNECTED, it is guaranteed to fire before the gamepad object is destroyed.

Returns

All gamepads connected to the system.

Implemented in NullPlatform, ProxyPlatform, and SdlPlatform.

isCursorShown()

virtual bool Platform::isCursorShown ( ) const

pure virtual

Getter for setCursorShown.

Returns

Whether the system cursor is currently shown on top of windows created by this platform.

Implemented in NullPlatform, ProxyPlatform, and SdlPlatform.

setCursorShown()

virtual void Platform::setCursorShown ( bool  cursorShown )

pure virtual

Shows / hides system cursor (on top of all windows created by this platform).

Parameters

cursorShown

Whether to show the system cursor.

Implemented in NullPlatform, ProxyPlatform, and SdlPlatform.

showMessageBox()

virtual void Platform::showMessageBox ( const std::string &  title, const std::string &  message  ) const

pure virtual

Shows a modal message box.

Parameters

title	Title of the message box window.
message	Message to display.

Implemented in NullPlatform, ProxyPlatform, and SdlPlatform.

tickCount()

virtual int64_t Platform::tickCount ( ) const

pure virtual

Returns

Current value of a monotonic clock in milliseconds.

Implemented in EngineDeterministicComponent, NullPlatform, ProxyPlatform, and SdlPlatform.

---

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

• src/Library/Platform/Interface/Platform.h
• src/Library/Platform/Sdl/SdlPlatform.cpp