net.rim.device.api.lbs.picker
Class LocationPicker

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.Manager
          extended by net.rim.device.api.ui.Screen
              extended by net.rim.device.api.ui.container.PopupScreen
                  extended by net.rim.device.api.lbs.picker.LocationPicker

public class LocationPicker
extends PopupScreen

The LocationPicker API provides a central repository to group individual LocationPickers such as the GPSLocationPicker, MapsLocationPicker, ContactsLocationPicker, RecentLocationPicker, SuggestedLocationPicker, and the EnterLocationPicker.

Locations will be described by a javax.microedition.location.Landmark

Applications may register with the LocationPicker API as an individual LocationPicker. Registered pickers will be accessible to any application using the LocationPicker API.

Locations selected by the user will be stored and available to the user during subsequent location selections. Stored locations will be accessible to any application using the LocationPicker API.

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 5.0.0

Nested Class Summary
static interface LocationPicker.Listener
          Interface for receiving location picked/cancelled events The Listener interface locationPicked is invoked when a location is selected, or the process is cancelled.
static interface LocationPicker.Picker
          Interface that defines a individual location picker An individual picker must define: A display name A method of "picking" a location Generate a Landmark (i.e.
 
Field Summary
 
Fields inherited from class net.rim.device.api.ui.Screen
DEFAULT_CLOSE, DEFAULT_MENU, NO_SYSTEM_MENU_ITEMS
 
Fields inherited from class net.rim.device.api.ui.Manager
BOTTOMMOST, DOWNWARD, HORIZONTAL_SCROLL, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_MASK, HORIZONTAL_SCROLL_MASK, LEAVE_BLANK_SPACE, LEFTMOST, LEFTWARD, NO_HORIZONTAL_SCROLL, NO_HORIZONTAL_SCROLLBAR, NO_SCROLL_RESET, NO_VERTICAL_SCROLL, NO_VERTICAL_SCROLLBAR, QUANTA_FONT, RIGHTMOST, RIGHTWARD, TOPMOST, UPWARD, VERTICAL_SCROLL, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_MASK, VERTICAL_SCROLL_MASK
 
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
 
Method Summary
Category: Signed  void addLocationPicker(LocationPicker.Picker locationPicker)
          Add an individual location picker to this instance
Category: Signed protected  void cancel()
          Cancels the location picker
Category: Signed  Enumeration getGlobalLocationPickers()
          Get an enumeration of the available 3rd party Location Pickers
Category: Signed static LocationPicker getInstance()
          Returns the default location picker
Category: Signed static LocationPicker getInstance(LocationPicker.Picker[] locationPickers)
          Returns the location picker initialize with an array of individual pickers
Category: Signed  void insertLocationPickerAt(LocationPicker.Picker locationPicker, int index)
          Insert an individual location picker in this instance
Category: Signed static void registerGlobalLocationPicker(LocationPicker.Picker locationPicker)
          Register a global location picker available to all applications
Category: Signed  void removeLocationPicker(LocationPicker.Picker locationPicker)
          Remove an individual location picker from this instance.
Category: Signed  void setFreeTextSearch(boolean useFreeTextSearch)
          Set whether to use free text search i.e.
Category: Signed  void setListener(LocationPicker.Listener listener)
          Sets the listener
Category: Signed  void show()
          Displays the location picker.
Category: Signed static void unregisterGlobalLocationPicker(LocationPicker.Picker locationPicker)
          Remove a global registered location picker
 
Methods inherited from class net.rim.device.api.ui.container.PopupScreen
paint, sublayout
 
Methods inherited from class net.rim.device.api.ui.Screen
add, addKeyListener, addScreenUiEngineAttachedListener, addTrackwheelListener, close, delete, deleteRange, doPaint, ensureRegionVisible, getAccessibleContext, getApplication, getDefaultMenuItem, getDelegate, getField, getFieldAtLocation, getFieldCount, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getGraphics, getLeafFieldWithFocus, getMenu, getScreenAbove, getScreenBelow, getUiEngine, getVirtualKeyboard, insert, invalidate, invalidate, invalidateAll, invalidateLayout, invokeAction, isDataValid, isDirty, isDisplayed, isFocus, isFocusable, isGlobal, isGlobalStatus, isMuddy, isSelecting, keyChar, keyCharUnhandled, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layoutDelegate, makeMenu, navigationClick, navigationMovement, navigationUnclick, onClose, onDisplay, onExposed, onFocus, onFocusNotify, onMenu, onMenuDismissed, onMenuDismissed, onObscured, onSave, onSavePrompt, onUiEngineAttached, onUndisplay, onUnfocus, openDevelopmentBackdoor, openProductionBackdoor, paintBackground, removeFocus, removeKeyListener, removeScreenUiEngineAttachedListener, removeTrackwheelListener, replace, save, scroll, setBackdoorAltStatus, setDefaultClose, setDirty, setFocus, setFocus, setHorizontalQuantization, setPositionDelegate, setTrackballFilter, setTrackballSensitivityXOffset, setTrackballSensitivityYOffset, setVerticalQuantization, touchEvent, trackwheelClick, trackwheelClickUnhandled, trackwheelRoll, trackwheelUnclick, updateDisplay
 
Methods inherited from class net.rim.device.api.ui.Manager
addAll, deleteAll, getHorizontalScroll, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, getVisibleHeight, getVisibleWidth, invalidateFieldRange, isDownArrowShown, isUpArrowShown, isValidLayout, layout, layoutChild, moveFocus, moveFocus, nextFocus, nextFocus, paintChild, setFocus, setHorizontalScroll, setHorizontalScroll, setPositionChild, setScrollListener, setScrollingInertial, setVerticalScroll, setVirtualExtent, subpaint
 
Methods inherited from class net.rim.device.api.ui.Field
drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getOriginal, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getVisualState, getWidth, isEditable, isPasteable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setEditable, setExtent, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, setVisualState, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

getInstance

public static LocationPicker getInstance()
Returns the default location picker

Returns:
An instance of the location picker
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 5.0.0

getInstance

public static LocationPicker getInstance(LocationPicker.Picker[] locationPickers)
                                  throws IllegalStateException
Returns the location picker initialize with an array of individual pickers

Parameters:
locationPickers - - An array of individual location pickers
Returns:
An instance of the location picker
Throws:
IllegalStateException
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 5.0.0

registerGlobalLocationPicker

public static void registerGlobalLocationPicker(LocationPicker.Picker locationPicker)
Register a global location picker available to all applications

Parameters:
locationPicker - - A location picker available to any application
Throws:
ControlledAccessException - If the application does not have PERMISSION_CROSS_APPLICATION_COMMUNICATION permission
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 5.0.0

unregisterGlobalLocationPicker

public static void unregisterGlobalLocationPicker(LocationPicker.Picker locationPicker)
Remove a global registered location picker

Parameters:
locationPicker - - A location picker available to any application
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 5.0.0

addLocationPicker

public void addLocationPicker(LocationPicker.Picker locationPicker)
Add an individual location picker to this instance

Parameters:
locationPicker - - A picker to add to this 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 5.0.0

insertLocationPickerAt

public void insertLocationPickerAt(LocationPicker.Picker locationPicker,
                                   int index)
Insert an individual location picker in this instance

Parameters:
locationPicker - - A picker to insert into this instance
index - position to insert the locationPicker
Throws:
ArrayIndexOutOfBoundsException
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 5.0.0

removeLocationPicker

public void removeLocationPicker(LocationPicker.Picker locationPicker)
Remove an individual location picker from this instance.

Parameters:
locationPicker - - A picker to remove from this 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 5.0.0

getGlobalLocationPickers

public Enumeration getGlobalLocationPickers()
Get an enumeration of the available 3rd party Location Pickers

Returns:
enumeration of registered global location pickers
Throws:
ControlledAccessException - If the application does not have PERMISSION_CROSS_APPLICATION_COMMUNICATION permission
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 5.0.0

setFreeTextSearch

public void setFreeTextSearch(boolean useFreeTextSearch)
Set whether to use free text search i.e. 'Paris', '10 Downing St London UK', '90210 USA'

Parameters:
useFreeTextSearch - - true to use free text search.
Throws:
ControlledAccessException - If the application does not have PERMISSION_LOCATION_DATA permission
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 5.0.0

setListener

public void setListener(LocationPicker.Listener listener)
Sets the listener

Parameters:
listener - - the listener. If null, the current listener is erased.
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 5.0.0

show

public void show()
          throws IllegalStateException
Displays the location picker.

Throws:
IllegalStateException - - If no location pickers have been set
IllegalStateException - - If one or more location picker is null
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 5.0.0

cancel

protected void cancel()
Cancels the location picker

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 5.0.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.