Class WindowingAPI

• Defined in File WindowingAPI.h

Nested Relationships

Nested Types

• Struct WindowingAPI::Data

• Struct WindowingAPI::InternalCursor

• Struct WindowingAPI::InternalMonitor

• Struct WindowingAPI::InternalVideoMode

• Struct WindowingAPI::InternalWindow

• Struct WindowingAPI::WindowConfig

• Struct WindowConfig::wayland

Class Documentation

class WindowingAPI

Remark

Headless mode: This class is not available in headless mode.

Public Types

enum class Error

Error codes.

Values:

enumerator No_Error

enumerator Not_Initialized

enumerator Invalid_Enum

enumerator Invalid_Value

enumerator Out_Of_Memory

enumerator API_Unavailable

enumerator Platform_Error

enumerator Format_Unavailable

enumerator Cursor_Unavailable

enumerator Feature_Unavailable

enumerator Feature_Unimplemented

enumerator Platform_Unavailable

enum class Hint

Hints for window creation and runtime changes.

Values:

enumerator Resizable

enumerator Maximized

enumerator Minimized

enumerator Visible

enumerator Focused

enumerator FocusOnShow

enumerator Hovered

enumerator Decorated

enumerator Floating

enumerator MousePassthrough

enum class CursorMode

Cursor modes that can be used.

Values:

enumerator Normal

enumerator Hidden

enumerator Disabled

enumerator Captured

enum class CursorType : u32

Cursor types that can be used.

Values:

enumerator Arrow

enumerator Input

enumerator Crosshair

enumerator PointingHand

enumerator ResizeHorizontal

enumerator ResizeVertical

enumerator ResizeDiagonalTopLeftBottomRight

enumerator ResizeDiagonalTopRightBottomLeft

enumerator ResizeAll

enumerator NotAllowed

enum class ProgressState

State of progress for a window.

Values:

enumerator Disabled

enumerator Indeterminate

enumerator Normal

enumerator Error

enumerator Paused

using WindowPositionFunc = void (*)(const InternalWindow &window, i32 xPos, i32 yPos)

The function pointer type for window position callbacks.

Param window:

The window that was moved.

Param xPos:

The new x-coordinate, in screen coordinates, of the upper-left corner of the content area.

Param yPos:

The new y-coordinate, in screen coordinates, of the upper-left corner of the content area.

using WindowSizeFunc = void (*)(const InternalWindow &window, i32 width, i32 height)

The function pointer type for window size callbacks.

Param window:

The window that was resized.

Param width:

The new width, in screen coordinates.

Param height:

The new height, in screen coordinates.

using WindowMinimizeFunc = void (*)(const InternalWindow &window, bool restored)

The function pointer type for window minimize/iconfiy callbacks.

Param window:

The window that was minimized/iconified or restored.

Param restored:

True if the window was minimized/iconified, or false if it was restored.

using WindowMaximizeFunc = void (*)(const InternalWindow &window, bool restored)

The function pointer type for window maximize callbacks.

Param window:

The window that was maximized or restored.

Param restored:

True if the window was maximized, or false if it was restored.

using WindowCloseFunc = void (*)(const InternalWindow &window)

The function pointer type for window close callbacks.

Param window:

The window that the user attempted to close.

using WindowFocusFunc = void (*)(const InternalWindow &window, bool focused)

The function pointer type for window focus callbacks.

Param window:

The window that gained or lost input focus.

Param focused:

True if the window was given input focus, or false if it lost it.

using FrameBufferSizeFunc = void (*)(const InternalWindow &window, i32 width, i32 height)

The function pointer type for framebuffer size callbacks.

Param window:

The window whose framebuffer was resized.

Param width:

The new width, in pixels, of the framebuffer.

Param height:

The new height, in pixels, of the framebuffer.

using WindowContentScaleFunc = void (*)(const InternalWindow &window, f32 xScale, f32 yScale)

The function pointer type for window content scale callbacks.

Param window:

The window whose content scale changed.

Param xScale:

The new x-axis content scale of the window.

Param yScale:

The new y-axis content scale of the window.

using MouseButtonFunc = void (*)(const InternalWindow &window, Input::MouseButton mouseButton, TRAP::Input::KeyState state)

The function pointer type for mouse button callbacks.

Param window:

The window that received the event.

Param mouseButton:

The mouse button that was pressed or released.

Param state:

State of the mouse button (pressed or released).

using CursorPositionFunc = void (*)(const InternalWindow &window, f64 xPos, f64 yPos)

The function pointer type for cursor position callbacks.

Param window>The:

window that received the event.

Param xPos:

The new cursor x-coordinate, relative to the left edge of the content area.

Param yPos:

The new cursor y-coordinate, relative to the top edge of the content area.

using CursorEnterFunc = void (*)(const InternalWindow &window, bool entered)

The function pointer type for cursor enter callbacks.

Param window:

The window that received the event.

Param entered:

True if the cursor entered the window’s content area, false if it left it.

using ScrollFunc = void (*)(const InternalWindow &window, f64 xOffset, f64 yOffset)

The function pointer type for scroll callbacks.

Param window:

The window that received the event.

Param xOffset:

The scroll offset along the x-axis.

Param yOffset:

The scroll offset along the y-axis.

using KeyFunc = void (*)(const InternalWindow &window, Input::Key key, Input::KeyState state)

The function pointer type for keyboard key callbacks.

Param window:

The window that received the event.

Param key:

The key that was pressed, repeated or released.

Param state:

The state of the key.

using CharFunc = void (*)(const InternalWindow &window, u32 codePoint)

The function pointer type for Unicode character callbacks.

Param window:

The window that received the event.

Param codePoint:

The Unicode code point of the character.

using DropFunc = void (*)(const InternalWindow &window, std::vector<std::string> paths)

The function pointer type for path drop callbacks.

Param window:

The window that received the event.

Param paths:

The UTF-8 encoded file and/or directory path names.

using MonitorFunc = void (*)(const InternalMonitor &monitor, bool connected)

The function pointer type for monitor configuration callbacks.

Param monitor:

The monitor that was connected or disconnected.

Param connceted:

True if monitor got connceted or false if it got disconnceted.

Public Functions

consteval WindowingAPI() = delete

Constructor.

constexpr ~WindowingAPI() = default

Destructor.

consteval WindowingAPI(const WindowingAPI&) = delete

Copy constructor.

consteval WindowingAPI &operator=(const WindowingAPI&) = delete

Copy assignment operator.

consteval WindowingAPI(WindowingAPI&&) = delete

Move constructor.

consteval WindowingAPI &operator=(WindowingAPI&&) = delete

Move assignment operator.

Public Static Functions

static bool Init()

Initializes the windowing API. Before most WindowingAPI functions can be used, the WindowingAPI must be initialized, and before the engine terminates the WindowingAPI should be terminated in order to free any resources allocated during or after initialization.

If this function fails, it calls WindowingAPI::Shutdown before returning. If it succeeds, WindowingAPI::Shutdown should be called before the engine exits.

