MaplyScreenLabel

Objective-C

@interface MaplyScreenLabel : NSObject

Swift

class MaplyScreenLabel : NSObject

The Screen Label is a 2D label that tracks a given geographic location.

This screen label will track the given geographic position. If it’s behind the globe it will disappear. The label is rendered in a fixed size and will always appear on top of other geometry.

  • loc

    Location of the screen label in geographic (lat/lon) in radians.

    The screen label will track this position. If it would be behind the globe (in globe mode), then it will disappear.

    Declaration

    Objective-C

    @property (nonatomic) MaplyCoordinate loc;

    Swift

    var loc: MaplyCoordinate { get set }

  • An optional rotation to apply to the screen label.

    This is a rotation we’ll apply after the screen position has been calculated. You can use this to do things like track the orientation of roads.

    Rotation is in radians counter-clockwise from north.

    Declaration

    Objective-C

    @property (nonatomic) float rotation;

    Swift

    var rotation: Float { get set }

  • When the screen is rotated, try to keep the label upright.

    This tells the layout and display engine to keep the label oriented upright no matter what. In practice this means it will manipulate the rotation by 180 degrees.

    Declaration

    Objective-C

    @property (nonatomic) _Bool keepUpright;

    Swift

    var keepUpright: Bool { get set }

  • The actual text to display.

    This is a simple NSString for the text. Things like font are set in the NSDictionary passed in to the add call in the view controller.

    Declaration

    Objective-C

    @property (nonatomic, strong) NSString *_Nullable text;

    Swift

    var text: String? { get set }

  • Text can be accompanied by an optional icon image.

    If set, we’ll put this image to the left of the text in the screen label. The UIImage will be tracked by the view controller and reused as needed or disposed of when no longer needed.

    The name had to change because Apple’s private selector search is somewhat weak.

    Declaration

    Objective-C

    @property (nonatomic, strong) UIImage * __nullable iconImage2

    Swift

    var iconImage2: UnsafeMutablePointer<Int32>? { get set }

  • Icon size in points.

    If there is an icon image, this is how big it is.

    Declaration

    Objective-C

    @property (nonatomic) CGSize iconSize;

    Swift

    var iconSize: CGSize { get set }

  • An optional offset for the whole screen label.

    If set, we’ll move the screen label around by this amount before rendering it. These are screen coordinates, not geographic.

    Declaration

    Objective-C

    @property (nonatomic) CGPoint offset;

    Swift

    var offset: CGPoint { get set }

  • An optional color override.

    If set, this color will override the color passed in with the NSDictionary in the view controller’s add method.

    Declaration

    Objective-C

    @property (nonatomic, strong) UIColor * __nullable color

    Swift

    var color: UnsafeMutablePointer<Int32>? { get set }

  • Label selectability. On by default

    If set, this label can be selected by the user. If not set, this screen label will never appear in selection results.

    Declaration

    Objective-C

    @property (nonatomic) _Bool selectable;

    Swift

    var selectable: Bool { get set }

  • The layout importance compared to other features, 0 by default.

    The toolkit has a simple layout engine that runs several times per second. It controls the placement of all participating screen based features, such as MaplyScreenLabel and MaplyScreenMaker objects. This value controls the relative importance of this particular object. By default that importance is 0 so the object must compete with others. Setting it to MAXFLOAT will bypass the layout engine entirely and the object will always appear.

    Declaration

    Objective-C

    @property (nonatomic) float layoutImportance;

    Swift

    var layoutImportance: Float { get set }
  • The placement rules for the layout engine to follow.

The layout engine isn't the brightest bulb in the string and it needs placement hints.  This value tells the engine where we can move the label around.  These are bit flags, so OR them together as needed.  The default is everything.
    Layout Flag Meaning
    kMaplyLayoutRight The layout engine can put this label to the right of the location point.
    kMaplyLayoutLeft The layout engine can put this label to the left of the location point.
    kMaplyLayoutAbove The layout engine may put this label above the location point, centered.
    kMaplyLayoutBelow The layout engine may put this albel below the location point, centered.

    Declaration

    Objective-C

    @property (nonatomic) int layoutPlacement;

    Swift

    var layoutPlacement: Int32 { get set }

  • The size of the label for layout purposes.

    If layoutImportance is not set to MAXFLOAT, the screen label will get throw into the mix when doing screen layout. With this, you can set the size of the label when considering layout. If you set this to (0,0) the maker will take up no space, but still be considered in the layout.

    Declaration

    Objective-C

    @property (nonatomic) CGSize layoutSize;

    Swift

    var layoutSize: CGSize { get set }

  • Used to resolve to resolve labels that show the same thing.

    By default this is nil and not used to resolve conflicts. When you set it to something, such as a string, it will be used to resolve display conflicts. Only one object that has this unique ID (evaluated with isEqualToString:) will be displayed. Importance is evaluated first, so the most important will be placed first.

    Declaration

    Objective-C

    @property (nonatomic, retain, nullable) NSString *uniqueID;

    Swift

    var uniqueID: String? { get set }

  • User data object for selection

    When the user selects a feature and the developer gets it in their delegate, this is an object they can use to figure out what the screen label means to them.

    Declaration

    Objective-C

    @property (nonatomic, strong) id _Nullable userObject;

    Swift

    var userObject: Any? { get set }