DD::Image::Knob

DD::Image::Knob Class Reference

Inherits DD::Image::ValueStuffI.

Inherited by DD::Image::ShapeKnob, and DummyKnob.

List of all members.

Classes

class  cstring
class  Indent
class  Script_List

Public Types

enum  CallbackReason { kDestroying, kIsVisible, kUpdateWidgets, kChanged }
enum  HandleType {
  POSITION, SELECTABLE, DISTANCE_FROM_POINT, DISTANCE_WITH_SNAP,
  ANYWHERE, ANYWHERE_MOUSEMOVES, ANYWHERE_KEY_PRESSED, SELECTED_BY_THIS
}
enum  HandleFlags { HOVER }
typedef U64 FlagMask
typedef int(* Callback )(void *closure, CallbackReason)

Public Member Functions

void setClaimedName (const std::string &claimedName)
const std::string & claimedName ()
void setDefaultName (const std::string &defaultName)
const std::string & defaultName () const
 Knob (Knob_Closure *c, const char *name, const char *label=0)
virtual const char * Class () const =0
virtual int ClassID () const
virtual Enumeration_KnobI * enumerationKnob ()
virtual MultiArray_KnobI * multiArrayKnob ()
virtual List_KnobI * listKnob ()
virtual Table_KnobI * tableKnob ()
virtual Geo_KnobI * geoKnob ()
virtual Axis_KnobI * axisKnob ()
virtual PositionVector_KnobI * positionVectorKnob ()
virtual PluginPython_KnobI * pluginPythonKnob ()
virtual GeoSelect_KnobI * geoSelectKnob ()
virtual
ControlPointCollection_KnobI * 		controlPointCollectionKnob ()
virtual MetaKeyFrame_KnobI * metaKeyFrameKnob ()
virtual TransformJack_KnobI * transformJackKnob ()
virtual Transform2d_KnobI * transform2dKnob ()
virtual Ripple_KnobI * rippleKnob ()
Node * node () const
void set_node (Node *n)
Op * op () const
const NameString & name () const
void name (const char *p)
bool is (const char *v) const
bool startsWith (const char *v) const
const std::string & label () const
bool labelNotNull () const
void label (const char *)
bool canCopyValue () const
std::string fullyQualifiedName () const
const char * label_c_str () const
const char * name_c_str () const
const std::string & tooltip () const
void tooltip (const std::string &p)
FlagMask flags () const
void flags (FlagMask f)
void set_flag (FlagMask f)
void clear_flag (FlagMask f)
void invert_flag (FlagMask f)
void set_flag (FlagMask f, bool b)
bool flag (FlagMask f) const
bool any_of (FlagMask f) const
bool all_of (FlagMask f) const
virtual bool priority_undo () const
virtual WidgetPointer make_widget ()
virtual void updateUI (const OutputContext &)
void addCallback (Callback cb, void *closure)
void removeCallback (Callback cb, void *closure)
bool isEnabled () const
void enable ()
void disable ()
virtual void enable (bool)
virtual bool disabledDueToLicensing () const
virtual bool isReadOnly () const
void setReadOnly (bool value)
bool isVisible () const
bool isHandleVisible () const
int openLinkCount () const
 the number of panels open which contain a link knob pointing at this knob
virtual void openLink ()
 increase the openLinkCount
virtual void closeLink ()
 decrease the openLinkCount
