Zakero's C++ Header Libraries
A collection of reusable C++ libraries
Public Member Functions | List of all members
zakero::Xenium::Window Class Reference

A Window. More...

Public Member Functions

 Window (Xenium *, void *)
 Construct a Window. More...
 
virtual ~Window ()
 Destroy a Window.
 
uint8_t bytesPerPixel () const noexcept
 Get the number of bytes per pixel. More...
 
void classSet (const std::string &) noexcept
 Change the window class. More...
 
Xenium::PointMm convertToMm (const Xenium::PointPixel &) const noexcept
 Unit conversion. More...
 
Xenium::SizeMm convertToMm (const Xenium::SizePixel &) const noexcept
 Unit conversion. More...
 
Xenium::PointPercent convertToPercent (const Xenium::PointPixel &) const noexcept
 Unit conversion. More...
 
Xenium::SizePercent convertToPercent (const Xenium::SizePixel &) const noexcept
 Unit conversion. More...
 
Xenium::PointPixel convertToPixel (const Xenium::PointMm &) const noexcept
 Unit conversion. More...
 
Xenium::PointPixel convertToPixel (const Xenium::PointPercent &) const noexcept
 Unit conversion. More...
 
Xenium::SizePixel convertToPixel (const Xenium::SizeMm &) const noexcept
 Unit conversion. More...
 
Xenium::SizePixel convertToPixel (const Xenium::SizePercent &) const noexcept
 Unit conversion. More...
 
void decorationsOnChange (Xenium::LambdaWindowDecorations) noexcept
 Respond to "Decoration Change" events. More...
 
std::error_code decorationsSet (const Xenium::WindowDecorations) noexcept
 Use the Desktop Environment borders. More...
 
std::error_code imageNext (uint8_t *&, Xenium::SizePixel &) noexcept
 Get an image buffer. More...
 
void imagePresent () noexcept
 Render the image. More...
 
void keyboardOnEnter (Xenium::Lambda) noexcept
 Respond to "Keyboard Enter" events. More...
 
void keyboardOnKey (Xenium::LambdaKey) noexcept
 Respond to "Keyboard Key" events. More...
 
void keyboardOnLeave (Xenium::Lambda) noexcept
 Respond to "Keyboard Leave" events. More...
 
std::error_code minimize () noexcept
 Minimize the window. More...
 
void onCloseRequest (Xenium::Lambda) noexcept
 Respond to "Close Request" events. More...
 
void onFocusChange (Xenium::LambdaBool) noexcept
 Respond to "Active" change events. More...
 
void pointerOnAxis (Xenium::LambdaAxis) noexcept
 Respond to "Pointer Axis" events. More...
 
void pointerOnButton (Xenium::LambdaButtonMm) noexcept
 Respond to "Pointer Button" events. More...
 
void pointerOnButton (Xenium::LambdaButtonPercent) noexcept
 Respond to "Pointer Button" events. More...
 
void pointerOnButton (Xenium::LambdaButtonPixel) noexcept
 Respond to "Pointer Button" events. More...
 
void pointerOnEnter (Xenium::LambdaPointMm) noexcept
 Respond to "Pointer Enter" events. More...
 
void pointerOnEnter (Xenium::LambdaPointPercent) noexcept
 Respond to "Pointer Enter" events. More...
 
void pointerOnEnter (Xenium::LambdaPointPixel) noexcept
 Respond to "Pointer Enter" events. More...
 
void pointerOnLeave (Xenium::Lambda) noexcept
 Respond to "Pointer Leave" events. More...
 
void pointerOnMotion (Xenium::LambdaPointMm) noexcept
 Respond to "Pointer Motion" events. More...
 
void pointerOnMotion (Xenium::LambdaPointPercent) noexcept
 Respond to "Pointer Motion" events. More...
 
void pointerOnMotion (Xenium::LambdaPointPixel) noexcept
 Respond to "Pointer Motion" events. More...
 
void sizeOnChange (Xenium::LambdaSizeMm) noexcept
 Respond to "Resize" events. More...
 
void sizeOnChange (Xenium::LambdaSizePercent) noexcept
 Respond to "Resize" events. More...
 
