222 lines
7.1 KiB
Markdown
222 lines
7.1 KiB
Markdown
# 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:**
|
|
```python
|
|
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:
|
|
|
|
```python
|
|
# 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
|
|
|
|
```python
|
|
# 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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
# 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.
|