void hide ()
void show ()
void visible (bool)
bool isOpen () const
void open ()
void close ()
void open (bool)
bool isPushed () const
void pushed (bool p)
Knob * knob (const char *) const
Knob * knob (int) const
bool node_disabled () const
bool panel_visible () const
bool node_selected () const
unsigned node_gl_color () const
bool script_command (const char *command, bool py=true, bool eval=true) const
bool script_expand (const char *str, int what=1) const
virtual void reset_to_default ()
virtual bool build_handle (ViewerContext *)
void add_draw_handle (ViewerContext *)
virtual void draw_handle (ViewerContext *)
typedef bool() Handle (ViewerContext *ctx, Knob *, int index)
void begin_handle (HandleContext command, ViewerContext *ctx, Handle *cb, int index, float x=0, float y=0, float z=0, ViewerContext::Cursor cursor=ViewerContext::kNoCursor)
void begin_handle (ViewerContext *ctx, Handle *cb, int index, float x=0, float y=0, float z=0, ViewerContext::Cursor cursor=ViewerContext::kNoCursor)
void end_handle (ViewerContext *ctx)
void make_handle (HandleContext command, ViewerContext *ctx, Handle *cb, int index, float x, float y, float z=0, ViewerContext::Cursor cursor=ViewerContext::kNoCursor)
void make_handle (ViewerContext *ctx, Handle *cb, int index, float x, float y, float z=0, ViewerContext::Cursor cursor=ViewerContext::kNoCursor)
bool is_selected (ViewerContext *, Handle *cb, int index)
bool clear_selected (ViewerContext *)
bool toggle_selected (ViewerContext *, Handle *cb, int index)
int selection_size (ViewerContext *)
void new_undo (const char *name=0)
void extra_undo ()
void new_undo (const void *controller)
virtual Knob * undoer ()
void setUndoer (Knob *undoer)
void new_nudge_undo ()
void undo ()
void redo ()
virtual void changed ()
void updateWidgets ()
void asapUpdate ()
void asapUpdate (const Box &box, int direction=0)
void redraw ()
void undoless (bool undoless)
const OutputContext & uiContext () const
const Format & input_format () const
virtual void store (StoreType, void *p, Hash &hash, const OutputContext &context)
virtual void append (Hash &hash, const OutputContext *context)
virtual int get_key_list (std::set< int > &keylist) const
virtual bool splitForViews () const
virtual ViewSet storedViews () const
virtual bool keyframesDisplayed () const
virtual bool from_script (const char *v)
bool set_text (const char *v)
bool to_double (const char *, double &result)
bool to_int (const char *, int &result)
bool to_bool (const char *, bool &result)
virtual const char * get_text (const OutputContext *=0) const
virtual void to_script (std::ostream &, const OutputContext *, bool quote) const
virtual void to_script_prefix (std::ostream &) const
virtual void to_script_userknob (std::ostream &) const
virtual bool not_default () const
void * pyObject ()
void setPyObject (void *s)

Static Public Member Functions

static void addTooltipOverride (const std::string &knob, const std::string &tooltip)
static const char * script_result (bool py=false)
static void script_unlock ()
static int message (char t, const char *,...)
static int vmessage (char t, const char *, va_list)
static Indent * indent ()
static void error (const char *lpFormat,...)
static void warning (const char *lpFormat,...)
static void critical (const char *lpFormat,...)
static void debug (const char *lpFormat,...)
static void error (Knob *lpKnob, const char *lpFormat,...)
static void warning (Knob *lpKnob, const char *lpFormat,...)
static void critical (Knob *lpKnob, const char *lpFormat,...)
static void debug (Knob *lpKnob, const char *lpFormat,...)

Static Public Attributes

static const FlagMask DISABLED
static const FlagMask NO_ANIMATION
static const FlagMask DO_NOT_WRITE
static const FlagMask INVISIBLE
static const FlagMask RESIZABLE
static const FlagMask STARTLINE
static const FlagMask ENDLINE
static const FlagMask NO_RERENDER
static const FlagMask NO_HANDLES
static const FlagMask KNOB_CHANGED_ALWAYS
static const FlagMask NO_KNOB_CHANGED
static const FlagMask HIDDEN
static const FlagMask NO_UNDO
static const FlagMask ALWAYS_SAVE
static const FlagMask NODE_KNOB
static const FlagMask HANDLES_ANYWAY
static const FlagMask KNOB_CHANGED_RECURSIVE
static const FlagMask READ_ONLY
static const FlagMask INDETERMINATE
static const FlagMask COLOURCHIP_HAS_UNSET
 whether a color chip can be in the 'unset' state, DEFAULTS TO FALSE
