Standalone desktop application for editing Navit on-screen display (OSD) layouts and the internal HTML GUI menu without hand-editing XML. It loads navit.xml (with xi:include expansion), offers a graphical canvas, property editor, menu tree with preview, undo/redo, plugin descriptor integration (including JSON schema v2 with optional runtime dialog entries), C-source command discovery for validating navit.*() onclick handlers, and safe save/backup behaviour.

Repository: github.com/Supermagnum/navit-osd-editor

• Visual OSD layout on a resolution-aware canvas (pixels, percent, negative edge anchoring); zoom from the toolbar, View menu, Ctrl++ / Ctrl+= / Ctrl+-, Ctrl+scroll wheel, or Ctrl+0 for 100% scale.
• Typed palette of built-in Navit OSD types plus plugin-contributed types (JSON descriptors under configurable search paths).
• Properties panel and coordinate editing with undo.
• Delete selected OSD from Edit or Delete / Backspace while the canvas has focus (removes the <osd> from the config; undo/redo supported). Rubber-band multi-select removes several at once.

• Parse and write <gui type="internal"> CDATA; tree view with live preview.
• Hierarchy editing without hand-editing JSON or XML: add screens under a chosen parent, rename titles, move screens (context menu or drag-and-drop between screen rows), reorder items within a screen.
• Breadcrumb under the tree (click a segment to jump); Screen properties in the right dock (path, parent, title, runtime trigger when applicable).
• Add Screen (Edit menu) and Add Child Screen (context menu) use a dialog with a parent-path picker (static or runtime dialog screens; optional trigger command with completion after a command scan).
• Double-click buttons / form buttons to edit onclick in a small structured dialog (navigate to screen, call navit.*(), set navit.attr=value, or custom text), including Save without closing and Save and exit.

• Tools → Scan plugin source folder… walks a Navit or plugin source tree (typically *.c), extracts registered command names from common registration patterns, and builds an in-memory command inventory used for:
  • Onclick validation against the loaded menu model (status-bar hint when unknown navit.*() references are found; click for a summary).
  • Completers in add-screen and property UI where a trigger or command name is requested.
• Tools → Command coverage report… compares that inventory to descriptor dialogs (schema v2) and, optionally, onclick strings from Navit’s shipped default internal-GUI config (navit_shipped.xml — not the user-edited ~/.navit/navit.xml from File → Open). The file picker labels that step accordingly. A copy of upstream navit_shipped.xml lives at the repository root so the optional scan can use it without a full Navit checkout. Results can be exported as CSV. Use a source path (e.g. …/navit), not a CMake build output directory, or the C scan will usually find nothing.

• Load plugin descriptor JSON (OSD types, menu_screens, dialogs); merge into palette and menu model alongside XML.
• Tools → Descriptor editor… builds and exports a descriptor-compatible JSON (live preview, include/exclude screens and plugin OSD types, edit runtime triggers, Export with backup if the file already exists). Import validates the file and reapplies it to the editor: include checkboxes follow the file’s menu_screens / osd_types, entries missing from the current menu model or OSD layout are listed greyed with tooltips, dialogs are rebuilt from the file (with a (!) marker when no matching runtime screen exists), and the JSON preview updates immediately.
• Shipped example: navit_osd_editor/plugins/driver_break_descriptor.json (Driver Break palette and menu/dialog stubs).

• Tools → Source diff… — compare menu HTML embedded in C sources vs the menu model from the open config (see preferences for scan mode and plugin paths).
• Tools → Scale layout… — proportionally scale all OSD elements between two resolutions.

• Export: standalone navitOSD.xml, optional xi:include wiring.
• Timestamped backups before overwriting configuration files.
• CLI --version / --help without starting the GUI (no display required).

Requires Python ≥ 3.10, PyQt6 ≥ 6.5, lxml ≥ 5.0.

Use a virtual environment so dependencies are not installed into the system interpreter:

