dreader-application/README.md

pyWebLayout-ereader

A complete ebook reader application built with pyWebLayout.

This project demonstrates how to build a full-featured ebook reader using pyWebLayout's layout engine. It serves as both a reference implementation and a ready-to-use ereader library.

Features

• 📖 EPUB Support - Load and read EPUB files
• 📄 Page Navigation - Forward/backward navigation with smooth rendering
• 🔖 Bookmarks - Save and restore reading positions
• 🎨 Text Highlighting - Highlight words and selections with notes
• 🔍 Text Selection - Select and query text via touch/click
• ⚙️ Customization - Font size, line spacing, colors
• 📑 Chapter Navigation - Jump to chapters via table of contents
• 👆 Gesture Support - Tap, swipe, pinch, long-press handling
• 💾 Position Persistence - Stable positions across style changes

Installation

From Source

# Install pyWebLayout first if not already installed
cd /path/to/pyWebLayout
pip install -e .

# Install pyWebLayout-ereader
cd /path/to/pyWebLayout-ereader
pip install -e .

As a Dependency

pip install pyweblayout-ereader

Quick Start

from pyweblayout_ereader import EbookReader

# Create reader
reader = EbookReader(page_size=(800, 1000))

# Load an EPUB
reader.load_epub("mybook.epub")

# Get current page as image
page = reader.get_current_page()
page.save("current_page.png")

# Navigate
reader.next_page()
reader.previous_page()

# Save position
reader.save_position("bookmark1")

# Later, restore position
reader.load_position("bookmark1")

Examples

See the examples/ directory for complete examples:

• simple_ereader_example.py - Basic ereader usage
• ereader_demo.py - Full-featured demo with all capabilities
• word_selection_highlighting.py - Text selection and highlighting
• generate_ereader_gifs.py - Generate animated demos

Architecture

This project is a high-level application layer that combines pyWebLayout components:

pyweblayout_ereader.EbookReader
    ↓
├── pyWebLayout.layout.EreaderLayoutManager  # Layout & pagination
├── pyWebLayout.core.HighlightManager        # Highlighting system
├── pyWebLayout.io.gesture                   # Touch/gesture handling
└── pyWebLayout.io.readers                   # EPUB parsing

API Overview

Loading Content

reader.load_epub("book.epub")
reader.is_loaded()  # Check if book loaded
reader.get_book_info()  # Get metadata

Navigation

reader.next_page()
reader.previous_page()
reader.jump_to_chapter("Chapter 1")
reader.get_reading_progress()  # 0.0 to 1.0

Styling

reader.increase_font_size()
reader.decrease_font_size()
reader.set_font_size(1.5)  # 150% scale
reader.set_line_spacing(8)
reader.set_inter_block_spacing(20)

Bookmarks

reader.save_position("my_bookmark")
reader.load_position("my_bookmark")
reader.list_saved_positions()
reader.delete_position("my_bookmark")

Highlighting

# Highlight a word at pixel coordinates
highlight_id = reader.highlight_word(x=100, y=200, note="Important!")

# Highlight a selection
highlight_id = reader.highlight_selection(
    start=(100, 200),
    end=(300, 250),
    color=(255, 255, 0, 128)  # Yellow
)

# Manage highlights
reader.list_highlights()
reader.remove_highlight(highlight_id)
reader.clear_highlights()

Gesture Handling

from pyWebLayout.io.gesture import TouchEvent, GestureType

# Handle touch input
event = TouchEvent(GestureType.TAP, x=400, y=300)
response = reader.handle_touch(event)

# Response contains action type and data
if response.action == ActionType.PAGE_TURN:
    print(f"Page turned: {response.data['direction']}")

Use Cases

• Desktop Ereader Applications - Build native ereader apps
• Web-based Readers - Serve rendered pages via Flask/FastAPI
• E-ink Device Firmware - Optimized for e-ink displays
• Reading Analytics - Track reading patterns and highlights
• Educational Tools - Annotated reading with highlights and notes

Relationship to pyWebLayout

pyWebLayout is a layout engine library providing low-level primitives for:

• Text rendering and layout
• Document structure and pagination
• Query systems for interactive content

pyWebLayout-ereader is an application framework that:

• Combines pyWebLayout components into a complete reader
• Provides user-friendly APIs for common ereader tasks
• Manages application state (bookmarks, highlights, etc.)
• Handles business logic for gestures and interactions

Think of it like this:

• pyWebLayout = React (library)
• pyWebLayout-ereader = Next.js (framework)

Development

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black pyweblayout_ereader/

# Type checking
mypy pyweblayout_ereader/

Contributing

Contributions welcome! This project demonstrates what's possible with pyWebLayout. If you build something cool or find ways to improve the reader, please share!

License

MIT License - see LICENSE file for details

Related Projects

• pyWebLayout - The underlying layout engine
• Add your projects here!