Zakero's C++ Header Libraries
A collection of reusable C++ libraries
|
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... | |
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 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:
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.
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.
zakero::Xenium::Window::Window | ( | Xenium * | xenium, |
void * | data | ||
) |
Using the data pointed to by ptr
, create a new Window instance.
This constructor is not intended to be used. The correct way to create a Window is to use one of these methods:
xenium | The owning Xenium instance |
data | The data to use |
|
noexcept |
The number of bytes required to represent one pixel is provided by this method.
|
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".
class_name | The class name |
|
noexcept |
The provided point
will be converted to millimeters.
point | The point to convert |
|
noexcept |
The provided size
will be converted to millimeters.
size | The size to convert |
|
noexcept |
The provided point
will be converted to a percentage.
point | The point to convert |
|
noexcept |
The provided size
will be converted to a percentage.
size | The size to convert |
|
noexcept |
The provided point
will be converted to pixels.
point | The point to convert |
|
noexcept |
The provided point
will be converted to pixels.
point | The point to convert |
|
noexcept |
The provided size
will be converted to pixels.
size | The size to convert |
|
noexcept |
The provided size
will be converted to pixels.
size | The size to convert |
|
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.
lambda | The lambda |
|
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.
error_code.value() == 0
. decorations | The requested decorations |
|
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".
image | The image data |
size | The image size |
|
noexcept |
Once the image data has been updated, this method will schedule the data to be rendered.
|
noexcept |
When a window gains keyboard focus, the provided lambda
will be called.
lambda | The 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.
lambda | The lambda |
|
noexcept |
When a window loses keyboard focus, the provided lambda
will be called.
lambda | The lambda |
|
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.
|
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.
lambda | The 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.
lambda | The lambda |
|
noexcept |
Some pointer devices have a "wheel" that can be rotated. The provided lambda
will be called when these "Pointer Axis" events happen.
lambda | The 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.
lambda | The 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.
lambda | The 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.
lambda | The 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.
lambda | The 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.
lambda | The 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.
lambda | The 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.
lambda | The 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.
lambda | The 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.
lambda | The 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.
lambda | The 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.
lambda | The 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.
lambda | The 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.
lambda | The lambda |
|
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.
Window_Size_Minimum
after millimeter conversion.error_code.value() == 0
. size | The Window 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.
Window_Size_Minimum
after percentage conversion.error_code.value() == 0
. size | The Window 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.
Window_Size_Minimum
.error_code.value() == 0
. size | The Window size |
|
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.
error_code.value() == 0
. size_min | The minimum size |
size_max | The maximum size |
|
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.
error_code.value() == 0
. size_min | The minimum size |
size_max | The maximum size |
|
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.
error_code.value() == 0
. size_min | The minimum size |
size_max | The maximum size |
|
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.
|
noexcept |
The window's title can be changed by using this method. Changing the title does not change the window's name.
title | The window title |
|
noexcept |
Provides the current WindowMode of the Window.
|
noexcept |
Compare the provided window_mode
with the current window mode.
true | The WindowMode matches |
false | The WindowMode's are different |
window_mode | The WindowMode |
|
noexcept |
The Desktop Environment is able to change the Window's mode. When that event happens, the provided lambda
will be called.
lambda | The lambda |
|
noexcept |
The current mode of a window can be changed programmatically by using this method.
window_mode | The WindowMode |