Difference between revisions of "Command interface"

From Navit's Wiki
Jump to: navigation, search
(Attributes)
(Commands: formerdests)
Line 197: Line 197:
 
|-
 
|-
 
|'''<tt>bookmarks()</tt>''' || Shows bookmarks.
 
|'''<tt>bookmarks()</tt>''' || Shows bookmarks.
 +
|-
 +
|'''<tt>formerdests()</tt>''' || Shows list of former destinations.
 
|-
 
|-
 
|'''<tt>get_data()</tt>''' || FIXME: description to be completed
 
|'''<tt>get_data()</tt>''' || FIXME: description to be completed

Revision as of 17:41, 25 December 2011

Navit has a rich interface through which it can be controlled by UI components. This page attempts to document it, but it is still under construction and far from complete.

Contents

Overview

Navit provides an object-oriented command interface to process commands from the GUI. Objects are arranged in a hierarchy, the topmost object being config. All other objects have exactly one parent object; the permissible parent object types depend on the object type. For instance, a navit object cannot have a parent of any type other than config while a log object can have either a vehicle or a navit object as its parent.

Objects have methods (called commands in Navit) and properties (attributes). The available commands are fixed for each object type; some objects have no commands at all. The available attributes are less strictly defined and may change at run time; in fact, virtually any object type can take any attribute. The attributes listed for each object type are those that are automatically created or evaluated by Navit.

Objects, their commands and attributes can be used:

  • In the navit.xml file: with some exceptions, an object gets created for each element in navit.xml, and the attributes of each element become attributes of the corresponding object. The hierarchy is determined by the XML structure.
  • In commands of OSD items: unqualified identifiers are assumed to be from the navit namespace. Note that the label attribute of text items uses a different syntax.
  • In commands or conditions of menu items in the internal GUI: the default namespace is gui.
  • In the QML GUI

Command attributes can contain any number of command calls or arithmetic operations, separated by semicolons. Condition attributes contain a Boolean expression which evaluates to true (nonzero) or false (zero). Both Boolean expressions and arithmetic operations can use properties of any object.

For example:

<img cond='navit.pitch!=0' src='gui_map' onclick='navit.pitch=0;redraw_map();back_to_map()'><text>2D</text></img>

This is an example of an internal GUI menu item. The cond attribute specifies that it is only visible when navit.pitch is nonzero (i.e. 3D map view is active). The onclick attribute is a series if command calls: first, navit.pitch is set to zero, then redraw_map() is called to refresh the map view, and finally back_to_map() exits from the menu and returns to the map.

The following operators are available:

  • ~ ! 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

Objects

The object hierarchy is defined in navit/xmlconfig.c

announce

Parent Objects

Child Objects

Attributes

Commands

announcement

Parent Objects

Child Objects

Attributes

Commands

arrows

Parent Objects

Child Objects

Attributes

Commands

circle

Parent Objects

Child Objects

Attributes

Commands

config

Parent Objects

None.

Child Objects

Attributes

Commands

coord

Parent Objects

Child Objects

Attributes

Commands

cursor

Parent Objects

Child Objects

Attributes

Commands

debug

Parent Objects

Child Objects

Attributes

Commands

graphics

Parent Objects

Child Objects

Attributes

Commands

gui

Defined in navit/gui/internal/gui_internal.c

Parent Objects

Child Objects

Attributes

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.
button Nonzero while the menu is rendered first time after it was called by clicking on the map, zero otherwise. Use <img cond='button' src='gui_map'><script>position(click_coord_geo,_("Map Point"),8|16|32|64|256);pois(click_coord_geo)</script></img> to automatically jump to clicked point information and list of POIs around it. Works for <gui type=internal> only.

Commands

Commands available in the internal GUI:

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.
formerdests() Shows list of former destinations.
get_data() FIXME: description to be completed
locale() Shows locale information.
log() FIXME: seems to bring up a dialog allowing the user to enter a message which will get written to the debug log; useful to mark a position in the log
menu() Brings up the menu (used as gui.menu() in OSD items in order to have a dedicated menu button).
pois(position,filter,isaddressfilter) Displays POIs around given point, possibly filtering them by text string as it would be entered in POI filtering dialog. Second and third arguments may be omitted.
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.
redraw_map() FIXME: found in an internal GUI menu item but navit/gui/internal/gui_internal.c does not declare this command (as of at least r3520) - has this command been removed?
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.

icon

Parent Objects

Child Objects

Attributes

Commands

image

Parent Objects

Child Objects

Attributes

Commands

itemgra

Parent Objects

Child Objects

Attributes

Commands

layer

Parent Objects

Child Objects

Attributes

Commands

layout

Parent Objects

Child Objects

Attributes

Commands

log

Parent Objects

Child Objects

Attributes

Commands

map

Parent Objects

Child Objects

Attributes

Commands

mapset

Parent Objects

Child Objects

Attributes

Commands

navigation

Parent Objects

Child Objects

Attributes

Commands

navit

Defined in navit/navit.c

Parent Objects

Child Objects

Attributes

Attribute Meaning
pitch Viewing angle, same semantics as in XML file. 0 means 2D view.

Commands

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

osd

Parent Objects

Child Objects

Attributes

Commands

plugin

Parent Objects

Child Objects

Attributes

Commands

plugins

Parent Objects

Child Objects

Attributes

Commands

polygon

Parent Objects

Child Objects

Attributes

Commands

polyline

Parent Objects

Child Objects

Attributes

Commands

roadprofile

Parent Objects

Child Objects

Attributes

Commands

route

Parent Objects

Child Objects

Attributes

Attribute Meaning
route_status Flags for the route status:
  • 4: route is being calculated
  • 48: seems to indicate that a route is active

Commands

speech

Parent Objects

Child Objects

Attributes

Attribute Meaning
active If nonzero, spoken directions are enabled, else they are disabled.

Commands

text

Parent Objects

Child Objects

Attributes

Commands

tracking

Parent Objects

Child Objects

Attributes

Commands

vehicle

Parent Objects

Child Objects

Attributes

Attribute Meaning
logging Under development (#631): If nonzero, the vehicle will log its position if one or more log files are specified for it. If zero, logging is disabled. The initial value is taken from the XML file; this determines if the vehicle will start logging immediately. Set it to a nonzero value to start logging manually, setting it to zero stops all logging for that vehicle.

Commands

Command Meaning
log_waypt(description) Under development (see #631): Logs a waypoint to a track log of type gpxwpt.

vehicleprofile

Parent Objects

Child Objects

Attributes

Commands