Zakero_Xenium.h File Reference

Zakero Xenium. More...

Include dependency graph for Zakero_Xenium.h:

Go to the source code of this file.

Classes
struct	zakero::Xenium::Key
	Key event information. More...
struct	zakero::Xenium::KeyModifier
	A collection modifier flags. More...
struct	zakero::Xenium::Output
	Information about a output device. More...
struct	zakero::Xenium::PointerAxis
	Information about an Axis event. More...
struct	zakero::Xenium::PointerButton
	Information about a pointer button event. More...
struct	zakero::Xenium::PointMm
	A location that uses millimeters. More...
struct	zakero::Xenium::PointPercent
	A location that uses percentages. More...
struct	zakero::Xenium::PointPixel
	A location that uses pixels. More...
struct	zakero::Xenium::SizeMm
	Size measured in millimeters. More...
struct	zakero::Xenium::SizePercent
	Size measured as a percentage of the Output (Monitor) resolution. More...
struct	zakero::Xenium::SizePixel
	Size measured in pixels. More...
class	zakero::Xenium::Window
	A Window. More...
class	zakero::Xenium
	A wrapper class for X11/XCB. More...

Macros
#define	_NET_WM_STATE_ADD
	A NET-WM Macro (that may not be defined).
#define	_NET_WM_STATE_REMOVE
	A NET-WM Macro (that may not be defined).
#define	_NET_WM_STATE_TOGGLE
	A NET-WM Macro (that may not be defined).
#define	explicit
	xkb.h uses the C++ keyword explicit for a variable name.
#define	X(name_, val_, mesg_)
	X-Macro. More...
#define	X(name_, val_, mesg_)
	X-Macro. More...
#define	X(value_, name_)
	X-Macro. More...
#define	X(value_, name_)
	X-Macro. More...
#define	ZAKERO_XENIUM_DEBUG_STREAM
	The stream to use for debugging output. More...
#define	ZAKERO_XENIUM_ENABLE_DEBUG
	Enable debugging output. More...
#define	ZAKERO_XENIUM_ENABLE_SAFE_MODE
	Add extra error checking. More...
#define	ZAKERO_XENIUM_IMPLEMENTATION
	Activate the implementation code. More...

Functions
bool	zakero::operator== (Xenium::PointMm &lhs, Xenium::PointMm &rhs) noexcept
	Compare two Point objects. More...
bool	zakero::operator== (Xenium::PointPercent &lhs, Xenium::PointPercent &rhs) noexcept
	Compare two Point objects. More...
bool	zakero::operator== (Xenium::PointPixel &lhs, Xenium::PointPixel &rhs) noexcept
	Compare two Point objects. More...
bool	zakero::operator== (Xenium::SizeMm &lhs, Xenium::SizeMm &rhs) noexcept
	Compare two Point objects. More...
bool	zakero::operator== (Xenium::SizePercent &lhs, Xenium::SizePercent &rhs) noexcept
	Compare two Point objects. More...
bool	zakero::operator== (Xenium::SizePixel &lhs, Xenium::SizePixel &rhs) noexcept
	Compare two Size objects. More...
std::string	zakero::to_string (const std::vector< int32_t > &vector) noexcept
	Convert a vector into a string. More...
std::string	zakero::to_string (const std::vector< xcb_atom_t > &vector) noexcept
	Convert a vector into a string. More...
std::string	zakero::to_string (const xcb_button_press_event_t &event) noexcept
	Convert an xcb_button_press_event_t into a string. More...
std::string	zakero::to_string (const xcb_client_message_event_t &event) noexcept
	Convert an xcb_client_message_event_t into a string. More...
std::string	zakero::to_string (const xcb_configure_notify_event_t &event) noexcept
	Convert an xcb_configure_notify_event_t into a string. More...
std::string	zakero::to_string (const xcb_enter_notify_event_t &event) noexcept
	Convert an xcb_enter_notify_event_t into a string. More...
std::string	zakero::to_string (const xcb_expose_event_t &event) noexcept
	Convert an xcb_expose_event_t into a string. More...
std::string	zakero::to_string (const xcb_focus_in_event_t &event) noexcept
	Convert an xcb_focus_in_event_t into a string. More...
std::string	zakero::to_string (const xcb_format_t &format) noexcept
	Convert an xcb_format_t into a string. More...
std::string	zakero::to_string (const xcb_generic_error_t &generic_error) noexcept
	Convert an xcb_generic_error_t into a string. More...
