trigger.md

Trigger

An action or set of actions performed using an input device, also referred to as gesture.

Configuration

Properties

These properties can be set on all triggers. See the other tables below and the Triggers page of every device for properties that are only available in specific cases.

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

• • Property
  • Type
  • Description
  • Default
• • type
  • enum(circle, click, hold, hover, pinch, press, rotate, shortcut, stroke, swipe, tap, wheel)
  • Same as the trigger's name but lowercase.
• • accelerated
  • bool
  • Use the accelerated delta (if available) for action intervals and the move_by_delta input action.
  • false
• • actions
  • list()
• • block_events
  • bool
  • Whether this trigger should block all input events required to perform it while active. Only one active trigger needs this property set to true in order for events to be blocked.
  • true
• • clear_modifiers
  • bool
  • Whether keyboard modifiers should be cleared when this trigger begins. They will not be restored after the trigger ends.
  • true if an is present, false otherwise
• • conditions
  • Must be satisfied in order for this trigger to be activated.
• • end_conditions
  • If satisfied, the trigger will end, otherwise it will be cancelled.
• • id
  • string
  • Must be unique.

• • resume_timeout

  • time

  • The amount of time after a trigger ends, during which the trigger can be performed again as if it never actually ended. Performing any action that does not activate this trigger causes it to be cancelled immediately.

    Can be used for a drag touchpad trigger that allows lifting fingers.

    Not compatible with stroke triggers.

  • 0

• • set_last_trigger
  • bool
  • Whether to set last_trigger variables.
  • true

• • threshold

  • float (min) or range(float) (min and max)

  • How far this trigger needs to progress in order to begin.

    Triggers with on: begin or on: update actions cannot have maximum thresholds.
• • keyboard_modifiers
  • Deprecated. Use the keyboard_modifiers variable in a condition instead.

:::

Motion trigger properties

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

• • Property
  • Type
  • Description
• • speed
  • enum(fast, slow)
  • The speed at which the trigger must be performed. Will be available as a variable in the future. :::

Description

Each device has its own set of triggers, listed in the Triggers subpage of the device.

Thresholds and action intervals are based on the trigger's delta. Time-based triggers update every 5 ms with a delta of 5.

Triggers use the unaccelerated delta if available. The accelerated delta is only used for action intervals and move_by_delta input actions if accelerated is set to true.

Lifecycle

• begin - Can be delayed or prevented by thresholds.
• update - Before a trigger receives an update event, its update conditions (direction) are checked first. If not satisfied, the trigger is cancelled.
• tick - Uses the same interval and delta as time-based triggers. Intended for creation of time-based actions in non-time-based triggers. Ticking starts when the trigger begins.
• end - The user has finished performing the trigger and end conditions have been satisfied.
• cancel - The trigger's update conditions were not satisfied, the trigger has been overridden by another one as a result of conflict resolution, or the user has started performing a different trigger.

Conflict resolution

Conflict resolution ensures that there are never multiple triggers executing actions simultaneously by immediately cancelling all other triggers when:

• a trigger is updated, and has any action that had been executed, or has an update action that can be executed but hasn't been yet (interval not reached),
• a trigger ends, and has an end action that can be executed,
• a stroke trigger is active (in this case only swipe triggers are cancelled).

Triggers are updated in the same order as specified in the configuration.

In the following example, it is not necessary to set speed: slow on Trigger 2, because when the action of Trigger 1 is executed, Trigger 2 will be cancelled immediately. The same applies to all other properties - conditions, thresholds etc.

# Trigger 1
- type: swipe
  direction: right
  speed: fast

  actions:
    - on: begin
      # ...

# Trigger 2
- type: swipe
  direction: right

  actions:
    - on: begin
      # ...

It is also possible for a trigger below to cancel the one above it if actions are executed at different points of the lifecycle.

# Trigger 1
- type: swipe
  direction: right

  actions:
    - on: end
      # ...

# Trigger 2
- type: swipe
  direction: right

  actions:
    - on: begin
      # ...