Indices and tables


Note

The README below is imported from the repository. File links might not work*

Introduction

This project aims to make it easier for developers, who write plugins/tools etc. for Nuke, to create persistent preferences and show them in the Nuke preferences Window.

Thanks to Wouter Gilsing for his contributions to the Nuke community which inspired and helped this project.

Below is a quick guide on how to get started.
For a more advanced example of custom preferences look at the subPreferencesManager.py file.
For more in-depth info take a look at the documentation or simply call help(Preferences.<method_name>) on the Preferences class’ methods.

Installation

Copy *preferencesManager.py* to a location in your sys.path or nuke.pluginPath() (for example ``~.nuke/``) or just next to your current project file. Done.

Basic setup

The best way to manage preferences for Your app is to subclass the Preferences class from the *preferencesManager.py* module:

import preferencesManager
class MyPrefs(preferencesManager.Preferences):
    def __init__(self):
        creatorName = "You!"
        appName = "Awesome Tool"
        super(MyPrefs, self).__init__(creatorName, appName)
PREFS = MyPrefs()
PREFS.setup()

You should import your custom preferences class and run the setup when Nuke starts so all knob values are set up correctly. For example in the menu.py write:

import myPrefsModule
myPrefsModule.MyPrefs().setup()

Adding knobs

To make sure Your preferences are maintained create a setup function in the MyPrefs subclass that adds all needed settings:

  • Create a nuke.Knob as you would when adding knobs to other nodes and pass it as the first argument to self.addKnob

  • Set nuke flags like nuke.STARTLINE etc.

  • Set the knob’s default in the defaultValue argument of the self.addKnob method

# (...)
def setup(self):
    # Add knobs
    knob = nuke.Boolean_Knob("checkbox", "Autoload")
    knob.setFlag(nuke.STARTLINE)
    self.addKnob(knob, defaultValue=True)

Removing knobs

If You for instance want to rename a knob in a newer setting of Your app, just call self.removeKnob with the name of the knob you want to

# (...)
def setup(self):
    # Remove old knobs
    self.removeKnob("checkbox")
    # Add knobs
    knob = nuke.Boolean_Knob("autoLoad", "Autoload")
    knob.setFlag(nuke.STARTLINE)
    self.addKnob(knob, defaultValue=True)

Removing apps

To remove all knobs associated with an app:

# (...)
def setup(self):
    # Remove old app
    self.removeApp('My App')

Removing creators

To remove all knobs (and tabs) associated with a creator:

# (...)
def setup(self):
    # Remove old creator
    self.removeCreator('Me')

Getting knob values

Similar to retrieving knob values on regular nodes. You get the knob and use its functions to get the value:

PREFS = MyPrefs()
PREFS.setup()
PREFS.getKnob('autoLoad').value()
PREFS.getKnob('autoLoad').getValue()

Setting knob values

Similar to setting knob values on regular nodes. You get the knob and use its function to set the value:

PREFS = MyPrefs()
PREFS.setup()
PREFS.getKnob('autoLoad').setValue(False)

Resetting knob values

When the user clicks ‘Restore Defaults’ in the Preferences window all custom knobs are set to the default that was defined when adding the knob. To manually reset a knob:

PREFS = MyPrefs()
PREFS.setup()
PREFS.resetKnob('autoLoad')

To manually reset all knobs:

PREFS = MyPrefs()
PREFS.setup()
PREFS.resetAllKnobs()

Reacting to changed knobs

Every time a knob is changed the changed Signal is emits the changed knob. Be considerate about what you connect to it since the signal is sometimes emitted for all knobs regardless if they actually changed or not:

  • When setting up the preferences when Nuke opens (this is required for everything to work correctly)

  • When a user clicks ‘cancel’ in the Preferences window

  • If you have created multiple instances of the PreferencesManager, the same knob might be returned twice depending on the context

Setup:

PREFS = MyPrefs()
PREFS.setup()
def test(knob):
    print(knob.name(), knob.value())
PREFS.changed.connect(test)

Dev Notes

Due to a bug in Nuke12.2v6-current the last added tab (creator) doesn’t show up. Bug report: https://support.foundry.com/hc/en-us/articles/360020761839 The Preferences manager works around this by adding an adding an additional tab when useing those Nuke versions.