wfx 220a886acc feat: add set as wallpaper functionality

Add ability to set current image as desktop wallpaper with keyboard
shortcut 'W' and icon button in Properties panel.

Supports COSMIC, GNOME, KDE, XFCE, and tiling window managers via
automatic detection and fallback mechanism.

Implementation uses wallpaper crate with custom COSMIC config file
integration and gsettings/feh fallbacks.

2026-01-15 20:40:53 +01:00

6.8 KiB

Raw Blame History

Usage Guide

Noctua is a modern image viewer for the COSMIC desktop environment with full keyboard support.

Opening Images

Command Line

Open an image directly from the terminal:

noctua /path/to/image.png

When you open an image, Noctua automatically scans the folder and indexes all supported images for quick navigation.

Supported Formats

Raster Images: PNG, JPEG, GIF, BMP, TIFF, WebP, and all formats supported by image-rs
Vector Graphics: SVG (planned, not yet implemented)
Portable Documents: PDF (planned, not yet implemented)

Keyboard Shortcuts

All keyboard shortcuts are case-insensitive unless otherwise noted.

Key	Action	Description
`←`	Previous image	Navigate to the previous image in the folder
`→`	Next image	Navigate to the next image in the folder

The footer shows your current position (e.g., "3 / 42").

Zoom and View

Key	Action	Description
`+` / `=`	Zoom in	Increase zoom by 10%
`-`	Zoom out	Decrease zoom by ~9%
`1`	Actual size (100%)	Display image at pixel-perfect 1:1 scale
`f`	Fit to window	Scale image to fit the window while preserving ratio

You can also zoom with the mouse wheel - the zoom centers on your cursor position.

The current zoom level is displayed in the footer (e.g., "150%" or "Fit").

Pan

Pan controls allow you to move around zoomed images:

Key	Action	Description
`Ctrl + ←`	Pan left	Move view to the left
`Ctrl + →`	Pan right	Move view to the right
`Ctrl + ↑`	Pan up	Move view upward
`Ctrl + ↓`	Pan down	Move view downward
`0`	Reset pan	Center the image

You can also click and drag with the mouse to pan around zoomed images.

Transformations

Key	Action	Description
`h`	Flip horizontal	Mirror the image horizontally
`v`	Flip vertical	Flip the image upside down
`r`	Rotate clockwise	Rotate 90° clockwise
`Shift + r`	Rotate counter-clockwise	Rotate 90° counter-clockwise

All transformations are lossless and show in real-time.

Panels and UI

Key	Action	Description
`i`	Toggle properties	Show/hide the properties panel (metadata)
`n`	Toggle navigation	Show/hide the navigation sidebar

Actions

Key	Action	Description
`w`	Set as wallpaper	Set the current image as desktop wallpaper

Mouse Controls

Zoom

Mouse wheel up/down: Zoom in/out centered on cursor
Footer buttons: Click zoom in/out buttons for step-by-step control

Pan

Click and drag: Pan around zoomed images
Hold and drag anywhere on the image to move the view

Footer navigation: Use Previous/Next buttons to browse images

The header toolbar provides quick access to common operations:

Left Side

Navigation toggle: Show/hide the sidebar
Previous/Next buttons: Navigate between images in the folder
Rotate buttons: Rotate clockwise or counter-clockwise
Flip buttons: Flip horizontally or vertically

Right Side

Properties toggle: Show/hide the metadata panel

Properties Panel

The properties panel (toggle with i) displays image metadata and provides quick actions:

Action Buttons

Located at the top-right of the properties panel:

Set as Wallpaper (w key): Set the current image as your desktop wallpaper
- Works with COSMIC, GNOME, KDE, XFCE, and tiling window managers
- Automatically detects your desktop environment
- Falls back to alternative methods if the primary method fails
Open With (planned): Open the image with another application
Show in Folder (planned): Open the containing folder in your file manager

Metadata Display

File Information: Name, format, dimensions, file size, color type
Camera Information (if available): Camera model, date taken, exposure settings, GPS location

Footer Information

The footer displays useful information:

Zoom controls: Zoom out, current zoom level, zoom in, fit buttons
Image dimensions: Width × Height in pixels
Navigation position: Current image / Total images in folder

Tips and Tricks

Keyboard-Driven Workflow

Noctua is designed for efficient keyboard use:

Open an image from terminal
Use ← → to browse through the folder
Press r to rotate, h or v to flip
Use + - to zoom, Ctrl + arrows to pan
Press i to check metadata

Zoom and Pan Together

Zoom with mouse wheel while hovering over the area you want to examine
The zoom centers on your cursor, making it easy to focus on details
Once zoomed, drag with mouse or use Ctrl + arrows to navigate

Bidirectional Controls

Mouse and keyboard work together seamlessly:

Zoom with keyboard, pan with mouse
Zoom with mouse wheel, the footer updates automatically
Pan with keyboard, continue with mouse drag

Configuration

Settings are stored in ~/.config/cosmic/org.codeberg.wfx.Noctua/v1/.

Configurable Options

Default directory: Set your preferred starting location
Panel states: Your panel preferences are remembered between sessions

Planned Features

The following features are prepared in code but not yet implemented:

File Operations

File open dialog
Save transformed images
Copy/Move/Delete operations

Document Support

SVG rendering with resvg
PDF rendering with multi-page support

Advanced Editing

Crop mode (c key prepared)
Scale/Resize mode (s key prepared)

See features.md for a complete list of planned features.

6.8 KiB Raw Blame History Unescape Escape