flet-map 0.1.0.dev2__py3-none-any.whl → 0.2.0.dev45__py3-none-any.whl

flet_map/map_layer.py

@@ -1,26 +1,20 @@
-from typing import Any, Optional
+import flet as ft
 
-from flet.core.control import Control
-from flet.core.ref import Ref
+__all__ = ["MapLayer"]
 
 
-class MapLayer(Control):
+@ft.control("MapLayer")
+class MapLayer(ft.Control):
     """
     Abstract class for all map layers.
-    """
 
-    def __init__(
-        self,
-        #
-        # Control
-        #
-        ref: Optional[Ref] = None,
-        visible: Optional[bool] = None,
-        data: Any = None,
-    ):
-        Control.__init__(
-            self,
-            ref=ref,
-            visible=visible,
-            data=data,
-        )
+    The following layers are available:
+
+    - [`CircleLayer`][(p).]
+    - [`MarkerLayer`][(p).]
+    - [`PolygonLayer`][(p).]
+    - [`PolylineLayer`][(p).]
+    - [`RichAttribution`][(p).]
+    - [`SimpleAttribution`][(p).]
+    - [`TileLayer`][(p).]
+    """

flet_map/marker_layer.py

@@ -1,183 +1,97 @@
-from typing import Any, List, Optional
-
-from flet.core.alignment import Alignment
-from flet.core.control import Control, OptionalNumber
-from flet_map.map import MapLatitudeLongitude
-from flet_map.map_layer import MapLayer
-from flet.core.ref import Ref
-
-
-class Marker(Control):
-    """
-    A marker displayed on the Map at the specified location through the MarkerLayer.
-
-    -----
-
-    Online docs: https://flet.dev/docs/controls/mapmarker
-    """
-
-    def __init__(
-        self,
-        content: Control,
-        coordinates: MapLatitudeLongitude,
-        rotate: Optional[bool] = None,
-        height: OptionalNumber = None,
-        width: OptionalNumber = None,
-        alignment: Optional[Alignment] = None,
-        #
-        # Control
-        #
-        ref: Optional[Ref] = None,
-        visible: Optional[bool] = None,
-        data: Any = None,
-    ):
-        Control.__init__(
-            self,
-            ref=ref,
-            visible=visible,
-            data=data,
-        )
-
-        self.content = content
-        self.coordinates = coordinates
-        self.rotate = rotate
-        self.height = height
-        self.width = width
-        self.alignment = alignment
-
-    def _get_control_name(self):
-        return "map_marker"
-
-    def _get_children(self):
-        return [self.__content]
+from dataclasses import field
+from typing import List, Optional
 
-    def before_update(self):
-        super().before_update()
-        self._set_attr_json("alignment", self.__alignment)
-        self._set_attr_json("coordinates", self.__coordinates)
-
-    # content
-    @property
-    def content(self) -> Optional[Alignment]:
-        return self.__content
-
-    @content.setter
-    def content(self, value: Optional[Alignment]):
-        self.__content = value
-
-    # rotate
-    @property
-    def rotate(self) -> bool:
-        return self._get_attr("rotate", data_type="bool", def_value=False)
-
-    @rotate.setter
-    def rotate(self, value: Optional[bool]):
-        self._set_attr("rotate", value)
-
-    # height
-    @property
-    def height(self) -> float:
-        return self._get_attr("height", data_type="float", def_value=30.0)
-
-    @height.setter
-    def height(self, value: OptionalNumber):
-        assert value is None or value >= 0, "height cannot be negative"
-        self._set_attr("height", value)
-
-    # width
-    @property
-    def width(self) -> float:
-        return self._get_attr("width", data_type="float", def_value=30.0)
-
-    @width.setter
-    def width(self, value: OptionalNumber):
-        assert value is None or value >= 0, "width cannot be negative"
-        self._set_attr("width", value)
-
-    # alignment
-    @property
-    def alignment(self) -> Optional[Alignment]:
-        return self.__alignment
-
-    @alignment.setter
-    def alignment(self, value: Optional[Alignment]):
-        self.__alignment = value
-
-    # coordinates
-    @property
-    def coordinates(self) -> MapLatitudeLongitude:
-        return self.__coordinates
-
-    @coordinates.setter
-    def coordinates(self, value: MapLatitudeLongitude):
-        self.__coordinates = value
+import flet as ft
 
+from .map_layer import MapLayer
+from .types import MapLatitudeLongitude
 
-class MarkerLayer(MapLayer):
+__all__ = ["Marker", "MarkerLayer"]
+
+
+@ft.control("Marker")
+class Marker(ft.Control):
     """
