flet-charts 0.2.0.dev35__py3-none-any.whl → 0.70.0.dev6555__py3-none-any.whl

flet_charts/plotly_chart.py

@@ -1,19 +1,28 @@
 import re
 import xml.etree.ElementTree as ET
 from dataclasses import field
+from typing import Any, Optional
 
 import flet as ft
 
+_PLOTLY_IMPORT_ERROR: Optional[ImportError] = None
+
 try:
     from plotly.graph_objects import Figure
-except ImportError as e:
-    raise Exception(
-        'Install "plotly" Python package to use PlotlyChart control.'
-    ) from e
+except ImportError as e:  # pragma: no cover - depends on optional dependency
+    Figure = Any  # type: ignore[assignment]
+    _PLOTLY_IMPORT_ERROR = e
 
 __all__ = ["PlotlyChart"]
 
 
+def _require_plotly() -> None:
+    if _PLOTLY_IMPORT_ERROR is not None:
+        raise ModuleNotFoundError(
+            'Install "plotly" Python package to use PlotlyChart control.'
+        ) from _PLOTLY_IMPORT_ERROR
+
+
 @ft.control(kw_only=True)
 class PlotlyChart(ft.Container):
     """
@@ -28,8 +37,9 @@ class PlotlyChart(ft.Container):
 
     figure: Figure = field(metadata={"skip": True})
     """