void sizeOnChange (Xenium::LambdaSizePixel) noexcept
 Respond to "Resize" events. More...
 
std::error_code sizeSet (const Xenium::SizeMm &) noexcept
 Set the window size. More...
 
std::error_code sizeSet (const Xenium::SizePercent &) noexcept
 Set the window size. More...
 
std::error_code sizeSet (const Xenium::SizePixel &) noexcept
 Set the window size. More...
 
std::error_code sizeSetMinMax (const Xenium::SizeMm &, const Xenium::SizeMm &) noexcept
 Set the minimum window size. More...
 
std::error_code sizeSetMinMax (const Xenium::SizePercent &, const Xenium::SizePercent &) noexcept
 Set the minimum window size. More...
 
std::error_code sizeSetMinMax (const Xenium::SizePixel &, const Xenium::SizePixel &) noexcept
 Set the minimum window size. More...
 
uint32_t time () const noexcept
 When the last frame was rendered. More...
 
void titleSet (const std::string &) noexcept
 Change the window title. More...
 
Xenium::WindowMode windowMode () const noexcept
 Get the current WindowMode. More...
 
bool windowModeIs (const Xenium::WindowMode) const noexcept
 Check the WindowMode. More...
 
void windowModeOnChange (Xenium::LambdaWindowMode) noexcept
 Respond to "Window Mode" events. More...
 
std::error_code windowModeSet (const Xenium::WindowMode) noexcept
 Change the window mode. More...
 

Detailed Description

The Window is the real work-horse of Xenium. This is the object that the user sees and interacts with. The Window API is rather straight forward and unsurprising, but there are some details to be aware of.

Decorations

Decorations are the window border, the title, and other things like the close button. These items are separate from the window itself in that a window is just a rectangular area on-screen.

Currently, there are two schools of thought, each with pro's and con's:

  1. Client-Side Decorations: The application should be responsible for rendering its own decorations.
    • Pro: The application knows best how to present decorations in a way that best fits it User Interface.
    • Con: No consistent Look-And-Feel across all applications.

  2. Server-Side Decorations: The X11 Server is responsible for rendering the window decorations.
    • Pro: Interacting with windows in consistent across all applications and windows are only responsible for there rectangular area on-screen.
    • Con: The X11 Server's window decorations may visually clash with the application's User Interface and/or provide redundant controls (like have two ways of closing the application).

X11 has traditionally been Server-Side Decorations, but "modern" X11 Servers have no problems with borderless (no decorations) windows. Use what works best for your application.

Rendering

Updating the contents of the window is a two-step process. The first step is to get an "image" from the window (Xenium::Window::imageNext()). The Window will provide a pointer to it's internal graphics buffer, which can then be used for rendering.

How do you do this rendering? Well that is up to you, Zakero Xenium does not provide any graphics API. You can write your own graphics library (not that hard), or use one that can accept a pointer and use it. For (a bad) example: Qt5's QImage can be used with a raw data pointer.

After writing all the required data to the "image", the second step is to tell the Window to present the image (Xenium::Window::imagePresent()). The Window will then tell the X11 server to update the window contents on-screen.

Why the method names "imageNext()" and "imagePresent()"? That is to match the same terminology that the Vulkan API uses. Zakero Xenium is not compatible with Vulkan at this point in time.

Cursors
future
Focus
X11 focus works very simply: either your window has focus or it doesn't. If the window has focus, then both keyboard and mouse (pointer) events will be set to the window.

Constructor & Destructor Documentation

◆ Window()

zakero::Xenium::Window::Window ( Xenium xenium,
void *  data 
)

Member Function Documentation

◆ bytesPerPixel()

uint8_t zakero::Xenium::Window::bytesPerPixel ( ) const
noexcept

The number of bytes required to represent one pixel is provided by this method.

Returns
The number of bytes per pixel.

◆ classSet()

void zakero::Xenium::Window::classSet ( const std::string &  class_name)
noexcept

The class_name of a window is a name that is used to group windows which the Desktop Environment may be able to use. An example of this grouping would be give all the windows a class_name of the application name.
Another example would be to give a "file browser" class_name to a window that allows the user to navigate the file system.

It is suggested to use a class_name that matches the basename of the application's .desktop file. For example, "org.freedesktop.FooViewer" where the .desktop file is "org.freedesktop.FooViewer.desktop".

Note
See http://standards.freedesktop.org/desktop-entry-spec for more details.
Parameters
class_nameThe class name

◆ convertToMm() [1/2]

Xenium::PointMm zakero::Xenium::Window::convertToMm ( const Xenium::PointPixel point) const
noexcept

The provided point will be converted to millimeters.

Returns
The converted point.
Parameters
pointThe point to convert

◆ convertToMm() [2/2]

Xenium::SizeMm zakero::Xenium::Window::convertToMm ( const Xenium::SizePixel size) const
noexcept

The provided size will be converted to millimeters.

Returns
The converted size.
Parameters
sizeThe size to convert

◆ convertToPercent() [1/2]

Xenium::PointPercent zakero::Xenium::Window::convertToPercent ( const Xenium::PointPixel point) const
noexcept

The provided point will be converted to a percentage.

Returns
The converted point.
Parameters
pointThe point to convert

◆ convertToPercent() [2/2]

Xenium::SizePercent zakero::Xenium::Window::convertToPercent ( const Xenium::SizePixel size) const
noexcept

The provided size will be converted to a percentage.

Returns
The converted size.
Parameters
sizeThe size to convert

◆ convertToPixel() [1/4]

Xenium::PointPixel zakero::Xenium::Window::convertToPixel ( const Xenium::PointMm point) const
noexcept

The provided point will be converted to pixels.

Returns
The converted point.
Parameters
pointThe point to convert

◆ convertToPixel() [2/4]

Xenium::PointPixel zakero::Xenium::Window::convertToPixel ( const Xenium::PointPercent point) const
noexcept

The provided point will be converted to pixels.

Returns
The converted point.
Parameters
pointThe point to convert

◆ convertToPixel() [3/4]

Xenium::SizePixel zakero::Xenium::Window::convertToPixel ( const Xenium::SizeMm size) const
noexcept

The provided size will be converted to pixels.

Returns
The converted size.
Parameters
sizeThe size to convert

◆ convertToPixel() [4/4]

Xenium::SizePixel zakero::Xenium::Window::convertToPixel ( const Xenium::SizePercent size) const
noexcept

The provided size will be converted to pixels.

Returns
The converted size.
Parameters
sizeThe size to convert

◆ decorationsOnChange()

void zakero::Xenium::Window::decorationsOnChange ( Xenium::LambdaWindowDecorations  lambda)
noexcept

The X11 Server will notify a Window whether or not it should render its own decorations. An example of this would be a user requesting for a Window to be border-less. This lambda will be called when that event happens.

Parameters
lambdaThe lambda

◆ decorationsSet()

std::error_code zakero::Xenium::Window::decorationsSet ( const Xenium::WindowDecorations  decorations)
noexcept

Using this method will inform the X11 Server that the window would like to use the "system borders" of the desktop environment by setting use_system_borders to true. Or by setting use_system_borders to ‘false’ the Compositor expect the window to provide its own title and borders or just be a borderlass window.

Even if use_system_borders is true, it may be possible for the Desktop Environment to hide the title and borders of the window.

Returns
An error code. If there was no error, then error_code.value() == 0.
Parameters
decorationsThe requested decorations

◆ imageNext()

std::error_code zakero::Xenium::Window::imageNext ( uint8_t *&  image,
Xenium::SizePixel size 
)
noexcept

To change the contents of the Window, the image data must be updated. This method will provide access to the Windows image data via the image pointer. The image data will have the same pixel format that was used when the Window was created. If the source graphic data is in a different pixel format, it must be translated to the Window's pixel format.

The size parameter is the width and height of the image data in pixels.
The total length of the image data in bytes is:

size.width * size.height * Window->bytesPerPixel()

To index into the image data the following formula is used:

image[(size.width * y) + x] = pixel_color

The contents of the data pointed to by image is undefined and may contain "garbage".

