Magnum::Platform::AbstractXApplication class

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 deprecated in Git master
Mouse event.
class MouseMoveEvent deprecated in Git master
Mouse move event.
class PointerEvent new in Git master
Pointer event.
class PointerMoveEvent new in Git master
Pointer move event.
class ScrollEvent new in Git master
Scroll event.
class ViewportEvent
Viewport event.
enum class Modifier: unsigned int { Shift = ShiftMask, Ctrl = ControlMask, Alt = Mod1Mask, AltGr = Mod5Mask, CapsLock = LockMask, NumLock = Mod2Mask } new in Git master
Keyboard modifier.
enum class Key: KeySym { LeftShift = XK_Shift_L new in Git master, RightShift = XK_Shift_R new in Git master, LeftCtrl = XK_Control_L new in Git master, RightCtrl = XK_Control_R new in Git master, LeftAlt = XK_Alt_L new in Git master, RightAlt = XK_Alt_R new in Git master, LeftSuper = XK_Super_L new in Git master, RightSuper = XK_Super_R new in Git master, Enter = XK_Return, Esc = XK_Escape, Up = XK_Up, Down = XK_Down, Left = XK_Left, Right = XK_Right, Home = XK_Home, End = XK_End, PageUp = XK_Page_Up, PageDown = XK_Page_Down, Backspace = XK_BackSpace new in Git master, Insert = XK_Insert new in Git master, Delete = XK_Delete new in Git master, F1 = XK_F1, F2 = XK_F2, F3 = XK_F3, F4 = XK_F4, F5 = XK_F5, F6 = XK_F6, F7 = XK_F7, F8 = XK_F8, F9 = XK_F9, F10 = XK_F10, F11 = XK_F11, F12 = XK_F12, Space = XK_space, Tab = XK_Tab new in Git master, Quote = XK_apostrophe new in Git master, Comma = XK_comma, Period = XK_period, Minus = XK_minus, Plus = XK_plus, Slash = XK_slash, Percent = XK_percent, Semicolon = XK_semicolon new in Git master, Equal = XK_equal, LeftBracket = XK_bracketleft new in Git master, RightBracket = XK_bracketright new in Git master, Backslash = XK_backslash new in Git master, Backquote = XK_grave new in Git master, Zero = XK_0, One = XK_1, Two = XK_2, Three = XK_3, Four = XK_4, Five = XK_5, Six = XK_6, Seven = XK_7, Eight = XK_8, Nine = XK_9, A = XK_a, B = XK_b, C = XK_c, D = XK_d, E = XK_e, F = XK_f, G = XK_g, H = XK_h, I = XK_i, J = XK_j, K = XK_k, L = XK_l, M = XK_m, N = XK_n, O = XK_o, P = XK_p, Q = XK_q, R = XK_r, S = XK_s, T = XK_t, U = XK_u, V = XK_v, W = XK_w, X = XK_x, Y = XK_y, Z = XK_z, CapsLock = XK_Caps_Lock new in Git master, ScrollLock = XK_Scroll_Lock new in Git master, NumLock = XK_Num_Lock new in Git master, PrintScreen = XK_Print new in Git master, NumZero = XK_KP_0 new in Git master, NumOne = XK_KP_1 new in Git master, NumTwo = XK_KP_2 new in Git master, NumThree = XK_KP_3 new in Git master, NumFour = XK_KP_4 new in Git master, NumFive = XK_KP_5 new in Git master, NumSix = XK_KP_6 new in Git master, NumSeven = XK_KP_7 new in Git master, NumEight = XK_KP_8 new in Git master, NumNine = XK_KP_9 new in Git master, NumDecimal = XK_KP_Decimal new in Git master, NumDivide = XK_KP_Divide new in Git master, NumMultiply = XK_KP_Multiply new in Git master, NumSubtract = XK_KP_Subtract new in Git master, NumAdd = XK_KP_Add new in Git master, NumEnter = XK_KP_Enter new in Git master, NumEqual = XK_KP_Equal new in Git master } new in Git master
Key.
enum class PointerEventSource: UnsignedByte { Mouse } new in Git master
Pointer event source.
enum class Pointer: UnsignedByte { MouseLeft = 1 << 0, MouseMiddle = 1 << 1, MouseRight = 1 << 2 } new in Git master
Pointer type.
using Modifiers = Containers::EnumSet<Modifier> new in Git master
Set of keyboard modifiers.
using Pointers = Containers::EnumSet<Pointer> new in Git master
Set of pointer types.

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.

Pointer handling

void pointerPressEvent(PointerEvent& event) private virtual new in Git master
Pointer press event.
void mousePressEvent(MouseEvent& event) deprecated in Git master private virtual
Mouse press event.
void pointerReleaseEvent(PointerEvent& event) private virtual new in Git master
Pointer release event.
void mouseReleaseEvent(MouseEvent& event) deprecated in Git master private virtual
Mouse release event.
void pointerMoveEvent(PointerMoveEvent& event) private virtual new in Git master
Pointer move event.
void mouseMoveEvent(MouseMoveEvent& event) deprecated in Git master private virtual
Mouse move event.
void scrollEvent(ScrollEvent& event) private virtual new in Git master
Mouse scroll event.

Enum documentation

enum class Magnum::Platform::AbstractXApplication::Key: KeySym new in Git master

Key.

Enumerators
LeftShift new in Git master

Left Shift

RightShift new in Git master

Right Shift

LeftCtrl new in Git master

Left Ctrl

RightCtrl new in Git master

Right Ctrl

LeftAlt new in Git master

Left Alt

RightAlt new in Git master

Right Alt