std::string	zakero::to_string (const xcb_generic_event_t &event) noexcept
	Convert an xcb_generic_event_t into a string. More...
std::string	zakero::to_string (const xcb_gravity_notify_event_t &event) noexcept
	Convert an xcb_gravity_notify_event_t into a string. More...
std::string	zakero::to_string (const xcb_key_press_event_t &event) noexcept
	Convert an xcb_key_press_event_t into a string. More...
std::string	zakero::to_string (const xcb_map_notify_event_t &event) noexcept
	Convert an xcb_map_notify_event_t into a string. More...
std::string	zakero::to_string (const xcb_motion_notify_event_t &event) noexcept
	Convert an xcb_motion_notify_event_t into a string. More...
std::string	zakero::to_string (const xcb_property_notify_event_t &event) noexcept
	Convert an xcb_property_notify_event_t into a string. More...
std::string	zakero::to_string (const xcb_randr_screen_change_notify_event_t &event) noexcept
	Convert an xcb_randr_screen_change_notify_event_t into a string. More...
std::string	zakero::to_string (const xcb_reparent_notify_event_t &event) noexcept
	Convert an xcb_reparent_notify_event_t into a string. More...
std::string	zakero::to_string (const xcb_screen_t &screen) noexcept
	Convert an xcb_screen_t into a string. More...
std::string	zakero::to_string (const xcb_setup_t &setup) noexcept
	Convert an xcb_setup_t into a string. More...
std::string	zakero::to_string (const xcb_unmap_notify_event_t &event) noexcept
	Convert an xcb_unmap_notify_event_t into a string. More...
std::string	zakero::to_string (const Xenium::Key &key) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::KeyModifier &key_modifier) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::KeyState key_state) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::Output &output) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::PointerAxis &pointer_axis) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::PointerAxisSource source) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::PointerAxisType type) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::PointerButton &button) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::PointerButtonState &button_state) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::PointMm point) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::PointPercent point) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::PointPixel point) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::SizeMm &size) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::SizePercent &size) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::SizePixel &size) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::WindowDecorations window_decorations) noexcept
	Convert a value to a std::string. More...
std::string	zakero::to_string (const Xenium::WindowMode window_mode) noexcept
	Convert a value to a std::string. More...

Detailed Description

API	Dependencies	TL;DR	What Is It?	Why Use It?	How To Use It?	Version

Making the X11/XCB windowing system easy to use.

Dependencies

• Zakero_Base.h
• Zakero_MemoryPool.h

TL;DR:

This library makes it very easy to connect to an X11 server and display windows. The developer must write pixel data directly into the window. No UI or graphics functionality is provided.

To use:

1. Add the implementation to a source code file:

   #define ZAKERO_XENIUM_IMPLEMENTATION
   #include "Zakero_Xenium.h"

2. Add the library to where it is used:

   #include "Zakero_Xenium.h"

3. Link to the X11/XCB libraries and pthread when building:

   -lpthread -lxcb -lxcb-xkb -lxcb-randr

What Is It?

X11 is a Windowing System and is used in many of the Unix-based operating systems such as Linux and BSD. X11/XCB has three parts: the client, the server, and the protocol.

The X11/XCB Server is responsible for rendering and managing all the application windows. The applications are the X11/XCB Clients. These clients tell the Server what to render as well as other requests, such as "minimize this window". Communication between the Server and the Clients is done using the X11 Protocol. XCB is the library that wraps the X11 Protocol to ensure all communication is consistent.

zakero::Xenium sits on top of the XCB library to hide it's complexity while adding as little overhead as possible.

Why Use It?

XCB was created to allow developers to faster and more responsive applications by by-passing the original X11 libraries. Not only was this goal achieved but parts of the X11 libraries where rewritten to use XCB.

However, what X11 provided was "ease of use". XCB requires the caller to maintain and track state, things that X11 did automatically.

zakero::Xenium aims to have the speed of XCB with the ease of X11, while at the same time offering some improvements. Instead of creating an event loop for all XCB applications, zakero::Xenium only creates one for you, it will only notify you of the events that were supplied lambdas.

How To Use It?

Step 0

Your compiler must support at least the C++20 standard. The location of the Zakero_*.h header files must be in your compiler's include path.

Step 1

The first step is to select which C++ source code file will contain the Zakero Xenium implementation. Once the location has been determined, add the following to that file:

