dtourolle/pyWebLayout
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
pyWebLayout/docs/images
History

README.md

pyWebLayout Visual Documentation

This directory contains visual documentation for pyWebLayout, including animated GIF demonstrations of the EbookReader functionality and static example outputs showcasing various features.

Generated GIFs

1. Page Navigation (ereader_page_navigation.gif)

Demonstrates forward and backward page navigation through an EPUB book. Shows smooth transitions between pages using next_page() and previous_page() methods.

Features shown:

  • Sequential page advancement
  • Page-by-page content rendering
  • Natural reading flow

2. Font Size Adjustment (ereader_font_size.gif)

Shows dynamic font size scaling from 0.8x to 1.4x and back. The reader maintains the current reading position even as the layout changes with different font sizes.

Features shown:

  • increase_font_size() / decrease_font_size()
  • set_font_size(scale) with specific values
  • Position preservation across layout changes
  • Text reflow with different sizes

3. Chapter Navigation (ereader_chapter_navigation.gif)

Demonstrates jumping between chapters in a book. Each chapter's first page is displayed, showing the ability to navigate non-linearly through the content.

Features shown:

  • jump_to_chapter(index) for index-based navigation
  • jump_to_chapter(title) for title-based navigation
  • get_chapters() to list available chapters
  • Quick access to any part of the book

4. Bookmarks & Positions (ereader_bookmarks.gif)

Illustrates the bookmark system: navigating to a position, saving it, navigating away, and then returning to the saved position.

Features shown:

  • save_position(name) to bookmark current location
  • load_position(name) to return to saved bookmark
  • Position stability across navigation
  • Multiple bookmark support

Generating Your Own GIFs

To generate these animations with your own EPUB file:

cd examples
python generate_ereader_gifs.py path/to/your/book.epub ../docs/images/

This will create all four GIF animations in the specified output directory.

Script Options

python generate_ereader_gifs.py <epub_path> [output_dir]
  • epub_path: Path to your EPUB file (required)
  • output_dir: Directory to save GIFs (default: current directory)

Customization

You can modify generate_ereader_gifs.py to adjust:

  • Frame duration (duration parameter in create_gif())
  • Page dimensions (change page_size in EbookReader)
  • Number of frames for each animation
  • Font scale ranges
  • Animation sequences

Technical Details

  • Format: Animated GIF
  • Page Size: 600x800 pixels
  • Frame Rate: Variable (500-1000ms per frame)
  • Loop: Infinite
  • Book Used: Alice's Adventures in Wonderland (test.epub)

File Sizes

GIF Size Frames Duration per Frame
ereader_page_navigation.gif ~500 KB 10 600ms
ereader_font_size.gif ~680 KB 13 500ms
ereader_chapter_navigation.gif ~290 KB 11 1000ms
ereader_bookmarks.gif ~500 KB 17 600ms

Example Outputs

Static PNG images generated by the example scripts, demonstrating various pyWebLayout features.

Example 01: Simple Page Rendering

File: example_01_page_rendering.png Source: examples/01_simple_page_rendering.py Demonstrates: Page styles, borders, padding, background colors

Example 06: Functional Elements

File: example_06_functional_elements.png Source: examples/06_functional_elements_demo.py Demonstrates: Buttons, form fields, interactive elements

Example 08: Pagination (NEW)

Files:

  • example_08_pagination_explicit.png (109 KB) - 5 pages with explicit PageBreaks
  • example_08_pagination_auto.png (87 KB) - 2 pages with automatic pagination

Source: examples/08_pagination_demo.py Test: tests/examples/test_08_pagination_demo.py

Demonstrates:

  • Using PageBreak to force content onto new pages
  • Multi-page document layout with explicit breaks
  • Automatic pagination when content overflows
  • Page numbering functionality
  • Document flow control

Coverage: ✅ Fills critical gap - PageBreak had NO examples before this

Example 09: Link Navigation (NEW)

File: example_09_link_navigation.png (60 KB) Source: examples/09_link_navigation_demo.py Test: tests/examples/test_09_link_navigation_demo.py

Demonstrates:

  • Internal links - Document navigation (#section1, #section2)
  • External links - Web URLs (https://example.com)
  • API links - API endpoints (/api/settings, /api/save)
  • Function links - Direct function calls (calculate(), process())
  • Link styling (underlined, color-coded by type)
  • Link callbacks and interactivity

Coverage: ✅ Comprehensive - All 4 LinkType variations demonstrated

Example 10: Comprehensive Forms (NEW)

File: example_10_forms.png (31 KB) Source: examples/10_forms_demo.py Test: tests/examples/test_10_forms_demo.py

Demonstrates all 14 FormFieldType variations:

Text-Based Fields:

  • TEXT - Standard text input
  • EMAIL - Email validation field
  • PASSWORD - Password masking
  • URL - URL validation
  • TEXTAREA - Multi-line text

Number/Date/Time Fields:

  • NUMBER - Numeric input
  • DATE - Date picker
  • TIME - Time selector
  • RANGE - Slider control
  • COLOR - Color picker

Selection Fields:

  • CHECKBOX - Boolean selection
  • RADIO - Single choice from options
  • SELECT - Dropdown menu
  • HIDDEN - Hidden form data

Coverage: ✅ Complete - All 14 field types across 4 practical examples

Generating New Examples

Run Individual Examples

# Navigate to project root
cd /path/to/pyWebLayout

# Run specific example
python examples/08_pagination_demo.py
python examples/09_link_navigation_demo.py
python examples/10_forms_demo.py

Run All Example Tests

# Run all example tests with pytest
python -m pytest tests/examples/ -v

# Run specific test file
python -m pytest tests/examples/test_08_pagination_demo.py -v

All new examples (08, 09, 10) include:

  • ✅ Comprehensive documentation
  • ✅ Full test coverage (30 tests total)
  • ✅ Visual output verification
  • ✅ Working code examples

See NEW_EXAMPLES_AND_TESTS_SUMMARY.md for detailed information.

Usage in Documentation

These visual assets are used throughout the pyWebLayout documentation to showcase capabilities.

To embed in Markdown:

![Page Navigation](docs/images/ereader_page_navigation.gif)
![Pagination Example](docs/images/example_08_pagination_explicit.png)

To embed in HTML with size control:

<img src="docs/images/ereader_page_navigation.gif" width="300" alt="Page Navigation">
<img src="docs/images/example_08_pagination_explicit.png" width="400" alt="Pagination">