com.here.android.mapping
Class MapCompatibilityFragment

java.lang.Object
  extended by Fragment
      extended by com.here.android.mapping.MapCompatibilityFragment

public class MapCompatibilityFragment
extends Fragment

Represents a map fragment for API Level 10 support, providing the same functionalities as MapFragment. This fragment class is designed to be used as a sub-component of an activity that automatically handles Map UI interactions like panning, zooming, etc ...

Map Fragments are automatically notified of onResume() and onPause() so that block is unnecessary.

Note: each MapCompatibilityFragment is bound to a Map created automatically upon the initialization of the MapFragment, and map-related objects should persisted during application runtime. MapCompatibilityFragment objects have their own life cycle, state, and back stack. Thus, it is unsafe to assume objects returned by MapCompatibilityFragment will be available throughout the life time of its attached activity. This fragment has Fragment.setRetainInstance(true) set. Therefore the Map will retain any properties applied to it during an application's lifetime.

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

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

Note: MapCompatibilityFragment automatically handles pause and resume of MapEngine during activity state changes, thus it is not necessary for the activity that owns Map Fragment(s) to manually call MapEngine.onPause() / MapEngine.onResume() during the activity's onPause() & onResume(). However, considerations should be made in how much processing to be 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: The hosting activity of MapCompatibilityFragment must inherit from FragmentActivity class instead of the traditional Activity class. See "http://developer.android.com/reference/android/support/v4/app/FragmentActivity.html"

Note: In order to use MapCompatibilityFragment, the Android Support Library must be included in the application. See "http://developer.android.com/training/basics/fragments/support-lib.html". As MapCompatibilityFragment is inherited from android.support.v4.app.Fragment, it may not offer the same fragment functionality support as MapFragment, which is inherited from android.app.Fragment

See Also:
MapFragment, "android.support.v4.app.Fragment", "android.support.v4.app.FragmentActivity"

Constructor Summary
MapCompatibilityFragment()
          Constructor
 
Method Summary
 void addMapEventListener(MapEventListener listener)
          Deprecated. See MapEventListener for information on new interfaces which provide equivalent functionality.
 void addRenderListener(MapRenderListener listener)
          Adds a MapRenderListener to listen for map render events.
 ViewRect getClipRect()
          Gets the ViewRect representing the clip rectangle for the MapCompatibilityFragment.
 Rect getCopyrightBoundaryRect()
          Gets the current rectangle relative to the view group as a container for the HERE copyright logo.
 MapCopyrightLogoPosition getCopyrightLogoPosition()
          Gets the position for the HERE copyright logo.
 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.
 Map getMap()
          Returns the instance of Map associated with this Map Fragment
 MapGesture getMapGesture()
          Gets the MapGesture representing the current gesture handler for the MapCompatibilityFragment.
 void init(Context context, FragmentInitListener listener)
          User of MapCompatibilityFragment must called this function after the fragment is first attached to its activity.
 void init(FragmentInitListener listener)
          User of MapCompatibilityFragment must called this function after the fragment is first attached to its activity.
 View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState)
          Called when a fragment is first attached to its activity.
 void onDestroyView()
          Called when the view previously created by onCreateView(LayoutInflater, ViewGroup, Bundle) has been detached from the fragment.
 void onInflate(Activity activity, AttributeSet attrs, Bundle savedInstanceState)
          Called when a fragment is being created as part of a view layout inflation, typically from setting the content view of an activity.
 void onPause()
          Called when the Fragment is no longer resumed.
 void onResume()
          Called when the fragment is visible to the user and actively running.
 void onSaveInstanceState(Bundle outState)
          Called to ask the fragment to save its current dynamic state, so it can later be reconstructed in a new instance of its process is restarted.
 void removeMapEventListener(MapEventListener listener)
          Deprecated. See MapEventListener for information on new interfaces which provide equivalent functionality.
 void removeRenderListener(MapRenderListener listener)
          Removes an existing MapRenderListener.
 void setClipRect(ViewRect rect)
          Sets a clipping rectangle to the MapCompatibilityFragment.
 void setClipRect(ViewRect rect, PointF transformCenter)
          Sets a clipping rectangle to the MapCompatibilityFragment.
 void setCopyrightBoundaryRect(int left, int top, int right, int bottom)
          Sets a margin, in pixels, for the Here copyright logo, an offset from the edge of the visible map area to the edge of the logo (depending on the placement).
 void setCopyrightLogoPosition(MapCopyrightLogoPosition position)
          Sets a position for the Here copyright logo.
 void setCopyrightMargin(int margin)
          Sets a margin, in pixels, for the Here copyright logo, an offset from the edge of the visible map area to the edge of the logo (depending on the placement).
 void setMapMarkerDragListener(MapMarkerDragListener listener)
          Sets a MapMarkerDragListener to be invoked whenever any MapMarker added onto a Map that is attached to this MapView is dragged.
 void setOnTouchListener(View.OnTouchListener listener)
          Sets an OnTouchListener to be invoked whenever a touch event is sent to the MapCompatibilityFragment.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MapCompatibilityFragment