Additional calls to this function after successful initialization but before terminiation will return true immediately.

Errors: Possible errors include Error::Platform_Unavailable and Error::Platform_Error.

Remark

X11: This function will set the LC_CTYPE category of the engine locale according to the current environment if that category is still “C”. This is because the “C” locale breaks Unicode text input.

Thread safety

This function must only be called from the main thread.

Returns:

True if windowing API was successfully initialized, false otherwise.

static void Shutdown()

This function destroys all remaining windows and cursor, and frees any other allocated resources. Once this function is called, you must again call WindowingAPI::Init successfully before you will be able to use most WindowingAPI functions.

If the WindowingAPI has been successfully initialized, this function should be called before the engine exits. If initialization fails, there is no need to call this function, as it is called by WindowingAPI::Init before it returns failure. This function has no effect if the WindowingAPI is not initialized.

Possible errors include Error::Platform_Error.

Remark

This function may be called before WindowingAPI::Init.

Reentrancy

This function must not be called from a callback.

Thread safety

This function must only be called from the main thread.

static void DestroyWindow(InternalWindow *window)

This function destroys the specified window. On calling this function, no further callbacks will be called for that window.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Reentrancy

This function must not be called from a callback.

Thread safety

This function must only be called from the main thread.

Parameters:

window – Internal window to destroy.

static void DefaultWindowHints()

Resets all window hints to their default values.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

static void WindowHint(Hint hint, bool value)

This function sets hints for the next call to WindowingAPI::CreateWindow. The hints, once set, retain their values until changed by a call to this function or WindowingAPI::DefaultWindowHints, or until the engine is terminated.

Some hints are platform specific. These may be set on any platform but they will only affect their specific platform. Other platforms will ignore them. Setting these hints requires no platform specific headers or functions.

Errors: Possible errors include Error::Not_Initialized and Error::Invalid_Enum.

Thread safety

This function must only be called from the main thread.

Parameters:

• hint – Hint to set.

• value – Value to set for the Hint.

static std::string GetMonitorName(const InternalMonitor &monitor)

This function returns a human-readable name, encoded as UTF-8, of the specified monitor. The name typically reflects the make and model of the monitor and is not guaranteed to be unique among the connected monitors.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

monitor – InternalMonitor to query name from.

Returns:

Name of the provided monitor.

static InternalMonitor *GetPrimaryMonitor()

This function returns the primary monitor. This is usually the monitor where elements like the task bar or global menu bar are located.

Errors: Possible errors include Error::Not_Initialized.

Remark

The primary monitor is always first in the vector returned by WindowingAPI::GetMonitors.

Thread safety

This function must only be called from the main thread.

Returns:

Primary internal monitor, or nullptr if no monitors were found or if an error occurred.

static std::vector<InternalMonitor*> GetMonitors()

This function returns a vector of handles for all currently connceted monitors. The primary monitor is always first in the returned vector. If no monitors were found, this function returns an empty vector.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Returns:

Vector of all connected monitor handles, or an empty vector if no monitors were found or if an error occurred.

static std::optional<InternalVideoMode> GetVideoMode(InternalMonitor &monitor)

This function returns the current video mode of the specified monitor. If you have created a full screen window for that monitor, the return value will depend on whether that window is minimized/iconified.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

monitor – Internal monitor to get internal video mode from.

Returns:

Current video mode of the specified monitor, or an empty optional if an error occurred.

static std::optional<InternalVideoMode> GetNativeVideoMode(InternalMonitor &monitor)

This function returns the native video mode of the specified monitor. The return value depends on the operating systems monitor settings.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

monitor – Internal monitor to get internal video mode from.

Returns:

Native video mode of the specified monitor, or an empty optional if an error occurred.

static std::vector<InternalVideoMode> GetVideoModes(InternalMonitor &monitor)

This function returns a vector of all video modes supported by the specified monitor. The returned vector is sorted in ascending order, first by color bit depth (the sum of all channel depths) and then by resolution area (the product of width and height).

Errors: Possible errors include: Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

monitor – Internal monitor to get all internal video modes from.

Returns:

Vector with all available video modes of the specified monitor, or an empty vector if an error occurred.

static InternalWindow *CreateWindow(u32 width, u32 height, std::string title, InternalMonitor *monitor)

This function creates a window. Most of the options controlling how the window should be created are specified with window hints.

The created window may differ from what you requested, as not all parameters and hints are hard constraints. This includes the size of the window, especially for full screen windows. To query the actual attributes of the create window, see WindowingAPI::GetWindowHint, WindowingAPI::GetWindowSize and WindowingAPI::GetFramebufferSize.

To create a full screen window, you need to specify the monitor the window will cover. If no monitor is specified, the window will be windowed mode. Unless you have a way for the user to choose a specific monitor, it is recommended that you pick the primary monitor.

For full screen windows, the specified size becomes the resolution of the window’s desired video mode. As long as a full screen window is not minimized/iconified, the supported video mode most closely matching the desired video mode is set for the specified monitor.

Once you have create the window, you can switch it between windowed, borderless full screen (windowed) and full screen mode with WindowingAPI::SetWindowMonitor and WindowingAPI::SetWindowMonitorBorderless.

By default, newly created windows use the placement recommended by the window system. To create the window at a specific position, make it initially invisible using the Hint::Visibile window hint, set its position and then show it.

As long as at least one full screen window is not minimized/iconified, the screensaver is prohibited from starting.

Window systems put limits on window sizes. Very large or very small window dimensions may be overriden by the window system on creation. Check the actual size after creation.

Errors: Possible errors include Error::Not_Initialized, Error::Invalid_Enum, Error::Invalid_Value, Error::Format_Unavailable and Error::Platform_Error.

Remark

Windows:: If the executable has an icon resource named ‘TRAP_ICON’, it will be set as the initial icon for the window. If no such icon is present, the IDI_APPLICATION icon will be used instead. To set a different icon, see WindowingAPI::SetWindowIcon.

Remark

X11: Some window managers will not respect the placement of initially hidden windows. Due to the asynchronous nature of X11, it may take a moment for a window to reach its requested state. This means you may not be able to query the final size, position or other attributes directly after window creation. The class part of the WM_CLASS window property will by default be set to the window title passed to this function. The instance part will use the contents of the RESOURCE_NAME environment variable, if present and not empty, or fall back to the window title.

Remark

Wayland: Compositors should implement the xdg-decoration protocol to decorate the window properly. If this protocol isn’t supported, or if the compositor prefers client-side decorations, a fallback decoration will be drawn using libdecor. If this is also not available then we fallback to a very simple frame using the wp_viewporter protocol. A compositor can still emit close, maximize or fullscreen events, using for instance a keybind mechanism. If neither of these protocols nor libdecor is supported, the window won’t be docorated. A full screen window will not attempt to change the mode, no matter what the requested size or refresh rate. Screensaver inhibition requires the idle-inhibit protocol to be implemented in the user’s compositor.

Thread safety

This function must only be called from the main thread.

Parameters:

• width – Desired width for the new window. Must be greater than zero.

• height – Desired height for the new window. Must be greater than zero.

• title – UTF-8 encoded title for the new window.

• monitor – Optional monitor to use for the new window.

Returns:

On success a new internal window, or nullptr if an error occurred.

static void SetWindowShouldClose(InternalWindow &window, bool value)

This function sets the value of the close flag of the specified window. This can be used to override the user’s attempt to close the window, or to signal that it should be closed.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function may be called from any thread.

Parameters:

• window – Internal window whose flag to change.

• value – Whether to close the window or not.

static void SetWindowTitle(InternalWindow &window, const std::string &title)

This function sets the window title, encoded as UTF-8, of the specified window.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window whose title to change.

• title – New UTF-8 encoded title for the window.

static void GetMonitorContentScale(const InternalMonitor &monitor, f32 &xScale, f32 &yScale)

This function retrieves the content scale for the specified monitor. The content scale is the ratio between the current DPI and the platform’s default DPI. This is especially important for text and any UI elements. If the pixel dimensions of your UI scaled by this look appropriate on your machine then it should appear at a reasonable size on other machines regardless of their DPI and scaling settings. This relies on the system DPI and scaling settings being somewhat correct.

The content scale may depend on both the monitor resolution and pixel density and on user settings. It may be very different from the raw DPI calculated from the physical size and current resolution.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• monitor – Internal monitor.

• xScale – Output variable for the X scale of the provided monitor.

• yScale – Output variable for the Y scale of the provided monitor.

static void DestroyCursor(InternalCursor *cursor)

This function destroys a cursor previously created with CreateCursor. Any remaining cursors will be destroyed by WindowingAPI::Shutdown.

If the specified cursor is current for any window, that window will be reverted to the default cursor. This does not affect the cursor mode.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Reentrancy

This function must not be called from a callback.

Thread safety

This function must only be called from the main thread.

Parameters:

cursor – Internal cursor to be destroyed.

static InternalCursor *CreateCursor(const Image &image, u32 xHotspot, u32 yHotspot)

Creates a new custom cursor image that can be set for a window with SetCursor. The cursor can be destroyed with DestroyCursor. Any remaining cursors are destroyed by WindowingAPI::Shutdown.

The cursor hotspot is specified in pixels, relative to the upper-left corner of the cursor image. Like all other coordinate system in the WindowingAPI, the X-axis points to the right and the Y-axis points down.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• image – Non HDR RGB 24BPP or RGBA 32 BPP image.

• xHotspot – Center x coordinate of the image.

• yHotspot – Center y coordinate of the image.

Returns:

On success new internal cursor, nullptr otherwise.

static InternalCursor *CreateStandardCursor(const CursorType &type)

Creates a cursor with a standard shape.

Errors: Possible errors include Error::Not_Initialized, Error::Invalid_Enum and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

type – Cursor type to get.

Returns:

On success new internal cursor, nullptr otherwise.

static void SetCursor(InternalWindow &window, InternalCursor *cursor)

This function sets the cursor image to be used when the cursor is over the content are of the specified window. The set cursor will only be visible when the CursorMode of the window is CursorMode::Normal.

On some platforms, the set cursor may not be visible unless the window also has input focus.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the cursor for.

• cursor – Internal cursor to set, or nullptr to switch back to the default arrow cursor.

static void SetWindowIcon(InternalWindow &window, const Image *image)

This function sets the icon of the specified window. If no image is specified, the window reverts to its default icon.

The image mustbe RGB 24BPP or RGBA 32BPP.

The desired image size varies depending on platform and system settings. Good sizes include 16x16, 32x32 and 48x48.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Remark

Wayland: There is no existing protocol to change an icon, the window will thus inherit the one defined in the application’s desktop file. This function will emit Error::Feature_Unavailable.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window whose icon to set.

• image – Image to be set as window icon or nullptr to revert back to the default icon.

static void SetWindowPos(const InternalWindow &window, i32 xPos, i32 yPos)

This function sets the position, in screen coordinates, of the upper-left corner of the content area of the specifed windowed mode window. If the window is a full screen window, this function does nothing.

DO NOT USE THIS FUNCTION to move an already visible window unless you have very good reasons for doing so, as it will confuse and annoy the user.

The window manager may put limits on what positions are allowed. The WindowingAPI cannot and should not override these limits.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Remark

Wayland: There is no way for an application to set the global position of its window. This function will emit Error::Feature_Unavailable.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the position for.

• xPos – X position to be set.

• yPos – Y position to be set.

static void GetWindowPos(const InternalWindow &window, i32 &xPos, i32 &yPos)

This function retrieves the position, in screen coordinates, of the upper-left corner of the content area of the specified window.

If an error occurs, xPos and yPos will be set to zero.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Remark

Wayland: There is now way for an application to retrieve the global position of its windows. This function will emit Error::Feature_Unavailable.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to get the current position from.

• xPos – Output variable for the current x position of the internal window.

• yPos – Output variable for the current y position of the internal window.

static void SetWindowSize(InternalWindow &window, i32 width, i32 height)

This function sets the size, in screen coordinates, of the content area of the specified window.

For full screen windows, this function updates the resolution of its desired video mode and switches to the video mode closest to it.

If you wish to update the refresh rate of the desired video mode in addition to its resolution, see WindowingAPI::SetWindowMonitor.

The window manager may put limits on what sizes are allowed. The WindowingAPI cannot and should not override these limits.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Remark

Wayland: A full screen window will not attempt to change the mode, no matter what the requested size.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the size for.

• width – New width for the internal window.

• height – New height for the internal window.

static void GetWindowSize(const InternalWindow &window, i32 &width, i32 &height)

This function retrieves the size, in screen coordinates, of the content area of the specified window. If you wish to retrieve the size of the framebuffer of the window in pixels, see WindowingAPI::GetFrameBufferSize.

If an error occurs, width and height will be set to zero.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to get the size from.

• width – Output variable for the internal windows current width.

• height – Output variable for the internal windows current height.

static void GetFrameBufferSize(const InternalWindow &window, i32 &width, i32 &height)

This function retrieves the size, in pixels, of the framebuffer of the specified window. If you wish to retrieve the size of the window in screen coordinates, see WindowingAPI::GetWindowSize.

If an error occcurs, width and height will be set to zero.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to get the framebuffer size from.

• width – Output variable for the internal windows current framebuffer width.

• height – Output variable for the internal windows current framebuffer height.

static void SetWindowOpacity(const InternalWindow &window, f32 opacity)

This function sets the opacity of the window, including any decorations.

The opacity (or alpha) value is a positive finite number between zero and one, where zero is fully transparent and one is fully opaque.

The initial opacity value for newly created windows is 1.0f.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Remark

Wayland: There is no way to set an opacity factor for a window. This function will emit Error::Feature_Unavailable.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set opacity for.

• opacity – Opacity ranging from 0.0f-1.0f.

