This document describes how you get started with using the Core V.2 LBS API. The document is based on the test client for Linux. Please also review the test client after reading this document.
Wayfinder API test client
The Wayfinder API test client is a simple sample client for using the Core V.2 LBS API that has test implementations of the interfaces provided by the Core V.2 LBS API.
The test client can be run in two different modes, the first one is command line mode in which there is a text display and input interface and then there is the Gtk interface with a map window in which keys can be pressed.
Furthermore, the test client can be started with a parameter stating which language the user want to run with, affecting both map and sounds. This parameter is
-l <language number>.
In the command line mode a help is printed with the available commands to enter in the main menu, in which there are several sub menus and a quit option available for selection.
Help menu, following commands exists:
dImage test menu.
fFavourite option. Add, delete, sync and get Favourites.
gLocation test menu.
hDisplays this help menu.
pSettings test menu.
rRoute option, you should specify origin and destination in WGS84 Coordinates.
sSearch test menu.
When selecting a sub menu option the help for that menu is printed with the available options for that menu. In all sub menus there is a back option to go back to the main menu and a help option to get the options listed again, this help option is also available in the main menu.
When running the test client there will be a Gtk window opened and a sample implementation of the map API with overlays and input. The
z key can be used to zoom in and the ´x` key to zoom out (m and n zooms in and out in incremental steps). Note that the map window can only respond to single character commands. If making a search, switch console window and enter your search string there and press enter. Then switch back to the map window to continue using the map.
Pressing enter after each character is not needed here, in fact maplib (which handles the key presses when in graphical mode) does not accept multiple character input, hence running the test
ss won’t be available and pressing enter will not do anything.
One typical test case could be to start the client on the device, press
r for route menu, then d for calculating a default route. When the route has been calculated the red line should appear on the map if it’s scrolled. Pressing
s after that starts the navigation simulation. Pressing 3 activates the 3d map mode, and 2 would put it back to 2d mode.
All tester classes inherits from a common super class named GenricTester that has the common handling of commands.
The main class for the testers is
WFAPITester that creates all the other testers and handles the main menu as well as sending the input commands to the currently active tester.
There are the following tester classes in the test client:
WFAPITester– starts Nav2API and is the holder of the rest of the testers.
FavouriteTester– tests for favourites.
ImageTester– tests for image retrieval.
LocationTester– tests for receiving location updates
RouteTester– tests for routes and navigation.
SearchTester– tests for searching.
SettingsTester– tests for settings.
NetworkTester- tests the network
BillingTester- tests for the billing interface.
ServiceWindowTester- tests the tunnel interface.
Running the testclient
Go to the folder where the test clients binary is located and run the command:
When starting the test client a help menu is presented:
From here the different test types are started. The help menu is always available by inputting “h”
Input to the test client differs depending on which platform it runs on and in which mode it’s run in, but for Linux just enter the commands using the keyboard.
The Nav2API is created in the constructor of WFAPITester, simply by doing
m_nav2API = new LinuxNav2API();
This call creates a new instance of the Nav2API for Linux platform. Below gives an example of how Nav2API should be started.
There are two callback functions that gets called by the Nav2API when startup is done.
When the above is done the Nav2API and MapLib are ready to use. An example of how to use one of the interfaces in Nav2API is described below.
When the route has been calculated the
routeReply() callback function, which is inherited from
RouteLister, will be called by the Nav2API. The UI now knows that the requested route has been calculated and can start navigation, fetching the route list etc.
Connecting MapLib to Nav2API
After the Nav2API has been successfully started it is possible to create and connect MapLib to Nav2API. The test application creates and connects MapLib to Nav2API.
The GtkDevControl is an example class that is using the MapLib API for the most common use cases, such as zooming, panning the map, adding and removing overlay items etc. This constructing and connection is done by the following code.
The first parameter is the path to images, i.e. where to find images for the overlay items to add. The second parameter is the network connection for MapLib to use, which are coming from Nav2API. The last parameter is a
WFAPI::ExternalKeyConsumer*, which is used to catch key events that
GtkDevControl does not handle.
For demonstration purposes, there is also a
UIControl class which shows how it is possible to update the map (
GtkDevControl) based on information received from Nav2. The UI controller is created and connected here in
UIControl class currently implements the listener interfaces from
LocationListener. When receiving location updates, the me marker on the map is updated to that position and the map is centered based on the updated position. The map is also rotated according to the heading.
UIControl will also update text labels in
GtkDevControl with distance to next turn and the name of the current street (just as examples). This is a simple and naïve implementation of parts of a navigation UI, meant to be an example of how a real navigation applications could be developed using the APIs. In order to start the navigation which will update the map as stated above, the easiest is to enter the following commands from the keyboard:
```‘h’ To get help text] ‘r’ To enter route menu] ‘d’ To create the default route] .. Wait about 10 seconds until the route has been calculated. ‘s’ To start simulation of the route] ´´´
Handling key events
When the test client is started with MapLib integrated all key events are first captured by the
GtkDevControl. The key events that are unhandled by GtkDevControl, are instead supplied into the Nav2API tester classes using the
WFAPI::ExternalKeyConsumer. In this way it is possible to zoom in and out in the map using
x, but also be able access the rest of the Nav2API tests (making routes etc).
Note that any key events must be supplied using the simulator virtual key pad when MapLib is enabled.
Initialization of key mappings; The following call in
GtkDevControl is responsible for initializing key mappings:
MapLib contains a class called
MapLibKeyInterface. This contains a number of different key names, listed below. The enum can be found in
These key names should be mapped against real key/pointer events coming from the framework. The way we do it in the
GtkDevControl.cpp is to map a Gtk specific key against a key name from the above list, e.g.
MapLibKeyInterface::ZOOM_OUT_KEY. By doing this you can easily translate a key event from the framework to an action that MapLib can execute.
Below is an example of how we do when mapping key types against map operations in the
When getting a callback by the framework in the listening function for key events it is quite simple to retrieve the correct MapLib key. Below is an example of how this is done in the
As you can see above, the mapped MapLib key is fetched by using the key from the key map, in this application the GdkEventKey. This key is then sent to the MapLibKeyInterface which will perform the correct map operation, such as zooming in, zooming out, panning the map etc.
Initializing window components
The following code in GtkDevControl is responsible for creating and initializing windows, registering key event callbacks and other Gtk specific code. This part does not contain any MapLib specific code.
This part is where you add the code that contains the actual map and it’s components. The initial method call in
GtkDevControl looks like this (supplying the connection retrieved from Nav2API):
The basic steps performed by this section is to create the MapLibAPI using the supplied factory methods. In addition to this, listeners are registered to MapLib to get notifications about when a map object has been selected, etc.
Initialization of overlays and dialogs
The following section in GtkDevControl is responsible for setting up some sample overlay items:
A seperate class,
OverlayZoomSetup, is added as a sample implementation of how to generally configure the visual representation of overlay items. This includes, which background images to use for the different zoom levels (S,M,L) and modes (highlighted or stacked). It also contains information about where the focus point of these images should be (i.e. the position of the image that should be set to the coordinate of the overlay item), etc. The keys
l are configured to toggle visibility for the friends and location layer respectively.
The following method call sets up the visuals for how the stacked dialogs should look, i.e. the dialog that appears when selecting one of multiple overlay items.
Wayfinder API utility functions
Included in the
WFAPITestClient source code directory, there is also one Utility class available which can be used to determine distance between two coordinates.
WFAPITestClient.cpp contains commented code which uses the utility function to calculate the distance between two coordinates:
If the calculated distance should be compared with another distance threshold, then we suggest that instead of taking the square root of the calculated distance, instead square the distance threshold (to increase performance) before doing the comparison.