flet-charts 0.2.0.dev13__py3-none-any.whl

flet_charts/line_chart.py

@@ -0,0 +1,251 @@
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import flet as ft
+
+from .chart_axis import ChartAxis
+from .line_chart_data import LineChartData
+from .types import ChartEventType, ChartGridLines
+
+__all__ = [
+    "LineChart",
+    "LineChartEvent",
+    "LineChartEventSpot",
+    "LineChartTooltip",
+]
+
+
+@dataclass
+class LineChartEventSpot:
+    bar_index: int
+    """
+    The line's index or `-1` if no line was hovered.
+    """
+
+    spot_index: int
+    """
+    The line's point index or `-1` if no point was hovered.
+    """
+
+
+@dataclass
+class LineChartEvent(ft.Event[ft.EventControlType]):
+    type: ChartEventType
+    """
+    The type of event that occured.
+    """
+
+    spots: list[LineChartEventSpot]
+    """
+    Spots on which the event occurred.
+    """
+
+
+@dataclass
+class LineChartTooltip:
+    """Configuration of the tooltip for [`LineChart`][(p).]s."""
+
+    bgcolor: ft.ColorValue = "#FF607D8B"
+    """
+    Background [color](https://flet.dev/docs/reference/colors) of tooltip.
+    """
+
+    border_radius: Optional[ft.BorderRadiusValue] = None
+    """
+    The tooltip's border radius.
+    """
+
+    margin: ft.Number = 16
+    """
+    Applies a bottom margin for showing tooltip on top of rods.
+    """
+
+    padding: ft.PaddingValue = field(
+        default_factory=lambda: ft.Padding.symmetric(vertical=8, horizontal=16)
+    )
+    """
+    Applies a padding for showing contents inside the tooltip.
+
+    Value is of type [`PaddingValue`](https://flet.dev/docs/reference/types/aliases#paddingvalue).
+    """
+
+    max_width: ft.Number = 120
+    """
+    Restricts the tooltip's width.
+    """
+
+    rotate_angle: ft.Number = 0.0
+    """
+    The tooltip's rotation angle in degrees.
+    """
+
+    horizontal_offset: ft.Number = 0.0
+    """
+    Applies horizontal offset for showing tooltip.
+    """
+
+    border_side: ft.BorderSide = field(default_factory=lambda: ft.BorderSide.none())
+    """
+    The tooltip's border side.
+    """
+
+    fit_inside_horizontally: bool = False
+    """
+    Forces the tooltip to shift horizontally inside the chart, if overflow happens.
+    """
+
+    fit_inside_vertically: bool = False
+    """
+    Forces the tooltip to shift vertically inside the chart, if overflow happens.
+    """
+
+    show_on_top_of_chart_box_area: bool = False
+    """
+    Whether to force the tooltip container to top of the line.
+    """
+
+
+@ft.control("LineChart")
+class LineChart(ft.ConstrainedControl):
+    """
+    Draws a line chart.
+
+    ![Overview](assets/line-chart/diagram.svg)
+    """
+
+    data_series: list[LineChartData] = field(default_factory=list)
+    """
+    A list of [`LineChartData`][(p).]
+    controls drawn as separate lines on a chart.
+    """
+
+    animation: ft.AnimationValue = field(
+        default_factory=lambda: ft.Animation(
+            duration=ft.Duration(milliseconds=150), curve=ft.AnimationCurve.LINEAR
+        )
+    )
+    """
+    Controls chart implicit animation.
+
+    Value is of type [`AnimationValue`](https://flet.dev/docs/reference/types/animationvalue).
+    """
+
+    interactive: bool = True
+    """
+    Enables automatic tooltips and points highlighting when hovering over the chart.
+    """
+
+    point_line_start: Optional[ft.Number] = None
+    """
+    The start of the vertical line drawn under the selected point.
+
+    Defaults to chart's bottom edge.
+    """
+
+    point_line_end: Optional[ft.Number] = None
+    """
+    The end of the vertical line drawn at selected point position.
+
+    Defaults to data point's `y` value.
+    """
+
+    bgcolor: Optional[ft.ColorValue] = None
+    """
+    Background [color](https://flet.dev/docs/reference/colors) of the chart.
+    """
+
+    border: Optional[ft.Border] = None
+    """
+    The border around the chart.
+
+    Value is of type [`Border`](https://flet.dev/docs/reference/types/border).
+    """
+
+    horizontal_grid_lines: Optional[ChartGridLines] = None
+    """
+    Controls drawing of chart's horizontal lines.
+
+    Value is of type [`ChartGridLines`][(p).].
+    """
+
+    vertical_grid_lines: Optional[ChartGridLines] = None
+    """
+    Controls drawing of chart's vertical lines.
+
+    Value is of type [`ChartGridLines`][(p).].
+    """
+
+    left_axis: ChartAxis = field(default_factory=lambda: ChartAxis(label_size=44))
+    """
+    Defines the appearance of the left axis, its title and labels.
+
+    Value is of type [`ChartAxis`][(p).].
+    """
+
+    top_axis: ChartAxis = field(default_factory=lambda: ChartAxis(label_size=30))
+    """
+    Defines the appearance of the top axis, its title and labels.
+
+    Value is of type [`ChartAxis`][(p).].
+    """
+
+    right_axis: ChartAxis = field(default_factory=lambda: ChartAxis(label_size=44))
+    """
+    Defines the appearance of the right axis, its title and labels.
+
+    Value is of type [`ChartAxis`][(p).].
+    """
+
+    bottom_axis: ChartAxis = field(default_factory=lambda: ChartAxis(label_size=30))
+    """
+    Defines the appearance of the bottom axis, its title and labels.
+
+    Value is of type [`ChartAxis`][(p).].
+    """
+
+    baseline_x: Optional[ft.Number] = None
+    """
+    Baseline value for X axis.
+    """
+
+    min_x: Optional[ft.Number] = None
+    """
+    Defines the minimum displayed value for X axis.
+    """
+
+    max_x: Optional[ft.Number] = None
+    """
+    Defines the maximum displayed value for X axis.
+    """
+
+    baseline_y: Optional[ft.Number] = None
+    """
+    Baseline value for Y axis.
+    """
+
+    min_y: Optional[ft.Number] = None
+    """
+    Defines the minimum displayed value for Y axis.
+    """
+
+    max_y: Optional[ft.Number] = None
+    """
+    Defines the maximum displayed value for Y axis.
+    """
+
+    tooltip: LineChartTooltip = field(default_factory=lambda: LineChartTooltip())
+    """
+    The tooltip configuration for this chart.
+    """
+
+    on_event: ft.OptionalEventHandler[LineChartEvent["LineChart"]] = None
+    """
+    Fires when a chart line is hovered or clicked.
+
+    Value is of type [`LineChartEvent`][(p).].
+    """
+
+    def __post_init__(self, ref: Optional[ft.Ref[Any]]):
+        super().__post_init__(ref)
+        self._internals["skip_properties"] = ["tooltip"]
+        self._internals["skip_inherited_notifier"] = True