static std::optional<f32> GetWindowOpacity(const InternalWindow &window)

This function returns the opacity of the window, including any decorations.

The opacity (or alpha) value is a positive finite number between zero and one, where zero is fully transparent and one is fully opaque. If the system does not support whole window transparency, this function always returns one.

The initial opacity value for newly created windows is 1.0f.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

window – Internal window to get the opacity from.

Returns:

Opacity of the given internal window on success, empty optional otherwise.

static void GetWindowContentScale(const InternalWindow &window, f32 &xScale, f32 &yScale)

This function retrieves the content scale for the specified window. The content scale is the reatio between the current DPI and the platform’s default DPI. This is especially important for text and any UI elements. If the pixel dimensions of your UI scaled by this look appropriate on your machine then it should appear at a reasonable size on other machines regardless of their DPI and scaling settings. This relies on the system DPI and scaling settings being somewhat correct.

On systems where each monitor can have its own content scale, the window content scale will depend on which monitor the system considers the window to be on.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to get the content scale from.

• xScale – Output variable for the internal windows content scale x.

• yScale – Output variable for the internal windows content scale y.

static void SetWindowHint(InternalWindow &window, Hint hint, bool value)

This function sets the value of a hint of the specified window.

Some of these hints are ignored for full screen windows. The new value will take effect if the window is later made windowed.

Some of these hints are ignored for windowed mode windows. The new value will take effect if the window is later made full screen.

Errors: Possible errors include Error::Not_Initialized, Error::Invaild_Enum, Error::Invalid_Value and Error::Platform_Error.

Remark

: Calling WindowingAPI::GetWindowHint will always return the latest value, even if that value is ignored by the current mode of the window.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the hint for.

• hint – Hint to be set.

• value – Value for the hint.

static bool GetWindowHint(const InternalWindow &window, Hint hint)

This function returns the value of a hint of the specified window.

Errors: Possible errors include Error::Not_Initialized, Error::Invalid_Enum and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to get the hint from.

• hint – Hint to query.

Returns:

True if hint is enabled, false otherwise.

static void SetWindowMonitor(InternalWindow &window, InternalMonitor *monitor, i32 xPos, i32 yPos, i32 width, i32 height, f64 refreshRate)

This function sets the monitor that the window uses for full screen mode or, if the monitor is nullptr, makes it windowed mode.

When setting a monitor, this function updates the width, height and refresh rate of the desired video mode and switches to the video mode closest to it. The window position is ignored when setting a monitor.

When the monitor is nullptr, the position, width and height are used to place the window content area. The refresh rate is ignored when no monitor is specified.

If you only wish to update the resolution of a full screen window or the size of a windowed mode window, see WindowingAPI::SetWindowSize.

When a window transitions from full screen to windowed mode, this function restores any previous window settings such as whether it is decorated, floating, resizable, has size limits, etc.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Remark

Wayland: The desired window position is ignored, as there is no way for an application to set this property. Setting the window to full screen will not attempt to change the mode, no matter what the requested size or refresh rate.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the monitor for.

• monitor – Internal monitor to use or nullptr.

• xPos – New x position for the window.

• yPos – New y position for the window.

• width – New width for the window.

• height – New height for the window.

• refreshRate – New refresh rate for the window.

static void SetWindowMonitorBorderless(InternalWindow &window, InternalMonitor &monitor)

This function sets the monitor that the window uses for borderless full screen mode.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the monitor for.

• monitor – Internal monitor to use.

static void SetWindowUserPointer(InternalWindow &window, void *ptr)

This function sets the user-define dpointer of the specified window. The current value is retained until the window is destroyed. The initial value is nullptr.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function may be called from any thread.

Parameters:

• window – Internal window to set the user pointer for.

• ptr – Data to be stored with the window.

static void *GetWindowUserPointer(const InternalWindow &window)

This function returns the current value of the user-defined pointer of the specified window. The initial value is nullptr.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function may be called from any thread.

Parameters:

window – Internal window to get the user pointer from.

Returns:

Data stored with the window.

static void SetMonitorCallback(MonitorFunc callback)

This function sets the monitor configuration callback, or removes the currently set callback. This is called when a monitor is connected to or disconnected from the system.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

callback – Function to call when a monitor event occurs, or nullptr to remove the currently set callback.

static void SetWindowPosCallback(InternalWindow &window, WindowPositionFunc callback)

This function sets the position callback of the specified window, which is called when the window is moved. The callback is provided with the position, in screen coordinates, of the upper-left corner of the content area of the window.

Errors: Possible errors include Error::Not_Initialized.

Remark

Wayland: This callback will never by called, as there is no way for an application to know its global position.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a position event occurs, or nullptr to remove the currently set callback.

static void SetWindowSizeCallback(InternalWindow &window, WindowSizeFunc callback)

This function sets the size callback of the specified window, which is called when the window is resized. The callback is provided with the size, in screen coordinates, of the content area of the window.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a size event occurs, or nullptr to remove the currently set callback.

static void SetWindowMinimizeCallback(InternalWindow &window, WindowMinimizeFunc callback)

This function sets the minimization/iconification callback of the specified window, which is called when the window is minimized/iconified or restored.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a minimize event occurs, or nullptr to remove the currently set callback.

static void SetWindowMaximizeCallback(InternalWindow &window, WindowMaximizeFunc callback)

This function sets the maximization callback of the specified window, which is called when the window is maximized or restored.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a maximize event occurs, or nullptr to remove the currently set callback.

static void SetWindowCloseCallback(InternalWindow &window, WindowCloseFunc callback)

This function sets the close callback of the specified window, which is called when the user attempts to close the window, for example by clicking the close widget in the title bar.

The close flags is set before this callback is called, but you can modify it at any time with WindowingAPI::SetWindowShouldClose.

The close callback is not triggered by WindowingAPI::DestroyWindow.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a close event occurs, or nullptr to remove the currently set callback.

static void SetWindowFocusCallback(InternalWindow &window, WindowFocusFunc callback)

This function sets the focus callback of the specified window, which is called when the window gains or loses input focus.

After the focus callback is called for a window that lost input focus, synthetic key and mouse button release events will be generated for all such that had been pressed. For more information, see WindowingAPI::SetKeyCallback and WindowingAPI::SetMouseButtonCallback.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a focus event occurs, or nullptr to remove the currently set callback.

static void SetFrameBufferSizeCallback(InternalWindow &window, FrameBufferSizeFunc callback)

This function sets the framebuffer resize callback of the specified window, which is called when the framebuffer of the specified window is resized.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a framebuffer size event occurs, or nullptr to remove the currently set callback.

static void SetContentScaleCallback(InternalWindow &window, WindowContentScaleFunc callback)

This function sets the window content scale callback of the specified window, which is called when the content scale of the specified window changes.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a content scale event occurs, or nullptr to remove the currently set callback.

static void SetKeyCallback(InternalWindow &window, KeyFunc callback)

This function sets the key callback of the specified window, which is called when a key is pressed, repeated or released.

