# ePDFView

A free and lightweight PDF document viewer written in C++ (C++14) using GTK4 and the Poppler rendering library. It focuses on simplicity and the essential features for viewing and navigating PDF documents.

Version: 0.3.0  
License: GPL-2.0-or-later  
Status: ✅ **Stable** (GTK4 migration complete I guess)

## Overview

ePDFView provides a fast, minimal PDF reading experience with a modern GTK4 UI and broad translation support. Originally a GTK2/GTK3 app, it has been successfully migrated to GTK4 with all core features working.

Key features:
- Page navigation (next, previous, first, last, jump to page)
- Zoom controls (in, out, fit page, fit width, custom)
- Page rotation (left, right)
- Text search with highlighting
- Document outline/index sidebar
- Full screen presentation mode
- Invert colors for night reading
- Print support (via CUPS on Linux/BSD)
- 22 language translations
- Keyboard shortcuts for all operations

## Stack and Tooling
- Language: C++ (C++14)
- GUI Framework: GTK4 (>= 4.0.0)
- PDF Rendering: Poppler-glib (>= 0.5.0)
- Core libs: GLib (gthread-2.0), Pango
- Build system: Meson (>= 0.50.0) with Ninja backend
- Internationalization: Meson i18n with `po/`
- Optional: CUPS for printing (feature auto-detected; disabled on Windows)

Entry point
- Binary target: `epdfview` (defined in `src/meson.build`)

Meson options (from `meson_options.txt`):
- `-Dtests=true|false` — Build test suite (default: false)
- `-Dcups=enabled|disabled|auto` — Enable CUPS printing support (default: auto)

## Requirements
Build-time dependencies:
- GTK4 >= 4.0.0
- Poppler-glib >= 0.5.0
- GLib (gthread-2.0) >= 2.8.0
- Pango
- Meson >= 0.50.0
- A C++ compiler with C++14 support
- Optional: CUPS (printing; auto-detected, disabled on Windows)

## Platform Support
- **Linux** ✅ Fully supported (X11 and Wayland)
- **FreeBSD** ✅ Fully supported
- **Windows** ✅ Supported via MSYS2 (see `docs/BUILD_WINDOWS.md`)
- **WSL** ✅ Works with X11 server (see `RUN_EPDFVIEW_WSL.md`)

## Setup and Build
Standard Meson build:

```bash
meson setup builddir
meson compile -C builddir
```

Install (system-wide):

```bash
sudo meson install -C builddir
```

Run without installing (from the build tree, platform permitting):

```bash
./builddir/src/epdfview [file.pdf]
```

Run after install:

```bash
epdfview [file.pdf]
```

For platform-specific instructions:
- **Windows (MSYS2):** See `docs/BUILD_WINDOWS.md`
- **WSL:** See `RUN_EPDFVIEW_WSL.md`

## Scripts
Convenience/testing scripts in the repository root:
- `test_index.sh` — automated index/navigation test harness (POSIX shell)
- `test_index_manual.sh` — manual test aid (POSIX shell)

On Windows, use WSL/MSYS2 to run these shell scripts.

## Configuration and Environment
- User settings are stored at: `~/.config/epdfview/main.conf` (created on first run).
- Known environment variables: none specific to ePDFView.
  - TODO: Document any runtime environment variables or flags if/when they are introduced.

## Tests
Meson option `tests` controls inclusion of the test suite. Tests depend on `cppunit` if available.

To configure and run tests:

```bash
meson setup builddir -Dtests=true
meson test -C builddir
```

If `cppunit` is not found, the unit tests will be skipped at build time (a warning will be shown).

The repository also includes simple test scripts (`test_index.sh` and `test_index_manual.sh`).

## Keyboard Shortcuts
Navigation:
- Page Down / Space — Next page
- Page Up / Backspace — Previous page
- Home — First page
- End — Last page

Zoom:
- `+` — Zoom in
- `-` — Zoom out
- `1` — Fit page
- `2` — Fit width

View:
- F11 — Full screen
- `I` — Invert colors
- `R` — Rotate right
- `Ctrl+R` — Rotate left

Other:
- `Ctrl+F` — Find
- `Ctrl+P` — Print
- `Ctrl+Q` — Quit

## Project Structure
```
.
├─ src/                 # Application source (GTK4 UI, core logic)
├─ src/gtk/             # GTK4 views and UI components
├─ data/                # App data/resources (icons, desktop files, etc.)
├─ po/                  # Translations (i18n)
├─ docs/                # Additional documentation (migration, install)
├─ tests/               # Meson tests (enabled with -Dtests=true)
├─ snap/                # Packaging assets for Snap (if applicable)
├─ meson.build          # Project definition (version, deps, options)
├─ meson_options.txt    # Build options (e.g., cups, tests)
└─ README               # This file
```

Refer to `meson.build` and `src/meson.build` for build targets and dependencies.

## Documentation
Additional documentation is available in `docs/`:

**Migration and Development:**
- `GTK4_MIGRATION_SUMMARY.md` — Technical migration summary
- `CRASH_FIX_2025-11-12.md` — Critical bug fixes and lessons learned
- `TODO_NEXT_SESSION.md` — Development roadmap and pending tasks
- `BUILD_WINDOWS.md` — Complete Windows/MSYS2 build guide

**Build and Installation:**
- `INSTALLATION.md` — Comprehensive installation guide
- `BUILD_STATUS.md` — Build system notes
- `COMPILATION_SUCCESS.md` — Compilation milestones

**Features:**
- `COMPLETE_GTK4_MIGRATION.md` — Migration milestone and features
- `MENU_SYSTEM_COMPLETE.md` — Menu system implementation
- `TRANSLATIONS_AND_DOCS.md` — Translation guide
- `FINAL_FIXES.md` — Final GTK4 fixes
- `PRINT_MIGRATION_TODO.md` — Print system notes

User-facing root docs:
- `INSTALL` — Quick installation instructions
- `TRANSLATION` — Translation guide
- `CONTRIBUTING` — Contribution guidelines
- `RUN_EPDFVIEW_WSL.md` — WSL-specific instructions

## License
GPL-2.0-or-later. See `COPYING` for the full text.

## Support and Links
- Homepage: https://github.com/JotaRandom/epdfview
- Issues: https://github.com/JotaRandom/epdfview/issues
- CI/CD: ![Build Status](https://github.com/JotaRandom/epdfview/actions/workflows/build.yml/badge.svg)

## Changelog and Status
- **Current Status:** See `PROJECT_STATUS.md` for detailed project status
- **Recent Changes:** See `ChangeLog` and `NEWS` for version history
- **Development:** See `docs/TODO_NEXT_SESSION.md` for ongoing work

## Recent Improvements (November 2025)
- ✅ Fixed critical crash on startup (PreferencesView lifetime management)
- ✅ Navigation buttons work correctly (no more stuck "pressed" state)
- ✅ Page numbers update visually in headerbar
- ✅ Improved compilation warnings (100+ → ~82)
- ✅ Windows build support added (MSYS2)
- ✅ FreeBSD CI/CD added
- ✅ Application ID updated to io.github.jotarandom.epdfview

## TODOs
- Fix PrintView GListStore type issues (GBoxedType → GObject)
- Clean remaining compilation warnings (~82 left)
- Comprehensive testing across platforms
- Consider migrating to std::unique_ptr for safer memory management

For detailed development tasks, see `docs/TODO_NEXT_SESSION.md`.