From Navit's Wiki
Revision as of 09:04, 20 September 2009 by Udo (talk | contribs) (command)
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 be numbered using e.g. the following:

   <osd osd_configuration="1" />
   <osd osd_configuration="2" />


An osd item can contain a command like in the following:

   <osd command="osd_configuration=2 />

Example navit.xml contents:

   <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.


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.


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 (FF = fully transparent, 99 = 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.


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" />

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.


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" />


The button type creates a placeholder in which a specified image is clickable and toggles one of the following options:

  • gui.fullscreen()
  • gui.menu()
  • gui.get_data()
  • zoom_in()
  • zoom_out()
  • speech.active

Example navit.xml contents:

   <osd enabled="yes" type="button" x="48"  y="48"  command="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.


The text type is useful for displaying current GPS data 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" />

Some options include:

   <!-- 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" />

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.

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.


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 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.