Layout Metrics

Source: ui/layout_metrics.py

Responsive measurements, cached metric access, platform checks, and field sizing helpers used throughout the UI. See the Layout guide.

Compute and cache responsive dimensions for route body controls.

LayoutMetrics dataclass

Snapshot of dimensions used by responsive route layouts.

Attributes:

Name	Type	Description
viewport_width	float	Current page or window width in logical pixels.
viewport_height	float	Current page or window height in logical pixels.
body_width	float	Width allocated to general shell content.
form_width	float	Width allocated to deep forms.
settings_width	float	Width allocated to settings content.
content_height	float	Viewport height remaining after visible chrome and configured padding are subtracted.
breakpoint	str	Responsive category: "compact", "normal", or "wide".
platform	PagePlatform | None	Current Flet page platform when known.

Source code in src/learning_app/ui/layout_metrics.py

@dataclass(frozen=True)
class LayoutMetrics:
    """Snapshot of dimensions used by responsive route layouts.

    Attributes:
        viewport_width: Current page or window width in logical pixels.
        viewport_height: Current page or window height in logical pixels.
        body_width: Width allocated to general shell content.
        form_width: Width allocated to deep forms.
        settings_width: Width allocated to settings content.
        content_height: Viewport height remaining after visible chrome and
            configured padding are subtracted.
        breakpoint: Responsive category: ``"compact"``, ``"normal"``, or
            ``"wide"``.
        platform: Current Flet page platform when known.
    """

    viewport_width: float
    viewport_height: float
    body_width: float
    form_width: float
    settings_width: float
    content_height: float
    breakpoint: str
    platform: ft.PagePlatform | None = None

LayoutMetricsStore

Process-wide cache of the most recently computed layout metrics.

Source code in src/learning_app/ui/layout_metrics.py

class LayoutMetricsStore:
    """Process-wide cache of the most recently computed layout metrics."""

    _current: LayoutMetrics | None = None

    @classmethod
    def refresh(cls, page: ft.Page) -> LayoutMetrics:
        """Recompute and cache metrics for a page.

        Args:
            page: Page whose current layout state should be measured.

        Returns:
            The newly computed metrics.
        """
        cls._current = compute_layout_metrics(page)
        return cls._current

    @classmethod
    def get(cls) -> LayoutMetrics:
        """Return cached metrics or a default pre-layout snapshot.

        Returns:
            The latest metrics, or token-based defaults before the first
            refresh.
        """
        if cls._current is None:
            return LayoutMetrics(
                viewport_width=DEFAULT_VIEWPORT_WIDTH,
                viewport_height=DEFAULT_VIEWPORT_HEIGHT,
                body_width=DEFAULT_VIEWPORT_WIDTH * BODY_WIDTH_RATIO,
                form_width=DEFAULT_VIEWPORT_WIDTH * FORM_WIDTH_RATIO,
                settings_width=DEFAULT_VIEWPORT_WIDTH * SETTINGS_WIDTH_RATIO,
                content_height=DEFAULT_VIEWPORT_HEIGHT,
                breakpoint="normal",
            )
        return cls._current

refresh classmethod

refresh(page: Page) -> LayoutMetrics

Recompute and cache metrics for a page.

Parameters:

Name	Type	Description	Default
page	Page	Page whose current layout state should be measured.	required

Returns:

Type	Description
LayoutMetrics	The newly computed metrics.

Source code in src/learning_app/ui/layout_metrics.py

@classmethod
def refresh(cls, page: ft.Page) -> LayoutMetrics:
    """Recompute and cache metrics for a page.

    Args:
        page: Page whose current layout state should be measured.

    Returns:
        The newly computed metrics.
    """
    cls._current = compute_layout_metrics(page)
    return cls._current

get classmethod

get() -> LayoutMetrics

Return cached metrics or a default pre-layout snapshot.

Returns:

Type	Description
LayoutMetrics	The latest metrics, or token-based defaults before the first
LayoutMetrics	refresh.

Source code in src/learning_app/ui/layout_metrics.py

@classmethod
def get(cls) -> LayoutMetrics:
    """Return cached metrics or a default pre-layout snapshot.

    Returns:
        The latest metrics, or token-based defaults before the first
        refresh.
    """
    if cls._current is None:
        return LayoutMetrics(
            viewport_width=DEFAULT_VIEWPORT_WIDTH,
            viewport_height=DEFAULT_VIEWPORT_HEIGHT,
            body_width=DEFAULT_VIEWPORT_WIDTH * BODY_WIDTH_RATIO,
            form_width=DEFAULT_VIEWPORT_WIDTH * FORM_WIDTH_RATIO,
            settings_width=DEFAULT_VIEWPORT_WIDTH * SETTINGS_WIDTH_RATIO,
            content_height=DEFAULT_VIEWPORT_HEIGHT,
            breakpoint="normal",
        )
    return cls._current

compute_layout_metrics

