# OpenLogi Actions Ring Configuration: Complete Guide to the 8-Slot Cursor Menu

> Master OpenLogi Actions Ring configuration with this guide. Learn to assign quick actions like Cut, Copy, and Paste using TOML or the UI editor for enhanced productivity.

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

---

**OpenLogi implements an eight-slot Actions Ring that appears around the cursor, allowing users to assign quick actions like Cut, Copy, and Paste through TOML configuration or the Desktop UI editor, with support for per-application overrides and haptic feedback.**

The **OpenLogi Actions Ring configuration** system provides a radial quick-action menu for customizable input devices. Defined in the `openlogi-core` crate and rendered by the desktop and overlay components, this feature enables device-wide and application-specific shortcuts without moving hands from the hardware. Understanding the configuration architecture allows you to customize the eight fixed slots, enable haptic feedback, and create context-aware layouts tailored to specific workflows.

## Architecture and Source Files

The Actions Ring implementation spans multiple crates, separating data models, UI editing, and rendering concerns.

### Core Data Structures

In [`crates/openlogi-core/src/binding/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action_ring.rs), the `ActionRingConfig` struct holds device-wide settings including the `enabled` boolean and `haptics` toggle. This structure contains a default `ActionRingLayout` and a `per_app` hash map for overrides. The layout stores eight fixed positions mapped to `ActionRingEntry` objects, each containing a `RingAction`, optional `ActionRingIcon`, and optional label.

### Desktop UI Editor

The `ActionRingPanel` in [`crates/openlogi-desktop/src/features/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/features/action_ring.rs) provides the graphical configuration interface. This component reads the current state from `AppState` and allows users to edit individual slots, assign custom icons, modify labels, and toggle both the enabled state and haptic feedback settings.

### Overlay Rendering

The stand-alone `openlogi-overlay` binary defined in [`crates/openlogi-overlay/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-overlay/src/main.rs) handles the visual presentation. When the user triggers the `ShowActionsRing` binding, this lightweight GPUI host renders the ring at the current cursor position using the active configuration transmitted via IPC.

### IPC Communication Layer

Configuration data travels between the agent and desktop through structures defined in [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs). The `ActionRingPresentation` and `ActionRingInvocation` types carry the layout data and display requests across process boundaries.

## Understanding the Eight-Slot Layout

The OpenLogi Actions Ring uses a fixed geometric design with eight immutable positions that form a circle around the cursor.

The eight slots follow compass directions:

- **Top**
- **TopRight**
- **Right**
- **BottomRight**
- **Bottom**
- **BottomLeft**
- **Left**
- **TopLeft**

Each slot accepts a `RingAction` enum variant representing concrete commands such as `Action::Copy` or custom application shortcuts. The system validates configurations to prevent recursive invocation: the `ShowActionsRing` action cannot be assigned to any slot within the ring itself, as enforced by the validation logic in [`binding/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/binding/action_ring.rs).

## Configuring the Actions Ring

Users can configure the ring through TOML files or programmatically via the Rust API.

### TOML Configuration

The user-editable [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) file mirrors the Rust structs via `serde`. The `action_ring` table configures device-specific settings, default layouts, and per-application overrides as documented in [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml).

```toml
[devices."receiver:1234abcd:slot:1".action_ring]
enabled = true            # Show the ring when ShowActionsRing is invoked

haptics = true            # Play haptic feedback on hover/activation

# Default layout – one entry per slot; omitted slots become empty

[devices."receiver:1234abcd:slot:1".action_ring.default.slots]
Top        = { action = "Copy",    icon = "Keyboard" }
TopRight   = { action = "Paste" }
Right      = { action = { OpenApplication = { path = "/Applications/Slack.app", display_name = "Slack" } }, icon = "Applications" }
BottomRight = { action = "ShowDesktop", label = "Desktop" }
Bottom     = { action = "PlayPause" }
BottomLeft = { action = "BrowserBack" }
Left       = { action = "Undo" }
TopLeft    = { action = "Redo" }

```

### Programmatic Configuration

For dynamic configuration, Rust code can manipulate the `ActionRingConfig` structure directly.

```rust
use openlogi_core::binding::{ActionRingConfig, ActionRingSlot, RingAction};

// Load the per‑device config (typically via AppState)
let cfg: ActionRingConfig = /* … */;

// Replace the top‑right slot with a custom shortcut
let mut layout = cfg.default.clone();
layout.set_action(ActionRingSlot::TopRight, Some(RingAction::new(Action::CustomShortcut("Ctrl+Shift+P".into())).unwrap()));

```

Creating a per-application override at runtime:

```rust
let mut cfg = ActionRingConfig::default();
let mut app_layout = cfg.default.clone();
app_layout.set_action(ActionRingSlot::Bottom, Some(RingAction::new(Action::ShowDesktop).unwrap()));
cfg.per_app.insert("com.apple.Safari".to_string(), app_layout);

```

## Advanced Customization Features

Beyond basic action assignment, the configuration system supports visual customization and context-specific behaviors.

### Custom Icons and Labels

Each `ActionRingEntry` may override the automatically derived icon with an `ActionRingIcon` and display a custom label string. When these fields are `None`, the UI falls back to the action's default icon and label as defined in the locale files located in [`crates/openlogi-ui/locales/en.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ui/locales/en.toml).

### Per-Application Layouts

The `per_app` field in `ActionRingConfig` maps foreground application identifiers to full `ActionRingLayout` instances. This allows context-specific configurations—for example, displaying coding shortcuts when using a text editor and media controls when using a music player.

### Haptic Feedback

When the `haptics` field is set to `true`, hover and activation events trigger short vibrations on devices that expose haptic feedback capabilities. This feature is handled in the `openlogi-agent-core` layer and respects the device-wide setting in `ActionRingConfig`.

## Summary

- **OpenLogi Actions Ring configuration** centers on eight fixed slots defined in `ActionRingConfig` within [`crates/openlogi-core/src/binding/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action_ring.rs).
- The system supports both TOML file configuration and programmatic Rust API manipulation.
- Per-application overrides allow context-specific layouts mapped by application identifier.
- Visual customization includes custom icons and labels stored in `ActionRingEntry` structures.
- Haptic feedback is controlled by the `haptics` boolean flag in the device configuration.
- The architecture separates concerns between core data models, Desktop UI editing (`ActionRingPanel`), and overlay rendering (`openlogi-overlay`).

## Frequently Asked Questions

### How many actions can I assign to the OpenLogi Actions Ring?

The OpenLogi Actions Ring contains exactly eight fixed slots corresponding to compass directions: Top, TopRight, Right, BottomRight, Bottom, BottomLeft, Left, and TopLeft. You cannot add or remove slots, but you can leave slots empty by omitting them from the configuration or setting them to `None`.

### Can I configure different Actions Ring layouts for specific applications?

Yes. The `ActionRingConfig.per_app` field allows you to map application identifiers (such as "com.apple.Safari") to complete `ActionRingLayout` instances. When the specified application becomes the foreground window, OpenLogi automatically switches to that layout instead of using the default configuration.

### Where is the Actions Ring configuration stored in OpenLogi?

Configuration resides in a TOML file (typically [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml)) that mirrors the Rust structs via serde. The specific path follows the pattern `devices."receiver:{id}:slot:{n}".action_ring` within the TOML structure, allowing per-device customization alongside the global defaults found in [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml).

### Why can't I assign the ShowActionsRing action to a slot in the ring?

The `ShowActionsRing` action is explicitly prohibited from being placed inside the Actions Ring to prevent infinite recursion. The validation logic in [`crates/openlogi-core/src/binding/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action_ring.rs) guards against this configuration error, ensuring the ring contains only terminal actions like Copy, Paste, or application shortcuts.