# How to Configure Long-Press Bindings in OpenLogi TOML Files

> Learn to configure long-press bindings in OpenLogi TOML files by defining short and long keys for dual-action button assignments. Trigger actions on quick release or after a 500ms hold.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-08-29

---

**OpenLogi supports dual-action button assignments by defining `short` and `long` keys in a TOML table, where actions trigger on quick release or after a built-in 500 ms hold threshold respectively.**

OpenLogi is an open-source driver for Logitech input devices that enables granular control over button behavior through TOML configuration files. To configure long-press bindings in OpenLogi TOML files, you define a table structure that maps button names to distinct actions for quick taps versus sustained holds. This feature is implemented in the `AprilNEA/OpenLogi` repository and allows workflow optimizations like assigning Mission Control to a long press while keeping Show Desktop on a short press.

## TOML Syntax for Long-Press Bindings

In the TOML configuration, long-press bindings use inline table syntax where the button name maps to an object containing `short` and `long` keys. As shown in [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml) (lines 36-38), you assign one action to fire on quick release and another after the hold threshold:

```toml
[devices."receiver:aabbccdd:slot:1".bindings]
DpiToggle = { short = "ShowDesktop", long = "MissionControl" }

```

The `short` field executes if the button is released before the timeout, while `long` executes if held for the threshold duration or longer.

## How the Timing Mechanism Works

OpenLogi distinguishes between short and long presses by measuring the duration between physical button-down and button-up events. According to [`crates/openlogi-agent-core/src/runtime/button.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent-core/src/runtime/button.rs), the runtime tracks this timing and routes to the appropriate action:

- **Short press**: Triggered when the button releases **before 500 ms**
- **Long press**: Triggered when the button is held **for 500 ms or more**

The long action fires once upon reaching the threshold, not repeatedly while held.

## Supported Action Values

Both `short` and `long` values accept any valid OpenLogi action identifier. As parsed in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs), these include:

- **Action names**: Strings like `"ShowDesktop"`, `"MissionControl"`, or `"Copy"`
- **Keyboard shortcuts**: Strings in standard notation (`"Ctrl+Space"`)
- **Custom shortcuts**: Tables with syntax `{ CustomShortcut = "F1" }`
- **Hold shortcuts**: Tables with syntax `{ HoldShortcut = "Ctrl+Space" }` (fires only while physically held)

## Device Configuration Placement

Bindings reside within device-specific tables under the `bindings` key. Devices are identified either by receiver slot (`receiver:aabbccdd:slot:1`) or persistent unit ID (`unit:...`). Place your long-press definitions inside this structure alongside other device settings like DPI or lighting:

```toml
[devices."receiver:abcd1234:slot:1".bindings]
Thumbwheel = { short = "AppExpose", long = { CustomShortcut = "F12" } }

```

## Customizing the Hold Threshold

The default 500 ms threshold is defined by the HID++ short-long timeout feature. Advanced users can modify this via the `Crown` device feature, where the field `short_long_timeout` is defined in [`crates/openlogi-hidpp/src/feature/crown.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/crown.rs). However, the default value suits most short-press versus long-press scenarios without adjustment.

## Complete Configuration Examples

Here are three working configurations demonstrating different long-press patterns.

**Dual-action DPI button**:

```toml
[devices."receiver:abcd1234:slot:1".bindings]
DpiToggle = { short = "ShowDesktop", long = "MissionControl" }

```

**Custom shortcut on long press**:

```toml
[devices."receiver:abcd1234:slot:1".bindings]
Thumbwheel = { short = "AppExpose", long = { CustomShortcut = "F12" } }

```

**Hold-style shortcut**:

```toml
[devices."receiver:abcd1234:slot:1".bindings]
MiddleClick = { HoldShortcut = "Ctrl+Space" }

```

## Summary

- OpenLogi uses TOML tables with `short` and `long` keys to define dual-action button bindings.
- The system measures hold duration against a 500 ms threshold defined in [`crates/openlogi-hidpp/src/feature/crown.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/crown.rs).
- Short actions fire on quick release, while long actions trigger after holding the button for 500 ms or longer.
- Configuration belongs in device-specific `bindings` tables identified by receiver or unit IDs.
- Actions can be simple strings, keyboard shortcuts, or structured tables for custom behaviors.

## Frequently Asked Questions

### What is the default long-press threshold in OpenLogi?

OpenLogi uses a 500 ms threshold to distinguish between short and long presses. This value is defined by the `short_long_timeout` field in the HID++ Crown feature implementation at [`crates/openlogi-hidpp/src/feature/crown.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/crown.rs). The button runtime in [`crates/openlogi-agent-core/src/runtime/button.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent-core/src/runtime/button.rs) uses this timing to route events to either the `short` or `long` action.

### Can I use keyboard shortcuts instead of named actions for long presses?

Yes, the `long` value accepts any valid action type that OpenLogi supports. You can assign a string shortcut like `"Ctrl+Space"`, a custom shortcut table like `{ CustomShortcut = "F12" }`, or a hold shortcut like `{ HoldShortcut = "Alt+Tab" }`. The configuration parser in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs) handles all these variants when processing the TOML file.

### Where should I place long-press bindings in my OpenLogi configuration?

Place bindings inside a device table under the `bindings` key, using the device route (receiver ID and slot) or unit ID as the table header. For example: `[devices."receiver:aabbccdd:slot:1".bindings]`. See [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml) for the reference structure showing where to insert your button definitions.

### Does the long action repeat if I keep holding the button?

No, the long action fires once when the 500 ms threshold is reached. If you need an action that repeats or only executes while the button is physically held, use the `HoldShortcut` syntax instead. This creates a different behavior where the shortcut is active only during the press duration, as distinct from the toggle-style long-press action.