compute_layout_metrics(page: Page) -> LayoutMetrics

Calculate a responsive layout snapshot for a page.

Visible shared chrome, page padding, and active-view padding are subtracted from viewport height. Widths are ratio-based and capped by layout tokens.

Parameters:

Name	Type	Description	Default
page	Page	Page supplying viewport, platform, route, chrome, and padding state.	required

Returns:

Type	Description
LayoutMetrics	The calculated immutable layout metrics.

Source code in src/learning_app/ui/layout_metrics.py

def compute_layout_metrics(page: ft.Page) -> LayoutMetrics:
    """Calculate a responsive layout snapshot for a page.

    Visible shared chrome, page padding, and active-view padding are subtracted
    from viewport height. Widths are ratio-based and capped by layout tokens.

    Args:
        page: Page supplying viewport, platform, route, chrome, and padding
            state.

    Returns:
        The calculated immutable layout metrics.
    """
    viewport_width = _viewport_width(page)
    viewport_height = _viewport_height(page)
    content_height = max(viewport_height - _chrome_occupied_height(page), 0)

    return LayoutMetrics(
        viewport_width=viewport_width,
        viewport_height=viewport_height,
        body_width=_bounded_width(viewport_width, BODY_WIDTH_RATIO),
        form_width=_bounded_width(viewport_width, FORM_WIDTH_RATIO),
        settings_width=_bounded_width(viewport_width, SETTINGS_WIDTH_RATIO),
        content_height=content_height,
        breakpoint=_breakpoint(viewport_width),
        platform=page.platform,
    )

is_windows_platform

is_windows_platform(page: Page | None = None) -> bool

Return whether the explicit or cached platform is Windows.

Parameters:

Name	Type	Description	Default
page	Page | None	Optional page whose platform takes precedence over cached metrics.	None

Returns:

Type	Description
bool	True when the resolved platform is Windows.

Source code in src/learning_app/ui/layout_metrics.py

def is_windows_platform(page: ft.Page | None = None) -> bool:
    """Return whether the explicit or cached platform is Windows.

    Args:
        page: Optional page whose platform takes precedence over cached
            metrics.

    Returns:
        ``True`` when the resolved platform is Windows.
    """
    return _resolve_platform(page) == ft.PagePlatform.WINDOWS

is_android_platform

is_android_platform(page: Page | None = None) -> bool

Return whether the explicit or cached platform is Android.

Parameters:

Name	Type	Description	Default
page	Page | None	Optional page whose platform takes precedence over cached metrics.	None

Returns:

Type	Description
bool	True when the resolved platform is Android.

Source code in src/learning_app/ui/layout_metrics.py

def is_android_platform(page: ft.Page | None = None) -> bool:
    """Return whether the explicit or cached platform is Android.

    Args:
        page: Optional page whose platform takes precedence over cached
            metrics.

    Returns:
        ``True`` when the resolved platform is Android.
    """
    return _resolve_platform(page) == ft.PagePlatform.ANDROID

learn_words_field_width

learn_words_field_width(
    form_width: float, page: Page | None = None
) -> float

Calculate the words exercise field width for a platform.

Parameters:

Name	Type	Description	Default
form_width	float	Available form width in logical pixels.	required
page	Page | None	Optional page used to resolve the platform.	None

Returns:

Type	Description
float	The field width after applying the platform-specific ratio.

Source code in src/learning_app/ui/layout_metrics.py

def learn_words_field_width(form_width: float, page: ft.Page | None = None) -> float:
    """Calculate the words exercise field width for a platform.

    Args:
        form_width: Available form width in logical pixels.
        page: Optional page used to resolve the platform.

    Returns:
        The field width after applying the platform-specific ratio.
    """
    ratio = (
        LEARN_WORDS_FIELD_WIDTH_RATIO_WINDOWS
        if is_windows_platform(page)
        else LEARN_WORDS_FIELD_WIDTH_RATIO
    )
    return form_width * ratio

learn_definition_field_width

learn_definition_field_width(
    form_width: float, page: Page | None = None
) -> float

Calculate the definition exercise field width for a platform.

Parameters:

Name	Type	Description	Default
form_width	float	Available form width in logical pixels.	required
page	Page | None	Optional page used to resolve the platform.	None

Returns:

Type	Description
float	The field width after applying the platform-specific ratio.

Source code in src/learning_app/ui/layout_metrics.py

def learn_definition_field_width(form_width: float, page: ft.Page | None = None) -> float:
    """Calculate the definition exercise field width for a platform.

    Args:
        form_width: Available form width in logical pixels.
        page: Optional page used to resolve the platform.

    Returns:
        The field width after applying the platform-specific ratio.
    """
    ratio = (
        LEARN_DEFINITION_FIELD_WIDTH_RATIO_WINDOWS
        if is_windows_platform(page)
        else LEARN_DEFINITION_FIELD_WIDTH_RATIO
    )
    return form_width * ratio