diff options
| author | Nadia Barbosa <nadiabarbosa@me.com> | 2018-08-02 13:42:35 -0700 |
|---|---|---|
| committer | Nadia Barbosa <captainbarbosa@users.noreply.github.com> | 2018-08-14 16:38:38 -0700 |
| commit | 4b9ed3837a68dd49286711049c1f07be7bbcab04 (patch) | |
| tree | 972c8dec541b24f076a2ce6b55315b485c91a70b | |
| parent | 20f880ebec82bbd7553fc382400227efc0105bce (diff) | |
| download | qtlocation-mapboxgl-4b9ed3837a68dd49286711049c1f07be7bbcab04.tar.gz | |
[ios] Remove duplicated guides
19 files changed, 4 insertions, 219 deletions
diff --git a/platform/ios/docs/guides/Adding Markers to a Map.md b/platform/ios/docs/guides/Adding Markers to a Map.md deleted file mode 100644 index b33b536d44..0000000000 --- a/platform/ios/docs/guides/Adding Markers to a Map.md +++ /dev/null @@ -1,62 +0,0 @@ -# Adding Markers to a Map - -Mapbox offers a few different ways to add markers to a map, each with different tradeoffs. Below is an overview of the variety of approaches that can be used. - -## **Annotations API** - -Our annotations API includes the `MGLAnnotationImage`, and `MGLAnnotationView` classes. These are most similar to MapKit’s annotation class and provide a familiar interface for working with markers and callouts. - -| <img src="img/adding-points-to-a-map/annotation-image.png" alt="MGLAnnotationImage" style="height: 500px;"/> | <img src="img/adding-points-to-a-map/annotation-view.png" alt="MGLAnnotationView" style="height: 500px;"/> | -|----------------------|---------------------| -| `MGLAnnotationImage` | `MGLAnnotationView` | - -**MGLAnnotationImage** is an annotation class that is easily customizable with any `UIImage`. -It is highly performant, as the images are rendered directly using OpenGL. However, if you need to animate your annotations or control z-layer ordering, consider working with **MGLAnnotationView** which supports any animation that can be applied to a `UIView`. View hierarchy can be manipulated by using instance methods available on `UIView` such as `-[UIView bringSubviewToFront:]`. - -**MGLAnnotationView** is an annotation class that is an easily customizable `UIView`. Use this class if you need your markers to be dynamic or animated. `MGLAnnotationView` has a significant advantage over `MGLAnnotationImage` when you need every annotation to be unique. For example, annotation views are ideal for showing user locations on a map using high-resolution profile pictures. However, the map can slow down when many annotation views are visible at the same time, so if you need to add a very large number of markers, consider using our runtime styling APIs instead. - -Both `MGLAnnotationImage` and `MGLAnnotationView` can become interactive by adding a [few lines of code](https://www.mapbox.com/ios-sdk/examples/marker/). When the user taps an annotation, the annotation’s name appears in a basic callout. An annotation view can additionally respond to [drag-and-drop gestures](https://www.mapbox.com/ios-sdk/examples/draggable-views/). - -## **Runtime styling API** - -For full control of how markers are displayed on a map, consider using our [runtime styling](runtime-styling.html) APIs. Like `MGLAnnotationImage`, it is a performant approach to adding markers because they rendered directly using OpenGL. However, the runtime styling APIs also provide support for rendering labels together with icons, finer control of z-ordering, and clustering, so consider using this set of APIs if you need to display a large amount of highly customizable markers. - -Our runtime styling API is the most powerful option if you need to create rich data visualizations within in your map, but it is the most complex and has a steeper learning curve than our annotations API. - -The runtime styling API includes our `MGLSymbolStyleLayer` and `MGLCircleStyleLayer` classes that can be used to dynamically display on markers on map when used in conjunction with either an `MGLVectorSource` or an `MGLShapeSource`. - -If you need to implement callouts with the `MGLSymbolStyleLayer` or `MGLCircleStyleLayer`, you will need to implement your own tap gesture recognizer that calls `-[MGLMapView visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:]` to get the tapped point feature, then show a `UIView` you provide. Additionally, if you need to animate markers when using the runtime styling APIs, consider using a timer to update the source data coordinates accordingly. - -| <img src="img/adding-points-to-a-map/circle-layer.png" alt="MGLCircleStyleLayer" style="height: 500px;"/> | <img src="img/adding-points-to-a-map/symbol-layer.png" alt="MGLSymbolStyleLayer" style="height: 500px;"/> | -|----------------------|---------------------| -| `MGLCircleStyleLayer` | `MGLSymbolStyleLayer` | - -The **MGLCircleStyleLayer** class is the style layer class responsible for displaying the source’s point features as circle-shaped markers. You can specify circle fill and outline colors, as well as size. You can also dynamically change the circle’s styling properties based on any attributes your source data contains. - -The **MGLSymbolStyleLayer** class is the style layer class responsible for displaying the source’s point features as icons and labels. You can use custom images as icons and also combine text labels, placing them exactly where you specify. You can also dynamically change the symbol’s styling properties based on any attributes your source data contains. - -Still undecided on which approach will work best for your use case? [Reach out to our support team](https://www.mapbox.com/contact/). - -See the table below for a summary of APIs that can be used to add markers to a map: - -✅ Recommended - -⚠️ Supported with caveats - -➖ Unavailable or not supported - - -| Feature | MGLAnnotationView | MGLAnnotationImage | MGLSymbolStyleLayer | MGLCircleStyleLayer | -|----------------------------------------------------|--------------------------------------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------| -| Customizability | ✅ Text labels, interactive subviews | ⚠️ Static images only | ✅ Full support for text labels and label placement | ✅Customize circle color and outline | -| Borrows familiar concepts from | MapKit, Google Maps SDK | ➖ | Mapbox GL JS, Mapbox Studio | Mapbox GL JS, Mapbox Studio | -| Can use images | ✅ | ✅ | ✅ | ➖ | -| Can use text | ✅ | ➖ | ✅ | ➖ | -| Control Z-index | ✅ | ➖ | ⚠️ Add multiple layers at, above, or below a specified layer index to control ordering | ⚠️ Add multiple layers at, above, or below a specified layer index to control ordering | -| Drag and drop | ✅ | ➖ | ➖ | ➖ | -| Core Animation support | ✅ | ➖ | ➖ | ➖ | -| Add/move/replace data | ✅ | ✅ | ⚠️ Partial data updates are less performant than using annotations | ⚠️ Partial data updates are less performant than using annotations | -| SceneKit support | ✅ | ➖ | ➖ | ➖ | -| Can be dynamically styled based on data attributes | ✅ Subclass `MGLPointAnnotation` to add custom attributes | ✅ Subclass `MGLPointAnnotation` to add custom attributes | ✅ | ✅ | -| Supports callouts | ✅ Built-in callouts included | ✅ Built-in callouts included | ⚠️ Implement your own gesture recognizer that uses feature querying, then create custom UIViews to mimic native callouts | ⚠️ Implement your own gesture recognizer that uses feature querying, then create custom UIViews to mimic native callouts | -| Supports clustering | ⚠️ Use a [third-party plugin](https://github.com/hulab/ClusterKit/) | ➖ | ✅ | ✅ | diff --git a/platform/ios/docs/guides/For Style Authors.md b/platform/ios/docs/guides/For Style Authors.md index 24a2f7d3a4..9d240045b3 100644 --- a/platform/ios/docs/guides/For Style Authors.md +++ b/platform/ios/docs/guides/For Style Authors.md @@ -41,7 +41,7 @@ Studio, especially when multitasking is enabled. Your user’s viewing distance may be shorter than on a desktop computer. Some of your users may use the Larger Dynamic Type and Accessibility Text features to increase the size of all text on the device. You can use the -[runtime styling API](#manipulating-the-style-at-runtime) to adjust your style’s +[runtime styling API](https://www.mapbox.com/ios-sdk/maps/overview/runtime-styling/) to adjust your style’s font and icon sizes accordingly. Design sprite images and choose font weights that look crisp on both @@ -98,7 +98,7 @@ represented at runtime by an `MGLStyle` object, which provides access to various `MGLSource` and `MGLStyleLayer` objects that represent content sources and style layers, respectively. For more information about the capabilities exposed by the runtime styling API, -see “[Runtime Styling](runtime-styling.html)”. +see “[Runtime Styling](https://www.mapbox.com/ios-sdk/maps/overview/runtime-styling/)”. The names of runtime styling classes and properties on iOS are generally consistent with the style specification and Mapbox Studio’s Styles editor. Any diff --git a/platform/ios/docs/guides/Migrating to Expressions.md b/platform/ios/docs/guides/Migrating to Expressions.md index 96d4df6853..b0965ee999 100644 --- a/platform/ios/docs/guides/Migrating to Expressions.md +++ b/platform/ios/docs/guides/Migrating to Expressions.md @@ -5,7 +5,7 @@ # Migrating from Style Functions to Expressions -[Runtime Styling](runtime-styling.html) enables you to modify every aspect of the map’s appearance dynamically as a user interacts with your application. Developers can specify in advance how a layout or paint attribute will vary as the zoom level changes or how the appearance of individual features vary based on metadata provided by a content source. +[Runtime Styling](https://www.mapbox.com/ios-sdk/maps/overview/runtime-styling/) enables you to modify every aspect of the map’s appearance dynamically as a user interacts with your application. Developers can specify in advance how a layout or paint attribute will vary as the zoom level changes or how the appearance of individual features vary based on metadata provided by a content source. With Mapbox Maps SDK for iOS v4.0.0, style functions have been replaced with expressions. These provide even more tools for developers who want to style their maps dynamically. This guide outlines some tips for migrating from style functions to expressions, and offers an overview of some things that developers can do with expressions. @@ -113,7 +113,7 @@ mapView.style?.insertLayer(layer, below: symbolLayer) If you previously used an interpolation base greater than `0` (other than `1`), you can use `MGLExpressionInterpolationMode.exponential` as the curve type for `+[NSExpression(MGLAdditions) mgl_expressionForInterpolatingExpression:withCurveType:parameters:stops:]` or `'exponential'` as the curve type for [`mgl_interpolate:withCurveType:parameters:stops:`](predicates-and-expressions.html#code-mgl_interpolate-withcurvetype-parameters-stops-code). The `parameters` argument takes that interpolation base. This interpolates between values exponentially, creating an accelerated ramp effect. -Here’s a visualization from Mapbox Studio (see [Working with Mapbox Studio](working-with-mapbox-studio.html)) comparing interpolation base values of `1.5` and `0.5` based on zoom. In order to convert camera style functions, use `$zoomLevel` or `MGL_FUNCTION('zoomLevel')` as the attribute key. +Here’s a visualization from Mapbox Studio (see [Working with Mapbox Studio](https://www.mapbox.com/ios-sdk/maps/overview/mapbox-studio/)) comparing interpolation base values of `1.5` and `0.5` based on zoom. In order to convert camera style functions, use `$zoomLevel` or `MGL_FUNCTION('zoomLevel')` as the attribute key. <img src="img/data-driven-styling/exponential-function.png" height=344/> <img src="img/data-driven-styling/exponential-function-1.png" height=344/> diff --git a/platform/ios/docs/guides/Runtime Styling.md b/platform/ios/docs/guides/Runtime Styling.md deleted file mode 100644 index 194d8b3bdd..0000000000 --- a/platform/ios/docs/guides/Runtime Styling.md +++ /dev/null @@ -1,57 +0,0 @@ -# Runtime Styling - -Mapbox’s runtime styling features allow you direct control over every layer in your maps with code. It’s now possible to create dynamic maps and visualizations that aren’t possible with other mobile maps SDKs. - -Runtime styling expands upon the design power of [Mapbox Studio](https://www.mapbox.com/mapbox-studio/) and exposes all of the same properties and attributes directly to mobile developers in our SDK. - -Beyond the custom styled maps that you can create with Mapbox Studio, you can now change the look and feel of your map on the fly having maps in your app visually respond to user interaction or or context. Or leverage the power of OpenGL for highly performant and complex data visualizations. Now it’s possible to mix in your own data and bring your map to life. - -## Example use cases - -As an example of what’s possible with runtime styling, consider some of the following use cases: - -### Styling maps on the fly - -At runtime, you can tailor the map specifically to your user interface. Tweak colors, text, and icons to match the style to your brand. - - - -For maps that aren’t going to change in response to custom data or user interaction, consider creating a custom map style with [Mapbox Studio](https://www.mapbox.com/mapbox-studio/). - -### Map interactivity - -You can customize the map to the point of having it respond dynamically based on the actions your users are taking. Increase the text size of streets while a user is driving, emphasize points of interest tailored to a user’s preferences, or change your UI if users are at parks, trails, landmarks, or rivers. - - - -### Powerful data visualization - -Mapbox maps are built on top of OpenGL and can support rendering data without the traditional overhead of `UIView`-based map annotations. - -Mapbox can support data visualizations that were slow or impossible with traditional map SDKs. Render heatmaps, visualize population density, or even go so far as updating the snow levels in the mountains to match recent snowfall. - - - - - -### Powerful annotations - -The Mapbox SDK gives you access to all of the same tools we use to render our default map styles. Instead of using generic pin markers, enrich your place data or custom polygons with icons and labels that make your maps stand out. - - - -### Custom shapes - -Draw custom shapes on the map the same way you would a custom `UIView` or `CALayer`. These shapes keep their geographic scale and are perfect for visualizing everything from indoor floor plans to metro systems to hurricane tracks. - -## Next steps - -Check out the [iOS code examples](https://www.mapbox.com/ios-sdk/examples/runtime-toggle-layer/) to learn more about how to use runtime styling in your own apps. - -## Resources - -* [Information for style authors](for-style-authors.html) -* [Mapbox Streets source reference](https://www.mapbox.com/vector-tiles/mapbox-streets-v7/) -* [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/) -* [Mapbox Studio](https://www.mapbox.com/mapbox-studio/) -* [iOS code examples](https://www.mapbox.com/ios-sdk/examples/) diff --git a/platform/ios/docs/guides/Working with Mapbox Studio.md b/platform/ios/docs/guides/Working with Mapbox Studio.md deleted file mode 100644 index 232b165efd..0000000000 --- a/platform/ios/docs/guides/Working with Mapbox Studio.md +++ /dev/null @@ -1,96 +0,0 @@ -# Working with Mapbox Studio - -[Mapbox Studio’s Styles editor](http://mapbox.com/studio) is Mapbox’s tool for creating custom map styles. It also serves as an excellent tool for rapidly prototyping dynamic maps and [runtime styling](runtime-styling.html) interactions for iOS. - -## Creating a base style - -Start by heading to [mapbox.com/studio](https://www.mapbox.com/studio) and creating a new style. Any style that’s close to what you’ll be using in your app is ideal. - -## Prototyping with data - -The goal in using Mapbox Studio for prototyping runtime styling implementations is to test data presentation assumptions as quickly as possible. With the Mapbox Studio tools, you can import a small subset of your own real data, fake data as a placeholder, or prototype with existing Mapbox data. - -### Prototyping with Mapbox data -The default [Mapbox Streets tileset](https://www.mapbox.com/studio/tilesets/mapbox.mapbox-streets-v7/) might offer data similar to your own that you can use to style before you swap in your own data at runtime. - -For example, if you’re looking to prototype points of interest, consider the `poi_label` layer; if you want to style GPS traces, the `roads` layer might be a good proxy. Take a look at what’s available in [Mapbox Streets](https://www.mapbox.com/studio/tilesets/mapbox.mapbox-streets-v7/): there’s probably a layer that closely matches your data. - -### Importing real data -If you can’t find a good approximation for your data in Mapbox Streets, consider uploading a small subset of your data into Mapbox Studio as a custom tileset. - -From the [Mapbox Studio Dashboard](https://www.mapbox.com/studio/), click `Tilesets` in the sidebar, then click `New Tileset` to get started with most common geo file formats including KML, GPX, GeoJSON, Shapefiles, and CSV. - -### Faking placeholder data -If you don’t have any custom data on hand in a format that works easily with the Tileset importer, you can fake placeholder data with the Dataset Editor. - -From the [Mapbox Studio Dashboard](https://www.mapbox.com/studio/), click `Datasets` in the sidebar, then click on `New Dataset` to get started. - -Zoom into your desired location and use the draw tools on the left to start creating a set of sample data. - - - -Next, add data properties you’d like to use to drive your style. Consider categorical properties or numeric properties that you’d use to filter and group your data. Text properties can be used to display icons or labels. - - - -**General Guidelines:** - -* Text along a line: add line with a text property -* Text at specific points on a line or polygon: in addition to the line, create points at the specific points you’d like with text properties -* If you want circles where scale doesn’t matter relative to the geography (e.g. always 20 pixels), you can add as a point and style with a circle layer or a symbol -* If you want circles or arcs where the scale matters (e.g. 10 mile radius), you’ll need to approximately freehand a polygon that you can create more precisely later in code. - -When you’re done, save your dataset and export as a tileset. When that’s complete, add your tileset to your style. - -### Import into your style - -1. Click `New Layer` -2. Select your tileset -3. Select your shape type: - * `Symbol`: best for text and icons - * `Line`: best for lines or adding strokes to polygons - * `Fill`: best for filling polygons - * `Circle`: for styling points or nodes along a line or polygon as circles. If you need circles of a fixed radius (e.g. 1 mile radius), you should model your data as a polygon. -4. Add filters if necessary - * You can selectively filter your data by their properties to group and style separately -5. Click on `Create Layer` - -## Styling with Mapbox Studio - -Mapbox Studio shines for styling your data and the process is much faster than attempting to style natively. - -There are some nuances to understand between the different layer types and how they work together. Don’t be afraid to use the layers sidebar to peek into the techniques used to style the stock Mapbox maps. You can duplicate these layers, re-point the source to your own data, and tweak as needed. - -**Best Practices:** - -* Layers are cheap, so duplicate and update filters liberally. -* If you’d like to stroke polygons you’ll need to use two layers: one a fill and one a stroked line. -* If you want to stroke a line, create two layers, one for the default stroke and one with a wider width for its casing -* If you intend to animate properties or transition between values, consider creating separate layers for each state and toggling visibility to visualize the difference. - -## Implement on iOS with runtime styling - -Once you’re happy with the styles you’ve created, it’s time to [get setup with Mapbox in your app](https://www.mapbox.com/ios-sdk/). - -To implement your prototypes with runtime styling: - -1. Implement `-[MGLMapViewDelegate mapView:didFinishLoadingStyle:]`. -2. Add your real data as a source: - * This can be done using vector data from tileset editor ([example](https://www.mapbox.com/ios-sdk/examples/dds-circle-layer)), custom vector tiles, added as GeoJSON ([example](https://www.mapbox.com/ios-sdk/examples/runtime-add-line), or added manually through the app via `MGLShapeSource` ([example](https://www.mapbox.com/ios-sdk/examples/runtime-multiple-annotations)) -3. For each layer you’ve prototyped in Studio, add its corresponding `MGLStyleLayer` subclass. See [“Configuring the map content’s appearance”](for-style-authors.html#configuring-the-map-content-s-appearance) for the available style layer classes. - -**Translating style attributes from Studio** -For each property you’ve edited in Studio, you can hover over the property name to find the corresponding property in the iOS SDK. It’ll generally be the camelCased version of the Property ID, but see [“Configuring the map content’s appearance”](for-style-authors.html#configuring-the-map-content-s-appearance) for a table of properties that differ between Mapbox Studio and the iOS SDK. - - - -**Translating stop functions** -It’s possible to use stop functions in Mapbox Studio to transition the style of a layer by its zoom level (e.g. a line that gets wider as you zoom in). These can be translated in the mobile SDKs using `+[MGLSyleValue valueWithInterpolationBase:stops:]`. The rate of change between stops in Studio is represented by `interpolationBase`. - - - -## Resources - -* [Mapbox Style Specification](https://www.mapbox.com/mapbox-gl-style-spec/) -* [Mapbox Studio](https://www.mapbox.com/mapbox-studio/) -* [iOS code examples](https://www.mapbox.com/ios-sdk/examples/) diff --git a/platform/ios/docs/img/adding-points-to-a-map/annotation-image.png b/platform/ios/docs/img/adding-points-to-a-map/annotation-image.png Binary files differdeleted file mode 100644 index b9aa946363..0000000000 --- a/platform/ios/docs/img/adding-points-to-a-map/annotation-image.png +++ /dev/null diff --git a/platform/ios/docs/img/adding-points-to-a-map/annotation-view.png b/platform/ios/docs/img/adding-points-to-a-map/annotation-view.png Binary files differdeleted file mode 100644 index 90c181f664..0000000000 --- a/platform/ios/docs/img/adding-points-to-a-map/annotation-view.png +++ /dev/null diff --git a/platform/ios/docs/img/adding-points-to-a-map/circle-layer.png b/platform/ios/docs/img/adding-points-to-a-map/circle-layer.png Binary files differdeleted file mode 100644 index 5edf88e0da..0000000000 --- a/platform/ios/docs/img/adding-points-to-a-map/circle-layer.png +++ /dev/null diff --git a/platform/ios/docs/img/adding-points-to-a-map/symbol-layer.png b/platform/ios/docs/img/adding-points-to-a-map/symbol-layer.png Binary files differdeleted file mode 100644 index cff39b0bce..0000000000 --- a/platform/ios/docs/img/adding-points-to-a-map/symbol-layer.png +++ /dev/null diff --git a/platform/ios/docs/img/runtime-styling/CustomAnnotations.gif b/platform/ios/docs/img/runtime-styling/CustomAnnotations.gif Binary files differdeleted file mode 100644 index 71d4c4a8a0..0000000000 --- a/platform/ios/docs/img/runtime-styling/CustomAnnotations.gif +++ /dev/null diff --git a/platform/ios/docs/img/runtime-styling/DynamicStyles.gif b/platform/ios/docs/img/runtime-styling/DynamicStyles.gif Binary files differdeleted file mode 100644 index 8854474ede..0000000000 --- a/platform/ios/docs/img/runtime-styling/DynamicStyles.gif +++ /dev/null diff --git a/platform/ios/docs/img/runtime-styling/Emoji.gif b/platform/ios/docs/img/runtime-styling/Emoji.gif Binary files differdeleted file mode 100644 index afb7a42693..0000000000 --- a/platform/ios/docs/img/runtime-styling/Emoji.gif +++ /dev/null diff --git a/platform/ios/docs/img/runtime-styling/HexBins.gif b/platform/ios/docs/img/runtime-styling/HexBins.gif Binary files differdeleted file mode 100644 index 6078ac9e8d..0000000000 --- a/platform/ios/docs/img/runtime-styling/HexBins.gif +++ /dev/null diff --git a/platform/ios/docs/img/runtime-styling/Population.gif b/platform/ios/docs/img/runtime-styling/Population.gif Binary files differdeleted file mode 100644 index 8de14e6422..0000000000 --- a/platform/ios/docs/img/runtime-styling/Population.gif +++ /dev/null diff --git a/platform/ios/docs/img/runtime-styling/SnowLevels.gif b/platform/ios/docs/img/runtime-styling/SnowLevels.gif Binary files differdeleted file mode 100644 index 463e0398d2..0000000000 --- a/platform/ios/docs/img/runtime-styling/SnowLevels.gif +++ /dev/null diff --git a/platform/ios/docs/img/studio-workflow/add-properties.gif b/platform/ios/docs/img/studio-workflow/add-properties.gif Binary files differdeleted file mode 100644 index 6cab64c050..0000000000 --- a/platform/ios/docs/img/studio-workflow/add-properties.gif +++ /dev/null diff --git a/platform/ios/docs/img/studio-workflow/create-polygons.gif b/platform/ios/docs/img/studio-workflow/create-polygons.gif Binary files differdeleted file mode 100644 index 6383dd31df..0000000000 --- a/platform/ios/docs/img/studio-workflow/create-polygons.gif +++ /dev/null diff --git a/platform/ios/docs/img/studio-workflow/property-values.png b/platform/ios/docs/img/studio-workflow/property-values.png Binary files differdeleted file mode 100644 index 2b85db80d6..0000000000 --- a/platform/ios/docs/img/studio-workflow/property-values.png +++ /dev/null diff --git a/platform/ios/docs/img/studio-workflow/stop-functions.png b/platform/ios/docs/img/studio-workflow/stop-functions.png Binary files differdeleted file mode 100644 index 8480cb2d53..0000000000 --- a/platform/ios/docs/img/studio-workflow/stop-functions.png +++ /dev/null |
