summaryrefslogtreecommitdiff
path: root/platform
diff options
context:
space:
mode:
authorMinh Nguyễn <mxn@1ec5.org>2017-06-14 17:35:08 -0700
committerMinh Nguyễn <mxn@1ec5.org>2017-06-22 09:58:47 -0700
commit2a5dc2d55b759541ed7e807a7b889a283b0c8372 (patch)
treea9366fb0ce9137009ed8604561403e1b7813843d /platform
parentd3730241bbc98ec9a44295e3d3f1e7318d4cf73e (diff)
downloadqtlocation-mapboxgl-2a5dc2d55b759541ed7e807a7b889a283b0c8372.tar.gz
[ios, macos] Rewrote MGLStyle class documentation
The documentation comment now provides a high-level overview of the runtime styling API and its components, as well as the main workflow for using a style.
Diffstat (limited to 'platform')
-rw-r--r--platform/darwin/src/MGLStyle.h53
1 files changed, 45 insertions, 8 deletions
diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index 08c6c047f1..8ffd7db2b2 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -32,14 +32,51 @@ NS_ASSUME_NONNULL_BEGIN
static MGL_EXPORT const NSInteger MGLStyleDefaultVersion = 10;
/**
- The proxy object for the current map style.
-
- MGLStyle provides a set of convenience methods for changing Mapbox
- default styles using `-[MGLMapView styleURL]`.
- <a href="https://www.mapbox.com/maps/">Learn more about Mapbox default styles</a>.
-
- It is also possible to directly manipulate the current map style
- via `-[MGLMapView style]` by updating the style's data sources or layers.
+ An `MGLStyle` object represents the active map style of an `MGLMapView`. A
+ style defines both the map’s content and every aspect of its appearance. Styles
+ can be designed in
+ <a href="https://www.mapbox.com/studio/">Mapbox Studio</a> and hosted on
+ mapbox.com. `MGLStyle` provides methods for inspecting and manipulating a style
+ dynamically, with classes and properties that parallel the style JSON format
+ defined by the
+ <a href="https://www.mapbox.com/mapbox-gl-js/style-spec/">Mapbox Style Specification</a>.
+
+ You set a map view’s active style using the `MGLMapView.styleURL` property.
+ `MGLStyle` provides a set of convenience methods that return the URLs of
+ <a href="https://www.mapbox.com/maps/">popular Mapbox-designed styles</a>.
+ Once the `-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]` or
+ `-[MGLMapViewDelegate mapViewDidFinishLoadingMap:]` method is called, signaling
+ that the style has finished loading, you can use the `MGLMapView.style`
+ property to obtain the map view’s `MGLStyle`.
+
+ A style primarily consists of the following components:
+
+ * _Content sources_ supply content to be shown on the map. Use methods such as
+ `-sourceWithIdentifier:` and `-addSource:` to configure the style’s content
+ sources, which are represented by `MGLSource` objects.
+ * _Style layers_ manage the layout and appearance of content at specific
+ z-indices in the style. Most kinds of style layers display content provided
+ by a content source. Use methods such as `-layerWithIdentifier:` and
+ `-addLayer:` to configure the style’s layers, which are represented by
+ `MGLStyleLayer` objects.
+ * _Style images_ are used as icons and patterns in style layers. Use the
+ `-setImage:forName:` method to register an image as a style image.
+ (Annotations are represented by annotation images rather than style images.
+ To configure an annotation’s appearance, use the
+ `-[MGLMapViewDelegate mapView:imageForAnnotation:]` method.)
+ * The style’s _light_ is the light source affecting any 3D extruded fills.
+ Use the `light` property to configure the style’s light, which is represented
+ by an `MGLLight` object.
+
+ The `MGLStyle`, `MGLSource`, `MGLStyleLayer`, and `MGLLight` classes are
+ collectively known as the _runtime styling API_. The active style influences a
+ related API, visible feature querying, which is available through methods such
+ as `-[MGLMapView visibleFeaturesInRect:]`.
+
+ Some terminology differs between the Mapbox Style Specification and the various
+ classes associated with `MGLStyle`. Consult the
+ “[Information for Style Authors](../for-style-authors.html)” guide for an
+ overview of these differences.
@note Wait until the map style has finished loading before modifying a map's
style via any of the `MGLStyle` instance methods below. You can use the