HERE Android SDK Developer's Guide

MapView

The class MapView is a member of com.here.android.mpa.mapping .

Class Summary

public class MapView

extends java.lang.Object

Represents a map view.

[For complete information, see the section Class Details]

See also:

MapActivity

android.view.ViewGroup

Constructor Summary

Table 1. Constructors in MapView
Constructors

MapView (Context context)

Constructor that initializes the context.

MapView (Context context, AttributeSet attrs)

Constructor that initializes the context and a set of attributes.

Method Summary

Table 2. Methods in MapView
Methods

public void addOnMapRenderListener (OnMapRenderListener listener)

Adds a OnMapRenderListener to listen for map render events.

protected void dispatchRestoreInstanceState (SparseArray container)

Override to prevent thawing of any child views.

protected void dispatchSaveInstanceState (SparseArray container)

Override to prevent freezing of any child views.

public ViewRect getClipRect ()

Gets the ViewRect representing the clip rectangle for the MapView .

public Rect getCopyrightBoundaryRect ()

Gets the current rectangle relative to the MapView's boundary as a container for the HERE copyright logo.

public int getCopyrightLogoHeight ()

Gets the height of the copyright logo.

public CopyrightLogoPosition getCopyrightLogoPosition ()

Gets the current position for the HERE copyright logo.

public int getCopyrightLogoVisibility ()

Gets the visibility of the HERE copyright logo.

public int getCopyrightLogoWidth ()

Gets the width of the copyright logo.

public int getCopyrightMargin ()

Gets the current margin, in pixels, for the HERE copyright logo, an offset from the edge of the visible map area to the edge of the logo.

public Map getMap ()

Returns the instance of Map associated with this MapView

public MapGesture getMapGesture ()

Gets the MapGesture representing the current gesture handler for the MapView .

public PositionIndicator getPositionIndicator ()

Returns the PositionIndicator instance that renders the current position with a marker.

public void getScreenCapture (OnScreenCaptureListener listener)

Gets the full screen bitmap for the MapView.

protected void onLayout (boolean changed, int left, int top, int right, int bottom)

For documentation, see android.view.ViewGroup

protected void onMeasure (int widthMeasureSpec, int heightMeasureSpec)

For documentation, see android.view.ViewGroup

public void onPause ()

Propagates an activity's onPause() event to the view.

public void onRestoreInstanceState (Parcelable state)

