Louvre  v1.2.1-2
C++ library for Wayland compositors
List of all members | Classes | Public Types | Public Member Functions
LKeyboard Class Reference

#include <LKeyboard.h>

Class for handling keyboard events. More...

Detailed Description

Class for handling keyboard events.

The LKeyboard class lets you handle keyboard events generated by the input backend, send them to clients, and configure parameters such as the keyboard map and key repeat rate.
There is a single instance of LKeyboard, which can be accessed from LSeat::keyboard().

Wayland Events

To send keyboard events to clients, you must first assign focus to a surface using setFocus().
Doing so, automatically removes focus from any previously focused surface. As a result, all subsequent keyboard events sent with sendKeyEvent() or sendModifiersEvent() will be directed to the currently focused surface.

Classes

struct  KeyboardModifiersState
 Keyboard modifiers. More...
 

Public Types

enum  KeyState : UChar8
 Key states. More...
 

Public Member Functions

 LKeyboard (const void *params)
 Constructor of the LKeyboard class. More...
 
virtual ~LKeyboard ()
 Destructor of the LKeyboard class. More...
 
void setFocus (LSurface *surface)
 Set keyboard focus. More...
 
LSurfacefocus () const
 Surface with keyboard focus. More...
 
void setGrabbingSurface (LSurface *surface, Protocols::Wayland::RKeyboard *keyboardResource)
 Set the surface that grabs keyboard events. More...
 
LSurfacegrabbingSurface () const
 Get the current surface that is grabbing the keyboard events. More...
 
Protocols::Wayland::RKeyboard * grabbingKeyboardResource () const
 Get the current wl_keyboard resource used during the keyboard grab. More...
 
const KeyboardModifiersStatemodifiersState () const
 State of the keyboard modifiers. More...
 
Int32 keymapFd () const
 Keyboard map file descriptor. More...
 
Int32 keymapSize () const
 Size of the keyboard map in bytes. More...
 
UInt32 keymapFormat () const
 Keymap format. More...
 
Int32 repeatRate () const
 Repetition rate. More...
 
Int32 repeatDelay () const
 Repetition delay. More...
 
void setRepeatInfo (Int32 rate, Int32 msDelay)
 Set the key repeat rate and delay. More...
 
xkb_keysym_t keySymbol (UInt32 keyCode)
 Key symbol. More...
 
xkb_state * keymapState () const
 Keyboard state. More...
 
bool isModActive (const char *, xkb_state_component type) const
 Check the state of a modifier. More...
 
const std::vector< UInt32 > & pressedKeys () const
 Vector of pressed key codes. More...
 
bool isKeyCodePressed (UInt32 keyCode) const
 Check if a key code is pressed. More...
 
bool isKeySymbolPressed (xkb_keysym_t keySymbol) const
 Check if a key symbol is pressed. More...
 
bool setKeymap (const char *rules=nullptr, const char *model=nullptr, const char *layout=nullptr, const char *variant=nullptr, const char *options=nullptr)
 Set the keyboard map. More...
 
void sendKeyEvent (UInt32 keyCode, KeyState keyState)
 Send a key event. More...
 
void sendModifiersEvent (UInt32 depressed, UInt32 latched, UInt32 locked, UInt32 group)
 Send custom modifier states. More...
 
void sendModifiersEvent ()
 Send the current modifiers state. More...
 
virtual void keyModifiersEvent (UInt32 depressed, UInt32 latched, UInt32 locked, UInt32 group)
 Notifies a change in the modifiers state. More...
 
virtual void keyEvent (UInt32 keyCode, KeyState keyState)
 Notifies a key state change. More...
 
virtual void focusChanged ()
 Notifies that the focused surface changed. More...
 
- Public Member Functions inherited from LObject
 LObject ()=default
 Constructor of the LObject class. More...
 
 ~LObject ()
 Destructor of the LObject class. More...
 
std::shared_ptr< const bool > isAlive () const
 Object's liveness status. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from LObject
static LCompositorcompositor ()
 Quick access to the global compositor instance. More...
 
static LSeatseat ()
 Quick access to the global seat instance. More...
 
static LCursorcursor ()
 Quick access to the global cursor instance. More...
 

Member Enumeration Documentation

◆ KeyState

enum KeyState : UChar8

Key states.

Enum with the possible states of a key.

Enumerator
Released 

The key is not being pressed.

Pressed 

The key is pressed.

Constructor & Destructor Documentation

◆ LKeyboard()

LKeyboard ( const void *  params)

Constructor of the LKeyboard class.

There is a single instance of LKeyboard, which can be accessed from LSeat::keyboard().

