Custom buttons layouts

Introduction

Since v0.4.0, OSMTracker can use custom buttons layouts in addition to the default one. This allows you to have the best button layout that suits your activities, and remove unused buttons. Also, since v0.7 was added a new functionality to download custom layouts from a GitHub repository, in order to facilitate to all users the implementation of their custom layouts in their activities.

Downloading and installing custom layouts

The new functionality of OSMTracker, that was added recently with the v0.7, allows the download and installation of custom layouts from the application. Currently, this layouts are stored in osmtracker-android-layouts repository (which is taken as the default repository).

Note: To learn more about how to add your custom layout in the default repository (or create your own custom repository) consult the wiki in the osmtracker-android-layouts repo.

To download and install a new layout, you need to go to your application settings and then scrolls until Buttons presets, press it. This will show a new screen with the default layout and the custom (downloaded) layouts that you already have in the phone.

Buttons presets screen

Once you are there, in the upper right corner you can see a green button (+), this button will display the Available layouts screen. In this screen will be show all the custom layouts that are available to download in the current repository.

Available layouts Screen

Now, you just need to press in the custom layout that you want to download and a description will be shown, read the description and then press the download buttonto proceed. Return to the Buttons presets screen and the layout will be show list in the DOWNLOADED LAYOUTS section.

To use it, only select it and that all. :)

Layout files

Each layout is defined in a XML file that will be in a /layouts directory inside the main OSMTracker storage dir. Each layout must be defined in XML, in UTF-8, and the filename should end with .xml.

Note: You have to manually create the layouts directory on your SD card (it isn't created by OSMTracker) then drop your XML files in it, if you wanna make the process manually, the new functionality makes it automatically.

Ex (Storage dir. defined in settings is /osmtracker):

/sdcard/osmtracker/layouts/cycling.xml
/sdcard/osmtracker/layouts/trek.xml
...

Each file matching these criteria will be listed as a potential layout in the settings screen. If the layout is invalid (incorrect XML syntax) the application will display a black screen instead of buttons. You can then go back to Settings -> Buttons presets, and choose the default layout to have the buttons displayed again.

Defining a layout: XML syntax

Each XML file must use the following syntax:

<layouts>

 <layout name="root">
  <row>
   <button type="..." label="..." (icon="...") (targetlayout="...") />
   ...
  </row>
 </layout>

 <layout name="...">
  ...
 </layout>

</layouts>

Important:

Each layout file must start with the <layouts> root tag, and define one or more <layout>. At least one layout with the name root must be defined.
Your file must not include an XML header <?xml version="1.0" encoding="utf-8"?>. If you do so, please ensure that your file doesn't contains a BOM. The Android XML parser that cannot parse XML files with a header and a BOM (Or I didn't find how to do it !)

`<layout>`

A <layout> corresponds to a page of buttons. The first layout displayed is the layout with name="root", so <layout name="root"> is mandatory.

Each layout can be subdivided in <row> of buttons:

<layout name="amenity">
 <row>
  <button ... />  
  <button ... />
 </row>
 <row>
  <button ... />
  ...
 </row>
</layout>

`<button>`

This tag represents a button, and uses the following syntax: <button type="..." label="..." (icon="...") (iconpos="...") (targetlayout="...") />

type is mandatory, and can be:
- voicerec : For a voice recording button.
- picture : For a picture button (Launches camera application).
- textnote : For the text note button.
- tag : For a classic tag button.
- page : To allow navigation between button pages.
  - A page button must define a targetlayout attribute, pointing to the layout to display. The value of targetlayout must match the name of another layout.
label is mandatory for tag and page buttons. It will be used as a label for the button, and as the waypoint tag name for tag buttons. For special buttons like voicerec, picture or textnote the label is automatically retrieved from the application string resources and cannot be changed.
icon is optional, and can be used to specify an icon for the button.
- The icon must be a relative filename with extension (Ex: airport.png).
- Icons should be in the same directory as the layout file, and in PNG format.
iconpos (Since v0.5.2) is optional, and can be used to specify where the icon should be drawn on the button. Possible values are auto,top,right,bottom or left.
- This attribute helps to prevent text to be cut off with some layout/orientation combination. Please see issue #42 for details.
targetlayout is mandatory for a page button. Its value must match an existing layout name.

Some examples:

<button type="voicerec" label="Record a voice note" icon="mic.png" />
<button type="tag" label="Airport" icon="airport.png" />
<button type="tag" label="Power line" />
<button type="page" label="Amenity..." targetlayout="amenity" />

Complete commented example

<layouts>

 <!-- Main layout, the first to be displayed -->
 <layout name="root">
  <row>
   <!-- 3 special action buttons -->
   <button type="voicerec" label="Voice record" icon="voice.png" />
   <button type="picture" label="Take picture" icon="camera.png" />
   <button type="textnote" label="Text note" icon="text.png" />
  </row>
  <row>
   <!-- "link" to 2 sub pages -->
   <button type="page" label="Amenity" targetlayout="amenity" />
   <button type="page" label="Restriction" icon="restriction.png" targetlayout="restriction" />
  </row>
  <row>
   <!-- Standard tag buttons -->
   <button type="tag" label="Airport" icon="airport.png" />
   <button type="tag" label="Marina" />
  </row>
 </layout>

 <!-- Amenity layout, will be displayed when clicking on "Amenity" previous defined button -->
 <layout name="amenity">
  <row>
   <!-- Two standard tag buttons -->
   <button type="tag" label="Bench" icon="button_amenity_bench.png" />
   <button type="tag" label="Water" icon="button_amenity_water.png" />
   <!-- A 2nd level page button -->
   <button type="page" label="More amenities..." targetlayout="amenity_more" />
   <!-- And a special action button -->
   <button type="textnote" label="Text note" icon="text.png" />
  </row>
 </layout>

 <!-- Restriction layout, will be displayed when clicking on "Restriction" previous defined button -->
 <layout name="restriction">
  <row>...</row>
 </layout>

 <!-- 2nd level Amenity page. Will be displayed when clicking on the "More amenities..." button on the Amenity page -->
 <layout name="amenity_more">
  <row>...</row>
 </layout>

</layouts>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly