net.rim.device.api.lbs.maps.ui
Class MapAction

java.lang.Object
  extended by net.rim.device.api.lbs.maps.ui.MapAction

public class MapAction
extends Object

Defines if and how actions are performed on the parent map field.

Note: for the setCenter* methods, if the new center is outside of the world boundaries for the latitude, then the coordinate is clipped to the maximum value. If the longitude coordinate exceeds the world boundaries, then the coordinate is wrapped to an equivalent point within the world boundaries.

Note: This class is tightly integrated with the MapField. If your application calls methods within this class while this class is orphaned (for example, this class is not linked to a MapField) a NullPointerException is thrown. Use the MapField.setAction(MapAction) method to associate this class with a MapField instance.

Since:
BlackBerry API 6.0.0

Field Summary
static int ACTION_CENTER_CHANGE
          Action event that indicates the center coordinates changed.
static int ACTION_CENTRE_CHANGE
          Deprecated. Use MapAction.ACTION_CENTER_CHANGE instead
static int ACTION_FOCUSED_CHANGE
          Action event that indicates the focused mappable item changed.
static int ACTION_NAVIGATE_CHANGE
          Action event that indicates the navigated mappable changed.
static int ACTION_OPERATION_MODE_CHANGE
          Action event that indicates the operational mode changed.
static int ACTION_ROTATION_CHANGE
          Action event that indicates the rotation angle changed.
static int ACTION_SELECTED_MAPPABLE_CHANGE
          Action event that indicates the selected mappable changed.
static int ACTION_ZOOM_CHANGE
          Action event that indicates the zoom level changed.
 
Constructor Summary
MapAction()
          Constructs a new MapAction instance.
 
Method Summary
protected  boolean allowNavigateNextPrev(boolean forward)
          Indicates whether the actions to navigate to the next or previous mappable items are allowed.
protected  boolean allowSetCenter(MapPoint newCenter)
          Indicates whether the center point of the map field may be set.
protected  boolean allowSetFocusMappable(Mappable target)
          Indicates whether focus can be set for a specified mappable item.
protected  boolean allowSetFocusMappableByPoint(MapPoint target)
          Indicates whether the selection of a mapable item by a point may be made.
protected  boolean allowSetFocusMappableByPoint(XYPoint target)
          Indicates whether a selection may be made of a mappable item that is near a specified point.
protected  boolean allowSetOperationMode(int newMode)
          Indicates whether the operation mode of the parent field may be changed.
protected  boolean allowSetRotation(int rotation)
          Indicates whether the rotation angle for the map field may be changed.
protected  boolean allowSetSelectionPoint(MapPoint target)
          Indicates whether the selection point may be set.
protected  boolean allowSetZoom(int zoom)
          Indicates whether the zoom level for the map field may be changed.
protected  boolean allowTemporaryFocusMappable()
          Indicates whether focus is kept on the current focused mappable item if no new mappable item is found to focus on.
 void disableOperationMode(int modeToDisable)
          Disables an operation mode from the current composite mode, leaving the other active modes enabled.
 void enableOperationMode(int modeToEnable)
          Enables an operation mode on top of the mode that is currently active.
 MapField getParentField()
          Retrieves the parent map field of this action instance.
 void navigateNext()
          Navigates to the next mappable item.
 void navigatePrev()
          Navigates to the previous mappable item.
protected  boolean performNavigateNext()
          Implements the action of navigating to the next mappable item.
protected  boolean performNavigatePrev()
          Implements the action of navigating to the previous mappable item.
protected  boolean performSetCenter(MapPoint newCenter)
          Centers the map to the specified point.
protected  void performSetFocusMappable(Mappable target)
          Sets focus on the specified mappable item.
protected  boolean performSetFocusMappableByPoint(MapPoint target)
          Sets a focused mappable item based on a specified point.
protected  boolean performSetFocusMappableByPoint(XYPoint target)
          Sets a focused mappable item based on a specified screen point.
