garview

Overview

garview is an image and document viewer designed for the gardesk desktop environment. It provides a unified interface for viewing images, browsing photo galleries, and reading PDF documents. Built with the gartk rendering framework, it offers smooth performance with hardware-accelerated rendering.

The viewer operates in two primary modes: Image mode for focused single-file viewing with zoom, pan, and rotation controls, and Gallery mode for browsing directories of images with thumbnail previews and sorting options. For PDF documents, it provides additional features like text search, selection, table of contents navigation, and clickable hyperlinks.

Key differentiators include session persistence (remembering your position in documents), EXIF-aware orientation handling, animated GIF support with proper frame timing, and a built-in slideshow mode for presentations.

Architecture

garview uses a modular architecture with pluggable backends for different file formats:

┌─────────────────────────────────────────────────────┐
│                    Application                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐  │
│  │  Image   │  │  Gallery │  │      Sidebar      │  │
│  │  Viewer  │  │   View   │  │  (Thumbnails/TOC) │  │
│  └────┬─────┘  └────┬─────┘  └────────┬─────────┘  │
│       │             │                  │            │
│  ┌────┴─────────────┴──────────────────┴────────┐  │
│  │              Backend Manager                  │  │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │  │
│  │  │  Image  │ │   PDF   │ │       SVG       │ │  │
│  │  │ Backend │ │ Backend │ │     Backend     │ │  │
│  │  │ (image) │ │(poppler)│ │     (resvg)     │ │  │
│  │  └─────────┘ └─────────┘ └─────────────────┘ │  │
│  └──────────────────────────────────────────────┘  │
│                                                     │
│  ┌─────────────────────────────────────────────┐   │
│  │         gartk-render (Cairo/GPU)            │   │
│  └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

Backend System

Each backend implements a common trait providing format detection, loading, rendering, and format-specific capabilities. The backend manager automatically selects the appropriate backend based on file extension and MIME type detection.

Rendering Pipeline

garview uses gartk-render, the same Cairo-based rendering system used by other gardesk components. The pipeline handles coordinate transformation, zoom calculations, and efficient partial redraws:

1. Backend renders the image/page at the current scale factor
2. Zoom state calculates effective dimensions based on mode (fit/fill/1:1/custom)
3. Scroll state applies pan offset, clamping to image bounds
4. Centering positions smaller images in viewport center
5. Compositor blits to screen, overlays UI elements (status bar, sidebar)

The zoom range spans 5% to 2000% (0.05x to 20x), with 1.25x steps for zoom in/out operations. Scroll-wheel zoom at cursor maintains the pointed location stable during zoom operations.

Caching Layer

garview implements caching at multiple levels to optimize performance:

• RGBA cache: Decoded pixel data stored at native resolution, avoiding re-decode during zoom/pan
• Thumbnail cache: Gallery thumbnails generated on-demand and stored in memory for smooth scrolling
• Page cache: PDF pages cached at current zoom level, regenerated only when zoom changes significantly
• Session cache: Per-file viewing state (page, zoom, scroll) persisted to disk

View Modes

garview operates in two primary modes, switchable with Tab or g:

Image Mode

The primary viewing mode for focused single-file display. Features include:

• Zoom controls: Fit, fill, 1:1, and custom zoom levels
• Pan: Mouse drag or arrow keys when zoomed beyond viewport
• Rotation: 90-degree increments, clockwise or counter-clockwise
• Flip: Horizontal and vertical mirroring
• Navigation: Previous/next image in directory with arrow keys
• Smart scroll: At image bounds, arrow keys navigate to adjacent images

For multi-page documents, page navigation keys (PageUp/PageDown/Home/End) are available, and scrolling past page bounds automatically advances to the next page.

Gallery Mode

A thumbnail browser for navigating directories of images. When you open a directory or toggle from image mode, garview displays a grid of thumbnails from the current image's directory.

Navigation uses vim-style keys (hjkl) or arrow keys. Press Enter or Space to open the selected image in Image mode. The gallery supports three sort modes (name, date, size) cyclable with s, and reversible with S.

Document View Modes

For multi-page documents (PDFs), garview offers three viewing layouts:

Press V to cycle through modes, or use the number keys for direct access. In continuous mode, scrolling flows naturally between pages. In single page mode, scrolling past the bottom advances to the next page.

Features

Zoom & Pan

The zoom system supports four modes with a range of 5% to 2000%:

• Fit (f): Scale to fit entire image in viewport, preserving aspect ratio
• Fill (F): Scale to fill viewport completely, cropping edges if needed
• 1:1 (0): Actual pixels, 1 image pixel = 1 screen pixel
• Custom (+/-): Manual zoom with 1.25x steps

Ctrl+scroll wheel zooms at the cursor position, keeping the pointed location stable. This is particularly useful for examining specific areas of large images or documents.

Pan with mouse drag or arrow keys. When the image is smaller than the viewport, it's automatically centered. Panning is clamped to image bounds to prevent scrolling into empty space.

Rotation & Flip

Images can be rotated and flipped for correct orientation:

• r - Rotate 90 degrees clockwise
• R - Rotate 90 degrees counter-clockwise
• h - Flip horizontally (mirror)
• v - Flip vertically

Rotations are applied on top of EXIF auto-rotation. If auto_rotate_exif is enabled (default), JPEG images from cameras are automatically oriented correctly before any manual rotation is applied.

Slideshow

Built-in slideshow mode auto-advances through images in a directory:

• s - Toggle slideshow on/off
• [ - Decrease interval by 0.5 seconds (min 1s)
• ] - Increase interval by 0.5 seconds (max 30s)
• --slideshow - Start in slideshow mode from CLI

Combine with --fullscreen for presentation mode. The default interval is 5 seconds, adjustable in 0.5-second increments from 1 to 30 seconds.

Text Selection & Search

For PDF documents, garview provides full text interaction:

• Selection: Shift+drag to select text. Uses glyph-level precision for accurate word boundaries.
• Auto-copy: Selected text is automatically copied to clipboard when selection ends.
• Search: Ctrl+F opens search dialog. Results are highlighted on the page.
• Navigation: F3/n for next result, Shift+F3/N for previous. Wraps at document ends.

Search is backend-dependent - it's available for PDFs (via poppler's text extraction) but not for raster images. The search state (query, results, current index) persists until Escape is pressed.

Clipboard

garview integrates with system clipboard using arboard:

• Ctrl+C - Copy selected text (PDFs)
• Ctrl+Shift+C - Copy current image to clipboard
• Text selection auto-copies to PRIMARY clipboard (X11)

PDF Features

PDF Rendering

PDF rendering uses poppler-glib, the same library powering Evince and other GTK PDF viewers. Pages are rendered to Cairo image surfaces at the current zoom level, then pixel-converted from Cairo's BGRA format to RGBA for display.

The white background is drawn first, then the PDF content is rendered on top. This ensures proper rendering of PDFs with transparency. Font rendering uses system font fallbacks when embedded fonts are missing.

Page Navigation

Multiple navigation methods for PDF documents:

• PageDown/PageUp - Next/previous page
• Home/End - First/last page
• Ctrl+G - Go to specific page number
• Scroll at bounds - Auto-advances in single-page mode
• Arrow keys at bounds - Navigate pages when panning hits edge
• Sidebar click - Jump to any page via thumbnail
• TOC click - Jump via table of contents entry

Links & Table of Contents

garview supports three types of PDF links:

• GOTO_DEST: Internal links to other pages. Click to jump.
• URI: External URLs. Opens in default browser.
• NAMED: Named destinations within the document.

The table of contents is extracted from the PDF's document outline using poppler's index iterator. It appears in the sidebar (F7) as a hierarchical tree with depth indication. Click any entry to jump to that section.

Text Search

Full-text search across all PDF pages:

1. Press Ctrl+F to open search dialog
2. Type search query and press Enter
3. All pages are searched, results stored as page + bounding rectangle pairs
4. First result is displayed with highlighting
5. Press F3 or n for next result
6. Press Shift+F3 or N for previous
7. Search wraps at document ends
8. Press Escape to clear search

Sidebar

Toggle the sidebar with F7. The 200-pixel sidebar provides two tabs:

The sidebar interacts with scroll events - scrolling while the cursor is over the sidebar scrolls the sidebar content, not the document.

Session Persistence

garview remembers your viewing state for each file, stored in ~/.local/share/garview/recent.json. For each recently opened file, the following state is tracked:

• Page number: Current page for multi-page documents
• Zoom level: Current zoom percentage
• Scroll position: Normalized (x, y) offset within the document
• Last opened: Timestamp for recent files sorting

When you reopen a file, garview restores your position if remember_position and/or remember_zoom are enabled in config. Session is saved automatically when navigating away from a file or closing garview.

Recent Files

Press Ctrl+R to open the recent files panel. garview tracks up to 50 recently opened files (configurable via max_entries).

Features:

• Files sorted by last opened time (most recent first)
• Non-existent files automatically removed on load
• Navigate with arrow keys, open with Enter
• Delete entries with d or Backspace
• Session state (page, zoom, scroll) stored per file