GLMapView

Objective-C


@interface GLMapView
    : NSView <CLLocationManagerDelegate, NSGestureRecognizerDelegate>

Swift

class GLMapView : NSView, CLLocationManagerDelegate, NSGestureRecognizerDelegate

GLMapView is a custom UIView that renders and presents a vector map.

  • Captures a frame from GLMapView as a UIImage.

    Declaration

    Objective-C

    - (nullable PlatformImage *)captureFrame;

    Swift

    func captureFrame() -> NSImage?

    Return Value

    The current state of the GLMapView.

  • Captures a frame from GLMapView as a UIImage when all load operations are finished.

    See

    -captureFrame

    See

    offscreen

    Declaration

    Objective-C

    - (void)captureFrameWhenFinish:(nonnull GLMapCaptureFrameBlock)block;

    Swift

    func captureFrame(whenFinish block: @escaping GLMapCaptureFrameBlock)

    Parameters

    block

    The block callback is called when the screenshot is ready.

  • Allows rendering of offscreen frames. By default, offscreen is set to NO. GLMapView stops rendering when there is no superview. If you need to capture frames from a standalone GLMapView, set offscreen to YES.

    Declaration

    Objective-C

    @property BOOL offscreen;

    Swift

    var offscreen: Bool { get set }

  • Rendering frame interval. By default, frameInterval is 1 (60 fps).

    Declaration

    Objective-C

    @property NSInteger frameInterval;

    Swift

    var frameInterval: Int { get set }

  • State of the tile in the center of the screen.

    See

    centerTileStateChangedBlock

    Declaration

    Objective-C

    @property (readonly) GLMapTileState centerTileState;

    Swift

    var centerTileState: GLMapTileState { get }

