Skip to content

Use the .NET 8 xmlns schema for Map, MapSpan, and Distance #1801

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
davidbritch merged 1 commit into from
Oct 19, 2023
Merged

Use the .NET 8 xmlns schema for Map, MapSpan, and Distance #1801

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
275 changes: 275 additions & 0 deletions docs/user-interface/controls/map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,8 @@ For information about the `ItemsSource`, `ItemTemplate`, and `ItemTemplateSelect

A <xref:Microsoft.Maui.Controls.Maps.Map> can be displayed by adding it to a layout or page:

::: moniker range="=net-maui-7.0"

```xaml
<ContentPage ...
xmlns:maps="clr-namespace:Microsoft.Maui.Controls.Maps;assembly=Microsoft.Maui.Controls.Maps">
Expand All @@ -183,6 +185,19 @@ A <xref:Microsoft.Maui.Controls.Maps.Map> can be displayed by adding it to a lay
> [!NOTE]
> In XAML, an `xmlns` namespace definition should be added for the <xref:Microsoft.Maui.Controls.Maps.Map> control. While this isn't required, it prevents a collision between the `Polygon` and `Polyline` types, which exist in both the <xref:Microsoft.Maui.Controls.Maps> and <xref:Microsoft.Maui.Controls.Shapes> namespaces.

::: moniker-end

::: moniker range=">=net-maui-8.0"

```xaml
<ContentPage ...
xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps">
<maps:Map x:Name="map" />
</ContentPage>
```

::: moniker-end

The equivalent C# code is:

```csharp
Expand Down Expand Up @@ -237,6 +252,8 @@ Map map = new Map

The region of a map to display when a map is loaded can be set by passing a `MapSpan` argument to the <xref:Microsoft.Maui.Controls.Maps.Map> constructor:

::: moniker range="=net-maui-7.0"

```xaml
<ContentPage ...
xmlns:maps="clr-namespace:Microsoft.Maui.Controls.Maps;assembly=Microsoft.Maui.Controls.Maps"
Expand All @@ -260,6 +277,35 @@ The region of a map to display when a map is loaded can be set by passing a `Map
</ContentPage>
```

::: moniker-end

::: moniker range=">=net-maui-8.0"

```xaml
<ContentPage ...
xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps"
xmlns:sensors="clr-namespace:Microsoft.Maui.Devices.Sensors;assembly=Microsoft.Maui.Essentials">
<maps:Map>
<x:Arguments>
<maps:MapSpan>
<x:Arguments>
<sensors:Location>
<x:Arguments>
<x:Double>36.9628066</x:Double>
<x:Double>-122.0194722</x:Double>
</x:Arguments>
</sensors:Location>
<x:Double>0.01</x:Double>
<x:Double>0.01</x:Double>
</x:Arguments>
</maps:MapSpan>
</x:Arguments>
</maps:Map>
</ContentPage>
```

::: moniker-end

The equivalent C# code is:

