PyPanel

Inherits :QWidget <https://pyside.github.io/docs/pyside/PySide/QtGui/QWidget.html> UserParamHolder

Synopsis

A custom PySide pane that can be docked into PyTabWidget. See detailed description…

Functions

Detailed Description

The PyPanel class can be used to implement custom PySide widgets that can then be inserted as tabs into tab-widgets .

There are 2 possible usage of this class:

Sub-classing:

When sub-classing the PyPanel class, you should specify when calling the base class constructor that you do not want to use user parameters, as this might conflict with the layout that you will use:

class MyPanel(NatronGui.PyPanel):
    def __init__(scriptName,label,app):
        NatronGui.PyPanel.__init__(scriptName,label,False,app)
        ...

You’re then free to use all features proposed by PySide in your class, including signal/slots See the following example.

Using the PyPanel API:

You can start adding user parameters using all the createXParam functions inherited from the UserParamHolder class.

Once all your parameters are created, create the GUI for them using the refreshUserParamsGUI() function:

panel = NatronGui.PyPanel("fr.inria.mypanel","My Panel",True,app)
myInteger = panel.createIntParam("myInt","This is an integer very important")
myInteger.setAnimationEnabled(False)
myInteger.setAddNewLine(False)

#Create a boolean on the same line
myBoolean = panel.createBooleanParam("myBool","Yet another important boolean")

panel.refreshUserParamsGUI()

You can then retrieve the value of a parameter at any time using the getParam(scriptName) function:

intValue = panel.getParam("myInt").get()
boolValue = panel.getParam("myBool").get()

Warning

Unlike the Effect class, parameters on panels are not automatically declared by Natron, which means you cannot do stuff like panel.intValue

You can get notified when a parameter’s value changed, by setting a callback using the setParamChangedCallback(callback) function that takes the name of a Python-defined function in parameters. The variable thisParam will be declared prior to calling the callback, referencing the parameter which just had its value changed.

Managing the panel:

Once created, you must add your panel to a PyTabWidget so it can be visible. Use the getTabWidget(scriptName) function to get a particular pane and then use the appendTab(tab) function to add this panel to the pane.

Warning

Note that the lifetime of the widget will be by default the same as the project’s GUI because PyPanel is auto-declared by Natron.

panel = NatronGui.PyPanel("fr.inria.mypanel","My Panel",True,app)
...
...
pane = app.getTabWidget("pane1")
pane.appendTab(panel)
app.mypanel = panel

If you want the panel to persist in the project so that it gets recreated and placed at its original position when the user loads the project, you must use the registerPythonPanel(panel,function) function.

Note that the function parameter is the name of a Python-defined function that takes no parameter used to create the widget, e.g.:

def createMyPanel():
panel = NatronGui.PyPanel(“MyPanel”,True,app) … #Make it live after the scope of the function app.mypanel = panel

app.registerPythonPanel(app.mypanel,”createMyPanel”)

This function will also add a custom menu entry to the “Manage layout” button (located in the top-left hand corner of every pane) which the user can trigger to move the custom pane on the selected pane.

../../../_images/customPaneEntry.png

Saving and restoring state:

When the panel is registered in the project using the registerPythonPanel(panel,function) function, you may want to also save the state of your widgets and/or special values.

To do so, you must sub-class PyPanel and implement the save() and restore(data) functions.

Note

User parameters, if used, will be automatically saved and restored, you don’t have to save it yourself. Hence if the panel is only composed of user parameters that you want to save, you do not need to sub-class PyPanel as it will be done automatically for you.

The function save() should return a string containing the serialization of your custom data.

The function restore(data) will be called upon loading of a project containing an instance of your panel. You should then restore the state of the panel from your custom serialized data.

Note that the auto-save of Natron occurs in a separate thread and for this reason it cannot call directly your save() function because it might create a race condition if the user is actively modifying the user interface using the main-thread.

To overcome this, Natron has an hidden thread-safe way to recover the data you have serialized using the save() function. The downside is that you have to call the onUserDataChanged() function whenever a value that you want to be persistent has changed (unless this is a user parameter in which case you do not need to call it).

Warning

If you do not call onUserDataChanged(), the save() function will never be called, and the data never serialized.