static const FlagMask SMALL_UI
static const FlagMask NO_NUMERIC_FIELDS
static const FlagMask NO_CURVE_EDITOR
static const FlagMask NO_MULTIVIEW
static const FlagMask EARLY_STORE
static const FlagMask MODIFIES_GEOMETRY
static const FlagMask OUTPUT_ONLY
static const FlagMask NO_KNOB_CHANGED_FINISHED
static const FlagMask SET_SIZE_POLICY
static const FlagMask MAGNITUDE
static const FlagMask SLIDER
static const FlagMask LOG_SLIDER
static const FlagMask STORE_INTEGER
static const FlagMask FORCE_RANGE
static const FlagMask ANGLE
static const FlagMask NO_PROXYSCALE
static const FlagMask GRANULAR_UNDO
static const FlagMask NO_RECURSIVE_PATHS
static const FlagMask SAVE_MENU
static const FlagMask CLOSED
static const FlagMask TOOLBAR_GROUP
static const FlagMask TOOLBAR_LEFT
static const FlagMask TOOLBAR_TOP
static const FlagMask TOOLBAR_BOTTOM
static const FlagMask TOOLBAR_RIGHT
static const FlagMask TOOLBAR_POSITION
static const FlagMask NO_CHECKMARKS
static const FlagMask NO_ALPHA_PULLDOWN
static const FlagMask PROXY_DEFAULT
static int nudgeController
static Knob & showPanel
 passed to Op::knob_changed() when panel opened
static Knob & hidePanel
 passed to Op::knob_changed() when panel closed
static Knob & inputChange
 passed to Op::knob_changed() when inputs change
static bool undo_state
 true in Op::knob_changed() when called due to undo/redo
static void(* pMessageCallback )(const Knob *lpKnob, const OpMessage &lrMessage)
 Callback function for internal use.

Detailed Description

Provides the user interface for a single named "control" of an Op.

The Op::knobs() function is called to create these and to list them in order to store() values into an instance of an Op.

The to_script() and from_script() methods are used to read and write the value as a text stream. This is used for saving scripts and also for implementing undo/redo.

The most common types of knobs produce a widget in the "control panel" of a Node in Nuke. However this functionality is private to Nuke. Plugins can only make knobs that are manipulated through the user clicking and dragging on the viewers. They can also create "child" knobs that display widgets.

Writing a new knob type is quite complex, though I hope it is not hopeless. It is recommended that you examine the source code to plugins that use it (DustBust, ...).

Member Enumeration Documentation

enum DD::Image::Knob::HandleType

Commands passed to begin_handle

Constructor & Destructor Documentation

Knob::Knob ( Knob_Closure *  cb,
const char *  name,
const char *  label = 0 
)

The constructor for a knob adds it to the list being built for the current Node.

References DD::Image::INVISIBLE.

Member Function Documentation

const char * Knob::Class (  )  const [pure virtual]

Return a string name for the type of knob. The base class returns "Knob". This is currently only used for messages.

int Knob::ClassID (  )  const [virtual]

Return the enumeration value from Knobs.h that will create this knob. This is used to write instructions for creating this knob to a saved script. If no value creates this knob then return 0, and the user will not be able to clone the knob. The base class returns zero.

Op * Knob::op (  )  const

Return an Op that belongs to the control panel this Knob is on. You cannot make very many assumptions about this op except that it has been constructed. You could for instance get the Class() or help().

bool Knob::startsWith ( const char *  substring  )  const

fn bool Knob::is(const char* name) const Return true if the name matches the passed string. You should use this in Op::knob_changed() methods to figure out if the changed knob is the one you are interested in.

Return true if the name starts with the substring. Useful in Op::knob_changed() to detect a set of related knobs.

std::string Knob::fullyQualifiedName (  )  const

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

const std::string & Knob::tooltip (  )  const

Get the tooltip for the knob

void DD::Image::Knob::addTooltipOverride ( const std::string &  knob,
const std::string &  tooltip 
) [static]

Add a tooltip override to the tooltip overrides table. 'knob' is expected to be in the form 'Blur.size', and tooltip is the text to be displayed instead of the default tooltip

WidgetPointer Knob::make_widget (  )  [virtual]

Create the widget to put in a panel for the knob and return it. This can return null if no widget should be created, this is what the default version does.

addCallback() must be called to add some function that is called when the value changes or when the knob is destroyed, so that the widget can respond to it. Nuke source code currently wraps this in another function called add_widget_to_knob().

