pyNavis panel

Settings

One window over the parts of pyNavis you are meant to change: theme, ribbon hints, where extensions load from, and the engine paths.

What it does#

pyNavis keeps its configuration in one JSON file, %APPDATA%\pyNavis\config.json. Most of that file is maintained by pyNavis itself. Settings is the window over the handful of keys a person is meant to change, so nobody has to open the file in a text editor to switch the theme or add an extension folder.

How to use it#

1. Click Settings. The window opens with the current values.
2. Appearance. Pick a theme, or leave it following Navisworks. Two checkboxes control the hints on button captions: a dot after a tool that has a keyboard shortcut, on by default, and an arrow after a tool that has a Shift+Click action, off by default. The box beside each checkbox is the glyph it draws. Leave a box empty and the default glyph is used; the checkbox is the only off switch.
3. Shortcuts. One checkbox: whether a shortcut may be bound without Ctrl or Alt in it. Off, every chord must carry one of them, which keeps a stray letter from firing a tool while you type a viewpoint name.
4. Where extensions are loaded from. Add or remove the folders pyNavis scans for *.extension folders. Two locations are always scanned whether listed or not: %APPDATA%\pyNavis\extensions, where the installer puts the shipped extension, and %PROGRAMDATA%\pyNavis\extensions when it exists and only administrators can write to it.
5. Engines. The pynavislib folder and a CPython executable. Leave both empty unless you know why you are changing them; CPython is only used by bundles that declare engine: cpython.
6. AI assistant (beta). The provider, endpoint, model and API key the Ask AI panel uses, with a Test button. The key is stored encrypted in secrets.json, not in config.json. The AI Settings button on the AI panel opens the window scrolled to this section.
7. Updates. Where this pyNavis stands against the latest release, with Check now, the release page, and Skip this version, which takes effect at once. Two switches: check once a day (one anonymous request to GitHub; nothing about you is sent), and download a newer release and install it when Navisworks closes. A download only runs when its SHA-256 matches the release's. Both are on by default.
8. Click Save. If an engine path changed, pyNavis says Navisworks needs a restart. Otherwise it offers to reload the ribbon there and then.

Limitations#

• Which tool holds which shortcut is not edited here. That is the Shortcuts editor's job.
• Engine paths take effect only after Navisworks restarts. A Reload cannot swap a Python engine under a running ribbon.
• The window edits only the keys listed above. Shortcut overrides, dock panel slot assignments and window layouts stay in the file untouched, because the tools that own them would otherwise fight the window for the same keys.

Other uses#

• Point pyNavis at a shared network folder of extensions so a whole team gets the same tools, then keep your own experiments in a second, local folder.
• Turn the Shift+Click arrow on while learning the tab, then off again once you know which tools carry settings.

Good to know#

An update replaces pyNavis.extension whole, and keeps everything else: your config.json, your other extensions, the AI's tools. Anything you had added to or edited in pyNavis.extension is copied to %APPDATA%\pyNavis\backups first, and the buttons and panels you had added move to My pyNavis.extension, where they stay on the pyNavis tab: tabs and panels with the same names join on the ribbon. Keep your own tools there from the start.

Cancel says nothing and changes nothing. Every key the window writes is described in the authoring guide's config.json reference, which is where to look if you would rather edit the file directly.

The last line of the window says which pyNavis this is, for which Navisworks, and where its runtime lives, with a Copy button beside it. Paste that line into any bug report. The same line is the first thing pyNavis writes to %APPDATA%\pyNavis\logs\pyNavis.log at every start, and pynavis.script.get_host().Version returns the version to a script.

Source#

The tool's own files, word for word as shipped in pyNavis.panel/Settings.pushbutton. Every pyNavis tool is an ordinary bundle: copy these into your own extension and change what you like.

# -*- coding: utf-8 -*-
"""Edits everything in config.json a person is meant to change, in a window.

The Shortcuts editor still owns which tool has which chord, and the pane registry
still owns which panel holds which slot, so neither is edited here. This covers
the rest: theme, the two ribbon hints, whether a bare key may be a shortcut,
where extensions load from, and the two engine paths.

Most of it shows after a Reload, which this offers. The engine paths cannot be
picked up by a Reload at all, so that case says restart instead of pretending.
"""

import clr

clr.AddReference('PyNavis.Runtime')
from PyNavis.Runtime.Forms import SettingsDialog

from pynavis import forms, script, toast


def run():
    try:
        outcome = SettingsDialog.ShowAndSave()
    except Exception as error:
        script.get_logger().error('settings not saved: %s' % error)
        toast.error('Could not save your settings', str(error))
        return

    if outcome == SettingsDialog.Outcome.Cancelled:
        return                                  # cancelled: say nothing

    if outcome == SettingsDialog.Outcome.NeedsRestart:
        toast.warning('Settings saved',
                      'The engine paths changed, so Navisworks needs restarting')
        return

    if forms.confirm('Reload pyNavis now so the changes show?', 'Settings saved'):
        script.reload_pynavis()
        # The ribbon rebuilding behind the dialog is easy to miss, and a reload
        # that says nothing reads as a reload that did not happen.
        toast.success('Settings saved', 'pyNavis reloaded, so they show now')
    else:
        toast.success('Settings saved', 'They show after the next Reload')


if '__commandpath__' in globals():
    run()

title: Settings
tooltip: Theme, ribbon hints, where extensions load from, and the engine paths. Everything pyNavis keeps in config.json that you are meant to change.