Callback indicating that a stored view state was restored (e.g.

public void onResume ()

Propagates an activity's onResume() event to the view.

public Parcelable onSaveInstanceState ()

Callback indicating that the internal state of a view was saved for later use (e.g.

public void removeOnMapRenderListener (OnMapRenderListener listener)

Removes an existing OnMapRenderListener.

public void setClipRect (ViewRect rect, PointF transformCenter)

Sets a clipping rectangle to the MapView .

public void setClipRect (ViewRect rect)

Sets a clipping rectangle to the MapView .

public void setCopyrightBoundaryRect (Rect rect)

Sets a rectangle, in pixels, relative to the top left corner of the MapView's boundary, for the placement of the HERE copyright logo.

public void setCopyrightLogoPosition (CopyrightLogoPosition position)

Sets a position for the HERE copyright logo.

public void setCopyrightMargin (int margin)

Sets a margin, in pixels, for the HERE copyright logo, an offset from the edge of the visible map area (or copyright boundary rect, if used) to the edge of the logo (depending on the placement).

public void setMap (Map aMap)

Associates the graphical view element with a Map .

public void setMapMarkerDragListener (OnDragListener listener)

Sets a MapMarker.OnDragListener to be invoked whenever any MapMarker added onto a Map that is attached to this MapView is dragged.

public void setOnTouchListener (View.OnTouchListener listener)

Sets an OnTouchListener to be invoked whenever a touch event is sent to the MapView .

Class Details

Represents a map view. This is the "View" UI class designed to handle all UI-related use cases, including rendering and screen touch events.

Each MapView must be bound to a Map, and map-related objects should be persisted during application runtime. MapView objects live and expire according to the associated activity's lifecycle.

A MapView is defined in an Android layout XML file. For example:


   <com.here.android.mpa.mapping.MapView
     android:id="@+id/mapview"
     android:layout_width="fill_parent"
     android:layout_height="fill_parent"
     android:visibility="visible"/>
  

Each MapView should follow the regular android lifecycle. When an activity's onResume() and onPause() are called, the view should also be notified via calls from within those methods. Please take care in how much processing is done in the onResume() method of an activity. Performing significant amounts of processing may delay the view rendering in cases such as device orientation change. It is recommended to use a specifically designated handler for organizing the amount of processing to be done in such cases.

Note that MapView does not notify the MapEngine when it is paused or resumed. User of MapView is responsible for handling the pausing and resuming of the MapEngine if needed. Another option is to utilize the MapActivity class when creating an activity with a MapView.

Although this class inherits from ViewGroup , it is not advisable for users to add children to MapView as no layout actions will be performed on any added children views.

See also:

MapActivity

android.view.ViewGroup

Constructor Details

MapView (Context context)

Constructor that initializes the context.

Parameters:

  • context

    Context of the MapView

See also:

MapView(Context, AttributeSet)

android.content.Context

MapView (Context context, AttributeSet attrs)

Constructor that initializes the context and a set of attributes.

Parameters:

  • context

    Context of the MapView

  • attrs

    An AttributeSet representing attributes of the MapView

See also:

MapView(Context)

android.content.Context

android.util.AttributeSet

Method Details

public void addOnMapRenderListener (OnMapRenderListener listener)

Adds a OnMapRenderListener to listen for map render events.

Parameters:

  • listener

    A OnMapRenderListener to add to the MapView

See also:

removeOnMapRenderListener(OnMapRenderListener)

protected void dispatchRestoreInstanceState (SparseArray container)

Override to prevent thawing of any child views. As child views created and added to the view group dynamically have the same id as the parent, causing conflict when the state is saved, all child views are blocked from being saved. Instead, this container will manually trigger the save and restore.

Parameters:

  • container

protected void dispatchSaveInstanceState (SparseArray container)

Override to prevent freezing of any child views. As child views created and added to the view group dynamically have the same id as the parent, causing conflict when the state is saved, all child views are blocked from being saved. Instead, this container will manually trigger the save and restore.

Parameters:

  • container

public ViewRect getClipRect ()

Gets the ViewRect representing the clip rectangle for the MapView .

Returns:

The clip rectangle for rendering MapObject objects and similar map-related screen elements

public Rect getCopyrightBoundaryRect ()

Gets the current rectangle relative to the MapView's boundary as a container for the HERE copyright logo. null is returned unless a boundary rect has been set previously.

Returns:

The boundary rect (null if not set).

See also:

getClipRect()

setCopyrightBoundaryRect(Rect)

public int getCopyrightLogoHeight ()

Gets the height of the copyright logo.

This method only returns a valid value once a Map has been set to this view.

Returns:

The height of the copyright logo in pixels. Returns -1 if unavailable.

public CopyrightLogoPosition getCopyrightLogoPosition ()

Gets the current position for the HERE copyright logo.

Returns:

The position of the logo.

public int getCopyrightLogoVisibility ()

Gets the visibility of the HERE copyright logo. Copyright logo is defaulted to be visible. Once changed, the visibility of logo stays effective even when the screen is rotated or re-created.

Returns:

One of the two values View.VISIBLE or View.INVISIBLE to represent the copyright logo's visibility.

public int getCopyrightLogoWidth ()

Gets the width of the copyright logo.

This method only returns a valid value once a Map has been set to this view.

Returns:

The width of the copyright logo in pixels. Returns -1 if unavailable.

public int getCopyrightMargin ()

Gets the current margin, in pixels, for the HERE copyright logo, an offset from the edge of the visible map area to the edge of the logo.

This method only returns a valid value once a Map has been set to this view.

Returns:

The current offset from the edge of the MapView

public Map getMap ()

Returns the instance of Map associated with this MapView

Returns:

The Map object currently displayed in this view.

public MapGesture getMapGesture ()

Gets the MapGesture representing the current gesture handler for the MapView . Applications can intercept this object and override the default events.

Returns:

The MapGesture

public PositionIndicator getPositionIndicator ()

Returns the PositionIndicator instance that renders the current position with a marker. The position indicator should be used with PositioningManager.

Returns:

The PositionIndicator

public void getScreenCapture (OnScreenCaptureListener listener)

Gets the full screen bitmap for the MapView. This API can be used to capture a screen shot of the MapView. The API is asynchronous and will callback once the operation is completed via OnScreenCaptureListener. Note the MapView must be visible to create the screen capture.

Parameters:

protected void onLayout (boolean changed, int left, int top, int right, int bottom)

For documentation, see android.view.ViewGroup

Parameters:

  • changed
  • left
  • top
  • right
  • bottom

protected void onMeasure (int widthMeasureSpec, int heightMeasureSpec)

For documentation, see android.view.ViewGroup

Parameters:

  • widthMeasureSpec
  • heightMeasureSpec

public void onPause ()

Propagates an activity's onPause() event to the view. Applications can call this method within the onPause() method of any activity which has a MapView as part of its view hierarchy. Note that unlike MapFragment, MapView does not automatically handle the pausing and/or resuming of MapEngine. Owner of MapView is responsible to address the handling of onPause() if needed.

See also:

onPause()

onPause()

public void onRestoreInstanceState (Parcelable state)

Callback indicating that a stored view state was restored (e.g. to create a new MapView with the same state).

Parameters:

See also:

android.view.View.onRestoreInstanceState(Parcelable)

public void onResume ()

Propagates an activity's onResume() event to the view. Applications can call this method within the onResume() method of any activity which has a MapView as part of its view hierarchy. Note that unlike MapFragment, MapView does not automatically handle the pausing and/or resuming of MapEngine. Owner of MapView is responsible to address the handling of onResume() if needed.

See also:

onResume()

onResume()

public Parcelable onSaveInstanceState ()

Callback indicating that the internal state of a view was saved for later use (e.g. to create a new MapView with the same state).

Returns:

The android.os.Parcelable for storing the view state

See also:

android.view.View.onSaveInstanceState()

public void removeOnMapRenderListener (OnMapRenderListener listener)

Removes an existing OnMapRenderListener.

Parameters:

  • listener

    A OnMapRenderListener to remove from the MapView

public void setClipRect (ViewRect rect, PointF transformCenter)

Sets a clipping rectangle to the MapView .

The center of the map is not moved and remains at the center of the map control. Only the ViewRect specified here will be used for rendering.

Note that the size of the map remains the same as the size of the map control.

The clipping rectangle (and the view rectangle) is reset to full-screen upon screen rotation or upon recreating the screen.

Moreover, setting the clipping rectangle will reset the view rectangle to full-screen.

Parameters:

  • rect

    A ViewRect for rendering MapObject objects and similar map-related screen elements

  • transformCenter

    A PointF representing the center coordinate for map transformations such as zooming and rotation

Throws:

  • IllegalArgumentException

See also:

setClipRect(ViewRect)

public void setClipRect (ViewRect rect)

Sets a clipping rectangle to the MapView .

Note that the size of the map remains the same as the size of the map control.

The clipping rectangle (and the view rectangle) is reset to full-screen upon screen rotation or upon recreating the screen.

Parameters:

  • rect

    A ViewRect for rendering MapObject objects and similar map-related screen elements

Throws:

  • IllegalArgumentException

See also:

setClipRect(ViewRect, PointF)

public void setCopyrightBoundaryRect (Rect rect)

Sets a rectangle, in pixels, relative to the top left corner of the MapView's boundary, for the placement of the HERE copyright logo.

If the specified rectangle is not contained completely within the current visible map area, their area of intersection will be used instead of the specified rectangle's area. If the specified rectangle is outside the current visible map area, it will be ignored. The copyright logo and copyright margin must fit into the rectangle, otherwise specified rectangle will be ignored.

The copyright boundary rectangle is reset upon screen rotation or upon screen re-creation.

Parameters:

  • rect

    A Rect representing the rectangular container to position the copyright logo. Use null Rect to reset the boundary container.

public void setCopyrightLogoPosition (CopyrightLogoPosition position)

Sets a position for the HERE copyright logo. The current default is to place the logo at the center-bottom of the visible map view area.

Note: after the logo's position is set, it stays effective even when the screen is rotated or re-created.

Parameters:

  • position

    A CopyrightLogoPosition value representing the desired placement of the HERE copyright logo with respect to the visible map view area

public void setCopyrightMargin (int margin)

Sets a margin, in pixels, for the HERE copyright logo, an offset from the edge of the visible map area (or copyright boundary rect, if used) to the edge of the logo (depending on the placement). The logo and margin must fit into the visible area (or copyright bounding rect). Therefore, the maximum allowed margin value is: (bounding rect dimension - logo size) / 2. The default (minimum) margin value is 1/2 of logo width. A margin value smaller than the default will not be saved.

Parameters:

  • margin

    Desired offset from the edge of the MapView

See also:

setCopyrightBoundaryRect(Rect)

public void setMap (Map aMap)

Associates the graphical view element with a Map . Applications must call this method to bind the MapView and Map .

Note: the Map that gets passed as a parameter to this method could be null , in which case all listeners will be cleaned up.

Users are advised to call setMap(Map) with null to detach the map only after the onPause() is called to avoid memory leaks.

Parameters:

  • aMap

    A Map to associate with the MapView (could be null)

public void setMapMarkerDragListener (OnDragListener listener)

Sets a MapMarker.OnDragListener to be invoked whenever any MapMarker added onto a Map that is attached to this MapView is dragged.

Parameters:

public void setOnTouchListener (View.OnTouchListener listener)

Sets an OnTouchListener to be invoked whenever a touch event is sent to the MapView .

Parameters:

  • listener

    An OnTouchListener to set for the MapView

See also:

android.view.View.OnTouchListener