165 lines
4.5 KiB
Markdown
165 lines
4.5 KiB
Markdown
# 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`](../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**:
|
|
```bash
|
|
python generate_library_demo_gif.py path/to/library [output.gif]
|
|
```
|
|
|
|
**Examples**:
|
|
```bash
|
|
# 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**:
|
|
```bash
|
|
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](../dreader/library.py))
|
|
- Book scanning and metadata extraction
|
|
- Cover image caching
|
|
- Interactive book selection
|
|
- Clickable book rows
|
|
|
|
- **Reading Mode** ([application.py](../dreader/application.py))
|
|
- EPUB rendering
|
|
- Page navigation (swipe, tap)
|
|
- Progress tracking
|
|
- Position saving/loading
|
|
|
|
- **State Persistence** ([state.py](../dreader/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](../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
|
|
|
|
- [REQUIREMENTS.md](../REQUIREMENTS.md) - Full application requirements
|
|
- [HTML_GENERATION.md](../HTML_GENERATION.md) - HTML rendering documentation
|
|
- [HTML_LINKS_INVESTIGATION.md](../HTML_LINKS_INVESTIGATION.md) - Link interactivity debugging
|