public MapCompatibilityFragment()
Constructor

Method Detail

init

public void init(FragmentInitListener listener)
User of MapCompatibilityFragment must called this function after the fragment is first attached to its activity. This automatically starts to initialize the Map Factory for later use and displays a map occupying the entire MapCompatibilityFragment's rect after initialization completes. This method is a method that can be used for fragments embedded in a layout XML. This method should not be used when programatically creating a MapCompatibilityFragment.

Parameters:
listener - A FragmentInitListener object that will be called when MapFactory initialization is finished. A null object can be supplied if caller do not expect any notification when initialization completes.
See Also:
MapFactory.initFactory(android.content.Context, FactoryInitListener)

init

public void init(Context context,
                 FragmentInitListener listener)
User of MapCompatibilityFragment must called this function after the fragment is first attached to its activity. This automatically starts to initialize the Map Factory for later use and displays a map occupying the entire MapCompatibilityFragment's rect after initialization completes. This method can be used when programatically creating a MapCompatibilityFragment.

Parameters:
context - Context of the application.
listener - A FragmentInitListener object that will be called when MapFactory initialization is finished. A null object can be supplied if caller do not expect any notification when initialization completes.
See Also:
MapFactory.initFactory(android.content.Context, FactoryInitListener)

onCreateView

public View onCreateView(LayoutInflater inflater,
                         ViewGroup container,
                         Bundle savedInstanceState)
Called when a fragment is first attached to its activity. Automatically starts to initialize the Map Factory for later use.

See Also:
Fragment

onInflate

public void onInflate(Activity activity,
                      AttributeSet attrs,
                      Bundle savedInstanceState)
Called when a fragment is being created as part of a view layout inflation, typically from setting the content view of an activity. This may be called immediately after the fragment is created from a tag in a layout file.

See Also:
Fragment

onResume

public void onResume()
Called when the fragment is visible to the user and actively running. All Map Engine activities will be resumed automatically.

See Also:
Fragment

onPause

public void onPause()
Called when the Fragment is no longer resumed. All Map Engine activities will be paused automatically.

See Also:
Fragment

onDestroyView

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

See Also:
Fragment

onSaveInstanceState

public void onSaveInstanceState(Bundle outState)
Called to ask the fragment to save its current dynamic state, so it can later be reconstructed in a new instance of its process is restarted.

See Also:
Fragment

getMap

public Map getMap()
Returns the instance of Map associated with this Map Fragment

Returns:
The Map object currently displayed in this fragment.

getClipRect

public ViewRect getClipRect()
Gets the ViewRect representing the clip rectangle for the MapCompatibilityFragment.

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

null maybe returned if the view's layout process has yet to be completed. Users can either retry later or subscribe as a MapRenderListener and call this method upon the callback MapRenderListener.onSizeChanged(int, int).


setClipRect

public void setClipRect(ViewRect rect,
                        PointF transformCenter)
Sets a clipping rectangle to the MapCompatibilityFragment.

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, while the rest of the view will be masked in black.

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

