Skip to content

feat: add text overflow detection to TextFrame#1114

Open
saggl wants to merge 4 commits intoscanny:masterfrom
saggl:feature/text-overflow-detection
Open

feat: add text overflow detection to TextFrame#1114
saggl wants to merge 4 commits intoscanny:masterfrom
saggl:feature/text-overflow-detection

Conversation

@saggl
Copy link

@saggl saggl commented Mar 21, 2026

Summary

Adds will_overflow() and overflow_info() methods to TextFrame for detecting text overflow before rendering. Supports vertical, horizontal, and combined detection.

API

# Simple check — does text overflow?
text_frame.will_overflow(font_size=18)  # -> bool

# Detailed metrics
info = text_frame.overflow_info(font_size=18)
info.overflow_percentage   # how much it overflows
info.fits_at_font_size     # font size that would fit

# Horizontal overflow (URLs, long words that break word-wrap)
text_frame.will_overflow(direction='horizontal', font_size=18)

# Check both directions at once
text_frame.will_overflow(direction='both', font_size=18)

will_overflow(direction, font_family, font_size, bold, italic, font_file) -> bool
overflow_info(...) -> OverflowInfo — returns dimensional metrics, overflow percentages, problematic elements, and suggested font sizes.

Default direction='vertical' preserves backward compatibility.

Changes

  • src/pptx/text/text.pyOverflowInfo frozen dataclass, will_overflow(), overflow_info() on TextFrame
  • src/pptx/text/layout.pyTextFitter methods: will_fit, will_fit_width, measure_text_height, measure_text_width, calculate_overflow_metrics, calculate_horizontal_overflow_metrics; empty-string guard in _rendered_size
  • tests/ — unit tests for all new methods and edge cases (vertical, horizontal, both, invalid direction, empty text, mixed fonts)
  • features/ — 12 BDD scenarios covering vertical, horizontal, and error paths
  • examples/ — usage examples for both overflow directions

Test plan

  • pytest tests/ -x — 2723 tests pass
  • behave features/txt-overflow-detection.feature — 12 scenarios pass
  • Backward compatible: default direction='vertical' unchanged

Christian Sagstetter and others added 4 commits March 21, 2026 10:21
Add new methods to detect and analyze text overflow before it occurs:

- TextFrame.will_overflow(): Simple boolean check for overflow
- TextFrame.overflow_info(): Detailed overflow metrics with OverflowInfo dataclass
- TextFitter.will_fit(): Core overflow detection logic
- TextFitter.measure_text_height(): Calculate required text height
- TextFitter.calculate_overflow_metrics(): Detailed overflow analysis

The OverflowInfo dataclass provides:
- will_overflow: Boolean indicator
- required_height/available_height: Size metrics
- overflow_height/overflow_percentage: Overflow amounts
- estimated_lines: Line count estimate
- fits_at_font_size: Recommended font size to fit

This enables proactive content validation to prevent text from being
cut off at the bottom of text frames, addressing the issue where users
don't know content will overflow until they open the presentation.

Includes comprehensive unit tests, feature tests, and examples.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Extends existing vertical overflow detection to support horizontal
overflow, providing comprehensive text overflow analysis in both
dimensions.

Key additions:
- TextFitter.will_fit_width() - Check if text fits horizontally
- TextFitter.measure_text_width() - Calculate max width and identify widest element
- TextFitter.calculate_horizontal_overflow_metrics() - Detailed horizontal metrics
- Added 'direction' parameter to TextFrame.will_overflow() and overflow_info()
  - Supports 'vertical' (default), 'horizontal', or 'both'
- Extended OverflowInfo dataclass with horizontal overflow fields
- Added comprehensive example and documentation

Features:
- Detects when individual words are too wide (word_wrap=True)
- Detects when entire lines are too wide (word_wrap=False)
- Backward compatible: default direction='vertical' maintains existing behavior
- Identifies specific problematic text elements
- Provides overflow percentages and font size suggestions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Performance improvements:
- Replace O(n) linear search with O(log n) binary search for horizontal best fit
- Add short-circuit evaluation in will_overflow() when direction='both'
- Reduce from 72 to ~7 iterations for large font sizes

Code quality improvements:
- Extract _calculate_overflow() helper to eliminate duplication
- Consolidate overflow percentage calculation logic
- Remove implementation documentation file

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Address issues identified in PR scanny#1114 review:
- Fix broken unit tests using positional args instead of keyword args
- Guard _rendered_size against empty strings (Pillow 10+ compat)
- Filter empty paragraphs in horizontal width methods
- Fix _calculate_overflow division by zero when available <= 0
- Make OverflowInfo frozen dataclass with Literal type for direction
- Fix dead conditional for widest_element, fix docstrings
- Add cross-platform font paths in examples
- Remove uv.lock and add to .gitignore
- Add unit tests for horizontal/both directions and invalid direction
- Add BDD scenarios for horizontal overflow detection

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant