From 3726ea16de06f2e3b75b9899cfa868e2668dbd36 Mon Sep 17 00:00:00 2001 From: mow Date: Thu, 15 Jan 2026 18:42:30 +0100 Subject: [PATCH] docs: update usage guide to current implementation status - Mark all zoom and pan controls as fully working - Remove status column (all shortcuts are implemented) - Add detailed descriptions for each feature - Include mouse controls and toolbar usage - Add tips for keyboard-driven workflow - Document bidirectional control synchronization - Remove or mark planned features accurately --- docs/usage.md | 175 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 143 insertions(+), 32 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index 18774a7..5e1e2f6 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,46 +1,157 @@ -# Usage +# 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: +```bash +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. + ### Navigation -| Key | Action | Status | -|:------|:------------------|:--------| -| `←` | Previous document | working | -| `→` | Next document | working | +| Key | Action | Description | +|:------|:------------------|:-----------------------------------------------| +| `←` | Previous image | Navigate to the previous image in the folder | +| `→` | Next image | Navigate to the next image in the folder | -### Transformations +The footer shows your current position (e.g., "3 / 42"). -| Key | Action | Status | -|:------------|:-------------------------------|:--------| -| `H` | Flip horizontal | working | -| `V` | Flip vertical | working | -| `R` | Rotate clockwise (90°) | working | -| `Shift + R` | Rotate counter-clockwise (90°) | working | +### Zoom and View -### Zoom +| 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 | -| Key | Action | Status | -|:----------|:---------------------------|:--------| -| `+` / `=` | Zoom in | partial | -| `-` | Zoom out | partial | -| `1` | Reset zoom (100% / actual) | working | -| `F` | Fit image to window | working | +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 -| Key | Action | Status | -|:-----------|:-------------------|:--------------------| -| `Ctrl + ←` | Pan left | not yet implemented | -| `Ctrl + →` | Pan right | not yet implemented | -| `Ctrl + ↑` | Pan up | not yet implemented | -| `Ctrl + ↓` | Pan down | not yet implemented | -| `0` | Reset pan (center) | not yet implemented | +Pan controls allow you to move around zoomed images: -### Modes +| 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 | -| Key | Action | Status | -|:----|:-----------------------|:--------------------| -| `C` | Toggle crop mode | not yet implemented | -| `S` | Toggle scale mode | not yet implemented | -| `A` | Toggle anotation mode | not yet implemented | +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 | + +## 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 + +### Navigation +- **Footer navigation**: Use Previous/Next buttons to browse images + +## Toolbar + +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 + +## 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: +1. Open an image from terminal +2. Use `←` `→` to browse through the folder +3. Press `r` to rotate, `h` or `v` to flip +4. Use `+` `-` to zoom, `Ctrl + arrows` to pan +5. 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/noctua/config.toml`. + +### 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](features.md) for a complete list of planned features.