-    Plotly figure to draw -
-    an instance of [`plotly.graph_objects.Figure`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html).
+    Plotly figure to draw.
+
+    The value is an instance of [`plotly.graph_objects.Figure`](https://plotly.com/python-api-reference/generated/plotly.graph_objects.Figure.html).
     """
 
     original_size: bool = False
@@ -40,6 +50,7 @@ class PlotlyChart(ft.Container):
     """
 
     def init(self):
+        _require_plotly()
         self.alignment = ft.Alignment.CENTER
         self.__img = ft.Image(fit=ft.BoxFit.FILL)
         self.content = self.__img

flet_charts/radar_chart.py

@@ -0,0 +1,214 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+import flet as ft
+from flet_charts.radar_data_set import RadarDataSet
+from flet_charts.types import ChartEventType
+
+__all__ = ["RadarChart", "RadarChartEvent", "RadarChartTitle", "RadarShape"]
+
+
+class RadarShape(Enum):
+    """Shape of the radar grid and data polygons."""
+
+    CIRCLE = "circle"
+    """Draws radial circles for the grid and data outlines."""
+
+    POLYGON = "polygon"
+    """Draws straight-edged polygons for the grid and data outlines."""
+
+
+@ft.control("RadarChartTitle")
+class RadarChartTitle(ft.BaseControl):
+    """
+    Custom title configuration displayed around a [`RadarChart`][(p).].
+    """
+
+    text: str = ""
+    """
+    The text displayed for the title.
+    """
+
+    angle: ft.Number = 0
+    """
+    Rotation angle (in degrees) applied to the title.
+    """
+
+    position_percentage_offset: Optional[ft.Number] = None
+    """
+    Defines the relative distance of this title from the chart center.
+
+    - `0` draws this title near the inside edge of each section.
+    - `1` draws this title near the outside edge of each section.
+
+    Must be between `0` and `1` (inclusive), if set.
+
+    Note:
+        If set, it takes precedence over the parent
+        [`RadarChart.title_position_percentage_offset`][(p).] value.
+    """
+
+    text_spans: Optional[list[ft.TextSpan]] = None
+    """
+    Inline spans appended to the title.
+    """
+
+
+@dataclass
+class RadarChartEvent(ft.Event["RadarChart"]):
+    """
+    Event raised for interactions with a [`RadarChart`][(p).].
+    """
+
+    type: ChartEventType
+    """
+    The touch or pointer event that occurred.
+    """
+
+    data_set_index: Optional[int] = None
+    """
+    The index of the touched data set, if any.
+    """
+
+    entry_index: Optional[int] = None
+    """
+    The index of the touched radar entry, if any.
+    """
+
+    entry_value: Optional[ft.Number] = None
+    """
+    The value of the touched radar entry, if any.
+    """
+
+
+@ft.control("RadarChart")
+class RadarChart(ft.LayoutControl):
+    """
+    A radar chart made of multiple datasets.
+    """
+
+    data_sets: list[RadarDataSet] = field(default_factory=list)
+    """
+    A list of [`RadarDataSet`][(p).] controls rendered on the chart.
+    """
+
+    titles: list[RadarChartTitle] = field(default_factory=list)
+    """
+    The titles shown around this chart, matching the number of entries per set.
+    """
+
+    title_text_style: Optional[ft.TextStyle] = None
+    """
+    The text style applied to titles around this chart.
+    """
+
+    title_position_percentage_offset: ft.Number = 0.2
+    """
+    Defines the relative distance of titles from the chart center.
+
+    - `0` draws titles near the inside edge of each section.
+    - `1` draws titles near the outside edge of each section.
+
+    Must be between `0` and `1` (inclusive).
+
+    Raises:
+        ValueError: If set to a value less than `0` or greater than `1`.
+    """
+
+    radar_bgcolor: ft.ColorValue = ft.Colors.TRANSPARENT
+    """
+    The background color of the radar area.
+    """
+
+    radar_border_side: ft.BorderSide = field(
+        default_factory=lambda: ft.BorderSide(width=2.0)
+    )
+    """
+    The outline drawn around the radar area.
+    """
+
+    radar_shape: RadarShape = RadarShape.POLYGON
+    """
+    The shape of the radar area.
+    """
+
+    border: Optional[ft.Border] = None
+    """
+    The border drawn around this chart.
+    """
+
+    center_min_value: bool = False
+    """
+    Whether minimum entry values should be positioned at the center of this chart.
+    """
+
+    tick_count: ft.Number = 1
+    """
+    Number of tick rings drawn from the centre to the edge.
+
+    Must be greater than or equal to `1`.
+
+    Raises:
+        ValueError: If set to a value less than `1`.
+    """
+
+    ticks_text_style: Optional[ft.TextStyle] = None
+    """
+    The text style used to draw tick labels.
+    """
+
+    tick_border_side: ft.BorderSide = field(
+        default_factory=lambda: ft.BorderSide(width=2.0)
+    )
+    """
+    The style of the tick rings.
+    """
+
+    grid_border_side: ft.BorderSide = field(
+        default_factory=lambda: ft.BorderSide(width=2.0)
+    )
+    """
+    The style of the radar grid lines.
+    """
+
+    animation: ft.AnimationValue = field(
+        default_factory=lambda: ft.Animation(
+            duration=ft.Duration(milliseconds=150), curve=ft.AnimationCurve.LINEAR
+        )
+    )
+    """
+    Controls the implicit animation applied when updating this chart.
+    """
+
+    interactive: bool = True
+    """
+    Enables touch interactions and event notifications.
+    """
+
+    long_press_duration: Optional[ft.DurationValue] = None
+    """
+    The duration before a long-press event fires.
+    """
+
+    touch_spot_threshold: ft.Number = 10
+    """
+    The radius (in logical pixels) used to detect nearby entries for touches.
+    """
+
+    on_event: Optional[ft.EventHandler[RadarChartEvent]] = None
+    """
+    Called when the chart is interacted with.
+    """
+
+    def init(self):
+        super().init()
+        entries_lengths = {len(ds.entries) for ds in self.data_sets}
+        if len(entries_lengths) > 1:
+            raise ValueError(
+                "All data sets in the data_sets list must have equal number of entries"
+            )
+        if not (0 <= self.title_position_percentage_offset <= 1):
+            raise ValueError("title_position_percentage_offset must be between 0 and 1")
+        if self.tick_count is not None and self.tick_count < 1:
+            raise ValueError("tick_count must be greater than or equal to 1")

flet_charts/radar_data_set.py

@@ -0,0 +1,66 @@
+from dataclasses import field
+from typing import Optional
+
+import flet as ft
+
+__all__ = ["RadarDataSet", "RadarDataSetEntry"]
+
+
+@ft.control("RadarDataSetEntry")
+class RadarDataSetEntry(ft.BaseControl):
+    """
+    A single data point rendered on a [`RadarChart`][(p).].
+    """
+
+    value: ft.Number
+    """
+    The numeric value drawn for this entry.
+    """
+
+
+@ft.control("RadarDataSet")
+class RadarDataSet(ft.BaseControl):
+    """
+    A collection of [`RadarDataSetEntry`][(p).] drawn as a filled radar shape.
+    """
+
+    entries: list[RadarDataSetEntry] = field(default_factory=list)
+    """
+    The data points that compose this set.
+    """
+
+    fill_color: ft.ColorValue = ft.Colors.CYAN
+    """
+    The color used to fill this dataset.
+    """
+
+    fill_gradient: Optional[ft.Gradient] = None
+    """
+    The gradient used to fill this dataset.
+
+    Takes precedence over [`fill_color`][..].
+    """
+
+    border_color: ft.ColorValue = ft.Colors.CYAN
+    """
+    The color of the dataset outline.
+    """
+
+    border_width: ft.Number = 2.0
+    """
+    The width of the dataset outline.
+    """
+
+    entry_radius: ft.Number = 5.0
+    """
+    The radius of each entry.
+    """
+
+    def init(self):
+        super().init()
+        entries_length = len(self.entries)
+        if entries_length != 0 and entries_length < 3:
+            raise ValueError(
+                f"entries can contain either 0 or at least 3 items, "
+                f"got {entries_length}"
+            )

flet_charts/scatter_chart.py

@@ -2,10 +2,9 @@ from dataclasses import dataclass, field
 from typing import Any, Optional
 
 import flet as ft
-
-from .chart_axis import ChartAxis
-from .scatter_chart_spot import ScatterChartSpot
-from .types import ChartEventType, ChartGridLines, ChartHorizontalAlignment
+from flet_charts.chart_axis import ChartAxis
+from flet_charts.scatter_chart_spot import ScatterChartSpot
+from flet_charts.types import ChartEventType, ChartGridLines, HorizontalAlignment
 
 __all__ = ["ScatterChart", "ScatterChartEvent", "ScatterChartTooltip"]
 
@@ -24,62 +23,104 @@ class ScatterChartTooltip:
     The tooltip's border radius.
     """
 
-    padding: Optional[ft.PaddingValue] = None
+    padding: ft.PaddingValue = field(
+        default_factory=lambda: ft.Padding.symmetric(vertical=8, horizontal=16)
+    )
     """
     Applies a padding for showing contents inside the tooltip.
     """
 
-    max_width: Optional[ft.Number] = None
+    max_width: ft.Number = 120
     """
     Restricts the tooltip's width.
     """
 
-    rotate_angle: Optional[ft.Number] = None
+    rotation: ft.Number = 0.0
     """
     The tooltip's rotation angle in degrees.
     """
 
-    horizontal_offset: Optional[ft.Number] = None
+    horizontal_offset: ft.Number = 0
     """
     Applies horizontal offset for showing tooltip.
     """
 
-    horizontal_alignment: Optional[ChartHorizontalAlignment] = None
+    horizontal_alignment: HorizontalAlignment = HorizontalAlignment.CENTER
     """
     The tooltip's horizontal alignment.
     """
 
-    border_side: Optional[ft.BorderSide] = None
+    border_side: ft.BorderSide = field(default_factory=lambda: ft.BorderSide.none())
     """
     The tooltip's border side.
     """
 
-    fit_inside_horizontally: Optional[bool] = None
+    fit_inside_horizontally: bool = False
     """
     Forces the tooltip to shift horizontally inside the chart, if overflow happens.
     """
 
-    fit_inside_vertically: Optional[bool] = None
+    fit_inside_vertically: bool = False
     """
     Forces the tooltip to shift vertically inside the chart, if overflow happens.
     """
 
+    def copy(
+        self,
+        *,
+        bgcolor: Optional[ft.ColorValue] = None,
+        border_radius: Optional[ft.BorderRadiusValue] = None,
+        padding: Optional[ft.PaddingValue] = None,
+        max_width: Optional[ft.Number] = None,
+        rotation: Optional[ft.Number] = None,
+        horizontal_offset: Optional[ft.Number] = None,
+        horizontal_alignment: Optional[HorizontalAlignment] = None,
+        border_side: Optional[ft.BorderSide] = None,
+        fit_inside_horizontally: Optional[bool] = None,
+        fit_inside_vertically: Optional[bool] = None,
+    ) -> "ScatterChartTooltip":
+        """
+        Returns a copy of this object with the specified properties overridden.
+        """
+        return ScatterChartTooltip(
+            bgcolor=bgcolor if bgcolor is not None else self.bgcolor,
+            border_radius=border_radius
+            if border_radius is not None
+            else self.border_radius,
+            padding=padding if padding is not None else self.padding,
+            max_width=max_width if max_width is not None else self.max_width,
+            rotation=rotation if rotation is not None else self.rotation,
+            horizontal_offset=horizontal_offset
+            if horizontal_offset is not None
+            else self.horizontal_offset,
+            horizontal_alignment=horizontal_alignment
+            if horizontal_alignment is not None
+            else self.horizontal_alignment,
+            border_side=border_side if border_side is not None else self.border_side,
+            fit_inside_horizontally=fit_inside_horizontally
+            if fit_inside_horizontally is not None
+            else self.fit_inside_horizontally,
+            fit_inside_vertically=fit_inside_vertically
+            if fit_inside_vertically is not None
+            else self.fit_inside_vertically,
+        )
+
 
 @dataclass
 class ScatterChartEvent(ft.Event["ScatterChart"]):
     type: ChartEventType
     """
-    Type of the event (e.g. tapDown, panUpdate)
+    The type of the event that occurred.
     """
 
     spot_index: Optional[int] = None
     """
-    Index of the touched spot, if any
+    The index of the touched spot, if any.
     """
 
 
 @ft.control("ScatterChart")
-class ScatterChart(ft.ConstrainedControl):
+class ScatterChart(ft.LayoutControl):
     """
     A scatter chart control.
 
@@ -99,9 +140,6 @@ class ScatterChart(ft.ConstrainedControl):
     )
     """
     Controls chart implicit animation.
-
-    Value is of [`AnimationValue`](https://flet.dev/docs/reference/types/animationvalue)
-    type.
     """
 
     interactive: bool = True