```csharp
Expand Down Expand Up @@ -512,6 +558,8 @@ In addition, the `Pin` class defines `MarkerClicked` and `InfoWindowClicked` eve

A `Pin` can be added to a <xref:Microsoft.Maui.Controls.Maps.Map> in XAML:

::: moniker range="=net-maui-7.0"

```xaml
<ContentPage ...
xmlns:maps="clr-namespace:Microsoft.Maui.Controls.Maps;assembly=Microsoft.Maui.Controls.Maps"
Expand Down Expand Up @@ -549,6 +597,49 @@ A `Pin` can be added to a <xref:Microsoft.Maui.Controls.Maps.Map> in XAML:
</ContentPage>
```

::: moniker-end

::: moniker range=">=net-maui-8.0"

```xaml
<ContentPage ...
xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps"
xmlns:sensors="clr-namespace:Microsoft.Maui.Devices.Sensors;assembly=Microsoft.Maui.Essentials">
<maps:Map x:Name="map">
<x:Arguments>
<maps:MapSpan>
<x:Arguments>
<sensors:Location>
<x:Arguments>
<x:Double>36.9628066</x:Double>
<x:Double>-122.0194722</x:Double>
</x:Arguments>
</sensors:Location>
<x:Double>0.01</x:Double>
<x:Double>0.01</x:Double>
</x:Arguments>
</maps:MapSpan>
</x:Arguments>
<maps:Map.Pins>
<maps:Pin Label="Santa Cruz"
Address="The city with a boardwalk"
Type="Place">
<maps:Pin.Location>
<sensors:Location>
<x:Arguments>
<x:Double>36.9628066</x:Double>
<x:Double>-122.0194722</x:Double>
</x:Arguments>
</sensors:Location>
</maps:Pin.Location>
</maps:Pin>
</maps:Map.Pins>
</maps:Map>
</ContentPage>
```

::: moniker-end

This XAML creates a <xref:Microsoft.Maui.Controls.Maps.Map> object that shows the region that is specified by the `MapSpan` object. The `MapSpan` object is centered on the latitude and longitude represented by a `Location` object, which extends 0.01 latitude and longitude degrees. A `Pin` object is added to the `Map.Pins` collection, and drawn on the <xref:Microsoft.Maui.Controls.Maps.Map> at the location specified by its `Location` property. For information about the `Location` class, see [Location and distance](#location-and-distance). For information about passing arguments in XAML to objects that lack default constructors, see [Pass arguments in XAML](~/xaml/pass-arguments.md).

The equivalent C# code is:
Expand Down Expand Up @@ -652,6 +743,8 @@ The <xref:Microsoft.Maui.Controls.Maps.Map> class defines the following bindable

A <xref:Microsoft.Maui.Controls.Maps.Map> can be populated with pins by using data binding to bind its `ItemsSource` property to an `IEnumerable` collection:

::: moniker range="=net-maui-7.0"

```xaml
<ContentPage ...
xmlns:maps="clr-namespace:Microsoft.Maui.Controls.Maps;assembly=Microsoft.Maui.Controls.Maps">
Expand All @@ -672,6 +765,32 @@ A <xref:Microsoft.Maui.Controls.Maps.Map> can be populated with pins by using da
</ContentPage>
```

::: moniker-end

::: moniker range=">=net-maui-8.0"

```xaml
<ContentPage ...
xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps">
<Grid>
...
<maps:Map x:Name="map"
ItemsSource="{Binding Positions}">
<maps:Map.ItemTemplate>
<DataTemplate>
<maps:Pin Location="{Binding Location}"
Address="{Binding Address}"
Label="{Binding Description}" />
</DataTemplate>
</maps:Map.ItemTemplate>
</maps:Map>
...
</Grid>
</ContentPage>
```

::: moniker-end

The `ItemsSource` property data binds to the `Positions` property of the connected viewmodel, which returns an `ObservableCollection` of `Position` objects, which is a custom type. Each `Position` object defines `Address` and `Description` properties, of type `string`, and a `Location` property, of type `Location`.

The appearance of each item in the `IEnumerable` collection is defined by setting the `ItemTemplate` property to a <xref:Microsoft.Maui.Controls.DataTemplate> that contains a `Pin` object that data binds to appropriate properties.
Expand All @@ -684,6 +803,8 @@ The following screenshot shows a <xref:Microsoft.Maui.Controls.Maps.Map> display

The appearance of each item in the `IEnumerable` collection can be chosen at runtime, based on the item value, by setting the `ItemTemplateSelector` property to a <xref:Microsoft.Maui.Controls.DataTemplateSelector>:

::: moniker range="=net-maui-7.0"

```xaml
<ContentPage ...
xmlns:templates="clr-namespace:WorkingWithMaps.Templates"
Expand Down Expand Up @@ -717,6 +838,45 @@ The appearance of each item in the `IEnumerable` collection can be chosen at run
</ContentPage>
```

::: moniker-end

::: moniker range=">=net-maui-8.0"

```xaml
<ContentPage ...
xmlns:templates="clr-namespace:WorkingWithMaps.Templates"
xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps">
<ContentPage.Resources>
<templates:MapItemTemplateSelector x:Key="MapItemTemplateSelector">
<templates:MapItemTemplateSelector.DefaultTemplate>
<DataTemplate>
<maps:Pin Location="{Binding Location}"
Address="{Binding Address}"
Label="{Binding Description}" />
</DataTemplate>
</templates:MapItemTemplateSelector.DefaultTemplate>
<templates:MapItemTemplateSelector.SanFranTemplate>
<DataTemplate>
<maps:Pin Location="{Binding Location}"
Address="{Binding Address}"
Label="Xamarin!" />
</DataTemplate>
</templates:MapItemTemplateSelector.SanFranTemplate>
</templates:MapItemTemplateSelector>
</ContentPage.Resources>

<Grid>
...
<maps:Map x:Name="map"
ItemsSource="{Binding Positions}"
ItemTemplateSelector="{StaticResource MapItemTemplateSelector}">
...
</Grid>
</ContentPage>
```

::: moniker-end

The following example shows the `MapItemTemplateSelector` class:

```csharp
Expand Down Expand Up @@ -770,6 +930,8 @@ The `Circle` class defines the following bindable properties:

A `Polygon` object can be added to a map by instantiating it and adding it to the map's `MapElements` collection:

::: moniker range="=net-maui-7.0"