The key functions deal with physical keys, with layout independent key tokens named after their values in the standard US keyboard layout. If oyu want to input text, use the character callback instead.

When a window loses input focus, it will generate synthetic key release events for all pressed named keys. You can tell these events from user-generated events by the fact that the synthetic ones are generated after the focus loss event has been processed, i.e. after the window focus callback has been called.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a key event occurs, or nullptr to remove the currently set callback.

static void SetCharCallback(InternalWindow &window, CharFunc callback)

This function sets the character callback of the specified window, which is called when a Unicode character is input.

The character callback is intended for Unicode text input. As it deals with characters, it is keyboard layout dependent. whereas the key callback is not. Characters do not map 1:1 to physical keys, as a key may produce zero, one or more character. If you want to know whether a specific physical key was pressed or released, see the key callback instead.

The character callback behaves as system text input normally does and will not be called if modifier keys are held down that would prevent normal text input on that platform, for example Alt key on Windows.

Erros: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a char event occurs, or nullptr to remove the currently set callback.

static void SetMouseButtonCallback(InternalWindow &window, MouseButtonFunc callback)

This function sets the mouse button callback of the specified window, which is called when amouse button is pressed or released.

When a window loses input focus, it will generate synthetic mouse button release events for all pressed mouse buttons. You cann tell these events from user-generated events by the fact that the synthetic ones are generated after the focus loss event has been processed, i.e. after the window focus callback has been called.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a mouse button event occurs, or nullptr to remove the currently set callback.

static void SetCursorPosCallback(InternalWindow &window, CursorPositionFunc callback)

This function sets the cursor position callback of the specified window, which is called when the cursor is moved. The callback is provided with the position, in screen coordinates, relative to the upper-left corner of the content area of the window.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a cursor position event occurs, or nullptr to remove the currently set callback.

static void SetCursorEnterCallback(InternalWindow &window, CursorEnterFunc callback)

This function sets the cursor boundary crossing callback of the specified window, which is called when the cursor enters or leaves the content area of the window.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This fucntion must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a cursor enter event occurs, or nullptr to remove the currently set callback.

static void SetScrollCallback(InternalWindow &window, ScrollFunc callback)

This function sets the scroll callback of the specified window, which is called when a scrolling device is used, such as a mouse wheel or scrolling area of a touchpad.

The scroll callback receives all scrolling input, like that from a mouse wheel or a touchpad scrolling area.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a scroll event occurs, or nullptr to remove the currently set callback.

static void SetDropCallback(InternalWindow &window, DropFunc callback)

This function sets the path drop callback of the specified window, which is called when one or more dragged paths are dropped on the window.

Errors: Possible errors include Error::Not_Initialized.

Remark

Wayland: File drop is currently unimplemented.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the callback for.

• callback – Function to call when a drop even occurs, or nullptr to remove the currently set callback.

static MonitorFunc GetMonitorCallback()

Gets the monitor configuration callback.

Returns:

Function that gets called when a monitor event occurs.

static constexpr WindowPositionFunc GetWindowPosCallback(const InternalWindow &window)

Gets the position callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a position event occurs.

static constexpr WindowSizeFunc GetWindowSizeCallback(const InternalWindow &window)

Gets the size callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a size event occurs.

static constexpr WindowCloseFunc GetWindowCloseCallback(const InternalWindow &window)

Gets the close callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a close event occurs.

static constexpr WindowFocusFunc GetWindowFocusCallback(const InternalWindow &window)

Gets the focus callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a focus event occurs.

static constexpr FrameBufferSizeFunc GetFrameBufferSizeCallback(const InternalWindow &window)

Gets the framebuffer resize callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a framebuffer size event occurs.

static constexpr WindowContentScaleFunc GetWindowContentScaleCallback(const InternalWindow &window)

Gets the window content scale callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a content scale event occurs.

static constexpr KeyFunc GetKeyCallback(const InternalWindow &window)

Gets the key callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a key event occurs.

static constexpr CharFunc GetCharCallback(const InternalWindow &window)

Gets the Unicode character callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a char event occurs.

static constexpr MouseButtonFunc GetMouseButtonCallback(const InternalWindow &window)

Gets the mouse button callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a mouse button event occurs.

static constexpr CursorPositionFunc GetCursorPosCallback(const InternalWindow &window)

Gets the cursor position callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a cursor position event occurs.

static constexpr CursorEnterFunc GetCursorEnterCallback(const InternalWindow &window)

Gets the cursor enter callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a cursor enter event occurs.

static constexpr ScrollFunc GetScrollCallback(const InternalWindow &window)

Gets the scroll callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a scroll event occurs.

static constexpr DropFunc GetDropCallback(const InternalWindow &window)

Gets the path drop callback for the specified window.

Parameters:

window – Internal window from which to query the callback from.

Returns:

Function that gets called when a drop event occurs.

static void PollEvents()

This function processes only those events that are already in the event queue and then returns immediately. Processing events will cause the window and input callbacks associated with those events to be called.

On some platforms, a window move, resize or menu operation will cause event processing to block. This is due to how event processing is designed on those platforms.

Do not assume that callbacks you set will only be called in response to event processing functions like this one. While it is necessary to poll for events, window systems that require the WindowingAPI to register callbacks of its own can pass evnts to the WindowingAPI in response to many window system function calls. The WindowingAPI will pass those events on to the application callbacks before returning.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Reentrancy

This function must not be called from a callback.

Thread safety

This function must only be called from the main thread.

static void WaitEvents(f64 timeout = 0.0)

This function puts the calling thread to sleep until at least one event is available in the event queue, or until the specified timeout is reached. Once one or more events are available, it behaves exactly like PollEvents, i.e. the events in the queue are processed and the function then returns immediately. Processing events will cause the window and input callbacks associated with those events to be called.

Since not all events are associated with callbacks, this function may return without a callback having been called even if you are monitoring all callbacks.

On some platforms, a window move, resize or menu operation will cause event processing to block. This is due to how event processing is designed on those platforms.

Do not assume that callbacks you set will only be called in response to event processing functions like this one. While it is neccessary to poll for events, window systems that require the WindowingAPI to register callbacks of its own can pass events to the WindowingAPI in response to many window system function calls. The WindowingAPI will pass those events on to the application callbacks before returning.

Errors: Possible errors include Error::Not_Initialized, Error::Invalid_Value and Error::Platform_Error.

Reentrancy

This function must not be called from a callback.

Thread safety

This function must only be called from the main thread.

Parameters:

timeout – Optional: Maximum amount of time, in seconds, to wait.

static void PostEmptyEvent()

This function posts an empty event from the current thread to the event queue, causing WaitEvents to return.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function may be called from any thread.

static void SetCursorMode(InternalWindow &window, CursorMode mode)

This function sets a cursor mode for the specified window.

The mode must be one of the following CursorModes:

• Normal makes the cursor visible and behaving normally.

• Hidden makes the cursor invisible when it is over the content area of the window but does not restrict the cursor from leaving.

• Disabled hides and grabs the cursor, providing virtual and unlimited cursor movement.

• Captured makes the cursor visible and confines it to the content area of the window.

Errors: Possible errors include Error::Not_Initialized, Error::Invalid_Enum and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the cursor mode for.

• mode – Cursor mode to be set.

static CursorMode GetCursorMode(const InternalWindow &window)

Retrieves the cursor mode from the specified window.

Parameters:

window – Internal window to query the cursor mode from.

Returns:

Cursor mode used by the internal window.

static bool RawMouseMotionSupported()

This function returns whether raw mouse motion is supported on the current system. This status does not change after the WindowingAPI has been initialized so you only need to check this once. If you attemp to enable raw motion on a system that does not support it, Error::Platform_Error will be emitted.

Raw mouse motion is closer to the actual motion of the mouse across a surface. It is not affected by the scaling and acceleration applied to the motion of the desktop cursor. That processing is suitable for a cursor while raw motion is better for controlling for example a 3D camera. Because of this, raw mouse motion is only provided when the cursor is disabled.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function must only be called from the main thread.

Returns:

True if raw mouse input is supported, false otherwise.

static void SetRawMouseMotionMode(InternalWindow &window, bool enabled)

Sets the raw mouse motion mode for the specified window.

If raw (unscaled and unaccelerated) mouse motion is not supported, attempting to set this will emit Error::Feature_Unavailable.

Errors: Possible errors include Error::Not_Initialized, Error::Invalid_Enum, Error::Platform_Error and Error::Feature_Unavailable.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set raw mouse input for.

• enabled – Whether to enable or disable raw mouse input.

static bool GetRawMouseMotionMode(const InternalWindow &window)

Retrieves the raw mouse motion mode for the specified window.

Parameters:

window – Internal window to query.

Returns:

True if raw mouse motion mode is enabled, false otherwise.

static void SetWindowProgressIndicator(const InternalWindow &window, ProgressState state, f64 progress)

Sets the dock or taskbar progress indicator of the specified window.

Linux: This only works on KDE & Unity environments. A .desktop file must exist for the application with the same name as given to TRAP::Application.

Errors: Possible errors include Error::Not_Initialized, Error::Invalid_Value, Error::Invalid_Enum, Error::Platform_Error, Error::Feature_Unimplemented

Remark

X11: Wayland: Requires a valid application desktop file with the same name as the compiled executable. Due to limitations in the Unity Launcher API ProgressState::Indeterminate, ProgressState::Error and ProgressState::Paused have the same behaviour as ProgressState::Normal. The Unity Launcher API is only known to be supported on Unity and KDE desktop environments; on other desktop environments this function may do nothing.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set progress for.

• state – State of progress to be displayed in the dock or taskbar.

• progress – The amount of completed progress to set. Valid range is [0.0-1.0]. This parameter is ignored if state is ProgressState::Disabled

static std::optional<std::string> GetKeyName(Input::Key key, i32 scanCode)

This function returns the name of the specified printable key, encoded as UTF-8. This is typically the character that key would produce without any modifier keys, intended for displaying key bindings to the user. For dead keys, it is typically the diacritic it would add to a character.

DO NOT USE THIS FUNCTION for text input. You will break text input for many languages even if it happens to work for yours.

If the key is Input::Key::Unknown, the scancode is used to identify the key, otherwise the scancode is ignored. If you specify a non-printable key, or Input::Key::Unknown and a scancode that maps to a non-printable key, this function return nullopt but does not emit an error.

This behaviour allows you to always pass in the arguments in the key callback without modification.

The printable keys are: Input::Key::Apostrophe Input::Key::Comma Input::Key::Minus Input::Key::Period Input::Key::Slash Input::Key::Semicolon Input::Key::Equal Input::Key::Left_Bracket Input::Key::Right_Bracket Input::Key::Backslash Input::Key::World_1 Input::Key::World_2 Input::Key::Zero to Input::Key::Nine Input::Key::A to Input::Key::Z Input::Key::KP_0 to Input::Key::KP_9 Input::Key::KP_Decimal Input::Key::KP_Divide Input::Key::KP_Multiply Input::Key::KP_Subtract Input::Key::KP_Add Input::Key::KP_Equal

Names for printable keys depend on keyboard layout, while names for non-printable keys are the same across layouts but depend on the application language and should be localized along with other user interface text.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Remark

: The contents of the returned string may change when a keyboard layout change event is received. Pointer lifetime: The returned string is allocated and freed by the WindowingAPI. You should not free it yourself. It is valid until the library is terminated.

Thread safety

This function must only be called from the main thread.

Parameters:

• key – Key to get layout-specific name from.

• scanCode – Optional scan code to get layout-specific name from.

Returns:

UTF-8 encoded, layout-specific name of the given key or nullptr.

static TRAP::Input::KeyState GetKey(const InternalWindow &window, Input::Key key)

This function returns the last state reported for the specified key to the specified window. The returned state is KeyState::Pressed or KeyState::Released.

The key functions deal with physical keys, with key token named after their use on the standard US keyboard layout. If you want to input text, use the Unicode character callback instead.

DO NOT USE THIS FUNCTION to implement text input.

Errors: Possible errors include Error::Not_Initialized and Error::Invalid_Enum.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to query.

• key – Key to get last reported state from.

Returns:

Last reported state of the specified key.

static TRAP::Input::KeyState GetMouseButton(const InternalWindow &window, Input::MouseButton button)

This function returns the last state reported for the specified mouse button to the specified window. The returned state is pressed (true) or released (false).

Errors: Possible errors include Error::Not_Initialized and Error::Invalid_Enum.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to query.

• button – Mouse button to get last reported state from.

Returns:

Last reported state of the specified mouse button.

static void SetCursorPos(InternalWindow &window, f64 xPos, f64 yPos)

This function sets the position, in screen coordinates, of the cursor relative to the upper-left corner of the content area of the specified window. The window must have input focus. If the window does not have input focus when this function is called, it fails silently.

DO NOT USE THIS FUNCTION to implement things like camera controls. The WindowingAPI already provides the CursorMode::Disabled that hides the cursor, transparently re-centers it and provides unconstrained cursor motion. See SetCursorMode for more information.

If the cursor mode is CursorMode::Disabled then the cursor position is unconstrained and limited only by the minimum and maximum values of a f64.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Remark

Wayland: This function will only work when the cursor mode is CursorMode::Disabled, otherwise it will emit Error::Feature_Unavailable.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set the cursor position for.

• xPos – New x position, relative to the left edge of the content area, for the cursor.

• yPos – New y position, relative to the top edge of the content area, for the cursor.

static void GetCursorPos(const InternalWindow &window, f64 &xPos, f64 &yPos)

This function returns the position of the cursor, in screen coordinates, relative to the upper-left corner of the content area of the specified window.

If the cursor is disabled (with CursorMode::Disabled) then the cursor position is unbounded and limited only by the minimum and maximum values of a f64.