flet_charts/line_chart_data.py

@@ -0,0 +1,140 @@
+from dataclasses import field
+from typing import Optional, Union
+
+import flet as ft
+
+from .line_chart_data_point import LineChartDataPoint
+from .types import ChartPointLine, ChartPointShape
+
+__all__ = ["LineChartData"]
+
+
+@ft.control("LineChartData")
+class LineChartData(ft.BaseControl):
+    points: list[LineChartDataPoint] = field(default_factory=list)
+    """
+    A list of points (dots) of [`LineChartDataPoint`][(p).]
+    type representing a single chart line.
+    """
+
+    curved: bool = False
+    """
+    Set to `True` to draw chart line as a curve.
+    """
+
+    color: ft.ColorValue = ft.Colors.CYAN
+    """
+    A [color](https://flet.dev/docs/reference/colors) of chart line.
+    """
+
+    gradient: Optional[ft.Gradient] = None
+    """
+    Gradient to draw line's background.
+
+    Value is of type [`Gradient`](https://flet.dev/docs/reference/types/gradient).
+    """
+
+    stroke_width: ft.Number = 2.0
+    """
+    The width of a chart line.
+    """
+
+    rounded_stroke_cap: bool = False
+    """
+    Whether to draw rounded line caps.
+    """
+
+    prevent_curve_over_shooting: bool = False
+    """
+    Whether to prevent overshooting when draw curve line on linear sequence spots.
+    """
+
+    prevent_curve_over_shooting_threshold: ft.Number = 10.0
+    """
+    Threshold to prevent overshooting algorithm.
+    """
+
+    dash_pattern: Optional[list[int]] = None
+    """
+    Defines dash effect of the line. The value is a circular list of dash offsets
+    and lengths. For example, the list `[5, 10]` would result in dashes 5 pixels
+    long followed by blank spaces 10 pixels long. By default, a solid line is
+    drawn.
+    """
+
+    shadow: ft.BoxShadow = field(default_factory=lambda: ft.BoxShadow(color=ft.Colors.TRANSPARENT))
+    """
+    Shadow to drop by a chart line.
+
+    Value is of type [`BoxShadow`](https://flet.dev/docs/reference/types/boxshadow).
+    """
+
+    above_line_bgcolor: Optional[ft.ColorValue] = None
+    """
+    Fill the area above chart line with the specified
+    [color](https://flet.dev/docs/reference/colors).
+    """
+
+    above_line_gradient: Optional[ft.Gradient] = None
+    """
+    Fill the area above chart line with the specified gradient.
+    """
+
+    above_line_cutoff_y: Optional[ft.Number] = None
+    """
+    Cut off filled area above line chart at specific Y value.
+    """
+
+    above_line: Optional[ChartPointLine] = None
+    """
+    A vertical line drawn between a line point and the top edge of the chart.
+
+    Value is of type [`ChartPointLine`][(p).].
+    """
+
+    below_line_bgcolor: Optional[ft.ColorValue] = None
+    """
+    Fill the area below chart line with the specified
+    [color](https://flet.dev/docs/reference/colors).
+    """
+
+    below_line_gradient: Optional[ft.Gradient] = None
+    """
+    Fill the area below chart line with the specified gradient.
+    """
+
+    below_line_cutoff_y: Optional[ft.Number] = None
+    """
+    Cut off filled area below line chart at specific Y value.
+    """
+
+    below_line: Optional[ChartPointLine] = None
+    """
+    A vertical line drawn between a line point and the bottom edge of the chart.
+
+    Value is of type [`ChartPointLine`][(p).].
+    """
+
+    selected_below_line: Union[None, bool, ChartPointLine] = None
+    """
+    A vertical line drawn between selected line point and the bottom adge of the
+    chart. The value is either `True` - draw a line with default style, `False` - do
+    not draw a line under selected point, or an instance of
+    [`ChartPointLine`][(p).] class to
+    specify line style to draw.
+    """
+
+    point: Union[None, bool, ChartPointShape] = None
+    """
+    Defines the appearance and shape of a line point (dot).
+
+    Value is of type bool (`True` - draw a point with default style or `False` - do
+    not draw a line point) or of type [`ChartPointShape`][(p).].
+    """
+
+    selected_point: Union[None, bool, ChartPointShape] = None
+    """
+    Defines the appearance and shape of a selected line point.
+
+    Value is of type [`ChartPointShape`][(p).].
+    """

