Action tasks (Broadcasts) - asamm/locus-api GitHub Wiki

Basic information

Android Broadcasts is a mechanism through which applications in Android communicate. One application may send to second (or also internally between its own components) piece of information bundled in the [Intent] object. The mechanism of how are data sent is called broadcasting.

Samples at the bottom.

How to

Locus Map since version 3.31 supports the new bunch of commands, that are received as Broadcast intent with defined tasks & actions to do.

Every broadcast has to have a defined tasks parameter with a well-formatted JSON object. Tasks usually have other parameters. In most cases, it is the action parameter that defines the sub-action. More in the definition below.

Every single task may have defined only a single action parameter with additional extra parameters. The list below displays all available tasks and their possible actions.

Tasks

`dashboard`

Locus Map/Classic 3.38+

action: "on"
name: "Name of the dashboard"

Display the dashboard defined by its name over the main map screen.

action: "off"

Just hide the current active dashboard. Nothing happens if no dashboard is active.

action: "toggle"

(Locus Map 4.28+), toggle the visibility of the last selected dashboard.

`function`

value: "[name]"

Start certain "big" functions (from internally defined functions, like these available for the functions panel), defined by their unique text ID.

Possible values:

altitude_manager : app altitude manager
quick_action_menu (deprecated, use 'floating_menu' below) : action menu for fast access for predefined functions (since 3.36.0)
floating_menu : action menu for fast access for predefined functions (since 3.53/4.2)
screen_compass : screen with compass
screen_data : screen with users points/tracks, opened on last visible tab
screen_data_points : screen with users points
screen_data_tracks : screen with users tracks
screen_gps : screen with GPS skyplot
screen_map_items : screen with "Map items" system
screen_maps : main app map manager
screen_store : Locus Store for download/purchase of additional content

`guide_to`

Locus Map/Classic 3.49+

name: "Name of point" (optional)
lon: "Geographic longitude (-180°;180°)"
lat: "Geographic latitude (-90°;90°)"

Start guide to a certain point defined by name and coordinates.

`gps_on_off`

Locus Map 4.17

action: "on"

Turn on the GNSS unit.

action: "off"

Turn off the GNSS unit.

action: "toggle"

Toggle the state of the GNSS unit.

`live_tracking_asamm`

action: "start"
name: "Name of configuration"

Start Asamm-based Live tracking defined by "profile ID" identification. Value is visible in the app UI, in the detail of the tracking profile at the bottom.

action: "stop"
name: "Name of configuration" (optional)

