Place pickers

A PlacePicker control allows you to browse and select places. The PlacePicker control supports choosing places based on the current location of a user, from a database of favorites, from recent selections, from contact addresses, and from remote search results.

The PlacePicker control extends the CustomControl class, and consists of a set of sheets running modally. When a PlacePicker control is in focus, operations are blocked until you select a place or cancel the PlacePicker control.

A PlacePicker control returns a SelectedPlace object pointer when a selection is made. A non-null pointer indicates that a place has been selected successfully.

You must enable the location capability in your app to launch some features of a PlacePicker control, such as 'My Location' and local point-of-interest search.

Screen showing a place picker control.

Prerequisites for a place picker

When you implement a PlacePicker control, you need to link to the appropriate library to be able to use the class in your app. In your .pro file, add the following line immediately after the CONFIG line:

LIBS += -lbbcascadesplaces

To implement a PlacePicker control in your app using QML, attach a PlacePicker object to a control. In the following sample, the PlacePicker object is attached to a Button that displays the PlacePicker control, and updates the Label text according to the selected place.

If you are using an API level of 10.1 or later, you don't have to register the PlacePicker and SelectedPlace custom controls. You just have to import the bb.cascades.places library in your QML file.

import bb.cascades.places 1.0
 
Page {
  content: Container {
    Label {
      id: title
      text: "Place name selected"
    }
    Button {
      text: "Click to open PlacePicker"
      onClicked: {
         var place = picker.show ()
         if (place) {
           title.text = place.name
         } else {
           title.text = "No place selected"
         }
       }
    }
  }
  attachedObjects: [
    PlacePicker {
      id: picker
    }
  ]
}

If you are using an API level of 10.0, you need to register the PlacePicker and SelectedPlace custom controls in C++ so you can use them in QML:

qmlRegisterType<bb::cascades::places::PlacePicker>
    ("CustomComponents", 1, 0, "PlacePicker");
qmlRegisterUncreatableType<bb::cascades::places::SelectedPlace>
    ("CustomComponents", 1, 0, "SelectedPlace",
    "Class SelectedPlace is not instantiable.");

You also need to add the following import statement in your QML:

import CustomComponents 1.0
#include <bb/cascades/places/PlacePicker>
 
QScopedPointer<PlacePicker> picker = new PlacePicker();
SelectedPlace *sp = picker->show();
if (sp != NULL) {
  // Extract details from SelectedPlace object
  label.text(sp->name());
 
  // Detaches sp from parent picker so it can 
  // still be used after the picker is destroyed
  sp->setParent(NULL);
} else {
  // The operation is canceled by the user, or 
  // location capability is not enabled
}
// Destruction of the picker pointer is handled by QScopedPointer

Not applicable

For a more detailed PlacePicker sample, check out the PlacePicker sample in GitHub.

Last modified: 2015-05-07



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus