From Navit's Wiki
Revision as of 21:17, 13 September 2010 by Chr (talk | contribs) (idle_color attribute for odometer and stopwatch)
Jump to: navigation, search

The On Screen Display (OSD) provides status information and controls blended directly onto the map. These can be implemented using the <osd ... /> tag inside navit.xml. Example layouts can be found at OSD_Layouts.


An osd item can be enabled/disabled using the following:

   <osd enabled="yes" />
   <osd enabled="no"  />


An osd item can have configuration flags using the following:

   <osd osd_configuration="1" />

The osd will only be visible if the value of osd_configuration from the navit tag bitwise ANDed with the value of osd_configuration of the osd is not zero. So you can have up to 32 dynamically changeable osd layouts. Don't overuse this feature, since a non-visible osd will still consume memory and cpu cycles.


An osd item can contain a command as in those examples:

   <osd command="osd_configuration=2" />
   <osd command="zoom_in()" />

The command will be called when the item is clicked.

Commands can contain expressions or one of the commands listed under Commands.

Expressions may use the following operators:

  • ~ ! Bit-wise and logical NOT
  • * / % Multiplication, division, modulo
  • + - Addition, subtraction
  • == != <= >= < > Comparison (equal, not equal, less than or equal, greater than or equal, less than, greater than)
  • & | ^ Bit-wise AND, OR, XOR
  • && || Logical AND, OR
  • ? : Conditional (a?b:c will return b if a is true, else it will return c)
  • = Assignment
  • , Comma operator

Available attributes for use in expressions are listed under Attributes.


The position of an element is specified in x and y pixels from the top-left hand corner of the screen. Negative values will position the element with respect to the bottom-right hand corner of the screen.

For example:

   <osd enabled="yes" x="0"   y="0"   />
   <osd enabled="yes" x="10"  y="10"  />
   <osd enabled="yes" x="-10" y="-10" />
   <osd enabled="yes" x="10"  y="-10" />
  • The first osd item is placed in the top left hand corner of the screen.
  • The second osd item is placed 10 pixels right from the left-hand-side of the screen and 10 pixels down from the top of the screen (i.e. top left of the screen).
  • The third osd item is placed 10 pixels left from the right-hand-side of the screen and 10 pixels up from the bottom of the screen (i.e. bottom right of the screen).
  • The fourth osd item is placed 10 pixels right from the left-hand-side of the screen and 10 pixels up from the bottom of the screen (i.e. bottom left of the screen).


The sizes of each item can be explicitly set in pixels using the 'w[idth]' and 'h[eight]' attributes.

For example:

   <osd enabled="yes" x="0" y="0" w="100" h="50" />

This will create an item of width 100 and height 50 pixels from the top-left corner of the item. The top-left corner of the item is also the point which is used when positioning the item using the 'x' and 'y' attributes.

Example navit.xml contents, based on osd items mentioned so far:

   <osd type="text" osd_configuration="1" w="100" h="50" x="-100" y="0" label="${vehicle.position_speed[named]}" font_size="350" command="osd_configuration=2"/>
   <osd type="text" osd_configuration="2" w="400" h="100" x="-400" y="0" label="${vehicle.position_speed[named]}" font_size="1200" command="osd_configuration=1"/>

The first osd is the small one, if you click on it, the second one (large) will get visible. If you click on the large one, you will get the small one back.


Certain osd items may be aligned. For example, text may be aligned centrally within an item. Alignment is specified using:

   <osd enabled="yes" x="0" y="0" w="100" h="50" align="ALIGN_NUMBER"/>

Where the alignment number can be any of the following:

  • "1": Align to the top
  • "2": Align to the bottom
  • "0" or "3": Align to the center (vertical)
  • "4": Align to the left
  • "8": Align to the right
  • "0" or "12": Align to the center (horizontal)

To get a combination of alignment you have to sum vertical and horizontal alignment, so align="5" would give top left alignment.


Background Color

The osd item's background color can be changed using the 'background_color' attribute. For example:

   <osd enabled="yes" x="0" y="0" w="100" h="50" align="0" background_color="#000000c8" />