User Interface

  • A vew that will be used to catch touches

    Declaration

    Objective-C

    @property (nonatomic, weak) PlatformView *_Nullable touchesView;

    Swift

    weak var touchesView: NSView? { get set }

  • A Boolean value that determines whether animations must stop on new touch.

    Declaration

    Objective-C

    @property (nonatomic) BOOL resetsAnimationOnTouch;

    Swift

    var resetsAnimationOnTouch: Bool { get set }

  • A Boolean value that determines whether the user may use pinch gestures to zoom in and out of the map.

    Declaration

    Objective-C

    @property (nonatomic) BOOL isZoomEnabled;

    Swift

    var isZoomEnabled: Bool { get set }

  • A Boolean value that determines whether the user may scroll around the map.

    Declaration

    Objective-C

    @property (nonatomic) BOOL isScrollEnabled;

    Swift

    var isScrollEnabled: Bool { get set }

  • A Boolean value that indicates whether the user may change pitch with gesture.

    Declaration

    Objective-C

    @property (nonatomic) BOOL isPitchEnabled;

    Swift

    var isPitchEnabled: Bool { get set }

  • A Boolean value that indicates whether the user uses may rotate map with gesture.

    Declaration

    Objective-C

    @property (nonatomic) BOOL isRotateEnabled;

    Swift

    var isRotateEnabled: Bool { get set }

  • A Boolean value that indicates whether the user touch map.

    Declaration

    Objective-C

    @property (nonatomic) BOOL isTouchActive;

    Swift

    var isTouchActive: Bool { get set }

  • tapGestureBlock is called for each tap gesture event.

    Declaration

    Objective-C

    @property (copy) GLMapGestureBlock _Nullable tapGestureBlock;

    Swift

    var tapGestureBlock: GLMapGestureBlock? { get set }

  • longPressGestureBlock is called for each long press gesture event.

    Declaration

    Objective-C

    @property (copy) GLMapGestureBlock _Nullable longPressGestureBlock;

    Swift

    var longPressGestureBlock: GLMapGestureBlock? { get set }

  • panGestureBlock is called for each pan gesture event.

    Declaration

    Objective-C

    @property (copy) GLMapGestureBlock _Nullable panGestureBlock;

    Swift

    var panGestureBlock: GLMapGestureBlock? { get set }

  • bboxChangedBlock is called when the map is moved or zoomed.

    Declaration

    Objective-C

    @property (copy) GLMapBBoxChangedBlock _Nullable bboxChangedBlock;

    Swift

    var bboxChangedBlock: GLMapBBoxChangedBlock? { get set }

  • mapDidMoveBlock is called when an animation or deceleration ends.

    Declaration

    Objective-C

    @property (copy) GLMapBBoxChangedBlock _Nullable mapDidMoveBlock;

    Swift

    var mapDidMoveBlock: GLMapBBoxChangedBlock? { get set }

  • mapDidMoveBlock is called when an animation or deceleration ends.

    Declaration

    Objective-C

    @property (copy) GLMapValueChangedBlock _Nullable onMapCenterChangedByGesture;

    Swift

    var onMapCenterChangedByGesture: GLMapValueChangedBlock? { get set }

  • mapDidMoveBlock is called when an animation or deceleration ends.

    Declaration

    Objective-C

    @property (copy) GLMapValueChangedBlock _Nullable onMapAngleChangedByGesture;

    Swift

    var onMapAngleChangedByGesture: GLMapValueChangedBlock? { get set }

  • mapDidMoveBlock is called when an animation or deceleration ends.

    Declaration

    Objective-C

    @property (copy) GLMapValueChangedBlock _Nullable onMapZoomChangedByGesture;

    Swift

    var onMapZoomChangedByGesture: GLMapValueChangedBlock? { get set }

  • mapDidMoveBlock is called when an animation or deceleration ends.

    Declaration

    Objective-C

    @property (copy) GLMapValueChangedBlock _Nullable onMapPitchChangedByGesture;

    Swift

    var onMapPitchChangedByGesture: GLMapValueChangedBlock? { get set }

  • visibleTilesChangedBlock is called when the set of visible tiles changes.

    Declaration

    Objective-C

    @property (copy) GLMapVisibleTilesChangedBlock _Nullable visibleTilesChangedBlock;

    Swift

    var visibleTilesChangedBlock: GLMapVisibleTilesChangedBlock? { get set }

  • centerTileStateChangedBlock is called when the centerTileState changes.

    Declaration

    Objective-C

    @property (copy) dispatch_block_t _Nullable centerTileStateChangedBlock;

    Swift

    var centerTileStateChangedBlock: (() -> Void)? { get set }

  • Bounding box of the map.

    Declaration

    Objective-C

    @property (readonly) GLMapBBox bbox;

    Swift

    var bbox: GLMapBBox { get }

  • Visible area of the map with applied safe area.

    Declaration

    Objective-C

    @property (readonly) GLMapRect visibleMapRect;

    Swift

    var visibleMapRect: GLMapRect { get }

  • Sets the position of map attribution.

    Declaration

    Objective-C

    @property GLMapPlacement attributionPosition;

    Swift

    var attributionPosition: GLMapPlacement { get set }

  • Checks if it’s a position of attribution label and opens URL.

    Declaration

    Objective-C

    - (BOOL)checkTapOnAttribution:(CGPoint)point;

    Swift

    func checkTap(onAttribution point: CGPoint) -> Bool

    Parameters

    point

    location in map view.

    Return Value

    YES if it’s a point inside of a attribution.

  • Calculates the bounding box of the map with insets.

    Declaration

    Objective-C

    - (GLMapBBox)bboxWithInsets:(PlatformEdgeInsets)insets;

    Swift

    func bbox(with insets: PlatformEdgeInsets) -> GLMapBBox

    Parameters

    insets

    Insets in points.

    Return Value

    Bounding box.

