A shortcuts overlay for the COSMIC™ DE.

A keyboard shortcuts overlay for the COSMIC™ DE in a semi-transparent overlay surface.

• The overlay is only displayed as long as a specific predefined hotkey is pressed, similar to how it works on Android for various tablets.
• The overlay is only displayed only on the output/display that has focus and changes accordingly.
• Intended usage is to be run as a background service with no disruption.

Other projects:

• ElementaryOs app: https://github.com/elementary/shortcut-overlay
• Ubuntu Unity's overlay: Unity's desktop overlay
• iPadOS/Android tablet: iPadOS

Features

• Wayland Native: Built using smithay-client-toolkit for native Wayland support
• Layer Shell: Uses wlr-layer-shell protocol for overlay functionality
• Singleton Instance: Ensures only one instance runs at a time using file locking
• Semi-transparent UI: Displays shortcuts with a blurred background effect
• Key Detection: Uses libinput to globally detect key press/release events
• Configurable: Customize colors, font size, and blur effects via TOML config

The overlay automatically detects and reads keyboard shortcuts from:

• COSMIC™: ~/.config/cosmic/config
• Niri: WIP
• Other: WIP

Configuration

The overlay can be configured via a TOML configuration file located at:

/usr/share/shortcuts-overlay/overlay-config.toml

Configuration Options

background_color = "#000000"  # Background color in hex format
text_color = "#ffffff"        # Text color in hex format
font_size = 13.0              # Font size in pixels
line_height = 1.7             # Line height multiply in pixels
apply-blur = true             # Enable/disable blur effect
anchor = "center"             # Overlay anchor position
width = 1200                  # Overlay width in pixels
height = 800                  # Overlay height in pixels
corner_radius = 32.0          # Corner radius in pixels

Default Values

If no configuration file is found, the following defaults are used:

• background_color: #000000 (black)
• text_color: #ffffff (white)
• font_size: 13.0 pixels
• line_height: 1.7
• apply-blur: false
• anchor: center
• width: 1200 pixels
• height: 800 pixels
• corner_radius: 32.0 pixels

Creating a Configuration File

# Create the config file
cat > /usr/share/shortcuts-overlay/overlay-config.toml << 'EOF'
background_color = "#32373C"
text_color = "#ffffff"
font_size = 13.0
line_height = 1.7
apply-blur = true
anchor = "center"
width = 1200
height = 800
corner_radius = 32.0
EOF

Requirements

• Rust 1.70 or later
• libwayland-dev
• libxkbcommon-dev
• libinput-dev
• libudev-dev
• Access to /dev/input/event* devices (user must be in the input group or run with appropriate permissions, see #permissions-setup and #checking-device-access)

Installation

From Source

# Install system dependencies (Ubuntu/Debian)
sudo apt-get install libwayland-dev libxkbcommon-dev libinput-dev libudev-dev

# Clone and build
git clone https://github.com/l-const/shortcuts-overlay.git
cd shortcuts-overlay
cargo build --release

Permissions Setup

Warning

The application uses libinput to read input events and detect key presses. This requires permission to access input devices.

Manual Setup

Add your user to the input group manually:

sudo usermod -a -G input $USER

After either method, you MUST log out and log back in for the changes to take effect.

Verify the setup worked:

groups
# You should see 'input' in the list

Building Distribution Packages

You can build Debian (.deb) or RPM packages for easier distribution and installation:

# Build Debian package
make package-deb

# Build RPM package  
make package-rpm

# Build both packages
make package-all

Installing Packages

Debian/Ubuntu:

sudo dpkg -i target/debian/shortcuts-overlay_*.deb

Fedora/RHEL:

sudo dnf install target/generate-rpm/shortcuts-overlay-*.rpm

Usage:

# Run with explicit size via CLI
shortcuts-overlay --width 1200 --height 800

# Run with custom anchor position
shortcuts-overlay --anchor topright

# Run with size and anchor
shortcuts-overlay --width 1200 --height 800 --anchor bottomleft

How It Works

• Press key: The overlay layer surface is created and displayed with your keyboard shortcuts
• Release key: The overlay layer surface is destroyed and hidden
• The application uses libinput (via the input crate) to monitor keyboard input globally, allowing it to detect key events even when the overlay doesn't have focus
• Libinput is the same input library used by Wayland compositors, providing stable and efficient event handling
• The overlay displays keyboard shortcuts found in your compositor's config file

Example Output

The overlay displays shortcuts like:

Super + Return: Launch terminal
Super + d: Launch application launcher  
Super + Shift + q: Close window
Super + f: Toggle fullscreen
Alt + Tab: Cycle windows

However, this is not recommended for security reasons. It's better to properly configure group membership.

Checking Device Access

To verify you have access to input devices:

ls -l /dev/input/event* | head -5
# Should show files readable by the 'input' group

groups
# Should include 'input'