The UI toolkit used is subject to change and may be statically linked into the application; it is currently recommended that plugins do NOT attempt to implement this function.

void Knob::updateUI ( const OutputContext &   )  [virtual]

Cause any update to widgets due to the outputContext() being changed. The default version does nothing, but subclasses that display the animated value must do this.

void Knob::addCallback ( Callback  cb,
void *  userData 
)

Add a callback to a GUI widget. Changes to the knob's visibility, enable, the value, and the destruction of the knob all send messages to this.

void Knob::removeCallback ( Callback  cb,
void *  userData 
)

Remove a callback added with addCallback(). You must not call this if your callback got the kDestroying message.

bool Knob::isEnabled (  )  const [inline]

Return true if enable() was called or false if disable() was called.

bool Knob::enable (  )  [inline]

Same as enable(true)

References enable().

Referenced by enable(), and DD::Image::ReadGeo::knob_changed().

bool Knob::disable (  )  [inline]

Same as enable(false)

Referenced by DD::Image::ReadGeo::knob_changed().

void Knob::enable ( bool  e  )  [virtual]

Enable or disable (gray out) the widget. For historical reasons this will also show/hide the handles in the viewer by setting the NO_HANDLES flag. If you don't want this, set the flag back to the way you want after calling this.

bool Knob::isReadOnly (  )  const [virtual]

Return true if this knob is read only. The default implementation tests for the read-only flag. In read-only mode, values will be displayed and can be copied and viewed as usual, but no modifications through direct user input will be possible. Changes may still be made through Tcl/Python.

Not all knobs support this flag.

bool Knob::isVisible (  )  const

Return true if the widget is visible (ie the control panel is open and switched to the tab that this knob is on). Knobs with no widgets return panel_visible().

References panel_visible().

void Knob::hide (  )  [inline]

Make the widget disappear. This only works if the widget exists, which means you have to defer this until Op::knob_callback() is called with the show-panel knob.

Referenced by DD::Image::NukeWrapper::knob_changed(), and DD::Image::DrawIop::knob_changed().

void Knob::show (  )  [inline]

Make the widget become visible, undoing a hide().

Referenced by DD::Image::NukeWrapper::knob_changed(), and DD::Image::DrawIop::knob_changed().

void Knob::visible ( bool  v  ) 

Does show() if true, hide() if false.

Referenced by DD::Image::DrawIop::knob_changed(), and DD::Image::Write::set_file_type().

bool Knob::isOpen (  )  const [inline]

Returns true if this hierarchy title is open.

void Knob::open (  )  [inline]

Makes a hierarchy title open, showing all the child knobs.

References open().

Referenced by open().

void Knob::close (  )  [inline]

Makes a hierarchy title close, hiding all the child knobs.

void Knob::open ( bool  v  ) 

Does open() if true, close() if false.

bool Knob::isPushed (  )  const [inline]

Return true if this knob is "pushed". This means that the user is either holding down a slider in the control panel or is dragging a handle in the viewer. This can be used to decide whether to draw a texture map preview or not.

void Knob::pushed ( bool  p  )  [inline]

Turn isPushed() on/off.

Knob * Knob::knob ( const char *  name  )  const

Return another knob on the same control panel as this knob, looked up by name.

Knob * Knob::knob ( int  n  )  const

Find a knob by index number. If the index number is larger than the number of knobs then null is returned. By starting at zero and incrementing until this returns null you will get every Knob known about. One of the return values will be this knob itself.

bool Knob::node_disabled (  )  const

Return true if the node this knob is in is disabled.

bool Knob::panel_visible (  )  const

Returns true if the control panel for this node is open. You may want to use visible(), which will return true only if the tab containing this knob is open.

Referenced by isVisible().

bool Knob::node_selected (  )  const

Returns true if the node is selected by the user. This can be used to turn a wireframe preview on/off.

unsigned Knob::node_gl_color (  )  const

Returns the color selected by the user to draw things in the viewer. The return value is of the form 0xrrggbb00.

bool Knob::script_command ( const char *  command,
bool  py = true,
bool  eval = true 
) const

Execute a string in Nuke's scripting language. You must call script_unlock() after calling this!

See also:
Op::script_command

