HERE Android SDK Developer's Guide

MapFragment

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

Class Summary

public class MapFragment

extends java.lang.Object

A fragment class that automatically creates a Map and handles map UI interactions such as panning and zooming.

[For complete information, see the section Class Details]

See also:

android.app.Fragment

Constructor Summary

Table 1. Constructors in MapFragment
Constructors

MapFragment ()

Constructor

Method Summary

Table 2. Methods in MapFragment
Methods

public void addOnMapRenderListener (OnMapRenderListener listener)

Adds a OnMapRenderListener to listen for map render events.

public ViewRect getClipRect ()

Returns the ViewRect representing the clip rectangle for this MapFragment.

public Rect getCopyrightBoundaryRect ()

Gets the current HERE copyright logo's boundary rectangle.

public int getCopyrightLogoHeight ()

Returns the height of the copyright logo.

public CopyrightLogoPosition getCopyrightLogoPosition ()

Returns the on-screen position of the HERE copyright logo as a CopyrightLogoPosition value.

public int getCopyrightLogoWidth ()

Returns the width of the copyright logo.

public int getCopyrightMargin ()

Returns the current margin for the HERE copyright logo, in number of pixels, as 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 map fragment

public MapGesture getMapGesture ()

Returns the MapGesture object representing the current gesture handler for the MapFragment.

public PositionIndicator getPositionIndicator ()

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

public void getScreenCapture (OnScreenCaptureListener listener)

Returns the full screen bitmap for the MapFragment.

public void init (OnEngineInitListener listener)

Initializes the MapEngine and displays a map that occupies the entire MapFragment's view rectangle.

public void init (Context context, MapVariant variant, OnEngineInitListener listener)

Deprecated: As of SDK 3.4.

Initializes the MapEngine and displays a map that occupies the entire MapFragment's view rectangle.

public void init (Context context, OnEngineInitListener listener)

Deprecated: As of SDK 3.4.

Initializes the MapEngine and displays a map that occupies the entire MapFragment's view rectangle.

public void init (ApplicationContext context, OnEngineInitListener listener)

Initializes the MapEngine and displays a map that occupies the entire MapFragment's view rectangle.

public View onCreateView (LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState)

Called when this fragment is first attached to its Activity .

public void onDestroyView ()

Called when the view previously created by onCreateView(LayoutInflater, ViewGroup, Bundle) has been detached from this fragment.

public void onInflate (Activity activity, AttributeSet attrs, Bundle savedInstanceState)

Deprecated: Deprecated as of release 3.5.

Called when this fragment is being created as part of a view layout inflation, typically from setting the content view of an activity.

public void onInflate (Context context, AttributeSet attrs, Bundle savedInstanceState)

Called when this fragment is being created as part of a view layout inflation, typically from setting the content view of an activity.

public void onPause ()

Called when this fragment is no longer resumed.

public void onResume ()

Called when this fragment is visible to the user and actively running.

public void onSaveInstanceState (Bundle outState)

Called when this fragment has been asked to save its current dynamic state.

public void removeOnMapRenderListener (OnMapRenderListener listener)

Removes an existing OnMapRenderListener.

public void setClipRect (ViewRect rect, PointF transformCenter)

Sets a clipping rectangle to the MapFragment.

public void setClipRect (ViewRect rect)

Sets a clipping rectangle to this MapFragment.

public void setCopyrightBoundaryRect (Rect rect)

Sets a rectangle, in pixels, relative to the top left corner of the MapFragment'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 for the HERE copyright logo, in number of pixels, as an offset from the edge of the visible map area to the edge of the logo (depending on the placement).

public void setMapMarkerDragListener (OnDragListener listener)

Sets a MapMarker.OnDragListener to be invoked whenever any MapMarker on a Map that is attached to this fragment is dragged.

public void setOnTouchListener (View.OnTouchListener listener)

Sets an android.view.OnTouchListener to be invoked whenever a touch event is sent to the MapFragment.

Class Details

A fragment class that automatically creates a Map and handles map UI interactions such as panning and zooming. MapFragment extends the Android Fragment class and retains its lifecycle behaviors.

Upon the initialization of MapFragment , a Map object is automatically created and bound to the fragment. This Map object is then persisted throughout the MapFragment 's lifetime. Since MapFragment internally calls Fragment.setRetainInstance(true) , the Map will retain any properties applied to it during an application's lifetime.

MapFragment objects have their own lifecycle, state, and back stack, thus it is unsafe to assume objects returned by a MapFragment instance (with the exception of Map ) will be available throughout the lifetime of its attached activity.

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


   <fragment
    class="com.here.android.mpa.mapping.MapFragment"
     android:id="@+id/map_fragment"
     android:layout_width="fill_parent"
     android:layout_height="fill_parent" />
  

Note: MapFragment automatically handles MapEngine pausing and resuming during activity state changes, thus it is not necessary for the activity that owns MapFragment instances to manually call onPause() or onResume() during the activity's onPause() and onResume(). However, considerations should be made in how much processing is done during the onResume() method. Performing significant amounts of processing may delay view rendering in cases such as device orientation changes. In these cases, it is recommended to use a specifically designated handler to organize the amount of processing to be done.