flet_charts/line_chart_data_point.py

@@ -0,0 +1,85 @@
+from dataclasses import dataclass, field
+from typing import Any, Optional, Union
+
+import flet as ft
+
+from .types import ChartDataPointTooltip, ChartPointLine, ChartPointShape
+
+__all__ = ["LineChartDataPoint", "LineChartDataPointTooltip"]
+
+
+@dataclass
+class LineChartDataPointTooltip(ChartDataPointTooltip):
+    """Tooltip configuration for the [`LineChartDataPoint`][(p).]."""
+
+    text: Optional[str] = None
+    """
+    The text to display in the tooltip.
+
+    When `None`, defaults to [`LineChartDataPoint.y`][(p).].
+    """
+
+
+@ft.control("LineChartDataPoint")
+class LineChartDataPoint(ft.BaseControl):
+    """A [`LineChartData`][(p).] point."""
+
+    x: ft.Number
+    """
+    The position of a point on `X` axis.
+    """
+
+    y: ft.Number
+    """
+    The position of a point on `Y` axis.
+    """
+
+    selected: bool = False
+    """
+    Draw the point as selected when [`LineChart.interactive`][(p).] 
+    is set to `False`.
+    """
+
+    point: Union[None, bool, ChartPointShape] = None
+    """
+    Defines the appearance and shape of a line point.
+
+    Value is of type [`ChartPointShape`][(p).].
+    """
+
+    selected_point: Union[None, bool, ChartPointShape] = None
+    """
+    Defines the appearance and shape of a selected line point.
+
+    Value is of type [`ChartPointShape`][(p).].
+    """
+
+    show_above_line: bool = True
+    """
+    Whether to display a line above data point.
+    """
+
+    show_below_line: bool = True
+    """
+    Whether to display a line below data point.
+    """
+
+    selected_below_line: Union[None, bool, ChartPointLine] = None
+    """
+    A vertical line drawn between selected line point and the bottom adge of the chart.
+
+    The value is either `True` - draw a line with default style, `False` - do not draw a
+    line under selected point, or an instance of [`ChartPointLine`][(p).] class to
+    specify line style to draw.
+    """
+
+    tooltip: LineChartDataPointTooltip = field(default_factory=lambda: LineChartDataPointTooltip())
+    """
+    Configuration of the tooltip for this data point.
+    """
+
+    show_tooltip: bool = True
+    """
+    Whether the [`tooltip`][..] should be shown when this data point is hovered over.
+    """
+

