Magnum::Platform::AbstractXApplication class
#include <Magnum/Platform/AbstractXApplication.h>

Base for X11-based applications.

Supports keyboard and mouse handling. See Platform support for brief introduction.

Derived classes

class GlxApplication: GLX application.
class XEglApplication: X/EGL application.

Public types

struct Arguments: Application arguments.
class Configuration: Configuration.
class GLConfiguration: OpenGL context configuration.
class InputEvent: Base for input events.
class KeyEvent: Key event.
class MouseEvent: Mouse event.
class MouseMoveEvent: Mouse move event.
class ViewportEvent: Viewport event.

Constructors, destructors, conversion operators

AbstractXApplication(const AbstractXApplication&) deleted: Copying is not allowed.
AbstractXApplication(AbstractXApplication&&) deleted: Moving is not allowed.

Public functions

auto operator=(const AbstractXApplication&) -> AbstractXApplication& deleted: Copying is not allowed.
auto operator=(AbstractXApplication&&) -> AbstractXApplication& deleted: Moving is not allowed.
auto exec() -> int: Execute main loop.
auto mainLoopIteration() -> bool new in 2020.06: Run one iteration of application main loop.
void exit(int exitCode = 0): Exit application.

Protected functions

void create(const Configuration& configuration, const GLConfiguration& glConfiguration): Create a window with given configuration for OpenGL context.
void create(const Configuration& configuration): Create a window with given configuration and OpenGL context.
void create(): Create a window with default configuration and OpenGL context.
auto tryCreate(const Configuration& configuration, const GLConfiguration& glConfiguration) -> bool: Try to create context with given configuration for OpenGL context.
auto tryCreate(const Configuration& configuration) -> bool: Try to create context with given configuration and OpenGL context.

Screen handling

auto windowSize() const -> Vector2i: Window size.
auto framebufferSize() const -> Vector2i: Framebuffer size.
void swapBuffers() protected: Swap buffers.
void redraw() protected: Redraw immediately.
void viewportEvent(ViewportEvent& event) private virtual: Viewport event.
void drawEvent() private pure virtual: Draw event.

Keyboard handling

void keyPressEvent(KeyEvent& event) private virtual: Key press event.
void keyReleaseEvent(KeyEvent& event) private virtual: Key release event.

Mouse handling

void mousePressEvent(MouseEvent& event) private virtual: Mouse press event.
void mouseReleaseEvent(MouseEvent& event) private virtual: Mouse release event.
void mouseMoveEvent(MouseMoveEvent& event) private virtual: Mouse move event.

Function documentation

int Magnum::Platform::AbstractXApplication::exec()

Execute main loop.

Returns	Value for returning from `main()`

Calls mainLoopIteration() in a loop until exit() is called. See MAGNUM_GLXAPPLICATION_MAIN() or MAGNUM_XEGLAPPLICATION_MAIN() for usage information.

bool Magnum::Platform::AbstractXApplication::mainLoopIteration() new in 2020.06

Run one iteration of application main loop.

Returns	`false` if exit() was called and the application should exit, `true` otherwise

Called internally from exec(). If you want to have better control over how the main loop behaves, you can call this function yourself from your own main() function instead of it being called automatically from exec() / MAGNUM_GLXAPPLICATION_MAIN() / MAGNUM_XEGLAPPLICATION_MAIN().

void Magnum::Platform::AbstractXApplication::exit(int exitCode = 0)

Exit application.

Parameters
exitCode	The exit code the application should return

When called from application constructor, it will cause the application to exit immediately after constructor ends, without any events being processed. Calling this function is recommended over std::exit() or Fatal, which exit without calling destructors on local scope. Note that, however, you need to explicitly return after calling it, as it can't exit the constructor on its own:

MyApplication::MyApplication(const Arguments& arguments):
    Platform::Application{arguments, NoCreate}
{
    // …

    if(!everythingGoingAsExpected) {
        exit(1);
        return;
    }

    // …
}