Parameters
paramsInternal library parameters passed in the LCompositor::createKeyboardRequest() virtual constructor.

◆ ~LKeyboard()

~LKeyboard ( )
virtual

Destructor of the LKeyboard class.

Invoked internally by the library after LCompositor::destroyKeyboardRequest() is called.

Member Function Documentation

◆ setFocus()

void setFocus ( LSurface surface)

Set keyboard focus.

This method assigns keyboard focus to the specified surface. Only one surface can have keyboard focus at a time, and this method automatically removes focus from any previously focused surface.
To remove focus from all surfaces, pass nullptr as the argument.

Note
Calling this method while there is a surface grabbing the keyboard is a no-op.

◆ focus()

LSurface * focus ( ) const

Surface with keyboard focus.

Pointer to the surface with keyboard focus assigned with setFocus(). Only surfaces with keyboard focus can receive keyboard events.

Returns
nullptr if no surface has keyboard focus.

◆ setGrabbingSurface()

void setGrabbingSurface ( LSurface surface,
Protocols::Wayland::RKeyboard *  keyboardResource 
)

Set the surface that grabs keyboard events.

This method redirects all keyboard events to the given surface, preventing other surfaces from gain focus with setFocus().
If the surface grabbing the keyboard is destroyed the grab is automatically assigned to its parent.
For example, an LPopupRole can request to make a keyboard grab with LPopupRole::grabSeatRequest().

If 'surface' is set to nullptr, the keyboard grab is disabled.

Parameters
surfaceThe surface that will grab the keyboard events or nullptr to disable it.
keyboardResourceThe specific wl_keyboard resource created by the client to which events must be sent.

◆ grabbingSurface()

LSurface * grabbingSurface ( ) const

Get the current surface that is grabbing the keyboard events.

This method returns the surface that is currently grabbing the keyboard events. If no grab is active, it returns nullptr.

Returns
The surface that is grabbing keyboard events, or nullptr if no grab is active.

◆ grabbingKeyboardResource()

RKeyboard * grabbingKeyboardResource ( ) const

Get the current wl_keyboard resource used during the keyboard grab.

This method returns the wl_keyboard resource to which keyboard events are sent during the grab. If no grab is active, it returns nullptr.

Returns
The wl_keyboard resource used during the keyboard grab, or nullptr if no grab is active.

◆ modifiersState()

const LKeyboard::KeyboardModifiersState & modifiersState ( ) const

State of the keyboard modifiers.

Returns
An instance of KeyboardModifiersState, which stores the state of the keyboard modifiers.

◆ keymapFd()

Int32 keymapFd ( ) const

Keyboard map file descriptor.

File descriptor of the XKB keyboard map assigned with setKeymap().

◆ keymapSize()

Int32 keymapSize ( ) const

Size of the keyboard map in bytes.

Size in bytes of the XKB keyboard map loaded with setKeymap().

◆ keymapFormat()

UInt32 keymapFormat ( ) const

Keymap format.

The keymap format can be either WL_KEYBOARD_KEYMAP_FORMAT_XKB_V1, which indicates the presence of a valid XKB keymap set, or WL_KEYBOARD_KEYMAP_FORMAT_NO_KEYMAP, indicating an issue with the XKB system configuration.

◆ repeatRate()

Int32 repeatRate ( ) const

Repetition rate.

Number of repetitions per second of a key when held down, assigned with setRepeatInfo().

The default value is 32 repetitions per second.

◆ repeatDelay()

Int32 repeatDelay ( ) const

Repetition delay.

Delay in milliseconds before triggering the repetition of a key by holding it down, set with setRepeatInfo().

The default value is 500 ms.

◆ setRepeatInfo()

void setRepeatInfo ( Int32  rate,
Int32  msDelay 
)

Set the key repeat rate and delay.

Assigns the repeat rate and delay when holding down a key.

Note
This impacts how clients respond to a key being held down.
Parameters
rateNumber of repetitions per second. 0 turns off repetition.
msDelayDelay in milliseconds before triggering the replay.

◆ keySymbol()

xkb_keysym_t keySymbol ( UInt32  keyCode)

Key symbol.

Returns the symbol of a raw key code generated by the input backend according to the status of the keyboard map.
The complete list of symbols can be found in <xkbcommon/xkbcommon-keysyms.h>.

◆ keymapState()

xkb_state * keymapState ( ) const

Keyboard state.

XKB keyboard map state.

◆ isModActive()

bool isModActive ( const char *  name,
xkb_state_component  type 
) const

Check the state of a modifier.

Parameters
nameModifier name defined in <xkbcommon/xkbcommon_names.h> such as XKB_MOD_NAME_SHIFT, XKB_LED_NAME_CAPS, etc.
typeIn XKB, the XKB_STATE_MODS_DEPRESSED, XKB_STATE_MODS_LATCHED, XKB_STATE_MODS_LOCKED, and XKB_STATE_MODS_EFFECTIVE are flags used to represent different aspects of the keyboard modifier keys' states.

XKB_STATE_MODS_DEPRESSED: This flag represents the currently depressed (pressed down) modifiers. When a modifier key is pressed, it falls into the depressed state. This flag helps identify which modifiers are currently held down.

XKB_STATE_MODS_LATCHED: This flag represents modifiers that are latched. A latched modifier is one that will be activated with the next non-modifier key press. Once the latched modifier is used, it returns to its original state.

XKB_STATE_MODS_LOCKED: This flag represents modifiers that are locked. When a modifier is locked, it stays active until explicitly unlocked. For example, if Caps Lock is activated, the Caps Lock state is locked until Caps Lock is pressed again.

XKB_STATE_MODS_EFFECTIVE: This flag represents the effective state of the modifiers. It takes into account the depressed, latched, and locked states to provide a combined view of the current modifier key states.

Returns
true if the modifier is active and false otherwise.

◆ pressedKeys()

const std::vector< UInt32 > & pressedKeys ( ) const

Vector of pressed key codes.

◆ isKeyCodePressed()

bool isKeyCodePressed ( UInt32  keyCode) const

Check if a key code is pressed.

◆ isKeySymbolPressed()

bool isKeySymbolPressed ( xkb_keysym_t  keySymbol) const

Check if a key symbol is pressed.

◆ setKeymap()

bool setKeymap ( const char *  rules = nullptr,
const char *  model = nullptr,
const char *  layout = nullptr,
const char *  variant = nullptr,
const char *  options = nullptr 
)

Set the keyboard map.

This method finds and assigns a keyboard map that matches the parameters passed in the arguments.
The keyboard map is automatically sent to clients when they connect to the compositor and use the wl_keyboard interface of the Wayland protocol. If a client is already connected, the library re-sends it the new keyboard map.
The library by default assigns the "latam" layout in LCompositor::initialized().

Parameters
rulesRules on how to interpret the other arguments. Can be nullptr. More information.
modelKeyboard model. Can be nullptr. More information.
layoutKeyboard layouts separated by comma (e.g. "latam"). Can be nullptr. More information.
variantVariants of layouts. Can be nullptr. More information.
optionsPreferences not related to layouts. Can be nullptr. More information.

◆ sendKeyEvent()

void sendKeyEvent ( UInt32  keyCode,
KeyState  keyState 
)

Send a key event.

Sends a key event to the currently focused surface.

Parameters
keyCodeRaw key code generated by the input backend.
keyStateKey state (LKeyboard::Pressed or LKeyboard::Released).

◆ sendModifiersEvent() [1/2]

void sendModifiersEvent ( UInt32  depressed,
UInt32  latched,
UInt32  locked,
UInt32  group 
)

Send custom modifier states.

This method allows you to send custom modifier states to the currently focused surface.

The parameters are equivalent to those described in LKeyboard::KeyboardModifiersState.

◆ sendModifiersEvent() [2/2]

void sendModifiersEvent ( )

Send the current modifiers state.

Sends the modifiers states to the focused surface.

Note
Louvre internally stores and updates the modifiers state, which can be accessed with modifiersState().

◆ keyModifiersEvent()

virtual void keyModifiersEvent ( UInt32  depressed,
UInt32  latched,
UInt32  locked,
UInt32  group 
)
virtual

Notifies a change in the modifiers state.

Override this virtual method if you want to be notified when the modifiers state changes.

Default implementation

void LKeyboard::keyModifiersEvent(UInt32 depressed, UInt32 latched, UInt32 locked, UInt32 group)
{
sendModifiersEvent(depressed, latched, locked, group);
}
void sendModifiersEvent()
Send the current modifiers state.
Definition: LKeyboard.cpp:385
virtual void keyModifiersEvent(UInt32 depressed, UInt32 latched, UInt32 locked, UInt32 group)
Notifies a change in the modifiers state.
uint32_t UInt32
32 bits unsigned integer
Definition: LNamespaces.h:207

◆ keyEvent()

virtual void keyEvent ( UInt32  keyCode,
KeyState  keyState 
)
virtual

Notifies a key state change.

Override this virtual method if you want to handle key press/release events.

Default implementation

