Create the UI

In your project, open the main.qml file, which contains the QML code for the UI of our app. Remove the prepopulated code that's included in the file and start coding from a blank file.

We start by importing the latest versions of the Cascades QML library and the Places library. If we design our app using the latest libraries, we can use the latest classes and their properties. To learn more about using the latest versions of the APIs, see API levels. We design our UI so that it uses asset selectors and design units to adapt to different devices. For more information, see Resolution independence and Design units 10.3.

Our UI is straightforward, so we start by creating a Page with a Container that displays our background image of a place marker using an ImageView. We use a DockLayout to format our Container so that we can fill the available width and height of the Container. For more information about using layouts, see Layouts.

import bb.cascades 1.3
import bb.cascades.places 1.0

Page {
    Container {
        layout: DockLayout {}

        // The background image
        ImageView {
            horizontalAlignment: HorizontalAlignment.Fill
            verticalAlignment: VerticalAlignment.Fill

            imageSource: "asset:///images/background.png"
        }
    }
}

Now we add a custom component to our UI container. Custom components are reusable UI components that can be used in the same way as any other component that comes with the framework. We use this custom component to handle devices with different screen sizes. If our app runs on an all-touch BlackBerry device, we can use a simple container for our UI. If our app runs on a device with a physical keyboard, we want to add our UI in a ScrollView to allow scrolling so that we can see more of the UI. We don't need to code the logic for this decision; we need to use the static asset selector. You learn more about how to do this later in the tutorial.

In your main.qml file, add the PlacepickerScrollView custom component after the ImageView that displays the background image for our UI. For now, we add a Container and a Button to this component. The Container uses du() to make sure that the positioning of the button suits every device density. The Button lets the user select a place from the PlacePicker and display it in the UI. The labels are populated with the properties of each SelectedPlace.

        // The custom container for our UI
        PlacepickerScrollView {
            horizontalAlignment: HorizontalAlignment.Fill

            Container {
                horizontalAlignment: HorizontalAlignment.Fill
                verticalAlignment: VerticalAlignment.Fill

                leftPadding: ui.du(3.3)
                topPadding: ui.du(5.6)
                rightPadding: ui.du(3.3)


                // The 'Select Place' button
                Button {
                    horizontalAlignment: HorizontalAlignment.Center

                    text: qsTr("Select Place")

                    onClicked: placePicker.selectPlace()
                }
            }
        }

In the PlacepickerScrollView component, we finish the UI with a Container of Label objects that display information about each place that the user selects. These labels use two custom components (FieldLabel and FieldNumber) to format the display of the information, because we want them all to be similarly displayed. We define these two custom components later in the tutorial.

Two properties that we display need an API level of 10.2. The isoAlpha3CountryCode and the isoAlpha2CountryCode properties were introduced in 10.2. We can reference these properties because we imported the 10.2 version of the Places library with the import bb.cascades.places 1.2 statement at the beginning of our main.qml file. If we try to run our app using an API level lower than 10.2, our app won't build and run. For more information, see API levels.

Now we need a mechanism for letting users choose a place they can display. You can attach a PlacePicker as an attached object. We add the PlacePicker as an attached object to the Container that holds our entire UI.

Page {
    Container {
        layout: DockLayout {}
    
    // ... (this is where the UI was defined)
 
    }

    attachedObjects: [
        PlacePicker {
            id: placePicker

            property variant selectedPlace

            function selectPlace()
            {
                selectedPlace = show()
            }
        }
    ]
}

We are finished with the UI of our app and the main.qml file. If we try to build our application now, it would build successfully, but it would throw errors when we run it, because we still need to define our custom components. We need to create three custom components: FieldLabel, FieldNumber, and PlacepickerScrollView. A custom component is a QML document that defines a single QML component that you can use in an application. To create a QML component, you create a file called <Name>.qml, where <Name> is the component name and it begins with an uppercase letter.

import bb.cascades 1.3
import bb.cascades.places 1.0

Page {
    Container {
        layout: DockLayout {}
        
        // The background image
        ImageView {
            horizontalAlignment: HorizontalAlignment.Fill
            verticalAlignment: VerticalAlignment.Fill
            
            imageSource: "asset:///images/background.png"
        }
        
        // The custom container for our UI         
        PlacepickerScrollView {
            horizontalAlignment: HorizontalAlignment.Fill
            
            Container {
                horizontalAlignment: HorizontalAlignment.Fill
                verticalAlignment: VerticalAlignment.Fill
                
                leftPadding: ui.du(3.3)
                topPadding: ui.du(5.6)
                rightPadding: ui.du(3.3)                
                
                // The 'Select Place' button
                Button {
                    horizontalAlignment: HorizontalAlignment.Center
                    
                    text: qsTr("Select Place")
                    
                    onClicked: placePicker.selectPlace()
                }
                
                // The container with all the place fields
                Container {
                    horizontalAlignment: HorizontalAlignment.Fill
                    verticalAlignment: VerticalAlignment.Fill
                    topMargin: ui.du(5.6)
                    
                    //! [1]
                    FieldLabel {
                        title: qsTr("name")
                        field: "name"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("alternative name")
                        field: "alternativeName"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("description")
                        field: "description"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("street")
                        field: "street"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("city")
                        field: "city"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("region")
                        field: "region"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("country")
                        field: "country"
                        selectedPlace: placePicker.selectedPlace
                    }
                    FieldLabel {
                        title: qsTr("postal code")
                        field: "postal"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("address label")
                        field: "addressLabel"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("phone")
                        field: "phone"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("secondary phone")
                        field: "secondaryPhone"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("fax")
                        field: "fax"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("email")
                        field: "email"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("web site")
                        field: "url"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldNumber {
                        title: qsTr("rating")
                        field: "rating"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldLabel {
                        title: qsTr("map URL")
                        field: "mapURL"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldNumber {
                        title: qsTr("latitude")
                        field: "latitude"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldNumber {
                        title: qsTr("longitude")
                        field: "longitude"
                        selectedPlace: placePicker.selectedPlace
                    }
                    
                    FieldNumber {
                        title: qsTr("altitude")
                        field: "altitude"
                        selectedPlace: placePicker.selectedPlace
                    }
                }
            }
        }
    }
    
    attachedObjects: [
        PlacePicker {
            id: placePicker
            
            property variant selectedPlace
            
            function selectPlace()
            {
                selectedPlace = show()
            }
        }
    ]
}

Last modified: 2014-11-17



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

comments powered by Disqus