The coordinate can be converted to their integer equivalents with the TRAP::Math::Floor function. Casting directly to an integer type works for positive coordinates, but fails for negative ones.

If an error occurs, xPos and yPos will be set to zero.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window from which to get the current cursor position.

• xPos – Output variable for the current x position, relative to the left edge of the content area, of the cursor.

• yPos – Output variable for the current y position, relative to the top edge of the content area, of the cursor.

static void GetMonitorPos(const InternalMonitor &monitor, i32 &xPos, i32 &yPos)

Returns the position of the monitor’s viewport on the virtual screen. This function returns the position, in screen coordinates, of the upper-left corner of the specified monitor.

If an error occurs, xPos and yPos will be set to zero.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• monitor – Internal monitor to query.

• xPos – Output variable for the x position of the monitor.

• yPos – Output variable for the y position of the monitor.

static void GetMonitorWorkArea(const InternalMonitor &monitor, i32 &xPos, i32 &yPos, i32 &width, i32 &height)

This function returns the position, in screen coordinates, of the upper-left corner of the work area of the specified monitor along with the work area size in screen coordinates. The work area is defined as the area of the monitor not occluded by the operating system task bar where present. If no task bar exists then the work area is the monitor resolution in screen coordinates.

If an error occurs, xPos, yPos, width and height will be set to zero.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

• monitor – Internal monitor to query.

• xPos – Output variable for the x position of the monitor.

• yPos – Output variable for the y position of the monitor.

• width – Output variable for the width of the monitor.

• height – Output variable for the height of the monitor.

static void ShowWindow(InternalWindow &window)

This function makes the specified window visible if it was previously hidden. If the window is already visible or is in full screen mode, this function does nothing.

By default, windowed mode window are focused when shown. Set the Hint::FocusOnShow window hint to change this behaviour for all newly created windows, or change the behaviour for and existing window with WindowingAPI::SetWindowHint.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Remark

Wayland: Because Wayland wants every frame of the desktop to be complete, this function does not immediately make the window visible. Instead it will become visible the next time the window framebuffer is updated after this call.

Thread safety

This function must only be called from the main thread.

Parameters:

window – Internal window to display.

static void FocusWindow(const InternalWindow &window)

This function brings the specified window to front and sets input focus. The window should already be visible and not minimized/iconified.

By default, both windowed and full screen mode windows are focused when initially created. Set the Hint::Focused hint to disable this behaviour.

Also by default windowed mode windows are focused when shown with WindowingAPI::ShowWindow. Set the Hint::FocusOnShow hint to disable this behaviour.

DO NOT USE THIS FUNCTION to steal focus from other applications unless you are certain that is what the user wants. Focus stealing can be extremely disruptive.

For a less disruptive way of gettings the user’s attention, see WindowingAPI::RequestWindowAttention.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Remark

Wayland: It is not possible for an application to set the input focus. This function will emit Error::Feature_Unavailable.

Thread safety

This function must only be called from the main thread.

Parameters:

window – Internal window to focus.

static void MaximizeWindow(InternalWindow &window)

This function maximizes the specified window if it was previously not maximized. If the window is already maximized, this function does nothing.

If the specified window is a full screen window, this function does nothing.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function may only be called from the main thread.

Parameters:

window – Internal window to maximize.

static void MinimizeWindow(const InternalWindow &window)

This function minimizes (iconifies) the specified window if it was previously restored. If the window is already minimized (iconified), this function does nothing.

If the specified window is a full screen window, the original monitor resolution is restored util the window is restored.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Remark

Wayland: Once a window is minimized, RestoreWindow won’t be able to restore it. This is a design decision of the xdg-shell protocol.

Thread safety

This function must only be called from the main thread.

Parameters:

window – Internal window to minimize/iconify.

static void RequestWindowAttention(InternalWindow &window)

This function requests user attention to the specified window. On platforms where this is not supported, attention is requested to the application as a whole.

Once the user has given attention, usually by focusing the window or application, the system will end the request automatically.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

window – Internal window to request user attention for.

static void HideWindow(InternalWindow &window)

This function hides the specified window if it was previously visible. If the window is already hidden or is in full screen mode, this function does nothing.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

window – Internal window to hide.

static void RestoreWindow(InternalWindow &window)

Restores the specified window. This function restores the specified window if it was previously minimized (iconified) or maximized. If the window is already restored, this function does nothing.

If the specified window is a full screen window, the resolution chosen for the window is restored on the selected monitor.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Parameters:

window – Internal window to be restored.

static void SetWindowSizeLimits(InternalWindow &window, i32 minWidth, i32 minHeight, i32 maxWidth, i32 maxHeight)

Sets the size limits of the specified window.

Wayland: The size limits will not be applied until the window is actually resized, either by the user or by the compositor. This function sets the size limits of the content area of the specified window. If the window is full screen, the size limits only take effect once it is made windowed. If the window is not resizable, this function does nothing.

The size limits are applied immediately to a windowed mode window and may cause it to be resized.

The maximum dimensions must be greater than or equal to the minimum dimensions and all must be greater than zero.

Use -1 to disable to minimum and/or maximum size constraints.

Errors: Possible errors include Error::Not_Initialized, Error::Invalid_Value and Error::Platform_Error.

Remark

Wayland: The size limits will not be applied until the window is actually resized, either by the user or by the compositor.

Thread safety

This function must only be called from the main thread.

Parameters:

• window – Internal window to set size limits for.

• minWidth – New minimum window width.

• minHeight – New minimum window height.

• maxWidth – New maximum window width.

• maxHeight – New maximum window height.

static void SetWindowAspectRatio(InternalWindow &window, i32 numerator, i32 denominator)

Sets the aspect ratio of the specified window.

Wayland: The aspect ratio will not be applied until the window is actually resized, either by the user or by the compositor.

This function sets the required aspect ratio of the content area of the specified window. If the window if full screen, the aspect ratio only takes effect once it is made windowed. If the window is not resizable, this function does nothing.

The aspect ratio is specified as a numerator and a denominator and both values must be greater than 0. For example, the common 16:9 aspect ratio is specified as 16 and 9, respectively.

If the numerator and denominator are set to -1 then the aspect ratio limit gets disabled.

The aspect ratio is applied immediately to a windowed mode window and may cause it to be resized.

Errors: Possible errors include Error::Not_Initialized, Error::Invalid_Value and Error::Platform_Error.

Remark

Wayland: The aspect ratio will not be applied until the window is actually resized, either by the user or by the compositor.

Thread safety

This function must only be called from the main thread.

Note

If you set the size limits and an aspect ratio that conflict, the results are undefined.

Parameters:

• window – Internal window to set aspect ratio for.

• numerator – Numerator of the desired aspect ratio, or -1.

• denominator – Denominator of the desired aspect ratio, or -1.

static void SetClipboardString(const std::string &string)

This function sets the system clipboard to the specified, UTF-8 encoded string.

Errors: Possible errors include Error::Not_Initialized, Error::Format_Unavailable and Error::Platform_Error. Pointer lifetime: The specified string is copied before this function returns.

