First steps

Last update: API 0.9.0

LocusVersion

Before you start work with Locus Map application, the first necessary step is to get information about installed Locus app(s) - basic question is Locus installed?

An object that transports these data, is called LocusVersion. To get a valid LocusVersion object, use

val lv = LocusUtils.getActiveVersion(ctx)
if (activeLocus == null) {
    // no Locus application is installed
} else {
    // valid application, let's continue
}

LocusUtils.getActiveVersion() tries to find all installed Locus Map applications (usually only single one) and compare their parameters. The version you should get in response will be the last active/running. Because this feature does some deeper tests and communicates with Locus Map, use this method as less as possible. Recommended is only at the start of your application.

LocusVersion is the core object that will be used in most of the API features, so keep it easily available.

LocusInfo

In many situations (the state of Locus, working with the file system, formatting values for the user, some tasks around geocaching, etc.), may be useful to get more information about active Locus version.

For this exists object LocusInfo that contains many interesting facts from Locus life. To get LocusInfo for certain LocusVersion, use

val locusInfo = ActionBasics.getLocusInfo(ctx, lv)
if (locusInfo == null) {
    // for unknown reason (visible in log), info was not loaded
} else {
    // valid info received
}

Three cases may happen with this function:

• all is well and valid (non-null) LocusInfo object is received
• null object is received in case of an unexpected error in communication with active Locus version
• RequiredVersionMissingException exception is thrown in case, Locus is installed but is too old to handle this call

What information may be received with LocusInfo object? Best to check current class source file.

Where to next?

• check basic tasks that may be useful at start
• TODO