Place pickers

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

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

A PlacePicker 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, such as 'My Location' and local point-of-interest search.

Screen showing a place picker control.

Implementing a place picker

When you implement a PlacePicker, you need to link to the 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 in your app using QML, attach a PlacePicker object to a control. In the following sample, the PlacePicker is attached to a Button that displays the PlacePicker, 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

Here’s how to create a PlacePicker using only C++:

#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 cancelled by the user, or 
  // location capability is not enabled.
}
// Destruction of the picker pointer is handled by QScopedPointer

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

Last modified: 2013-12-21



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

comments powered by Disqus