KDE API Reference

Contents

KKeySequenceRecorder Class

Record a QKeySequence by listening to key events in a window. More...

Header: #include <KKeySequenceRecorder>
CMake: find_package(KF6 REQUIRED COMPONENTS GuiAddons)
target_link_libraries(mytarget PRIVATE KF6::GuiAddons)
Since: 6.0
Inherits: QObject

Properties

Public Functions

KKeySequenceRecorder(QWindow *window, QObject *parent = nullptr)
QKeySequence currentKeySequence() const
bool isRecording() const
bool modifierOnlyAllowed() const
bool modifierlessAllowed() const
bool multiKeyShortcutsAllowed() const
void setCurrentKeySequence(const QKeySequence &sequence)
void setModifierOnlyAllowed(bool allowed)
void setModifierlessAllowed(bool allowed)
void setMultiKeyShortcutsAllowed(bool allowed)
void setWindow(QWindow *window)
void startRecording()
QWindow *window() const

Public Slots

void cancelRecording()

Signals

void currentKeySequenceChanged()
void gotKeySequence(const QKeySequence &keySequence)
void modifierOnlyAllowedChanged()
void modifierlessAllowedChanged()
void multiKeyShortcutsAllowedChanged()
void recordingChanged()
void windowChanged()

Detailed Description

After calling startRecording key events in the set window will be captured until a valid QKeySequence has been recorded and gotKeySequence is emitted. See multiKeyShortcutsAllowed and modifierlessAllowed for what constitutes a valid key sequence.

During recording any shortcuts are inhibited and cannot be triggered. Either by using the keyboard-shortcuts-inhibit protocol on Wayland or grabbing the keyboard.

For graphical elements that record key sequences and can optionally perform conflict checking against existing shortcuts see KKeySequenceWidget and KeySequenceItem.

Porting from KF5 to KF6:

The class KeySequenceRecorder was renamed to KKeySequenceRecorder.

See also KKeySequenceWidget and KeySequenceItem.

Property Documentation

currentKeySequence : QKeySequence

The recorded key sequence. After construction this is empty.

During recording it is continuously updated with the newest user input.

After recording it contains the last recorded QKeySequence

Access functions:

QKeySequence currentKeySequence() const
void setCurrentKeySequence(const QKeySequence &sequence)

Notifier signal:

void currentKeySequenceChanged()

[read-only] isRecording : const bool

Whether key events are currently recorded

Access functions:

bool isRecording() const

Notifier signal:

void recordingChanged()

modifierOnlyAllowed : bool

It makes it acceptable for the key sequence to be just a modifier (e.g. Shift or Control)

By default, if only a modifier is pressed and then released, the component will remain waiting for the sequence. When enabled, it will take the modifier key as the key sequence.

By default this is false.

Access functions:

bool modifierOnlyAllowed() const
void setModifierOnlyAllowed(bool allowed)

Notifier signal:

void modifierOnlyAllowedChanged()

modifierlessAllowed : bool

If key presses of "plain" keys without a modifier are considered to be a valid finished key combination. Plain keys include letter and symbol keys and text editing keys (Return, Space, Tab, Backspace, Delete). Other keys like F1, Cursor keys, Insert, PageDown will always work.

By default this is false.

Access functions:

bool modifierlessAllowed() const
void setModifierlessAllowed(bool allowed)

Notifier signal:

void modifierlessAllowedChanged()

multiKeyShortcutsAllowed : bool

Controls the amount of key combinations that are captured until recording stops and gotKeySequence is emitted. By default this is true and "Emacs-style" key sequences are recorded. Recording does not stop until four valid key combination have been recorded. Afterwards currentKeySequence().count() will be 4.

Otherwise only one key combination is recorded before gotKeySequence is emitted with a QKeySequence with a count() of 1.

Access functions:

bool multiKeyShortcutsAllowed() const
void setMultiKeyShortcutsAllowed(bool allowed)

Notifier signal:

void multiKeyShortcutsAllowedChanged()

See also QKeySequence.

window : QWindow*

The window in which the key events are happening that should be recorded

Access functions:

QWindow *window() const
void setWindow(QWindow *window)

Notifier signal:

void windowChanged()

Member Function Documentation

[explicit] KKeySequenceRecorder::KKeySequenceRecorder(QWindow *window, QObject *parent = nullptr)

Constructor.

window The window whose key events will be recorded.

See also window.

[slot] void KKeySequenceRecorder::cancelRecording()

Stops the recording session

[signal] void KKeySequenceRecorder::gotKeySequence(const QKeySequence &keySequence)

This signal is emitted when a key sequence has been recorded.

Compared to currentKeySequenceChanged and currentKeySequence this is signal is not emitted continuously during recording but only after recording has finished.

[invokable] void KKeySequenceRecorder::startRecording()

Start recording. Calling startRecording when window() is nullptr has no effect.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.