Display points on a map

One of main tasks that may come on your mind ... display few custom points on Locus map. Here are simple steps you need to follow.

Creating single point

Points in Locus API are stored in container called Waypoint (it's not correct as 'waypoints' are usually points attached to tracks, we know).

How to construct waypoint

Prepare Location object with coordinates. Provider parameter define source of location. This object may also contains other useful parameters like speed, elevation, etc..

Location loc = new Location(provider)
loc.setLatitude(Math.random() + 50.0);
loc.setLongitude(Math.random() + 14.0);
loc.set...

With known location, we may create a Waypoint as

Waypoint point = new Waypoint(name, loc);

Sending data to Locus

It is needed to describe two main options.

• send data when Locus is not running or if you wants to give option to import them into Database
• send data to already running application

In both cases, we needs to prepare PackWaypoints container that will be send to Locus application. Once this pack is created, ActionDisplayPoints is all you need.

Creating PackWaypoints

Usually we wants to send more points at once, not just a single. In all cases, points from same source (like your add-on) should be packed into single container. To create this container, simply use

PackWaypoints pw = new PackWaypoints("my pack ID");

// add points you wants to send
pw.addWaypoint(point)

Send points by startActivity

In case, Locus is not running or in case, you wants to offer import into Locus database, use this method.

ActionDisplayPoints.sendPack(context, pack, extraAction);

Or if you wants to send more packs at once

ActionDisplayPoints.sendPacks(context, packs, extraAction);

ExtraAction parameter define if we wants data only display or directly offer import.

Send points by sendBroadcast

In case, Locus is running and we do not wants to disturb users, we may send data silently. This means, points will be immediately loaded on a map. In such cases, we may use similar functions called

ActionDisplayPoints.sendPackSilent(context, pack, center);

or for more packs at once similar

ActionDisplayPoints.sendPacksSilent(context, packs, center);

Center parameter in above methods allows to center map on received data immediately, they are loaded. Be careful with this parameter as it may really cause unexpected behavior to users.

Sending huge number of points/packs

System of intents has one major limitations. Android support intents up to size 2 MB (before Android 3.x it was only 1 MB). So if you send huge number of points (it is case of geocaching points mainly), which packed into binary file has size bigger then this limit, data won't be correctly send! In this case we need to use method, when data are temporary stored to filesystem and Locus loads them from file.

ActionDisplayPoints.sendPacksFile(context, packs, filepath, extraAction);

or similar silent version

ActionDisplayPoints.sendPacksFileSilent(context, packs, filepath, center);

Silent version is not anyway recommended here, because working with such huge data packs on background may slow down application a lot.

Be also careful, that this method may require filesystem permissions.