net.rim.device.api.lbs
Class MapField

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.lbs.MapField

public class MapField
extends Field

Renders a map using the current mapping service.

There are three basic ways to navigate the MapField:

And there are two basic ways to change the currently displayed view:

Note: In any conversion or navigation (move) methods, world coordinates are used whereby the valid ranges for latitude values are inclusive for -9000000 to 9000000, and; longitude values are inclusive for -18000000 to 18000000. Methods using WGS84 coordinates become converted to world coordinates are subject to this validation.

You can also use the MapField and the RichMapField that are defined in net.rim.device.api.lbs.maps.ui to render maps. These classes were released in BlackBerry Java SDK 6.0, and provide extended services and functions over this MapField.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

Field Summary
 
Fields inherited from class net.rim.device.api.ui.Field
ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL
 
Constructor Summary
Category: Signed MapField()
          Constructs a MapField instance.
Category: Signed MapField(long style)
          Constructs a MapField instance with a given style.
 
Method Summary
Category: Signed  void convertFieldToWorld(XYPoint fieldIn, Coordinates worldOut)
          Converts Field units (pixels) to world units (coordinates).
Category: Signed  void convertFieldToWorld(XYPoint fieldIn, XYPoint worldOut)
          Converts Field units (pixels) to world units (degrees * 100000).
Category: Signed  void convertWorldToField(Coordinates worldIn, XYPoint fieldOut)
          Converts World units to field units.
Category: Signed  void convertWorldToField(XYPoint worldIn, XYPoint fieldOut)
          Converts World units (degrees * 100000) to field units.
Category: Signed  Coordinates getCoordinates()
          Returns the coordinates for the center of the map view.
Category: Signed  int getLatitude()
          Returns the latitudinal coordinate for the center of the map view.
Category: Signed  int getLongitude()
          Returns the longitudinal coordinate for the center of the map view.
Category: Signed  int getMaxZoom()
          Retrieves the maximum zoom level (largest visible area) that is supported.
Category: Signed  int getMinZoom()
          Retrieves the minimum zoom level (smallest visible area) that is supported.
Category: Signed  int getPreferredHeight()
          Returns the preferred height of the MapField.
Category: Signed  int getPreferredWidth()
          Returns the preferred width of the MapField.
Category: Signed  int getRotation()
          Returns the current rotation in degree.
Category: Signed  XYPoint getXYPoint()
          Returns the coordinates for the center of the map view as an XYPoint.
Category: Signed  int getZoom()
          Returns the current zoom level.
Category: Signed protected  void layout(int width, int height)
          Lays out field contents.
Category: Signed  void move(int dx, int dy)
          Moves the current view by the given pixels.
Category: Signed  void moveTo(int latitude, int longitude)
          Centers the map view on the specified location's latitude and longitude.
Category: Signed  void moveTo(Coordinates coordinates)
          Centers the map view on the specified location's coordinates.
Category: Signed protected  void paint(Graphics graphics)
          Paints the MapField.
Category: Signed  void setPreferredSize(int preferredWidth, int preferredHeight)
          Sets the preferred size.
Category: Signed  void setRotation(int rotation)
          Sets the rotation of the current view.
Category: Signed  void setZoom(int zoom)
          Sets the current zoom level.
Category: Signed protected  void updateView()
          Deprecated. MapField.move(int, int), MapField.moveTo(int, int), MapField.moveTo(Coordinates), MapField.setZoom(int), MapField.zoomIn(), MapField.zoomOut() and MapField.setRotation(int) all implicitly update the MapField.
Category: Signed  void zoomIn()
          Zooms in by one zoom level.
Category: Signed  void zoomOut()
          Zooms out by one zoom level.
 
Methods inherited from class net.rim.device.api.ui.Field
drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getAccessibleContext, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, makeContextMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onFocus, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setEnabled, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, touchEvent, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

MapField

public MapField(long style)
Constructs a MapField instance with a given style.

Parameters:
style - The specified style. For more information, see Field(long style).
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

MapField

public MapField()
Constructs a MapField instance.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0


Method Detail

getPreferredHeight

public int getPreferredHeight()
Returns the preferred height of the MapField.

Overrides:
getPreferredHeight in class Field
Returns:
the preferred height of the MapField.
See Also:
MapField.setPreferredSize(int, int)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

getPreferredWidth

public int getPreferredWidth()
Returns the preferred width of the MapField.

Overrides:
getPreferredWidth in class Field
Returns:
the preferred width of the MapField.
See Also:
MapField.setPreferredSize(int, int)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

setPreferredSize

public void setPreferredSize(int preferredWidth,
                             int preferredHeight)
Sets the preferred size. If you specify a size, this will override any screen orientation changes from the BlackBerry device.

Parameters:
preferredWidth - The preferred width, or -1 for the default width.
preferredHeight - The preferred height, or -1 for the default height.
Throws:
IllegalArgumentException - if either parameter is less than -1.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

getMinZoom

public int getMinZoom()
Retrieves the minimum zoom level (smallest visible area) that is supported.

Returns:
The minimum zoom level.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

getMaxZoom

public int getMaxZoom()
Retrieves the maximum zoom level (largest visible area) that is supported.

Returns:
The maximum zoom level.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

setZoom

public void setZoom(int zoom)
Sets the current zoom level.

The minimum and maximum zoom levels and the resolution at any particular zoom level may change and should not be assumed.

Parameters:
zoom - The zoom level, which must be greater than or equal to MapField.getMinZoom() or less than or equal to MapField.getMaxZoom().
Throws:
IllegalArgumentException - if zoom is less than MapField.getMinZoom() or greater than MapField.getMaxZoom().
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

getZoom

public int getZoom()
Returns the current zoom level.

Returns:
The current zoom level.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.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.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
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.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0

move

public void move(int dx,
                 int dy)
Moves the current view by the given pixels. Note that screen calculations differ from latitude and longitude calculations. For screen calculations, X values increase from left to right, and Y values increase from top to bottom. The origin (0,0) of the screen's grid can be viewed as in the upper, left corner.

Parameters:
dx - The number of pixels to move horizontally. A positive dx moves east if the rotation is 0.
dy - The number of pixels to move vertically. A positive dy moves south if the rotation is 0.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

moveTo

public void moveTo(int latitude,
                   int longitude)
Centers the map view on the specified location's latitude and longitude.

Parameters:
latitude - The latitudinal coordinate, in one hundred thousandths of degrees north (south is negative). Valid values are inclusive for -9000000 to 9000000.
longitude - The longitudinal coordinate, in one hundred thousandths of degrees east (west is negative). Valid values are inclusive for -18000000 to 18000000.
Throws:
IllegalArgumentException - if the coordinates are out of range.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

moveTo

public void moveTo(Coordinates coordinates)
Centers the map view on the specified location's coordinates.

Parameters:
coordinates - The location coordinates to move to.
Throws:
IllegalArgumentException - if converted world coordinates are out of range.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

getLatitude

public int getLatitude()
Returns the latitudinal coordinate for the center of the map view.

Returns:
The latitude in degrees * 100000 north (south is negative).
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

getLongitude

public int getLongitude()
Returns the longitudinal coordinate for the center of the map view.

Returns:
The longitude in degrees * 100000 east (west is negative).
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

getCoordinates

public Coordinates getCoordinates()
Returns the coordinates for the center of the map view.

Returns:
The center coordinates.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

getXYPoint

public XYPoint getXYPoint()
Returns the coordinates for the center of the map view as an XYPoint.

Returns:
The XYPoint of the coordinates in degrees * 100000.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

setRotation

public void setRotation(int rotation)
Sets the rotation of the current view.

Parameters:
rotation - The rotation of the current view, in clockwise degrees (0 is North Up, 90 is North Right, 180 is North Down, etc.)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

getRotation

public int getRotation()
Returns the current rotation in degree.

Returns:
The current rotation, in clockwise degrees (0 is North Up).
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

convertWorldToField

public void convertWorldToField(XYPoint worldIn,
                                XYPoint fieldOut)
Converts World units (degrees * 100000) to field units.

Parameters:
worldIn - The input point to convert, in 100000th degrees.
fieldOut - The converted output point, in pixels.
Throws:
IllegalArgumentException - if world coordinates are out of range.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

convertWorldToField

public void convertWorldToField(Coordinates worldIn,
                                XYPoint fieldOut)
Converts World units to field units.

Parameters:
worldIn - The input point to convert, degrees in WGS84 datum.
fieldOut - The converted output point, in pixels.
Throws:
IllegalArgumentException - if either converted values out of range.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

convertFieldToWorld

public void convertFieldToWorld(XYPoint fieldIn,
                                XYPoint worldOut)
Converts Field units (pixels) to world units (degrees * 100000).

Parameters:
fieldIn - The input point to convert, in pixels.
worldOut - The converted point, in 100000th degrees.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

convertFieldToWorld

public void convertFieldToWorld(XYPoint fieldIn,
                                Coordinates worldOut)
Converts Field units (pixels) to world units (coordinates).

Parameters:
fieldIn - The input point to convert, in pixels.
worldOut - The converted point, degrees in WGS84 datum.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

layout

protected void layout(int width,
                      int height)
Description copied from class: Field
Lays out field contents.

This method is abstract; any class that extends Field must implement this method appropriate to its needs.

Invoked after the screen has been created, or when system parameters change (for example, after a system font change). Field.getExtent() will return a valid value after this method is invoked. Implementations of this method must invoke Field.setExtent(int, int) with the size used by the field.

During this call, Field.setExtent(int, int) must be called with parameters such that both width and height are between 0 and the values passed into this function for the Manager to be able to position this Field properly.

Fields may cache system attributes for efficiency (such as the current system font); however, they cannot depend on these attributes remaining unchanged. When one of these attributes changes, a message event is sent to that effect: in these cases, this method refetch and cache these attributes.

Specified by:
layout in class Field
Parameters:
width - Amount of available horizontal space.
height - Amount of available vertical space.
See Also:
Field.layout(int, int)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

paint

protected void paint(Graphics graphics)
Paints the MapField. Subclasses can override to provide overlays on the MapField.

Specified by:
paint in class Field
Parameters:
graphics - The graphics context.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0

updateView

protected void updateView()
Deprecated. MapField.move(int, int), MapField.moveTo(int, int), MapField.moveTo(Coordinates), MapField.setZoom(int), MapField.zoomIn(), MapField.zoomOut() and MapField.setRotation(int) all implicitly update the MapField.

Updates the MapField to have the set coordinates, zoom level, and rotation rendered to it.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.5.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.