211 lines
5.2 KiB
Markdown
211 lines
5.2 KiB
Markdown
# pyWebLayout-ereader
|
|
|
|
A complete ebook reader application built with [pyWebLayout](https://github.com/yourusername/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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
pip install pyweblayout-ereader
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
reader.load_epub("book.epub")
|
|
reader.is_loaded() # Check if book loaded
|
|
reader.get_book_info() # Get metadata
|
|
```
|
|
|
|
### Navigation
|
|
|
|
```python
|
|
reader.next_page()
|
|
reader.previous_page()
|
|
reader.jump_to_chapter("Chapter 1")
|
|
reader.get_reading_progress() # 0.0 to 1.0
|
|
```
|
|
|
|
### Styling
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
reader.save_position("my_bookmark")
|
|
reader.load_position("my_bookmark")
|
|
reader.list_saved_positions()
|
|
reader.delete_position("my_bookmark")
|
|
```
|
|
|
|
### Highlighting
|
|
|
|
```python
|
|
# 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
|
|
|
|
```python
|
|
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
|
|
|
|
```bash
|
|
# 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](https://github.com/yourusername/pyWebLayout) - The underlying layout engine
|
|
- Add your projects here!
|