User Location

  • The last location received by GLMapView.

    Declaration

    Objective-C

    @property (readonly) CLLocation *_Nullable lastLocation;

    Swift

    var lastLocation: CLLocation? { get }

  • Determines if the user location is displayed or not. If set to YES, the user’s location is displayed.

    Declaration

    Objective-C

    @property (nonatomic) BOOL showUserLocation;

    Swift

    var showUserLocation: Bool { get set }

  • Sets alternative user location images.

    Declaration

    Objective-C

    - (void)setUserLocationImage:(PlatformImage *_Nullable)locationImage
               movementImage:(PlatformImage *_Nullable)movementImage;

    Swift

    func setUserLocationImage(_ locationImage: NSImage?, movementImage: NSImage?)

    Parameters

    locationImage

    New user location image. If nil, the old image is left unchanged.
    movementImage

    New user movement image. If nil, the old image is left unchanged.

Style

  • Sets the map style.

    Declaration

    Objective-C

    - (void)setStyle:(nonnull GLMapVectorCascadeStyle *)style;

    Swift

    func setStyle(_ style: GLMapVectorCascadeStyle)

    Parameters

    style

    The style to set.

  • Sets the scale of the font loaded from the styleBundle. By default, fontScale is 1.0.

    Declaration

    Objective-C

    - (void)setFontScale:(float)fontScale;

    Swift

    func setFontScale(_ fontScale: Float)

  • Base source of tiles. The default is vector source.

    Declaration

    Objective-C

    @property (copy) GLMapTileSource *_Nonnull base;

    Swift

    @NSCopying var base: GLMapTileSource { get set }

  • Tiles that are drawn over base tiles.

    Declaration

    Objective-C

    @property (copy) NSArray<GLMapTileSource *> *_Nullable overlays;

    Swift

    var overlays: [GLMapTileSource]? { get set }

  • Draws elevation lines. The default is false.

    Declaration

    Objective-C

    @property BOOL drawElevationLines;

    Swift

    var drawElevationLines: Bool { get set }

  • Draws hillshades. The default is false.

    Declaration

    Objective-C

    @property BOOL drawHillshades;

    Swift

    var drawHillshades: Bool { get set }

  • Draws slopes. The default is false.

    Declaration

    Objective-C

    @property BOOL drawSlopes;

    Swift

    var drawSlopes: Bool { get set }

  • Forces reloading of all tiles. Call this function after modifying the map style with functions loadStyle*.

    Declaration

    Objective-C

    - (void)reloadTiles;

    Swift

    func reloadTiles()

  • Removes all tiles. Useful for reducing memory usage in background mode.

    Declaration

    Objective-C

    - (void)removeAllTiles;

    Swift

    func removeAllTiles()

