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

```bash
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

![Page Rendering Example](../docs/images/example_01_page_rendering.png)

### 02. Text and Layout
**`02_text_and_layout.py`** - HTML parsing and text rendering

```bash
python 02_text_and_layout.py
```

Demonstrates:
- Parsing HTML content
- Text alignment options
- Font sizes and styles
- Document structure

![Text and Layout Example](../docs/images/example_02_text_and_layout.png)

### 03. Page Layouts
**`03_page_layouts.py`** - Different page configurations

```bash
python 03_page_layouts.py
```

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

![Page Layouts Example](../docs/images/example_03_page_layouts.png)

### 04. Table Rendering
**`04_table_rendering.py`** - HTML table rendering with styling

```bash
python 04_table_rendering.py
```

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

![Table Rendering Example](../docs/images/example_04_table_rendering.png)

### 05. Tables with Images
**`05_html_table_with_images.py`** - Tables containing images and mixed content

```bash
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

![Table with Images Example](../docs/images/example_05_html_table_with_images.png)

### 06. Functional Elements (Interactive)
**`06_functional_elements_demo.py`** - Interactive buttons and forms with callbacks

```bash
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

![Functional Elements Example](../docs/images/example_06_functional_elements.png)

### 07. Button Pressed States (Interactive)
**`07_pressed_state_demo.py`** - Visual feedback for button interactions

```bash
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`

![Button Pressed State Animation](../docs/images/example_07_button_animation.gif)

*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

```bash
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

![Bundled Fonts Example](../docs/images/demo_08_bundled_fonts.png)

### 08. Pagination with PageBreak ✅
**`08_pagination_demo.py`** - Multi-page documents with explicit and automatic pagination

```bash
python 08_pagination_demo.py
```

**Test Coverage:** [tests/examples/test_08_pagination_demo.py](../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!

![Pagination Example](../docs/images/example_08_pagination_explicit.png)

### 09. Link Navigation (NEW) ✅
**`09_link_navigation_demo.py`** - All link types and interactive navigation

```bash
python 09_link_navigation_demo.py
```

**Test Coverage:** [tests/examples/test_09_link_navigation_demo.py](../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!

![Link Navigation Example](../docs/images/example_09_link_navigation.png)

### 10. Comprehensive Forms (NEW) ✅
**`10_forms_demo.py`** - All 14 form field types with validation

```bash
python 10_forms_demo.py
```

**Test Coverage:** [tests/examples/test_10_forms_demo.py](../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!

![Comprehensive Forms Example](../docs/images/example_10_forms.png)

### 11. Table Text Wrapping (NEW) ✅
**`11_table_text_wrapping_demo.py`** - Automatic line wrapping in table cells

```bash
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

![Table Text Wrapping Example](../docs/images/example_11_table_text_wrapping.png)

---

## Running the Examples

All examples can be run directly from the examples directory:

```bash
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:

```bash
# 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.