The color is specified in standard 6-figure hexadecimal, with the last two figures specifying amount of transparency/opacity (00 = fully transparent, FF = fully opaque). The above color is a translucent black.

As can be seen, the previous attributes can be combined to create a filled box of particular dimensions and in a particular position. However, a box is useless without content, which is where the 'type' attribute comes in.

Text Color

The color of osd text items color can be changed using the 'text_color' attribute. For example:

   <osd enabled="yes" type="text" x="90"  y="0" w="110" h="45" align="4" font_size="400"  text_color="#ff0000"  label="${vehicle.position_speed}" />

The color is specified in standard 6-figure hexadecimal, red in the example above. (to be tested: transparency/opacity for text?)


An osd type is implemented using:

   <osd enabled="yes" x="10" y="10" type="OSD_TYPE" />

Current OSD types (from navit/osd/core/osd_core.c):

For example:

   <osd enabled="yes" x="10" y="10" type="compass" />
   <osd enabled="yes" x="10" y="10" type="gps_status" />
   <osd enabled="yes" x="10" y="10" type="text" />
   <osd enabled="yes" x="10" y="10" type="scale" />

You can determine the supported xml options for each OSD type by reading navit/osd/core/osd_core.c, searching for "attr_xxx" inside the osd_xxx_new() functions. Most types have at least an "x" and "y" option that determine the location of their OSD.


The button type creates a placeholder in which a specified image is clickable; this is usually accompanied by a command.

Example navit.xml contents:

   <osd enabled="yes" type="button" x="48"  y="48"  command="gui.fullscreen=!gui.fullscreen" src="toggle_fullscreen.xpm" />
   <osd enabled="yes" type="button" x="-96" y="48"  command="gui.menu()"                     src="menu.xpm" />
   <osd enabled="yes" type="button" x="-96" y="-96" command="zoom_in()"                      src="zoom_in.xpm" />
   <osd enabled="yes" type="button" x="48"  y="-96" command="zoom_out()"                     src="zoom_out.xpm" />

The button type is useful when using gui_internal, as it could provide zoom in/out functionality. gui_internal does not draw any controls onto the map view, so unless you have a scroll wheel the zoom in/out functionality will be missing.


This creates a compass containing a white arrow, pointing north (whenever a GPS signal is available). In routing mode, the compass shows a second green arrow, indicating the direction to the destination, and the direct distance to the destination. Example:

   <osd enabled="yes" type="compass" font_size="150" x="-68" y="-58" w="36" h="45"/>


This shows a bar indicating the GPS signal strength. Example:

   <osd enabled="yes" type="gps_status" x="-32" y="-58"/>


This osd item displays an image of the next turn which the vehicle will have to undertake. Nothing is displayed if routing is not on (i.e when just using navit for GPS instead of sat-nav).

An example use is:

   <osd enabled="yes" type="navigation_next_turn" x="0" y="-75" />


Odometer OSD can be used to measure distance and average speed of certain paths during travelling. Starting, pausing and restarting of measurement is supported. Single click toggles enabled state, double click resets distance and average speed calculations and puts odometer into stopped state. The type attribute of this osd should be set to "odometer" in the osd tag of navit.xml . The label attribute can be used to control the displayed quantities.The value of this attribute is used as a format string. In this format string ${avg_spd} is replaced by the value of average speed and the corresponding unit. ${distance} is replaced by the measured distance value and the corresponding unit. The idle_color attribute defines the text color in idle state. The idle_color attribute defaults to orange and can be helpful in combination with the standard attributes text_color and background_color. You can see an example xml tag for navit.xml to configure odometer OSD below:

   <osd enabled="yes" type="odometer" w="350" h="40"  x="30" y="300"   font_size="450" label="Dst:${distance} ; Spd:${avg_spd}" />


The 'scale' type overlays a simple ruler and scale on the current map. This updates as you zoom in or out. For example:

   <osd enabled="yes" x="0" y="-84" w="240" h="26" font_size="150" type="scale"/>n