-    A layer to display Markers.
+    A marker displayed on the Map at the specified location through the [`MarkerLayer`][(p).].
 
-    -----
+    Raises:
+        AssertionError: If the [`content`][(c).] is not visible, or if [`height`][(c).] or [`width`][(c).] are negative.
+    """
 
-    Online docs: https://flet.dev/docs/controls/mapmarkerlayer
+    content: ft.Control
+    """
+    The content to be displayed at [`coordinates`][..].
+    
+    Note:
+        Must be provided and visible.
     """
 
-    def __init__(
-        self,
-        markers: List[Marker],
-        alignment: Optional[Alignment] = None,
-        rotate: Optional[bool] = None,
-        #
-        # MapLayer
-        #
-        ref: Optional[Ref] = None,
-        visible: Optional[bool] = None,
-        data: Any = None,
-    ):
-        MapLayer.__init__(
-            self,
-            ref=ref,
-            visible=visible,
-            data=data,
-        )
+    coordinates: MapLatitudeLongitude
+    """
+    The coordinates of the marker.
+    
+    This will be the center of the marker, if `alignment=ft.Alignment.center()`.
+    """
+
+    rotate: Optional[bool] = None
+    """
+    Whether to counter rotate this marker to the map's rotation, to keep a fixed orientation.
+    So, when `True`, this marker will always appear upright and vertical from the user's perspective.
+    
+    Note: this is not used to apply a custom rotation in degrees to the marker.
+    
+    Defaults to the value of the parent [`MarkerLayer.rotate`][(p).].
+    """
 
-        self.markers = markers
-        self.alignment = alignment
-        self.rotate = rotate
+    height: ft.Number = 30.0
+    """
+    The height of the [`content`][..] Control.
+    
+    Note:
+        Must be non-negative.
+    """
 
-    def _get_control_name(self):
-        return "map_marker_layer"
+    width: ft.Number = 30.0
+    """
+    The width of the [`content`][..] Control.
+    
+    Note:
+        Must be non-negative.
+    """
 
-    def _get_children(self):
-        return self.__markers
+    alignment: Optional[ft.Alignment] = None
+    """
+    Alignment of the marker relative to the normal center at [`coordinates`][..].
+    
+    Defaults to the value of the parent [`MarkerLayer.alignment`][(m).].
+    """
 
     def before_update(self):
         super().before_update()
-        self._set_attr_json("alignment", self.__alignment)
-
-    # alignment
-    @property
-    def alignment(self) -> Optional[Alignment]:
-        return self.__alignment
-
-    @alignment.setter
-    def alignment(self, value: Optional[Alignment]):
-        self.__alignment = value
-
-    # markers
-    @property
-    def markers(self) -> List[Marker]:
-        return self.__markers
-
-    @markers.setter
-    def markers(self, value: List[Marker]):
-        self.__markers = value
-
-    # rotate
-    @property
-    def rotate(self) -> bool:
-        return self._get_attr("rotate", data_type="bool", def_value=False)
-
-    @rotate.setter
-    def rotate(self, value: Optional[bool]):
-        self._set_attr("rotate", value)
+        assert self.content.visible, "content must be visible"
+        assert self.height >= 0, "height must be greater than or equal to 0"
+        assert self.width >= 0, "width must be greater than or equal to 0"
+
+
+@ft.control("MarkerLayer")
+class MarkerLayer(MapLayer):
+    """
+    A layer to display Markers.
+    """
+
+    markers: List[Marker]
+    """
+    List of [`Marker`][(m).]s to display.
+    """
+
+    alignment: Optional[ft.Alignment] = field(
+        default_factory=lambda: ft.Alignment.center()
+    )
+    """
+    Alignment of each marker relative to its normal center at `Marker.coordinates`.
+    """
+
+    rotate: bool = False
+    """
+    Whether to counter-rotate `markers` to the map's rotation, to keep a fixed orientation.
+    """

flet_map/polygon_layer.py

@@ -1,262 +1,125 @@
-from typing import Any, List, Optional
+from typing import List, Optional
 
-from flet.core.control import Control, OptionalNumber
-from flet_map.map import MapLatitudeLongitude
-from flet_map.map_layer import MapLayer
-from flet.core.ref import Ref
-from flet.core.text_style import TextStyle
-from flet.core.types import ColorEnums, ColorValue, StrokeCap, StrokeJoin
+import flet as ft
 
+from .map_layer import MapLayer
+from .types import MapLatitudeLongitude
 
-class PolygonMarker(Control):
-    """
-    A marker for the PolygonLayer.
+__all__ = ["PolygonMarker", "PolygonLayer"]
 
-    -----
 
-    Online docs: https://flet.dev/docs/controls/mappolygonmarker
+@ft.control("PolygonMarker")
+class PolygonMarker(ft.Control):
+    """
+    A marker for the [`PolygonLayer`][(p).].
     """
 
-    def __init__(
-        self,
-        coordinates: List[MapLatitudeLongitude],
-        label: Optional[str] = None,
-        label_text_style: Optional[TextStyle] = None,
-        border_color: Optional[ColorValue] = None,
-        color: Optional[ColorValue] = None,
-        border_stroke_width: OptionalNumber = None,
-        disable_holes_border: Optional[bool] = None,
-        rotate_label: Optional[bool] = None,
-        stroke_cap: Optional[StrokeCap] = None,
-        stroke_join: Optional[StrokeJoin] = None,
-        #
-        # Control
-        #
-        ref: Optional[Ref] = None,
-        visible: Optional[bool] = None,
-        data: Any = None,
-    ):
-        Control.__init__(
-            self,
-            ref=ref,
-            visible=visible,
-            data=data,
-        )
-
-        self.coordinates = coordinates
-        self.label = label
-        self.label_text_style = label_text_style
-        self.border_color = border_color
-        self.color = color
-        self.border_stroke_width = border_stroke_width
-        self.disable_holes_border = disable_holes_border
-        self.rotate_label = rotate_label
-        self.stroke_cap = stroke_cap
-        self.stroke_join = stroke_join
-
-    def _get_control_name(self):
-        return "map_polygon_marker"
-
-    def before_update(self):
-        super().before_update()
-        self._set_attr_json("coordinates", self.__coordinates)
-        if isinstance(self.__label_text_style, TextStyle):
-            self._set_attr_json("labelTextStyle", self.__label_text_style)
-
-    # stroke_cap
-    @property
-    def stroke_cap(self) -> Optional[StrokeCap]:
-        return self.__stroke_cap
-
-    @stroke_cap.setter
-    def stroke_cap(self, value: Optional[StrokeCap]):
-        self.__stroke_cap = value
-        self._set_enum_attr("strokeCap", value, StrokeCap)
-
-    # stroke_join
-    @property
-    def stroke_join(self) -> Optional[StrokeJoin]:
-        return self.__stroke_join
-
-    @stroke_join.setter
-    def stroke_join(self, value: Optional[StrokeJoin]):
-        self.__stroke_join = value
-        self._set_enum_attr("strokeJoin", value, StrokeJoin)
-
-    # label_text_style
-    @property
-    def label_text_style(self) -> Optional[TextStyle]:
-        return self.__label_text_style
-
-    @label_text_style.setter
-    def label_text_style(self, value: Optional[TextStyle]):
-        self.__label_text_style = value
-
-    # rotate_label
-    @property
-    def rotate_label(self) -> bool:
-        return self._get_attr("rotateLabel", data_type="bool", def_value=False)
-
-    @rotate_label.setter
-    def rotate_label(self, value: Optional[bool]):
-        self._set_attr("rotateLabel", value)
-
-    # label
-    @property
-    def label(self) -> Optional[str]:
-        return self._get_attr("label")
+    coordinates: List[MapLatitudeLongitude]
+    """
+    The points for the outline of this polygon.
+    """
 
-    @label.setter
-    def label(self, value: Optional[str]):
-        self._set_attr("label", value)
+    label: Optional[str] = None
+    """
+    An optional label for this polygon.
 
-    # disable_holes_border
-    @property
-    def disable_holes_border(self) -> bool:
-        return self._get_attr("disableHolesBorder", data_type="bool", def_value=False)
+    Note: specifying a label will reduce performance, as the internal
+    canvas must be drawn to and 'saved' more frequently to ensure the proper
+    stacking order is maintained. This can be avoided, potentially at the
+    expense of appearance, by setting [`PolygonLayer.draw_labels_last`][(p).].
+    """
 
-    @disable_holes_border.setter
-    def disable_holes_border(self, value: Optional[bool]):
-        self._set_attr("disableHolesBorder", value)
+    label_text_style: Optional[ft.TextStyle] = None
+    """
+    The text style for the label.
+    """
 
-    # color
-    @property
-    def color(self) -> Optional[ColorValue]:
-        return self.__color
+    border_color: ft.ColorValue = ft.Colors.GREEN
+    """
+    The color of the border outline.
+    """
 
-    @color.setter
-    def color(self, value: Optional[ColorValue]):
-        self.__color = value
-        self._set_enum_attr("color", value, ColorEnums)
+    color: ft.ColorValue = ft.Colors.GREEN
+    """
+    The color of the polygon.
+    """
 
-    # border_color
-    @property
-    def border_color(self) -> Optional[ColorValue]:
-        return self.__border_color
+    border_stroke_width: ft.Number = 0.0
+    """
+    The width of the border outline.
+    
+    Note:
+        Must be non-negative.
+    """
 
-    @border_color.setter
-    def border_color(self, value: Optional[ColorValue]):
-        self.__border_color = value
-        self._set_enum_attr("borderColor", value, ColorEnums)
+    disable_holes_border: bool = False
+    """
+    Whether holes should have borders.
+    """
 
-    # border_stroke_width
-    @property
-    def border_stroke_width(self) -> float:
-        return self._get_attr("borderStrokeWidth", data_type="float", def_value=0.0)
+    rotate_label: bool = False
+    """
+    Whether to rotate the label counter to the camera's rotation, 
+    to ensure it remains upright.
+    """
 
-    @border_stroke_width.setter
-    def border_stroke_width(self, value: OptionalNumber):
-        assert value is None or value >= 0, "border_stroke_width cannot be negative"
-        self._set_attr("borderStrokeWidth", value)
+    stroke_cap: ft.StrokeCap = ft.StrokeCap.ROUND
+    """
+    Style to use for line endings.
+    """
 
-    # coordinates
-    @property
-    def coordinates(self) -> List[MapLatitudeLongitude]:
-        return self.__coordinates
+    stroke_join: ft.StrokeJoin = ft.StrokeJoin.ROUND
+    """
+    Style to use for line segment joins.
+    """
 
-    @coordinates.setter
-    def coordinates(self, value: List[MapLatitudeLongitude]):
-        self.__coordinates = value
+    def before_update(self):
+        super().before_update()
+        assert (
+            self.border_stroke_width >= 0
+        ), "border_stroke_width must be greater than or equal to 0"
 
 
+@ft.control("PolygonLayer")
 class PolygonLayer(MapLayer):
     """
     A layer to display PolygonMarkers.
-
-    -----
-
-    Online docs: https://flet.dev/docs/controls/mappolygonlayer
     """
 