See also:

android.app.Fragment

Constructor Details

MapFragment ()

Constructor

Method Details

public void addOnMapRenderListener (OnMapRenderListener listener)

Adds a OnMapRenderListener to listen for map render events.

Parameters:

  • listener

    A OnMapRenderListener to add to the MapFragment

See also:

removeOnMapRenderListener(OnMapRenderListener)

public ViewRect getClipRect ()

Returns the ViewRect representing the clip rectangle for this MapFragment.

Returns:

The clip rectangle for rendering MapObject objects and similar map-related screen elements. Null if the view's layout process has yet to be completed.

If the process is not yet complete, users can either retry later or subscribe as a OnMapRenderListener and call this method upon the callback onSizeChanged(int, int).

public Rect getCopyrightBoundaryRect ()

Gets the current HERE copyright logo's boundary rectangle. Returns null if a boundary rect has not been set previously.

Returns:

The copyright logo's boundary rect. null if a boundary rect has not been set previously.

See also:

setCopyrightBoundaryRect(Rect)

public int getCopyrightLogoHeight ()

Returns the height of the copyright logo.

This method only returns a valid value once fragment initialization has taken completed.

Returns:

The height of the copyright logo, in number of pixels

public CopyrightLogoPosition getCopyrightLogoPosition ()

Returns the on-screen position of the HERE copyright logo as a CopyrightLogoPosition value.

Returns:

The position of the logo.

public int getCopyrightLogoWidth ()

Returns the width of the copyright logo.

This method only returns a valid value once fragment initialization has completed.

Returns:

The width of the copyright logo, in number of pixels

public int getCopyrightMargin ()

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

This method only returns a valid value once fragment initialization has taken place.

Returns:

The current offset from the edge of the MapFragment, in number of pixels

public Map getMap ()

Returns the instance of Map associated with this map fragment

Returns:

The Map object currently displayed in this fragment.

public MapGesture getMapGesture ()

Returns the MapGesture object representing the current gesture handler for the MapFragment. Applications can intercept this object and override the default event behaviors.

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)

Returns the full screen bitmap for the MapFragment. This method is asynchronous and will invoke a callback once the operation is completed through the OnScreenCaptureListener. The MapFragment must be visible to create the screen capture.

Parameters:

  • listener

    A OnScreenCaptureListener to listen for the callback when screen capture is complete.

public void init (OnEngineInitListener listener)

Initializes the MapEngine and displays a map that occupies the entire MapFragment's view rectangle. Users of MapFragment should call this method or init(ApplicationContext, OnEngineInitListener) after the fragment is first attached to its activity. This method should only be used for fragments declared in a layout XML. Do not use this method when MapFragment is created programmatically.

This method will initialize MapEngine with GLOBAL map variant on first SDK usage and with stored map variant on sub-sequent usages.

Parameters:

  • listener

    A OnEngineInitListener object that will be called when MapFragment initialization is finished. A null object can be supplied if the caller does not expect any notification when initialization completes.

See also:

OnEngineInitListener

init(ApplicationContext, OnEngineInitListener)

init(ApplicationContext, OnEngineInitListener)

public void init (Context context, MapVariant variant, OnEngineInitListener listener)

Deprecated: As of SDK 3.4.

Use init(ApplicationContext, OnEngineInitListener) instead.

Initializes the MapEngine and displays a map that occupies the entire MapFragment's view rectangle. Users of MapFragment should call this method after the fragment is first attached to its activity.

This method can be used for MapFragment objects that are created programmatically or declared in a layout XML file.

This method can configure map variant which will be used by MapEngine. If initialization fails - OPERATION_NOT_ALLOWED will be reported. Currently following variants are supported: - GLOBAL - initialize MapEngine to use international map variant; - KOREA - initialize MapEngine to use Korean map variant; - null - initialize MapEngine to use stored map variant or international map variant for first run. This method is used to configure MapEngine to use certain map variant. If MapEngine was already configured and passed variant differs - error will be reported and initialization fails.

Parameters:

  • context

    The application context of this fragment.

  • variant

    Map data variant to use.

  • listener

    A OnEngineInitListener object that will be called when MapFragment initialization is finished. A null object can be supplied if the caller does not require any notification when initialization completes.

See also:

OnEngineInitListener

init(Context, OnEngineInitListener)

init(OnEngineInitListener)

public void init (Context context, OnEngineInitListener listener)

Deprecated: As of SDK 3.4.

Use init(ApplicationContext, OnEngineInitListener) instead.

Initializes the MapEngine and displays a map that occupies the entire MapFragment's view rectangle. Users of MapFragment should call this method after the fragment is first attached to its activity.

This method can be used for MapFragment objects that are created programmatically or declared in a layout XML file.

This method will initialize MapEngine with GLOBAL map variant on first SDK usage and with stored map variant on sub-sequent usages.

Parameters:

  • context

    The application context of this fragment.

  • listener

    A OnEngineInitListener object that will be called when MapFragment initialization is finished. A null object can be supplied if the caller does not require any notification when initialization completes.

See also:

