MGLSymbolStyleAnnotation

@interface MGLSymbolStyleAnnotation : MGLStyleAnnotation

An MGLSymbolStyleAnnotation is a type of style layer annotation that renders both an icon and text label at a specified coordinate.

To display a symbol style annotation on a map, use one of the initializers below to create a symbol style annotation object. Then, use -[MGLSymbolAnnotationController add:] to add the annotation to a symbol style annotation controller.

If rendering an icon, first add an image to the map style’s sprite using the -[MGLStyle setImage:forName:] method within the Mapbox Maps SDK for iOS.

Example

func mapView(_ mapView: MGLMapView, didFinishLoading style: MGLStyle) {
   let attraction = UIImage(named: "attraction")

   if let styleImage = attraction {
       self.mapView.style?.setImage(styleImage, forName: "attraction")
   }

   let symbolAnnotationController = MGLSymbolAnnotationController(mapView: self.mapView)

   let symbol = MGLSymbolStyleAnnotation(coordinate: CLLocationCoordinate2DMake(59, 18));
   symbol.iconImageName = "attraction"
   symbol.text = "This is a cool place!"
   symbol.textFontSize = 16
   symbolAnnotationController.add(symbol)
}
  • Returns a new symbol style annotation anchored at a specified coordinate.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithCoordinate:(id)coordinate;

    Swift

    init(coordinate: Any!)

    Parameters

    coordinate

    The coordinate at which the symbol style annotation’s anchor should be placed.

    Return Value

    An initialized symbol style annotation anchored at the specified coordinate.

  • Returns a new symbol style annotation anchored at a specified coordinate with a defined text color.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithCoordinate:(id)coordinate
                                          text:(nonnull NSString *)text
                                         color:(nonnull UIColor *)color;

    Swift

    init(coordinate: Any!, text: String, color: UIColor)

    Parameters

    coordinate

    The coordinate at which the symbol style annotation’s anchor should be placed.

    color

    The textColor of the symbol style annotation’s text.

    Return Value

    An initialized symbol style annotation anchored at the specified coordinate with a text field and a defined text color.

  • Returns a new symbol style annotation anchored at a specified coordinate with a defined icon image.

    To add an image to the map style’s sprite, use the -[MGLStyle setImage:forName:] method within the Mapbox Maps SDK for iOS.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithCoordinate:(id)coordinate
                                 iconImageName:(nonnull NSString *)iconImageName;

    Swift

    init(coordinate: Any!, iconImageName: String)

    Parameters

    coordinate

    The coordinate at which the symbol style annotation’s anchor should be placed.

    iconImageName

    The name of the image within the MGLMapStyle‘s sprite to use for rendering the icon image of the symbol style annotation.

    Return Value

    An initialized symbol style annotation anchored at the specified coordinate with a defined icon image.

  • The name of the image within an MGLMapStyle‘s sprite to use for rendering the icon image of the symbol style annotation. Not set by default.

    To add an image to the map style’s sprite, use the -[MGLStyle setImage:forName:] method within the Mapbox Maps SDK for iOS.

    This property corresponds to the icon-image property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) NSString *_Nonnull iconImageName;

    Swift

    var iconImageName: String { get set }
  • The color to render the icon image of the symbol style annotation. Requires iconImageName. Defaults to black.

    This property corresponds to the icon-color property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) UIColor *_Nonnull iconColor;

    Swift

    var iconColor: UIColor { get set }
  • The placement of the symbol style annotation’s icon image relative to its anchor, as specified by MGLIconAnchor. Requires iconImageName. Defaults to center.

    This property corresponds to the icon-anchor property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) int iconAnchor;

    Swift

    var iconAnchor: Int32 { get set }
  • The offset distance of the symbol style annotation’s icon image from its anchor. Positive values indicate right and down, while negative values indicate left and up.

    Each component is multiplied by the value of iconSize to obtain the final offset in screen points. When combined with iconRotation, the offset will be as if the rotated direction was up. Requires iconImageName. Defaults to a CGVector struct set to 0 points rightward and 0 points downward.

    This property corresponds to the icon-offset property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGVector iconOffset;

    Swift

    var iconOffset: CGVector { get set }
  • The opacity of the symbol style annotation’s icon image. Requires iconImageName. Defaults to 1.

    This property corresponds to the icon-opacity property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat iconOpacity;

    Swift

    var iconOpacity: CGFloat { get set }
  • The counterclockwise rotation angle of the symbol style annotation’s icon image, measured in degrees. Requires iconImageName. Defaults to 0.

    This property corresponds to the icon-rotate property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat iconRotation;

    Swift

    var iconRotation: CGFloat { get set }
  • The value of which to multiply the size of the original symbol style annotation icon size, measured in screen points.

    The new size of the image will be the original size multiplied by the iconScale value. 1 is the original size; 3 triples the size of the image. Requires iconImageName. Defaults to 1.

    This property corresponds to the icon-size property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat iconScale;

    Swift

    var iconScale: CGFloat { get set }
  • An optional value representing the size of the halo or outline around a symbol annotation’s icon image, measured in screen points. Requires iconImageName. Defaults to 0.

    This property corresponds to the icon-halo-width property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat iconHaloWidth;

    Swift

    var iconHaloWidth: CGFloat { get set }
  • An optional value representing the fade out size of the halo or outline around a symbol annotation’s icon image, measured in screen points. Requires iconImageName. Defaults to 0.

    This property corresponds to the icon-halo-blur property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat iconHaloBlur;

    Swift

    var iconHaloBlur: CGFloat { get set }
  • An optional value representing the color of the halo or outline around a symbol annotation’s icon image. Requires iconImageName. Defaults to a clear color.

    This property corresponds to the icon-halo-blur property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) UIColor *_Nonnull iconHaloColor;

    Swift

    var iconHaloColor: UIColor { get set }
  • An optional array of font face names used to display the text of the symbol style annotation. Requires text.

    Defaults to an array containing the strings Open Sans Regular and Arial Unicode MS Regular. Fonts installed on the device’s system are not used. You can register a custom font with your style when designing styles in Mapbox Studio.

    This property corresponds to the text-font property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) NSArray<NSString *> *_Nonnull fontNames;

    Swift

    var fontNames: [String] { get set }
  • The text to display for a symbol style annotation. Defaults to "".

    This property corresponds to the text-field property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) NSString *_Nonnull text;

    Swift

    var text: String { get set }
  • The color of the text used by the symbol style annotation. Requires text. Defaults to black.

    This property corresponds to the text-color property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) UIColor *_Nonnull textColor;

    Swift

    var textColor: UIColor { get set }
  • The font size of the text used by the symbol style annotation, measured in screen points. Requires text. Defaults to 16.

    This property corresponds to the text-size property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat textFontSize;

    Swift

    var textFontSize: CGFloat { get set }
  • The opacity of the text used by the symbol style annotation, represented as a range of values between 0 and 1. Requires text. Defaults to 1.

    This property corresponds to the text-opacity property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat textOpacity;

    Swift

    var textOpacity: CGFloat { get set }
  • The type of text transformation that should be used by the text of the symbol style annotation, as specified by MGLTextTransform. Requires text. Defaults to none.

    This property corresponds to the text-transform property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) int textTransform;

    Swift

    var textTransform: Int32 { get set }
  • The text justification or alignment of the symbol style annotation’s text, as specified by MGLTextJustification. Requires text. Defaults to center.

    This property corresponds to the text-justify property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) int textJustification;

    Swift

    var textJustification: Int32 { get set }
  • The placement of the symbol style annotation’s text relative to its anchor, as specified by MGLTextAnchor. Requires text. Defaults to center.

    This property corresponds to the text-anchor property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) int textAnchor;

    Swift

    var textAnchor: Int32 { get set }
  • The tracking amount of the symbol style annotation’s text, measured in ems. Requires text. Defaults to 0.

    This property corresponds to the text-letter-spacing property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat textLetterSpacing;

    Swift

    var textLetterSpacing: CGFloat { get set }
  • The counterclockwise rotation angle of the symbol style annotation’s text, measured in degrees. Requires text. Defaults to 0.

    This property corresponds to the text-rotate property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat textRotation;

    Swift

    var textRotation: CGFloat { get set }
  • The distance that the text of the symbol style annotation is moved from its original placement.

    Positive values indicate right and down, while negative values indicate left and up. Requires text. Defaults to a CGVector struct set to 0 points rightward and 0 points downward.

    This property corresponds to the text-translate property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGVector textTranslation;

    Swift

    var textTranslation: CGVector { get set }
  • The offset distance of the text belonging to a symbol style annotation from its anchor, measured in ems.

    Positive values indicate right and down, while negative values indicate left and up. Requires text. Defaults to a CGVector struct set to 0 points rightward and 0 points downward. Disabled by textRadialOffset. This property corresponds to the text-offset property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGVector textOffset;

    Swift

    var textOffset: CGVector { get set }
  • The radial offset of the text belonging to a symbol style annotation in the direction of the symbol’s anchor, measured in ems. Requires text. Defaults to 0. Disabled by textOffset.

    This property corresponds to the text-offset property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat textRadialOffset;

    Swift

    var textRadialOffset: CGFloat { get set }
  • An optional value representing the fade out size of the halo or outline around a symbol style annotation’s text, measured in screen points. Requires text. Defaults to 0.

    This property corresponds to the text-halo-blur property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat textHaloBlur;

    Swift

    var textHaloBlur: CGFloat { get set }
  • An optional value representing the color of the halo or outline around a symbol style annotation’s text. Requires text. Defaults to a clear color.

    This property corresponds to the text-halo-blur property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic) UIColor *_Nonnull textHaloColor;

    Swift

    var textHaloColor: UIColor { get set }
  • An optional value representing the size of the halo or outline around a symbol style annotation’s text, measured in screen points. Requires text. Defaults to 0.

    This property corresponds to the text-halo-width property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat textHaloWidth;

    Swift

    var textHaloWidth: CGFloat { get set }
  • The maximum line width before text wraps to a new line, measured in ems. Requires text. Defaults to 10.

    This property corresponds to the text-max-width property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) CGFloat maximumTextWidth;

    Swift

    var maximumTextWidth: CGFloat { get set }
  • An optional value representing the ascending order at which symbol style annotations should be placed.

    Features with a higher sort key will appear above features with a lower sort key when they overlap. Features with a lower sort key will have priority over other features when doing placement.

    This property corresponds to the symbol-sort-key property in the style Mapbox Style Specification.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSInteger symbolSortKey;

    Swift

    var symbolSortKey: Int { get set }