Stop Asamm-based Live tracking, optionally with the certain configuration defined by name (won't stop if named configuration is not running).

`live_tracking_custom`

action: "start"
name: "Name of configuration" (optional)

Start custom-based Live tracking, optionally with the certain configuration defined by name (won't start if the named configuration does not exist).

action: "stop"
name: "Name of configuration" (optional)

Stop custom-based Live tracking, optionally with the certain configuration defined by name (won't stop if the named configuration is not running).

`map_center`

action: "on"

Enable map centering.

action: "off"

Disable map centering.

action: "toggle"

Toggle map centering.

`map_hold_center`

Locus Map 4.28

action: "on"

Enable hold map center functionality.

action: "off"

Disable hold map center functionality.

action: "toggle"

Toggle hold map center functionality.

`map_layer_base`

Locus Map 4.18

action: "toggle_last"

Switch the current map to the previously selected map. So it is easy to toggle between current and previous map.

`map_move_x`

value: [+,-]X
unit: "[%,dp,px]" (optional, default: px)
keep_centering: "[true/false]" (optional, default: false)

Move the map in X-axis direction (+ => right), by the defined X value. Optional units modify value. The optional parameter keep_centering allows keeping enabled "hold center".

`map_move_y`

value: [+,-]X
unit: "[%,dp,px]" (optional, default: px)
keep_centering: "[true/false]" (optional, default: false)

Move the map in Y-axis direction (+ => bottom), by the defined X value. Optional units modify value. The optional parameter keep_centering allows keeping enabled "hold center".

`map_move_zoom`

Locus Map/Classic 4.2/3.53

move_by_x: [+,-]X
move_by_x_unit: "[%,dp,px]" (optional, default: px)
move_by_y: [+,-]X
move_by_y_unit: "[%,dp,px]" (optional, default: px)

move_to_lon: "Geographic longitude (-180°;180°)"
move_to_lat: "Geographic latitude (-90°;90°)"

optional

zoom: [0;24] (optional, default: -1)
animate: "[true/false]" (optional, default: true)
keep_centering: "[true/false]" (optional, default: false)

Complex action that is able to move and zoom with the map. It is necessary to follow these conditions:

there has to be defined movement, otherwise, the task will fail
use 'move_by' for relative movement with the map or 'move_to' for absolute movement to a certain location
change of the zoom is an optional parameter
keep_centering is also optional and allows keeping enabled "hold center"

Suggestion: do not use it for repeated actions (like the long-press of the hardware button), because there is no guarantee, that the previous task will be 100% finished. For quick relative movement of the map without any delay (useful for repeated long-press calls for example), use map_move_x and map_move_y actions.

`map_overlay`

Locus Map 4.18

action: "on"

Turn the map overlay on.

action: "off"

Turn the map overlay off.

action: "toggle"

Switch the enabled/disabled state of the map overlay.

`map_reload_theme`

Locus Map 4.18

No parameters are defined here. This is a useful method for map theme creators. It allows you to easily refresh the current map with the theme from the disk. So call this right after you upload an updated version of the theme into the app directory and you need to reload it to see changes.

`map_rotate`

Locus Map/Classic 3.38+

action: "on"

Enable map rotation.

action: "off"

Disable map rotation.

action: "toggle"

Toggle map rotation.

`map_zoom`

action: "+"

Perform zoom-in action.

action: "-"

Perform zoom-out action.

action: "value"

Zoom to a certain value (in range [0;24]).

Sample tasks: { map_zoom: { action: "value", value: "20" } }

`navigate_to`

Locus Map/Classic 3.51+

name: "Name of point" (optional)
lon: "Geographic longitude (-180°;180°)"
lat: "Geographic latitude (-90°;90°)"

Start the "Navigate to" screen to a certain pre-set point defined by name and coordinates. There is still a need to manually trigger the start of navigation in the UI.

`navigation`

Locus Map/Classic 3.51+

action: "nearest_point"

Find the nearest point along the active route and set it as the current navigation target.

action: "recalculate"

Recalculate current active navigation.

action: "stop"

Stop current navigation.

`open`

action: "menu"

Open app main menu.

`poi_alert`

Locus Map/Classic 4.2+/3.53+

action: "start"

Start the POI Alert feature with the last used parameters.

action: "stop"

Stop the POI Alert feature.

`preset`

action: "start"
name: "Name of preset"

Activate preset defined by its name.

`quick_bookmark`

Locus Map 4.0+

Execute a certain quick bookmark defined by its name.

action: "start"
name: "Name of the bookmark"

`screen_lock`

action: "on"

Enable screen lock on the main screen.

action: "off"

Disable screen lock on the main screen.

or action: "toggle"

Toggle visibility of the screen lock on the main screen.

`screen_on_off`

action: "on"

Turn screen on.

or action: "off"

Turn screen off.

or action: "toggle"

Toggle screen on/off state.

`track_record`

action: "start"
name: "My profile" (optional)

Check if the optional name is defined. If so, try to set a recording profile with the same name. In case of fail, ends this task. As the second step, start recording if it's not currently running.

action: "stop"
name: "My profile" (optional)
auto_save: [true,false] (optional)

Stop track recording, optionally with automatic save of track (if missing, the value from the profile is used). If name is also defined, the recording will be stopped only in case, profile with the same name is currently active.

action: "pause"
name: "My profile" (optional)

Pause active track recording. If name is also defined, the recording will be paused only in case, profile with the same name is currently active.

action: "discard"
name: "My profile" (optional)
confirm: [true,false]

Discard the current active track recording. Parameter confirm specify, if user confirmation is needed. In case, the application is currently not visible, track recording is always discarded without confirmation. If name is also defined, the recording will be discarded only in case, profile with the same name is currently active.

action: "toggle"
allow_start: [true,false] (optional, Locus Map 3.38+)

Allow toggling recording state. If the recording is running, pause it, otherwise if is paused, un-pause it. When recording is not running at all, nothing happens if parameter allow_start is not set to true

action: "add_wpt"
name: "Point name" (optional)
description: "Point description" (optional)
auto_save: [true,false] (optional)
action_after: "[audio,photo,video]" (optional)

Add waypoint to the current active recording. Extra parameters are optional and may predefine point name, allow to save point automatically and also allows to take an audio/photo/video point directly. In the case auto_save is enabled, action_after is ignored.

`weather`

Locus Map 4.15+

action: "start"
lon: "Geographic longitude (-180°;180°)" (optional)
lat: "Geographic latitude (-90°;90°)" (optional)

Start the "Weather" screen with a certain pre-defined location. The current map screen center is used when coordinates are invalid (or not defined).

Samples

Samples below show parameters that need to be defined for custom intents or for example for Tasker application. All intents need to be sent as broadcasts (in Tasker defined as Broadcast Receiver).

The intent may have also defined a package parameter that say "which application should receive it". In case, you use Locus Map Free (Beta) and Locus Map Pro at once, or in case of target platform Android 8+, it is necessary to set this parameter too.

Locus Map Free (Beta): menion.android.locus

Locus Map Pro: menion.android.locus.pro