-    def __init__(
-        self,
-        polygons: List[PolygonMarker],
-        polygon_culling: Optional[bool] = None,
-        polygon_labels: Optional[bool] = None,
-        draw_labels_last: Optional[bool] = None,
-        simplification_tolerance: OptionalNumber = None,
-        use_alternative_rendering: Optional[bool] = None,
-        #
-        # MapLayer
-        #
-        ref: Optional[Ref] = None,
-        visible: Optional[bool] = None,
-        data: Any = None,
-    ):
-        MapLayer.__init__(
-            self,
-            ref=ref,
-            visible=visible,
-            data=data,
-        )
-
-        self.polygons = polygons
-        self.polygon_culling = polygon_culling
-        self.polygon_labels = polygon_labels
-        self.draw_labels_last = draw_labels_last
-        self.simplification_tolerance = simplification_tolerance
-        self.use_alternative_rendering = use_alternative_rendering
-
-    def _get_control_name(self):
-        return "map_polygon_layer"
-
-    def _get_children(self):
-        return self.__polygons
-
-    # polygons
-    @property
-    def polygons(self) -> List[PolygonMarker]:
-        return self.__polygons
-
-    @polygons.setter
-    def polygons(self, value: List[PolygonMarker]):
-        self.__polygons = value
-
-    # polygon_culling
-    @property
-    def polygon_culling(self) -> bool:
-        return self._get_attr("polygonCulling", data_type="bool", def_value=False)
-
-    @polygon_culling.setter
-    def polygon_culling(self, value: Optional[bool]):
-        self._set_attr("polygonCulling", value)
-
-    # use_alternative_rendering
-    @property
-    def use_alternative_rendering(self) -> bool:
-        return self._get_attr(
-            "useAlternativeRendering", data_type="bool", def_value=False
-        )
-
-    @use_alternative_rendering.setter
-    def use_alternative_rendering(self, value: Optional[bool]):
-        self._set_attr("useAlternativeRendering", value)
-
-    # polygon_labels
-    @property
-    def polygon_labels(self) -> bool:
-        return self._get_attr("polygonLabels", data_type="bool", def_value=True)
+    polygons: List[PolygonMarker]
+    """
+    A list of [`PolygonMarker`][(p).]s to display.
+    """
 
-    @polygon_labels.setter
-    def polygon_labels(self, value: Optional[bool]):
-        self._set_attr("polygonLabels", value)
+    polygon_culling: bool = True
+    """
+    Whether to cull polygons and polygon sections that are outside of the viewport.
+    """
 
-    # simplification_tolerance
-    @property
-    def simplification_tolerance(self) -> float:
-        return self._get_attr(
-            "simplificationTolerance", data_type="float", def_value=0.5
-        )
+    polygon_labels: bool = True
+    """
+    Whether to draw per-polygon labels.
+    """
 
-    @simplification_tolerance.setter
-    def simplification_tolerance(self, value: OptionalNumber):
-        self._set_attr("simplificationTolerance", value)
+    draw_labels_last: bool = False
+    """
+    Whether to draw labels last and thus over all the polygons.
+    """
 
-    # draw_labels_last
-    @property
-    def draw_labels_last(self) -> bool:
-        return self._get_attr("drawLabelsLast", data_type="bool", def_value=False)
+    simplification_tolerance: ft.Number = 0.3
+    """
+    
+    """
 
-    @draw_labels_last.setter
-    def draw_labels_last(self, value: Optional[bool]):
-        self._set_attr("drawLabelsLast", value)
+    use_alternative_rendering: bool = False
+    """
+    Whether to use an alternative rendering pathway to draw polygons onto the
+    underlying `Canvas`, which can be more performant in 'some' circumstances. 
+    
+    This will not always improve performance, and there are other important
+    considerations before enabling it. It is intended for use when prior
+    profiling indicates more performance is required after other methods are
+    already in use. For example, it may worsen performance when there are a
+    huge number of polygons to triangulate - and so this is best used in
+    conjunction with simplification, not as a replacement.
+    """