protected  boolean performSetOperationMode(int newMode)
          Changes the operation mode of the parent map field.
protected  boolean performSetRotation(int rotation)
          Rotates the map field to the specified rotation angle.
protected  void performSetSelectionPoint(MapPoint target)
          Sets the current selection point.
protected  boolean performSetZoom(int zoom)
          Sets the zoom to the specified level.
 void setCenter(MapPoint newCenter)
          Sets the center of the map to the specified point.
 void setCenterAndZoom(Boxable visible)
          Sets the center and zoom levels for the mappable item by performing both a MapAction.setCenter(MapPoint) and a MapAction.setZoom(int), and then updates the mappable item, with a single update instead of two updates.
 void setCenterAndZoom(MapPoint center, int zoom)
          Sets the center point and zoom level of the map, and then updates the map.
 void setCenterLatLon(double lat, double lon)
          Sets the center of the map to the specified latitude and longitude coordinates.
 void setCentre(MapPoint newCenter)
          Deprecated. Use MapAction.setCenter(MapPoint) instead
 void setCentreAndZoom(MapPoint center, int zoom)
          Deprecated. Use MapAction.setCenterAndZoom(MapPoint,int) instead
 void setCentreLatLon(double lat, double lon)
          Deprecated. Use MapAction.setCenterLatLon(double,double) instead
 void setFocusMappable(Mappable target)
          Sets focus on the specified mappable item.
 boolean setFocusMappableByPoint(MapPoint target)
          Sets the mappable item that is nearest to the specified point as the focused mappable item.
 boolean setFocusMappableByPoint(XYPoint screenPt)
          Sets the mappable item that is nearest to the specified point as the focused mappable item.
 void setRotation(int rotation)
          Sets the rotation angle of the map field.
 void setSelectionPoint(MapPoint target)
          Sets the current selection point.
protected  void setTrackpadSensitivity(int level)
          Sets the screen's trackpad sensitivity offset and trackpad filter based on the given level.
 void setZoom(int zoom)
          Sets the zoom level for the map field.
 void zoomIn()
          Zooms in by one zoom level.
 void zoomOut()
          Zooms out by one zoom level.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

ACTION_ZOOM_CHANGE

public static final int ACTION_ZOOM_CHANGE
Action event that indicates the zoom level changed.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ACTION_CENTER_CHANGE

public static final int ACTION_CENTER_CHANGE
Action event that indicates the center coordinates changed.

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0

ACTION_CENTRE_CHANGE

public static final int ACTION_CENTRE_CHANGE
Deprecated. Use MapAction.ACTION_CENTER_CHANGE instead
Action event that indicates the center coordinates changed.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ACTION_FOCUSED_CHANGE

public static final int ACTION_FOCUSED_CHANGE
Action event that indicates the focused mappable item changed.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ACTION_OPERATION_MODE_CHANGE

public static final int ACTION_OPERATION_MODE_CHANGE
Action event that indicates the operational mode changed.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ACTION_NAVIGATE_CHANGE

public static final int ACTION_NAVIGATE_CHANGE
Action event that indicates the navigated mappable changed.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ACTION_SELECTED_MAPPABLE_CHANGE

public static final int ACTION_SELECTED_MAPPABLE_CHANGE
Action event that indicates the selected mappable changed.

See Also:
Constant Field Values
Since:
BlackBerry API 6.0.0

ACTION_ROTATION_CHANGE

public static final int ACTION_ROTATION_CHANGE
Action event that indicates the rotation angle changed.

See Also:
Constant Field Values
Since:
BlackBerry API 7.0.0


Constructor Detail

MapAction

public MapAction()
Constructs a new MapAction instance.

Note: MapAction must be associated with a MapField instance.

Since:
BlackBerry API 7.0.0


Method Detail

getParentField

public MapField getParentField()
Retrieves the parent map field of this action instance.

Returns:
The parent map field.
Since:
BlackBerry API 7.0.0

