| java.lang.Object | ||||
| ↳ | android.view.View | |||
| ↳ | android.view.SurfaceView | |||
| ↳ | android.opengl.GLSurfaceView | |||
| ↳ | com.carto.ui.MapView | |||
Class Overview
MapView is a view class supporting map rendering and interaction.
Summary
|
[Expand]
Inherited Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
 From class
android.opengl.GLSurfaceView
| |||||||||||
|
From class
android.view.View
| |||||||||||
| Public Constructors | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
MapView(Context context)
Creates a new MapView object from a context object.
| |||||||||||
|
MapView(Context context, AttributeSet attrs)
Creates a new MapView object from a context object and attributes.
| |||||||||||
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| void |
cancelAllTasks()
Cancels all qued tasks such as tile and vector data fetches.
| ||||||||||
| void |
clearAllCaches()
Releases memory occupied by all caches.
| ||||||||||
| void |
clearPreloadingCaches()
Releases the memory occupied by the preloading area.
| ||||||||||
| synchronized void |
delete()
Deletes the resources associated with the MapView.
| ||||||||||
| MapPos |
getFocusPos()
Returns the position that the camera is currently looking at.
| ||||||||||
| Layers |
getLayers()
Returns the Layers object, that can be used for adding and removing map layers.
| ||||||||||
| MapEventListener |
getMapEventListener()
Returns the map event listener.
| ||||||||||
| MapRenderer |
getMapRenderer()
Returns the MapRenderer object, that can be used for controlling rendering related options.
| ||||||||||
| float |
getMapRotation()
Returns the map rotation in degrees.
| ||||||||||
| Options |
getOptions()
Returns the Options object, that can be used for modifying various map options.
| ||||||||||
| float |
getTilt()
Returns the tilt angle in degrees.
| ||||||||||
| float |
getZoom()
Returns the zoom level.
| ||||||||||
| ScreenPos |
mapToScreen(MapPos mapPos)
Calculates the screen position corresponding to a map position, using the current view parameters.
| ||||||||||
| void |
moveToFitBounds(MapBounds mapBounds, ScreenBounds screenBounds, boolean integerZoom, float durationSeconds)
Animate the view parameters (focus position, tilt, rotation, zoom) so that the specified bounding box becomes fully visible.
| ||||||||||
| void |
moveToFitBounds(MapBounds mapBounds, ScreenBounds screenBounds, boolean integerZoom, boolean resetRotation, boolean resetTilt, float durationSeconds)
Animate the view parameters (focus position, tilt, rotation, zoom) so that the specified bounding box becomes fully visible.
| ||||||||||
| synchronized void | onDrawFrame(GL10 gl) | ||||||||||
| synchronized void | onSurfaceChanged(GL10 gl, int width, int height) | ||||||||||
| synchronized void | onSurfaceCreated(GL10 gl, EGLConfig config) | ||||||||||
| synchronized boolean | onTouchEvent(MotionEvent event) | ||||||||||
| void |
pan(MapVec deltaPos, float durationSeconds)
Pans the view relative to the current focus position.
| ||||||||||
| static boolean |
registerLicense(String licenseKey, Context context)
Registers the SDK license.
| ||||||||||
| void |
rotate(float deltaAngle, float durationSeconds)
Rotates the view relative to the current rotation value.
| ||||||||||
| void |
rotate(float deltaAngle, MapPos targetPos, float durationSeconds)
Rotates the view relative to the current rotation value.
| ||||||||||
| MapPos |
screenToMap(ScreenPos screenPos)
Calculates the map position corresponding to a screen position, using the current view parameters.
| ||||||||||
| void |
setFocusPos(MapPos pos, float durationSeconds)
Sets the new absolute focus position.
| ||||||||||
| void |
setMapEventListener(MapEventListener mapEventListener)
Sets the map event listener.
| ||||||||||
| void |
setMapRotation(float angle, MapPos targetPos, float durationSeconds)
Sets the new absolute rotation value.
| ||||||||||
| void |
setMapRotation(float angle, float durationSeconds)
Sets the new absolute rotation value.
| ||||||||||
| void |
setTilt(float tilt, float durationSeconds)
Sets the new absolute tilt value.
| ||||||||||
| void |
setZoom(float zoom, float durationSeconds)
Sets the new absolute zoom value.
| ||||||||||
| void |
setZoom(float zoom, MapPos targetPos, float durationSeconds)
Sets the new absolute zoom value.
| ||||||||||
| void |
tilt(float deltaTilt, float durationSeconds)
Tilts the view relative to the current tilt value.
| ||||||||||
| void |
zoom(float deltaZoom, MapPos targetPos, float durationSeconds)
Zooms the view relative to the current zoom value.
| ||||||||||
| void |
zoom(float deltaZoom, float durationSeconds)
Zooms the view relative to the current zoom value.
| ||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
From class
android.opengl.GLSurfaceView
| |||||||||||
|
From class
android.view.SurfaceView
| |||||||||||
|
From class
android.view.View
| |||||||||||
|
From class
java.lang.Object
| |||||||||||
|
From interface
android.graphics.drawable.Drawable.Callback
| |||||||||||
|
From interface
android.opengl.GLSurfaceView.Renderer
| |||||||||||
|
From interface
android.view.KeyEvent.Callback
| |||||||||||
|
From interface
android.view.SurfaceHolder.Callback
| |||||||||||
|
From interface
android.view.accessibility.AccessibilityEventSource
| |||||||||||
|
From interface
com.carto.ui.MapViewInterface
| |||||||||||
Public Constructors
public MapView (Context context)
Creates a new MapView object from a context object.
Parameters
| context | The context object. |
|---|
public MapView (Context context, AttributeSet attrs)
Creates a new MapView object from a context object and attributes.
Parameters
| context | The context object. |
|---|---|
| attrs | The attributes. |
Public Methods
public void cancelAllTasks ()
Cancels all qued tasks such as tile and vector data fetches. Tasks that have already started may continue until they finish. Tasks that are added after this method call are not affected.
public void clearAllCaches ()
Releases memory occupied by all caches. Calling this means that everything has to be fetched again, including the visible area.
public void clearPreloadingCaches ()
Releases the memory occupied by the preloading area. Calling this method releases some memory if preloading is enabled, but means that the area right outside the visible area has to be fetched again.
public synchronized void delete ()
Deletes the resources associated with the MapView. The method can be used to dispose native objects immediately, without waiting for next GC cycle.
public MapPos getFocusPos ()
Returns the position that the camera is currently looking at.
Returns
- The current focus position in the coordinate system of the base projection.
public Layers getLayers ()
Returns the Layers object, that can be used for adding and removing map layers.
Returns
- The Layer object.
public MapEventListener getMapEventListener ()
Returns the map event listener. May be null.
Returns
- The map event listener.
public MapRenderer getMapRenderer ()
Returns the MapRenderer object, that can be used for controlling rendering related options.
Returns
- the MapRenderer object.
public float getMapRotation ()
Returns the map rotation in degrees. 0 means looking north, 90 means west, -90 means east and 180 means south.
Returns
- The map rotation in degrees in range of (-180 .. 180].
public Options getOptions ()
Returns the Options object, that can be used for modifying various map options.
Returns
- the Option object.
public float getTilt ()
Returns the tilt angle in degrees. 0 means looking directly at the horizon, 90 means looking directly down.
Returns
- The tilt angle in degrees.
public float getZoom ()
Returns the zoom level. The value returned is never negative, 0 means absolutely zoomed out and all other values describe some level of zoom.
Returns
- The zoom level.
public ScreenPos mapToScreen (MapPos mapPos)
Calculates the screen position corresponding to a map position, using the current view parameters.
Parameters
| mapPos | The map position in base projection coordinate system. |
|---|
Returns
- The calculated screen position. Can be off-screen.
public void moveToFitBounds (MapBounds mapBounds, ScreenBounds screenBounds, boolean integerZoom, float durationSeconds)
Animate the view parameters (focus position, tilt, rotation, zoom) so that the specified bounding box becomes fully visible. This method does not work before the screen size is set.
Parameters
| mapBounds | The bounding box on the map to be made visible in the base projection's coordinate system. |
|---|---|
| screenBounds | The screen bounding box where to fit the map bounding box. |
| integerZoom | If true, then closest integer zoom level will be used. If false, exact fractional zoom level will be used. |
| durationSeconds | The duration in which the operation will be completed in seconds. |
public void moveToFitBounds (MapBounds mapBounds, ScreenBounds screenBounds, boolean integerZoom, boolean resetRotation, boolean resetTilt, float durationSeconds)
Animate the view parameters (focus position, tilt, rotation, zoom) so that the specified bounding box becomes fully visible. Also supports resetting the tilt and rotation angles over the course of the animation. This method does not work before the screen size is set.
Parameters
| mapBounds | The bounding box on the map to be made visible in the base projection's coordinate system. |
|---|---|
| screenBounds | The screen bounding box where to fit the map bounding box. |
| integerZoom | If true, then closest integer zoom level will be used. If false, exact fractional zoom level will be used. |
| resetRotation | If true, rotation will be reset. If false, current rotation will be kept. |
| resetTilt | If true, view will be untilted. If false, current tilt will be kept. |
| durationSeconds | The duration in which the operation will be completed in seconds. |
public synchronized void onDrawFrame (GL10 gl)
public synchronized void onSurfaceChanged (GL10 gl, int width, int height)
public synchronized void onSurfaceCreated (GL10 gl, EGLConfig config)
public synchronized boolean onTouchEvent (MotionEvent event)
public void pan (MapVec deltaPos, float durationSeconds)
Pans the view relative to the current focus position. The deltaPos vector is expected to be in the coordinate system of the base projection. The new calculated focus position will be clamped to the world bounds and to the bounds set by Options::setPanBounds. If durationSeconds > 0 the panning operation will be animated over time. If the previous panning animation has not finished by the time this method is called, it will be stopped.
Parameters
| deltaPos | The coordinate difference the map should be moved by. |
|---|---|
| durationSeconds | The duration in which the tilting operation will be completed in seconds. |
public static boolean registerLicense (String licenseKey, Context context)
Registers the SDK license. This class method and must be called before creating any actual MapView instances.
Parameters
| licenseKey | The license string provided for this application. |
|---|---|
| context | Application context for the license. |
Returns
- True if license is valid, false if not.
public void rotate (float deltaAngle, float durationSeconds)
Rotates the view relative to the current rotation value. Positive values rotate clockwise, negative values counterclockwise. The new calculated rotation value will be wrapped to the range of (-180 .. 180]. Rotations are ignored if Options::setRotatable is set to false. If durationSeconds > 0 the rotating operation will be animated over time. If the previous rotating animation has not finished by the time this method is called, it will be stopped.
Parameters
| deltaAngle | The delta angle value in degrees. |
|---|---|
| durationSeconds | The duration in which the zooming operation will be completed in seconds. |
public void rotate (float deltaAngle, MapPos targetPos, float durationSeconds)
Rotates the view relative to the current rotation value. Positive values rotate clockwise, negative values counterclockwise. The new calculated rotation value will be wrapped to the range of (-180 .. 180]. Rotations are ignored if Options::setRotatable is set to false. Rotating is done around the specified target position, keeping it at the same location on the screen. If durationSeconds > 0 the rotating operation will be animated over time. If the previous rotating animation has not finished by the time this method is called, it will be stopped.
Parameters
| deltaAngle | The delta angle value in degrees. |
|---|---|
| targetPos | The zooming target position in the coordinate system of the base projection. |
| durationSeconds | The duration in which the zooming operation will be completed in seconds. |
public MapPos screenToMap (ScreenPos screenPos)
Calculates the map position corresponding to a screen position, using the current view parameters.
Parameters
| screenPos | The screen position. |
|---|
Returns
- The calculated map position in base projection coordinate system. If the given screen position is not on the map, then NaNs are returned.
public void setFocusPos (MapPos pos, float durationSeconds)
Sets the new absolute focus position. The new focus position is expected to be in the coordinate system of the base projection. The new focus position will be clamped to the world bounds and to the bounds set by Options::setPanBounds. If durationSeconds > 0 the panning operation will be animated over time. If the previous panning animation has not finished by the time this method is called, it will be stopped.
Parameters
| pos | The new focus point position in base coordinate system. |
|---|---|
| durationSeconds | The duration in which the tilting operation will be completed in seconds. |
public void setMapEventListener (MapEventListener mapEventListener)
Sets the map event listener. If a null pointer is passed no map events will be generated. The default is null.
Parameters
| mapEventListener | The new map event listener. |
|---|
public void setMapRotation (float angle, MapPos targetPos, float durationSeconds)
Sets the new absolute rotation value. 0 means look north, 90 means west, -90 means east and 180 means south. The rotation value will be wrapped to the range of (-180 .. 180]. Rotations are ignored if Options::setRotatable is set to false. Rotating is done around the specified target position, keeping it at the same location on the screen. If durationSeconds > 0 the rotating operation will be animated over time. If the previous rotating animation has not finished by the time this method is called, it will be stopped.
Parameters
| angle | The new absolute rotation angle value in degrees. |
|---|---|
| targetPos | The zooming target position in the coordinate system of the base projection. |
| durationSeconds | The duration in which the zooming operation will be completed in seconds. |
public void setMapRotation (float angle, float durationSeconds)
Sets the new absolute rotation value. 0 means look north, 90 means west, -90 means east and 180 means south. The rotation value will be wrapped to the range of (-180 .. 180]. Rotations are ignored if Options::setRotatable is set to false. If durationSeconds > 0 the rotating operation will be animated over time. If the previous rotating animation has not finished by the time this method is called, it will be stopped.
Parameters
| angle | The new absolute rotation angle value in degrees. |
|---|---|
| durationSeconds | The duration in which the zooming operation will be completed in seconds. |
public void setTilt (float tilt, float durationSeconds)
Sets the new absolute tilt value. 0 means look directly at the horizon, 90 means look directly down. The minimum tilt angle is 30 degrees and the maximum is 90 degrees. The tilt value can be further constrained by the Options::setTiltRange method. Values exceeding these ranges will be clamped. If durationSeconds > 0 the tilting operation will be animated over time. If the previous tilting animation has not finished by the time this method is called, it will be stopped.
Parameters
| tilt | The new absolute tilt value in degrees. |
|---|---|
| durationSeconds | The duration in which the tilting operation will be completed in seconds. |
public void setZoom (float zoom, float durationSeconds)
Sets the new absolute zoom value. The minimum zoom value is 0, which means absolutely zoomed out and the maximum zoom value is 24. The zoom value can be further constrained by the Options::setZoomRange method. Values exceeding these ranges will be clamped. If durationSeconds > 0 the zooming operation will be animated over time. If the previous zooming animation has not finished by the time this method is called, it will be stopped.
Parameters
| zoom | The new absolute zoom value. |
|---|---|
| durationSeconds | The duration in which the zooming operation will be completed in seconds. |
public void setZoom (float zoom, MapPos targetPos, float durationSeconds)
Sets the new absolute zoom value. The minimum zoom value is 0, which means absolutely zoomed out and the maximum zoom value is 24. The zoom value can be further constrained by the Options::setZoomRange method. Values exceeding these ranges will be clamped. Zooming is done towards the specified target position, keeping it at the same location on the screen. If durationSeconds > 0, the zooming operation will be animated over time. If the previous zooming animation has not finished by the time this method is called, it will be stopped.
Parameters
| zoom | The new absolute zoom value. |
|---|---|
| targetPos | The zooming target position in the coordinate system of the base projection. |
| durationSeconds | The duration in which the zooming operation will be completed in seconds. |
public void tilt (float deltaTilt, float durationSeconds)
Tilts the view relative to the current tilt value. Positive values tilt the view down towards the map, negative values tilt the view up towards the horizon. The new calculated tilt value will be clamped to the range of [30 .. 90] and to the range set by Options::setZoomRange. If durationSeconds > 0 the tilting operation will be animated over time. If the previous tilting animation has not finished by the time this method is called, it will be stopped.
Parameters
| deltaTilt | The number of degrees the camera should be tilted by. |
|---|---|
| durationSeconds | The duration in which the tilting operation will be completed in seconds. |
public void zoom (float deltaZoom, MapPos targetPos, float durationSeconds)
Zooms the view relative to the current zoom value. Positive values zoom in, negative values zoom out. The new calculated zoom value will be clamped to the range of [0 .. 24] and to the range set by Options::setZoomRange. Zooming is done towards the specified target position, keeping it at the same location on the screen. If durationSeconds > 0 the zooming operation will be animated over time. If the previous zooming animation has not finished by the time this method is called, it will be stopped.
Parameters
| deltaZoom | The delta zoom value. |
|---|---|
| targetPos | The zooming target position in the coordinate system of the base projection. |
| durationSeconds | The duration in which the zooming operation will be completed in seconds. |
public void zoom (float deltaZoom, float durationSeconds)
Zooms the view relative to the current zoom value. Positive values zoom in, negative values zoom out. The new calculated zoom value will be clamped to the range of [0 .. 24] and to the range set by Options::setZoomRange. If durationSeconds > 0 the zooming operation will be animated over time. If the previous zooming animation has not finished by the time this method is called, it will be stopped.
Parameters
| deltaZoom | The delta zoom value. |
|---|---|
| durationSeconds | The duration in which the zooming operation will be completed in seconds. |