nuke.Gsv_Knob

class nuke.Gsv_Knob

Bases: Knob

A knob which holds the Graph Variables created within the scope of this group.

GSV knobs show variables inherited from parent groups. If these are modified then the inherited variables are overridden once they reach the scope of this group. In addition, the root group node shows the variables introduced by all groups in the script. This allows the root node to update GSVs within all VariableGroups. Note that VariableGroup scoped variables are still held by their respective groups; renaming or removing the VariableGroups will rename or remove all the GSV within the VariableGroup scope.

Methods

`Class`	return Class name.
`ClassID`	return Class ID.
`addGsvSet`	Add a GSV set to the containing group.
`clearAnimated`	Clear animation for channel 'c'.
`clearFlag`	Clear flag.
`contains`	Return True if the path exist relative to the GSV knob.
`critical`	param message message to put the knob in error, and do a popup.
`debug`	param message message to put out to the error console, attached to the knob, if the verbosity level is set high enough.
`enabled`	return True if the knob is enabled, False if it's disabled.
`error`	param message message to put the knob in error.
`fromScript`	Initialise from script.
`fullyQualifiedName`	Returns the fully-qualified name of the knob within the node.
`getAuthorMode`	Returns the authoring mode currently set on the knob.
`getAuthorModes`	Returns the names of the authoring modes of the knob if the knob is an authoring knob, otherwise an empty list.
`getDataType`	Return the data type of the GSV.
`getDerivative`	Return derivative at time 't' for channel 'c'.
`getFlag`	Returns whether the input flag is set.
`getGsvValue`	Return the value of the Graph Scope Variable.
`getIntegral`	Return integral at the interval [t1, t2] for channel 'c'.
`getKeyIndex`	Return keyframe index at time 't' for channel 'c'.
`getKeyList`	Get all unique keys on the knob.
`getKeyTime`	Return index of the keyframe at time 't' for channel 'c'.
`getLabel`	Return the label for the GSV.
`getListOptions`	Return the value options for a list GSV.
`getNthDerivative`	Return nth derivative at time 't' for channel 'c'.
`getNumKeys`	Return number of keyframes for channel 'c'.
`getTooltip`	Return the tooltip for the GSV.
`getValue`	Return the GSV sets.
`getValueAt`	Return value at time 't' for channel 'c'.
`hasExpression`	Return True if animation at index 'index' has an expression.
`isAnimated`	Return True if channel 'c' is animated.
`isFavorite`	Return True if the GSV under this path is marked as a favorite.
`isKey`	Return True if there is a keyframe at the current frame for channel 'c'.
`isKeyAt`	Return True if there is a keyframe at time 't' for channel 'c'.
`label`	Return the label for the GSV.
`makeWidget`	Returns an instance of the QWidget subclass used to edit the knob's value.
`name`	return name.
`node`	Return the node that this knob belongs to.
`notDefault`	return True if any of the values is not set to the default, False otherwise.
`removeGsv`	Remove a GSV from the containing variable set.
`removeGsvSet`	Remove a GSV set from the containing group.
`removeKey`	Remove key for channel 'c'.
`removeKeyAt`	Remove key at time 't' for channel 'c'.
`renameGsv`	Rename a GSV.
`renameGsvSet`	Rename a GSV set.
`setAnimated`	Set channel 'c' to be animated.
`setAuthorMode`	Sets the authoring mode on the knob.
`setDataType`	Set the data type of the GSV.
`setEnabled`	Enable or disable the knob.
`setExpression`	Set the expression for a knob.
`setFavorite`	Set the favorite property of a GSV.
`setFlag`	Logical OR of the argument and existing knob flags.
`setGsvValue`	Set the value of the Graph Scope Variable.
`setLabel`	Set the label for the GSV.
`setListOptions`	Set the value options for a list GSV.
`setName`	param s New name.
`setTooltip`	Set the tooltip for the GSV.
`setValue`	Set the GSV sets as a dictionary of dictionaries.
`setValueAt`	Sets the value 'val' at channel 'chan' for time 'time'.
`setVisible`	Show or hide the knob.
`toScript`	Return the value of the knob in script syntax.
`toScriptPrefix`	Write commands that must be executed before the to_script() value can be parsed.
`tooltip`	Return the tooltip for the GSV.
`value`	Return the GSV sets.
`visible`	return True if the knob is visible, False if it's hidden.
`warning`	param message message to put a warning on the knob.