OnEngineInitListener

init(Context, OnEngineInitListener)

init(OnEngineInitListener)

public void init (ApplicationContext context, OnEngineInitListener listener)

Initializes the MapEngine and displays a map that occupies the entire MapFragment's view rectangle. Users of MapFragment should call this method after the fragment is first attached to its activity.

This method can be used for MapFragment objects that are created programmatically or declared in a layout XML file.

This method will initialize MapEngine with ApplicationContext to be used during initialization.

Parameters:

  • context

    ApplicationContext to be used during initialization.

  • listener

    A OnEngineInitListener object that will be called when MapFragment initialization is finished. A null object can be supplied if the caller does not require any notification when initialization completes.

See also:

OnEngineInitListener

init(ApplicationContext, OnEngineInitListener)

public View onCreateView (LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState)

Called when this fragment is first attached to its Activity . Automatically starts to initialize the MapEngine for later use.

Parameters:

  • inflater
  • container
  • savedInstanceState

Returns:

The created MapView object.

See also:

android.app.Fragment#onAttach(android.app.Activity)

public void onDestroyView ()

Called when the view previously created by onCreateView(LayoutInflater, ViewGroup, Bundle) has been detached from this fragment. The MapView object created earlier will detach itself of its associated Map instance.

See also:

android.app.Fragment#onDestroyView()

public void onInflate (Activity activity, AttributeSet attrs, Bundle savedInstanceState)

Deprecated: Deprecated as of release 3.5.

Use #onInflate(Context, android.util.AttributeSet, android.os.Bundle) instead.

Called when this fragment is being created as part of a view layout inflation, typically from setting the content view of an activity. This method may be called immediately after the fragment is created from a tag in a layout file.

Parameters:

  • activity
  • attrs
  • savedInstanceState

See also:

android.app.Fragment#onInflate(Activity, AttributeSet, Bundle)

public void onInflate (Context context, AttributeSet attrs, Bundle savedInstanceState)

Called when this fragment is being created as part of a view layout inflation, typically from setting the content view of an activity. This method may be called immediately after the fragment is created from a tag in a layout file.

Parameters:

  • context
  • attrs
  • savedInstanceState

See also:

android.app.Fragment#onInflate(Activity, AttributeSet, Bundle)

public void onPause ()

Called when this fragment is no longer resumed. All MapEngine activities will be paused automatically.

See also:

android.app.Fragment#onPause()

public void onResume ()

Called when this fragment is visible to the user and actively running. All MapEngine activities will be resumed automatically.

See also:

android.app.Fragment#onResume()

public void onSaveInstanceState (Bundle outState)

Called when this fragment has been asked to save its current dynamic state. Saving its current state allows for it to be later reconstructed in a new instance.

Parameters:

  • outState

See also:

android.app.Fragment#onSaveInstanceState(android.os.Bundle)

public void removeOnMapRenderListener (OnMapRenderListener listener)

Removes an existing OnMapRenderListener.

Parameters:

  • listener

    A OnMapRenderListener to remove from the MapFragment

public void setClipRect (ViewRect rect, PointF transformCenter)

Sets a clipping rectangle to the MapFragment. Only the area specified by the ViewRect will be used for rendering, while the rest of the view will be masked in black. This rectangle will be reset to the full size of the MapFragment upon screen rotation or upon recreating the screen.

Note that setting a clipping rectangle will also reset the MapFragment 's viewing rectangle to its full default size.

If the ViewRect is not valid, this method does nothing.

Parameters:

  • rect

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

  • transformCenter

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

See also:

setClipRect(ViewRect)

public void setClipRect (ViewRect rect)

Sets a clipping rectangle to this MapFragment. Only the area specified by the ViewRect will be used for rendering, while the rest of the view will be masked in black. This rectangle will be reset to the full size of the MapFragment upon screen rotation or upon recreating the screen.

If the ViewRect is not valid, this method does nothing.

Parameters:

  • rect

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

See also:

setClipRect(ViewRect, PointF)

public void setCopyrightBoundaryRect (Rect rect)

Sets a rectangle, in pixels, relative to the top left corner of the MapFragment'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. The copyright logo and copyright margin must fit into the rectangle, otherwise specified rectangle will be ignored.

The rectangle is reset upon screen rotation or upon screen re-creation, or it can be done by setting a null - Rect .

Parameters:

  • rect

    A Rect representing the desired rectangular container to be used for positioning 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.

After the logo's position is set, the position 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 for the HERE copyright logo, in number of pixels, as an offset from the edge of the visible map area to the edge of the logo (depending on the placement).

Parameters:

  • margin

    Desired offset from the edge of the MapFragment

public void setMapMarkerDragListener (OnDragListener listener)

Sets a MapMarker.OnDragListener to be invoked whenever any MapMarker on a Map that is attached to this fragment is dragged.

Parameters:

public void setOnTouchListener (View.OnTouchListener listener)

Sets an android.view.OnTouchListener to be invoked whenever a touch event is sent to the MapFragment.

Parameters:

  • listener

    An android.view.OnTouchListener to set for the MapFragment

See also:

android.view.View.OnTouchListener