PyModalDialog — Natron 2.5.0 documentation

# PyModalDialog

Inherits QDialog UserParamHolder

## Synopsis

A modal dialog to ask information to the user or to warn about something. See detailed description…

### Functions

- def `addWidget` (widget)

- def `getParam` (scriptName)

- def `insertWidget` (index,widget)

- def `setParamChangedCallback` (callback)

## Detailed Description

The modal dialog is a way to ask the user for data or to inform him/her about something going on. A modal window means that control will not be returned to the user (i.e. no event will be processed) until the user closed the dialog.

If you are looking for a simple way to just ask a question or report an error, warning or even just a miscenalleous information, use the `informationDialog(title,message)` function.

To create a new PyModalDialog, just use the `createModalDialog()` function, e.g.:

> # In the Script Editor

> dialog = app1.createModalDialog()

To show the dialog to the user, use the `exec_()` function inherited from `QDialog`

    dialog.exec_()

Note that once `exec_()` is called, no instruction will be executed until the user closed the dialog.

The modal dialog always has OK and Cancel buttons. To query which button the user pressed, inspect the return value of the `exec_()` call:

    if dialog.exec_():
        #The user pressed OK
        ...
    else:
        #The user pressed Cancel or Escape

### Adding user parameters:

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

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

    myInteger = dialog.createIntParam("myInt","This is an integer very important")
    myInteger.setAnimationEnabled(False)
    myInteger.setAddNewLine(False)

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

    dialog.refreshUserParamsGUI()

    dialog.exec_()

You can then retrieve the value of a parameter once the dialog is finished using the `getParam(scriptName)` function:

    if dialog.exec_():
        intValue = dialog.getParam("myInt").get()
        boolValue = dialog.getParam("myBool").get()

Warning

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

### Member functions description

NatronGui.PyModalDialog.addWidget(widget)
  Parameters

    widget – QWidget

Append a QWidget inherited widget at the bottom of the dialog. This allows one to add custom GUI created directly using PySide that will be inserted after any custom parameter.

NatronGui.PyModalDialog.getParam(scriptName)
  Parameters

    scriptName – `str`

  Return type

    `Param`

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

NatronGui.PyModalDialog.insertWidget(index, widget)
  Parameters

    - index – `int`

    - widget – `PySide.QtGui.QWidget`

Inserts a QWidget inherited widget at the given index of the layout in the dialog. This allows one to add custom GUI created directly using PySide. The widget will always be inserted after any user parameter.

NatronGui.PyModalDialog.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)

    dialog.setParamChangedCallback("myParamChangedCallback")