flet-map 0.2.0.dev46__tar.gz → 0.2.0.dev63__tar.gz

{flet_map-0.2.0.dev46/src/flet_map.egg-info → flet_map-0.2.0.dev63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flet-map
-Version: 0.2.0.dev46
+Version: 0.2.0.dev63
 Summary: Display interactive Maps in your Flet apps.
 Author-email: Flet contributors <hello@flet.dev>
 License-Expression: Apache-2.0
@@ -41,7 +41,9 @@ This package supports the following platforms:
 | Android  |     ✅     |
 | Web      |     ✅     |
 
-## Installation
+## Usage
+
+### Installation
 
 To install the `flet-map` package and add it to your project dependencies:
 
@@ -61,6 +63,6 @@ To install the `flet-map` package and add it to your project dependencies:
     poetry add flet-map
     ```
 
-## Examples
+### Examples
 
-For examples, see [this](./examples)
+For examples, see [these](./examples).

{flet_map-0.2.0.dev46 → flet_map-0.2.0.dev63}/README.md

@@ -25,7 +25,9 @@ This package supports the following platforms:
 | Android  |     ✅     |
 | Web      |     ✅     |
 
-## Installation
+## Usage
+
+### Installation
 
 To install the `flet-map` package and add it to your project dependencies:
 
@@ -45,6 +47,6 @@ To install the `flet-map` package and add it to your project dependencies:
     poetry add flet-map
     ```
 
-## Examples
+### Examples
 
-For examples, see [this](./examples)
+For examples, see [these](./examples).

flet_map-0.2.0.dev63/pyproject.toml

@@ -0,0 +1,97 @@
+[project]
+name = "flet-map"
+version = "0.2.0.dev63"
+description = "Display interactive Maps in your Flet apps."
+readme = "README.md"
+authors = [{ name = "Flet contributors", email = "hello@flet.dev" }]
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = [
+    "flet >=0.70.0.dev0",
+]
+
+[project.urls]
+Homepage = "https://flet.dev"
+Documentation = "https://flet-dev.github.io/flet-map"
+Repository = "https://github.com/flet-dev/flet-map"
+Issues = "https://github.com/flet-dev/flet-map/issues"
+
+[tool.setuptools.package-data]
+"flutter.flet_map" = ["**/*"]
+
+[dependency-groups]
+test = [
+    "pytest >=7.2.0",
+]
+lint = [
+    "ruff >=0.11.7",
+]
+dev = [
+    "pre-commit >=4.2.0",
+    { include-group = 'lint' },
+    { include-group = 'test' },
+]
+docs-coverage = [
+    "docstr-coverage >=2.3.2",
+]
+docs = [
+    "mkdocs >=1.6.1",
+    "mkdocs-material >=9.6.15",
+    "mkdocstrings-python >=1.16.12",
+    "mkdocstrings-python-xref >=1.16.3",
+    "mike >=2.1.3",
+    "markdown >=3.6",
+    "pymdown-extensions >=10.16",
+    "mkdocs-exclude >=1.0.2",
+    "mkdocs-glightbox >=0.4.0",
+    "mkdocs-open-in-new-tab >=1.0.8",
+    "mkdocs-section-index >=0.3.10",
+    "griffe-modernized-annotations >=1.0.8",
+    "griffe-warnings-deprecated >=1.1.0",
+    "pygments >=2.16",
+    "markdown-exec[ansi] >=1.11.0",
+    "pydocstyle >=6.3.0",
+    "linkcheckmd >=1.4.0",
+    "mkdocs-external-images",
+    { include-group = 'docs-coverage' },
+]
+all = [
+    { include-group = 'dev' },
+    { include-group = 'docs' },
+]
+
+[tool.uv.sources]
+mkdocs-external-images = { git = "https://github.com/flet-dev/mkdocs-external-images", tag = "v0.2.0" }
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+fix = true
+show-fixes = true
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I"
+]
+preview = true
+pydocstyle = { convention = 'google' }
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"

flet_map-0.2.0.dev63/src/flet_map/__init__.py

