pyWebLayout/examples/README_BROWSER_VIEWPORT.md

pyWebLayout Viewport System

The viewport system provides a movable window into large content areas, enabling efficient scrolling and memory usage for documents of any size. This complements your existing pagination system by allowing smooth scrolling within pages.

Key Components

1. Viewport Class (pyWebLayout.concrete.Viewport)

A viewport that provides a movable window into a larger content area.

Key Features:

• Only renders visible content (efficient memory usage)
• Supports smooth scrolling in all directions
• Provides hit testing for element interaction
• Caches content bounds for performance
• Auto-calculates content size or accepts explicit sizing

Basic Usage:

from pyWebLayout.concrete import Viewport, ScrollablePageContent

# Create viewport
viewport = Viewport(viewport_size=(800, 600))

# Add content
content = ScrollablePageContent(content_width=800)
content.add_child(some_renderable_element)
viewport.add_content(content)

# Scroll and render
viewport.scroll_to(0, 100)
image = viewport.render()

2. ScrollablePageContent Class

A specialized container designed to work with viewports for page content that can grow dynamically.

Features:

• Auto-adjusts height as content is added
• Optimized for vertical scrolling layouts
• Maintains proper content positioning

3. Enhanced HTML Browser

The new html_browser_with_viewport.py demonstrates the viewport system in action:

Enhanced Features:

• Mouse Wheel Scrolling: Smooth scrolling with configurable speed
• Keyboard Navigation: Page Up/Down, Home/End, Arrow keys
• Scrollbar Integration: Traditional scrollbar with viewport synchronization
• Text Selection: Works across viewport boundaries
• Memory Efficient: Only renders visible content

Integration with Existing System

The viewport system complements your existing pagination system:

1. Pages: Still handle content layout and organization
2. Viewport: Provides efficient viewing and scrolling within pages
3. Pagination: Can be used for chapter/section navigation
4. Viewport Scrolling: Handles smooth navigation within content

Scrolling Methods

The viewport supports multiple scrolling methods:

# Direct positioning
viewport.scroll_to(x, y)
viewport.scroll_by(dx, dy)

# Convenience methods
viewport.scroll_to_top()
viewport.scroll_to_bottom()
viewport.scroll_page_up()
viewport.scroll_page_down()
viewport.scroll_line_up(line_height)
viewport.scroll_line_down(line_height)

Performance Benefits

Memory Efficiency

• Only visible elements are rendered
• Large documents don't consume excessive memory
• Content bounds are cached for fast intersection testing

Rendering Efficiency

• Only renders what's visible in the viewport
• Supports partial element rendering (clipping)
• Fast hit testing for interaction

Scalability

• Handles documents of any size
• Performance doesn't degrade with content size
• Efficient scrolling regardless of document length

Browser Integration

The enhanced browser (html_browser_with_viewport.py) provides:

User Interface

• Scrollbar: Traditional scrollbar showing position and size
• Scroll Info: Real-time scroll progress display
• Multiple Input Methods: Mouse, keyboard, and scrollbar

Interaction

• Hit Testing: Click detection works within viewport
• Text Selection: Select and copy text across viewport boundaries
• Link Navigation: Clickable links work normally

Navigation

• Smooth Scrolling: Configurable scroll speed and behavior
• Page Navigation: Full page scrolling with configurable overlap
• Precision Control: Line-by-line scrolling for fine positioning

API Reference

Viewport Methods

# Scrolling
viewport.scroll_to(x, y)                    # Absolute positioning
viewport.scroll_by(dx, dy)                  # Relative movement
viewport.scroll_to_top()                    # Jump to top
viewport.scroll_to_bottom()                 # Jump to bottom
viewport.scroll_page_up()                   # Page up
viewport.scroll_page_down()                 # Page down
viewport.scroll_line_up(pixels)             # Line up
viewport.scroll_line_down(pixels)           # Line down

# Information
viewport.get_scroll_info()                  # Detailed scroll state
viewport.get_visible_elements()             # Currently visible elements
viewport.hit_test(point)                    # Find element at point

# Content Management
viewport.add_content(renderable)            # Add content
viewport.clear_content()                    # Remove all content
viewport.set_content_size(size)             # Set explicit size

Properties

viewport.viewport_size                      # (width, height) of viewport
viewport.content_size                       # (width, height) of content
viewport.viewport_offset                    # (x, y) scroll position
viewport.max_scroll_x                       # Maximum horizontal scroll
viewport.max_scroll_y                       # Maximum vertical scroll

Use Cases

1. Document Viewing

Perfect for viewing long documents, articles, or books where you need to scroll through content smoothly.

2. Web Page Rendering

Ideal for HTML rendering where pages can be very long but you only want to render the visible portion.

3. Large Data Visualization

Useful for rendering large datasets or complex layouts where only a portion is visible at any time.

4. Mobile-Style Interfaces

Enables smooth scrolling interfaces similar to mobile applications.

Example: Basic Viewport Usage

from pyWebLayout.concrete import Viewport, ScrollablePageContent, Text
from pyWebLayout.style.fonts import Font

# Create content
content = ScrollablePageContent(content_width=800)

# Add lots of text
font = Font(font_size=14)
for i in range(100):
    text = Text(f"This is line {i+1} of content", font)
    content.add_child(text)

# Create viewport
viewport = Viewport(viewport_size=(800, 600))
viewport.add_content(content)

# Scroll and render
viewport.scroll_to(0, 500)  # Scroll down 500 pixels
image = viewport.render()   # Only renders visible content

# Get scroll information
scroll_info = viewport.get_scroll_info()
print(f"Scroll progress: {scroll_info['scroll_progress_y']:.1%}")

Example: Browser Integration

# In your HTML browser
def handle_mouse_wheel(self, event):
    if event.delta > 0:
        self.viewport.scroll_line_up(20)
    else:
        self.viewport.scroll_line_down(20)
    self.update_display()

def handle_page_down(self, event):
    self.viewport.scroll_page_down()
    self.update_display()

def update_display(self):
    image = self.viewport.render()
    self.display_image(image)
    self.update_scrollbar()

Conclusion

The viewport system provides a powerful and efficient way to handle large content areas while maintaining smooth user interaction. It integrates seamlessly with your existing pyWebLayout architecture and provides the foundation for building sophisticated document viewers and web browsers.

The system is designed to be both easy to use for simple cases and powerful enough for complex applications, making it a valuable addition to the pyWebLayout toolkit.