# Global Keyboard Remapping in OpenLogi: Supported Modifiers and Syntax

> Discover global keyboard remapping in OpenLogi. Learn supported modifiers like shift, ctrl, alt, and cmd, and master the mod+key syntax for custom shortcuts.

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

---

**OpenLogi supports four modifiers for global keyboard remapping: `shift`, `control` (alias `ctrl`), `option` (alias `alt`), and `command` (alias `cmd`), which can be combined in any order with a base key using the `mod+key` syntax.**

Understanding the exact modifiers available for **global keyboard remapping in OpenLogi** is essential for creating effective hotkey configurations. This guide covers the complete modifier set, their aliases, parsing behavior, and practical usage based on the official source code in the AprilNEA/OpenLogi repository.

## Supported Modifiers in OpenLogi

OpenLogi defines global keyboard remapping triggers through the `KeyModifiers` struct in [`crates/openlogi-core/src/config/key_trigger.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config/key_trigger.rs) [(lines 22-30)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config/key_trigger.rs#L22-L30). The implementation recognizes four modifier keys:

| Modifier | Description | Accepted Aliases |
|----------|-------------|----------------|
| `shift` | Shift key held | — |
| `control` | Control key held | `ctrl` |
| `option` | Option/Alt key held | `alt` |
| `command` | Command (⌘) key held | `cmd` |

These modifiers are mutually combinable. You can specify any subset from zero modifiers (bare key) up to all four simultaneously.

## Trigger String Syntax

OpenLogi parses modifier specifications from textual trigger strings following the pattern `[modifier+]*+key`. The parser:

1. Splits the string on `+` delimiters
2. Matches each modifier segment against valid names and aliases
3. Rejects unknown modifiers with a parse error [(lines 41-44)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config/key_trigger.rs#L41-L44)

**Valid trigger examples:**

- `"f5"` — bare F5 key
- `"shift+f2"` — Shift+F2 combination
- `"ctrl+alt+f1"` — Control+Option+F1 using aliases
- `"shift+cmd+f5"` — Shift+Command+F5

Case sensitivity follows the implementation in `KeyTrigger::from_str` [(lines 36-41)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config/key_trigger.rs#L36-L41).

## Practical Code Examples

### Creating a Keyboard Configuration with Modifiers

```rust
use openlogi_core::config::{KeyTrigger, KeyboardConfig};
use openlogi_core::binding::Action;

// Simple F5 binding with no modifiers
let mut cfg = KeyboardConfig::default();
cfg.bindings.insert(
    "f5".parse::<KeyTrigger>().unwrap(),
    Action::LaunchApplication { 
        path: "/Applications/Calculator.app".into() 
    },
);

// Complex modifier combination: Shift+Command+F2
cfg.bindings.insert(
    "shift+cmd+f2".parse::<KeyTrigger>().unwrap(),
    Action::RunCommand { 
        command: "osascript -e 'tell application \"Safari\" to reload'".into() 
    },
);

```

### Parsing and Inspecting Modifier Masks

```rust
let trigger: KeyTrigger = "ctrl+alt+f1".parse()
    .expect("valid trigger");

// Access individual modifier flags
assert!(trigger.modifiers.control);
assert!(trigger.modifiers.option);
assert!(!trigger.modifiers.shift);
assert!(!trigger.modifiers.command);

// Verify the base keycode
assert_eq!(trigger.keycode, 0x7A); // F1 scan code

```

### Runtime Modifier Inspection

```rust
let mods = trigger.modifiers;

println!(
    "Active modifiers — Shift: {}, Control: {}, Option: {}, Command: {}",
    mods.shift, mods.control, mods.option, mods.command
);

```

## Key Source Files and Exports

| File Path | Purpose |
|-----------|---------|
| [`crates/openlogi-core/src/config/key_trigger.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config/key_trigger.rs) | Defines `KeyModifiers` struct, implements parsing logic, documents supported modifier names |
| [`crates/openlogi-core/src/config/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config/config.rs) | Re-exports `KeyModifiers` and `KeyTrigger` for public API consumption |
| [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md) | Describes TOML configuration syntax for end users |

## Modifier Limitations and Error Handling

OpenLogi enforces strict validation during trigger parsing. **Any unrecognized modifier produces a parse failure** rather than silent ignore. This prevents configuration errors from creating unexpected behavior.

The alias system provides flexibility—`control` and `ctrl` are equivalent—while maintaining a canonical internal representation. When serializing configurations, OpenLogi uses the full canonical names (`control`, `option`, `command`) rather than aliases.

## Summary

- **Four modifiers** support **global keyboard remapping in OpenLogi**: `shift`, `control`/`ctrl`, `option`/`alt`, and `command`/`cmd`
- **Syntax**: Combine modifiers with `+` delimiters ending in the base key (e.g., `"shift+cmd+k"`)
- **Implementation**: Defined in `KeyModifiers` struct at [`crates/openlogi-core/src/config/key_trigger.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config/key_trigger.rs)
- **Validation**: Unknown modifiers trigger parse errors; aliases are accepted during input parsing
- **Combinations**: Multiple modifiers stack arbitrarily; zero modifiers valid for bare key bindings

## Frequently Asked Questions

### Can I use Windows/Super key as a modifier in OpenLogi?

No. The `KeyModifiers` struct in OpenLogi only defines the four macOS-oriented modifiers (`shift`, `control`, `option`, `command`). There is no dedicated Windows or Super key modifier in the current implementation. Cross-platform support would require extending the modifier mask definition in [`key_trigger.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/key_trigger.rs).

### What happens if I misspell a modifier name?

OpenLogi returns a parse error. The `FromStr` implementation for `KeyTrigger` validates each modifier segment against the known set and rejects unknown strings [(lines 41-44)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config/key_trigger.rs#L41-L44). This strict validation ensures configuration errors surface immediately rather than causing silent binding failures.

### Are modifier order and case significant in trigger strings?

Modifier order is flexible—`"shift+cmd+k"` and `"cmd+shift+k"` parse identically. However, case sensitivity depends on the specific parser implementation. The source uses direct string matching, so lowercase is recommended for consistency with the documented examples.