LeftSuper new in Git master

Left Super key (Windows/⌘)

RightSuper new in Git master

Right Super key (Windows/⌘)

Enter

Enter

Esc

Escape

Up

Up arrow

Down

Down arrow

Left

Left arrow

Right

Right arrow

Home

Home

End

End

PageUp

Page up

PageDown

Page down

Backspace new in Git master

Backspace

Insert new in Git master

Insert

Delete new in Git master

Delete

F1

F1

F2

F2

F3

F3

F4

F4

F5

F5

F6

F6

F7

F7

F8

F8

F9

F9

F10

F10

F11

F11

F12

F12

Space

Space

Tab new in Git master

Tab

Quote new in Git master

Quote (')

Comma

Comma

Period

Period

Minus

Minus

Plus

Plus

Slash

Slash

Percent

Percent

Semicolon new in Git master

Semicolon (;)

Equal

Equal

LeftBracket new in Git master

Left bracket ([)

RightBracket new in Git master

Right bracket (])

Backslash new in Git master

Backslash (\)

Backquote new in Git master

Backquote (`)

Zero

Zero

One

One

Two

Two

Three

Three

Four

Four

Five

Five

Six

Six

Seven

Seven

Eight

Eight

Nine

Nine

A

Small letter A

B

Small letter B

C

Small letter C

D

Small letter D

E

Small letter E

F

Small letter F

G

Small letter G

H

Small letter H

I

Small letter I

J

Small letter J

K

Small letter K

L

Small letter L

M

Small letter M

N

Small letter N

O

Small letter O

P

Small letter P

Q

Small letter Q

R

Small letter R

S

Small letter S

T

Small letter T

U

Small letter U

V

Small letter V

W

Small letter W

X

Small letter X

Y

Small letter Y

Z

Small letter Z

CapsLock new in Git master

Caps lock

ScrollLock new in Git master

Scroll lock

NumLock new in Git master

Num lock

PrintScreen new in Git master

Print screen

NumZero new in Git master

Numpad zero

NumOne new in Git master

Numpad one

NumTwo new in Git master

Numpad two

NumThree new in Git master

Numpad three

NumFour new in Git master

Numpad four

NumFive new in Git master

Numpad five

NumSix new in Git master

Numpad six

NumSeven new in Git master

Numpad seven

NumEight new in Git master

Numpad eight

NumNine new in Git master

Numpad nine

NumDecimal new in Git master

Numpad decimal

NumDivide new in Git master

Numpad divide

NumMultiply new in Git master

Numpad multiply

NumSubtract new in Git master

Numpad subtract

NumAdd new in Git master

Numpad add

NumEnter new in Git master

Numpad enter

NumEqual new in Git master

Numpad equal

enum class Magnum::Platform::AbstractXApplication::PointerEventSource: UnsignedByte new in Git master

Pointer event source.

Enumerators
Mouse

The event is coming from a mouse

enum class Magnum::Platform::AbstractXApplication::Pointer: UnsignedByte new in Git master

Pointer type.

Enumerators
MouseLeft

Left mouse button. Corresponds to Button1 / Button1Mask.

MouseMiddle

Middle mouse button. Corresponds to Button2 / Button2Mask.

MouseRight

Right mouse button. Corresponds to Button3 / Button3Mask.

Typedef documentation

typedef Containers::EnumSet<Modifier> Magnum::Platform::AbstractXApplication::Modifiers new in Git master

Set of keyboard modifiers.

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 a key is pressed. Default implementation does nothing.

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

Key release event.

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

void Magnum::Platform::AbstractXApplication::pointerPressEvent(PointerEvent& event) virtual private new in Git master

Pointer press event.

Called when a mouse is pressed. Note that if at least one mouse button is already pressed and another button gets pressed in addition, pointerMoveEvent() with the new combination is called, not this function.

On builds with MAGNUM_BUILD_DEPRECATED enabled, default implementation delegates to mousePressEvent(). On builds with deprecated functionality disabled, default implementation does nothing.

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

Mouse press event.

Default implementation does nothing.

void Magnum::Platform::AbstractXApplication::pointerReleaseEvent(PointerEvent& event) virtual private new in Git master

Pointer release event.

Called when a mouse is released. Note that if multiple mouse buttons are pressed and one of these is released, pointerMoveEvent() with the new combination is called, not this function.

On builds with MAGNUM_BUILD_DEPRECATED enabled, default implementation delegates to mouseReleaseEvent(). On builds with deprecated functionality disabled, default implementation does nothing.

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

Mouse release event.

Default implementation does nothing.

void Magnum::Platform::AbstractXApplication::pointerMoveEvent(PointerMoveEvent& event) virtual private new in Git master

Pointer move event.

Called when any of the currently pressed pointers is moved or changes its properties. Gets called also if the set of pressed mouse buttons changes.

On builds with MAGNUM_BUILD_DEPRECATED enabled, default implementation delegates to mouseMoveEvent(), or if PointerMoveEvent::pointer() is not Containers::NullOpt, to either mousePressEvent() or mouseReleaseEvent(). On builds with deprecated functionality disabled, default implementation does nothing.

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

Mouse move event.

Default implementation does nothing.

void Magnum::Platform::AbstractXApplication::scrollEvent(ScrollEvent& event) virtual private new in Git master

Mouse scroll event.

Called when a scrolling device is used (mouse wheel or scrolling area on a touchpad).

On builds with MAGNUM_BUILD_DEPRECATED enabled, default implementation delegates to mousePressEvent() and mouseReleaseEvent() with MouseEvent::Button::WheelDown and MouseEvent::Button::WheelUp.