Important
Until v1.0.0 is released, breaking changes may be introduced at any time.
There is currently no configuration UI. The configuration file is located at ~/.config/kwingestures.yml. It is created automatically when the plugin is loaded. The plugin should be reconfigured when the file changes. If it doesn't, disable and enable it manually or run qdbus org.kde.KWin /Effects org.kde.kwin.Effects.reconfigureEffect kwin_gestures.
When the configuration fails to load, the error will be logged. To see it, run journalctl --boot=0 -g "kwin_gestures:" -n 5. The message should contain the approximate position of where the error has occurred.
kwin_gestures: Failed to load configuration: Invalid swipe direction (line 4, column 17)
Bolded properties must be set.
| Type | Description |
|---|---|
| bool | true or false |
| int | A positive or negative number. |
| uint | A positive number. |
| float | A positive or negative number with decimal places. |
| list(type) | List containing elements of type. Example: list(int) - [ 1, 2, 3 ] or:- 1 - 2 - 3 |
| range(type) | A range of numbers of type. Format: min-max.Example: range(int) - 1-2 |
| enum(value1, value2, ...) | A single value from the list of valid values in brackets. |
| flags(value1, value2, ...) | A list of one or multiple values from the list of valid values in brackets. Example: [ value1, value2 ] |
| Property | Type | Description | Default |
|---|---|---|---|
| autoreload | bool |
Whether the configuration should be automatically reloaded on file change. | true |
| touchpad | Device |
See Device below. |
The only device supported at the time is touchpad.
The device is the root element in the configuration file:
touchpad:
gestures:
# ...| Property | Type | Description | Default |
|---|---|---|---|
| gestures | list(Gesture) |
Gestures for this device. See Gesture below. | none |
| speed | Speed |
Settings for how gesture speed is determined. See Speed below. | |
| delta_multiplier | float |
Delta multiplier used for move_by_delta mouse input actions. | 1.0 |
The defaults may not work for everyone, as they depend on the device's sensitivity and size.
| Property | Type | Description | Default |
|---|---|---|---|
| events | uint |
How many input events to sample in order to determine the speed at which the gesture is performed. The average of each event's delta is compared against the thresholds below. If the threshold is reached, the gesture is considered to have been performed fast, otherwise slow. Note: No gestures will be triggered until all events have been sampled. |
3 |
| swipe_threshold | float |
20 | |
| pinch_in_threshold | float |
0.04 | |
| pinch_out_threshold | float |
0.08 |
See example_gestures.md for examples.
| Property | Type | Description | Default |
|---|---|---|---|
| type | enum(hold, pinch, swipe) |
For pinch in gestures, the scale ranges from 1.0 to 0.0. For pinch out, the scale is larger than 1.0. | none |
| direction | For pinch gestures: enum(in, out, any)For swipe gestures: enum(left, right, up, down, left_right, up_down, any) |
any, left_right and up_down are bi-directional gestures. The direction can be changed during the gesture. | none |
| fingers | uint (exact amount) or range(uint) |
The exact amount or range of fingers required to trigger this gesture. Minimum value: 1 for hold gestures, 2 for pinch gestures, 3 for swipe. Maximum value: Depends on how many fingers the device can detect. |
none |
| speed | enum(any, fast, slow) |
The speed at which the gesture must be performed. If a value other than any is specified, this gesture will cause all other gestures of the same device and type to be delayed by Speed.events input events until the speed is determined. |
any |
| threshold | float (min) or range(float) (min and max) |
How far this gesture needs to progress in order to be activated. A gesture with begin or update actions can't have a maximum threshold. |
none |
| conditions | list(Condition) |
See Condition below. At least one condition (or 0 if none specified) must be satisfied in order for this gesture to be triggered. |
none |
| actions | list(Action) |
See Action below. | none |
All specified subconditions must be satisfied in order for the condition to be satisfied. OR conditions can be created by adding multiple conditions.
| Property | Type | Description | Default |
|---|---|---|---|
| negate | flags(window_class, window_state) |
Which properties to negate. | none |
| window_class | regex |
Executed on the currently focused window's resource class and resource name. If a match is not found for either, the condition will not be satisfied. | none |
| window_state | flags(fullscreen, maximized) |
none |
| Property | Type | Description | Default |
|---|---|---|---|
| on | enum(begin, end, cancel, update, end_cancel) |
begin - The gesture has started. end - The gesture has ended. cancel - The gesture has been cancelled, for example due a to a finger being lifted or the direction being changed. update - An input event has been sent by the device. end_cancel - end or cancel When the action should be triggered. To make a gesture trigger when the fingers are lifted, use end. To make a gesture trigger immediately, use begin. |
end |
| interval | float |
How often an update action should be repeated. Can be negative for bi-directional gestures. If set to 0, the action will execute exactly once per input event. Otherwise, the action may execute 0, if the delta is smaller than the interval, or multiple, if the delta is at least two timer larger than the interval, times per input event. |
0 |
| block_other | bool |
Whether this action should block other actions when executed. | false |
| conditions | list(Condition) |
List of conditions. See Condition below. At least one condition (or 0 if none specified) must be satisfied in order for this action to be triggered. |
none |
| threshold | float (min) or range(float) (min and max) |
Same as Gesture.threshold, but only applied to this action. Begin actions can't have thresholds. |
none |
| command | string |
Run a command. Mutually exclusive with input, keyboard and plasma_shortcut. |
none |
| input | List of input devices and the actions to be performed by them. Devices can be used multiple times. Devices keyboard, mouse Keyboard and mouse actions +[key/button] - Press key on keyboard or button on mouse-[key/button] - Release key on keyboard or button on mouse[key1/button1]+[key2/button2] - One or more keys/buttons separated by +. Pressed in the order as specified and released in reverse order.Full list of keys and buttons: src/libgestures/libgestures/yaml_convert.h Mouse actions move_by [x] [y] - Move the pointer by (x, y)move_to [x] [y] - Move the pointer to (x, y)move_by_delta - Move the pointer by the gesture's delta. Swipe gestures have a different acceleration profile. The delta will be multiplied by Device.delta_multiplier.Example: input: - keyboard: [ leftctrl+n ] - mouse: [ left ]Mutually exclusive with command, keyboard and plasma_shortcut. |
none | |
| plasma_shortcut | string |
Invoke a KDE Plasma global shortcut. Format: component,shortcut.Run qdbus org.kde.kglobalaccel | grep /component for the list of components. Don't put the /component/ prefix in this file.Run qdbus org.kde.kglobalaccel /component/$component org.kde.kglobalaccel.Component.shortcutNames for the list of shortcuts.Example: kwin,Window MinimizeMutually exclusive with command, input and keyboard. |
none |
list(string) |
Like input but only for the keyboard. Deprecated. This option is kept for backwards compatibility and may be removed in the future. Mutually exclusive with command, input and plasma_shortcut. |
none |
touchpad:
speed:
swipe_threshold: 15
gestures:
- type: pinch
fingers: 2
direction: in
actions:
- plasma_shortcut: kwin,Window Close