This OSD displays a stopwatch which can be useful for measuring time needed to take certain paths. Pausing, restarting and resetting counter is supported. Single click toggles counting, double click resets the counter. The osd accepts the standard osd attributes. The idle_color attribute defines the text color in idle state. The idle_color attribute defaults to orange and can be helpful in combination with the standard attributes text_color and background_color. The following example shows how to enable stopwatch osd:

   <osd enabled="yes" type="stopwatch" x="100" y="200" font_size="400" w="100" h="30" />


The text type is useful for displaying static text, current GPS data, routing information or status information on the map view (viewable in the status bar in GTK mode). This is implemented in the following manner:

   <osd enabled="yes" type="text" label="${GPS_OR_ROUTE_DATA}" x="-200" y="0" />

The label attribute can hold any combination of static text and placeholders, which will be replaced with data and updated in real time when displaying.

When using the text type, it is useful to set the width and height of each item, in addition to aligning the text using the 'align' attribute.

Placeholders are specified as ${section.attribute}. Attributes which can be used in labels include:

Attribute Value
navigation Section containing routing information, available only when routing
navigation.item Information related to the entire route
navigation.item.destination_length[named] Remaining distance to destination. Use navigation.item.destination_length[value] to get the bare value (without units) or navigation.item.destination_length[unit] to get just the unit. Useful for displaying the value and the unit in two rows, or in different font sizes.
navigation.item.destination_time[arrival] Estimated time of arrival
navigation.item.destination_time[remaining] Estimated remaining time
navigation.item.street_name Name of the road which the vehicle is currently on (e.g. Via Gallarate)
navigation.item.street_name_systematic Number/reference of the road which the vehicle is currently on, if available (e.g. SS33)
navigation.item[1] Information related to the next navigation item (from the next maneuver to the one following it)
navigation.item[1].length[named] Distance to next maneuver. Use navigation.item[1].length[value] and navigation.item[1].length[unit] in the same manner as for navigation.item.destination_length.
navigation.item[1].street_name Name of the road following the next maneuver (cf. navigation.item.street_name)
navigation.item[1].street_name_systematic Name of the road following the next maneuver (cf. navigation.item.street_name_systematic)
tracking Section containing information on current track, available whenever valid GPS information and corresponding map data is available. The difference to navigation is that tracking data is also available when not routing. Ensure that tracking="1" is set in the <navit> tag to use these attributes.
tracking.item Information related to the road the vehicle is currently traveling along
tracking.item.route_speed Speed limit on the road which the vehicle is currently on
tracking.item.street_name Name of the road which the vehicle is currently on (cf. navigation.item.street_name)
tracking.item.street_name_systematic Number/reference of the road which the vehicle is currently on (cf. navigation.item.street_name_systematic)
vehicle Section containing GPS information, available whenever valid GPS information is available
vehicle.position_coord_geo Current position. Use vehicle.position_coord_geo[format] to control the output format of the coordinates (works reliably from r3490 onwards). Valid format values are:
  • pos_deg: Latitute and longitude in decimal degrees
  • pos_degmin: Latitude and longitude in degrees, minutes and fractions of minutes (similar to NMEA style)
  • pos_degminsec: Latitude and longitude in degrees, minutes and seconds
  • lat_deg, lat_degmin, lat_degminsec: Only the latitude in one of the formats described above
  • lng_deg, lng_degmin, lng_degminsec: Only the longitude in one of the formats described above

If omitted, pos_degminsec will be assumed.