setZoom

public final void setZoom(int zoom)
Sets the zoom level for the map field.

Parameters:
zoom - The specified zoom level for the map field.
Since:
BlackBerry API 6.0.0

performSetZoom

protected boolean performSetZoom(int zoom)
Sets the zoom to the specified level.

Parameters:
zoom - The specified zoom level.
Returns:
true if the zoom level successfully changed, false otherwise.
Since:
BlackBerry API 7.0.0

allowSetZoom

protected boolean allowSetZoom(int zoom)
Indicates whether the zoom level for the map field may be changed.

Parameters:
zoom - The new zoom level.
Returns:
true if the zoom level may be changed, false otherwise.
Since:
BlackBerry API 7.0.0

zoomIn

public void zoomIn()
Zooms in by one zoom level. If the current zoom level is already at the minimum, the zoom level does not change.

Since:
BlackBerry API 6.0.0

zoomOut

public void zoomOut()
Zooms out by one zoom level. If the current zoom level is already at the maximum, the zoom level does not change.

Since:
BlackBerry API 6.0.0

setCentreAndZoom

public final void setCentreAndZoom(MapPoint center,
                                   int zoom)
Deprecated. Use MapAction.setCenterAndZoom(MapPoint,int) instead

Since:
BlackBerry API 6.0.0

setCenterAndZoom

public final void setCenterAndZoom(MapPoint center,
                                   int zoom)
Sets the center point and zoom level of the map, and then updates the map.

Parameters:
center - The new center of the screen.
zoom - The new zoom level.
Since:
BlackBerry API 7.0.0

setRotation

public final void setRotation(int rotation)
Sets the rotation angle of the map field.

Parameters:
rotation - The new rotation angle of the map field.
Since:
BlackBerry API 7.0.0

performSetRotation

protected boolean performSetRotation(int rotation)
Rotates the map field to the specified rotation angle.

Parameters:
rotation - The new rotation angle of the map field.
Returns:
true if the rotation angle successfully changed, false otherwise.
Since:
BlackBerry API 7.0.0

allowSetRotation

protected boolean allowSetRotation(int rotation)
Indicates whether the rotation angle for the map field may be changed.

Parameters:
rotation - The new rotation angle for the map field.
Returns:
true if the rotation angle may be changed, false otherwise.
Since:
BlackBerry API 7.0.0

setCenterAndZoom

public final void setCenterAndZoom(Boxable visible)
Sets the center and zoom levels for the mappable item by performing both a MapAction.setCenter(MapPoint) and a MapAction.setZoom(int), and then updates the mappable item, with a single update instead of two updates.

The center point is calculated based on the parameter's center point, and the zoom level is calculated based on what level is required to make the parameter entirely visible.

Parameters:
visible - The visible entity to base the zoom and center calculations on.
Since:
BlackBerry API 7.0.0

setCentre

public final void setCentre(MapPoint newCenter)
Deprecated. Use MapAction.setCenter(MapPoint) instead

Since:
BlackBerry API 6.0.0

setCenter

public final void setCenter(MapPoint newCenter)
Sets the center of the map to the specified point.

Parameters:
newCenter - The new center point.
Since:
BlackBerry API 7.0.0

setCentreLatLon

public final void setCentreLatLon(double lat,
                                  double lon)
Deprecated. Use MapAction.setCenterLatLon(double,double) instead

Since:
BlackBerry API 6.0.0

setCenterLatLon

public final void setCenterLatLon(double lat,
                                  double lon)
Sets the center of the map to the specified latitude and longitude coordinates.

Parameters:
lat - The latitude of the location (in degrees).
lon - The longitude of the location (in degrees).
Since:
BlackBerry API 7.0.0

performSetCenter

protected boolean performSetCenter(MapPoint newCenter)
Centers the map to the specified point.

Parameters:
newCenter - The new center point of the map.
Returns:
true if the center successfully changed, false otherwise.
Since:
BlackBerry API 7.0.0