Example
// Pixel Format: ARGB8888 -- 32-bit, 4 bytes per pixel
uint32_t* image = nullptr;
Xenium::SizePixel size;
window->imageNext((uint8_t*)image, size);
uint32_t color = 0x00ffffff; // White
uint32_t x = 44;
uint32_t y = 22;
uint32_t pixel = (y * size.width) + x;
image[pixel] = color;
Returns
An error code.
Parameters
imageThe image data
sizeThe image size

◆ imagePresent()

void zakero::Xenium::Window::imagePresent ( )
noexcept

Once the image data has been updated, this method will schedule the data to be rendered.

◆ keyboardOnEnter()

void zakero::Xenium::Window::keyboardOnEnter ( Xenium::Lambda  lambda)
noexcept

When a window gains keyboard focus, the provided lambda will be called.

Parameters
lambdaThe lambda

◆ keyboardOnKey()

void zakero::Xenium::Window::keyboardOnKey ( Xenium::LambdaKey  lambda)
noexcept

When a Window has Keyboard Focus, it will be notified of key press, key repeat, and key release events. The provided lambda will be called when these events happen.

Parameters
lambdaThe lambda

◆ keyboardOnLeave()

void zakero::Xenium::Window::keyboardOnLeave ( Xenium::Lambda  lambda)
noexcept

When a window loses keyboard focus, the provided lambda will be called.

Parameters
lambdaThe lambda

◆ minimize()

std::error_code zakero::Xenium::Window::minimize ( )
noexcept

Using this method will remove the window from view. The user will have to use the Desktop Environment to have the window redisplayed, perhaps using the task viewer.

Returns
An error code if there was a problem.

◆ onCloseRequest()

void zakero::Xenium::Window::onCloseRequest ( Xenium::Lambda  lambda)
noexcept

When a user requests a Window to be close via the Desktop Environment, the Desktop Environment may send an event to the window so that the application can decide how to handle the request. The provided lambda will be called when the window receives a "Close Request" event.

If a lambda has been previously set that needs to be removed, then pass a nullptr as the lambda value.

Parameters
lambdaThe lambda

◆ onFocusChange()

void zakero::Xenium::Window::onFocusChange ( Xenium::LambdaBool  lambda)
noexcept

When a window becomes active (gains focus) or becomes inactive (loses focus), an "Active" event is emitted. The provided lambda will be called to handle the change of the "Active" status.

If a lambda has been previously set that needs to be removed, then pass a nullptr as the lambda value.

Note
Execution of the lambda will block the Xenium object's event handling.
So keep the lambda as small and simple as possible for best performance.
Parameters
lambdaThe lambda

◆ pointerOnAxis()

void zakero::Xenium::Window::pointerOnAxis ( Xenium::LambdaAxis  lambda)
noexcept

Some pointer devices have a "wheel" that can be rotated. The provided lambda will be called when these "Pointer Axis" events happen.

Parameters
lambdaThe lambda

◆ pointerOnButton() [1/3]

void zakero::Xenium::Window::pointerOnButton ( Xenium::LambdaButtonMm  lambda)
noexcept

When the user clicks on a mouse button or some other pointer device, it generates a "Pointer Button" event. The provided lambda will be called when that event occurs.

Parameters
lambdaThe lambda

◆ pointerOnButton() [2/3]

void zakero::Xenium::Window::pointerOnButton ( Xenium::LambdaButtonPercent  lambda)
noexcept

When the user clicks on a mouse button or some other pointer device, it generates a "Pointer Button" event. The provided lambda will be called when that event occurs.

Parameters
lambdaThe lambda

◆ pointerOnButton() [3/3]

void zakero::Xenium::Window::pointerOnButton ( Xenium::LambdaButtonPixel  lambda)
noexcept

When the user clicks on a mouse button or some other pointer device, it generates a "Pointer Button" event. The provided lambda will be called when that event occurs.

Parameters
lambdaThe lambda

◆ pointerOnEnter() [1/3]

void zakero::Xenium::Window::pointerOnEnter ( Xenium::LambdaPointMm  lambda)
noexcept

When the mouse or some other pointer device enters the Window, a "Pointer Enter" event occurs. The provided lambda will be called when that event happens.

This event does not occur when the pointer enters the boarder/decoration area, but the Window (content) itself.

Parameters
lambdaThe lambda

