Friday, April 18, 2014

It's Easy and Fun to Write Map Based Apps

Yesterday I started work on an app that I personally want to use. I don't have a car, so I use services like Metro Bus, Metro Rail, Car2Go, and BikeShare around DC all the time. It's annoying to go to each different web page or app to get the information that I want, so I decided to write an app that combines it all for me in one place.

After asking around, I settled on a best practice for Ubuntu map apps, and I was pointed to this excellent code as a basis:
http://bazaar.launchpad.net/~yohanboniface/osmtouch/trunk/view/head:/OSMTouch.qml

It was so easy and fun once I got started, that I decided to show the world. So, here we go.

I started with a "Simple UI" project. Then I deleted the default column that it started with, and I set the title of the Page to an empty string. While I was at it, I changed the height and width to be more like a phone's dimensions to make testing a little easier. So my starter code for an emply Window looks like this:
 import QtQuick 2.0  
 import Ubuntu.Components 0.1  
 import "components"  
 MainView {  
   objectName: "mainView"  
   applicationName: "com.ubuntu.developer.rick-rickspencer3.MapExample"  
   width: units.gu(40)  
   height: units.gu(60)  
   Page  
   {  
     title: i18n.tr("")  
   }  
 }  
So what's missing now is a map. First I need to import the parts of Qt where I get location and map information, so I add these imports:
 import QtPositioning 5.2  
 import QtLocation 5.0  
Then I can use the Map tag to add a Map to the MainView. I do four things in the Map to make it show up. First, I tell it to fill it's parent (normal for any component). Then I set it's center property. I choose to do this using a coordinate. Note that you can't make a coordinate in a declarative way, you have to construct it like below. The center property tells the map the latitude and longitude to be centered on. Then I choose the zoom level, which determines the scale of the map. Finally, I need to specify the plug in. For various reasons, I choose to use the Open Street Maps plugin, though feel free to experiment with others. So, a basic funcitonal map looks like this:
   Page  
   {  
     title: i18n.tr("")  
     Map  
     {  
       anchors.fill: parent  
       center: QtPositioning.coordinate(38.87, -77.045)  
       zoomLevel: 13  
       plugin: Plugin { name: "osm"}  
     }  
    }  
When I run it, I get a lot of functionality for free. On the desktop I can drag the map, and when I run the app on my phone or tablet, I can pinch to zoom in or out. All that functionality comes for free. Of course, you are free to add mapping controls as desired, but I find that map works well out of the box, at least on a device that supports pinch and zoom.


Typically, a map displays little pinpoints. These are often referred to as Points of Interest, or more typically "POI". It's delightfully easy to populate your map with POI using our old friend XmlListModel. First, you will need some XML that has location information. For this exmaple, I am going to use the Bike Share feed for Washington, DC. It's easy to get and to parse, so it makes a nice example. You can see the feed here:
https://www.capitalbikeshare.com/data/stations/bikeStations.xml

So let's use it to set up our XmlListModel. First, of course, we need to import the XmlListModel functionality.


 import QtQuick.XmlListModel 2.0  
Next, we'll make the list model, and use the query and Roles functionality to set up the model with the latitude and longitude of each POI inside the model. This is *exactly* like using the XmlListModel for a typical list view. Very cool.
   XmlListModel  
   {  
     id: bikeStationModel  
     source: "https://www.capitalbikeshare.com/data/stations/bikeStations.xml"  
     query: "/stations/station"  
     XmlRole { name: "lat"; query: "lat/string()"; isKey: true }  
     XmlRole { name: "lng"; query: "long/string()"; isKey: true }  
   }  
Now that I have my list model set up, it's time to display them on the Map. We don't do that with a ListView, but rather wtih a MapItemView. This works exactly the same as a ListView, except it displays items on a map instead of in a list. Just like a ListView I need a delegate that will translate use data from the each item in the XmlListModel to create a UI element. In this case, it's a MapQuickItem instead of a ListItem (or similar). A MapQuickItem needs to know 4 things.

  1. The model where it will get the data. In this case, it's my XmlListModel, but it could be a javascript list or other model as well.
  2. A latitude and longitude for the POI, which I set up as roles in the XmlListModel.
  3. An offset for whatever I am using for POI so that it is positioned properly. In this case I have made a little pushpin image out of the bikeshare logo (I know it's bad I'll make a better one later :) ). The offset is set by anchorPoint, so I make the anchorPoint the bottom and center of of the pushpin. 
  4. Something to use for the POI. In this case, I choose to use an image. Note that it is important to use grid units, or the POI may appear too small on some devices, and too large on others. Grid Units make them "just right" on all devices, and ensure that users can click them on any device. 


So, here is my MapItemView that goes *inside* the Map tag. It's a MapItemView for the map, after all.

       MapItemView  
       {  
         model: bikeStationModel  
         delegate: MapQuickItem  
         {  
          id: poiItem  
          coordinate: QtPositioning.coordinate(lat,lng)  
          anchorPoint.x: poiImage.width * 0.5  
          anchorPoint.y: poiImage.height  
          sourceItem: Image  
          {  
            id: poiImage  
            width: units.gu(2)  
            height: units.gu(2)  
            source: "bike_poi.png"  
          }  
         }  
       }  
Now when I run the app, the POI are displayed. As you would expect, when the user moves the Map, the MapItemView automatically displays the correct POI. It's really that easy.


If you want to add interactivity, that's easy, you can simply add a MouseArea to the Image and then use things like Ubuntu.Components.Popups to popup additional information about the POI. 


This sample code is here: http://bazaar.launchpad.net/~rick-rickspencer3/+junk/MapExample/view/head:/MapExample.qml

No comments:

Post a Comment