dtourolle/dreader-application
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dreader-application/examples/LIBRARY_DEMO.md
Duncan Tourolle b5ae08c2b5
Some checks failed
Python CI / test (push) Has been cancelled
Details
undo mis-commit
2025-11-08 20:11:44 +01:00

4.5 KiB
Raw Blame History

Library Reading Demo

This directory contains scripts to demonstrate the complete LIBRARY ↔ READING workflow for the dreader e-reader application.

Demo GIF

File: doc/images/library_reading_demo.gif (591 KB, 800x1200 pixels)

What the Demo Shows

The animated GIF demonstrates the complete user workflow:

  1. Library View (2s)

    • Shows a grid of available books
    • Title: "📚 My Library - Select a book"

  2. Book Selection (1.5s)

    • Visual tap indicator on the first book
    • Shows where user taps to select

  3. Reading Pages (5 frames, ~5s total)

    • Opens "Alice's Adventures in Wonderland"
    • Shows 5 consecutive pages
    • Page turns are animated
    • Progress shown in header

  4. Settings Overlay (2s)

    • Shows settings panel with font controls
    • Highlights "Back to Library" button
    • Visual tap indicator showing where to click

  5. Return to Library (2s)

    • Book closes, position saved automatically
    • Library view shown again
    • Annotation: "Back to Library (position saved)"

  6. Reopen Book (1.5s)

    • User taps same book again
    • Visual indicator shows reselection

  7. Auto-Resume (3s)

    • Book opens at saved position (24.6% progress)
    • Shows the exact page where user left off
    • Annotation: "✅ Auto-resumed at 24.6%"

Total Duration: ~17 seconds (looping)

Scripts

generate_library_demo_gif.py

Generate the demo GIF showing the complete workflow.

Usage:

python generate_library_demo_gif.py path/to/library [output.gif]

Examples:

# Generate to default location (doc/images/library_reading_demo.gif)
python generate_library_demo_gif.py tests/data/library-epub/

# Generate to custom location
python generate_library_demo_gif.py tests/data/library-epub/ doc/images/custom_demo.gif

Features:

  • Automatic book scanning and cover extraction
  • Visual tap indicators showing user interactions
  • Annotations explaining each step
  • Configurable frame durations
  • Auto-resume demonstration

library_reading_integration.py

Comprehensive integration test for the library ↔ reading workflow.

Usage:

python library_reading_integration.py path/to/library

What it Tests:

  1. Library scanning and rendering
  2. Book selection via tap
  3. Book loading and reading
  4. Page navigation (swipe gestures)
  5. Settings overlay
  6. Settings adjustments (font size)
  7. Back to library button
  8. Auto-resume functionality
  9. Multiple book selection

Output: Generates PNG images for each step (8 images total)

Implementation Status

✅ Complete Features

  • Library Management (library.py)

    • Book scanning and metadata extraction
    • Cover image caching
    • Interactive book selection
    • Clickable book rows

  • Reading Mode (application.py)

    • EPUB rendering
    • Page navigation (swipe, tap)
    • Progress tracking
    • Position saving/loading

  • State Persistence (state.py)

    • Auto-save on page turn
    • Resume at last position
    • Settings persistence
    • Per-book bookmarks

  • Overlays

    • TOC (Table of Contents) - ✅ Working
    • Settings - ✅ Working
    • Bookmarks - ✅ Working

🚧 Known Issues

  • HTML Link Interactivity: The "Back to Library" button in settings overlay doesn't respond to taps
    • Root cause documented in HTML_LINKS_INVESTIGATION.md
    • Workaround: Will be implemented using programmatic UI generation
    • Does not affect the demo GIF (which shows the intended workflow)

Requirements

  • Python 3.8+
  • PIL/Pillow (for image generation)
  • dreader application
  • pyWebLayout library
  • Test EPUB files in the library directory

File Sizes

  • Demo GIF: ~622 KB (optimized for quality)
  • Integration test PNGs: ~50-170 KB each
  • Total demo assets: <2 MB

Demo Generation Time

  • Library scanning: <1 second
  • EPUB loading: <1 second
  • Page rendering: ~0.5 seconds per page
  • Total: ~10-15 seconds to generate complete GIF

Use Cases

  1. Documentation: Visual demonstration of application features
  2. Testing: Verify complete workflow end-to-end
  3. Presentations: Show stakeholders the user experience
  4. Debugging: Identify issues in the workflow
  5. Training: Help users understand the application flow

See Also