bool Knob::script_expand ( const char *  text,
int  arg = 1 
) const

See also:
Op::script_expand(). The integer argument is unused currently. Use 1 for future compatibility.

const char * Knob::script_result ( bool  py = false  )  [static]

See also:
Op::script_result().

void Knob::script_unlock (  )  [static]

See also:
Op::script_unlock()

int Knob::message ( char  t,
const char *  format,
  ... 
) [static]

See also:
Op::message_f

int Knob::vmessage ( char  t,
const char *  format,
va_list  va 
) [static]

See also:
Op::message_f

bool Knob::build_handle ( ViewerContext *  ctx  )  [virtual]

This call is used by viewers to search for objects that need to draw "handles" into the viewer. This will be called for all knobs on any opened control panel.

If you want to draw anything you should add a callback with ViewerContext::add_draw_handle(). Or you can return true and a callback that calls draw_handle() will be added for you.

Recommended you check that the viewer is in the correct mode (ctx->viewer_mode()!=0 indicates a 3D mode) and that visible() is true before you add the callbacks.

The default version returns false.

Referenced by DD::Image::Op::anyKnobHandles(), and DD::Image::Op::build_knob_handles().

void Knob::add_draw_handle ( ViewerContext *  ctx  ) 

Convenience function to call ViewerContext::add_draw_handle() with a function that will call this->draw_handle().

References DD::Image::ViewerContext::add_draw_handle().

Referenced by DD::Image::Op::add_knob_handle(), and DD::Image::Op::build_knob_handles().

void Knob::draw_handle ( ViewerContext *  ctx  )  [virtual]

If build_handle() returns true, then this will be called to actually draw the handle in OpenGL.

void Knob::begin_handle ( HandleContext  command,
ViewerContext *  ctx,
Handle *  cb,
int  index,
float  x = 0,
float  y = 0,
float  z = 0,
ViewerContext::Cursor  cursor = ViewerContext::kNoCursor 
)

Start drawing a handle. Any OpenGL you draw after this will be passed through hit-detection on a PUSH event and if selected then the cb will be called with events. draw_handle() should call this to indicate that the next thing to be drawn is something the user can click on, which we call a "handle".

The command describes the xyz that will be passed back to the handle callback. Current values are:

  • POSITION: The xyz passed in plus the distance the mouse dragged, with the numbers rounded somewhat to "nice" decimal numbers, and if the mouse has not moved very far or if shift is held down to restrict the axis, the passed-in xyz unchanged.

  • SELECTABLE: Same as POSITION except this is a selectable handle. It is selected by the user clicking on it, by the user dragging out a box, or by shift-clicking. When the user drags any selected handle then all of them get PUSH, DRAG, and RELEASE events and the first one gets the rounded position and all the others move in a locked formation with it. Any keystrokes are sent as KEY events to all the selected handles. If cb calls ctx->menu() then the menu only appears once, and all other calls return the same menu item, so the same action is done to all points.

  • DISTANCE_FROM_POINT: The difference between where the mouse is and the xyz position passed in this call (pass 0,0,0 if you want the absolute position in space). The xyz are not rounded so you probably don't want the numbers shown to the user, as they will have ugly extra digits of precision.

  • DISTANCE_WITH_SNAP: Same as DISTANCE_FROM_POINT except the delta values are rounded to "nice" numbers. Pass 0,0,0 to get "nice" rounded positions in space.

  • ANYWHERE, ANYWHERE_MOUSEMOVES, SELECTED_BY_THIS: these should only be passed to make_handle.

The cb function is called when the user causes an event that Nuke thinks should be sent to this handle. The function should return true if the event is consumed by this handle (returing false allows an ANYWHERE handle to get events). The context->event() says why this is being called:

  • PUSH - mouse was pushed down

  • DRAG - mouse was dragged after being pushed. The mouse position can be retrieved from context->x(), y(), and z(). These coordinates are in the same transformation that make_handle() was called in. You can also get the mouse position in pixels from context->mouse_x() and mouse_y(), though I'm not sure if you can do anything useful with that.

  • RELEASE - mouse was released after being dragged.

  • KEY - A keyboard key was pushed. You can get it from context->key().

  • KEYUP - A keyboard key was released. You can get it from context->key().

  • WHEEL - Mouse wheel (or other secondary manipulator) was moved. You can get the amount it was moved (in pixels) from context->wheel_dx() and wheel_dy().

  • MOVE - mouse is being dragged over window with no button pushed.

  • FIRST_MENU - You should use this as the first enumeration assigned to items in a Menu. If you call ctx->menu() and an item is picked the event is set to the picked item.

  • NO_EVENT - If you call ctx->menu() and either the user does not pick an item or they already picked an item from a different menu, then the event is set to this. You should not do anything in this case.