Class() → Class name.

Returns: Class name.

ClassID() → Class ID.

Returns: Class ID.

addGsvSet(path) → bool

Add a GSV set to the containing group.

Parameters

path (str) – The path to the GSV set. The path format is [GroupName.][GroupName...]SetName.

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Returns

True if the GSV set was successfully added.

Return type

bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01'
knob.addGsvSet(path)

clearAnimated(): Clear animation for channel ‘c’. Return True if successful.

clearFlag(f) → None.: Clear flag. :param f: Flag. :return: None.

contains(path) → bool

Return True if the path exist relative to the GSV knob.

This function does not make distinction between the element types for the given path i.e. the path must include the GSV set name when checking for a variable in the __default__ variable set.

Parameters

path (str) – The path to test. The path format is [GroupName.][GroupName...]SetName.VariableName.

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Returns

Return True if the path exist relative to the GSV knob.

Return type

bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
knob.contains(path)

critical(message) → None.

Parameters: message – message to put the knob in error, and do a popup.
Returns: None.

debug(message) → None.

Parameters: message – message to put out to the error console, attached to the knob, if the verbosity level is set high enough.
Returns: None.

enabled() → Boolean.

Returns: True if the knob is enabled, False if it’s disabled.

error(message) → None.

Parameters: message – message to put the knob in error.
Returns: None.

fromScript(): Initialise from script.

fullyQualifiedName(channel=- 1) → string

Returns the fully-qualified name of the knob within the node. This can be useful for expression linking.

Parameters: channel – Optional parameter, specifies the channel number of the sub-knob (for example, channels of 0 and 1 would refer to the x and y of a XY_Knob respectively), leave blank or set to -1 to get the qualified name of the knob only.
Returns: The string of the qualified knob or sub-knob, which can be used directly in expression links.

getAuthorMode() → Integer.: Returns the authoring mode currently set on the knob. This is a unique string identifier of the option, which is also used for serialisation and deserialisation. It is not meant to change,thus one can rely on it. :return: The string identifier of the current authoring mode set.

getAuthorModes() → List.: Returns the names of the authoring modes of the knob if the knob is an authoring knob, otherwise an empty list. :return: The names of the authoring modes of the knob if the knob is an authoring knob, otherwise an empty list. This is a list of strings.

getDataType(path) → nuke.gsv.DataType

Return the data type of the GSV.

Parameters: path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
Returns: The type of data stored in the GSV (string/integer/list).
Return type: nuke.gsv.DataType

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
dataType = knob.getDataType(path)

getDerivative(): Return derivative at time ‘t’ for channel ‘c’.

getFlag(f) → Bool.: Returns whether the input flag is set. :param f: Flag. :return: True if set, False otherwise.

getGsvValue(path) → str

Return the value of the Graph Scope Variable.

Parameters: path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
Returns: Return the value of the Graph Scope Variable.
Return type: str

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
value = knob.getGsvValue(path)

getIntegral(): Return integral at the interval [t1, t2] for channel ‘c’.

getKeyIndex(): Return keyframe index at time ‘t’ for channel ‘c’.

getKeyList(): Get all unique keys on the knob. Returns list.

getKeyTime(): Return index of the keyframe at time ‘t’ for channel ‘c’.

getLabel() → str

Return the label for the GSV.

Parameters: path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
Returns: Return the label for the GSV.
Return type: str

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
label = knob.getLabel(path)

getListOptions(path) → list

Return the value options for a list GSV.

Parameters: path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
Raises: ValueError – If the path does not point to a list GSV.
Returns: Return the value options for a list GSV.
Return type: list

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
listOptions = knob.getListOptions(path)

getNthDerivative(): Return nth derivative at time ‘t’ for channel ‘c’.

getNumKeys(): Return number of keyframes for channel ‘c’.

getTooltip() → str

Return the tooltip for the GSV.

Parameters: path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
Returns: Return the tooltip for the GSV.
Return type: str

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
tooltip = knob.getTooltip(path)

getValue() → dict

Return the GSV sets.

Returns: GSV sets as a dictionary of dictionaries. Keys are the set names (including __default__). Values are dictionaries of the variables. Variables are returned as {variable_name: variable_value}.
Return type: dict

Example:

root = nuke.root()
knob = root['gsv']
sets = knob.getValue()

getValueAt(): Return value at time ‘t’ for channel ‘c’.

hasExpression(index=- 1) → bool: Return True if animation at index ‘index’ has an expression. :param index: Optional index parameter. Defaults to -1 if not specified. This can be specified as a keyword parameter if desired. :return: True if has expression, False otherwise.

isAnimated(): Return True if channel ‘c’ is animated.

isFavorite(path) → bool

Return True if the GSV under this path is marked as a favorite.

Favorite variables are shown in Nuke’s Variables Panel.

Parameters: path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
Returns: Return True if the GSV under this path is marked as a favorite.
Return type: bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
knob.isFavorite(path)

isKey(): Return True if there is a keyframe at the current frame for channel ‘c’.

isKeyAt(): Return True if there is a keyframe at time ‘t’ for channel ‘c’.

label() → str

Return the label for the GSV.

Parameters: path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
Returns: Return the label for the GSV.
Return type: str

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
label = knob.label(path)

makeWidget() → PySide6.QtWidgets.QWidget.: Returns an instance of the QWidget subclass used to edit the knob’s value. The widget will update the knob’s value when its value changes and should update its displayed value(s) when they change on the knob. Can return null if no widget should be created for the knob. :return: PySide6.QtWidgets.QWidget.

name() → name.

Returns: name.

node() → nuke.Node: Return the node that this knob belongs to. If the node has been cloned, we’ll always return a reference to the original. :return: The node which owns this knob, or None if the knob has no owner yet.

notDefault() → True if any of the values is not set to the default, False otherwise.

Returns: True if any of the values is not set to the default, False otherwise.

removeGsv(path) → bool

Remove a GSV from the containing variable set.

Parameters

path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Returns

True if the GSV was successfully removed.

Return type

bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
knob.removeGsv(path)

removeGsvSet(path) → bool

Remove a GSV set from the containing group.

Parameters

path (str) – The path to the GSV set. The path format is [GroupName.][GroupName...]SetName.

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Returns

True if the GSV set was successfully added.

Return type

bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01'
knob.removeGsvSet(path)

removeKey(): Remove key for channel ‘c’. Return True if successful.

removeKeyAt(): Remove key at time ‘t’ for channel ‘c’. Return True if successful.

renameGsv(path, name) → bool

Rename a GSV.

Parameters

path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
name (str) – The new variable name.

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Returns

True if the GSV was successfully renamed.

Return type

bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.OldVariableName'
knob.renameGsv(path, 'NewVariableName')

renameGsvSet(path, name) → bool

Rename a GSV set.

Parameters

path (str) – The path to the GSV set. The path format is [GroupName.][GroupName...]SetName.
name (str) – The new variable set name.

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Returns

True if the GSV set was successfully renamed.

Return type

bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.OldVariableSet'
knob.renameGsvSet(path, 'NewVariableSet')

setAnimated(): Set channel ‘c’ to be animated.

setAuthorMode(authorMode) → None.: Sets the authoring mode on the knob. This accepts both the unique string identifier, which is also used for serialisation and deserialisation, or index of the option for convenience. These values are not meant to change, thus one can rely on them. :param authorMode: The string identifier or index of the authoring mode. :return: None.

setDataType(path, value) → bool

Set the data type of the GSV.

Parameters

path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
value (nuke.gsv.DataType) – The type of data stored in the GSV (string/integer/list).

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Returns

True if the data type was set successfully.

Return type

bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
knob.setDataType(path, nuke.gsv.DataType.List)

setEnabled(enabled) → None.: Enable or disable the knob. :param enabled: True to enable the knob, False to disable it.