```xaml
<ContentPage ...
xmlns:maps="clr-namespace:Microsoft.Maui.Controls.Maps;assembly=Microsoft.Maui.Controls.Maps"
Expand Down Expand Up @@ -800,6 +962,42 @@ A `Polygon` object can be added to a map by instantiating it and adding it to th
</ContentPage>
```

::: moniker-end

::: moniker range=">=net-maui-8.0"

```xaml
<ContentPage ...
xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps"
xmlns:sensors="clr-namespace:Microsoft.Maui.Devices.Sensors;assembly=Microsoft.Maui.Essentials">
<maps:Map>
<maps:Map.MapElements>
<maps:Polygon StrokeColor="#FF9900"
StrokeWidth="8"
FillColor="#88FF9900">
<maps:Polygon.Geopath>
<sensors:Location>
<x:Arguments>
<x:Double>47.6458676</x:Double>
<x:Double>-122.1356007</x:Double>
</x:Arguments>
</sensors:Location>
<sensors:Location>
<x:Arguments>
<x:Double>47.6458097</x:Double>
<x:Double>-122.142789</x:Double>
</x:Arguments>
</sensors:Location>
...
</maps:Polygon.Geopath>
</maps:Polygon>
</maps:Map.MapElements>
</maps:Map>
</ContentPage>
```

::: moniker-end

The equivalent C# code is:

```csharp
Expand Down Expand Up @@ -837,6 +1035,8 @@ The `StrokeColor` and `StrokeWidth` properties are specified to set the polygon'

A `Polyline` object can be added to a map by instantiating it and adding it to the map's `MapElements` collection:

::: moniker range="=net-maui-7.0"

```xaml
<ContentPage ...
xmlns:maps="clr-namespace:Microsoft.Maui.Controls.Maps;assembly=Microsoft.Maui.Controls.Maps"
Expand Down Expand Up @@ -866,6 +1066,43 @@ A `Polyline` object can be added to a map by instantiating it and adding it to t
</ContentPage>
```

::: moniker-end

::: moniker range=">=net-maui-8.0"

```xaml
<ContentPage ...
xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps"
xmlns:sensors="clr-namespace:Microsoft.Maui.Devices.Sensors;assembly=Microsoft.Maui.Essentials">
<maps:Map>
<maps:Map.MapElements>
<maps:Polyline StrokeColor="Black"
StrokeWidth="12">
<maps:Polyline.Geopath>
<sensors:Location>
<x:Arguments>
<x:Double>47.6381401</x:Double>
<x:Double>-122.1317367</x:Double>
</x:Arguments>
</sensors:Location>
<sensors:Location>
<x:Arguments>
<x:Double>47.6381473</x:Double>
<x:Double>-122.1350841</x:Double>
</x:Arguments>
</sensors:Location>
...
</maps:Polyline.Geopath>
</maps:Polyline>
</maps:Map.MapElements>
</maps:Map>
</ContentPage>
```

::: moniker-end

The equivalent C# code is:

```csharp
using Microsoft.Maui.Controls.Maps;
using Microsoft.Maui.Maps;
Expand Down Expand Up @@ -897,6 +1134,8 @@ The `StrokeColor` and `StrokeWidth` properties are specified to set the line app

A `Circle` object can be added to a map by instantiating it and adding it to the map's `MapElements` collection:

::: moniker range="=net-maui-7.0"

```xaml
<ContentPage ...
xmlns:maps="clr-namespace:Microsoft.Maui.Controls.Maps;assembly=Microsoft.Maui.Controls.Maps"
Expand Down Expand Up @@ -927,6 +1166,42 @@ A `Circle` object can be added to a map by instantiating it and adding it to the
</ContentPage>
```

::: moniker-end

::: moniker range=">=net-maui-8.0"

```xaml
<ContentPage ...
xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps"
xmlns:sensors="clr-namespace:Microsoft.Maui.Devices.Sensors;assembly=Microsoft.Maui.Essentials">
<maps:Map>
<maps:Map.MapElements>
<maps:Circle StrokeColor="#88FF0000"
StrokeWidth="8"
FillColor="#88FFC0CB">
<maps:Circle.Center>
<sensors:Location>
<x:Arguments>
<x:Double>37.79752</x:Double>
<x:Double>-122.40183</x:Double>
</x:Arguments>
</sensors:Location>
</maps:Circle.Center>
<maps:Circle.Radius>
<maps:Distance>
<x:Arguments>
<x:Double>250</x:Double>
</x:Arguments>
</maps:Distance>
</maps:Circle.Radius>
</maps:Circle>
</maps:Map.MapElements>
</maps:Map>
</ContentPage>
```

::: moniker-end

The equivalent C# code is:

```csharp
Expand Down