git clone https://github.com/Supermagnum/navit-osd-editor.git
cd navit-osd-editor
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Avoid sudo pip or pip install without a venv; that can break distro-managed Python packages.

Run:

python -m navit_osd_editor
# or
navit-osd-editor

Install build dependencies, then build from the package root (the directory that contains debian/):

sudo apt install build-essential debhelper dh-python pybuild-plugin-pyproject \
  python3-all python3-setuptools python3-pyqt6 python3-lxml
dpkg-buildpackage -us -uc -b

The last lines of the build name the generated .deb (under the parent of the source tree). Install that exact file, not an older .deb still sitting in .. from a previous build:

ls -1 ../*navit-osd-editor*_all.deb
sudo apt install "$(pwd)/../navit-osd-editor_0.3.0-2_all.deb"

apt treats a path as a local .deb only if it starts with ./ or / (or ends with .deb in some versions). A bare ../file.deb can be rejected as “unsupported”; use $(pwd)/../… or sudo dpkg -i ../navit-osd-editor_…_all.deb.

Use the filename that ls shows after you build. If that version is not listed, run dpkg-buildpackage again so debian/changelog matches.

Adjust the version to match debian/changelog and the filename dpkg-deb reported. If you run apt install on an older navit-osd-editor_*_all.deb after building a newer changelog entry, you reinstall the old package and will not see new features.

See debian/control for runtime dependencies. The Debian revision (after the hyphen) is independent of the Python wheel version printed during pybuild; both are driven by debian/changelog.

1. File → Open… — choose your navit.xml.
2. Drag OSD types from the left dock onto the canvas; edit attributes in Properties.
3. Use View or the toolbar to zoom; Delete / Backspace (canvas focused) or Edit → Delete selected OSD to remove widgets.
4. Edit the Internal menu in the bottom dock if your file has <gui type="internal"> (breadcrumb, hierarchy, add/move screens, onclick on buttons).
5. Optional: Tools → Scan plugin source folder… on your Navit/plugin source checkout so onclick validation and completers know registered commands.
6. File → Save writes the full configuration (and fragments as needed).

Tools (summary): source diff, command scan, command coverage report, scale layout, descriptor editor.

CLI:

navit-osd-editor --version
navit-osd-editor --help

• User manual — how to use the application (workflows, menus, tools, preferences).
• Other guides: installation, quickstart, OSD editor, menu editor, export / save, plugins.
• HTML: run make docs and open docs/_build/html/index.html.

Persistent settings use Qt (QSettings) under organisation navit-gps and application navit-osd-editor (typically under ~/.config/ on Linux).

• Descriptor directories — extra folder trees scanned recursively for *.json plugin descriptors (common build/cache directory names are skipped; see docs/user/plugins.md), in addition to the built-in navit_osd_editor/plugins/.
• Icon directory — optional search path for menu preview assets.

Configure via Edit → Preferences….

That is normal when the folder contains no valid descriptor JSON the editor can read.

1. Check that files exist — Descriptors are separate from Navit’s C plugin and from on-device gui_internal_* menus. A checkout of a plugin such as Driver Break may include no *.json for this editor at all.
2. Built-in copy — This package already ships Driver Break metadata as navit_osd_editor/plugins/driver_break_descriptor.json (palette + declarative menu stubs). You do not need to add a path for that unless you use a custom descriptor.
3. If you want the editor to load from another tree — Copy or symlink a valid descriptor (for example driver_break_descriptor.json from this repository) into that tree outside skipped directories such as build/, or add in Preferences the folder that actually contains the JSON files.

More detail: docs/user/plugins.md (including Navit runtime UI vs editor JSON).

See docs/developer/contributing.md for the virtual environment, pytest, ruff, mypy, and how to add golden fixtures.

The full catalog of automated tests, what each one checks, and a recent pass/fail snapshot is in docs/developer/test_suite.md.

Full documentation can be built with make docs (Sphinx).

GPL-3.0-or-later (see debian/copyright and pyproject.toml).