◆ pointerOnEnter() [2/3]

void zakero::Xenium::Window::pointerOnEnter ( Xenium::LambdaPointPercent  lambda)
noexcept

When the mouse or some other pointer device enters the Window, a "Pointer Enter" event occurs. The provided lambda will be called when that event happens.

This event does not occur when the pointer enters the boarder/decoration area, but the Window (content) itself.

Parameters
lambdaThe lambda

◆ pointerOnEnter() [3/3]

void zakero::Xenium::Window::pointerOnEnter ( Xenium::LambdaPointPixel  lambda)
noexcept

When the mouse or some other pointer device enters the Window, a "Pointer Enter" event occurs. The provided lambda will be called when that event happens.

This event does not occur when the pointer enters the boarder/decoration area, but the Window (content) itself.

Parameters
lambdaThe lambda

◆ pointerOnLeave()

void zakero::Xenium::Window::pointerOnLeave ( Xenium::Lambda  lambda)
noexcept

When the mouse or some other pointer device leave the Window, a "Pointer Leave" event occurs. The provided lambda will be called when that event happens.

Parameters
lambdaThe lambda

◆ pointerOnMotion() [1/3]

void zakero::Xenium::Window::pointerOnMotion ( Xenium::LambdaPointMm  lambda)
noexcept

When the mouse or some other pointer device moves in the Window, a "Pointer Motion" event occurs. The provided lambda will be called when that event happens.

Parameters
lambdaThe lambda

◆ pointerOnMotion() [2/3]

void zakero::Xenium::Window::pointerOnMotion ( Xenium::LambdaPointPercent  lambda)
noexcept

When the mouse or some other pointer device moves in the Window, a "Pointer Motion" event occurs. The provided lambda will be called when that event happens.

Parameters
lambdaThe lambda

◆ pointerOnMotion() [3/3]

void zakero::Xenium::Window::pointerOnMotion ( Xenium::LambdaPointPixel  lambda)
noexcept

When the mouse or some other pointer device moves in the Window, a "Pointer Motion" event occurs. The provided lambda will be called when that event happens.

Parameters
lambdaThe lambda

◆ sizeOnChange() [1/3]

void zakero::Xenium::Window::sizeOnChange ( Xenium::LambdaSizeMm  lambda)
noexcept

"Resize" events are unique to Xenium. After a window has been resized, the provided lambda will be called. This event is triggered by the user manually resizing the Window.

If a lambda has been previously set that needs to be removed, then pass a nullptr as the lambda value.

Note
Execution of the lambda will block the Xenium object's event handling.
So keep the lambda as small and simple as possible for best performance.
Parameters
lambdaThe lambda

◆ sizeOnChange() [2/3]

void zakero::Xenium::Window::sizeOnChange ( Xenium::LambdaSizePercent  lambda)
noexcept

"Resize" events are unique to Xenium. After a window has been resized, the provided lambda will be called. This event is triggered by the user manually resizing the Window.

If a lambda has been previously set that needs to be removed, then pass a nullptr as the lambda value.

Note
Execution of the lambda will block the Xenium object's event handling.
So keep the lambda as small and simple as possible for best performance.
Parameters
lambdaThe lambda

◆ sizeOnChange() [3/3]

void zakero::Xenium::Window::sizeOnChange ( Xenium::LambdaSizePixel  lambda)
noexcept

"Resize" events are unique to Xenium. After a window has been resized, the provided lambda will be called. This event is triggered by the user manually resizing the Window.

If a lambda has been previously set that needs to be removed, then pass a nullptr as the lambda value.

Note
Execution of the lambda will block the Xenium object's event handling.
So keep the lambda as small and simple as possible for best performance.
Parameters
lambdaThe lambda

◆ sizeSet() [1/3]

std::error_code zakero::Xenium::Window::sizeSet ( const Xenium::SizeMm size)
noexcept

The window will be resized to the requested size.

Changing the size in this manner ignores the Window's minimum and maximum size settings. This can result in strange behavior when a user then attempts to manually resize the Window.

Note
The size of a window must be greater than Window_Size_Minimum after millimeter conversion.
This method does will trigger the Resize Event.
Returns
An error code. If there was no error, then error_code.value() == 0.
Parameters
sizeThe Window size

