Knob Flags, Ranges & Tooltips
=============================

.. _knobs-knobflags:

Knob Flags
----------

Knob flags provide a means for customising a number of aspects of the previously created knob. Flags can be added or removed from a knob using the **SetFlags(callback, flags)** and **ClearFlags(callback, flags)** calls, so 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, if not, there is a set_flag() call to achieve similar 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, 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()                    A disabled knob is greyed out in the interface and its value cannot be altered via interface interaction.
                              | disable()                   Neither can it be used as a expression source using animation menu drag and drop, to allow this to 
                              | enable(bool)                happen use OUTPUT_ONLY.
                              | isEnabled()
NO_ANIMATION                                                Disables the right click and button animation and expression options.
DO_NOT_WRITE                                                Disables writing knob data to the script file, and when copying and pasting.
INVISIBLE                                                   Disables panel and viewer widgets. 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 knob to start a new line in the param panel interface before drawing its widget. Set by default on most knobs.
ENDLINE                                                     Causes knob to start a new line in the param panel interface after drawing its widget. For code sanity, generally
                                                            STARTLINE on subsequent knob, or Newline() knob type is recommended.
NO_RERENDER                                                 Removes knob from the Op hash calculation. This has the effect of changes to the knob not
                                                            resulting in a rerender in the viewer.
NO_HANDLES                    | isHandleVisible()           Disables any viewer handle/widget drawing the knob offers.
KNOB_CHANGED_ALWAYS                                         Calls node()->knob_changed(), regardless of if the node panel is currently open. Associated knob variables not synchronised prior to calling knob_changed.
NO_KNOB_CHANGED                                             Disables calling of node()->knob_changed(). Automatically set if knob_changed() returns false for this knob.
HIDDEN                        | show()                      Disables drawing of panel and viewer widgets. Can be set and cleared on the fly (eg as a result of another
                              | hide()                      knob's knob_changed action) using the show() and hide() methods.
                              | visible(bool)
                              | isVisible()
NO_UNDO                       | undoless(bool)              Disables laying down of undo and redo points on the knob.
ALWAYS_SAVE                                                 Forces data saving to NUKE script regardless of whether not_default returns false. 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 tab. This 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)           Disables modification through interface interaction, but allows copy and paste from knob in question.
                              | isReadOnly()
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 it's 'unset' state, as seen in the node tile_color & gl_color knobs by default.
SMALL_UI                                                    Puts the knob param 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 view menu button and splitting on the knob in question when in a multiview script.
EARLY_STORE                                                 Forces early synchronisation 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. Forces NUKE to rebuild acceleration caches and so forth.
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 occuring 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 enables a button to only show a single numerical entry box with slider by default, until
                                                            the user toggles the button to show all numerical entry boxes. Defaults to true, for example, on :ref:`knobs-knobtypes-color_knob`.
SLIDER                                                      Turns on a slider widget. Only works if a single data type, or if MAGNITUDE is on. Defaults to on for most numerical entry types, excepting
                                                            int based.
LOG_SLIDER                                                  For knobs with SLIDER enabled, this sets the check marks to be drawn in a logarithmic rather than linear fashion. Defaults to on for 
                                                            :ref:`knobs-knobtypes-color_knob` and :ref:`knobs-knobtypes-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                                                       Turn on an angle related widget.
NO_PROXYSCALE                                               Disables proxyscale on knobs which have it enabled (note clearing it won't magically enable proxy scaling on those without such an 
                                                            implementation). Useful in the situation where, for example, you want two params with labels x & y, but you don't want the proxy scaling
                                                            feature of the :ref:`knobs-knobtypes-xy_knob`. In most such circumstances you'll likely 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. Will make for tedious single letter undos!
NO_RECURSIVE_PATHS                                          Badly named, this actually disables *relative* paths within a :ref:`knobs-knobtypes-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()                      Used to store a group's open or closed state.
                              | close()
                              | open(bool)
                              | isOpen()

**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 :ref:`knobs-knobtypes-begintoolbar` construction pase.
TOOLBAR_TOP                                                 Used to define the position of a toolbar knob. Usually set during the :ref:`knobs-knobtypes-begintoolbar` construction pase.
TOOLBAR_BOTTOM                                              Used to define the position of a toolbar knob. Usually set during the :ref:`knobs-knobtypes-begintoolbar` construction pase.
TOOLBAR_RIGHT                                               Used to define the position of a toolbar knob. Usually set during the :ref:`knobs-knobtypes-begintoolbar` construction pase.
TOOLBAR_POSITION                                            A convenience mask for the position part of the flags.

**ChannelSet/Channel knobs**
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
NO_CHECKMARKS                                               Removes the individual channel checkboxes from the param panel.
NO_ALPHA_PULLDOWN                                           Removes the extra pulldown that allows the user to elect the 4th channel from the param 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:

.. code-block:: c

  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 initialised, and the Op code is using the DD::Image namespace.

Knob Ranges
-----------

Most numerical knobs in NUKE default to a range of 0 to 1, which is not necessarily what you're after. The SetRange should sort you out.

Knob Tooltips
------------- 

Very importantly, and oft 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 clients 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; simply after you 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.