#define ZAKERO_XENIUM_IMPLEMENTATION
#include "Zakero_Xenium.h"

The macro ZAKERO_XENIUM_IMPLEMENTATION tells the header file to include the implementation of the Xenium.

In all other files that will use Xenium, they only need to include the header.

#include "Zakero_Xenium.h"

Step 2

Below is a simple program that will connect to the X11 Server and display a window.

#define ZAKERO_XENIUM_IMPLEMENTATION
#include "Zakero_Xenium.h"
 
int main()
{
     std::error_code error;
 
     zakero::Xenium* xenium = zakero::Xenium::connect(error);
     if(error)
     {
             std::cout << "Error: " << zakero::to_string(error) << '\n';
             return 1;
     }
 
     zakero::Xenium::SizePixel window_size = { 640, 480 };
     auto* window = xenium->windowCreate(window_size, error);
     if(error)
     {
             std::cout << "Error: " << zakero::to_string(error) << '\n';
             return 1;
     }
 
     window->titleSet("Xenium");
 
     bool time_to_die = false;
     window->onCloseRequest([&]()
     {
             time_to_die = true;
     });
 
     while(time_to_die == false)
     {
             std::this_thread::yield();
     }
 
     delete window;
     delete xenium;
 
     return 0;
}

The following commands will build and run the example program.

> g++ -std=c++20 -lpthread -lxcb -lxcb-xkb -lxcb-randr -o example example.cpp
> ./example

Version

v0.1.0

• Window resizing
• Window image/surface rendering
• Fully multi-threaded, all X11/XCB communication happens in a separate thread.
• Flexible sizing options: Millimeters, Percent, and Pixel

---

Class Documentation

zakero::Xenium::Key

struct zakero::Xenium::Key

Time is based on the "steady clock" and not system time.

Class Members
uint32_t	code	The key code of the event.
KeyState	state	The state of the key.
uint32_t	time	When the key event happened.

zakero::Xenium::KeyModifier

struct zakero::Xenium::KeyModifier

The meaning of the modifiers are:

• pressed
  This is the easiest to understand type of modifier. A modifier such as "Control" is pressed.
• locked
  The best example of a "locked" modifier is the "Caps Lock" key.
• latched
  This modifer can occur with "Sticky Keys".

Class Members
uint32_t	group	The keyboard layout.
uint32_t	latched	A collection of latched modifiers.
uint32_t	locked	A collection of locked modifiers.
uint32_t	pressed	A collection of pressed modifiers.

zakero::Xenium::Output

struct zakero::Xenium::Output

All the X11 information about an output device in a single structure.

Class Members
int32_t	height	The height of the device in hardware units.
string	name	The name of the output.
uint32_t	physical_height_mm	The height of the device in millimeters.
uint32_t	physical_width_mm	The width of the device in millimeters.
float	pixels_per_mm_horizontal	A pre-calculated value.
float	pixels_per_mm_vertical	A pre-calculated value.
int32_t	subpixel	The device's subpixel orientation.
int32_t	transform	Transform that maps framebuffer to output.
int32_t	width	The width of the device in hardware units.
int32_t	x	The X position within the global compositor.
int32_t	y	The Y position within the global compositor.

zakero::Xenium::PointerAxis

struct zakero::Xenium::PointerAxis

Class Members
float	distance	The distance traveled.
PointerAxisSource	source	The source of the event.
int32_t	steps	The number of rotation steps.
uint32_t	time	When the event occurred.
PointerAxisType	type	The type of Axis.

zakero::Xenium::PointerButton

struct zakero::Xenium::PointerButton

Class Members
uint32_t	code	The event code.
PointerButtonState	state	The button state.

Macro Definition Documentation

X [1/4]

#define X	(		name_,
			val_,
			mesg_
	)

This macro is used to expand another macro that contain data into working code.

X [2/4]

#define X	(		name_,
			val_,
			mesg_
	)

This macro is used to expand another macro that contain data into working code.

X [3/4]

#define X	(		value_,
			name_
	)

This macro is used to expand another macro that contain data into working code.

X [4/4]

#define X	(		value_,
			name_
	)

This macro is used to expand another macro that contain data into working code.

ZAKERO_XENIUM_DEBUG_STREAM

#define ZAKERO_XENIUM_DEBUG_STREAM

This macro holds the stream that will be written to for the debug messages.
If this macro is undefined at compile time, then std::cerr will be used.

