Introduction

Configuration

There is no configuration UI. The file is located at ~/.config/inputactions/config.yaml. On debug builds ~/.config/inputactions/config-debug.yaml takes priority over the previous path.

Warning

InputActions can run commands and simulate keyboard and mouse events. You may want to restrict write access to the configuration file.

Configuration will be reloaded automatically when the file is modified, any errors will be shown in notifications. You can run qdbus6 org.inputactions / reloadConfig to reload it manually, this will also print errors.

Configuration uses the YAML format, JSON will work as well if you really want to use it.

Important

Breaking changes may be introduced at any time, they will be announced in pull requests and in the release changelog.

First trigger

All configuration for specific device types is located in the keyboard, mouse, pointer and touchpad root nodes. Triggers are defined in the gesturesproperty of the those nodes.

This trigger will launch dolphin if you swipe three fingers to the right.

touchpad:
  gestures:
    - type: swipe
      direction: right
      fingers: 3

      actions:
        - on: end
          command: dolphin

The on property of actions allows you to control at which point of the trigger’s lifecycle it should execute. The default value is end. Set it to begin if you want to execute an actions as soon as the trigger begins.

To create a repeating action, set on to update and specify the repeat rate in the interval property.

touchpad:
  gestures:
    - type: swipe
      direction: up
      fingers: 3

      actions:
        - on: update
          interval: 10
          input:
            - keyboard: [ volumeup ]

See Trigger, Action and everything else in the Core section of the sidebar for more information.

Input event blocking

Input events are processed and blocked in the compositor. Programs that do not receive events from the compositor will still be able to process them.

Complex triggers

Complex triggers will require multiple actions that execute at different points of the trigger’s lifecycle. Here is an example three-finger window drag trigger.

- type: swipe
  direction: any
  fingers: 3

  actions:
    - on: begin
      input:
        - keyboard: [ +leftmeta ]
        - mouse: [ +left ]

    - on: update
      input:
        - mouse: [ move_by_delta ]

    - on: end_cancel
      input:
        - keyboard: [ -leftmeta ]
        - mouse: [ -left ]

Conditions

Conditions allow you to make a trigger activate only if certain criteria are met - finger count, window class, cursor shape and much more.

It is also possible to set conditions on actions, though they will not have an effect on whether events are blocked.

touchpad:
  gestures:
    - type: swipe
      direction: right
      fingers: 3

      conditions:
        - $window_class == firefox

      actions:
        - input:
            - mouse: [ forward ]

See Condition.

Bidirectional triggers

Changing the direction does not cause trigger activation. The following configuration will not allow for changing direction without lifting fingers.

- type: rotate
  direction: clockwise

  # ...

- type: rotate
  direction: counterclockwise

  # ...

To create triggers with two repeating actions depending on the direction, set direction to a value that allows multiple directions (explicitly stated in the property’s description).

- type: rotate
  direction: any

  actions:
    - on: update
      interval: -10
      input:
        - keyboard: [ volumedown ]

    - on: update
      interval: 10
      input:
        - keyboard: [ volumeup ]

Conflicting triggers

At some point you may run into a situation where you want a global trigger that does x, and a local one for program y that does z. The first solution that may come to your mind is this:

# Global
- type: ...
  conditions:
    - $window_class != program

  # ...

# Local
- type: ...
  conditions:
    - $window_class == program

  # ...

This will very quickly become a big mess. Instead, you should rely on the behavior that the first trigger to execute an action will cancel all other triggers, and triggers are updated from top to bottom. This is a simplification, see Conflict resolution for a detailed explanation.

The proper solution is:

# Local
- type: ...
  conditions:
    - $window_class == program

  # ...

# Global
- type: ...
  # No window_class condition

Chaining triggers

The last_trigger_id variable contains the ID of the last trigger. You can use it to have a trigger activate only if another specific trigger had been performed immediately prior.

- type: press
  fingers: 2
  id: hold_2

- type: swipe
  direction: right
  fingers: 3

  conditions:
    - $last_trigger_id == hold_2

  actions:
    # ...

If you want to be able to perform the swipe trigger multiple times without holding every time, you can set set_last_trigger: false on the swipe trigger and it will not set the last_trigger_id variable anymore.

There is currently no convenient way to chain more than two triggers.