allowSetCenter

protected boolean allowSetCenter(MapPoint newCenter)
Indicates whether the center point of the map field may be set.

Parameters:
newCenter - The new center point of the map field.
Returns:
true if the center may be set, false otherwise.
Since:
BlackBerry API 7.0.0

enableOperationMode

public final void enableOperationMode(int modeToEnable)
Enables an operation mode on top of the mode that is currently active. This allows for composite modes, such as MODE_SELECTION and MODE_ZOOM to be active concurrently.

Note: No validation is performed to ensure that mutually exclusive modes (such as MODE_ZOOM and MODE_PAN) are not enabled at the same time.

It is the responsibility of the caller to ensure mode consistency. When mutually exclusive modes are enabled, the behavior is undefined.

Parameters:
modeToEnable - The operation mode to enable.
Since:
BlackBerry API 6.0.0

disableOperationMode

public final void disableOperationMode(int modeToDisable)
Disables an operation mode from the current composite mode, leaving the other active modes enabled.

Parameters:
modeToDisable - The mode to be disabled.
Since:
BlackBerry API 6.0.0

performSetOperationMode

protected boolean performSetOperationMode(int newMode)
Changes the operation mode of the parent map field.

Parameters:
newMode - The new operation mode.
Returns:
true if the mode was changed, false otherwise.
Since:
BlackBerry API 7.0.0

allowSetOperationMode

protected boolean allowSetOperationMode(int newMode)
Indicates whether the operation mode of the parent field may be changed.

Parameters:
newMode - The new operation mode.
Returns:
true if the parent field's operation mode may be changed, false otherwise.
Since:
BlackBerry API 7.0.0

setSelectionPoint

public final void setSelectionPoint(MapPoint target)
Sets the current selection point. The selection point is different from the current focused mappable item because the selection point is only applicable in the selection mode, and it does not modify the current focused mappable item.

Parameters:
target - The point that is selected.
Since:
BlackBerry API 6.0.0

allowSetSelectionPoint

protected boolean allowSetSelectionPoint(MapPoint target)
Indicates whether the selection point may be set.

Parameters:
target - The selection point.
Returns:
true if the selection point may be set, false otherwise.
Since:
BlackBerry API 7.0.0

performSetSelectionPoint

protected void performSetSelectionPoint(MapPoint target)
Sets the current selection point.

Parameters:
target - The entity (or point) that now has focus.
Since:
BlackBerry API 7.0.0

setFocusMappableByPoint

public final boolean setFocusMappableByPoint(XYPoint screenPt)
Sets the mappable item that is nearest to the specified point as the focused mappable item.

Note: This method behaves slightly differently than MapAction.setFocusMappableByPoint(MapPoint) because it considers on-screen artifacts to help determine what's in focus. On-screen artifacts are rendered objects that aren't directly on the mappable item. For example, a mappable item's flag is an on-screen artifact.

If the specified point is off-screen, MapAction.setFocusMappableByPoint(MapPoint) is used to set the focused mappable item.

Parameters:
screenPt - The screen point near which to focus the mappable item.
Returns:
true if focus was successfully set, false otherwise.
Since:
BlackBerry API 7.0.0

allowSetFocusMappableByPoint

protected boolean allowSetFocusMappableByPoint(XYPoint target)
Indicates whether a selection may be made of a mappable item that is near a specified point.

Parameters:
target - The specified point at which to select the mappable item.
Returns:
true if a selection may be made, false otherwise.
Since:
BlackBerry API 7.0.0

performSetFocusMappableByPoint

protected boolean performSetFocusMappableByPoint(XYPoint target)
Sets a focused mappable item based on a specified screen point.

Parameters:
target - The screen point to indicate what's in focus.
Returns:
true if a mappable item in the map model has focus, false otherwise.
Since:
BlackBerry API 7.0.0

setFocusMappableByPoint