Member functions description

NatronGui.PyPanel.PyPanel(label, useUserParameters, app)
Parameters:
  • label – str
  • useUserParameters – bool
  • app – GuiApp

Make a new PyPanel with the given label that will be used to display in the tab header. If useUserParameters is True then user parameters support will be activated, attempting to modify the underlying layout in these circumstances will result in undefined behaviour.

NatronGui.PyPanel.addWidget(widget)
Parameters:widget – QWidget <https://pyside.github.io/docs/pyside/PySide/QtGui/QWidget.html>

Append a QWidget <https://pyside.github.io/docs/pyside/PySide/QtGui/QWidget.html> inherited widget at the bottom of the dialog. This allows to add custom GUI created directly using PySide that will be inserted after any custom parameter.

Warning

This function should be used exclusively when the widget was created using useUserParameters = True

NatronGui.PyPanel.getParam(scriptName)
Parameters:scriptName – str
Return type:Param

Returns the user parameter with the given scriptName if it exists or None otherwise.

Warning

This function should be used exclusively when the widget was created using useUserParameters = True

NatronGui.PyPanel.getParams()
Return type:sequence

Returns all the user parameters used by the panel.

Warning

This function should be used exclusively when the widget was created using useUserParameters = True

NatronGui.PyPanel.insertWidget(index, widget)
Parameters:
  • index – int
  • widget – QWidget <https://pyside.github.io/docs/pyside/PySide/QtGui/QWidget.html>

Inserts a QWidget <https://pyside.github.io/docs/pyside/PySide/QtGui/QWidget.html> inherited widget at the given index of the layout in the dialog. This allows to add custom GUI created directly using PySide. The widget will always be inserted after any user parameter.

Warning

This function should be used exclusively when the widget was created using useUserParameters = True

NatronGui.PyPanel.setParamChangedCallback(callback)
Parameters:callback – str

Registers the given Python callback to be called whenever a user parameter changed. The parameter callback is a string that should contain the name of a Python function.

The signature of the callback used on PyModalDialog is:

callback(paramName, app, userEdited)
  • paramName indicating the script-name of the parameter which just had its value changed.
  • app : This variable will be set so it points to the correct application instance.
  • userEdited : This indicates whether or not the parameter change is due to user interaction (i.e: because the user changed the value by theirself) or due to another parameter changing the value of the parameter via a derivative of the setValue(value) function.

Example:

def myParamChangedCallback(paramName, app, userEdited):
    if paramName == "myInt":
        intValue = thisParam.get()
        if intValue > 0:
            myBoolean.setVisible(False)

panel.setParamChangedCallback("myParamChangedCallback")

Warning

This function should be used exclusively when the widget was created using useUserParameters = True

NatronGui.PyPanel.setPanelLabel(label)
Parameters:callback – str

Set the label of the panel as it will be displayed on the tab header of the PyTabWidget. This name should be unique.

NatronGui.PyPanel.getPanelLabel()
Return type:str

Get the label of the panel as displayed on the tab header of the PyTabWidget.

NatronGui.PyPanel.getPanelScriptName()
Return type:str

Get the script-name of the panel as used internally. This is a unique string identifying the tab in Natron.

NatronGui.PyPanel.onUserDataChanged()

Callback to be called whenever a parameter/value (that is not a user parameter) that you want to be saved has changed.

Warning

If you do not call onUserDataChanged(), the save()NatronGui.PyPanel.save() function will never be called, and the data never serialized.

Warning

This function should be used exclusively when the widget was created using useUserParameters = True

NatronGui.PyPanel.save()
Return type:str

Warning

You should overload this function in a derived class. The base version does nothing.

Note

User parameters, if used, will be automatically saved and restored, you don’t have to save it yourself. Hence if the panel is only composed of user parameters that you want to save, you do not need to sub-class PyPanel as it will be done automatically for you.

Returns a string with the serialization of your custom data you need to be persistent.

NatronGui.PyPanel.restore(data)
Parameters:data – str

Warning

You should overload this function in a derived class. The base version does nothing.

This function should restore the state of your custom PyPanel using the custom data that you serialized. The data are exactly the return value that was returned from the save() function.