Example

#define ZAKERO_XENIUM_DEBUG_STREAM MyLogger::errorLogStream()

ZAKERO_XENIUM_ENABLE_DEBUG

#define ZAKERO_XENIUM_ENABLE_DEBUG

Enabled debugging messages to be written.

ZAKERO_XENIUM_ENABLE_SAFE_MODE

#define ZAKERO_XENIUM_ENABLE_SAFE_MODE

Before a method executes, it should validate the argument values that it receives. This is useful while developing code but adds overhead. If the calling code can guarantee that all argument data is valid, this macro can be enabled to reduce the validation checks and overhead.

ZAKERO_XENIUM_IMPLEMENTATION

#define ZAKERO_XENIUM_IMPLEMENTATION

Defining this macro will cause the Zakero Xenium implementation to be included. This should only be done once, since compiler and/or linker errors will typically be generated if more than a single implementation is found.

Note

It does not matter if the macro is given a value or not, only its existence is checked.

Function Documentation

operator==() [1/6]

bool zakero::operator== ( Xenium::PointMm &  lhs, Xenium::PointMm &  rhs  )

noexcept

The X coordinates of both objects are considered to be equal if they are less than 0.001mm apart.

The same applies with the Y coordinates.

Note

The time value is not compared.

Return values

true	Equal
false	Not Equal

Parameters

lhs	Left-Hand side
rhs	Right-Hand side

operator==() [2/6]

bool zakero::operator== ( Xenium::PointPercent &  lhs, Xenium::PointPercent &  rhs  )

noexcept

The X coordinates of both objects are considered to be equal if they are less than 0.001% apart.

The same applies with the Y coordinates.

Note

The time value is not compared.

Return values

true	Equal
false	Not Equal

Parameters

lhs	Left-Hand side
rhs	Right-Hand side

operator==() [3/6]

bool zakero::operator== ( Xenium::PointPixel &  lhs, Xenium::PointPixel &  rhs  )

noexcept

Compare the X and Y values.

Note

The time value is not compared.

Return values

true	Equal
false	Not Equal

Parameters

lhs	Left-Hand side
rhs	Right-Hand side

operator==() [4/6]

bool zakero::operator== ( Xenium::SizeMm &  lhs, Xenium::SizeMm &  rhs  )

noexcept

The width of both objects are considered to be equal if they are less than 0.001mm difference in length.

The same applies with the height.

Return values

true	Equal
false	Not Equal

Parameters

lhs	Left-Hand side
rhs	Right-Hand side

operator==() [5/6]

bool zakero::operator== ( Xenium::SizePercent &  lhs, Xenium::SizePercent &  rhs  )

noexcept

The width of both objects are considered to be equal if they are less than 0.001% difference in length.

The same applies with the height.

Return values

true	Equal
false	Not Equal

Parameters

lhs	Left-Hand side
rhs	Right-Hand side

operator==() [6/6]

bool zakero::operator== ( Xenium::SizePixel &  lhs, Xenium::SizePixel &  rhs  )

noexcept

Compare the width and height values.

Return values

true	Equal
false	Not Equal

Parameters

lhs	Left-Hand side
rhs	Right-Hand side

to_string() [1/38]

std::string zakero::to_string ( const std::vector< int32_t > &  vector )

noexcept

Returns

The string.

Parameters

vector

The value to convert

to_string() [2/38]

std::string zakero::to_string ( const std::vector< xcb_atom_t > &  vector )

noexcept

Returns

The string.

Parameters

vector

The value to convert

to_string() [3/38]