@@ -109,11 +147,6 @@ class ScatterChart(ft.ConstrainedControl):
     Enables automatic tooltips when hovering chart bars.
     """
 
-    handle_built_in_touches: bool = True
-    """
-    Whether to show a tooltip popup on top of the spots if a touch occurs.
-    """
-
     long_press_duration: Optional[ft.DurationValue] = None
     """
     The duration of a long press on the chart.
@@ -139,22 +172,22 @@ class ScatterChart(ft.ConstrainedControl):
     Controls drawing of chart's vertical lines.
     """
 
-    left_axis: ChartAxis = field(default_factory=lambda: ChartAxis())
+    left_axis: Optional[ChartAxis] = None
     """
     Configures the appearance of the left axis, its title and labels.
     """
 
-    top_axis: ChartAxis = field(default_factory=lambda: ChartAxis())
+    top_axis: Optional[ChartAxis] = None
     """
     Configures the appearance of the top axis, its title and labels.
     """
 
-    right_axis: ChartAxis = field(default_factory=lambda: ChartAxis())
+    right_axis: Optional[ChartAxis] = None
     """
     Configures the appearance of the right axis, its title and labels.
     """
 
-    bottom_axis: ChartAxis = field(default_factory=lambda: ChartAxis())
+    bottom_axis: Optional[ChartAxis] = None
     """
     Configures the appearance of the bottom axis, its title and labels.
     """
@@ -189,14 +222,27 @@ class ScatterChart(ft.ConstrainedControl):
     The maximum displayed value for Y axis.
     """
 