void LKeyboard::keyEvent(UInt32 keyCode, KeyState keyState)
{
sendKeyEvent(keyCode, keyState);
const bool L_CTRL { isKeyCodePressed(KEY_LEFTCTRL) };
const bool L_SHIFT { isKeyCodePressed(KEY_LEFTSHIFT) };
const bool mods { isKeyCodePressed(KEY_LEFTALT) && L_CTRL };
const xkb_keysym_t sym { keySymbol(keyCode) };
if (keyState == Released)
{
if (keyCode == KEY_F1 && !mods)
LLauncher::launch("weston-terminal");
else if (L_CTRL && (sym == XKB_KEY_q || sym == XKB_KEY_Q))
{
if (focus())
focus()->client()->destroy();
}
else if (L_CTRL && (sym == XKB_KEY_m || sym == XKB_KEY_M))
{
if (focus() && focus()->toplevel() && !focus()->toplevel()->fullscreen())
focus()->setMinimized(true);
}
// Screenshot
else if (L_CTRL && L_SHIFT && keyCode == KEY_3)
{
if (cursor()->output() && cursor()->output()->bufferTexture(0))
{
std::filesystem::path path { getenvString("HOME") };
if (path.empty())
return;
path /= "Desktop/Louvre_Screenshoot_";
char timeString[32];
const auto now { std::chrono::system_clock::now() };
const auto time { std::chrono::system_clock::to_time_t(now) };
std::strftime(timeString, sizeof(timeString), "%Y-%m-%d %H:%M:%S.png", std::localtime(&time));
path += timeString;
cursor()->output()->bufferTexture(0)->save(path);
}
}
else if (keyCode == KEY_ESC && L_CTRL && L_SHIFT)
{
return;
}
else if (L_CTRL && !L_SHIFT)
else if (!L_CTRL && L_SHIFT)
else if (!L_CTRL && !L_SHIFT)
}
// Key pressed
else
{
// CTRL sets Copy as the preferred action in drag & drop session
if (L_CTRL)
// SHIFT sets the Move as the preferred action in drag & drop session
else if (L_SHIFT)
}
}
void destroy()
Terminates the client connection with the compositor.
Definition: LClient.cpp:44
void finish()
Ends and uninitializes the compositor.
Definition: LCompositor.cpp:320
LOutput * output() const
Get the current cursor output.
Definition: LCursor.cpp:253
void setPreferredAction(Action action)
Assigns the preferred action.
Definition: LDNDManager.cpp:132
@ NoAction
No preferred action.
Definition: LDNDManager.h:53
@ Copy
The preferred action is to copy.
Definition: LDNDManager.h:56
@ Move
The preferred action is to move.
Definition: LDNDManager.h:59
KeyState
Key states.
Definition: LKeyboard.h:60
@ Released
The key is not being pressed.
Definition: LKeyboard.h:62
virtual void keyEvent(UInt32 keyCode, KeyState keyState)
Notifies a key state change.
bool isKeyCodePressed(UInt32 keyCode) const
Check if a key code is pressed.
Definition: LKeyboard.cpp:419
xkb_keysym_t keySymbol(UInt32 keyCode)
Key symbol.
Definition: LKeyboard.cpp:390
LSurface * focus() const
Surface with keyboard focus.
Definition: LKeyboard.cpp:238
void sendKeyEvent(UInt32 keyCode, KeyState keyState)
Send a key event.
Definition: LKeyboard.cpp:335
static pid_t launch(const std::string &command)
Launches an application.
Definition: LLauncher.cpp:189
static LSeat * seat()
Quick access to the global seat instance.
Definition: LObject.h:36
static LCursor * cursor()
Quick access to the global cursor instance.
Definition: LObject.h:44
static LCompositor * compositor()
Quick access to the global compositor instance.
Definition: LObject.h:28
LTexture * bufferTexture(UInt32 bufferIndex)
Access the texture of a specific buffer.
Definition: LOutput.cpp:218
LDNDManager * dndManager() const
Access to the drag & drop session manager.
Definition: LSeat.cpp:137
LClient * client() const
Client owner of the surface.
Definition: LSurface.cpp:333
void setMinimized(bool state)
Sets the minimized property.
Definition: LSurface.cpp:137
bool save(const std::filesystem::path &name) const
Save the texture as a PNG file.
Definition: LTexture.cpp:504

◆ focusChanged()

virtual void focusChanged ( )
virtual

Notifies that the focused surface changed.

This event is triggered when the focus() property changes, either through the use of setFocus() or when the current focused surface is destroyed.

See also
setFocus()
focus()

Default Implementation

{
/* No default implementation. */
}
virtual void focusChanged()
Notifies that the focused surface changed.