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.ScrollView
          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
All Implemented Interfaces:
AdjustmentListener

public class LocationPicker
extends PopupScreen

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

Locations are described by a javax.microedition.location.Landmark object.

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

Global Location Pickers

Applications may register with the LocationPicker API as a global LocationPicker. Registered location pickers can be accessed by any application that uses the LocationPicker API.

If BlackBerry Maps is installed on the device, BlackBerry Maps is registered as a global LocationPicker. Users may select favorite locations that they saved in BlackBerry Maps.

The following code sample demonstrates how to add global LocationPickers:

      LocationPicker locationPicker = LocationPicker.getInstance();
      Enumeration globalPickers = locationPicker.getGlobalLocationPickers();
      
      while (globalPickers.hasMoreElements()) {
          locationPicker.addLocationPicker((LocationPicker.Picker)globalPickers.nextElement());
      }
 

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
Category: Signed static interface LocationPicker.Listener
          Interface for receiving events when a location is selected or when a location selection is canceled.
Category: Signed static interface LocationPicker.Picker
          Interface that defines an individual location picker.
 
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)
          Adds an individual location picker to this instance.
Category: Signed  void cancel()
          Cancels the location picker.
Category: Signed  Enumeration getGlobalLocationPickers()
          Returns an enumeration of the available global location pickers.
Category: Signed static LocationPicker getInstance()
          Returns the default LocationPicker.
Category: Signed static LocationPicker getInstance(LocationPicker.Picker[] locationPickers)
          Returns the LocationPicker initialized with an array of individual pickers.
Category: Signed  void insertLocationPickerAt(LocationPicker.Picker locationPicker, int index)
          Inserts an individual location picker into this instance.
Category: Signed static void registerGlobalLocationPicker(LocationPicker.Picker locationPicker)
          Register a global location picker that is available to all applications.
Category: Signed  void removeLocationPicker(LocationPicker.Picker locationPicker)
          Removes an individual location picker from this instance.
Category: Signed  void setFreeTextSearch(boolean useFreeTextSearch)
          Specifies whether to use free text search (for example, 'Paris', '10 Downing St London UK', '90210 USA').
Category: Signed  void setListener(LocationPicker.Listener listener)
          Sets the listener for the location picker.
Category: Signed  void show()
          Displays the location picker.
Category: Signed static void unregisterGlobalLocationPicker(LocationPicker.Picker locationPicker)
          Removes a registered global 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, addInputSettings, addKeyListener, addScreenUiEngineAttachedListener, addTrackwheelListener, clearInputSettings, close, delete, deleteRange, doPaint, ensureRegionVisible, getAccessibleContext, getApplication, getContextMenuProvider, getDefaultMenuItem, getDelegate, getField, getFieldAtLocation, getFieldCount, getFieldWithFocus, getFieldWithFocusIndex, getFocusRect, getGraphics, getInputHelper, getInputSettings, getLeafFieldWithFocus, getMenu, getScreenAbove, getScreenBelow, getTitleBar, 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, removeInputSettings, removeKeyListener, removeScreenUiEngineAttachedListener, removeTrackwheelListener, replace, save, scroll, setBackdoorAltStatus, setContextMenuProvider, setDefaultClose, setDirty, setFocus, setFocus, setHorizontalQuantization, setInputHelper, setPositionDelegate, setTitleBar, 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, insertAll, invalidateFieldRange, isDownArrowShown, isUpArrowShown, isValidLayout, layout, layoutChild, moveFocus, moveFocus, nextFocus, nextFocus, paintChild, setFocus, setPositionChild, setScrollingInertial, setVirtualExtent, subpaint
 
Methods inherited from class net.rim.device.api.ui.ScrollView
configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, setCurrentLocation, setExtent, setHorizontalAdjustment, setHorizontalScroll, setHorizontalScroll, setScrollListener, setVerticalAdjustment, setVerticalScroll, setVerticalScroll, valueChanged, waitForScrolling
 
Methods inherited from class net.rim.device.api.ui.Field
drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getVisualState, getWidth, isEditable, isEnabled, isPasteable, isScrollCopyable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setEditable, setEnabled, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, 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 LocationPicker.

Returns:
An instance of the LocationPicker.
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 LocationPicker initialized with an array of individual pickers.

Parameters:
locationPickers - An array of individual location pickers.
Returns:
An instance of the LocationPicker.
Throws:
IllegalStateException - if no location pickers were specified.
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 that is available to all applications.

Parameters:
locationPicker - A location picker that is 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)
Removes a registered global location picker.

Parameters:
locationPicker - A location picker that is 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)
Adds an individual location picker to this instance.

Parameters:
locationPicker - The location 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)
Inserts an individual location picker into this instance.

Parameters:
locationPicker - The location picker to insert into this instance.
index - The 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)
Removes an individual location picker from this instance.

Parameters:
locationPicker - The location 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()
Returns an enumeration of the available global location pickers.

Returns:
An 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)
Specifies whether to use free text search (for example, 'Paris', '10 Downing St London UK', '90210 USA').

Parameters:
useFreeTextSearch - true to use free text search, false otherwise.
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

setListener

public void setListener(LocationPicker.Listener listener)
Sets the listener for the location picker.

Parameters:
listener - The location picker 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 were 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

public void cancel()
Cancels the location picker.

Cancels any active picker including any geocode requests. Any open picker screens are closed. If no picker is active or displayed, this method does nothing.

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.