Knob flags provide a mean to customize aspects of a previously created knob. Flags can be added or removed from a knob using the SetFlags(callback, flags) and ClearFlags(callback, flags) calls singly or in combination using bitmask techniques. Knob flags should be used in the Knobs() creation call of your Op. Some have corresponding function calls on the knob object, which can be used in Op functions after the Knobs() call has completed - there is also a set_flag() call to achieve a similar result for those without such corresponding calls. In some circumstances, after such an update the knob interface may require manual refreshing through manual use of the appropriate updateWidgets(), redraw(), or changed() call. The most commonly used Flags are generic across all knobs and the remainder are specific to subsets of the full roster.
The flags are defined in Knob.h under the FlagMask enumeration.
| Flag (in ID order) | Related Knob calls | Action |
|---|---|---|
| DISABLED | enable()
disable()
enable(bool)
isEnabled()
|
A disabled knob is greyed out in the interface and its value cannot be altered by interface interaction. Neither can it be used as an expression source using animation menu drag and drop - to allow this to happen use OUTPUT_ONLY. |
| NO_ANIMATION | Disables the right-click button animation and expression options. | |
| DO_NOT_WRITE | Disables writing knob data to the script file and when copying/pasting. | |
| INVISIBLE | Disables panel and Viewer widgets. This is not the same as HIDDEN, and cannot be undone using show(), etc. | |
| RESIZABLE | Allows some knobs (notably curves and multi-line string) to expand to fill the gaps in the interface. On by default for most of the more complex knobs, but may not be appropriate depending on your interface layout. | |
| STARTLINE | Causes the knob to start a new line in the interface Properties panel before drawing its widget. Set by default on most knobs. | |
| ENDLINE | Causes the knob to start a new line in the interface Properties panel after drawing its widget. For code sanity, we recommend using STARTLINE on subsequent knobs, or alternatively use the Newline() knob type. | |
| NO_RERENDER | Removes the knob from the Op hash calculation, stopping re-rendering in the Viewer when the knob changes. | |
| NO_HANDLES | isHandleVisible()
|
Disables any Viewer handle/widget drawing the knob would normally perform. |
| KNOB_CHANGED_ALWAYS | Calls node()->knob_changed(), regardless of whether the node panel is currently open. Associated knob variables are not synchronized prior to calling knob_changed. | |
| NO_KNOB_CHANGED | Disables the calling of node()->knob_changed(). Automatically set if knob_changed() returns false for this knob. | |
| HIDDEN | show()
hide()
visible(bool)
isVisible()
|
Disables the drawing of panel and Viewer widgets. This can be set and cleared on the fly (for example, as a result of another knob’s knob_changed action) using the show() and hide() methods. |
| NO_UNDO | undoless(bool)
|
Disables the laying down of undo and redo points on the knob. |
| ALWAYS_SAVE | Forces data saving to the NUKE script regardless of whether not_default returns false. This flag is deprecated; simply override not_default as required. Bear in mind stashing large quantities of reconstructable data to the script can slow down NUKE’s loading and saving, and bloat scripts. | |
| NODE_KNOB | For internal use only. | |
| HANDLES_ANYWAY | Knob Viewer widgets/handles normally draw only when the knob is on the currently viewed Properties tab. This flag forces them to be drawn regardless of the current tab. | |
| KNOB_CHANGED_RECURSIVE | Generally, recursive knob_changed events are prevented. This disables this protection for the knob in question. | |
| READ_ONLY | setReadOnly(bool)
isReadOnly()
|
Disables modification through interface interaction, but allows copy and paste from the knob in question. |
| INDETERMINATE | Puts the knob into an indeterminate state, in many cases represented by a blacked out interface panel. | |
| COLOURCHIP_HAS_UNSET | Allows the ColorChip_knob to be put into its ‘unset’ state, as seen in the node tile_color and gl_color knobs by default. | |
| SMALL_UI | Puts the knob Properties panel into small interface mode, if it implements one. Often used for buttons on toolbars. | |
| NO_NUMERIC_FIELDS | Disables numeric entry box panels on the knob in question. | |
| NO_CURVE_EDITOR | Disables curve editor pop up on the knob in question. | |
| NO_MULTIVIEW | Disables the view menu button and splitting on the knob in question when in a multiview script. | |
| EARLY_STORE | Forces early synchronization of data back to storage. Allows knobs to be accessed from pre Op methods such as split_input and inputContext. | |
| MODIFIES_GEOMETRY | Should be set for any knob which, as the name suggests, modifies geometry. The flag forces NUKE to rebuild acceleration caches and so on. | |
| OUTPUT_ONLY | Like a READ_ONLY combined with a NO_RERENDER - any changes to it won’t count as a change to the script. | |
| NO_KNOB_CHANGED_FINISHED | Knob_changed_finished is a similar call to the more common Knob_changed, only occurring after a mouse drag or move has completed. This flag prevents it from being called. | |
| Numeric knobs | ||
| MAGNITUDE | For a knob containing an array of numbers, this flag enables a button to toggle between showing a single numerical entry box with slider (default) and all numerical entry boxes. For example, this flag defaults to true on the Color_knob. | |
| SLIDER | Turns on a slider widget. Only works if a single data type, or MAGNITUDE, is on. Defaults to on for most numerical entry types, except int based types. | |
| LOG_SLIDER | For knobs with SLIDER enabled, this flag sets the check marks to draw in a logarithmic rather than linear fashion. Defaults to on for Color_knob and WH_knob. If your slider range passes through zero, the checkmarks are drawn on a cubic rather than logarithmic scale. | |
| STORE_INTEGER | Stores and displays integers rather than floats. | |
| FORCE_RANGE | Forces the knob to clamp the value to the range set, rather than allowing out of range data. | |
| ANGLE | Turns on an angle related widget. | |
| NO_PROXYSCALE | Disables proxyscale on knobs which have it enabled (Note that clearing it won’t magically enable proxy scaling on those without such implementation). Useful in the situation where, for example, you want two params with labels x and y, but you don’t want the proxy scaling feature of the XY_knob. In such circumstances you may want to set NO_HANDLES as well. | |
| String knobs | ||
| GRANULAR_UNDO | Prevents the string knob concatenating multiple lesser undo stages into a single major undo. Could cause tedious, single letter undos! | |
| NO_RECURSIVE_PATHS | Badly named, this actually disables relative paths within a String_knob or one of its children. | |
| Enumeration knobs | ||
| SAVE_MENU | Forces the knob to write the contents of its menu entries to the script. Useful for Ops which dynamically alter the menu entries. | |
| Group knobs | ||
| CLOSED | open()
close()
open(bool)
isOpen()
|
Used to store a group’s open or closed state. |
| Toolbar knob | ||
| TOOLBAR_GROUP | Set by a BeginToolbar to turn a standard group into a Viewer toolbar. Usually not altered manually. | |
| TOOLBAR_LEFT | Used to define the position of a toolbar knob. Usually set during the BeginToolbar/EndToolbar construction phase. | |
| TOOLBAR_TOP | Used to define the position of a toolbar knob. Usually set during the BeginToolbar/EndToolbar construction phase. | |
| TOOLBAR_BOTTOM | Used to define the position of a toolbar knob. Usually set during the BeginToolbar/EndToolbar construction phase. | |
| TOOLBAR_RIGHT | Used to define the position of a toolbar knob. Usually set during the BeginToolbar/EndToolbar construction phase. | |
| TOOLBAR_POSITION | A convenience mask for the position part of the flags. | |
| ChannelSet/Channel knobs | ||
| NO_CHECKMARKS | Removes the individual channel checkboxes from the Properties panel. | |
| NO_ALPHA_PULLDOWN | Removes the extra dropdown that allows the user to select the 4th channel from the Properties panel. | |
| Format knob | ||
| PROXY_DEFAULT | Sets the default value of the knob to be the root.proxy_format, rather than the root.format. | |
For example, you could set a float knob to have a logarithmic slider and to be read only as below:
Float_knob(f, &_floatKnobData, "Float_knob");
SetFlags(Knob::LOG_SLIDER | Knob::READ_ONLY);
Where f is the knob callback, the _floatKnobData has been previously declared and initialized, and the Op code is using the DD::Image namespace.
Most numerical knobs in NUKE default to a range of 0 to 1, which is not necessarily what you’re after. SetRange can sort this out.
Very importantly, and often overlooked, NUKE has the ability to assign tooltips to every knob you create. Do this, and do it as soon as you can, since ultimately there’ll always be somebody using your tool other than you, and like the rest of us they won’t read the manual first. Tooltips, coupled with the overall node help, are the perfect solution to this as they provide contextual help at the customers fingertips. In the long term, it’ll save you time in writing extensive per control manual entries and answering questions and support enquiries.
Adding a tooltip is dead easy - after your knob creation call add a Tooltip(<knob callback>, <text>) call. For the text you can use plain text coupled with ‘\n’ for newlines, basic tags such as <i> </i>, <b> </b>, and so on.