vehicle.position_direction Current orientation (direction of travel) in degrees
vehicle.position_height Current altitude in m
vehicle.position_qual Number of satellites which your GPS receiver can see. However, your receiver may not be using all of them for positioning due to low signal etc...
vehicle.position_sats_used Number of satellites used
vehicle.position_speed Current speed in km/h
vehicle.position_time_iso8601 Current GPS time (roughly the same as UTC, with a few seconds of difference)
vehicle.position_time_iso8601[string] Current GPS time with formatting string: { iso8601 | [ local; | offset ; ] format }
  • local; retrieves the timezone setting of the system
  • offset is a literal offset such as +02:00 (sign, hours, colon, minutes)
  • format is a time format string which follows the syntax for the C strftime function


  • vehicle.position_time_iso8601[iso8601] --> Current GPS time (default as without qualifier)
  • vehicle.position_time_iso8601[local;%Y-%m-%d %X] --> Current GPS date and time at local timezone of the system (tested on WinCE), %X gives time using the system's time format
  • vehicle.position_time_iso8601[iso8601] --> Current GPS time (default as without qualifier)
  • vehicle.position_time_iso8601[+01:00;%X] --> time of the UTC+01:00 time zone


   <!-- ALWAYS AVAILABLE (if GPS connected) -->
   <!-- Current Speed (integer in km/h) -->
   <osd enabled="yes" type="text" label="${vehicle.position_speed}" x="-200" y="0" />
   <!-- Current Coordinate Position -->
   <osd enabled="yes" type="text" label="${vehicle.position_coord_geo}" x="-200" y="0" />
   <!-- Current Altitude (in metres)-->
   <osd enabled="yes" type="text" label="${vehicle.position_height}m" x="-60" y="-80" />
   <!-- Current Direction of Travel (integer from<!-- 0-360) -->
   <osd enabled="yes" type="text" label="${vehicle.position_direction}" x="-60" y="-80" />
   <!-- Number of Satellites Used / Number of Satellites Available -->
   <osd enabled="yes" type="text" label="${vehicle.position_sats_used}/${vehicle.position_qual}" x="-50"
  y="40" />
   <!-- ONLY AVAILABLE WHEN ROUTING (i.e in Sat-Nav mode) -->
   <!-- Currently on ROADNAME -->
   <osd enabled="yes" type="text" label="Currently on ${navigation.item.street_name_systematic}" x="0" y="0" />
   <!-- Distance to next turn (in metres) -->
   <osd enabled="yes" type="text" label="${navigation.item[1].length[named]}" x="0" y="-105" />
   <!-- Next turn is onto ROADNAME -->
   <osd enabled="yes" type="text" label="Turn onto ${navigation.item[1].street_name_systematic}" x="0" y="-105" />
   <!-- Estimated time of arrival (HH:mm) -->
   <osd enabled="yes" type="text" label="ETA ${navigation.item.destination_time[arrival]}" x="-150" y="-30" />
   <!-- Entire route distance remaining (in km) -->
   <osd enabled="yes" type="text" label="DR ${navigation.item.destination_length[named]}" x="-85" y="-60" />
   <!-- Time remaining until destination is reached (HH:mm) -->
   <osd enabled="yes" type="text" label="TR ${navigation.item.destination_time[remaining]}" x="-85" y="-90" />

Font Size

The size of font used in an osd item can be set using the 'font_size' attribute, for example:

   <osd enabled="yes" type="text" label="${vehicle.position_coord_geo}" x="0" y="0" w="360" font_size="300" />

This creates an osd item displaying the current position coordinates with a font size of 300. Default font size is currently 200.

For text color, see the section Color on this wiki page.


An example implementation is shown below.

Error creating thumbnail: Unable to save thumbnail to destination
  • Top left is type="compass"
  • Bottom left is type="navigation_next_turn"
  • Top right is type="text" with label="${navigation.item.destination_time[arrival]}" and label="${navigation.item.destination_length[named]}"

More osd layouts can be found at OSD_Layouts.

Icon source setting for OSD

The Nokia N8x0 platform (and possibly others) is not very supportive of .svg image files. Navit on the other hand relies heavily on svg. The result is often missing images from your display. In the examples above you may need to replace the .svg with .png. The solution for Next Turn is to use the following config addition:

<osd enabled="yes" type="navigation_next_turn" x="325" y="-135" w="150" h="100" align="15"
   background_color="#a60c0f00" icon_src="$NAVIT_SHAREDIR/xpm/%s_wh_48_48.png" />

