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

Map field renders a map using the current mapping service.

There are three basic ways to navigate the MapField:

     move(int int) - move the map by a certain number of pixels.
     moveTo(Coordinates) - move the map to the location specified by a Coordinate object.
     moveTo(int int) - move the map to the specified latitude and longitude.

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

     setRotation(int) - rotate the current view.
     setZoom(int) - change the zoom level of the current 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.

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()
          Default constructor.
Category: Signed MapField(long style)
          Constructs a MapField 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 current center of the map view.
Category: Signed  int getLatitude()
          Returns the current center of the map view.
Category: Signed  int getLongitude()
          Returns the current center of the map view.
Category: Signed  int getMaxZoom()
          The maximum zoom level (largest visible area) supported.
Category: Signed  int getMinZoom()
          The minimum zoom level (smallest visible area) 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.
Category: Signed  XYPoint getXYPoint()
          Returns the current 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)
          Move the current view by the given pixels.
Category: Signed  void moveTo(int latitude, int longitude)
          Centers the map view on the specified location.
Category: Signed  void moveTo(Coordinates coordinates)
          Centers the map view on the specified location.
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()
          Causes the MapField to have the set coordinates, zoom level, and rotation be rendered to it.
 
Methods inherited from class net.rim.device.api.ui.Field
drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getAccessibleContext, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isFocus, isFocusable, isMuddy, isPasteable, 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, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, 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 with a given style.

Parameters:
style -
Throws:
MapServiceException - if LBS Map API is not installed.
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()
Default constructor.

Throws:
MapServiceException - if LBS Map API is not installed.
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 set this will override any screen orientation changes from the BlackBerry.

Parameters:
preferredWidth - Preferred width, or -1 for default.
preferredHeight - Preferred height, or -1 for default.
Throws:
IllegalArgumentException - if either param 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()
The minimum zoom level (smallest visible area) 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()
The maximum zoom level (largest visible area) 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 level and the resolution at any particular zoom level may change and should not be assumed.

Parameters:
zoom - Zoom level. getMinZoom() <= zoom <= 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:
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

move

public void move(int dx,
                 int dy)
Move the current view by the given pixels. Note, screen calculations differ from lat/lon 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 hand corner.

Parameters:
dx - the number of pixels to move horizontally. Positive dx moves east if rotation is 0.
dy - the number of pixels to move vertically. Positive dy moves south if rotation is 0.
Throws:
IllegalArgumentException - if resulting 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

moveTo

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

Parameters:
latitude - Latitude in one hundred thousandths of degrees north (south is negative). Valid values are inclusive for -9000000 to 9000000.
longitude - Longitude in one hundred thousandths of degress east (west is negative). Valid values are inclusive for -18000000 to 18000000.
Throws:
IllegalArgumentException - if 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.

Parameters:
coordinates - the location 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 current center of the map view.

Returns:
Latidude 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 current center of the map view.

Returns:
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 current center of the map view.

Returns:
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 current center of the map view as an XYPoint.

Returns:
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 - 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.

Returns:
Rotation in clockwise degrees (0 means 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 ouput 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 ouput 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:
grapics - 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()
Causes the MapField to have the set coordinates, zoom level, and rotation be 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.