noctua/docs/usage.md

# 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 (with scalable rendering)
- **Portable Documents**: PDF (with multi-page navigation and thumbnails)

## Keyboard Shortcuts

All keyboard shortcuts are case-insensitive unless otherwise noted.

### Navigation

| 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").

For multi-page documents (PDF):
- Click thumbnails in the left sidebar to jump to a specific page
- Use `←` `→` to navigate between pages

### 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         |

For multi-page documents (PDF), the navigation sidebar displays page thumbnails.
Click on a thumbnail to jump to that page.

### 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

### 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

### Center (Horizontally Centered)
- **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

For PDFs, it also shows the current page number.

## 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/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 (implemented)

### 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.