-    tooltip: Optional[ScatterChartTooltip] = None
+    tooltip: ScatterChartTooltip = field(default_factory=lambda: ScatterChartTooltip())
     """
     The tooltip configuration for the chart.
     """
 
+    show_tooltips_for_selected_spots_only: bool = False
+    """
+    Whether to permanently and only show the tooltips of spots with their
+    [`selected`][(p).ScatterChartSpot.selected] property set to `True`.
+    """
+
+    rotation_quarter_turns: ft.Number = 0
+    """
+    Number of quarter turns (90-degree increments) to rotate the chart.
+    Ex: `1` rotates the chart `90` degrees clockwise,
+    `2` rotates `180` degrees and `0` for no rotation.
+    """
+
     on_event: Optional[ft.EventHandler[ScatterChartEvent]] = None
     """
-    Fires when an event occurs on the chart.
+    Called when an event occurs on this chart.
     """
 
     def __post_init__(self, ref: Optional[ft.Ref[Any]]):

flet_charts/scatter_chart_spot.py

@@ -2,8 +2,7 @@ from dataclasses import dataclass, field
 from typing import Any, Optional, Union
 
 import flet as ft
-
-from .types import ChartDataPointTooltip, ChartPointShape
+from flet_charts.types import ChartDataPointTooltip, ChartPointShape
 
 __all__ = ["ScatterChartSpot", "ScatterChartSpotTooltip"]
 