std::string zakero::to_string ( const xcb_button_press_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [4/38]

std::string zakero::to_string ( const xcb_client_message_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [5/38]

std::string zakero::to_string ( const xcb_configure_notify_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [6/38]

std::string zakero::to_string ( const xcb_enter_notify_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [7/38]

std::string zakero::to_string ( const xcb_expose_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [8/38]

std::string zakero::to_string ( const xcb_focus_in_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [9/38]

std::string zakero::to_string ( const xcb_format_t &  format )

noexcept

Returns

The string.

Parameters

format

The value to convert

to_string() [10/38]

std::string zakero::to_string ( const xcb_generic_error_t &  generic_error )

noexcept

Returns

The string.

Parameters

generic_error

The value to convert

to_string() [11/38]

std::string zakero::to_string ( const xcb_generic_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [12/38]

std::string zakero::to_string ( const xcb_gravity_notify_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [13/38]

std::string zakero::to_string ( const xcb_key_press_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [14/38]

std::string zakero::to_string ( const xcb_map_notify_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [15/38]

std::string zakero::to_string ( const xcb_motion_notify_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [16/38]

std::string zakero::to_string ( const xcb_property_notify_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [17/38]

std::string zakero::to_string ( const xcb_randr_screen_change_notify_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [18/38]

std::string zakero::to_string ( const xcb_reparent_notify_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [19/38]

std::string zakero::to_string ( const xcb_screen_t &  screen )

noexcept

Returns

The string.

Parameters

screen

The value to convert.

to_string() [20/38]

std::string zakero::to_string ( const xcb_setup_t &  setup )

noexcept

Returns

The string.

Parameters

setup

The value to convert

to_string() [21/38]

std::string zakero::to_string ( const xcb_unmap_notify_event_t &  event )

noexcept

Returns

The string.

Parameters

event

The value to convert

to_string() [22/38]

std::string zakero::to_string ( const Xenium::Key &  key )

noexcept

The key data will be converted into a JSON formatted std::string.

Returns

A string

Parameters

key	The value to convert

to_string() [23/38]

std::string zakero::to_string ( const Xenium::KeyModifier &  key_modifier )

noexcept

The key_modifier data will be converted into a JSON formatted std::string.

Returns

A string

Parameters

key_modifier

The value to convert

to_string() [24/38]

std::string zakero::to_string ( const Xenium::KeyState  key_state )

noexcept

The key_state will be converted into a std::string.

Returns

A string

Parameters

key_state

The value to convert

to_string() [25/38]

std::string zakero::to_string ( const Xenium::Output &  output )

noexcept

The output data will be converted into a JSON formatted std::string.

Returns

A string

Parameters

output

The value to convert

to_string() [26/38]

std::string zakero::to_string ( const Xenium::PointerAxis &  pointer_axis )

noexcept

The source will be converted into a std::string.

Returns

A string

Parameters

pointer_axis

The value to convert

to_string() [27/38]

std::string zakero::to_string ( const Xenium::PointerAxisSource  source )

noexcept

The source will be converted into a std::string.

Returns

A string

Parameters

source

The value to convert

to_string() [28/38]

std::string zakero::to_string ( const Xenium::PointerAxisType  type )

noexcept

The type will be converted into a std::string.

Returns

A string

Parameters

type	The value to convert

to_string() [29/38]

std::string zakero::to_string ( const Xenium::PointerButton &  button )

noexcept

The button will be converted into a std::string.

Returns

A string

Parameters

button

The value to convert

to_string() [30/38]

std::string zakero::to_string ( const Xenium::PointerButtonState &  button_state )

noexcept

The button_state will be converted into a std::string.

Returns

A string

Parameters

button_state

The value to convert

to_string() [31/38]

std::string zakero::to_string ( const Xenium::PointMm  point )

noexcept

The source will be converted into a std::string.

Returns

A string

Parameters

point

The value to convert

to_string() [32/38]

std::string zakero::to_string ( const Xenium::PointPercent  point )

noexcept

The source will be converted into a std::string.

Returns

A string

Parameters

point

The value to convert

to_string() [33/38]

std::string zakero::to_string ( const Xenium::PointPixel  point )

noexcept

The source will be converted into a std::string.

Returns

A string

Parameters

point

The value to convert

to_string() [34/38]

std::string zakero::to_string ( const Xenium::SizeMm &  size )

noexcept

The size will be converted into a std::string.

Returns

A string

Parameters

size	The value to convert

to_string() [35/38]

std::string zakero::to_string ( const Xenium::SizePercent &  size )

noexcept

The size will be converted into a std::string.

Returns

A string

Parameters

size	The value to convert

to_string() [36/38]

std::string zakero::to_string ( const Xenium::SizePixel &  size )

noexcept

The size will be converted into a std::string.

Returns

A string

Parameters

size	The value to convert

to_string() [37/38]

std::string zakero::to_string ( const Xenium::WindowDecorations  window_decorations )

noexcept

The window_decorations will be converted into a std::string.

Returns

A string

Parameters

window_decorations

The value to convert

to_string() [38/38]

std::string zakero::to_string ( const Xenium::WindowMode  window_mode )

noexcept

The window_mode value will be converted into a std::string.

Returns

A string

Parameters

window_mode

The value