public final boolean setFocusMappableByPoint(MapPoint target)
Sets the mappable item that is nearest to the specified point as the focused mappable item.

Note: This method behaves slightly differently than MapAction.setFocusMappableByPoint(XYPoint) because it doesn't consider on-screen artifacts to determine what's in focus. On-screen artifacts are rendered objects that aren't directly on the mappable item. For example, the caption box is an on-screen artifact.

If the specified point is off-screen, MapAction.setFocusMappableByPoint(MapPoint) is used to set the focused mappable item.

Parameters:
target - The screen point near which to focus the mappable item.
Returns:
true if focus was successfully set, false otherwise.
Since:
BlackBerry API 7.0.0

performSetFocusMappableByPoint

protected boolean performSetFocusMappableByPoint(MapPoint target)
Sets a focused mappable item based on a specified point.

Parameters:
target - The point at which to focus the mappable item.
Returns:
true if a mappable item in the map model has focus, false otherwise.
Since:
BlackBerry API 7.0.0

allowSetFocusMappableByPoint

protected boolean allowSetFocusMappableByPoint(MapPoint target)
Indicates whether the selection of a mapable item by a point may be made.

Parameters:
target - The point at which to select the mappable item.
Returns:
true if a selection may be made, false otherwise.
Since:
BlackBerry API 7.0.0

allowTemporaryFocusMappable

protected boolean allowTemporaryFocusMappable()
Indicates whether focus is kept on the current focused mappable item if no new mappable item is found to focus on.

Returns:
true to set focus on a temporary MapPoint if no new mappable item is found to focus on, false if focus is kept on the current focused mappable if no new mappable item is found to focus on.
Since:
BlackBerry API 7.0.0

setFocusMappable

public final void setFocusMappable(Mappable target)
Sets focus on the specified mappable item.

Parameters:
target - The mappable item to receive focus.
Since:
BlackBerry API 6.0.0

performSetFocusMappable

protected void performSetFocusMappable(Mappable target)
Sets focus on the specified mappable item.

Parameters:
target - The mappable item to receive focus.
Since:
BlackBerry API 7.0.0

allowSetFocusMappable

protected boolean allowSetFocusMappable(Mappable target)
Indicates whether focus can be set for a specified mappable item.

Parameters:
target - The mappable item to receive focus.
Returns:
true if focus can be set for the mappable item, false otherwise.
Since:
BlackBerry API 7.0.0

setTrackpadSensitivity

protected void setTrackpadSensitivity(int level)
Sets the screen's trackpad sensitivity offset and trackpad filter based on the given level.

Parameters:
level - The specified level to set the sensitivity of the trackpad, which are defined with the prefix TRACKPAD_SENSITIVITY_* in MapConstants.
Since:
BlackBerry API 7.0.0

allowNavigateNextPrev

protected boolean allowNavigateNextPrev(boolean forward)
Indicates whether the actions to navigate to the next or previous mappable items are allowed.

Parameters:
forward - If true, navigation moves forward to the next mappable item, if false, navigation moves to the previous mappable item.
Returns:
true if navigation to the next or previous mappable item is allowed, false otherwise.
Since:
BlackBerry API 7.0.0

performNavigateNext

protected boolean performNavigateNext()
Implements the action of navigating to the next mappable item. Subclasses can override this method to change the implementation of the navigate action.

Returns:
true if the action performed a change or if the action was successful, false otherwise.
Since:
BlackBerry API 7.0.0

navigateNext

public final void navigateNext()
Navigates to the next mappable item.

Since:
BlackBerry API 6.0.0

performNavigatePrev

protected boolean performNavigatePrev()
Implements the action of navigating to the previous mappable item. Subclasses can override this method to change the implementation of the navigate action.

Returns:
true if the action performed a change or if it was successful, false otherwise.
Since:
BlackBerry API 7.0.0

navigatePrev

public final void navigatePrev()
Navigates to the previous mappable item.

Since:
BlackBerry API 6.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal