Hello,

since the old days of Appeon Mobile, now PowerServer Mobile, the possibility to write PowerScript and deploy a mobile apps to iOS and Android devices has been a great plus to PowerBuilder developers. Clearly the ability do leverage full-fledged DataWindow presentation styles and functionality, as well support for the majority of PowerBuilder objects, has made the way to Mobile apps distribution as easy and quick as building a desktop application.

However, the PowerServer Mobile features are not "limited" to the regular PowerBuilder language.

A handful of additional API allows to control a wide range of builtin sensors and software functionality that are exclusive of smartphones and tablets. Among them, geolocation, maps, camera, barcode, e-payment, fingerprint recognition to name a few. 

Goal of the Article

This article demonstrates how easy is to write simple PowerScript to use the default Maps functionality and create immersive location experiences and make better business decisions with accurate real-time data and dynamic imagery.

Indeed, the list of use cases is as intuitive as powerful:

• visually embed terrain and driving maps within an application, display the current position, zoom in, zoom out or move so that mobile-optimized address information can be created;
• access latitude, longitude, altitude, speed and more through the GPS chip;
• convert addresses into map coordinates and viceversa;
• record movements and register them on a map;
• process annotations by means of add, remove or select custom labels and images on the maps.

Here below you can see a PowerServer Mobile app with a few buttons to localize your position, display user annotations and change the map type between normal, satellite or hybrid. The map displays 5 custom annotations corresponding to different touristic places mostly in the Tuscany region, Italy. They are shown in different colours, although also images can be specified. Additionally, when users tap a given annotation, a bubble will show up with given title and subtitle.

So this is the kind of app we are going to build today.

And in order to do that, let me quickly brush up on the API provided by PowerServer Mobile.

Mobile API

PowerServer API is provided via the appeon_workaround.pbl library, which is located under C:\inetpub\wwwroot\appeon\developTempFile\appeon_workarounds after PowerServer si installed.

In this PBL, there’s a visual class called eon_mobile_mapex.

It consists of events, for instance when you click on an annotation, or the current location is changed, or an error occurs.

It provides a number of functions to add, remove, select annotations or convert addresses to and from coordinates.

It also contains two basic structures, one for the map options – like whether users are allowed to move and zoom or to jump to the current location – and one for the annotation settings – like coordinates, pincolor, image and description.

Implementation

Let's now move to coding. First of all, create an empty window and drag on it a eon_mobile_mapex User Object. 

Name it uo_map.

In the window's open event, declare and set a structure that stores the initial map options, by means of rights to move and zoom, satellite view and 2 km accuracy.

eon_mobile_str_mapoption istr_mapoption

istr_mapoption.b_locatetocurrentlocation=False
istr_mapoption.b_allowmove=True
istr_mapoption.b_allowzoom=True
istr_mapoption.i_mapaccuracy=2000
istr_mapoption.i_maptype=0

Then, yet in the open event, add 5 annotations and specify their name, address info and pincolor in dedicates arrays. Latitude and longitude will be later derived automatically and stored in zero-initialized arrays. 

String label[] = {"Florence","Lucca","Bologna","Pisa","Siena"}
String subtitle[] = {"Santa Maria del Fiore Cathedral", "Roman Amphitheatre","San Petronio Basilica","Leaning Tower","Piazza del Campo"}
String city[] = {"Florence","Lucca","Bologna","Pisa","Siena"}
String street[] = {"Santa Maria Cathedral","Piazza dell'Anfiteatro","Basilica San Petronio","Leaning Tower","Piazza del Campo"}
Decimal latitude[] = {0,0,0,0,0}
Decimal longitude[] = {0,0,0,0,0}
Decimal pincolor[] = {0,2,0,1,2} // 0=RED,1=GREEN,2=PURPLE

The Map visual object is initialized by the of_open() function with options specified above.

The coordinates of each annotation is calculated from its address. This is the purpose of the of_addressToCoordinates() function. At each step, of_addAnnotation() displays the ith annotation, while the second argument sets the first annotation as the center of the map.

If uo_map.of_open(lstr_mapoption) = 1 Then
   // Add annotations to the map and move to the first one
   int i
   For i = 1 To UpperBound(label)
      // Build up address and convert to coordinates
      uo_map.of_addresstocoordinate(city[i] + ', ' + street[i], longitude[i], latitude[i])

      // Prepare annotation
      eon_mobile_str_annotation lstr_annotation
      lstr_annotation.s_title = label[i]
      lstr_annotation.s_subtitle = subtitle[i]
      lstr_annotation.i_pincolor = pincolor[i]
      lstr_annotation.dec_latitude = latitude[i]
      lstr_annotation.dec_longitude = longitude[i]

      // Add annotation to map and move to 1st location
      uo_map.of_addannotation(lstr_annotation, (i=1))
   Next 
End If

Quite handy, isn’t it?

Of course in a real app, you are most likely going to retrieve a few addresses from a DB, loop over them and convert each one into latitude and longitude.

Should you need to add annotations on the go, it is possible to use the eon_mobile_geolocationex object that provides realtime geolocation.

Instead of coloured pins, annotations can also be represented by icons using the s_pinimage property of eon_mobile_str_annotation structure:

String pinimage[] ={"L1.jpg","L2.jpg","L3.jpg","L4.jpg","L5.jpg"}

[...]

lstr_annotation.s_pinimage = pinimage[i]

Relevant API to trigger annotation management are:

• uo_map.of_removeAnnotation(eon_mobile_str_annotation lstr_annotation), which removes a given annotation from the Map;
• uo_mapex.of_selectAnnotation(eon_mobile_str_annotation lstr_annotation), which selects and moves to a given annotation;
• uo_mapex.of_refresh(eon_mobile_str_mapoption lstr_mapoption), which refreshes the map and sets the center at specified latitude/longitude.

Run the code

Time to run the app.

You can deploy the source code as a PowerServer Mobile project, and then use the Appeon WorkSpace (AWS) to run the app from an actual mobile device (iOS or Android smartphone/tablet) without building an IPA/APK package, which may need to undergo a number of packaging and distribution steps especially on iOS. At any rate, Powerbuilder Universal offers the necessary build toolchain.

Summary

This tutorial has shown how to use the eon_mobile_map object to access and manipulate geo-location information such as longitude, latitude and address, as well as add and remove custom annotations. This visual object is part of the Appeon PowerServer workarounds API and offers solution to a wide range of use cases like city planning, mountaineering, tourism and route navigation, with the ease of PowerBuilder syntax and the power of PowerServer Mobile deployment.