Configuring the Map Position

  • Origin point of the map coordinate system (X, Y). Changing the values in this property between 0 and 1 in relative coordinates describes the point of GLMapView, which is considered as a center point for mapCenter and setMapCenter:animated:.

    See

    mapCenter, setMapCenter:

    Declaration

    Objective-C

    @property CGPoint mapOrigin;

    Swift

    var mapOrigin: CGPoint { get set }

  • Coordinates of the origin point of the map.

    See

    mapOrigin

    Declaration

    Objective-C

    @property GLMapPoint mapCenter;

    Swift

    var mapCenter: GLMapPoint { get set }

  • Coordinates of the origin point of the map.

    See

    mapOrigin

    Declaration

    Objective-C

    @property GLMapGeoPoint mapGeoCenter;

    Swift

    var mapGeoCenter: GLMapGeoPoint { get set }

  • The current zoom of the map view.

    Declaration

    Objective-C

    @property double mapZoom;

    Swift

    var mapZoom: Double { get set }

  • The current zoom level of the map view.

    Declaration

    Objective-C

    @property double mapZoomLevel;

    Swift

    var mapZoomLevel: Double { get set }

  • The maximum possible value of mapZoom. The map won’t zoom closer.

    Declaration

    Objective-C

    @property double maxZoom;

    Swift

    var maxZoom: Double { get set }

  • The map rotation angle from 0° to 360°.

    Declaration

    Objective-C

    @property float mapAngle;

    Swift

    var mapAngle: Float { get set }

  • The map pitch angle.

    Declaration

    Objective-C

    @property float mapPitch;

    Swift

    var mapPitch: Float { get set }

  • Captures the state of the map for search (screenScale, mapCenter, zoom, etc.).

    Declaration

    Objective-C

    @property (readonly) GLMapViewState *_Nonnull state;

    Swift

    var state: GLMapViewState { get }

  • Starts the animation described in the block.

    Declaration

    Objective-C

    - (nonnull GLMapAnimation *)animate:(nonnull GLMapAnimationBlock)animations;

    Swift

    func animate(_ animations: (GLMapAnimation) -> Void) -> GLMapAnimation

    Parameters

    animations

    The block with animations. You can set animation params using the block param.

  • Starts the animation described in the block.

    Declaration

    Objective-C

    - (nonnull GLMapAnimation *)animate:(nonnull GLMapAnimationBlock)animations
                     withCompletion:
                         (GLMapAnimationCompletionBlock _Nullable)completion;

    Swift

    func animate(_ animations: (GLMapAnimation) -> Void, withCompletion completion: GLMapAnimationCompletionBlock? = nil) -> GLMapAnimation

    Parameters

    animations

    The block with animations. You can set animation params using the block param.
    completion

    The completion block. It’s called when the animation ends or is canceled.

  • Starts the animation.

    Declaration

    Objective-C

    - (void)startAnimation:(nonnull GLMapAnimation *)animation;

    Swift

    func start(_ animation: GLMapAnimation)

    Parameters

    animation

    The animation to start.

  • Cancels all map position, zoom, and angle animations.

    Declaration

    Objective-C

    - (void)cancelMapAnimations;

    Swift

    func cancelMapAnimations()

  • Calculates the map zoom to fit the bounding box in the view with the given size.

    Warning

    If the bounding box size is 0, returns +inf.

    Declaration

    Objective-C

    - (double)mapZoomForBBox:(GLMapBBox)bbox viewSize:(CGSize)size;

    Swift

    func mapZoom(for bbox: GLMapBBox, viewSize size: CGSize) -> Double

  • Calculates the map zoom to fit the current view.

    Warning

    If the bounding box size is 0, returns +inf.

    Declaration

    Objective-C

    - (double)mapZoomForBBox:(GLMapBBox)bbox;

    Swift

    func mapZoom(for bbox: GLMapBBox) -> Double

  • Enables clipping of the visible map area.

    Declaration

    Objective-C

    - (void)enableClipping:(GLMapBBox)bbox
              minLevel:(float)minLevel
              maxLevel:(float)maxLevel;

    Swift

    func enableClipping(_ bbox: GLMapBBox, minLevel: Float, maxLevel: Float)

    Parameters

    bbox

    Clipping bounding box to set.
    minLevel

    Minimum zoom level.
    maxLevel

    Maximum zoom level.

  • Disables clipping of the visible map area.

    Declaration

    Objective-C

    - (void)disableClipping;

    Swift

    func disableClipping()

  • Checks if clipping is enabled.

    Declaration

    Objective-C

    - (BOOL)isClippingEnabled;

    Swift

    func isClippingEnabled() -> Bool

    Return Value

    True if enabled.

