ArcGIS Runtime SDK for iOS: AGSBasemap Class Reference
ArcGIS Runtime SDK for iOS  100.15
AGSBasemap Class Reference

Description

A basemap for a map or a scene.

Instances of this class represent a basemap for a map or a scene.

A basemap helps orient the user and provides a geographical context for the content you want to display in the scene. It is used for locational reference and provides a framework on which you can overlay operational layers. Thus, the basemap serves as a foundation and provides a framework for working with information geographically. It's content is typically static and does not change frequently. For eg, streets, parcel boundaries, or geographic features such as rivers. Some basemaps also contain reference layers, such as labels, which are drawn on top of operational layers.

ArcGIS Online provides a number of ready-to-use basemaps such as streetsBasemap (AGSBasemap(AGSDeprecated)), topographicBasemap (AGSBasemap(AGSDeprecated)), etc, but you can also create your own basemap by mashing up layers. A basemap is composed of a collection of baseLayers, and referenceLayers. Base layers are displayed at the bottom, and reference layers are displayed at the top, with other operational layers sandwiched between them. The content of a basemap is typically static and does not change frequently.

In order to take advantage of geographically load balanced services and monitor usage with API keys or named users, use initWithStyle: (AGSBasemap).

Since
100
Inheritance diagram for AGSBasemap:
AGSLoadableBase <AGSJSONSerializable> <AGSRemoteResource> <AGSAPIKeyResource> AGSObject <AGSLoadable>

Instance Methods

(void) - cancelLoad
 
(void) - doCancelLoading
 
(void) - doStartLoading:
 
(instancetype) - init
 
(instancetype) - initWithBaseLayer:
 
(instancetype) - initWithBaseLayers:referenceLayers:
 
(instancetype) - initWithItem:
 
(instancetype) - initWithStyle:
 
(nullable instancetype) - initWithURL:
 
(void) - loadDidFinishWithError:
 
(void) - loadWithCompletion:
 
(void) - onLoadStatusChanged
 
(void) - retryLoadWithCompletion:
 
(nullable id) - toJSON:
 

Class Methods

(instancetype) + basemap
 
(instancetype) + basemapWithBaseLayer:
 
(instancetype) + basemapWithBaseLayers:referenceLayers:
 
(instancetype) + basemapWithItem:
 
(instancetype) + basemapWithStyle:
 
(nullable instancetype) + basemapWithURL:
 
(instancetype) + darkGrayCanvasVectorBasemap
 
(nullable id< AGSJSONSerializable >) + fromJSON:error:
 
(instancetype) + imageryBasemap
 
(instancetype) + imageryWithLabelsBasemap
 
(instancetype) + imageryWithLabelsVectorBasemap
 
(instancetype) + lightGrayCanvasBasemap
 
(instancetype) + lightGrayCanvasVectorBasemap
 
(instancetype) + nationalGeographicBasemap
 
(instancetype) + navigationVectorBasemap
 
(instancetype) + oceansBasemap
 
(instancetype) + openStreetMapBasemap
 
(instancetype) + streetsBasemap
 
(instancetype) + streetsNightVectorBasemap
 
(instancetype) + streetsVectorBasemap
 
(instancetype) + streetsWithReliefVectorBasemap
 
(instancetype) + terrainWithLabelsBasemap
 
(instancetype) + terrainWithLabelsVectorBasemap
 
(instancetype) + topographicBasemap
 
(instancetype) + topographicVectorBasemap
 

Properties

NSString * APIKey
 
NSMutableArray< AGSLayer * > * baseLayers
 
AGSCredentialcredential
 
AGSItemitem
 
NSError * loadError
 
AGSLoadStatus loadStatus
 
NSString * name
 
NSMutableArray< AGSLayer * > * referenceLayers
 
AGSRequestConfigurationrequestConfiguration
 
NSDictionary< NSString *, id > * unknownJSON
 
NSDictionary< NSString *, id > * unsupportedJSON
 
NSURL * URL
 

Method Documentation

◆ basemap

+ (instancetype) basemap

Instantiates a new basemap.

Since
100

◆ basemapWithBaseLayer:

+ (instancetype) basemapWithBaseLayer: (AGSLayer *)  layer

Instantiates a new basemap.

Parameters
layerThe layer to be used as the basemap's base layer
Since
100

◆ basemapWithBaseLayers:referenceLayers:

+ (instancetype) basemapWithBaseLayers: (NSArray< AGSLayer * > *)  baseLayers
referenceLayers: (nullable NSArray< AGSLayer * > *)  referenceLayers 

Instantiates a new basemap.

Parameters
baseLayersThe layers to be used as the basemap's base layers
referenceLayersThe layers to be used as the basemap's reference layers
Since
100

◆ basemapWithItem:

+ (instancetype) basemapWithItem: (AGSItem *)  item

Instantiates a new basemap.

Parameters
itemThe web map item on ArcGIS Online or an on-premise portal that represents a basemap
Note
The item must be of type AGSPortalItemTypeWebMap.
Since
100

◆ basemapWithStyle:

+ (instancetype) basemapWithStyle: (AGSBasemapStyle style

Creates a basemap with a style.

Parameters
styleThe basemap style.
See also
AGSBasemapStyle
Since
100.10

◆ basemapWithURL:

+ (nullable instancetype) basemapWithURL: (NSURL *)  URL

Instantiate a basemap with a URL to a portal item which is a web basemap.

Parameters
URLof the web basemap on ArcGIS Online or an on-premises portal
Returns
The basemap created from the URL, or nil if an invalid URL is passed.
Since
100.4

◆ cancelLoad

- (void) cancelLoad
requiredinherited

Cancels loading if it is in progress, otherwise it does nothing. This should be called carefully because other objects could be waiting for loadWithCompletion: or retryLoadWithCompletion: to complete and this will call them all back with the error of NSUserCancelledError

Since
100

◆ darkGrayCanvasVectorBasemap

+ (instancetype) darkGrayCanvasVectorBasemap

Instantiates a new basemap based on ArcGIS Online Dark Gray Canvas basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISDarkGray.

Provided by category AGSBasemap(AGSDeprecated).

◆ doCancelLoading

- (void) doCancelLoading

Never call this method directly. The framework calls this method on a background thread when cancelLoad (AGSLoadable-p) is called. It is meant to be overriden by subclasses. Subclasses should override this method to cancel loading their data and call loadDidFinishWithError: (AGSLoadableBase(ForSubclassEyesOnly)) at the end passing in an error representing NSUserCancelledError.

Since
100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ doStartLoading:

- (void) doStartLoading: (BOOL)  retrying

Never call this method directly. The framework calls this method on a background thread when loadWithCompletion: (AGSLoadable-p) or retryLoadWithCompletion: (AGSLoadable-p) is called. It is meant to be overriden by subclasses. Subclasses should override this method to load their data and call loadDidFinishWithError: (AGSLoadableBase(ForSubclassEyesOnly)) upon completion, passing in the error if any.

Parameters
retryingflag that is true if this method was called from retryLoadWithCompletion: (AGSLoadable-p).
Since
100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ fromJSON:error:

+ (nullable id<AGSJSONSerializable>) fromJSON: (id)  JSONObject
error: (NSError **)  error 
staticrequiredinherited

Initializes and returns an object from its JSON representation.

Parameters
JSONObjectNSDictionary or NSArray containing the JSON.
errorencountered during the operation, if any.
Since
100

◆ imageryBasemap

+ (instancetype) imageryBasemap

Instantiates a new basemap based on ArcGIS Online World Imagery basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISImageryStandard.

Provided by category AGSBasemap(AGSDeprecated).

◆ imageryWithLabelsBasemap

+ (instancetype) imageryWithLabelsBasemap

Instantiates a new basemap based on ArcGIS Online Imagery with Labels basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISImagery.

Provided by category AGSBasemap(AGSDeprecated).

◆ imageryWithLabelsVectorBasemap

+ (instancetype) imageryWithLabelsVectorBasemap

Instantiates a new basemap based on ArcGIS Online Imagery Hybrid basemap.

Since
100\
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISImagery.

Provided by category AGSBasemap(AGSDeprecated).

◆ init

- (instancetype) init

◆ initWithBaseLayer:

- (instancetype) initWithBaseLayer: (AGSLayer *)  layer

Instantiates a new basemap.

Parameters
layerThe layer to be used as the basemap's base layer
Since
100

◆ initWithBaseLayers:referenceLayers:

- (instancetype) initWithBaseLayers: (NSArray< AGSLayer * > *)  baseLayers
referenceLayers: (nullable NSArray< AGSLayer * > *)  referenceLayers 

Instantiates a new basemap.

Parameters
baseLayersThe layers to be used as the basemap's base layers
referenceLayersThe layers to be used as the basemap's reference layers
Since
100

◆ initWithItem:

- (instancetype) initWithItem: (AGSItem *)  item

Instantiates a new basemap.

Parameters
itemThe item on ArcGIS Online or an on-premise portal that represents a basemap
Since
100

◆ initWithStyle:

- (instancetype) initWithStyle: (AGSBasemapStyle style

Creates a basemap with a style.

Parameters
styleThe basemap style.
See also
AGSBasemapStyle
Since
100.10

◆ initWithURL:

- (nullable instancetype) initWithURL: (NSURL *)  URL

Instantiate a basemap with a URL to a portal item which is a web basemap.

Parameters
URLof the web basemap on ArcGIS Online or an on-premises portal
Returns
The basemap created from the URL, or nil if an invalid URL is passed.
Since
100.4

◆ lightGrayCanvasBasemap

+ (instancetype) lightGrayCanvasBasemap

Instantiates a new basemap based on ArcGIS Online Light Gray Canvas basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISLightGray.

Provided by category AGSBasemap(AGSDeprecated).

◆ lightGrayCanvasVectorBasemap

+ (instancetype) lightGrayCanvasVectorBasemap

Instantiates a new basemap based on ArcGIS Online Light Gray Canvas basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISLightGray.

Provided by category AGSBasemap(AGSDeprecated).

◆ loadDidFinishWithError:

- (void) loadDidFinishWithError: (nullable NSError *)  error

Only subclasses should call this method in doStartLoading: (AGSLoadableBase(ForSubclassEyesOnly)) and doCancelLoading (AGSLoadableBase(ForSubclassEyesOnly)) when done loading or failed to load.

Since
100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ loadWithCompletion:

- (void) loadWithCompletion: (nullable void(^)(NSError *__nullable error))  completion
requiredinherited

Loads data for the object asynchronously. The completion block is invoked upon completion.

You can call this method any number of times, however only one attempt is made to load the data. If it is already loading, it will just continue to load (i.e. not force a reload). If it has already loaded successfully, the completion block will be invoked right away. If it has already failed to load, the completion block will be invoked right away with error previously encountered. This method supports multiple callers and will call them all back on completion. However, each caller's completion block will be invoked once and only once.

Parameters
completionblock that is invoked when object loads successfully or fails to load. An error is passed to the block if the object fails to load.
Note
The completion block is always invoked on the main thread.
Since
100
See also
- cancelLoad to cancel loading
- retryLoadWithCompletion: to force reload

◆ nationalGeographicBasemap

+ (instancetype) nationalGeographicBasemap

Instantiates a new basemap based on ArcGIS Online National Geographic World basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use the National Geographic Style Map. https://www.arcgis.com/home/item.html?id=f33a34de3a294590ab48f246e99958c9

Provided by category AGSBasemap(AGSDeprecated).

◆ navigationVectorBasemap

+ (instancetype) navigationVectorBasemap

Instantiates a new basemap based on ArcGIS Online World Navigation Map basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISNavigation.

Provided by category AGSBasemap(AGSDeprecated).

◆ oceansBasemap

+ (instancetype) oceansBasemap

Instantiates a new basemap based on ArcGIS Online Oceans basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISOceans.

Provided by category AGSBasemap(AGSDeprecated).

◆ onLoadStatusChanged

- (void) onLoadStatusChanged

Never call this method directly. The framework calls this method on a background thread when AGSLoadable::loadStatus changes is called. Subclasses can optionally implement this to know when their loading status has changed.

Since
100

Provided by category AGSLoadableBase(ForSubclassEyesOnly).

◆ openStreetMapBasemap

+ (instancetype) openStreetMapBasemap

Instantiates a new basemap based on OpenStreetMap basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleOSMStandard.

Provided by category AGSBasemap(AGSDeprecated).

◆ retryLoadWithCompletion:

- (void) retryLoadWithCompletion: (nullable void(^)(NSError *__nullable error))  completion
requiredinherited

Tries to reload when an object has failed to load. This method should be called judiciously. It should be called when:

  1. you didn't have network connectivity earlier when it failed and you want to retry now that you have connectivity
  2. the server was down earlier when it failed and you want to retry
  3. the request is taking too long and you want to cancel it and retry, in which case you will first call cancelLoad and then this method

If the data hasn't started loading, it will start loading. If it is already loading, it will just continue to load. If it has already loaded successfully, calls back right away. If it has already failed to load, tries again. This method supports multiple callers and will call them all back on completion. However, each caller's completion block will be invoked once and only once.

Parameters
completionblock that is invoked when object loads successfully or fails to load. An error is passed to the block if the object fails to load.
Note
The completion block is always invoked on the main thread.
Since
100

◆ streetsBasemap

+ (instancetype) streetsBasemap

Instantiates a new basemap based on ArcGIS Online World Street basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISStreets.

Provided by category AGSBasemap(AGSDeprecated).

◆ streetsNightVectorBasemap

+ (instancetype) streetsNightVectorBasemap

Instantiates a new basemap based on ArcGIS Online World Street Map (Night) basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISStreetsNight.

Provided by category AGSBasemap(AGSDeprecated).

◆ streetsVectorBasemap

+ (instancetype) streetsVectorBasemap

Instantiates a new basemap based on ArcGIS Online World Street Map basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISStreets.

Provided by category AGSBasemap(AGSDeprecated).

◆ streetsWithReliefVectorBasemap

+ (instancetype) streetsWithReliefVectorBasemap

Instantiates a new basemap based on ArcGIS Online Streets (with Relief) basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISStreetsRelief.

Provided by category AGSBasemap(AGSDeprecated).

◆ terrainWithLabelsBasemap

+ (instancetype) terrainWithLabelsBasemap

Instantiates a new basemap based on ArcGIS Online Terrain with Labels basmap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISTerrain.

Provided by category AGSBasemap(AGSDeprecated).

◆ terrainWithLabelsVectorBasemap

+ (instancetype) terrainWithLabelsVectorBasemap

Instantiates a new basemap based on ArcGIS Online Terrain with Labels basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISTerrain.

Provided by category AGSBasemap(AGSDeprecated).

◆ toJSON:

- (nullable id) toJSON: (NSError **)  error
requiredinherited

Returns JSON representation for this object.

Parameters
errorencountered during the operation, if any.
Returns
NSDictionary or NSArray containing the JSON.
Since
100

Reimplemented in AGSPortalItem.

◆ topographicBasemap

+ (instancetype) topographicBasemap

Instantiates a new basemap based on ArcGIS Online World Topographic basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISTopographic.

Provided by category AGSBasemap(AGSDeprecated).

◆ topographicVectorBasemap

+ (instancetype) topographicVectorBasemap

Instantiates a new basemap based on ArcGIS Online Topographic basemap.

Since
100
Deprecated:
100.14.0. AGSBasemapType and its associated basemap helpers has been deprecated. Use initWithStyle: with AGSBasemapStyleArcGISTopographic.

Provided by category AGSBasemap(AGSDeprecated).

Property Documentation

◆ APIKey

- (NSString*) APIKey
readwriterequirednonatomiccopyinherited

The API key to access API key enabled services and resources in ArcGIS Online.

An API key is a unique key used to authorize access to specific services and resources in ArcGIS Online. It is also used to monitor access to those services. An API key is created and managed in the ArcGIS developer dashboard and is tied to a specific ArcGIS account.

In addition to setting an API key at a global level for your application using the AGSArcGISRuntimeEnvironment::APIKey property, you can set an AGSAPIKeyResource::APIKey property on any ArcGIS Runtime class that implements AGSAPIKeyResource. When you set an individual AGSAPIKeyResource::APIKey property on an AGSAPIKeyResource it will override the default key at the global level (on the AGSArcGISRuntimeEnvironment::APIKey property, in other words), enabling more granular usage telemetry and management for ArcGIS Online resources used by your app. Classes that expose an API key property by implementing AGSAPIKeyResource include:

◆ baseLayers

- (NSMutableArray<AGSLayer*>*) baseLayers
readnonatomicstrong

The base layers of this basemap. Base layers are displayed at the bottom in a mapview, and reference layers are displayed at the top, with the map's operational layers sandwiched between them. The layers are drawn in a bottom-up fashion with the 0th layer in the list drawn first, next layer drawn on top of the previous one, and so on.

Note
This array does not allow duplicate objects.
Since
100

◆ credential

- (AGSCredential*) credential
readwritenonatomicstronginherited

Security credentials to access the remote resource. Only applicable if the resource is secured.

Since
100

◆ item

- (AGSItem*) item
readnonatomicstrong

The portal item that was used to create the basemap

Since
100

◆ loadError

- (NSError*) loadError
readnonatomicstronginherited

The error that was encountered during the most recent load operation. Will be nil if the operation succeeded.

Since
100

◆ loadStatus

- (AGSLoadStatus) loadStatus
readrequirednonatomicassigninherited

Status of the load operation.

Since
100

◆ name

- (NSString*) name
readwritenonatomiccopy

The name of the basemap

Since
100

◆ referenceLayers

- (NSMutableArray<AGSLayer*>*) referenceLayers
readnonatomicstrong

The reference layers of this basemap. Base layers are displayed at the bottom in a mapview, and reference layers are displayed at the top, with the map's operational layers sandwiched between them. The layers are drawn in a bottom-up fashion with the 0th layer in the list drawn first, next layer drawn on top of the previous one, and so on.

Note
This array does not allow duplicate objects.
Since
100

◆ requestConfiguration

- (AGSRequestConfiguration*) requestConfiguration
readwritenonatomicstronginherited

The AGSRequestConfiguration object which defines the behavior and policies to use when accessing the remote resource. The default will be nil. If it is nil the [AGSRequestConfiguration globalConfiguration] will be used.

Since
100

◆ unknownJSON

- (NSDictionary<NSString*,id>*) unknownJSON
readrequirednonatomiccopyinherited

A dictionary of values that was in the source JSON but was unparsed by API.

Returns
NSDictionary containing the unknown JSON.
Since
100

◆ unsupportedJSON

- (NSDictionary<NSString*,id>*) unsupportedJSON
readnonatomiccopyinherited

A dictionary of values that are supported by the REST API, but not exposed through the SDK API.

Returns
NSDictionary containing the unsupported JSON.
Since
100

◆ URL

- (NSURL*) URL
readrequirednonatomicstronginherited

The URL of the remote resource.

Since
100