UNL iOS SDK SDK Package Annotations

Annotations

  • MGLAnnotationImage 

    
                              @interface MGLAnnotationImage : NSObject <NSSecureCoding>

    The MGLAnnotationImage class is responsible for presenting point-based annotations visually on a map view. Annotation image objects wrap UIImage objects and may be recycled later and put into a reuse queue that is maintained by the map view.

    See the Mark a place on the map with an image example to learn how use an image as a marker using MGLAnnotationImage.

    Initializing and Preparing the Image Object

    • +annotationImageWithImage:reuseIdentifier:

      Initializes and returns a new annotation image object.

      Declaration

      Objective-C

      + (nonnull instancetype)annotationImageWithImage:(nonnull UIImage *)image
                                             reuseIdentifier:
                                                 (nonnull NSString *)reuseIdentifier;

      Swift

      convenience init(image: UIImage, reuseIdentifier: String)

      Parameters

      image

      The image to be displayed for the annotation.
      reuseIdentifier

      The string that identifies that this annotation image is reusable.

      Return Value

      The initialized annotation image object or nil if there was a problem initializing the object.

      View Source on GitHub

    Getting and Setting Attributes

    • image

      The image to be displayed for the annotation.

      Declaration

      Objective-C

      @property (nonatomic, strong, nullable) UIImage *image;

      Swift

      var image: UIImage? { get set }
      View Source on GitHub

    • reuseIdentifier

      The string that identifies that this annotation image is reusable. (read-only)

      You specify the reuse identifier when you create the image object. You use this type later to retrieve an annotation image object that was created previously but which is currently unused because its annotation is not on screen.

      If you define distinctly different types of annotations (with distinctly different annotation images to go with them), you can differentiate between the annotation types by specifying different reuse identifiers for each one.

      Declaration

      Objective-C

      @property (nonatomic, readonly) NSString *_Nonnull reuseIdentifier;

      Swift

      var reuseIdentifier: String { get }
      View Source on GitHub

    • enabled

      A Boolean value indicating whether the annotation is enabled.

      The default value of this property is YES. If the value of this property is NO, the annotation image ignores touch events and cannot be selected.

      Declaration

      Objective-C

      @property (nonatomic, getter=isEnabled) BOOL enabled;

      Swift

      var isEnabled: Bool { get set }
      View Source on GitHub

    MGLAnnotationView 

    
            @interface MGLAnnotationView : UIView <NSSecureCoding>

    The MGLAnnotationView class is responsible for marking a point annotation with a view. Annotation views represent an annotation object, which is an object that corresponds to the MGLAnnotation protocol. When an annotation’s geographic coordinate is visible in the map view, the map view asks its delegate to a corresponding annotation view. If an annotation view is created with a reuse identifier, the map view may recycle the view when it goes offscreen.

    Annotation views are compatible with UIKit, Core Animation, and other Cocoa Touch frameworks. On the other hand, if you do not need animation or interactivity such as dragging, you can use an MGLAnnotationImage instead to conserve memory and optimize drawing performance.

    Initializing and Preparing the View

    • -initWithReuseIdentifier:

      Initializes and returns a new annotation view object.

      The reuse identifier provides a way for you to improve performance by recycling annotation views as they enter and leave the map’s viewport. As an annotation leaves the viewport, the map view moves its associated view to a reuse queue. When a new annotation becomes visible, you can request a view for that annotation by passing the appropriate reuse identifier string to the -[MGLMapView dequeueReusableAnnotationViewWithIdentifier:] method.

      Declaration

      Objective-C

      - (nonnull instancetype)initWithReuseIdentifier:
                (nullable NSString *)reuseIdentifier;

      Swift

      init(reuseIdentifier: String?)

      Parameters

      reuseIdentifier

      A unique string identifier for this view that allows you to reuse this view with multiple similar annotations. You can set this parameter to nil if you don’t intend to reuse the view, but it is a good idea in general to specify a reuse identifier to avoid creating redundant views.

      Return Value

      The initialized annotation view object.

      View Source on GitHub

    • -initWithAnnotation:reuseIdentifier:

      Initializes and returns a new annotation view object.

      Providing an annotation allows you to explicitly associate the annotation instance with the new view and, in custom subclasses of MGLAnnotationView, customize the view based on properties of the annotation instance in an overridden initializer. However, annotation views that are reused will not necessarily be associated with the same annotation they were initialized with. Also, annotation views that are in the reuse queue will have a nil value for the annotation property. Passing an annotation instance to the view is optional and the map view will automatically associate annotations with views when views are provided to the map via the -[MGLMapViewDelegate mapView:viewForAnnotation:] method.

      The reuse identifier provides a way for you to improve performance by recycling annotation views as they enter and leave the map’s viewport. As an annotation leaves the viewport, the map view moves its associated view to a reuse queue. When a new annotation becomes visible, you can request a view for that annotation by passing the appropriate reuse identifier string to the -[MGLMapView dequeueReusableAnnotationViewWithIdentifier:] method.

      Declaration

      Objective-C

      - (nonnull instancetype)initWithAnnotation:
                                        (nullable id<MGLAnnotation>)annotation
                                       reuseIdentifier:(nullable NSString *)reuseIdentifier;

      Parameters

      annotation

      The annotation object to associate with the new view.
      reuseIdentifier

      A unique string identifier for this view that allows you to reuse this view with multiple similar annotations. You can set this parameter to nil if you don’t intend to reuse the view, but it is a good idea in general to specify a reuse identifier to avoid creating redundant views.

      Return Value

      The initialized annotation view object.

      View Source on GitHub

    • -prepareForReuse

      Called when the view is removed from the reuse queue.

      The default implementation of this method does nothing. You can override it in your custom annotation view implementation to put the view in a known state before it is returned to your map view delegate.

      Declaration

      Objective-C

      - (void)prepareForReuse;

      Swift

      func prepareForReuse()
      View Source on GitHub

    • annotation

      The annotation object currently associated with the view.

      You should not change the value of this property directly. This property contains a non-nil value while the annotation view is visible on the map. If the view is queued, waiting to be reused, the value is nil.

      Declaration

      Objective-C

      @property (nonatomic, nullable) id<MGLAnnotation> annotation;
      View Source on GitHub

    • reuseIdentifier

      The string that identifies that this annotation view is reusable.

      You specify the reuse identifier when you create the view. You use the identifier later to retrieve an annotation view that was created previously but which is currently unused because its annotation is not on-screen.

      If you define distinctly different types of annotations (with distinctly different annotation views to go with them), you can differentiate between the annotation types by specifying different reuse identifiers for each one.

      Declaration

      Objective-C

      @property (nonatomic, readonly, nullable) NSString *reuseIdentifier;

      Swift

      var reuseIdentifier: String? { get }
      View Source on GitHub

    Configuring the Appearance

    • centerOffset

      The offset, measured in points, at which to place the center of the view.

      By default, the center point of an annotation view is placed at the geographic coordinate point of the associated annotation. If you do not want the view to be centered, you can use this property to reposition the view. The offset’s dx and dy values are measured in points. Positive offset values move the annotation view down and to the right, while negative values move it up and to the left.

      Set the offset if the annotation view’s visual center point is somewhere other than the logical center of the view. For example, the view may contain an image that depicts a downward-pointing pushpin or thumbtack, with the tip positioned at the center-bottom of the view. In that case, you would set the offset’s dx to zero and its dy to half the height of the view.

      Declaration

      Objective-C

      @property (nonatomic) CGVector centerOffset;

      Swift

      var centerOffset: CGVector { get set }
      View Source on GitHub

    • scalesWithViewingDistance

      A Boolean value that determines whether the annotation view grows and shrinks as the distance between the viewpoint and the annotation view changes on a tilted map.

      When the value of this property is YES and the map is tilted, the annotation view appears smaller if it is towards the top of the view (closer to the horizon) and larger if it is towards the bottom of the view (closer to the viewpoint). This is also the behavior of MGLAnnotationImage objects. When the value of this property is NO or the map’s pitch is zero, the annotation view remains the same size regardless of its position on-screen.

      The default value of this property is NO. Keep this property set to NO if the view’s legibility is important.

      Note

      Scaling many on-screen annotation views can contribute to poor map performance. Consider keeping this property disabled if your use case involves hundreds or thousands of annotation views.

      Declaration

      Objective-C

      @property (nonatomic) BOOL scalesWithViewingDistance;

      Swift

      var scalesWithViewingDistance: Bool { get set }
      View Source on GitHub

    • rotatesToMatchCamera

      A Boolean value that determines whether the annotation view rotates together with the map.

      When the value of this property is YES and the map is rotated, the annotation view rotates. This is also the behavior of MGLAnnotationImage objects. When the value of this property is NO the annotation has its rotation angle fixed.

      The default value of this property is NO. Set this property to YES if the view’s rotation is important.

      Declaration

      Objective-C

      @property (nonatomic) BOOL rotatesToMatchCamera;

      Swift

      var rotatesToMatchCamera: Bool { get set }
      View Source on GitHub

    Managing the Selection State

    • selected

      A Boolean value indicating whether the annotation view is currently selected.

      You should not set the value of this property directly. If the property is set to YES, the annotation view is displaying a callout.

      By default, this property is set to NO and becomes YES when the user taps the view. Selecting another annotation, whether it is associated with an MGLAnnotationView or MGLAnnotationImage object, deselects any currently selected view.

      Setting this property changes the view’s appearance to reflect the new value immediately. If you want the change to be animated, use the -setSelected:animated: method instead.

      Declaration

      Objective-C

      @property (nonatomic, getter=isSelected) BOOL selected;

      Swift

      var isSelected: Bool { get set }
      View Source on GitHub

    • -setSelected:animated:

      Sets the selection state of the annotation view with an optional animation.

      You should not call this method directly. A map view calls this method in response to user interactions with the annotation. Subclasses may override this method in order to customize the appearance of the view depending on its selection state.

      See the Annotation views example to learn how to modify an MGLAnnotationView‘s behavior when it is selected.

      Declaration

      Objective-C

      - (void)setSelected:(BOOL)selected animated:(BOOL)animated;

      Swift

      func setSelected(_ selected: Bool, animated: Bool)

      Parameters

      selected

      YES if the view should display itself as selected; NO if it should display itself as unselected.
      animated

      YES if the change in selection state is animated; NO if the change is immediate.
      View Source on GitHub

    Supporting Drag Operations

    • draggable

      A Boolean value indicating whether the annotation view is draggable.

      If this property is set to YES, the user can drag the annotation after pressing and holding the view, and the associated annotation object must also implement the -setCoordinate: method. The default value of this property is NO.

      Setting this property to YES lets the map view know that the annotation is always draggable. In other words, you cannot conditionalize drag operations by attempting to stop an operation that has already been initiated; doing so can lead to undefined behavior. Once begun, the drag operation should always continue to completion.

      See the Draggable annotation views to learn how to enable users to drag MGLAnnotationView objects on your map.

      Declaration

      Objective-C

      @property (nonatomic, getter=isDraggable) BOOL draggable;

      Swift

      var isDraggable: Bool { get set }
      View Source on GitHub

    • dragState

      The current drag state of the annotation view.

      All states are handled automatically when the draggable property is set to YES. To perform a custom animation in response to a change to this property, override the -setDragState:animated: method.

      Declaration

      Objective-C

      @property (nonatomic, readonly) MGLAnnotationViewDragState dragState;

      Swift

      var dragState: MGLAnnotationViewDragState { get }
      View Source on GitHub

    • -setDragState:animated:

      Sets the current drag state for the annotation view.

      You can override this method to animate a custom annotation view as the user drags it. As the system detects user actions that would indicate a drag, it calls this method to update the drag state.

      Declaration

      Objective-C

      - (void)setDragState:(MGLAnnotationViewDragState)dragState
                        animated:(BOOL)animated;

      Swift

      func setDragState(_ dragState: MGLAnnotationViewDragState, animated: Bool)
      View Source on GitHub

    MGLUserLocation 

    
            @interface MGLUserLocation : NSObject <MGLAnnotation, NSSecureCoding>

    The MGLUserLocation class defines a specific type of annotation that identifies the user’s current location. You do not create instances of this class directly. Instead, you retrieve an existing MGLUserLocation object from the userLocation property of the map view displayed in your application.

    See the Customize the user location annotation example to learn how to overide the default user location annotation.

    Determining the User’s Position

    • location

      The current location of the device. (read-only)

      This property returns nil if the user’s location has not yet been determined.

      Declaration

      Objective-C

      @property (nonatomic, readonly, nullable) CLLocation *location;

      Swift

      var location: CLLocation? { get }
      View Source on GitHub

    • updating

      A Boolean value indicating whether the user’s location is currently being updated. (read-only)

      Declaration

      Objective-C

      @property (nonatomic, readonly, getter=isUpdating) BOOL updating;

      Swift

      var isUpdating: Bool { get }
      View Source on GitHub

    • heading

      The heading of the user location. (read-only)

      This property is nil if the user location tracking mode is not MGLUserTrackingModeFollowWithHeading or if MGLMapView.showsUserHeadingIndicator is disabled.

      Declaration

      Objective-C

      @property (nonatomic, readonly, nullable) CLHeading *heading;

      Swift

      var heading: CLHeading? { get }
      View Source on GitHub

    Accessing the User Annotation Text

    • title

      The title to display for the user location annotation.

      Declaration

      Objective-C

      @property (nonatomic, copy) NSString *_Nonnull title;

      Swift

      var title: String { get set }
      View Source on GitHub

    • subtitle

      The subtitle to display for the user location annotation.

      Declaration

      Objective-C

      @property (nonatomic, copy, nullable) NSString *subtitle;

      Swift

      var subtitle: String? { get set }
      View Source on GitHub

    MGLUserLocationAnnotationView 

    
            @interface MGLUserLocationAnnotationView : MGLAnnotationView

    View representing an MGLUserLocation on screen.

    • mapView

      Returns the associated map view.

      The value of this property is nil during initialization.

      Declaration

      Objective-C

      @property (nonatomic, weak, readonly, nullable) MGLMapView *mapView;

      Swift

      weak var mapView: MGLMapView? { get }
      View Source on GitHub

    • userLocation

      Returns the annotation object indicating the user’s current location.

      The value of this property is nil during initialization and while user tracking is inactive.

      See the Customize the user location annotation example to learn how to customize the default user location annotation object.

      Declaration

      Objective-C

      @property (nonatomic, weak, readonly, nullable) MGLUserLocation *userLocation;

      Swift

      weak var userLocation: MGLUserLocation? { get }
      View Source on GitHub

    • hitTestLayer

      Returns the layer that should be used for annotation selection hit testing.

      The default value of this property is the presentation layer of the view’s Core Animation layer. When subclassing, you may override this property to specify a different layer to be used for hit testing. This can be useful when you wish to limit the interactive area of the annotation to a specific sublayer.

      Declaration

      Objective-C

      @property (nonatomic, weak, readonly) CALayer *_Nullable hitTestLayer;

      Swift

      weak var hitTestLayer: CALayer? { get }
      View Source on GitHub

    • -update

      Updates the user location annotation.

      Use this method to update the appearance of the user location annotation. This method is called by the associated map view when it has determined that the user location annotation needs to be updated. This can happen in response to user interaction, a change in the user’s location, when the user tracking mode changes, or when the viewport changes.

      Note

      During user interaction with the map, this method may be called many times to update the user location annotation. Therefore, your implementation of this method should be as lightweight as possible to avoid negatively affecting performance.

      Declaration

      Objective-C

      - (void)update;

      Swift

      func update()
      View Source on GitHub