Thread safety

This function must only be called from the main thread.

Parameters:

string – UTF-8 encoded string to be set for the clipboard.

static std::string GetClipboardString()

This function returns the contents of the system clipboard, if it contains or is convertible to a UTF-8 encoded string. If the clipboard is empty or if its content cannot be converted, an empty string is returned and a Error::Format_Unavailable error is generated.

Errors: Possible errors include Error::Not_Initialized and Error::Platform_Error.

Thread safety

This function must only be called from the main thread.

Returns:

UTF-8 encoded string containing clipboard contents, or empty string if an error occurred.

static bool VulkanSupported()

This function returns whether the Vulkan loader and any minimally function ICD have been found.

The availability of a Vulkan loader and even an ICD does not by itself guarantee that surface creation or even instance creation is possible. Call GetRequiredInstanceExtensions to check whether the extensions necessary for Vulkan surface creation are available. You still have to check whether a queue family of a physical device supports image presentation.

Errors: Possible errors include Error::Not_Initialized.

Thread safety

This function may be called from any thread.

Returns:

True if Vulkan API is minimally supported, false otherwise.

static std::array<std::string, 2> GetRequiredInstanceExtensions()

This function returns an array of names of Vulkan instance extensions required by the WindowingAPI for creating Vulkan surface for WindowingAPI windows. If successful, the list will always contain VK_KHR_surface, so if you don’t require any additional extensions you can pass this list directly to the VkInstanceCreateInfo struct.

If Vulkan is not available on the machine, this function return an array with empty strings and generates a Error::API_Unavailable error. Call WindowingAPI::VulkanSupported to check whether Vulkan is at least minimally available.

If Vulkan is available but no set of extensions allowing window surface creation was found, this function returns an array with empty strings. You may still use Vulkan for off-screen rendering and compute work.

Errors: Possible errors include Error::Not_Initialized and Error::API_Unavailable.

Remark

: Additional extensions may be required by future versions of the WindowingAPI. You should check if any extensions you wish to enable are already in the returned array, as it is an error to specify an extension more than once in the VkInstanceCreateInfo struct.

Thread safety

This function may be called from any thread.

Returns:

Array containing the required instance extensions, or an array with empty string if an error occurred.

static VkResult CreateWindowSurface(VkInstance instance, const InternalWindow &window, const VkAllocationCallbacks *allocator, VkSurfaceKHR &surface)

Creates a Vulkan surface for the specified window. This function create a Vulkan surface for the specified window.

If the Vulkan loader or at least one minimally functiona ICD were not found, this function return VK_ERROR_INITIALIZATION_FAILED and generates a Error::API_Unavilable error. Call WindowingAPI::VulkanSupported to check whether Vulkan is at least minimally available.

If the required window surface creation instance extensions are not available or if the specified instance was not created with these extensions enabled, this function returns VK_ERROR_EXTENSION_NOT_PRESENT and generates a Error::API_Unavailable error. Call WindowingAPI::GetRequiredInstanceExtensions to check what instance extensions are required.

The window surface must be destroyed before the specified Vulkan instance. It is the responsibility of the caller to destroy the window surface. The WindowingAPI does not destroy it for you. Call vkDestroySurfaceKHR to destroy the surface.

Errors: Possible errors include Error::Not_Initialized, Error::API_Unavailable, Error::Platform_Error and Error::Invalid_Value.

Remark

: If an error occurs before the creation call is made, the WindowingAPI returns the Vulkan error code most appropriate for the error. Appropriate use of WindowingAPI::VulkanSupported and WindowingAPI::GetRequiredInstanceExtensions should eliminate almost all occurrences of these errors.

Thread safety

This function may be called from any thread.

Parameters:

• instance – Vulkan instance.

• window – Internal window for which to create the surface for.

• allocator – Optional allocator.

• surface – Output variable for the new Vulkan surface.

Returns:

VK_SUCCESS if successful, or a Vulkan error code if an error occurred.

static void HideWindowFromTaskbar(InternalWindow &window)

Hides the specified window from the taskbar.

Parameters:

window – Internal window to hide from the taskbar.

static void SetDragAndDrop(InternalWindow &window, bool value)

Enable/Disable drag and drop feature for the specified window.

Parameters:

• window – Internal window for which to set drag and drop.

• value – Whether to enable or disable drag and drop.

struct InternalCursor

Cursor structure.

struct InternalMonitor

Monitor structure.

Public Members

std::string Name = {}

InternalWindow *Window = nullptr

std::vector<InternalVideoMode> Modes = {}

InternalVideoMode CurrentMode = {}

std::optional<InternalVideoMode> NativeMode = std::nullopt

struct InternalVideoMode

This describes a single video mode.

Public Functions

constexpr auto operator<=>(const InternalVideoMode &other) const noexcept = default

Public Members

i32 Width = 0

i32 Height = 0

i32 RedBits = 0

i32 GreenBits = 0

i32 BlueBits = 0

f64 RefreshRate = 0

struct InternalWindow

Window structure.

Public Members

bool Resizable = true

bool Decorated = true

bool Floating = false

bool ShouldClose = false

bool FocusOnShow = true

bool MousePassthrough = false

bool DragAndDrop = false

bool BorderlessFullscreen = false

void *UserPointer = nullptr

InternalVideoMode videoMode = {}

InternalMonitor *Monitor = nullptr

InternalCursor *Cursor = nullptr

i32 MinWidth = -1

i32 MinHeight = -1

i32 MaxWidth = -1

i32 MaxHeight = -1

i32 Numerator = -1

i32 Denominator = -1

CursorMode cursorMode = CursorMode::Normal

std::array<TRAP::Input::KeyState, std::to_underlying(TRAP::Input::MouseButton::Eight) + 1> MouseButtons = {}

std::array<TRAP::Input::KeyState, std::to_underlying(TRAP::Input::Key::Menu) + 1> Keys = {}

f64 VirtualCursorPosX = 0.0

f64 VirtualCursorPosY = 0.0

bool RawMouseMotion = false

WindowPositionFunc Pos = nullptr

WindowSizeFunc Size = nullptr

WindowMinimizeFunc Minimize = nullptr

WindowMaximizeFunc Maximize = nullptr

WindowCloseFunc Close = nullptr

WindowFocusFunc Focus = nullptr

FrameBufferSizeFunc FBSize = nullptr

WindowContentScaleFunc Scale = nullptr

MouseButtonFunc MouseButton = nullptr

CursorPositionFunc CursorPos = nullptr

CursorEnterFunc CursorEnter = nullptr

ScrollFunc Scroll = nullptr

KeyFunc Key = nullptr

CharFunc Character = nullptr

DropFunc Drop = nullptr

struct TRAP::INTERNAL::WindowingAPI::InternalWindow::[anonymous] Callbacks

bool Minimized = false

bool Maximized = false

i32 LastCursorPosX = 0

i32 LastCursorPosY = 0

i32 Width = 0

i32 Height = 0