MPowerKit.GoogleMaps 1.0.2

MPowerKit.GoogleMaps

Google Maps SDK library for .NET MAUI. Very easy to use. Allows to interact with map in MVVM manner through bindings or with map control directly.

This library is designed for the .NET MAUI. The main control of this library GoogleMap implements every single feature that Google Maps SDK for Android and iOS provides. Every feature of the SDK is represented as BindableProperty, so you can build very flexible solutions that require usage of Google Maps.

Table Of Contents

• Setup
• Usage
• API definition
  • Events and commands
  • Public methods, actions, funcs
  • Bindable properties
    • Read only properties
    • Properties related to objects on the map
    • Other properties
  • Models
    • Point
    • LatLngBounds
    • VisibleRegion
    • MapCapabilities
    • PointOfInterest
    • CameraPosition
    • CameraUpdate
    • CameraUpdateFactory
    • IndoorBuilding
    • IndoorLevel
    • CameraMoveReason
    • MapType
    • MapColorScheme
    • ViewImageSource
    • NoTileImageSource
    • Distance
  • Map objects
    • Pin
    • Polyline
    • Polygon
    • Circle
    • GroundOverlay
    • TileOverlay
      • TileProvider

Setup

First of all you need to make sure you have set up Google Cloud Console and obtained Google Maps API key.

Then you need to set up your project to be able to use Google Maps SDK. In your MainProgram.cs add next:

builder
    .UseMauiApp<App>()
    .UseMPowerKitGoogleMaps(
#if IOS
        "Your iOS API key here"
#endif
    );

and in Android's MainApplication.cs:

[Application]
[MetaData("com.google.android.maps.v2.API_KEY", Value = "Your Android API key here")]
public class MainApplication : MauiApplication
{
    public MainApplication(IntPtr handle, JniHandleOwnership ownership) : base(handle, ownership)
    { }
    
    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}

or in you Android's AndroidManifest.xml:

<application>
    
    <meta-data android:name="com.google.android.geo.API_KEY" android:value="Your Android API key here" />
</application>

Also, be sure you have added permissions to your Android's AndroidManifest.xml if you want to show 'My location' on the map:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-feature android:name="android.hardware.location" android:required="false" />
<uses-feature android:name="android.hardware.location.gps" android:required="false" />
<uses-feature android:name="android.hardware.location.network" android:required="false" />

Usage

To use this library in you MAUI projects just add GoogleMap control you your xaml file as next:

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="Sample.Views.MainPage"
             xmlns:gm="clr-namespace:MPowerKit.GoogleMaps;assembly=MPowerKit.GoogleMaps">
    <gm:GoogleMap />
</ContentPage>

The full list of all properties and features you can find here. Also every single feature is shown in Sample project, so it is better to download it and there you can find how to use feature you need.

API definition

!!! Important: If you cannot find documentation about some methods, events or properties here, then you can search some at offical Google Maps SDK web site.

API of this library is devided into 9 logical groups: Map features, Camera, UI Settings, Pins, Circles, Polylines, Polygons, Tiles, Ground overlays. Each logic group is represented as separate manager and responsible only for that part of logic, and preregistered in the public static dictionary inside the handler:

public static Dictionary<string, Func<IMapFeatureManager<GoogleMap, NativeMapView, GoogleMapHandler>>> ManagerMapper = new()
{
    { nameof(MapManager), () => new MapManager() },
    { nameof(CameraManager), () => new CameraManager() },
    { nameof(UiSettingsManager), () => new UiSettingsManager() },
    { nameof(PolylineManager), () => new PolylineManager() },
    { nameof(PolygonManager), () => new PolygonManager() },
    { nameof(CircleManager), () => new CircleManager() },
    { nameof(TileOverlayManager), () => new TileOverlayManager() },
    { nameof(GroundOverlayManager), () => new GroundOverlayManager() },
    { nameof(PinManager), () => new PinManager() },
};

Note: NativeMapView is different for Android and iOS

This approach is very flexible and gives you possibility to operate with different logics in a very simple way, and it is very easy understand, add, change or remove already registered implementations by your's. For example: if you want to remove some logic, you just need to remove registration from ManagerMapper dictionary, as next:

GoogleMapHandler.ManagerMapper.Remove(nameof(GroundOverlayManager));

If you want to change implementation, you can do next:

GoogleMapHandler.ManagerMapper[nameof(Pins)] = () => new YourPinManager();

If you want to add absolutely new logic to your map, you can do next:

GoogleMapHandler.ManagerMapper["YourManagerUniqueName"] = () => new YourNewLogicManager();

and your YourNewLogicManager should be typeof(IMapFeatureManager<GoogleMap, NativeMapView, GoogleMapHandler>)

Note: You can do it in your MauiProgram.cs or in any other place in your code. But you should understand, that this changes can be applied to the map only before navigating to the page with map.

Events and commands

Public methods, actions, funcs

Bindable properties

Read only properties

There are some readonly properties, which are not visible in XAML editor, but you can bind them. One condition, they can be bound only with Mode=OneWayToSource, otherwise it will not work. This means that value can be passed only from map control to the viewmodel. Example of usage:

