# Configuration
InputActions is configured through a YAML configuration file. There are no plans to add a UI in the future.

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

:::{important}
If a configuration renders the session unusable, the emergency key combination (backspace+space+enter in any order) can be held for 2 seconds to
suspend InputActions until the next config reload. A notification will be sent when triggered.
:::

## Configuration file path
File candidates (highest priority to lowest):
- ``~/.config/inputactions/config-debug.yaml`` (debug builds only)
- ``/etc/inputactions/config.yaml``
- ``~/.config/inputactions/config.yaml`` (created if not present)

If write access to the configuration file by unprivileged programs is not desired, choose the  ``/etc/inputactions/config.yaml`` file.

:::{note}
The configuration path is only chosen when ``inputactions-client`` is started (standalone implementation) or the compositor plugin is loaded
(compositor plugin implementations).
:::

## Reloading
By default, the configuration is reloaded automatically when the file is modified and a notification is shown when there is an error. To reload the configuration manually, run ``inputactions config reload``.

## Issues
The ``inputactions config reload`` and ``inputactions config issues`` commands will show detailed information about any issues with the configuration - errors,
deprecated features and unused properties.

## Subproperties
``a.b`` in the ``Property`` column means that ``b`` is a property of ``a``:
```yaml
a:
  b: value
```

## Inheritance
Child objects inherit all properties from their parent, add new ones and can be used in properties where an object of the parents' type is required.

## Types
:::{list-table}
:header-rows: 1
:widths: 10 20 15

* - Type
  - Description
  - Examples

* - bool
  - ``true`` or ``false``
  -

* - float
  - Floating point number.
  -

* - function
  - A JavaScript function.
  - ```js
    () => {
        console.log("a");
    }
    ```

* - int
  - Signed integer, can be negative.
  -

* - keyboard_key
  - See [](/devices/keyboard/scancodes).
  -

* - regex
  - Regular expression.
  -

* - string
  - Text, can be wrapped in ``"`` or ``'``, but usually does not have to be.
  -

* - time
  - Duration in milliseconds, cannot be negative.
  -

* - uint
  - Unsigned integer, cannot be negative.
  -

* - enum(value1, value2, ...)
  - One value from the list of values in brackets.
  - ``value2``

* - flags(value1, value2, ...)
  - List of one or more values from the list of values in brackets.
  - ```yaml
    [ value1, value2 ]
    ```

* - list(type)
  - List of elements of type ``type``.
  - ```yaml
    [ 1, 2, 3 ]
    ```

    ```yaml
    - 1
    - 2
    - 3
    ```

* - map(key_type, value_type)
  - A map (``key: value``) where all keys are of type ``key_type`` and values of type ``value_type``.
  - ```yaml
    key1: value1
    key2: value2
    ```

* - point(type)
  - Two numeric values (x and y) of type ``type``. Format: ``x,y``
  - ``point(int)`` - ``4,0``<br>
    ``point(float)`` - ``1.1,2.2``

* - range(type)
  - Range of numbers of type ``type``. Format: ``min-max``, ``-`` may be surrounded by exactly one space on each side.
  - ``range(int)`` - ``1 - 2``<br>
    ``range(point)`` - ``0;0 - 0.5;0.5``
:::

## Structure
**Bold** properties are required, ~~struck through~~ properties are deprecated and will be removed in the future.

### Root
:::{list-table}
:header-rows: 1

* - Property
  - Type
  - Description
  - Default

* - anchors
  -
  - For defining YAML anchors without unused property warnings.
  -

* - autoreload
  - *bool*
  - Whether the configuration should be automatically reloaded on file change.
  - ``true``

* - device_rules
  - *list([](/devices/rule))*
  - Evaluated from bottom to top, each rule applies properties to all devices that satisfy the rule's conditions.
  -

* - emergency_combination
  - *list(keyboard_key)*
  - Keyboard keys that can be pressed in any order and held for 2 seconds to suspend InputActions until the next config reload.

    Set to an empty list to disable.
  - ``[ backspace, enter, space ]``

* - external_variable_access
  - *bool*
  - Allow dumping variables by running ``inputactions variables list``.
  - ``true``

* - notifications.config_error
  - *bool*
  - Send a notification when the configuration fails to load.
  - ``true``

* - keyboard
  - *[](#eventhandler)*
  -
  -

* - mouse
  - *[](#eventhandler)*
  -
  -

* - pointer
  - *[](#eventhandler)*
  -
  -

* - scripting.scripts
  - *list([](#script))*
  - See [](/scripting/index).
  -

* - touchpad
  - *[](#eventhandler)*
  -
  -

* - touchscreen
  - *[](#eventhandler)*
  -
  -
:::

### EventHandler
:::{list-table}
:header-rows: 1

* - Property
  - Type
  - Description

* - **gestures**
  - *list([](/trigger))*
  -

* - speed
  - *[](#speed)*
  - Settings for how motion trigger speed is determined.
:::

### Script
:::{list-table}
:header-rows: 1

* - Property
  - Type
  - Description

* - **source**
  - *string*
  - The script.
:::

### Speed
The defaults may not work for everyone, as they depend on the device's sensitivity and size.

:::{list-table}
:header-rows: 1

* - Property
  - Type
  - Description
  - Default

* - events
  - *uint*
  - How many input events to sample in order to determine the speed at which the trigger is performed. The average of each event's delta is compared against the thresholds below. If the threshold is reached, the trigger is considered to have been performed fast, otherwise slow.

    **Note**: No triggers will begin until all events have been sampled.
  - ``3``

* - swipe_threshold
  - *float*
  -
  - ``20``

* - pinch_in_threshold
  - *float*
  -
  - ``0.04``

* - pinch_out_threshold
  - *float*
  -
  - ``0.08``

* - rotate_threshold
  - *float*
  -
  - ``5``
:::

## Example
```yaml
device_rules:
  - conditions: $name == Synaptics TM3276-022
    pressure_ranges:
      thumb: 75
      palm: 140

  - conditions: $mouse
    click_timeout: 50

mouse:
  gestures:
    # ...

touchpad:
  speed:
    swipe_threshold: 15

  gestures:
    - type: pinch
      fingers: 2
      direction: in

      actions:
        - plasma_shortcut: kwin,Window Close
```