From c268b67d5ccc6fec0c63fd90b19667cfe82bc3be Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Wed, 28 Feb 2024 13:51:58 +0100 Subject: [PATCH 1/4] Update Maps Project API Docs --- .../Maps/src/AppHostBuilderExtensions.cs | 7 +++ src/Controls/Maps/src/Circle.cs | 12 ++++++ src/Controls/Maps/src/Controls.Maps.csproj | 2 +- src/Controls/Maps/src/MapClickedEventArgs.cs | 10 +++++ src/Controls/Maps/src/MapElement.cs | 13 ++++++ src/Controls/Maps/src/Pin.cs | 43 ++++++++++++++++++- src/Controls/Maps/src/PinClickedEventArgs.cs | 9 ++++ src/Controls/Maps/src/Polygon.cs | 12 ++++++ src/Controls/Maps/src/Polyline.cs | 9 ++++ 9 files changed, 115 insertions(+), 2 deletions(-) diff --git a/src/Controls/Maps/src/AppHostBuilderExtensions.cs b/src/Controls/Maps/src/AppHostBuilderExtensions.cs index 03f69c4e8385..d3a1fb94eb49 100644 --- a/src/Controls/Maps/src/AppHostBuilderExtensions.cs +++ b/src/Controls/Maps/src/AppHostBuilderExtensions.cs @@ -21,6 +21,7 @@ public static partial class AppHostBuilderExtensions /// /// The to configure. /// The configured . + /// Thrown on Windows because the maps control currently is not implemented for Windows. public static MauiAppBuilder UseMauiMaps(this MauiAppBuilder builder) { builder @@ -56,6 +57,12 @@ public static MauiAppBuilder UseMauiMaps(this MauiAppBuilder builder) return builder; } + /// + /// Registers the .NET MAUI Maps handlers that are needed to render the map control. + /// + /// An instance of on which to register the map handlers. + /// The provided object with the registered map handlers for subsequent registration calls. + /// Thrown on Windows because the maps control currently is not implemented for Windows. public static IMauiHandlersCollection AddMauiMaps(this IMauiHandlersCollection handlersCollection) { #if __ANDROID__ || __IOS__ diff --git a/src/Controls/Maps/src/Circle.cs b/src/Controls/Maps/src/Circle.cs index ef4ff81d5156..d18214d2d503 100644 --- a/src/Controls/Maps/src/Circle.cs +++ b/src/Controls/Maps/src/Circle.cs @@ -4,6 +4,9 @@ namespace Microsoft.Maui.Controls.Maps { + /// + /// Represents a circle drawn on the map control. + /// public partial class Circle : MapElement { /// Bindable property for . @@ -27,18 +30,27 @@ public partial class Circle : MapElement typeof(Circle), null); + /// + /// Gets or sets the center location. + /// public Location Center { get => (Location)GetValue(CenterProperty); set => SetValue(CenterProperty, value); } + /// + /// Gets or sets the radius. + /// public Distance Radius { get => (Distance)GetValue(RadiusProperty); set => SetValue(RadiusProperty, value); } + /// + /// Gets or sets the fill color. + /// public Color FillColor { get => (Color)GetValue(FillColorProperty); diff --git a/src/Controls/Maps/src/Controls.Maps.csproj b/src/Controls/Maps/src/Controls.Maps.csproj index 8b466199cf21..5576732cada8 100644 --- a/src/Controls/Maps/src/Controls.Maps.csproj +++ b/src/Controls/Maps/src/Controls.Maps.csproj @@ -8,7 +8,7 @@ enable <_MauiDesignDllBuild Condition=" '$(OS)' != 'Unix' ">True true - $(NoWarn);CS1591;RS0041;RS0026;RS0027;RS0022 + $(NoWarn);RS0041;RS0026;RS0027;RS0022 $(WarningsAsErrors);CS1591 diff --git a/src/Controls/Maps/src/MapClickedEventArgs.cs b/src/Controls/Maps/src/MapClickedEventArgs.cs index f6536b2041bf..983c3864af1f 100644 --- a/src/Controls/Maps/src/MapClickedEventArgs.cs +++ b/src/Controls/Maps/src/MapClickedEventArgs.cs @@ -2,10 +2,20 @@ namespace Microsoft.Maui.Controls.Maps { + /// + /// Event arguments that are associated with a click/tap event that occurs on the map control. + /// public class MapClickedEventArgs { + /// + /// Gets the location of the click/tap. + /// public Location Location { get; } + /// + /// Initializes a new instance of the class with a location. + /// + /// The location data associated with this event. public MapClickedEventArgs(Location location) { Location = location; diff --git a/src/Controls/Maps/src/MapElement.cs b/src/Controls/Maps/src/MapElement.cs index b4174a5e6214..6ee336248420 100644 --- a/src/Controls/Maps/src/MapElement.cs +++ b/src/Controls/Maps/src/MapElement.cs @@ -7,6 +7,9 @@ namespace Microsoft.Maui.Controls.Maps { + /// + /// Represents an element which is visually drawn on the map control. + /// public partial class MapElement : Element { /// Bindable property for . @@ -23,18 +26,28 @@ public partial class MapElement : Element typeof(MapElement), 5f); + /// + /// Gets or sets the stroke color. + /// public Color StrokeColor { get => (Color)GetValue(StrokeColorProperty); set => SetValue(StrokeColorProperty, value); } + /// + /// Gets or sets the stroke width. + /// public float StrokeWidth { get => (float)GetValue(StrokeWidthProperty); set => SetValue(StrokeWidthProperty, value); } + /// + /// Gets or sets the platform counterpart of this map element. + /// + /// This should typically not be set by the developer. Doing so might result in unpredictable behavior. public object? MapElementId { get; set; } } } diff --git a/src/Controls/Maps/src/Pin.cs b/src/Controls/Maps/src/Pin.cs index e488843666e6..2f2322bbcc92 100644 --- a/src/Controls/Maps/src/Pin.cs +++ b/src/Controls/Maps/src/Pin.cs @@ -5,6 +5,9 @@ namespace Microsoft.Maui.Controls.Maps { + /// + /// Represents a pin on the map control. + /// public partial class Pin : Element { /// Bindable property for . @@ -42,14 +45,19 @@ public Location Location } /// - /// The kind of pin. + /// Gets or sets the kind of pin. /// + /// Depending on the platform, and versions of the platform, this might change the visual representation. This varies between the different platforms. public PinType Type { get { return (PinType)GetValue(TypeProperty); } set { SetValue(TypeProperty, value); } } + /// + /// Gets or sets the platform counterpart of this pin element. + /// + /// This should typically not be set by the developer. Doing so might result in unpredictable behavior. public object? MarkerId { get => _markerId; @@ -69,17 +77,28 @@ public PinType Type /// public event EventHandler? InfoWindowClicked; + /// public override bool Equals(object? obj) { if (obj is null) + { return false; + } + if (ReferenceEquals(this, obj)) + { return true; + } + if (obj.GetType() != GetType()) + { return false; + } + return Equals((Pin)obj); } + /// public override int GetHashCode() { unchecked @@ -99,16 +118,33 @@ public override int GetHashCode() } } + /// + /// Equality operator for equals. + /// + /// Left to compare. + /// Right to compare. + /// if objects are equal, otherwise . public static bool operator ==(Pin? left, Pin? right) { return Equals(left, right); } + /// + /// Inequality operator. + /// + /// Left to compare. + /// Right to compare. + /// if objects are not equal, otherwise . public static bool operator !=(Pin? left, Pin? right) { return !Equals(left, right); } + /// + /// Triggers the click/tap event for a pin. + /// + /// if the info window associated to this pin will hide after this event has occurred, otherwise + /// For internal use only. This API can be changed or removed without notice at any time. [EditorBrowsable(EditorBrowsableState.Never)] public bool SendMarkerClick() { @@ -117,6 +153,11 @@ public bool SendMarkerClick() return args.HideInfoWindow; } + /// + /// Triggers the click/tap event for a info window of a pin. + /// + /// if the info window associated to this pin will hide after this event has occurred, otherwise + /// For internal use only. This API can be changed or removed without notice at any time. [EditorBrowsable(EditorBrowsableState.Never)] public bool SendInfoWindowClick() { diff --git a/src/Controls/Maps/src/PinClickedEventArgs.cs b/src/Controls/Maps/src/PinClickedEventArgs.cs index a346cbdb408f..8b08ebbd9e4a 100644 --- a/src/Controls/Maps/src/PinClickedEventArgs.cs +++ b/src/Controls/Maps/src/PinClickedEventArgs.cs @@ -1,9 +1,18 @@ namespace Microsoft.Maui.Controls.Maps { + /// + /// Event arguments that are associated with a click/tap event that occurs on a pin element of the map control. + /// public class PinClickedEventArgs : System.EventArgs { + /// + /// Gets or sets whether the info window should be hidden after the event occurred. + /// public bool HideInfoWindow { get; set; } + /// + /// Initializes a new instance of the class. + /// public PinClickedEventArgs() { HideInfoWindow = false; diff --git a/src/Controls/Maps/src/Polygon.cs b/src/Controls/Maps/src/Polygon.cs index 735aae2dc64d..3305caedc4f2 100644 --- a/src/Controls/Maps/src/Polygon.cs +++ b/src/Controls/Maps/src/Polygon.cs @@ -5,6 +5,9 @@ namespace Microsoft.Maui.Controls.Maps { + /// + /// Represents a polygon drawn on the map control. + /// public partial class Polygon : MapElement { /// Bindable property for . @@ -14,14 +17,23 @@ public partial class Polygon : MapElement typeof(Polygon), default(Color)); + /// + /// Gets or sets the fill color. + /// public Color FillColor { get => (Color)GetValue(FillColorProperty); set => SetValue(FillColorProperty, value); } + /// + /// Gets a list of locations on the map which forms the outline of this polygon on the map. + /// public IList Geopath { get; } + /// + /// Initializes a new instance of the class. + /// public Polygon() { var observable = new ObservableCollection(); diff --git a/src/Controls/Maps/src/Polyline.cs b/src/Controls/Maps/src/Polyline.cs index 5c911358a204..3f5029182fb9 100644 --- a/src/Controls/Maps/src/Polyline.cs +++ b/src/Controls/Maps/src/Polyline.cs @@ -4,10 +4,19 @@ namespace Microsoft.Maui.Controls.Maps { + /// + /// Represents a polyline drawn on the map control. + /// public partial class Polyline : MapElement { + /// + /// Gets a list of locations on the map which forms the polyline on the map. + /// public IList Geopath { get; } + /// + /// Initializes a new instance of the class. + /// public Polyline() { var observable = new ObservableCollection(); From 8d224853637b59f0ebe6cf4eec82fe2b910120f1 Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Wed, 28 Feb 2024 15:25:00 +0100 Subject: [PATCH 2/4] Add more docs --- src/Controls/Maps/src/Circle.cs | 6 +- src/Controls/Maps/src/Map.cs | 99 +++++++++++++++++++++++++---- src/Controls/Maps/src/MapElement.cs | 5 +- src/Controls/Maps/src/Polygon.cs | 2 +- 4 files changed, 95 insertions(+), 17 deletions(-) diff --git a/src/Controls/Maps/src/Circle.cs b/src/Controls/Maps/src/Circle.cs index d18214d2d503..a33ac2c4e154 100644 --- a/src/Controls/Maps/src/Circle.cs +++ b/src/Controls/Maps/src/Circle.cs @@ -31,7 +31,7 @@ public partial class Circle : MapElement null); /// - /// Gets or sets the center location. + /// Gets or sets the center location. This is a bindable property. /// public Location Center { @@ -40,7 +40,7 @@ public Location Center } /// - /// Gets or sets the radius. + /// Gets or sets the radius. This is a bindable property. /// public Distance Radius { @@ -49,7 +49,7 @@ public Distance Radius } /// - /// Gets or sets the fill color. + /// Gets or sets the fill color. This is a bindable property. /// public Color FillColor { diff --git a/src/Controls/Maps/src/Map.cs b/src/Controls/Maps/src/Map.cs index 3d3ddd87e047..2b75cda93ee6 100644 --- a/src/Controls/Maps/src/Map.cs +++ b/src/Controls/Maps/src/Map.cs @@ -10,6 +10,9 @@ namespace Microsoft.Maui.Controls.Maps { + /// + /// The Map control is a cross-platform view for displaying and annotating maps. + /// public partial class Map : View { /// Bindable property for . @@ -44,6 +47,10 @@ public partial class Map : View MapSpan? _visibleRegion; MapSpan? _lastMoveToRegion; + /// + /// Initializes a new instance of the class with a region. + /// + /// The region that should be initially shown by the map. public Map(MapSpan region) { MoveToRegion(region); @@ -55,83 +62,142 @@ public Map(MapSpan region) _mapElements.CollectionChanged += MapElementsCollectionChanged; } - - // center on Maui by default + /// + /// Initializes a new instance of the class with a region. + /// + // The selected region will default to Maui, Hawaii. public Map() : this(new MapSpan(new Devices.Sensors.Location(20.793062527, -156.336394697), 0.5, 0.5)) { } + /// + /// Gets or sets if scrolling by user input is enabled. Default value is . + /// This is a bindable property. + /// public bool IsScrollEnabled { get { return (bool)GetValue(IsScrollEnabledProperty); } set { SetValue(IsScrollEnabledProperty, value); } } + /// + /// Gets or sets if zooming by user input is enabled. Default value is . + /// This is a bindable property. + /// public bool IsZoomEnabled { get { return (bool)GetValue(IsZoomEnabledProperty); } set { SetValue(IsZoomEnabledProperty, value); } } + /// + /// Gets or sets if the map shows an indicator of the current position of this device. Default value is + /// This is a bindable property. + /// + /// Depending on the platform it is likely that runtime permission(s) need to be requested to determine the current location of the device. public bool IsShowingUser { get { return (bool)GetValue(IsShowingUserProperty); } set { SetValue(IsShowingUserProperty, value); } } + /// + /// Gets or sets if the map shows current traffic information. Default value is . + /// This is a bindable property. + /// public bool IsTrafficEnabled { get => (bool)GetValue(IsTrafficEnabledProperty); set => SetValue(IsTrafficEnabledProperty, value); } + /// + /// Gets or sets the style of the map. Default value is . + /// This is a bindable property. + /// public MapType MapType { get { return (MapType)GetValue(MapTypeProperty); } set { SetValue(MapTypeProperty, value); } } + /// + /// Gets the pins currently added to this map. + /// public IList Pins { get { return _pins; } } + /// + /// Gets or sets the object that represents the collection of pins that should be shown on the map. + /// This is a bindable property. + /// public IEnumerable ItemsSource { get { return (IEnumerable)GetValue(ItemsSourceProperty); } set { SetValue(ItemsSourceProperty, value); } } + /// + /// Gets or sets the template that is to be applied to each object in . + /// This is a bindable property. + /// public DataTemplate ItemTemplate { get { return (DataTemplate)GetValue(ItemTemplateProperty); } set { SetValue(ItemTemplateProperty, value); } } + /// + /// Gets or sets the object that selects the template that is to be applied to each object in . + /// This is a bindable property. + /// public DataTemplateSelector ItemTemplateSelector { get { return (DataTemplateSelector)GetValue(ItemTemplateSelectorProperty); } set { SetValue(ItemTemplateSelectorProperty, value); } } + /// + /// Gets the elements (pins, polygons, polylines, etc.) currently added to this map. + /// public IList MapElements => _mapElements; + /// + /// Occurs when the user clicks/taps on the map control. + /// public event EventHandler? MapClicked; + /// + /// Gets the currently visible region of the map. + /// public MapSpan? VisibleRegion { get { return _visibleRegion; } } + /// + /// Returns an enumarator of all the pins that are currently added to the map. + /// + /// An instance of . public IEnumerator GetEnumerator() { return _pins.GetEnumerator(); } + /// + /// Adjusts the viewport of the map control to view the specified region. + /// + /// A object containing details on what region should be shown. + /// Thrown when is . public void MoveToRegion(MapSpan mapSpan) { - if (mapSpan == null) + if (mapSpan is null) + { throw new ArgumentNullException(nameof(mapSpan)); + } + _lastMoveToRegion = mapSpan; Handler?.Invoke(nameof(IMap.MoveToRegion), _lastMoveToRegion); } @@ -143,11 +209,15 @@ IEnumerator IEnumerable.GetEnumerator() void SetVisibleRegion(MapSpan? visibleRegion) { - if (visibleRegion == null) + if (visibleRegion is null) + { throw new ArgumentNullException(nameof(visibleRegion)); + } if (_visibleRegion == visibleRegion) + { return; + } OnPropertyChanging(nameof(VisibleRegion)); _visibleRegion = visibleRegion; @@ -156,15 +226,18 @@ void SetVisibleRegion(MapSpan? visibleRegion) void PinsOnCollectionChanged(object? sender, NotifyCollectionChangedEventArgs e) { - if (e.NewItems != null && e.NewItems.Cast().Any(pin => pin.Label == null)) + if (e.NewItems is not null && e.NewItems.Cast().Any(pin => pin.Label is null)) + { throw new ArgumentException("Pin must have a Label to be added to a map"); + } + Handler?.UpdateValue(nameof(IMap.Pins)); } void MapElementsCollectionChanged(object? sender, NotifyCollectionChangedEventArgs e) { Handler?.UpdateValue(nameof(IMap.Elements)); - if (e.NewItems != null) + if (e.NewItems is not null) { foreach (MapElement item in e.NewItems) { @@ -172,7 +245,7 @@ void MapElementsCollectionChanged(object? sender, NotifyCollectionChangedEventAr } } - if (e.OldItems != null) + if (e.OldItems is not null) { foreach (MapElement item in e.OldItems) { @@ -237,7 +310,7 @@ void OnItemsSourceCollectionChanged(object? sender, NotifyCollectionChangedEvent void CreatePinItems() { - if (ItemsSource == null || (ItemTemplate == null && ItemTemplateSelector == null)) + if (ItemsSource is null || (ItemTemplate is null && ItemTemplateSelector is null)) { return; } @@ -253,11 +326,15 @@ void CreatePinItems() void CreatePin(object newItem) { DataTemplate? itemTemplate = ItemTemplate; - if (itemTemplate == null) + if (itemTemplate is null) + { itemTemplate = ItemTemplateSelector?.SelectTemplate(newItem, this); + } - if (itemTemplate == null) + if (itemTemplate is null) + { return; + } var pin = (Pin)itemTemplate.CreateContent(); pin.BindingContext = newItem; @@ -271,7 +348,7 @@ void RemovePin(object itemToRemove) for (int i = 0; i < _pins.Count; ++i) { Pin? pin = _pins[i] as Pin; - if (pin != null) + if (pin is not null) { if (pin.BindingContext?.Equals(itemToRemove) == true) { diff --git a/src/Controls/Maps/src/MapElement.cs b/src/Controls/Maps/src/MapElement.cs index 6ee336248420..cae15100821e 100644 --- a/src/Controls/Maps/src/MapElement.cs +++ b/src/Controls/Maps/src/MapElement.cs @@ -27,7 +27,7 @@ public partial class MapElement : Element 5f); /// - /// Gets or sets the stroke color. + /// Gets or sets the stroke color. This is a bindable property. /// public Color StrokeColor { @@ -36,7 +36,8 @@ public Color StrokeColor } /// - /// Gets or sets the stroke width. + /// Gets or sets the stroke width. The default value is 5f. + /// This is a bindable property. /// public float StrokeWidth { diff --git a/src/Controls/Maps/src/Polygon.cs b/src/Controls/Maps/src/Polygon.cs index 3305caedc4f2..99eabdd222d5 100644 --- a/src/Controls/Maps/src/Polygon.cs +++ b/src/Controls/Maps/src/Polygon.cs @@ -18,7 +18,7 @@ public partial class Polygon : MapElement default(Color)); /// - /// Gets or sets the fill color. + /// Gets or sets the fill color. This is a bindable property. /// public Color FillColor { From 8500b109630b5f36b3a1f31eefbaf0ac98faab7f Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Wed, 28 Feb 2024 16:29:33 +0100 Subject: [PATCH 3/4] And more --- .../Maps/src/AppHostBuilderExtensions.cs | 3 + .../Maps/src/HandlerImpl/Circle.Impl.cs | 1 + src/Controls/Maps/src/HandlerImpl/Map.Impl.cs | 3 + .../Maps/src/HandlerImpl/Polygon.Impl.cs | 58 ++++++++++++++++++- .../Maps/src/HandlerImpl/Polyline.Impl.cs | 54 +++++++++++++++++ src/Controls/Maps/src/Pin.cs | 3 +- src/Core/maps/src/Core/ICircleMapElement.cs | 8 +++ src/Core/maps/src/Core/IFilledMapElement.cs | 6 ++ src/Core/maps/src/Core/IMapElement.cs | 6 ++ 9 files changed, 139 insertions(+), 3 deletions(-) diff --git a/src/Controls/Maps/src/AppHostBuilderExtensions.cs b/src/Controls/Maps/src/AppHostBuilderExtensions.cs index d3a1fb94eb49..ab52e85cbbe5 100644 --- a/src/Controls/Maps/src/AppHostBuilderExtensions.cs +++ b/src/Controls/Maps/src/AppHostBuilderExtensions.cs @@ -14,6 +14,9 @@ namespace Microsoft.Maui.Controls.Hosting { + /// + /// This class contains the Map's extensions. + /// public static partial class AppHostBuilderExtensions { /// diff --git a/src/Controls/Maps/src/HandlerImpl/Circle.Impl.cs b/src/Controls/Maps/src/HandlerImpl/Circle.Impl.cs index b0484d66dee8..59f2556b8c64 100644 --- a/src/Controls/Maps/src/HandlerImpl/Circle.Impl.cs +++ b/src/Controls/Maps/src/HandlerImpl/Circle.Impl.cs @@ -5,6 +5,7 @@ namespace Microsoft.Maui.Controls.Maps { public partial class Circle : ICircleMapElement { + /// public Paint? Fill => FillColor?.AsPaint(); } } diff --git a/src/Controls/Maps/src/HandlerImpl/Map.Impl.cs b/src/Controls/Maps/src/HandlerImpl/Map.Impl.cs index cf04a6d9d02a..ad58fdd756ec 100644 --- a/src/Controls/Maps/src/HandlerImpl/Map.Impl.cs +++ b/src/Controls/Maps/src/HandlerImpl/Map.Impl.cs @@ -26,6 +26,9 @@ public partial class Map : IMap, IEnumerable } + /// + /// Raised when the handler for this map control changed. + /// protected override void OnHandlerChanged() { base.OnHandlerChanged(); diff --git a/src/Controls/Maps/src/HandlerImpl/Polygon.Impl.cs b/src/Controls/Maps/src/HandlerImpl/Polygon.Impl.cs index 00900bb67401..fd01fb38b19b 100644 --- a/src/Controls/Maps/src/HandlerImpl/Polygon.Impl.cs +++ b/src/Controls/Maps/src/HandlerImpl/Polygon.Impl.cs @@ -10,8 +10,14 @@ namespace Microsoft.Maui.Controls.Maps { public partial class Polygon : IGeoPathMapElement, IFilledMapElement { + /// public Paint? Fill => FillColor?.AsPaint(); + /// + /// Gets or sets the location object at the specified index. + /// + /// The index of the location object to return or set. + /// The location object at the specified index. public Location this[int index] { get { return Geopath[index]; } @@ -22,10 +28,21 @@ public partial class Polygon : IGeoPathMapElement, IFilledMapElement } } + /// + /// Gets the location object count in this polygon. + /// public int Count => Geopath.Count; + /// + /// Gets whether this polygon is read-only. + /// + /// Always returns . public bool IsReadOnly => false; + /// + /// Adds a location to this polygon. + /// + /// The location to add. public void Add(Location item) { var index = Geopath.Count; @@ -33,39 +50,72 @@ public void Add(Location item) NotifyHandler(nameof(Add), index, item); } + /// + /// Clears all locations that make up this polygon. + /// public void Clear() { for (int i = Geopath.Count - 1; i >= 0; i--) + { RemoveAt(i); + } } + /// + /// Returns whether the specified location is contained in this polygon. + /// + /// The location object of which to determine if it is contained in the location collection of this polygon. + /// if is contained in the location collection of this polygon, otherwise . public bool Contains(Location item) { return Geopath.Contains(item); } + /// + /// Copies the child locations to the specified array. + /// + /// The target array to copy the child views to. + /// The index at which the copying needs to start. public void CopyTo(Location[] array, int arrayIndex) { Geopath.CopyTo(array, arrayIndex); } + /// + /// Returns an enumerator that lists all of the location object in this polygon. + /// + /// A of type with all the locations in this polygon. public IEnumerator GetEnumerator() { return Geopath.GetEnumerator(); } - + + /// + /// Gets the index of a specified location object. + /// + /// The location object of which to determine the index. + /// The index of the specified location, if the location was not found this will return -1. public int IndexOf(Location item) { return Geopath.IndexOf(item); } + /// + /// Inserts a location object at the specified index. + /// + /// The index at which to specify the location object. + /// The location object to insert. public void Insert(int index, Location item) { Geopath.Insert(index, item); NotifyHandler(nameof(Insert), index, item); - } + /// + /// Removes a location object from this polygon. + /// + /// The location object to remove. + /// if the location was removed successfully, otherwise . public bool Remove(Location item) { var index = Geopath.IndexOf(item); @@ -74,6 +124,10 @@ public bool Remove(Location item) return result; } + /// + /// Removes a location object at the specified index. + /// + /// The index at which to remove the location. public void RemoveAt(int index) { var item = Geopath[index]; diff --git a/src/Controls/Maps/src/HandlerImpl/Polyline.Impl.cs b/src/Controls/Maps/src/HandlerImpl/Polyline.Impl.cs index d84004f09b62..f1b9483eb60f 100644 --- a/src/Controls/Maps/src/HandlerImpl/Polyline.Impl.cs +++ b/src/Controls/Maps/src/HandlerImpl/Polyline.Impl.cs @@ -11,6 +11,11 @@ namespace Microsoft.Maui.Controls.Maps { public partial class Polyline : IGeoPathMapElement { + /// + /// Gets or sets the location object at the specified index. + /// + /// The index of the location object to return or set. + /// The location object at the specified index. public Location this[int index] { get { return Geopath[index]; } @@ -21,10 +26,21 @@ public partial class Polyline : IGeoPathMapElement } } + /// + /// Gets the location object count in this polyline. + /// public int Count => Geopath.Count; + /// + /// Gets whether this polyline is read-only. + /// + /// Always returns . public bool IsReadOnly => false; + /// + /// Adds a location to this polyline. + /// + /// The location to add. public void Add(Location item) { var index = Geopath.Count; @@ -32,32 +48,61 @@ public void Add(Location item) NotifyHandler(nameof(Add), index, item); } + /// + /// Clears all locations that make up this polyline. + /// public void Clear() { for (int i = Geopath.Count - 1; i >= 0; i--) + { RemoveAt(i); + } } + /// + /// Returns whether the specified location is contained in this polyline. + /// + /// The location object of which to determine if it is contained in the location collection of this polyline. + /// if is contained in the location collection of this polyline, otherwise . public bool Contains(Location item) { return Geopath.Contains(item); } + /// + /// Copies the child locations to the specified array. + /// + /// The target array to copy the child views to. + /// The index at which the copying needs to start. public void CopyTo(Location[] array, int arrayIndex) { Geopath.CopyTo(array, arrayIndex); } + /// + /// Returns an enumerator that lists all of the location object in this polyline. + /// + /// A of type with all the locations in this polyline. public IEnumerator GetEnumerator() { return Geopath.GetEnumerator(); } + /// + /// Gets the index of a specified location object. + /// + /// The location object of which to determine the index. + /// The index of the specified location, if the location was not found this will return -1. public int IndexOf(Location item) { return Geopath.IndexOf(item); } + /// + /// Inserts a location object at the specified index. + /// + /// The index at which to specify the location object. + /// The location object to insert. public void Insert(int index, Location item) { Geopath.Insert(index, item); @@ -65,6 +110,11 @@ public void Insert(int index, Location item) } + /// + /// Removes a location object from this polyline. + /// + /// The location object to remove. + /// if the location was removed successfully, otherwise . public bool Remove(Location item) { var index = Geopath.IndexOf(item); @@ -73,6 +123,10 @@ public bool Remove(Location item) return result; } + /// + /// Removes a location object at the specified index. + /// + /// The index at which to remove the location. public void RemoveAt(int index) { var item = Geopath[index]; diff --git a/src/Controls/Maps/src/Pin.cs b/src/Controls/Maps/src/Pin.cs index 2f2322bbcc92..0dfb99b54426 100644 --- a/src/Controls/Maps/src/Pin.cs +++ b/src/Controls/Maps/src/Pin.cs @@ -45,7 +45,8 @@ public Location Location } /// - /// Gets or sets the kind of pin. + /// Gets or sets the kind of pin. The default value is . + /// This is a bindable property. /// /// Depending on the platform, and versions of the platform, this might change the visual representation. This varies between the different platforms. public PinType Type diff --git a/src/Core/maps/src/Core/ICircleMapElement.cs b/src/Core/maps/src/Core/ICircleMapElement.cs index 10eb38514823..c1c44f09c919 100644 --- a/src/Core/maps/src/Core/ICircleMapElement.cs +++ b/src/Core/maps/src/Core/ICircleMapElement.cs @@ -2,9 +2,17 @@ namespace Microsoft.Maui.Maps { + /// + /// Represents a visual element on the map control shaped like a circle. + /// public interface ICircleMapElement : IMapElement, IFilledMapElement { + /// + /// Gets the center location. + /// Location Center { get; } + + Distance Radius { get; } } } diff --git a/src/Core/maps/src/Core/IFilledMapElement.cs b/src/Core/maps/src/Core/IFilledMapElement.cs index 25c64296cdc8..47e2bba1b22b 100644 --- a/src/Core/maps/src/Core/IFilledMapElement.cs +++ b/src/Core/maps/src/Core/IFilledMapElement.cs @@ -2,8 +2,14 @@ namespace Microsoft.Maui.Maps { + /// + /// Represents a visual element on the map control that has a fill color. + /// public interface IFilledMapElement : IMapElement { + /// + /// Gets the fill color. + /// Paint? Fill { get; } } } diff --git a/src/Core/maps/src/Core/IMapElement.cs b/src/Core/maps/src/Core/IMapElement.cs index 3acaad1dcbc1..410212180df5 100644 --- a/src/Core/maps/src/Core/IMapElement.cs +++ b/src/Core/maps/src/Core/IMapElement.cs @@ -1,7 +1,13 @@ namespace Microsoft.Maui.Maps { + /// + /// Represents an element that can be added to the map control. + /// public interface IMapElement : IElement, IStroke { + /// + /// Gets or sets the platform counterpart of this map element. + /// object? MapElementId { get; set; } } } From 72d74f2fb22957456db8c5bea249ef683402d9bb Mon Sep 17 00:00:00 2001 From: Gerald Versluis Date: Wed, 28 Feb 2024 20:32:32 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Juan Diego Herrera --- src/Controls/Maps/src/Map.cs | 8 ++++---- src/Controls/Maps/src/MapElement.cs | 2 +- src/Controls/Maps/src/Pin.cs | 4 ++-- src/Core/maps/src/Core/ICircleMapElement.cs | 4 +++- 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/src/Controls/Maps/src/Map.cs b/src/Controls/Maps/src/Map.cs index 2b75cda93ee6..52875e5650ad 100644 --- a/src/Controls/Maps/src/Map.cs +++ b/src/Controls/Maps/src/Map.cs @@ -71,7 +71,7 @@ public Map() : this(new MapSpan(new Devices.Sensors.Location(20.793062527, -156. } /// - /// Gets or sets if scrolling by user input is enabled. Default value is . + /// Gets or sets a value that indicates if scrolling by user input is enabled. Default value is . /// This is a bindable property. /// public bool IsScrollEnabled @@ -81,7 +81,7 @@ public bool IsScrollEnabled } /// - /// Gets or sets if zooming by user input is enabled. Default value is . + /// Gets or sets a value that indicates if zooming by user input is enabled. Default value is . /// This is a bindable property. /// public bool IsZoomEnabled @@ -91,7 +91,7 @@ public bool IsZoomEnabled } /// - /// Gets or sets if the map shows an indicator of the current position of this device. Default value is + /// Gets or sets a value that indicates if the map shows an indicator of the current position of this device. Default value is /// This is a bindable property. /// /// Depending on the platform it is likely that runtime permission(s) need to be requested to determine the current location of the device. @@ -102,7 +102,7 @@ public bool IsShowingUser } /// - /// Gets or sets if the map shows current traffic information. Default value is . + /// Gets or sets a value that indicates if the map shows current traffic information. Default value is . /// This is a bindable property. /// public bool IsTrafficEnabled diff --git a/src/Controls/Maps/src/MapElement.cs b/src/Controls/Maps/src/MapElement.cs index cae15100821e..6d469f7de041 100644 --- a/src/Controls/Maps/src/MapElement.cs +++ b/src/Controls/Maps/src/MapElement.cs @@ -8,7 +8,7 @@ namespace Microsoft.Maui.Controls.Maps { /// - /// Represents an element which is visually drawn on the map control. + /// Represents an element which is visually drawn on the control. /// public partial class MapElement : Element { diff --git a/src/Controls/Maps/src/Pin.cs b/src/Controls/Maps/src/Pin.cs index 0dfb99b54426..c0a32e27b602 100644 --- a/src/Controls/Maps/src/Pin.cs +++ b/src/Controls/Maps/src/Pin.cs @@ -6,7 +6,7 @@ namespace Microsoft.Maui.Controls.Maps { /// - /// Represents a pin on the map control. + /// Represents a pin on the control. /// public partial class Pin : Element { @@ -120,7 +120,7 @@ public override int GetHashCode() } /// - /// Equality operator for equals. + /// Equality operator for equals. /// /// Left to compare. /// Right to compare. diff --git a/src/Core/maps/src/Core/ICircleMapElement.cs b/src/Core/maps/src/Core/ICircleMapElement.cs index c1c44f09c919..314f9cc3bebc 100644 --- a/src/Core/maps/src/Core/ICircleMapElement.cs +++ b/src/Core/maps/src/Core/ICircleMapElement.cs @@ -12,7 +12,9 @@ public interface ICircleMapElement : IMapElement, IFilledMapElement /// Location Center { get; } - + /// + /// Gets the radius. + /// Distance Radius { get; } } }