feat: custom TimePicker hour formats

[ndonkoHenri]

Fix #5185

Example

from datetime import time

import flet as ft


def main(page: ft.Page):
    page.horizontal_alignment = ft.CrossAxisAlignment.CENTER

    def get_system_hour_format():
        """Returns the current system's hour format."""
        return "24h" if page.media.always_use_24_hour_format else "12h"

    def format_time(value: time) -> str:
        """Returns a formatted time string based on TimePicker and system settings."""
        use_24h = time_picker.hour_format == ft.TimePickerHourFormat.H24 or (
            time_picker.hour_format == ft.TimePickerHourFormat.SYSTEM
            and page.media.always_use_24_hour_format
        )
        return value.strftime("%H:%M" if use_24h else "%I:%M %p")

    def handle_change(e: ft.Event[ft.TimePicker]):
        selection.value = f"Selection: {format_time(time_picker.value)}"

    time_picker = ft.TimePicker(
        value=time(hour=9, minute=30),
        help_text="Choose your meeting time",
        on_change=handle_change,
    )

    def open_picker(e: ft.Event[ft.Button]):
        choice = format_dropdown.value
        hour_format_map = {
            "system": ft.TimePickerHourFormat.SYSTEM,
            "12h": ft.TimePickerHourFormat.H12,
            "24h": ft.TimePickerHourFormat.H24,
        }
        time_picker.hour_format = hour_format_map[choice]
        page.show_dialog(time_picker)

    page.add(
        ft.Row(
            alignment=ft.MainAxisAlignment.CENTER,
            controls=[
                format_dropdown := ft.Dropdown(
                    label="Hour format",
                    value="system",
                    width=260,
                    options=[
                        ft.DropdownOption(
                            key="system",
                            text=f"System default ({get_system_hour_format()})",
                        ),
                        ft.DropdownOption(key="12h", text="12-hour clock"),
                        ft.DropdownOption(key="24h", text="24-hour clock"),
                    ],
                ),
                ft.Button(
                    "Open TimePicker",
                    icon=ft.Icons.SCHEDULE,
                    on_click=open_picker,
                ),
            ],
        ),
        selection := ft.Text(weight=ft.FontWeight.BOLD),
    )


if __name__ == "__main__":
    ft.run(main)

Summary by Sourcery

Enable custom hour formatting in TimePicker by introducing a new hour_format option and propagating the platform's 24-hour preference, refactor entry_mode API, and update documentation and tests accordingly

New Features:

• Add TimePickerHourFormat enum and hour_format property to allow selecting system, 12h, or 24h display modes
• Expose always_use_24_hour_format in PageMediaData and apply it via MediaQuery to honor platform time format settings

Enhancements:

• Rename time_picker_entry_mode to entry_mode across Python and Dart implementations
• Wrap TimePicker dialog in MediaQuery for proper 24-hour format rendering
• Change show_dialog to raise RuntimeError when opening an already open dialog

Documentation:

• Document the new TimePickerHourFormat and add an hour formats example to the TimePicker docs

Tests:

• Add integration and screenshot tests covering basic, 12h, 24h, and system hour format behaviors

[sourcery-ai]

We've reviewed this pull request using the Sourcery rules engine

[cloudflare-workers-and-pages]

Deploying flet-docs with    Cloudflare Pages

Latest commit:	6662886
Status:	✅  Deploy successful!
Preview URL:	https://94551396.flet-docs.pages.dev
Branch Preview URL:	https://timepicker-time-format.flet-docs.pages.dev

View logs

[ndonkoHenri]

Two issues left:

• running basic.py example and changing the entry mode from the UI, I get an unexpected AttributeError: 'TimePickerEntryModeChangeEvent' object has no attribute 'entry_mode' - (ref)
• integration_tests/examples/material/test_time_picker.py::test_hour_formats fails with an unexpected RuntimeError: The finder "Found 2 widgets with text "12-hour clock", though we have only one on the UI. (ref)

[Copilot]

Pull Request Overview

This PR adds support for controlling the hour format (12-hour vs 24-hour) in the TimePicker control. The implementation introduces a new TimePickerHourFormat enum with three values: SYSTEM, H12, and H24, and adds a corresponding hour_format property to the TimePicker control.

Key changes:

• New TimePickerHourFormat enum with system/12h/24h options
• Updated TimePicker with hour_format property and improved documentation
• Added always_use_24_hour_format to PageMediaData for system-level hour format detection
• Enhanced documentation with examples demonstrating hour format usage

Reviewed Changes

Copilot reviewed 16 out of 22 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
sdk/python/packages/flet/src/flet/controls/theme.py	Fixed Markdown link syntax in docstrings for TextStyle references
sdk/python/packages/flet/src/flet/controls/material/time_picker.py	Added TimePickerHourFormat enum, updated TimePicker class with hour_format property and improved documentation
sdk/python/packages/flet/src/flet/controls/base_page.py	Added always_use_24_hour_format field to PageMediaData
sdk/python/packages/flet/src/flet/__init__.py	Exported new TimePickerHourFormat enum
sdk/python/packages/flet/mkdocs.yml	Added documentation page for TimePickerHourFormat
sdk/python/examples/controls/time_picker/basic.py	Updated example with improved code quality
sdk/python/examples/controls/time_picker/hour_formats.py	New example demonstrating hour format functionality
packages/flet/lib/src/controls/time_picker.dart	Dart implementation for hour format support using MediaQuery
packages/flet/lib/src/protocol/page_media_data.dart	Added alwaysUse24HourFormat field to protocol
packages/flet/lib/src/widgets/page_media.dart	Updated to read alwaysUse24HourFormat from MediaQuery
Integration test files	Added comprehensive tests for different hour formats

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The print statement appears to be a debugging artifact and should be removed before merging to production code.

Suggested change

print(e, e.entry_mode)

[Copilot]

The Markdown link syntax is malformed. It should be [TextStyle][flet.TextStyle] not [TextStyle][[flet.TextStyle] (note the double opening bracket).

[Copilot]

The Markdown link syntax is malformed. It should be [TextStyle][flet.TextStyle] not [TextStyle][[flet.TextStyle] (note the double opening bracket).

[Copilot]

The Markdown link syntax is malformed. It should be [TextStyle][flet.TextStyle] not [TextStyle][[flet.TextStyle] (note the double opening bracket).

Suggested change

	Used to configure the [`TextStyle`][[flet.TextStyle] for the hour/minute controls.
	Used to configure the [`TextStyle`][flet.TextStyle] for the hour/minute controls.