@@ -21,6 +20,37 @@ class ScatterChartSpotTooltip(ChartDataPointTooltip):
     When `None`, defaults to [`ScatterChartSpot.y`][(p).].
     """
 
+    bottom_margin: ft.Number = 8
+    """
+    The bottom space from the spot.
+    """
+
+    def copy(
+        self,
+        *,
+        text: Optional[str] = None,
+        text_style: Optional[ft.TextStyle] = None,
+        text_align: Optional[ft.TextAlign] = None,
+        text_spans: Optional[list[ft.TextSpan]] = None,
+        rtl: Optional[bool] = None,
+        bottom_margin: Optional[float] = None,
+    ) -> "ScatterChartSpotTooltip":
+        """
+        Returns a copy of this object with the specified properties overridden.
+        """
+        return ScatterChartSpotTooltip(
+            text=text if text is not None else self.text,
+            text_style=text_style if text_style is not None else self.text_style,
+            text_align=text_align if text_align is not None else self.text_align,
+            text_spans=text_spans.copy()
+            if text_spans is not None
+            else (self.text_spans.copy() if self.text_spans is not None else None),
+            rtl=rtl if rtl is not None else self.rtl,
+            bottom_margin=bottom_margin
+            if bottom_margin is not None
+            else self.bottom_margin,
+        )
+
 
 @ft.control("ScatterChartSpot")
 class ScatterChartSpot(ft.BaseControl):
@@ -72,10 +102,10 @@ class ScatterChartSpot(ft.BaseControl):
 
     selected: bool = False
     """
-    TBD
+    Whether to treat this spot as selected.
     """
 
-    tooltip: ScatterChartSpotTooltip = field(
+    tooltip: Union[ScatterChartSpotTooltip, str] = field(
         default_factory=lambda: ScatterChartSpotTooltip()
     )
     """
@@ -87,12 +117,12 @@ class ScatterChartSpot(ft.BaseControl):
     Wether to show the tooltip.
     """
 
-    label_text: Optional[str] = None
+    label_text: str = ""
     """
     TBD
     """
 
-    label_style: Optional[ft.TextStyle] = None
+    label_text_style: ft.TextStyle = field(default_factory=lambda: ft.TextStyle())
     """
     TBD
     """
@@ -101,3 +131,11 @@ class ScatterChartSpot(ft.BaseControl):
     """
     TBD
     """
+
+    def before_update(self):
+        super().before_update()
+        self._internals["tooltip"] = (
+            ScatterChartSpotTooltip(text=self.tooltip)
+            if isinstance(self.tooltip, str)
+            else self.tooltip
+        )