Converting map coordinates

  • Converts a point on the screen to an internal map coordinate.

    Declaration

    Objective-C

    - (GLMapPoint)makeMapPointFromDisplayPoint:(CGPoint)displayPoint;

    Swift

    func makeMapPoint(fromDisplay displayPoint: CGPoint) -> GLMapPoint

    Parameters

    displayPoint

    The point you want to convert.

    Return Value

    The internal map coordinate of the specified point.

  • Converts a distance between two points on the screen to an internal map coordinate at the current map zoom.

    Declaration

    Objective-C

    - (GLMapPoint)makeMapPointFromDisplayDelta:(CGPoint)displayDelta;

    Swift

    func makeMapPoint(fromDisplayDelta displayDelta: CGPoint) -> GLMapPoint

    Parameters

    displayDelta

    The delta you want to convert.

    Return Value

    The delta in internal map coordinates.

  • Converts a distance between two points on the screen to an internal map coordinate.

    Declaration

    Objective-C

    - (GLMapPoint)makeMapPointFromDisplayDelta:(CGPoint)displayDelta
                                andMapZoom:(double)mapZoom
                               andMapAngle:(float)mapAngle;

    Swift

    func makeMapPoint(fromDisplayDelta displayDelta: CGPoint, andMapZoom mapZoom: Double, andMapAngle mapAngle: Float) -> GLMapPoint

    Parameters

    displayDelta

    The delta you want to convert.
    mapZoom

    Zoom of map.
    mapAngle

    Angle of map.

    Return Value

    The delta in internal map coordinates.

  • Converts a geo point to the point on the screen.

    Declaration

    Objective-C

    - (CGPoint)makeDisplayPointFromGeoPoint:(GLMapGeoPoint)geoPoint;

    Swift

    func makeDisplayPoint(from geoPoint: GLMapGeoPoint) -> CGPoint

    Parameters

    geoPoint

    The geo point you want to convert.

    Return Value

    The corresponding point on the screen.

  • Converts a point on the screen to a geo point.

    Declaration

    Objective-C

    - (GLMapGeoPoint)makeGeoPointFromDisplayPoint:(CGPoint)displayPoint;

    Swift

    func makeGeoPoint(fromDisplay displayPoint: CGPoint) -> GLMapGeoPoint

    Parameters

    displayPoint

    Point on the screen you want to convert.

    Return Value

    The corresponding geo point.

  • Converts an internal map coordinate to the point on the screen.

    Declaration

    Objective-C

    - (CGPoint)makeDisplayPointFromMapPoint:(GLMapPoint)mapPoint;

    Swift

    func makeDisplayPoint(from mapPoint: GLMapPoint) -> CGPoint

    Parameters

    mapPoint

    The map point you want to convert.

    Return Value

    The corresponding point on the screen.

  • Converts geo coordinates to the internal point.

    Declaration

    Objective-C

    + (GLMapPoint)makeMapPointFromGeoPoint:(GLMapGeoPoint)geoPoint;

    Swift

    class func makeMapPoint(from geoPoint: GLMapGeoPoint) -> GLMapPoint

    Parameters

    geoPoint

    Geo point you want to convert.

    Return Value

    Corresponding point in map coordinates.

  • Converts an internal point to geo coordinates.

    Declaration

    Objective-C

    + (GLMapGeoPoint)makeGeoPointFromMapPoint:(GLMapPoint)mapPoint;

    Swift

    class func makeGeoPoint(from mapPoint: GLMapPoint) -> GLMapGeoPoint

    Parameters

    mapPoint

    Point in map coordinates.

    Return Value

    Corresponding point in geo coordinates.

  • Converts distance in meters to pixels on the screen.

    Declaration

    Objective-C

    - (double)makePixelsFromMeters:(double)meters;

    Swift

    func makePixels(fromMeters meters: Double) -> Double

    Parameters

    meters

    Distance in meters.

    Return Value

    Distance in pixels.

  • Converts distance in pixels on the screen to meters.

    Declaration

    Objective-C

    - (double)makeMetersFromPixels:(double)pixels;

    Swift

    func makeMeters(fromPixels pixels: Double) -> Double

    Parameters

    pixels

    Distance in pixels.

    Return Value

    Distance in meters.

  • Converts distance in meters to map coordinates.

    Declaration

    Objective-C

    - (double)makeInternalFromMeters:(double)meters;

    Swift

    func makeInternal(fromMeters meters: Double) -> Double

    Parameters

    meters

    Distance in meters.

    Return Value

    Distance in map coordinates.

  • Converts distance in map coordinates to meters.

    Declaration

    Objective-C

    - (double)makeMetersFromInternal:(double)internal;

    Swift

    func makeMeters(fromInternal internal: Double) -> Double

    Parameters

    internal

    Distance in map coordinates.

    Return Value

    Distance in meters.

  • Converts distance in pixels to map coordinates.

    Declaration

    Objective-C

    - (double)makeInternalFromPixels:(double)pixels;

    Swift

    func makeInternal(fromPixels pixels: Double) -> Double

    Parameters

    pixels

    Distance in pixels.

    Return Value

    Distance in map coordinates.

  • Converts distance in map coordinates to pixels.

    Declaration

    Objective-C

    - (double)makePixelsFromInternal:(double)internal;

    Swift

    func makePixels(fromInternal internal: Double) -> Double

    Parameters

    internal

    Distance in map coordinates.

    Return Value

    Distance in pixels.

Vector Objects

  • Adds the GLMapDrawObject to the map view. This method must be called on the main thread.

    For adding individual objects to the map, it’s recommended to use GLMapVectorObjectLayer and GLMapMarkerLayer, which can be added to GLMapView. Drawing 1000 objects within one layer is optimized for a single GPU call. Adding 1000 objects each in their own layer will result in 1000 GPU calls, significantly impacting FPS.

    Declaration

    Objective-C

    - (void)add:(nonnull GLMapDrawObject *)drawObject;

    Swift

    func add(_ drawObject: GLMapDrawObject)

    Parameters

    drawObject

    The object to add.

  • Removes the previously added GLMapDrawObject from the map view. This method must be called on the main thread.

    Declaration

    Objective-C

    - (void)remove:(nonnull GLMapDrawObject *)drawObject;

    Swift

    func remove(_ drawObject: GLMapDrawObject)

    Parameters

    drawObject

    The object to be removed.

  • Changes draw order of previously added GLMapDrawObject. This method must be called on the main thread.

    Declaration

    Objective-C

    - (void)change:(nonnull GLMapDrawObject *)drawObject
     drawOrder:(int32_t)drawOrder;

    Swift

    func change(_ drawObject: GLMapDrawObject, drawOrder: Int32)

    Parameters

    drawObject

    The object to be changed.
    drawOrder

    new draw order

  • Adds or updates the area where text (and associated icons) must not be drawn. To add a 20x20 pt forbidden area around a specific point on the map, pass an offset of 10,10 and a size of 20,20. The forbidden area will be 10 pt in all directions from the origin point.

    Declaration

    Objective-C

    - (void)addTextForbiddenArea:(int32_t)name
                      origin:(GLMapPoint)origin
                      offset:(CGPoint)offset
                        size:(CGSize)size;

    Swift

    func addTextForbiddenArea(_ name: Int32, origin: GLMapPoint, offset: CGPoint, size: CGSize)

    Parameters

    name

    Unique name for the area.
    origin

    Origin of the area.
    offset

    Offset of the area from the origin (in points). Axes direction is bottom left.
    size

    Size of the area (in points).

  • Removes the area.

    Declaration

    Objective-C

    - (void)removeTextForbiddenArea:(int32_t)name;

    Swift

    func removeTextForbiddenArea(_ name: Int32)

    Parameters

    name

    The name of the area.

  • Map locale settings. The set of supported locales is returned by [GLMapLocaleSettings supportedLocales]. For example, to set the map languages priority to English, Deutsch, and native: [_mapView setLocaleSettings:[[GLMapLocaleSettings alloc] initWithLocalesOrder:@[@“en”, @“de”, @“native”]]]; Then, reload the tiles to apply new locale settings: [_mapView reloadTiles]; The default value is the supported languages from [NSLocale preferredLanguages].

    Declaration

    Objective-C

    @property (strong) GLMapLocaleSettings *_Nonnull localeSettings;

    Swift

    var localeSettings: GLMapLocaleSettings { get set }

  • Defines the visible part of the map. Useful for interactive objects like balloons.

    Declaration

    Objective-C

    - (PlatformEdgeInsets)visibleMapInsets;

    Swift

    func visibleMapInsets() -> PlatformEdgeInsets

  • Changes zoom level with focus point

    Declaration

    Objective-C

    - (void)changeZoomLevel:(int)diff focus:(GLMapPoint)focus;

    Swift

    func changeZoomLevel(_ diff: Int32, focus: GLMapPoint)

    Parameters

    diff

    - number of zoom levels to change
    focus

    - focus point