pyWebLayout/examples/README.md

PyWebLayout Examples

This directory contains example scripts demonstrating the pyWebLayout library.

Getting Started Examples

These examples demonstrate the core rendering capabilities of pyWebLayout:

01. Simple Page Rendering

01_simple_page_rendering.py - Introduction to the Page system

python 01_simple_page_rendering.py

Demonstrates:

• Creating pages with different styles
• Setting borders, padding, and backgrounds
• Understanding page layout structure
• Basic rendering to images

02. Text and Layout

02_text_and_layout.py - HTML parsing and text rendering

python 02_text_and_layout.py

Demonstrates:

• Parsing HTML content
• Text alignment options
• Font sizes and styles
• Document structure

03. Page Layouts

03_page_layouts.py - Different page configurations

python 03_page_layouts.py

Demonstrates:

• Various page sizes (portrait, landscape, square)
• Different aspect ratios
• Border and padding variations
• Color schemes

04. Table Rendering

04_table_rendering.py - HTML table rendering with styling

python 04_table_rendering.py

Demonstrates:

• Rendering HTML tables
• Table headers and body rows
• Cell borders and padding
• Caption support
• Custom table styling

05. Tables with Images

05_html_table_with_images.py - Tables containing images and mixed content

python 05_html_table_with_images.py

Demonstrates:

• Creating tables programmatically
• Adding images to table cells
• Book catalog and product showcase tables
• Mixed content (images and text) in cells
• Using cover images from test data
• HTML table parsing with <img> tags

06. Functional Elements (Interactive)

06_functional_elements_demo.py - Interactive buttons and forms with callbacks

python 06_functional_elements_demo.py

Demonstrates:

• Creating interactive buttons
• Building forms with multiple field types
• Post-layout callback binding
• CallbackRegistry system for managing interactables
• Accessing application state from callbacks
• Batch callback operations
• Simulating user interactions

07. Button Pressed States (Interactive)

07_pressed_state_demo.py - Visual feedback for button interactions

python 07_pressed_state_demo.py

Demonstrates:

• Button pressed/released state management
• Visual feedback timing (150ms press duration)
• Automatic interaction handling with InteractionHandler
• Manual state management for custom event loops
• Dirty flag system for optimized re-rendering
• State tracking with InteractionStateManager

Animated GIF showing button press sequence: initial → pressed → released

---

🆕 New Examples (2024-11)

These examples address critical coverage gaps and demonstrate advanced features:

08. Bundled Fonts Showcase

08_bundled_fonts_demo.py - Demonstration of all bundled fonts

python 08_bundled_fonts_demo.py

Demonstrates:

• DejaVu Sans (Sans-serif)
• DejaVu Serif (Serif)
• DejaVu Sans Mono (Monospace)
• All font variants: Regular, Bold, Italic, Bold Italic

08. Pagination with PageBreak ✅

08_pagination_demo.py - Multi-page documents with explicit and automatic pagination

python 08_pagination_demo.py

Test Coverage: tests/examples/test_08_pagination_demo.py - 11 tests

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
• Combining pages into vertical strips

Coverage Impact: Fills critical gap - PageBreak layouter had NO examples before this!

09. Link Navigation (NEW) ✅

09_link_navigation_demo.py - All link types and interactive navigation

python 09_link_navigation_demo.py

Test Coverage: tests/examples/test_09_link_navigation_demo.py - 10 tests

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
• Mixed text and link paragraphs

Coverage Impact: Comprehensive - All 4 LinkType variations demonstrated!

10. Comprehensive Forms (NEW) ✅

10_forms_demo.py - All 14 form field types with validation

python 10_forms_demo.py

Test Coverage: tests/examples/test_10_forms_demo.py - 9 tests

Demonstrates all 14 FormFieldType variations:

Text-Based Fields:

• TEXT, EMAIL, PASSWORD, URL, TEXTAREA

Number/Date/Time Fields:

• NUMBER, DATE, TIME, RANGE, COLOR

Selection Fields:

• CHECKBOX, RADIO, SELECT, HIDDEN

Coverage Impact: Complete - All 14 field types across 4 practical form examples!

11. Table Text Wrapping (NEW) ✅

11_table_text_wrapping_demo.py - Automatic line wrapping in table cells

python 11_table_text_wrapping_demo.py

Simple Version: 11b_simple_table_wrapping.py - Quick demonstration

Demonstrates:

• Automatic line wrapping - Text wraps across multiple lines within cells
• Word hyphenation - Long words are intelligently hyphenated
• Narrow columns - Aggressive wrapping for tight spaces
• Mixed content - Both short and long text in the same table
• Technical documentation - API reference style tables
• News layouts - Article-style table content

Implementation: Uses the Line class from pyWebLayout.concrete.text with:

• Word-by-word fitting with intelligent spacing
• Pyphen-based dictionary hyphenation
• Brute-force splitting for edge cases
• Proper baseline alignment and metrics

---

Running the Examples

All examples can be run directly from the examples directory:

cd examples

# Getting Started (01-07)
python 01_simple_page_rendering.py    # Page layouts
python 02_text_and_layout.py          # Text alignment with justified text
python 03_page_layouts.py             # Various page sizes
python 04_table_rendering.py          # Table styles
python 05_html_table_with_images.py   # HTML tables with images
python 06_functional_elements_demo.py # Interactive buttons and forms
python 07_pressed_state_demo.py       # Button pressed states (generates GIF)

# Advanced Features (08-11)
python 08_bundled_fonts_demo.py       # Bundled font showcase
python 08_pagination_demo.py          # Multi-page documents
python 09_link_navigation_demo.py     # All link types
python 10_forms_demo.py               # All form field types
python 11_table_text_wrapping_demo.py # Table text wrapping
python 11b_simple_table_wrapping.py   # Simple wrapping demo

Output images are saved to the docs/images/ directory.

Recent Improvements

✅ Justified Text Fix (2024-11-10)

Lines using justified alignment now properly fill the entire width by:

• Calculating base spacing and remainder pixels
• Distributing remainder across word gaps to eliminate short lines
• Removing max_spacing constraint for true justification

Affected examples: 02, 11, 11b - All text now perfectly justified!

✅ Animated Button States (2024-11-10)

Example 07 now automatically generates an animated GIF showing button interactions:

• Initial state (1000ms)
• Pressed state (200ms)
• Released state (500ms)
• Loops continuously

Output: docs/images/example_07_button_animation.gif

Running Tests

All new examples (08, 09, 10) include comprehensive test coverage:

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

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

Total Test Coverage: 30 tests (11 + 10 + 9), all passing ✅

Additional Documentation

• README_HTML_MULTIPAGE.md - HTML multi-page rendering guide
• ../ARCHITECTURE.md - Detailed explanation of the Abstract/Concrete architecture
• ../docs/images/README.md - Visual documentation index with all examples
• ../pyWebLayout/layout/README_EREADER_API.md - EbookReader API reference

Debug/Development Scripts

Low-level debug and rendering scripts have been moved to the scripts/ directory.