From 1254bcdb4006d87fefedfc5020b3dc7d3cd0e544 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Minh=20Nguy=E1=BB=85n?= Date: Tue, 20 Dec 2016 16:11:05 -0800 Subject: [ios, macos] Update and reformat documentation for runtime styling (#7475) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [ios, macos] Optimized changelog for runtime styling Changelog entries related to style JSON now lead off with the analogous portion of the runtime styling API. * [ios, macos] Autolink cross-class property references in docs jazzy can autolink `Class.property` references in documentation comments. * [ios, macos] Removed extra blank lines * [ios, macos] Corrected typo in MGLMultiPoint docs * [ios, macos] Rewrote shape and feature docs Rewrote documentation about MGLShape, its subclasses, and MGLFeature to emphasize runtime styling uses over annotation uses, associate each type with real-world concepts, cross-reference related style layer classes, and cross-reference related or easily confused shape classes. Links to the GeoJSON specification have been updated to RFC 7946. * [ios, macos] Expanded style layer docs With this change, documentation about style layer classes is nominally based on the documentation in the style specification. However, all the existing layer types’ documentation has been overridden to explain what the layer looks like, relate the layer to a real-world concept, and cross-reference related geometry classes. This change also corrects the description of MGLBackgroundStyleLayer, which erroneously stated that the identifier must be “background”, whereas that only happens to be true by default for Studio template styles. * [ios, macos] Wrap style layer docs * [ios, macos] Removed unused code * [ios, macos] Corrected symbol references in docs * [ios, macos] Corrected typo in abstract class exception --- platform/darwin/src/MGLShape.h | 41 +++++++++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 8 deletions(-) (limited to 'platform/darwin/src/MGLShape.h') diff --git a/platform/darwin/src/MGLShape.h b/platform/darwin/src/MGLShape.h index af815da0e9..ecb66118a1 100644 --- a/platform/darwin/src/MGLShape.h +++ b/platform/darwin/src/MGLShape.h @@ -5,11 +5,23 @@ NS_ASSUME_NONNULL_BEGIN /** - The `MGLShape` class is an abstract class that defines the basic properties for - all shape-based annotation objects. This class must be subclassed and cannot be - used as is. Subclasses are responsible for defining the geometry of the shape - and providing an appropriate value for the coordinate property inherited from - the `MGLAnnotation` protocol. + `MGLShape` is an abstract class that represents a shape or annotation. Shapes + constitute the content of a map – not only the overlays atop the map, but also + the content that forms the base map. + + You do not create instances of this class directly or create subclasses of this + class. Instead, you create instances of `MGLPointAnnotation`, + `MGLPointCollection`, `MGLPolyline`, `MGLMultiPolyline`, `MGLPolygon`, + `MGLMultiPolygon`, or `MGLShapeCollection`. The shape classes correspond to the + Geometry object + types in the GeoJSON standard, but some have nonstandard names for backwards + compatibility. + + You can add shapes to the map by adding them to an `MGLShapeSource` object. + Configure the appearance of an `MGLShapeSource`’s or `MGLVectorSource`’s shapes + collectively using a concrete instance of `MGLVectorStyleLayer`. Alternatively, + you can add some kinds of shapes directly to a map view as annotations or + overlays. */ @interface MGLShape : NSObject @@ -38,21 +50,34 @@ NS_ASSUME_NONNULL_BEGIN #pragma mark Accessing the Shape Attributes /** - The title of the shape annotation. The default value of this property is `nil`. + The title of the shape annotation. + + The default value of this property is `nil`. + + This property is ignored when the shape is used in an `MGLShapeSource`. To name + a shape used in a shape source, create an `MGLFeature` and add an attribute to + the `MGLFeature.attributes` property. */ @property (nonatomic, copy, nullable) NSString *title; /** The subtitle of the shape annotation. The default value of this property is `nil`. + + This property is ignored when the shape is used in an `MGLShapeSource`. To + provide additional information about a shape used in a shape source, create an + `MGLFeature` and add an attribute to the `MGLFeature.attributes` property. */ @property (nonatomic, copy, nullable) NSString *subtitle; #if !TARGET_OS_IPHONE /** - The tooltip of the shape annotation. The default value of this property is - `nil`. + The tooltip of the shape annotation. + + The default value of this property is `nil`. + + This property is ignored when the shape is used in an `MGLShapeSource`. */ @property (nonatomic, copy, nullable) NSString *toolTip; -- cgit v1.2.1 From 2c7569b879eb2bc9438a17226b333392052dd2db Mon Sep 17 00:00:00 2001 From: Fredrik Karlsson Date: Mon, 3 Oct 2016 11:33:38 +0200 Subject: [ios, macos] features and annotations now conforms to NSSecureCoding --- platform/darwin/src/MGLShape.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'platform/darwin/src/MGLShape.h') diff --git a/platform/darwin/src/MGLShape.h b/platform/darwin/src/MGLShape.h index ecb66118a1..4063ab39ea 100644 --- a/platform/darwin/src/MGLShape.h +++ b/platform/darwin/src/MGLShape.h @@ -23,7 +23,7 @@ NS_ASSUME_NONNULL_BEGIN you can add some kinds of shapes directly to a map view as annotations or overlays. */ -@interface MGLShape : NSObject +@interface MGLShape : NSObject #pragma mark Creating a Shape -- cgit v1.2.1 From 2a9f883239acef0dd8ed34b5dc1bf29c86858a25 Mon Sep 17 00:00:00 2001 From: Jesse Bounds Date: Sun, 8 Jan 2017 20:22:44 -0800 Subject: [ios, macos] Document that MGLShape can deserialize GeoJSON (#7638) --- platform/darwin/src/MGLShape.h | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'platform/darwin/src/MGLShape.h') diff --git a/platform/darwin/src/MGLShape.h b/platform/darwin/src/MGLShape.h index 4063ab39ea..eae5b3ae21 100644 --- a/platform/darwin/src/MGLShape.h +++ b/platform/darwin/src/MGLShape.h @@ -17,6 +17,10 @@ NS_ASSUME_NONNULL_BEGIN types in the GeoJSON standard, but some have nonstandard names for backwards compatibility. + Although you do not create instances of this class directly, you can use its + `+[MGLShape shapeWithData:encoding:error:]` factory method to create one of the + concrete subclasses of `MGLShape` noted above from GeoJSON data. + You can add shapes to the map by adding them to an `MGLShapeSource` object. Configure the appearance of an `MGLShapeSource`’s or `MGLVectorSource`’s shapes collectively using a concrete instance of `MGLVectorStyleLayer`. Alternatively, -- cgit v1.2.1 From 07496597276b977057839a1cfb3cf15e751c5dab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Minh=20Nguye=CC=82=CC=83n?= Date: Sat, 7 Jan 2017 21:48:04 -0800 Subject: [ios, macos] Added MGLShape from GeoJSON example Added an example of deserializing an MGLShape from a GeoJSON file. --- platform/darwin/src/MGLShape.h | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'platform/darwin/src/MGLShape.h') diff --git a/platform/darwin/src/MGLShape.h b/platform/darwin/src/MGLShape.h index eae5b3ae21..8dc1b4f1cf 100644 --- a/platform/darwin/src/MGLShape.h +++ b/platform/darwin/src/MGLShape.h @@ -41,6 +41,14 @@ NS_ASSUME_NONNULL_BEGIN collection object, the returned value is an instance of `MGLShapeCollectionFeature`. + ### Example + + ```swift + let url = mainBundle.url(forResource: "amsterdam", withExtension: "geojson")! + let data = try! Data(contentsOf: url) + let feature = try! MGLShape(data: data, encoding: String.Encoding.utf8.rawValue) as! MGLShapeCollectionFeature + ``` + @param data String data containing GeoJSON source code. @param encoding The encoding used by `data`. @param outError Upon return, if an error has occurred, a pointer to an -- cgit v1.2.1