index is passed unchanged to the cb function. This can be used to select what part of a knob is being moved.

x and y (and z) indicate the initial position of the dragged object. Notice that it does not have to be the location you are drawing at.

void Knob::end_handle ( ViewerContext *  ctx  ) 

draw_handle() should call this after calling begin_handle() and drawing the selectable items. It is harmless to call this extra times.

void Knob::make_handle ( HandleContext  command,
ViewerContext *  ctx,
Handle *  cb,
int  index,
float  x,
float  y,
float  z = 0,
ViewerContext::Cursor  cursor = ViewerContext::kNoCursor 
)

Calls begin_handle(), draws a small square (using GL_POINTS), and calls end_handle(). The arguments are the same as for begin_handle().

If you don't want the square to be visible to the user you can call this only when ctx->event() is equal to PUSH.

You can also use this to create some special handles that do not use OpenGL hit detection:

  • ANYWHERE - A click anywhere in the window, or any keystroke not handled by another handle, calls this handle. You do not need to draw anything or call end_handle(). You will get PUSH and DRAG and RELEASE events with mouse coordinates rounded to nice values relative, similar to DISTANCE_WITH_SNAP. You will also get KEY events for any keys that the normal handles do not want.

  • ANYWHERE_MOUSEMOVES - Similar to ANYWHERE, but additionally moving the mouse anywhere in the window will cause MOVE events to be generated.

  • SELECTED_BY_THIS - This should only be called by a Handle in response to a PUSH event. It will cause this new handle to be added to the selected set if it is not in there already. This allows one handle to control the selection of several handles, for instance clicking on the line of a Bezier will select all the points in that line, this is done by having the line Handle function call this with every point. Nuke will clear other selected handles and toggle all of them on and off depending on the state of the shift key and the first one of these.

bool Knob::is_selected ( ViewerContext *  ctx,
Handle *  cb,
int  index 
)

Return true if the cb was flagged as a SELECTABLE one and it is currently selected by the user.

bool Knob::clear_selected ( ViewerContext *  ctx  ) 

Clear the selection list Return true if successful.

bool Knob::toggle_selected ( ViewerContext *  ctx,
Handle *  cb,
int  index 
)

Toggle the selection Return true if successful.

int Knob::selection_size ( ViewerContext *  ctx  ) 

Return the selection size

void Knob::new_undo ( const char *  name = 0  ) 

Same as new_undo(0). If this knob has not been recorded into the current Undo, start a new Undo and record the current state.

void Knob::extra_undo (  ) 

Make changes to this knob be part of the current Undo. Deprecated. You should not need to call this, Nuke merges undos for everything done by an Op::knob_changed() or other functions that should look like a single action to the user.

void Knob::new_undo ( const void *  widget  ) 

Start a new Undo and remember the current state in that Undo, if either:

  • this knob has not been recorded in the current Undo
  • widget is non-zero and different than the previous call

The intention was for widget to be the widget being manipulated, though you can also pass pointers to static variables that indicate the "class" of widget, for instance if you want a set of checkmarks to all act like a single Undo.

You can call repeatedly with widget == NULL and subsequent calls are ignored. This makes it convienent to stuff this call into any method that is going to change the value.

See also:
extra_undo

void Knob::new_nudge_undo (  )  [inline]

Call new_undo(widget) with a pointer to a constant that indicates a "nudge" modification, such as the numeric keypad keys. All adjacent nudge modifications for a knob are merged into a single undo.

void Knob::undo (  ) 

If possible this backs up to the last time new_undo() was called. However this may back up many other knobs to the same state, so only call this on one knob per panel!