@@ -0,0 +1,85 @@
+from flet_map.circle_layer import CircleLayer, CircleMarker
+from flet_map.map import Map
+from flet_map.marker_layer import Marker, MarkerLayer
+from flet_map.polygon_layer import PolygonLayer, PolygonMarker
+from flet_map.polyline_layer import PolylineLayer, PolylineMarker
+from flet_map.rich_attribution import RichAttribution
+from flet_map.simple_attribution import SimpleAttribution
+from flet_map.source_attribution import (
+    ImageSourceAttribution,
+    SourceAttribution,
+    TextSourceAttribution,
+)
+from flet_map.tile_layer import TileLayer
+from flet_map.types import (
+    AttributionAlignment,
+    Camera,
+    CameraFit,
+    CursorKeyboardRotationConfiguration,
+    CursorRotationBehaviour,
+    DashedStrokePattern,
+    DottedStrokePattern,
+    FadeInTileDisplay,
+    InstantaneousTileDisplay,
+    InteractionConfiguration,
+    InteractionFlag,
+    KeyboardConfiguration,
+    MapEvent,
+    MapEventSource,
+    MapHoverEvent,
+    MapLatitudeLongitude,
+    MapLatitudeLongitudeBounds,
+    MapPointerEvent,
+    MapPositionChangeEvent,
+    MapTapEvent,
+    MultiFingerGesture,
+    PatternFit,
+    SolidStrokePattern,
+    StrokePattern,
+    TileDisplay,
+    TileLayerEvictErrorTileStrategy,
+)
+
+__all__ = [
+    "AttributionAlignment",
+    "Camera",
+    "CameraFit",
+    "CircleLayer",
+    "CircleMarker",
+    "CursorKeyboardRotationConfiguration",
+    "CursorRotationBehaviour",
+    "DashedStrokePattern",
+    "DottedStrokePattern",
+    "FadeInTileDisplay",
+    "ImageSourceAttribution",
+    "InstantaneousTileDisplay",
+    "InteractionConfiguration",
+    "InteractionFlag",
+    "KeyboardConfiguration",
+    "Map",
+    "MapEvent",
+    "MapEventSource",
+    "MapHoverEvent",
+    "MapLatitudeLongitude",
+    "MapLatitudeLongitudeBounds",
+    "MapPointerEvent",
+    "MapPositionChangeEvent",
+    "MapTapEvent",
+    "Marker",
+    "MarkerLayer",
+    "MultiFingerGesture",
+    "PatternFit",
+    "PolygonLayer",
+    "PolygonMarker",
+    "PolylineLayer",
+    "PolylineMarker",
+    "RichAttribution",
+    "SimpleAttribution",
+    "SolidStrokePattern",
+    "SourceAttribution",
+    "StrokePattern",
+    "TextSourceAttribution",
+    "TileDisplay",
+    "TileLayer",
+    "TileLayerEvictErrorTileStrategy",
+]

{flet_map-0.2.0.dev46 → flet_map-0.2.0.dev63}/src/flet_map/circle_layer.py

@@ -1,17 +1,18 @@
-from typing import List, Optional
+from typing import Optional
 
 import flet as ft
 
-from .map_layer import MapLayer
-from .types import MapLatitudeLongitude
+from flet_map.map_layer import MapLayer
+from flet_map.types import MapLatitudeLongitude
 
-__all__ = ["CircleMarker", "CircleLayer"]
+__all__ = ["CircleLayer", "CircleMarker"]
 
 
 @ft.control("CircleMarker")
 class CircleMarker(ft.Control):
     """
-    A circular marker displayed on the Map at the specified location through the [`CircleLayer`][(p).].
+    A circular marker displayed on the Map at the specified
+    location through the [`CircleLayer`][(p).].
 
     Raises:
         AssertionError: If the [`border_stroke_width`][(c).] is negative.
@@ -29,14 +30,16 @@ class CircleMarker(ft.Control):
     border_color: Optional[ft.ColorValue] = None
     """
     The color of the circle border line.
-    
-    Needs [`border_stroke_width`][..] to be greater than `0.0` in order to be visible.
+
+    Note:
+        [`border_stroke_width`][..] must to be greater than
+        `0.0` in order for this color to be visible.
     """
 
     border_stroke_width: ft.Number = 0.0
     """
-    The stroke width for the circle border. 
-    
+    The stroke width for the circle border.
+
     Note:
         Must be non-negative.
     """
@@ -48,9 +51,10 @@ class CircleMarker(ft.Control):
 
     def before_update(self):
         super().before_update()
-        assert (
-            self.border_stroke_width >= 0
-        ), "border_stroke_width must be greater than or equal to 0"
+        assert self.border_stroke_width >= 0, (
+            f"border_stroke_width must be greater than or equal to 0, "
+            f"got {self.border_stroke_width}"
+        )
 
 
 @ft.control("CircleLayer")
@@ -59,5 +63,5 @@ class CircleLayer(MapLayer):
     A layer to display [`CircleMarker`][(p).]s.
     """
 