flet_charts/matplotlib_chart.py

@@ -0,0 +1,64 @@
+import io
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import field
+
+import flet as ft
+
+try:
+    from matplotlib.figure import Figure
+except ImportError as e:
+    raise Exception(
+        'Install "matplotlib" Python package to use MatplotlibChart control.'
+    ) from e
+
+__all__ = ["MatplotlibChart"]
+
+
+@ft.control(kw_only=True)
+class MatplotlibChart(ft.Container):
+    """
+    Displays a [Matplotlib](https://matplotlib.org/) chart.
+
+    Warning:
+        This control requires the [`matplotlib`](https://matplotlib.org/) Python package to be installed.
+
+        See this [installation guide](index.md#installation) for more information.
+    """
+
+    figure: Figure = field(metadata={"skip": True})
+    """
+    Matplotlib figure to draw - an instance of 
+    [`matplotlib.figure.Figure`](https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html#matplotlib.figure.Figure).
+    """
+
+    original_size: bool = False
+    """
+    Whether to display chart in original size.
+
+    Set to `False` to display a chart that fits configured bounds.
+    """
+
+    transparent: bool = False
+    """
+    Whether to remove the background from the chart.
+    """
+
+    def init(self):
+        self.alignment = ft.Alignment.center()
+        self.__img = ft.Image(fit=ft.BoxFit.FILL)
+        self.content = self.__img
+
+    def before_update(self):
+        super().before_update()
+        if self.figure is not None:
+            s = io.StringIO()
+            self.figure.savefig(s, format="svg", transparent=self.transparent)
+            svg = s.getvalue()
+
+            if not self.original_size:
+                root = ET.fromstring(svg)
+                w = float(re.findall(r"\d+", root.attrib["width"])[0])
+                h = float(re.findall(r"\d+", root.attrib["height"])[0])
+                self.__img.aspect_ratio = w / h
+            self.__img.src = svg

flet_charts/pie_chart.py

@@ -0,0 +1,89 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+import flet as ft
+
+from .pie_chart_section import PieChartSection
+from .types import ChartEventType
+
+__all__ = ["PieChart", "PieChartEvent"]
+
+
+@dataclass
+class PieChartEvent(ft.Event[ft.EventControlType]):
+    type: ChartEventType
+    """
+    Type of the event.
+
+    Value is of type [`ChartEventType`][(p).].
+    """
+
+    section_index: Optional[int] = None
+    """
+    Section's index or `-1` if no section was hovered.
+    """
+
+    local_x: Optional[float] = None
+    """
+    X coordinate of the local position where the event occurred.
+    """
+
+    local_y: Optional[float] = None
+    """
+    Y coordinate of the local position where the event occurred.
+    """
+
+
+@ft.control("PieChart")
+class PieChart(ft.ConstrainedControl):
+    """
+    A pie chart control displaying multiple sections as slices of a circle.
+
+    ![Overview](assets/pie-chart/diagram.svg)
+    """
+
+    sections: list[PieChartSection] = field(default_factory=list)
+    """
+    A list of [`PieChartSection`][(p).]
+    controls drawn in a circle.
+    """
+
+    center_space_color: Optional[ft.ColorValue] = None
+    """
+    Free space [color](https://flet.dev/docs/reference/colors) in the middle of a chart.
+    """
+
+    center_space_radius: Optional[ft.Number] = None
+    """
+    Free space radius in the middle of a chart.
+    """
+
+    sections_space: Optional[ft.Number] = None
+    """
+    A gap between `sections`.
+    """
+
+    start_degree_offset: Optional[ft.Number] = None
+    """
+    By default, `sections` are drawn from zero degree (right side of the circle)
+    clockwise. You can change the starting point by setting `start_degree_offset`
+    (in degrees).
+    """
+
+    animation: ft.AnimationValue = field(
+        default_factory=lambda: ft.Animation(
+            duration=ft.Duration(milliseconds=150), curve=ft.AnimationCurve.LINEAR
+        )
+    )
+    """
+    Controls chart implicit animation.
+
+    Value is of type [`AnimationValue`](https://flet.dev/docs/reference/types/animationvalue).
+    """
+
+    on_event: ft.OptionalEventHandler[PieChartEvent["PieChart"]] = None
+    """
+    Fires when a chart section is hovered or clicked.
+
+    Event data is an instance [`PieChartEvent`][(p).].
+    """