v1: Charts and routing examples (#5764)

* Add declarative dashboard example with line charts

Introduces a new example for a dashboard using Flet and Flet Charts, displaying CPU, memory, and disk usage as animated line charts. Demonstrates component-based design and real-time data updates for chart visualization.

* Refactor routing-navigation examples for async routes

Updated routing-navigation example apps to use async route handling and push_route instead of go for navigation. Improved view management and event handling, and replaced flet.app with flet.run for app startup. Removed requirements.txt as dependencies are now managed elsewhere.

* Refactor route change handling in navigation examples

Moved and updated route_change and view_pop logic in routing-navigation examples for consistency and clarity. Improved example in Page control documentation to use ft.Button, update views, and clarify async usage.

* Add contributing guide to Python package docs

Added a reference to the main CONTRIBUTING.md file in the Python package documentation to provide contribution guidelines for developers.

Close #5769

* Add divider_color support to theme configuration

Introduces the divider_color property to the Theme class in Python and updates Dart theme parsing to use divider_color from the theme configuration. This allows customization of divider colors in UI components such as Divider, VerticalDivider, ListTile, and DataTable.

* Fix documentation links and animation curve reference

Corrected the example_media path in Switch control docs and updated references in ExpansionTile docstrings to use the correct link format and AnimationCurve.EASE_IN instead of Curves.EASE_IN.

* Improve type annotations and docstrings in hooks and controls

Updated docstrings in use_effect.py to clarify argument types and descriptions for hook functions. Improved type annotation for dataclass_kwargs in base_control.py to specify Any type for keyword arguments.

* Update badge property handling in pie chart section

Introduces 'skip_properties' for 'badge' in PieChartSection Python class and updates Dart code to use 'badge' instead of 'badge_content' for widget building. This improves consistency and property management between Python and Dart implementations.

* Update chart examples to use flet_charts as fch

Refactored imports in candlestick, pie, and scatter chart examples to consistently use 'flet_charts as fch' instead of 'ftc'. Updated all references to chart classes and constants accordingly. Also fixed a color constant typo in pie chart example.

* Update scrollable_control.py

Author: FeodorFitsner

packages/flet/lib/src/utils/theme.dart

@@ -136,7 +136,7 @@ ThemeData parseTheme(
     canvasColor: parseColor(value?["canvas_color"], theme),
     scaffoldBackgroundColor: parseColor(value?["scaffold_bgcolor"], theme),
     cardColor: parseColor(value?["card_bgcolor"], theme),
-    dividerColor: dividerTheme?.color,
+    dividerColor: parseColor(value?["divider_color"], theme),
     hintColor: parseColor(value?["hint_color"], theme),
     shadowColor: colorScheme?.shadow,
     secondaryHeaderColor: parseColor(value?["secondary_header_color"], theme),

sdk/python/examples/apps/routing-navigation/building-views-on-route-change.py

@@ -6,8 +6,14 @@ def main(page: ft.Page):
 
     print("Initial route:", page.route)
 
-    def route_change(e):
-        print("Route change:", e.route)
+    async def open_mail_settings(e):
+        await page.push_route("/settings/mail")
+
+    async def open_settings(e):
+        await page.push_route("/settings")
+
+    def route_change():
+        print("Route change:", page.route)
         page.views.clear()
         page.views.append(
             ft.View(
@@ -50,22 +56,17 @@ def route_change(e):
             )
         page.update()
 
-    def view_pop(e):
-        print("View pop:", e.view)
-        page.views.pop()
-        top_view = page.views[-1]
-        page.go(top_view.route)
+    async def view_pop(e):
+        if e.view is not None:
+            print("View pop:", e.view)
+            page.views.remove(e.view)
+            top_view = page.views[-1]
+            await page.push_route(top_view.route)
 
     page.on_route_change = route_change
     page.on_view_pop = view_pop
 
-    def open_mail_settings(e):
-        page.go("/settings/mail")
-
-    def open_settings(e):
-        page.go("/settings")
-
-    page.go(page.route)
+    route_change()
 
 
 ft.app(target=main, view=ft.AppView.WEB_BROWSER)

sdk/python/examples/apps/routing-navigation/home-store.py

@@ -1,45 +1,55 @@
+import asyncio
+
 import flet as ft
 
 
 def main(page: ft.Page):
     page.title = "Routes Example"
 
-    def route_change(e):
+    def route_change():
         page.views.clear()
         page.views.append(
             ft.View(
-                "/",
-                [
+                route="/",
+                controls=[
                     ft.AppBar(
                         title=ft.Text("Flet app"), bgcolor=ft.Colors.SURFACE_BRIGHT
                     ),
-                    ft.Button("Visit Store", on_click=lambda _: page.go("/store")),
+                    ft.Button(
+                        "Visit Store",
+                        on_click=lambda: asyncio.create_task(page.push_route("/store")),
+                    ),
                 ],
             )
         )
         if page.route == "/store":
             page.views.append(
                 ft.View(
-                    "/store",
-                    [
+                    route="/store",
+                    controls=[
                         ft.AppBar(
                             title=ft.Text("Store"), bgcolor=ft.Colors.SURFACE_BRIGHT
                         ),
-                        ft.Button("Go Home", on_click=lambda _: page.go("/")),
+                        ft.Button(
+                            "Go Home",
+                            on_click=lambda: asyncio.create_task(page.push_route("/")),
+                        ),
                     ],
                 )
             )
         page.update()
 
-    def view_pop(e):
-        page.views.pop()
-        top_view = page.views[-1]
-        page.go(top_view.route)
+    async def view_pop(e):
+        if e.view is not None:
+            print("View pop:", e.view)
+            page.views.remove(e.view)
+            top_view = page.views[-1]
+            await page.push_route(top_view.route)
 
     page.on_route_change = route_change
     page.on_view_pop = view_pop
 
-    page.go(page.route)
+    route_change()
 
 
 ft.run(main)

sdk/python/examples/apps/routing-navigation/initial-route.py

@@ -6,4 +6,4 @@ def main(page: Page):
     page.add(Text(f"Initial route: {page.route}"))
 
 
-flet.app(target=main, view=flet.AppView.WEB_BROWSER)
+flet.run(main)

sdk/python/examples/apps/routing-navigation/requirements.txt

@@ -12,4 +12,4 @@ def route_change(e):
     page.update()
 
 
-flet.app(target=main, view=flet.AppView.WEB_BROWSER)
+flet.run(main)

sdk/python/examples/apps/routing-navigation/route-change-event.py

@@ -1,5 +1,5 @@
 import flet as ft
-import flet_charts as ftc
+import flet_charts as fch
 
 CANDLE_DATA = [
     ("Mon", 24.8, 28.6, 23.9, 27.2),
@@ -12,19 +12,19 @@
 ]
 
 
-def build_spots() -> list[ftc.CandlestickChartSpot]:
+def build_spots() -> list[fch.CandlestickChartSpot]:
     """Create candlestick spots from the static data."""
-    spots: list[ftc.CandlestickChartSpot] = []
+    spots: list[fch.CandlestickChartSpot] = []
     for index, (label, open_, high, low, close) in enumerate(CANDLE_DATA):
         spots.append(
-            ftc.CandlestickChartSpot(
+            fch.CandlestickChartSpot(
                 x=float(index),
                 open=open_,
                 high=high,
                 low=low,
                 close=close,
                 selected=index == len(CANDLE_DATA) - 1,
-                tooltip=ftc.CandlestickChartSpotTooltip(
+                tooltip=fch.CandlestickChartSpotTooltip(
                     text=(
                         f"{label}\n"
                         f"Open: {open_:0.1f}\n"
@@ -52,7 +52,7 @@ def main(page: ft.Page):
     min_y = min(low for _, _, _, low, _ in CANDLE_DATA) - 1
     max_y = max(high for _, _, _, _, high in CANDLE_DATA) + 1
 
-    def handle_event(e: ftc.CandlestickChartEvent):
+    def handle_event(e: fch.CandlestickChartEvent):
         if e.spot_index is not None and e.spot_index >= 0:
             label, open_, high, low, close = CANDLE_DATA[e.spot_index]
             info.value = (
@@ -63,7 +63,7 @@ def handle_event(e: ftc.CandlestickChartEvent):
             info.value = f"{e.type.value} • outside candlesticks"
         info.update()
 
-    chart = ftc.CandlestickChart(
+    chart = fch.CandlestickChart(
         expand=True,
         min_x=min_x,
         max_x=max_x,
@@ -72,17 +72,17 @@ def handle_event(e: ftc.CandlestickChartEvent):
         baseline_x=0,
         baseline_y=min_y,
         bgcolor=ft.Colors.with_opacity(0.2, ft.Colors.BLUE_GREY_900),
-        horizontal_grid_lines=ftc.ChartGridLines(interval=2, dash_pattern=[2, 2]),
-        vertical_grid_lines=ftc.ChartGridLines(interval=1, dash_pattern=[2, 2]),
-        left_axis=ftc.ChartAxis(
+        horizontal_grid_lines=fch.ChartGridLines(interval=2, dash_pattern=[2, 2]),
+        vertical_grid_lines=fch.ChartGridLines(interval=1, dash_pattern=[2, 2]),
+        left_axis=fch.ChartAxis(
             label_spacing=2,
             label_size=60,
             title=ft.Text("Price (k USD)", color=ft.Colors.GREY_300),
             show_min=False,
         ),
-        bottom_axis=ftc.ChartAxis(
+        bottom_axis=fch.ChartAxis(
             labels=[
-                ftc.ChartAxisLabel(
+                fch.ChartAxisLabel(
                     value=index,
                     label=ft.Text(name, color=ft.Colors.GREY_300),
                 )
@@ -94,9 +94,9 @@ def handle_event(e: ftc.CandlestickChartEvent):
             show_max=False,
         ),
         spots=spots,
-        tooltip=ftc.CandlestickChartTooltip(
+        tooltip=fch.CandlestickChartTooltip(
             bgcolor=ft.Colors.BLUE_GREY_800,
-            horizontal_alignment=ftc.HorizontalAlignment.CENTER,
+            horizontal_alignment=fch.HorizontalAlignment.CENTER,
             fit_inside_horizontally=True,
         ),
         on_event=handle_event,

sdk/python/examples/controls/charts/candlestick_chart/example_1.py

@@ -0,0 +1,137 @@
+import asyncio
+import random
+from dataclasses import dataclass, field
+
+import flet as ft
+import flet_charts as ft_charts
+
+MAX_POINTS = 20
+
+
+@dataclass
+class DataPoint:
+    x: float
+    y: float
+
+
+@dataclass
+@ft.observable
+class ChartData:
+    x: float = 0.0
+    min_y: float = 0.0
+    max_y: float = 1.0
+    points: list[DataPoint] = field(default_factory=list)
+
+    def __post_init__(self):
+        for _ in range(MAX_POINTS):
+            self.add_point()
+
+    def add_point(self):
+        self.points.append(
+            DataPoint(x=self.x, y=random.uniform(self.min_y, self.max_y))
+        )
+        self.x += 0.5
+        if len(self.points) > MAX_POINTS:
+            self.points.pop(0)
+
+
+@ft.component
+def Gauge(
+    min_y: float = 0.0,
+    max_y: float = 1.0,
+    width: int = 200,
+    height: int = 150,
+    line_color=ft.Colors.BLUE,
+    bgcolor=ft.Colors.BLUE_100,
+):
+    chart_data, _ = ft.use_state(lambda: ChartData(min_y=min_y, max_y=max_y))
+
+    async def generate_chart_data():
+        for _ in range(0, 100):
+            chart_data.add_point()
+            await asyncio.sleep(1.0)
+
+    ft.on_mounted(generate_chart_data)
+
+    return ft_charts.LineChart(
+        data_series=[
+            ft_charts.LineChartData(
+                stroke_width=2,
+                color=line_color,
+                curved=True,
+                points=[
+                    ft_charts.LineChartDataPoint(
+                        key=point.x,
+                        x=point.x,
+                        y=point.y,
+                        selected_point=ft_charts.ChartCirclePoint(radius=4),
+                        selected_below_line=False,
+                        tooltip=f"{round(point.y, 2)}%",
+                    )
+                    for point in chart_data.points
+                ],
+                below_line_bgcolor=bgcolor,
+            )
+        ],
+        border=ft.Border.all(1, ft.Colors.GREY_400),
+        horizontal_grid_lines=ft_charts.ChartGridLines(
+            color=ft.Colors.GREY_300, width=1, dash_pattern=[3, 3], interval=0.1
+        ),
+        tooltip=ft_charts.LineChartTooltip(
+            bgcolor=ft.Colors.BLACK_12,
+            border_radius=4,
+            padding=ft.Padding(5),
+        ),
+        min_y=0,
+        max_y=1,
+        width=width,
+        height=height,
+        animation=ft.Animation(duration=0),
+    )
+
+
+@ft.component
+def App():
+    return ft.Row(
+        controls=[
+            ft.Column(
+                [
+                    ft.Text("CPU Usage"),
+                    Gauge(
+                        min_y=0.3,
+                        max_y=1.0,
+                        line_color=ft.Colors.BLUE,
+                        bgcolor=ft.Colors.BLUE_100,
+                    ),
+                ],
+                horizontal_alignment=ft.CrossAxisAlignment.CENTER,
+            ),
+            ft.Column(
+                [
+                    ft.Text("Memory Usage"),
+                    Gauge(
+                        min_y=0.2,
+                        max_y=0.5,
+                        line_color=ft.Colors.GREEN,
+                        bgcolor=ft.Colors.GREEN_100,
+                    ),
+                ],
+                horizontal_alignment=ft.CrossAxisAlignment.CENTER,
+            ),
+            ft.Column(
+                [
+                    ft.Text("Disk Usage"),
+                    Gauge(
+                        min_y=0.7,
+                        max_y=0.9,
+                        line_color=ft.Colors.ORANGE,
+                        bgcolor=ft.Colors.ORANGE_100,
+                    ),
+                ],
+                horizontal_alignment=ft.CrossAxisAlignment.CENTER,
+            ),
+        ]
+    )
+
+
+ft.run(lambda page: page.render(App))

sdk/python/examples/controls/charts/line_chart/dashboard_declarative.py

@@ -1,6 +1,5 @@
-import flet_charts as fch
-
 import flet as ft
+import flet_charts as fch
 
 NORMAL_RADIUS = 100
 HOVER_RADIUS = 110
@@ -11,7 +10,7 @@
     size=16,
     color=ft.Colors.WHITE,
     weight=ft.FontWeight.BOLD,
-    shadow=ft.BoxShadow(blur_radius=2, color=ft.Colors.BLACK54),
+    shadow=ft.BoxShadow(blur_radius=2, color=ft.Colors.BLACK_54),
 )
 NORMAL_BADGE_SIZE = 40
 HOVER_BADGE_SIZE = 50