<gm:GoogleMap MapCapabilities="{Binding MapCapabilities, Mode=OneWayToSource}" />

Properties related to objects on the map

Other properties

Models

Point

This structure is taken from Microsoft.Maui.Graphics namespace just to simplify the framework and not to 'invent the bicycle'. Basically it is used to represent coordinates on the map, where X - Latitude, Y - Longitude. But in some cases Point represents just point on the screen where X - x coordinate, Y - y coordinate. It depends on the context of usage of this structure.

LatLngBounds

A structure that represents a latitude/longitude aligned rectangle.

VisibleRegion

VisibleRegion is a struct. Contains the four points defining the four-sided polygon that is visible in a map's camera. This polygon can be a trapezoid instead of a rectangle, because a camera can have tilt. If the camera is directly over the center of the camera, the shape is rectangular, but if the camera is tilted, the shape will appear to be a trapezoid whose smallest side is closest to the point of view.

MapCapabilities

MapCapabilities is a struct that allows customers to track the availability of each capability.

PointOfInterest

PointOfInterest is a struct that contains information about a 'Point of Interest' that was clicked on.

CameraPosition

An immutable class that aggregates all camera position parameters such as location, zoom level, tilt angle, and bearing. Use CameraPosition.Builder to construct a CameraPosition instance, which you can then use in conjunction with CameraUpdateFactory.

CameraUpdate

An abstract class that is used to update camera position. Can be created by different factory methods of CameraUpdateFactory.

CameraUpdateFactory

A class containing methods for creating CameraUpdate objects that change a map's camera. Each method returns CameraUpdate object.

IndoorBuilding

IndoorBuilding is a record. Represents a building on the map that can be focused.

IndoorLevel

IndoorLevel is a record. Represents a level in a building. It has only one method Activate(), when calling this method this building's level will be activated.

CameraMoveReason

CameraMoveReason is an enum. It indicates the reason of camera movement.

MapType

MapType is an enum. Indicates what type of map tiles that should be displayed.

MapColorScheme

MapColorScheme is an enum. Indicates what color mode should be used to show the map. Applies only for Android.

ViewImageSource

ViewImageSource is a class derived from MAUI's ImageSource. It has only one property public View? View { get; set; }. This type of image source can be used to show any view as image. Can be used in XAML.

NoTileImageSource

NoTileImageSource is a class derived from MAUI's ImageSource. It has only one static property public static readonly ImageSource Instance = new NoTileImageSource();. This type of image source should only be used to specify that there is no tile at specific coordinates and zoom level.

Distance

Distance is an utility static class. It provides utility methods to calculate distance between coordinates or converting other units to meters, and has other useful methods and constants. All methods that operate with distance return distance in meters.

Map objects

There 6 types of objects that can be added to the map: Pin, Circle, Polyline, Polygon, TileOverlay, GroundOverlay. To simplify implementation of the library for polylines and polygons were used already existing classes from Microsoft.Maui.Controls.Shapes namespace. Circle is derived from Shape class. Pin, TileOverlay, GroundOverlay are derived from VisualElement class.

Pin

Pin is a subclass from VisualElement. It is an icon placed at a particular point on the map's surface. A pin icon is drawn oriented against the device's screen rather than the map's surface; i.e., it will not necessarily change orientation due to map rotations, tilting, or zooming. Every property of the pin can be changed any time.

Polyline

Polyline is a class taken from Microsoft.Maui.Controls.Shapes namespace just to simplify the framework and not to 'invent the bicycle'. It is a list of points, where line segments are drawn between consecutive points. Every property of the polyline can be changed any time.

Polygon

Polygon is a class taken from Microsoft.Maui.Controls.Shapes namespace just to simplify the framework and not to 'invent the bicycle'. A polygon on the earth's surface. A polygon can be convex or concave, it may span the 180 meridian and it can have holes that are not filled in. Every property of the polygon can be changed any time.

Circle

Circle is a subclass of Shape. A circle on the earth's surface (spherical cap). Every property of the circle can be changed any time.

GroundOverlay

GroundOverlay is a subclass of VisualElement. A ground overlay is an image that is fixed to a map. Every property of the ground overlay can be changed any time.

TileOverlay

GroundOverlay is a subclass of VisualElement. A Tile Overlay is a set of images which are displayed on top of the base map tiles. These tiles may be transparent, allowing you to add features to existing maps.

TileProvider

TileProvider is a property of TileOverlay. Used to provide tile images based on coordinates, zoom level and tile size. First parameter is a Point that represents tile coordinate (this is not Earth coordinate) at specific zoom level. Second parameter represents zoom level. Third parameter represents tile size. Return type is ImageSource?. You can return all types of image sources as tile images, such as stream, url, file etc. Also, you can return ViewImageSource to provide a custom view as tile image. If you return null this means that there is no image available at the moment, but can be available later. To specify that for specific coordinates and zoom there is should not be any tile, you must return NoTileImageSource.Instance.