Note: the view rectangle is reset to full size of the {code MapCompatibilityFragment} upon screen rotation or upon recreating the 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
See Also:
setClipRect(ViewRect)

setClipRect

public void setClipRect(ViewRect rect)
Sets a clipping rectangle to the MapCompatibilityFragment.

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

Note: the view rectangle is reset to full size of the MapCompatibilityFragment upon screen rotation or upon recreating the screen.

Parameters:
rect - A ViewRect for rendering MapObject objects and similar map-related screen elements
See Also:
setClipRect(ViewRect, PointF)

getCopyrightBoundaryRect

public Rect getCopyrightBoundaryRect()
Gets the current rectangle relative to the view group as a container for the HERE copyright logo.

Returns:
The boundary rect (can be null).

setCopyrightBoundaryRect

public void setCopyrightBoundaryRect(int left,
                                     int top,
                                     int right,
                                     int bottom)
Sets a margin, in pixels, for the Here copyright logo, an offset from the edge of the visible map area to the edge of the logo (depending on the placement).

Parameters:
left - Desired Left offset from the edge of the MapFragment
top - Desired Top offset from the edge of the MapFragment
right - Desired Right offset from the edge of the MapFragment
bottom - Desired Bottom offset from the edge of the MapFragment

getCopyrightMargin

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.

Returns:
The current offset from the edge of the MapFragment

setCopyrightMargin

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 to the edge of the logo (depending on the placement).

Parameters:
margin - Desired offset from the edge of the MapFragment

getCopyrightLogoPosition

public MapCopyrightLogoPosition getCopyrightLogoPosition()
Gets the position for the HERE copyright logo.

Returns:
The position of the logo.

setCopyrightLogoPosition

public void setCopyrightLogoPosition(MapCopyrightLogoPosition 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 MapCopyrightLogoPosition value representing the desired placement of the Here copyright logo with respect to the visible map view area

getMapGesture

public MapGesture getMapGesture()
Gets the MapGesture representing the current gesture handler for the MapCompatibilityFragment. Applications can intercept this object and override the default events.

Returns:
The MapGesture

addMapEventListener

public void addMapEventListener(MapEventListener listener)
Deprecated. See MapEventListener for information on new interfaces which provide equivalent functionality.

Adds a MapEventListener to listen for map events.

Note: after you add a MapEventListener to an application, remember to call removeMapEventListener(MapEventListener) if you no longer need to listen for map view events and want to free up application resources.

Parameters:
listener - A MapEventListener to add to the MapFragment
See Also:
removeMapEventListener(MapEventListener)

removeMapEventListener

public void removeMapEventListener(MapEventListener listener)
Deprecated. See MapEventListener for information on new interfaces which provide equivalent functionality.

Removes an existing MapEventListener.

Note: call this method to free up application resources once you no longer need to listen for map view events.

Parameters:
listener - A MapEventListener to remove from the MapFragment

addRenderListener

public void addRenderListener(MapRenderListener listener)
Adds a MapRenderListener to listen for map render events.

Parameters:
listener - A MapRenderListener to add to the MapCompatibilityFragment
See Also:
removeRenderListener(MapRenderListener)

removeRenderListener

public void removeRenderListener(MapRenderListener listener)
Removes an existing MapRenderListener.

Parameters:
listener - A MapRenderListener to remove from the MapCompatibilityFragment

setOnTouchListener

public void setOnTouchListener(View.OnTouchListener listener)
Sets an OnTouchListener to be invoked whenever a touch event is sent to the MapCompatibilityFragment.

Parameters:
listener - An OnTouchListener to set for the MapCompatibilityFragment
See Also:
android.view.View.OnTouchListener

setMapMarkerDragListener

public void setMapMarkerDragListener(MapMarkerDragListener listener)
Sets a MapMarkerDragListener to be invoked whenever any MapMarker added onto a Map that is attached to this MapView is dragged.

Parameters:
listener - An MapMarkerDragListener to set for this MapView

Copyright (C) 2011-2013 HERE Global B.V. All rights reserved.