-    circles: List[CircleMarker]
+    circles: list[CircleMarker]
     """A list of [`CircleMarker`][(p).]s to display."""

flet_map-0.2.0.dev63/src/flet_map/map.py

@@ -0,0 +1,368 @@
+from dataclasses import field
+from typing import Optional
+
+import flet as ft
+
+from flet_map.map_layer import MapLayer
+from flet_map.types import (
+    CameraFit,
+    InteractionConfiguration,
+    MapEvent,
+    MapHoverEvent,
+    MapLatitudeLongitude,
+    MapPointerEvent,
+    MapPositionChangeEvent,
+    MapTapEvent,
+)
+
+__all__ = ["Map"]
+
+
+@ft.control("Map")
+class Map(ft.ConstrainedControl):
+    """
+    An interactive map that displays various layers.
+    """
+
+    layers: list[MapLayer]
+    """
+    A list of layers to be displayed (stack-like) on the map.
+    """
+
+    initial_center: MapLatitudeLongitude = field(
+        default_factory=lambda: MapLatitudeLongitude(latitude=50.5, longitude=30.51)
+    )
+    """
+    The initial center of the map.
+    """
+
+    initial_rotation: ft.Number = 0.0
+    """
+    The rotation (in degrees) when the map is first loaded.
+    """
+
+    initial_zoom: ft.Number = 13.0
+    """
+    The zoom when the map is first loaded.
+    If initial_camera_fit is defined this has no effect.
+    """
+
+    interaction_configuration: InteractionConfiguration = field(
+        default_factory=lambda: InteractionConfiguration()
+    )
+    """
+    The interaction configuration.
+    """
+
+    bgcolor: ft.ColorValue = ft.Colors.GREY_300
+    """
+    The background color of this control.
+    """
+
+    keep_alive: bool = False
+    """
+    Whether to enable the built in keep-alive functionality.
+
+    If the map is within a complex layout, such as a [`ListView`][flet.ListView],
+    the map will reset to it's inital position after it appears back into view.
+    To ensure this doesn't happen, enable this flag to prevent it from rebuilding.
+    """
+
+    max_zoom: Optional[ft.Number] = None
+    """
+    The maximum (highest) zoom level of every layer.
+    Each layer can specify additional zoom level restrictions.
+    """
+
+    min_zoom: Optional[ft.Number] = None
+    """
+    The minimum (smallest) zoom level of every layer.
+    Each layer can specify additional zoom level restrictions.
+    """
+
+    animation_curve: ft.AnimationCurve = ft.AnimationCurve.FAST_OUT_SLOWIN
+    """
+    The default animation curve to be used for map-animations
+    when calling instance methods like [`zoom_in()`][(c).zoom_in],
+    [`rotate_from()`][(c).rotate_from],
+    [`move_to()`][(c).move_to] etc.
+    """
+
+    animation_duration: ft.DurationValue = field(
+        default_factory=lambda: ft.Duration(milliseconds=500)
+    )
+    """
+    The default animation duration to be used for map-animations
+    when calling instance methods like [`zoom_in()`][(c).zoom_in],
+    [`rotate_from()`][(c).rotate_from],
+    [`move_to()`][(c).move_to] etc.
+    """
+
+    initial_camera_fit: Optional[CameraFit] = None
+    """
+    Defines the visible bounds when the map is first loaded.
+    Takes precedence over [`initial_center`][..]/[`initial_zoom`][..].
+    """
+
+    on_init: Optional[ft.ControlEventHandler["Map"]] = None
+    """
+    Fires when the map is initialized.
+    """
+
+    on_tap: Optional[ft.EventHandler[MapTapEvent]] = None
+    """
+    Fires when a tap event occurs.
+    """
+
+    on_hover: Optional[ft.EventHandler[MapHoverEvent]] = None
+    """
+    Fires when a hover event occurs.
+    """
+
+    on_secondary_tap: Optional[ft.EventHandler[MapTapEvent]] = None
+    """
+    Fires when a secondary tap event occurs.
+    """
+
+    on_long_press: Optional[ft.EventHandler[MapTapEvent]] = None
+    """
+    Fires when a long press event occurs.
+    """
+
+    on_event: Optional[ft.EventHandler[MapEvent]] = None
+    """
+    Fires when any map events occurs.
+    """
+
+    on_position_change: Optional[ft.EventHandler[MapPositionChangeEvent]] = None
+    """
+    Fires when the map position changes.
+    """
+
+    on_pointer_down: Optional[ft.EventHandler[MapPointerEvent]] = None
+    """
+    Fires when a pointer down event occurs.
+    """
+
+    on_pointer_cancel: Optional[ft.EventHandler[MapPointerEvent]] = None
+    """
+    Fires when a pointer cancel event occurs.
+    """
+
+    on_pointer_up: Optional[ft.EventHandler[MapPointerEvent]] = None
+    """
+    Fires when a pointer up event occurs.
+    """
+
+    async def rotate_from(
+        self,
+        degree: ft.Number,
+        animation_curve: Optional[ft.AnimationCurve] = None,
+        animation_duration: Optional[ft.DurationValue] = None,
+        cancel_ongoing_animations: bool = False,
+    ) -> None:
+        """
+        Applies a rotation of `degree` to the current rotation.
+
+        Args:
+            degree: The number of degrees to increment to the current rotation.
+            animation_curve: The curve of the animation. If None (the default),
+                [`Map.animation_curve`][(p).] will be used.
+            animation_duration: The duration of the animation.
+                If None (the default), [`Map.animation_duration`][(p).] will be used.
+            cancel_ongoing_animations: Whether to cancel/stop all
+                ongoing map-animations before starting this new one.
+        """
+        await self._invoke_method(
+            method_name="rotate_from",
+            arguments={
+                "degree": degree,
+                "curve": animation_curve or self.animation_curve,
+                "duration": animation_duration or self.animation_duration,
+                "cancel_ongoing_animations": cancel_ongoing_animations,
+            },
+        )
+
+    async def reset_rotation(
+        self,
+        animation_curve: Optional[ft.AnimationCurve] = None,
+        animation_duration: Optional[ft.DurationValue] = None,
+        cancel_ongoing_animations: bool = False,
+    ) -> None:
+        """
+        Resets the map's rotation to 0 degrees.
+
+        Args:
+            animation_curve: The curve of the animation. If None (the default),
+                [`Map.animation_curve`][(p).] will be used.
+            animation_duration: The duration of the animation.
+                If None (the default), [`Map.animation_duration`][(p).] will be used.
+            cancel_ongoing_animations: Whether to cancel/stop all
+                ongoing map-animations before starting this new one.
+        """
+        await self._invoke_method(
+            method_name="reset_rotation",
+            arguments={
+                "curve": animation_curve or self.animation_curve,
+                "duration": animation_duration or self.animation_duration,
+                "cancel_ongoing_animations": cancel_ongoing_animations,
+            },
+        )
+
+    async def zoom_in(
+        self,
+        animation_curve: Optional[ft.AnimationCurve] = None,
+        animation_duration: Optional[ft.DurationValue] = None,
+        cancel_ongoing_animations: bool = False,
+    ) -> None:
+        """
+        Zooms in by one zoom-level from the current one.
+
+        Args:
+            animation_curve: The curve of the animation. If None (the default),
+                [`Map.animation_curve`][(p).] will be used.
+            animation_duration: The duration of the animation.
+                If None (the default), [`Map.animation_duration`][(p).] will be used.
+            cancel_ongoing_animations: Whether to cancel/stop all
+                ongoing map-animations before starting this new one.
+        """
+        await self._invoke_method(
+            method_name="zoom_in",
+            arguments={
+                "curve": animation_curve or self.animation_curve,
+                "duration": animation_duration or self.animation_duration,
+                "cancel_ongoing_animations": cancel_ongoing_animations,
+            },
+        )
+
+    async def zoom_out(
+        self,
+        animation_curve: Optional[ft.AnimationCurve] = None,
+        animation_duration: Optional[ft.DurationValue] = None,
+        cancel_ongoing_animations: bool = False,
+    ) -> None:
+        """
+        Zooms out by one zoom-level from the current one.
+
+        Args:
+            animation_curve: The curve of the animation. If None (the default),
+                [`Map.animation_curve`][(p).] will be used.
+            animation_duration: The duration of the animation.
+                If None (the default), [`Map.animation_duration`][(p).] will be used.
+            cancel_ongoing_animations: Whether to cancel/stop all
+                ongoing map-animations before starting this new one.
+        """
+        await self._invoke_method(
+            method_name="zoom_out",
+            arguments={
+                "curve": animation_curve or self.animation_curve,
+                "duration": animation_duration or self.animation_duration,
+                "cancel_ongoing_animations": cancel_ongoing_animations,
+            },
+        )
+
+    async def zoom_to(
+        self,
+        zoom: ft.Number,
+        animation_curve: Optional[ft.AnimationCurve] = None,
+        animation_duration: Optional[ft.DurationValue] = None,
+        cancel_ongoing_animations: bool = False,
+    ) -> None:
+        """
+        Zoom the map to a specific zoom level.
+
+        Args:
+            zoom: The zoom level to zoom to.
+            animation_curve: The curve of the animation. If None (the default),
+                [`Map.animation_curve`][(p).] will be used.
+            animation_duration: The duration of the animation.
+                If None (the default), [`Map.animation_duration`][(p).] will be used.
+            cancel_ongoing_animations: Whether to cancel/stop all
+                ongoing map-animations before starting this new one.
+        """
+        await self._invoke_method(
+            method_name="zoom_to",
+            arguments={
+                "zoom": zoom,
+                "curve": animation_curve or self.animation_curve,
+                "duration": animation_duration or self.animation_duration,
+                "cancel_ongoing_animations": cancel_ongoing_animations,
+            },
+        )
+
+    async def move_to(
+        self,
+        destination: Optional[MapLatitudeLongitude] = None,
+        zoom: Optional[ft.Number] = None,
+        rotation: Optional[ft.Number] = None,
+        animation_curve: Optional[ft.AnimationCurve] = None,
+        animation_duration: Optional[ft.DurationValue] = None,
+        offset: ft.OffsetValue = (0, 0),
+        cancel_ongoing_animations: bool = False,
+    ) -> None:
+        """
+        Moves to a specific location.
+
+        Args:
+            destination: The destination point to move to.
+            zoom: The zoom level to be applied. If provided,
+                must be greater than or equal to `0.0`.
+            rotation: Rotation (in degrees) to be applied.
+            offset: The offset to be used. Only works when `rotation` is `None`.
+            animation_curve: The curve of the animation. If None (the default),
+                [`Map.animation_curve`][(p).] will be used.
+            animation_duration: The duration of the animation.
+                If None (the default), [`Map.animation_duration`][(p).] will be used.
+            cancel_ongoing_animations: Whether to cancel/stop all
+                ongoing map-animations before starting this new one.
+
+        Raises:
+            AssertionError: If `zoom` is not `None` and is negative.
+        """
+        assert zoom is None or zoom >= 0, (
+            f"zoom must be greater than or equal to zero, got {zoom}"
+        )
+        await self._invoke_method(
+            method_name="move_to",
+            arguments={
+                "destination": destination,
+                "zoom": zoom,
+                "offset": offset,
+                "rotation": rotation,
+                "curve": animation_curve or self.animation_curve,
+                "duration": animation_duration or self.animation_duration,
+                "cancel_ongoing_animations": cancel_ongoing_animations,
+            },
+        )
+
+    async def center_on(
+        self,
+        point: MapLatitudeLongitude,
+        zoom: Optional[ft.Number],
+        animation_curve: Optional[ft.AnimationCurve] = None,
+        animation_duration: Optional[ft.DurationValue] = None,
+        cancel_ongoing_animations: bool = False,
+    ) -> None:
+        """
+        Centers the map on the given point.
+
+        Args:
+            point: The point on which to center the map.
+            zoom: The zoom level to be applied.
+            animation_curve: The curve of the animation. If `None` (the default),
+                [`Map.animation_curve`][(p).] will be used.
+            animation_duration: The duration of the animation.
+                If None (the default), [`Map.animation_duration`][(p).] will be used.
+            cancel_ongoing_animations: Whether to cancel/stop all
+                ongoing map-animations before starting this new one.
+        """
+        await self._invoke_method(
+            method_name="center_on",
+            arguments={
+                "point": point,
+                "zoom": zoom,
+                "curve": animation_curve or self.animation_curve,
+                "duration": animation_duration or self.animation_duration,
+                "cancel_ongoing_animations": cancel_ongoing_animations,
+            },
+        )