See also:
redo, new_undo, new_nudge_undo

void Knob::redo (  ) 

If possible this goes forward and undoes an undo. However this may back up many other knobs to the same state, so only call this on one knob per panel!

See also:
undo, new_undo, new_nudge_undo

void Knob::changed (  )  [virtual]

This virtual function is called when the value of the knob changes. Subclasses can override this, they should not do anything very expensive (such as read a file) or Nuke will lock up! They must call the base class implementation, it calls UpdateWidgets(), sets the modified flag, and triggers the viewer to check to see if it needs to update, among other things.

void Knob::updateWidgets (  ) 

Sometimes (especially in subclasses) you know that only the widget has to redraw and that the knob's value did not change. In this case you can call this function instead of changed(), to avoid triggering unnecessary recalculation.

void Knob::asapUpdate (  ) 

See Op::asapUpdate(). Indicate the output of the Ops controlled by this node are dynamically changing. This causes the viewer to update right away and disables disk caching of viewer images.

You must make the hash() of the Op change. If you are altering the knob's value, then this is probably enough to make the hash change.

void Knob::asapUpdate ( const Box &  box,
int  direction = 0 
)

See Op::asapUpdate(). Indicate the output of the Ops controlled by this node are dynamically changing and that the indicated area of the viewer should be drawn first. This causes the viewer to update right away and disables disk caching of viewer images. The direction indicates which way to draw the box, zero indicates you don't care. This is used by paint strokes, setting the direction to the same way the paint brush is moving makes the best feedback.

void Knob::redraw (  ) 

Make any handles in the viewer redraw, such as to show highlighting or previews, without the overhead or setting modified flags that changed() does.

const OutputContext & Knob::uiContext (  )  const

Return the "user interface context" from the node this knob belongs to. This is best thought of as "what frame/view the user thinks the Node is at". In reality, a node may produce several ops at different frames/views/proxy settings, one of these settings is returned by this.

const Format & Knob::input_format (  )  const

Same as Op::input_format(). A store() method can use this to scale uv coordinates to pixels or to take into account pixel aspect when storing width/height pairs.

void Knob::store ( StoreType  type,
void *  pointer,
Hash &  hash,
const OutputContext &  context 
) [virtual]

Write over the passed location (which is in an Op) with the new data, and append that data to the Hash somehow. This is how data is stored into the pointed-to locations referred to by the knobs() function.

The context is used to figure out the current value from an animated knob, and to scale the stored values to the current proxy resolution. The hash should depend on these values.

If there is any problem storing the value you should call error() with a message to show the user. You should still put a legal value there and return the correct hash.

The base class does nothing.

void Knob::append ( Hash &  hash,
const OutputContext *  context 
) [virtual]

Append a representation of the current value() at the context to the hash. Nuke will use this to calculate the hash of any knob that does not have a pointer for the store() function but also does not have the NO_RERENDER flag on.

If the context is null, then you should instead append the entire animation of the knob to the hash. This is used to identify if any frame in a clip has changed.

The base class does nothing.

Referenced by DD::Image::LookupCurves::append().

int Knob::get_key_list ( std::set< int > &  keylist  )  const [virtual]

Turn on a flag in the bl array for each frame number between first and last that contains a key frame, and return the total number of keyframes. This is used to update the tick mark display in the Viewer frame slider. The base class returns zero.

virtual bool DD::Image::Knob::keyframesDisplayed (  )  const [inline, virtual]

Whether the viewer should display the tickmarks for me at the moment subclasses can override this to display tickmarks for invisible knobs

void Knob::error ( const char *  lpFormat,
  ... 
) [static]

Use these to report once-off warning or error messages produced by a knob. They'll only be displayed as message boxes, and won't be stored. The versions that take a knob parameter use parameters from that knob they're called on, such as the pop-up scheme from any associated op.

bool Knob::from_script ( const char *  v  )  [virtual]

Parse a string read from a saved script. The result should be a knob that is in exactly the same state as it was when to_script() was called to produce the string.

The return value is whether or not the value changed. If it did this must also call changed(). Note it should do this even if an error() is produced.

If any errors are encountered you should call error() to print a message.

