diff --git a/platform/darwin/docs/guides/Customizing_Fonts.md b/platform/darwin/docs/guides/Customizing_Fonts.md deleted file mode 100644 index 52038c9fa..000000000 --- a/platform/darwin/docs/guides/Customizing_Fonts.md +++ /dev/null @@ -1,21 +0,0 @@ -# Customizing Fonts - -The Mapbox Maps SDK can render text that is part of an `MLNSymbolStyleLayer` in a font of your choice. The font customization options discussed in this document do not apply to user interface elements such as the scale bar or annotation callout views. - -## Server-side fonts - -By default, the map renders characters using glyphs downloaded from the [Mapbox Fonts API](https://docs.mapbox.com/api/maps/#fonts). You apply fonts in [Mapbox Studio](https://studio.mapbox.com/), in the `text-font` layout property in style JSON, or in the `MLNSymbolStyleLayer.textFontNames` property at runtime. The values in these properties must be font display names, not font family names or PostScript names. - -Each font name in the list must match a font that is registered in Mapbox Studio; otherwise, the text will not load, even if one of the fonts is available. Each font name must be included in the `{fontstack}` portion of the JSON stylesheet’s [`glyphs`](https://docs.mapbox.com/mapbox-gl-js/style-spec/glyphs/) property. - -## Client-side fonts - -By default, Chinese hanzi, Japanese kana, and Korean hangul characters (CJK) are rendered on the client side. Client-side text rendering uses less bandwidth than server-side text rendering, especially when viewing regions of the map that feature a wide variety of CJK characters. - -First, the map attempts to apply a font that you specify the same way as you would specify a server-side font: in [Mapbox Studio](https://studio.mapbox.com/), in the `text-font` layout property in style JSON, or in the `MLNSymbolStyleLayer.textFontNames` property at runtime. Instead of downloading the glyphs, the map tries to find a [system font](https://developer.apple.com/fonts/system-fonts/) or a font [bundled with your application](https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app) that matches one of these fonts based on its family name (for example, “PingFang TC”), display name (“PingFang TC Ultralight”), or PostScript name (“PingFangTC-Ultralight”). - -If the symbol layer does not specify an available font that contains the required glyphs, then the map tries to find a matching font in the [`MLNIdeographicFontFamilyName`](infoplist-keys.html#mglideographicfontfamilyname) Info.plist key. Like the `MLNSymbolStyleLayer.textFontNames` property, this key can contain a family name, display name, or PostScript name. This key is a global fallback that applies to all layers uniformly. It can either be a single string or an array of strings, which the map tries to apply in order from most preferred to least preferred. - -Each character is rendered in the first font you specify that has a glyph for the character. If the entire list of fonts is exhausted, the map uses the system’s font cascade list, which may vary based on the device model and system language. - -To disable client-side rendering of CJK characters, set the `MLNIdeographicFontFamilyName` key to the Boolean value `NO`. The map will revert to server-side font rendering. diff --git a/platform/darwin/scripts/style-spec-overrides-v8.json b/platform/darwin/scripts/style-spec-overrides-v8.json index 80ef6fde4..7daf53880 100644 --- a/platform/darwin/scripts/style-spec-overrides-v8.json +++ b/platform/darwin/scripts/style-spec-overrides-v8.json @@ -78,7 +78,7 @@ "examples": "See the Cluster point data and Use images to cluster point data to learn how to use an expression to set this attribute to the number of markers within a cluster." }, "text-font": { - "doc": "An array of font face names used to display the text.\n\nThe first font named in the array is applied to the text. For each character in the text, if the first font lacks a glyph for the character, the next font is applied as a fallback, and so on.\n\nSee the “[Customizing Fonts](../customizing-fonts.html)” guide for details on how this SDK chooses and renders fonts based on the value of this property." + "doc": "An array of font face names used to display the text.\n\nThe first font named in the array is applied to the text. For each character in the text, if the first font lacks a glyph for the character, the next font is applied as a fallback, and so on.\n\nSee the “[Customizing Fonts](doc:Customizing_Fonts)” guide for details on how this SDK chooses and renders fonts based on the value of this property." }, "text-offset": { "doc": "Offset distance of text from its anchor." diff --git a/platform/ios/MapLibre.docc/Customizing_Fonts.md b/platform/ios/MapLibre.docc/Customizing_Fonts.md new file mode 100644 index 000000000..f3286f80d --- /dev/null +++ b/platform/ios/MapLibre.docc/Customizing_Fonts.md @@ -0,0 +1,25 @@ +# Customizing Fonts + +Using custom fonts + +MapLibre Native iOS can render text that is part of an ``MLNSymbolStyleLayer`` in a font of your choice. The font customization options discussed in this document do not apply to user interface elements such as the scale bar or annotation callout views. + +## Server-side fonts + +By default, the map renders characters using glyphs downloaded from the server. You apply fonts when building a style with [Maputnik](https://maputnik.github.io), in the `text-font` layout property in style JSON, or in the ``MLNSymbolStyleLayer/textFontNames`` property at runtime. The values in these properties must be font display names, not font family names or PostScript names. + +Each font name in the list must match a font that is present on the server; otherwise, the text will not load, even if one of the fonts is available. Each font name must be included in the `{fontstack}` portion of the JSON stylesheet’s [`glyphs`](https://maplibre.org/maplibre-style-spec/glyphs/) property. + +[Martin](https://maplibre.org/martin/sources-fonts.html) can serve fonts directly. You can also generate fonts with [font-maker](https://github.com/maplibre/font-maker). + +## Client-side fonts + +By default, Chinese hanzi, Japanese kana, and Korean hangul characters (CJK) are rendered on the client side. Client-side text rendering uses less bandwidth than server-side text rendering, especially when viewing regions of the map that feature a wide variety of CJK characters. + +First, the map attempts to apply a font that you specify the same way as you would specify a server-side font: in [Maputnik](https://maputnik.github.io), in the `text-font` layout property in style JSON, or in the `MLNSymbolStyleLayer.textFontNames` property at runtime. Instead of downloading the glyphs, the map tries to find a [system font](https://developer.apple.com/fonts/system-fonts/) or a font [bundled with your application](https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app) that matches one of these fonts based on its family name (for example, “PingFang TC”), display name (“PingFang TC Ultralight”), or PostScript name (“PingFangTC-Ultralight”). + +If the symbol layer does not specify an available font that contains the required glyphs, then the map tries to find a matching font in the `MLNIdeographicFontFamilyName` [Info.plist key](doc:Info.plist_Keys). Like the ``MLNSymbolStyleLayer.textFontNames`` property, this key can contain a family name, display name, or PostScript name. This key is a global fallback that applies to all layers uniformly. It can either be a single string or an array of strings, which the map tries to apply in order from most preferred to least preferred. + +Each character is rendered in the first font you specify that has a glyph for the character. If the entire list of fonts is exhausted, the map uses the system’s font cascade list, which may vary based on the device model and system language. + +To disable client-side rendering of CJK characters, set the `MLNIdeographicFontFamilyName` key to the Boolean value `NO`. The map will revert to server-side font rendering. diff --git a/platform/ios/docs/guides/Info.plist Keys.md b/platform/ios/MapLibre.docc/Info.plist_Keys.md similarity index 57% rename from platform/ios/docs/guides/Info.plist Keys.md rename to platform/ios/MapLibre.docc/Info.plist_Keys.md index 20ef8742e..9cfae2315 100644 --- a/platform/ios/docs/guides/Info.plist Keys.md +++ b/platform/ios/MapLibre.docc/Info.plist_Keys.md @@ -1,15 +1,16 @@ # Info.plist Keys -The Mapbox Maps SDK for iOS supports custom `Info.plist` keys in your application in order to configure various settings. +MapLibre Native for iOS supports custom `Info.plist` keys in your application in order to configure various settings. ## MLNApiKey -If it is required by the tileserver you use, set the API key to be used by all instances of `MLNMapView` in the current application. +If it is required by the tileserver you use, set the API key to be used by all instances of ``MLNMapView`` in the current application. + +As an alternative, you can use ``MLNSettings.accessToken`` to set a token in code. -As an alternative, you can use `MLNSettings.accessToken` to set a token in code. ## MLNAccuracyAuthorizationDescription -Set the Mapbox accuracy authorization description string as an element of `NSLocationTemporaryUsageDescriptionDictionary` to be used by the map to request authorization when the `MLNLocationManager.accuracyAuthorization` is set to `CLAccuracyAuthorizationReducedAccuracy`. Requesting accuracy authorization is available for devices running iOS 14.0 and above. +Set the accuracy authorization description string as an element of `NSLocationTemporaryUsageDescriptionDictionary` to be used by the map to request authorization when the `MLNLocationManager.accuracyAuthorization` is set to `CLAccuracyAuthorizationReducedAccuracy`. Requesting accuracy authorization is available for devices running iOS 14.0 and above. Example: @@ -17,25 +18,15 @@ Example: NSLocationTemporaryUsageDescriptionDictionary MLNAccuracyAuthorizationDescription - Mapbox requires your precise location to help you navigate the map. + We require your precise location to help you navigate the map. ``` Remove `MLNAccuracyAuthorizationDescription` if you want to control when to request for accuracy authorization. -## MLNMapboxAPIBaseURL - -Use this key if you need to customize the API base URL used throughout the SDK. If unset, the default Mapbox API is used. - -The default value is `https://api.mapbox.com`. - -## MLNMapboxMetricsEnabledSettingShownInApp - -If you have implemented custom opt-out of Mapbox Telemetry within the user interface of your app, use this key to disable the built-in check for opt-out support. See [this guide](https://docs.mapbox.com/help/how-mapbox-works/attribution/#mapbox-maps-sdk-for-ios) for more details. - ## MLNIdeographicFontFamilyName -This key configures a global fallback font or fonts for [client-side text rendering](customizing-fonts.html#client-side-fonts) of Chinese hanzi, Japanese kana, and Korean hangul characters (CJK) that appear in text labels. +This key configures a global fallback font or fonts for [client-side text rendering](doc:Customizing_Fonts) of Chinese hanzi, Japanese kana, and Korean hangul characters (CJK) that appear in text labels. If the fonts you specify in the `MLNSymbolStyleLayer.textFontNames` property are all unavailable or lack a glyph for rendering a given CJK character, the map uses the contents of this key to choose a [system font](https://developer.apple.com/fonts/system-fonts/) or a font [bundled with your application](https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app). This key specifies a fallback for all style layers in all map views and map snapshots. If you do not specify this key or none of the font names matches, the map applies a font from the system’s font cascade list, which may vary based on the device model and system language. @@ -49,13 +40,13 @@ This key customizes the file path at which `MLNOfflineStorage` keeps the offline The key is interpreted as either an absolute file path or a file path relative to the main bundle’s resource folder, resolving any tilde or symbolic link. The path must be writable. If a database does not exist at the path you specify, one will be created automatically. -An offline map database can consume a significant amount of the user’s bandwidth and iCloud storage due to iCloud backups. To exclude the database from backups, set the containing directory’s `NSURLIsExcludedFromBackupKey` resource property to the Boolean value `YES` using the `-[NSURL setResourceValue:forKey:error:]` method. The entire directory will be affected, not just the database file. If the user restores the application from a backup, your application will need to restore any offline packs that had been previously downloaded. +An offline map database can consume a significant amount of the user’s bandwidth and iCloud storage due to iCloud backups. To exclude the database from backups, set the containing directory’s `NSURLIsExcludedFromBackupKey` resource property to the Boolean value `YES` using the [`NSURL/setResourceValue:forKey:error:`](https://developer.apple.com/documentation/foundation/nsurl/1413819-setresourcevalue) method. The entire directory will be affected, not just the database file. If the user restores the application from a backup, your application will need to restore any offline packs that had been previously downloaded. -At runtime, you can obtain the value of this key using the `MLNOfflineStorage.databasePath` and `MLNOfflineStorage.databaseURL` properties. +At runtime, you can obtain the value of this key using the ``MLNOfflineStorage/databasePath`` and ``MLNOfflineStorage/databaseURL`` properties. ## MLNCollisionBehaviorPre4_0 - If this key is set to YES (`true`), collision detection is performed only between symbol style layers based on the same source, as in versions 2.0–3.7 of the Mapbox Maps SDK for iOS. In other words, symbols in an `MLNSymbolStyleLayer` based on one source (for example, an `MLNShapeSource`) may overlap with symbols in another layer that is based on a different source (such as the Mapbox Streets source). This is the case regardless of the `MLNSymbolStyleLayer.iconAllowsOverlap`, `MLNSymbolStyleLayer.iconIgnoresPlacement`, `MLNSymbolStyleLayer.textAllowsOverlap`, and `MLNSymbolStyleLayer.textIgnoresPlacement` properties. + If this key is set to YES (`true`), collision detection is performed only between symbol style layers based on the same source, as in versions 2.0–3.7 of the MapLibre Native iOS. In other words, symbols in an `MLNSymbolStyleLayer` based on one source (for example, an `MLNShapeSource`) may overlap with symbols in another layer that is based on a different source. This is the case regardless of the ``MLNSymbolStyleLayer/iconAllowsOverlap``, ``MLNSymbolStyleLayer/iconIgnoresPlacement``, ``MLNSymbolStyleLayer/textAllowsOverlap``, and ``MLNSymbolStyleLayer/textIgnoresPlacement`` properties. Beginning in version 4.0, the SDK also performs collision detection between style layers based on different sources by default. For the default behavior, omit the `MLNCollisionBehaviorPre4_0` key or set it to NO (`false`). diff --git a/platform/ios/benchmark/Info.plist b/platform/ios/benchmark/Info.plist index 4db652439..ba91cce48 100644 --- a/platform/ios/benchmark/Info.plist +++ b/platform/ios/benchmark/Info.plist @@ -28,8 +28,6 @@ 15256 LSRequiresIPhoneOS - MLNMapboxMetricsEnabledSettingShownInApp - NSHumanReadableCopyright © 2015–2019 Mapbox UIApplicationExitsOnSuspend diff --git a/platform/macos/docs/guides/Info.plist Keys.md b/platform/macos/docs/guides/Info.plist Keys.md deleted file mode 100644 index 1ef9826ef..000000000 --- a/platform/macos/docs/guides/Info.plist Keys.md +++ /dev/null @@ -1,39 +0,0 @@ -# Info.plist Keys - -The Mapbox Maps SDK for macOS supports custom `Info.plist` keys in your application in order to configure various settings. - -## MLNApiKey - -Some vector tiles servers require a API key. Set the API key to be used by all instances of `MLNMapView` in the current application. - -As an alternative, you can use `MLNSettings.accessToken` to set a token in code. See [our guide](https://www.mapbox.com/help/ios-private-access-token/) for some tips on keeping access tokens in open source code private. - -## MLNTileServerBaseURL - -Use this key if you need to customize the API base URL used throughout the SDK. - -## MLNIdeographicFontFamilyName - -This key configures a global fallback font or fonts for [client-side text rendering](customizing-fonts.html#client-side-fonts) of Chinese hanzi, Japanese kana, and Korean hangul characters (CJK) that appear in text labels. - -If the fonts you specify in the `MLNSymbolStyleLayer.textFontNames` property are all unavailable or lack a glyph for rendering a given CJK character, the map uses the contents of this key to choose a [system font](https://developer.apple.com/fonts/system-fonts/) or a font [bundled with your application](https://developer.apple.com/documentation/bundleresources/information_property_list/atsapplicationfontspath). This key specifies a fallback for all style layers in all map views and map snapshots. If you do not specify this key or none of the font names matches, the map applies a font from the system’s font cascade list, which may vary based on the system language and other installed applications. - -This key can either be set to a single string or an array of strings, which the map tries to apply in order from most preferred to least preferred. Each string can be a family name (for example, “PingFang TC”), display name (“PingFang TC Ultralight”), or PostScript name (“PingFangTC-Ultralight”). - -To disable client-side rendering of CJK characters in favor of [server-side rendering](customizing-fonts.html#server-side-fonts), set this key to the Boolean value `NO`. - -## MLNOfflineStorageDatabasePath - -This key customizes the file path at which `MLNOfflineStorage` keeps the offline map database, which contains any offline packs as well as the ambient cache. Most applications should not need to customize this path; however, you could customize it to implement a migration path between different versions of your application. - -The key is interpreted as either an absolute file path or a file path relative to the main bundle’s resource folder, resolving any tilde or symbolic link. The path must be writable. If a database does not exist at the path you specify, one will be created automatically. - -An offline map database can consume a significant amount of the user’s bandwidth and iCloud storage due to iCloud backups. To exclude the database from backups, set the containing directory’s `NSURLIsExcludedFromBackupKey` resource property to the Boolean value `YES` using the `-[NSURL setResourceValue:forKey:error:]` method. The entire directory will be affected, not just the database file. If the user restores the application from a backup, your application will need to restore any offline packs that had been previously downloaded. - -At runtime, you can obtain the value of this key using the `MLNOfflineStorage.databasePath` and `MLNOfflineStorage.databaseURL` properties. - -## MLNCollisionBehaviorPre4_0 - -If this key is set to YES (`true`), collision detection is performed only between symbol style layers based on the same source, as in versions 0.1–0.7 of the Mapbox Maps SDK for iOS. In other words, symbols in an `MLNSymbolStyleLayer` based on one source (for example, an `MLNShapeSource`) may overlap with symbols in another layer that is based on a different source (such as the Mapbox Streets source). This is the case regardless of the `MLNSymbolStyleLayer.iconAllowsOverlap`, `MLNSymbolStyleLayer.iconIgnoresPlacement`, `MLNSymbolStyleLayer.textAllowsOverlap`, and `MLNSymbolStyleLayer.textIgnoresPlacement` properties. - -Beginning in version 0.7, the SDK also performs collision detection between style layers based on different sources by default. For the default behavior, omit the `MLNCollisionBehaviorPre4_0` key or set it to NO (`false`). This property is so named because version 0.7 of the Mapbox Maps SDK for macOS corresponds to version 4.0 of the Mapbox Maps SDK for iOS.