Gaffer’s UIs for plugs and nodes are defined using a metadata convention. This makes it easy to customise the UI for a specific node type, or even for a specific node instance. This document provides a reference for the most common metadata items.


Name Purpose Example Values
label Label used instead of plug name “My Label”
description Describes the purpose of a node or plug “Turns on the thingammajig”
icon Name of an image file used to represent a node “myAwesomeNode.png”
documentation:url Link to node documentation
userDefault Overrides the default value of a plug 10.5
preset:<name> Specifies a named preset value “preset:Max”, 1

NodeEditor Layout

Name Purpose Example Values
layout:divider Places a divider after the plug True
layout:index Integer index in the layout order 0 (first), -1 (last)
layout:section Specifies the section the plug belongs in TabName.SectionName
layout:accessory Places widget on same line as previous widget True

GraphEditor Layout

Name Purpose Example Values
nodule:color The colour of the plug imath.Color3f( 0, 1, 0 )
connectionGadget:color The colour of input connections imath.Color3f( 1, 0, 0 )
nodeGadget:color The colour of a node imath.Color3f( 0, 0, 1 )
noduleLayout:section The edge the plug appears on “left”, “right”, “top”, “bottom”
noduleLayout:visible Shows/hides the plug True (visible), False (hidden)

Viewer Layout

Name Purpose Example Values
layout:divider Places a divider after the plug True
layout:index Integer index in the layout order 0 (first), -1 (last)
toolbarLayout:section The edge of the viewer the plug appears on “Left”, “Right”, “Top”, “Bottom”


Custom widget types may be registered for use in the NodeEditor by adding "plugValueWidget:type" metadata to a plug. Note that not all widget types are compatible with all plug types - the table below lists the relevant widget types by plug type.

Plug Type Purpose PlugValueWidgetType
Plug (and subclasses) Hide the plug permanently “”
Plug (and subclasses) Display the input connection “GafferUI.ConnectionPlugValueWidget”
ValuePlug (and subclasses) Show a menu of presets “GafferUI.PresetsPlugValueWidget”
IntPlug Display a checkbox “GafferUI.BoolPlugValueWidget”
StringPlug Allow multi-line text entry “GafferUI.MultiLineStringPlugValueWidget”
StringPlug Show a file chooser “GafferUI.FileSystemPathPlugValueWidget”
StringVectorDataPlug Show a file chooser “GafferUI.FileSystemPathVectorDataPlugValueWidget”

These widget types may be further customised using additional metadata as follows


Name Purpose Example values
boolPlugValueWidget:displayMode Change display style “checkBox”, “switch”


These options also apply to the FileSystemPathVectorDataPlugValueWidget.

Name Purpose Example values
path:bookmarks Specify which bookmarks to use “image”
path:leaf Don’t accept directories True, False
path:valid Only accept files that exist True, False
fileSystemPath:extensions Specify valid file types “jpg jpeg png”
fileSystemPath:extensionsLabel Describe valid file types “Web images”
fileSystemPath:includeSequences Display file sequences True


Name Purpose Example values
presetsPlugValueWidget:allowCustom Allow values not in preset list True, False