Nuke provides a helper class Knob::String_List to split nested lists of words at spaces (this actually uses tcl to do the work), and the to_double() and to_bool() methods to turn words into values.

The default version produces an error. You don't need to implement this as long as not_default() is always false.

Reimplemented in DD::Image::ShapeKnob.

bool Knob::to_double ( const char *  expr,
double &  result 
)

from_script() can call this to convert a word into a double. This will run the Nuke expression evaluator so that math expressions typed in by the user will be handled. If there is any problem a message is printed with error() and false is returned. If true is returned then the second argument is set to the resulting double value.

If you wish to write doubles in to_script(), using << works acceptably.

bool Knob::to_int ( const char *  expr,
int &  result 
)

from_script() can call this to convert a word into an integer value. The argument can be any legal expression. If it is not an integer then int(floor(x)) is returned.

bool Knob::to_bool ( const char *  expr,
bool &  result 
)

from_script() can call this to convert a word into a boolean value. The argument can be any legal expression that evaluates to 0, non-zero, or the words "false" or "true".

const char * Knob::get_text ( const OutputContext *  = 0  )  const [virtual]

Return the null-terminated text that to_script(o, context, false) would write to the stream, or return null to indicate that this is not implemented.

The main purpose of this function is so a caller can avoid the overhead of creating a stringstream and extracting the result from there if they just want to copy the to_script value somewhere.

A caller can assume this is implemented for String_knob(). It is also implemented for Enumeration_knob and Bool_knob and most others that use keywords for their value, if a context is given or the knob is not animated.

The returned value is temporary and is only good until the next time this or any other knob is changed. However you are allowed to pass it once to a from_script() method on this or any knob.

The base class returns null. Notice that this means the base class to_script() always writes an empty string.

Referenced by DD::Image::ReadGeo::_validate(), DD::Image::Read::make_format(), DD::Image::WriteGeo::set_file_type_from_filename(), DD::Image::Write::set_file_type_from_filename(), and to_script().

void Knob::to_script ( std::ostream &  o,
const OutputContext *  context,
bool  quote 
) const [virtual]

Write the text that describes the state of the knob to a stream. The resulting text must be able to be passed to from_script() to restore the current value.

If context is null, then you should write a description of all the animation of the knob. If context is not null, you should write the a description of the value that is stored for the given context (this string, if passed to from_script(), would then produce a non-animated value for the knob).

For speed this writes directly to the output file, so you must do the quoting if necessary. quote indicates that you should modify the output with the necessary quoting characters and delimiters so that the text results in exactly one word in a space-separated tcl list (generally this means you should add curly braces around it). If quote is false then you should output the text in the form it would be after it is extracted from the list.

The helper class Knob::cstring will correctly quote a string or null so that it is returned unchanged to from_script() or so it can be put into a space-separated Knob::Script_List.

The default version prints the result of get_text(), using Knob::cstring if necessary to quote it.

Reimplemented in DD::Image::ShapeKnob.

References get_text().

void Knob::to_script_prefix ( std::ostream &  o  )  const [virtual]

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. Be sure to put a newline after the command. The default version writes nothing.

void Knob::to_script_userknob ( std::ostream &  o  )  const [virtual]

Write the arguments to an addUserKnob command that will create this knob. Nuke will already have written the ClassID() and the name() (the way these are written may change in future versions). This should write keyword+value pairs separated by spaces with a leading space, and use cstring to quote values.

The base class writes " l \a label t \a tooltip ". label is not written if it is the same as name(). tooltip is not written if it is blank.

bool Knob::not_default (  )  const [virtual]

Return true if the knob is not at it's default value. This is used to avoid writing knobs which are set to the default to saved scripts. The base class returns false always.

Member Data Documentation

void(* Knob::pMessageCallback)(const Knob *lpKnob, const OpMessage &lrMessage) ( const Knob *  lpKnob,
const OpMessage &  lrMessage 
) [static]

Callback function for internal use.

from_script() should call this to format an error message that is reported to the user. It should then leave the knob in a stable (ideally unchanged) and then return true/false depending on whether the value changed.


©2009 The Foundry Visionmongers, Ltd. All Rights Reserved.
www.thefoundry.co.uk