Note the icon_src parameter specifies the template for the image file names. This should work for all OSD items.

If you don't have the .png files already, you can create them this way:

$ for f in *wh.svg; do convert -background none -resize 48x48 $f `basename $f .svg`_48_48.png; done

Please note that the OSD layer is still under development, and content on this page may be out-of-date.


Navit commands

The following commands (from navit/navit.c) can be used in the command attribute of OSD items by specifying the function name as shown below. If you want to call them from elsewhere (e.g. from internal GUI menu items), prefix them with navit. (e.g. navit.zoom_in()):

Command Meaning
announcer_toggle() FIXME: description to be completed
fmt_coordinates() FIXME: description to be completed
say(text) Use to produce speech output; sends text to the text-to-speech engine.
set_center_cursor() FIXME: description to be completed
set_destination() FIXME: description to be completed
zoom_in() Zoom into the map (dividing the current zoom level by 2).
zoom_out() Zoom out of the map (multiplying the current zoom level by 2).
zoom_to_route() Zoom the entire route into view

GUI commands

GUI commands can be used within from GUI menu items by specifying the function name as shown below. If you want to call them from elsewhere (e.g. from OSD items), prefix them with gui. (e.g. gui.menu()) The following are available (from navit/gui/internal/gui_internal.c):

Command Meaning
abort_navigation() Cancels navigation: The route is cleared and Navit switches to tracking mode.
about() Displays the About screen.
back() FIXME: description to be completed.
back_to_map() Leaves the menu and returns to map view.
bookmarks() Shows bookmarks.
get_data() FIXME: description to be completed
locale() Shows locale information.
log FIXME: description to be completed
menu() Brings up the menu (used as gui.menu() in OSD items in order to have a dedicated menu button).
position(position, text, flags) Presents possible operations on a position (set as current location, set as destination etc.). position is a coordinate-type attribute (e.g. position_coord_geo).
quit() Closes Navit.
route_description() Shows a turn-by-turn description of the active route when in navigation mode.
route_height_profile() Shows a height profile of the active route when in navigation mode.
setting_layout() Presents a selection of available screen layouts.
setting_maps() Presents a dialog to switch between available mapsets.
setting_rules() Presents a dialog for setting various internal options.
setting_vehicle() Presents a dialog for selecting the active vehicle.
town() Presents a dialog for selecting an address, starting with a town.
write(attribute) Writes an attribute. Used by the GUI menu in conjunction with <script> to display the content of an attribute in a menu item.


Expressions in the command attribute of an OSD item or in the cond and onclick attributes of OSD menu items can use the attributes listed below.

GUI Attributes

These have to be prefixed with gui. when used in an OSD item. In menu items they can be used directly.

Attribute Meaning
flags GUI flags. FIXME: complete description
  • 2 (if set, the menu should offer Show Map)
fullscreen Nonzero if full-screen mode is active, zero otherwise. Use fullscreen=!fullscreen to toggle between window and fullscreen mode.

Other attributes

These can be used as shown below in OSD items, not sure about menu items.

Attribute Meaning
navit.pitch Viewing angle, same semantics as in XML file. 0 means 2D view. (Seen in menu item, not sure about usage in OSD item.)
navit.route.route_status Flags for the route status. 48 seems to indicate that a route is active (or possibly being calculated). (Seen in menu item, not sure about usage in OSD item.)

See also route.h (enum route_status):

Const Value
route_status_no_destination 0
route_status_destination_set 1
route_status_not_found 1/2
route_status_building_path 1/4
route_status_building_graph 1/4/8
route_status_path_done_new 1/16
route_status_path_done_incremental 1/32
osd Not yet implemented. Use e.g. osd[type=="xxx"].active=0 to disable or enable certain OSD items.
osd_configuration Set the osd_configuration flags for navit. With the command osd_configuration=2 all osds where the condition (osd_configuration & 2) != 0 is true will get visible, all others non-visible.
speech.active Use speech.active!=speech.active to enable or disable spoken directions.