When called from the main loop, the application exits cleanly before next main loop iteration is executed.

void Magnum::Platform::AbstractXApplication::create(const Configuration& configuration, const GLConfiguration& glConfiguration) protected

Create a window with given configuration for OpenGL context.

Parameters
configuration	Application configuration
glConfiguration	OpenGL context configuration

Must be called only if the context wasn't created by the constructor itself, i.e. when passing NoCreate to it. Error message is printed and the program exits if the context cannot be created, see tryCreate() for an alternative.

void Magnum::Platform::AbstractXApplication::create(const Configuration& configuration) protected

Create a window with given configuration and OpenGL context.

Equivalent to calling create(const Configuration&, const GLConfiguration&) with default-constructed GLConfiguration.

void Magnum::Platform::AbstractXApplication::create() protected

Create a window with default configuration and OpenGL context.

Equivalent to calling create(const Configuration&) with default-constructed Configuration.

bool Magnum::Platform::AbstractXApplication::tryCreate(const Configuration& configuration, const GLConfiguration& glConfiguration) protected

Try to create context with given configuration for OpenGL context.

Unlike create(const Configuration&, const GLConfiguration&) returns false if the context cannot be created, true otherwise.

bool Magnum::Platform::AbstractXApplication::tryCreate(const Configuration& configuration) protected

Try to create context with given configuration and OpenGL context.

Unlike create(const Configuration&) returns false if the context cannot be created, true otherwise.

Vector2i Magnum::Platform::AbstractXApplication::windowSize() const

Window size.

Window size to which all input event coordinates can be related. Same as framebufferSize().

Vector2i Magnum::Platform::AbstractXApplication::framebufferSize() const

Framebuffer size.

Size of the default framebuffer. Same as windowSize().

void Magnum::Platform::AbstractXApplication::swapBuffers() protected

Swap buffers.

Paints currently rendered framebuffer on screen.

void Magnum::Platform::AbstractXApplication::redraw() protected

Redraw immediately.

Marks the window for redrawing, resulting in call to drawEvent() in the next iteration. You can call it from drawEvent() itself to redraw immediately without waiting for user input.

void Magnum::Platform::AbstractXApplication::viewportEvent(ViewportEvent& event) virtual private

Viewport event.

Called when window size changes. The default implementation does nothing. If you want to respond to size changes, you should pass the new size to GL::DefaultFramebuffer::setViewport() (if using OpenGL) and possibly elsewhere (to SceneGraph::Camera::setViewport(), other framebuffers...).

Note that this function might not get called at all if the window size doesn't change. You should configure the initial state of your cameras, framebuffers etc. in application constructor rather than relying on this function to be called. Size of the window can be retrieved using windowSize().

void Magnum::Platform::AbstractXApplication::drawEvent() pure virtual private

Draw event.

Called when the screen is redrawn. You should clean the framebuffer using GL::DefaultFramebuffer::clear() (if using OpenGL) and then add your own drawing functions. After drawing is finished, call swapBuffers(). If you want to draw immediately again, call also redraw().

void Magnum::Platform::AbstractXApplication::keyPressEvent(KeyEvent& event) virtual private

Key press event.

Called when an key is pressed. Default implementation does nothing.

void Magnum::Platform::AbstractXApplication::keyReleaseEvent(KeyEvent& event) virtual private

Key release event.

Called when an key is released. Default implementation does nothing.

void Magnum::Platform::AbstractXApplication::mousePressEvent(MouseEvent& event) virtual private

Mouse press event.

Called when mouse button is pressed. Default implementation does nothing.

void Magnum::Platform::AbstractXApplication::mouseReleaseEvent(MouseEvent& event) virtual private

Mouse release event.

Called when mouse button is released. Default implementation does nothing.

void Magnum::Platform::AbstractXApplication::mouseMoveEvent(MouseMoveEvent& event) virtual private

Mouse move event.

Called when mouse is moved. Default implementation does nothing.