setExpression(expression, channel=- 1, view=None) → bool

Set the expression for a knob. You can optionally specify a channel to set the expression for.

Parameters

expression – The new expression for the knob. This should be a string.
channel – Optional parameter, specifying the channel to set the expression for. This should be an integer.
view – Optional view parameter. Without, this command will set the expression for the current view theinterface is displaying. Can be the name of the view or the index.

Returns

True if successful, False if not.

setFavorite(path, value) → bool

Set the favorite property of a GSV.

Parameters

path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
value (bool) – True to add to favorites. False to remove from favorites.

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Returns

True if the favorite property was successfully updated.

Return type

bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
knob.setFavorite(path, True)

setFlag(f) → None.: Logical OR of the argument and existing knob flags. :param f: Flag. :return: None.

setGsvValue(path, value, dataType, listOptions) → bool

Set the value of the Graph Scope Variable.

Parameters

path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
value (str) – The value of the Graph Scope Variable.
dataType (nuke.gsv.DataType, optional) – The type of data to store in the GSV (string/integer/list).
listOptions (list, optional) – The available options for a list variable.

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Returns

True if the GSV was set successfully.

Return type

bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
value = 'Clip1234'
knob.setGsvValue(path, value)

setLabel(path, value) → bool

Set the label for the GSV.

Parameters

path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
value (str) – The label text.

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Returns

True if the label was set successfully.

Return type

bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
knob.setLabel(path, 'Custom Label')

setListOptions(path, list) → bool

Set the value options for a list GSV.

Parameters

path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
list (list) – List of value options

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Returns

True if the value options were set successfully.

Return type

bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
knob.setListOptions(path, ['shot01', 'shot02'])

setName(s) → None.

Parameters: s – New name.
Returns: None.

setTooltip(path, value) → bool

Set the tooltip for the GSV.

Parameters

path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
value (str) – The tooltip text.

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Returns

True if the label was set successfully.

Return type

bool

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
knob.setTooltip(path, 'Custom Tooltip')

setValue(value) → None

Set the GSV sets as a dictionary of dictionaries.

Parameters

value (dict) – GSV sets as a dictionary of dictionaries. Keys are the set names (including __default__). Values are dictionaries of the variables. Variable are set as {variable_name: variable_value}.

Raises

RuntimeError – If the knob is locked.
ValueError – If the knob is read only.

Example:

root = nuke.root()
knob = root['gsv']
knob.setValue(
  {
    '__default__': {'dk1': 'dv1', 'dk2': 'dv2'},
    'Custom': {'ck1': 'cv1', 'ck2': 'cv2'}
  }
)

setValueAt(val, time, chan) → bool: Sets the value ‘val’ at channel ‘chan’ for time ‘time’. :return: True if successful, False if not.

setVisible(visible) → None.: Show or hide the knob. :param visible: True to show the knob, False to hide it.

toScript(quote, context=current) → string.: Return the value of the knob in script syntax. Pass True for quote to return results quoted in {}. Pass None for context to get results for all views and key times (as stored in a .nk file).

toScriptPrefix() → string: Write commands that must be executed before the to_script() value can be parsed. This is used to write commands to declare Layers and Formats and other objects that are shared by knobs.

tooltip() → str

Return the tooltip for the GSV.

Parameters: path (str) – The path to the GSV. The path format is [GroupName.][GroupName...]SetName.VariableName.
Returns: Return the tooltip for the GSV.
Return type: str

Example:

root = nuke.root()
knob = root['gsv']
path = 'VariableGroup1.VariableSet_01.Variable_01'
tooltip = knob.tooltip(path)

value() → dict

Return the GSV sets.

Returns: GSV sets as a dictionary of dictionaries. Keys are the set names (including __default__). Values are dictionaries of the variables. Variables are returned as {variable_name: variable_value}.
Return type: dict

Example:

root = nuke.root()
knob = root['gsv']
sets = knob.value()

visible() → Boolean.

Returns: True if the knob is visible, False if it’s hidden.

warning(message) → None.

Parameters: message – message to put a warning on the knob.
Returns: None.