◆ sizeSet() [2/3]

std::error_code zakero::Xenium::Window::sizeSet ( const Xenium::SizePercent size)
noexcept

The window will be resized to the requested size.

Changing the size in this manner ignores the Window's minimum and maximum size settings. This can result in strange behavior when a user then attempts to manually resize the Window.

Note
The size of a window must be greater than Window_Size_Minimum after percentage conversion.
This method does will trigger the Resize Event.
Returns
An error code. If there was no error, then error_code.value() == 0.
Parameters
sizeThe Window size

◆ sizeSet() [3/3]

std::error_code zakero::Xenium::Window::sizeSet ( const Xenium::SizePixel size)
noexcept

The window will be resized to the requested size.

Changing the size in this manner ignores the Window's minimum and maximum size settings. This can result in strange behavior when a user then attempts to manually resize the Window.

Note
The size of a window must be greater than Window_Size_Minimum.
This method will trigger a Resize Event.
Returns
An error code. If there was no error, then error_code.value() == 0.
Parameters
sizeThe Window size

◆ sizeSetMinMax() [1/3]

std::error_code zakero::Xenium::Window::sizeSetMinMax ( const Xenium::SizeMm size_min,
const Xenium::SizeMm size_max 
)
noexcept

The window will be restricted to the provided size_min and size_max.

If either the width or height values in size_min or size_max are 0, then the size restriction for that dimension will be disabled.

Returns
An error code. If there was no error, then error_code.value() == 0.
Parameters
size_minThe minimum size
size_maxThe maximum size

◆ sizeSetMinMax() [2/3]

std::error_code zakero::Xenium::Window::sizeSetMinMax ( const Xenium::SizePercent size_min,
const Xenium::SizePercent size_max 
)
noexcept

The window will be restricted to the provided size_min and size_max.

If either the width or height values in size_min or size_max are 0, then the size restriction for that dimension will be disabled.

Returns
An error condition. If there was no error, then error_code.value() == 0.
Parameters
size_minThe minimum size
size_maxThe maximum size

◆ sizeSetMinMax() [3/3]

std::error_code zakero::Xenium::Window::sizeSetMinMax ( const Xenium::SizePixel size_min,
const Xenium::SizePixel size_max 
)
noexcept

The window will be restricted to the provided size_min and size_max.

If either the width or height values in size_min or size_max are 0, then the size restriction for that dimension will be disabled.

Returns
An error condition. If there was no error, then error_code.value() == 0.
Parameters
size_minThe minimum size
size_maxThe maximum size

◆ time()

uint32_t zakero::Xenium::Window::time ( ) const
noexcept

Access the time, in milliseconds, of most recent window update. The delta between two window timestamps can be used to determine the Frames-Per-Second.

Note
This is not based on wall-time.
Returns
The time.

◆ titleSet()

void zakero::Xenium::Window::titleSet ( const std::string &  title)
noexcept

The window's title can be changed by using this method. Changing the title does not change the window's name.

Parameters
titleThe window title

◆ windowMode()

Xenium::WindowMode zakero::Xenium::Window::windowMode ( ) const
noexcept

Provides the current WindowMode of the Window.

Returns
Xenium::WindowMode

◆ windowModeIs()

bool zakero::Xenium::Window::windowModeIs ( const Xenium::WindowMode  window_mode) const
noexcept

Compare the provided window_mode with the current window mode.

Return values
trueThe WindowMode matches
falseThe WindowMode's are different
Parameters
window_modeThe WindowMode

◆ windowModeOnChange()

void zakero::Xenium::Window::windowModeOnChange ( Xenium::LambdaWindowMode  lambda)
noexcept

The Desktop Environment is able to change the Window's mode. When that event happens, the provided lambda will be called.

Parameters
lambdaThe lambda

◆ windowModeSet()

std::error_code zakero::Xenium::Window::windowModeSet ( const Xenium::WindowMode  window_mode)
noexcept

The current mode of a window can be changed programmatically by using this method.

See also
Xenium::WindowMode
Returns
An error code if there was a problem.
Parameters
window_modeThe WindowMode

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