=== NodeEditor anchor:interface_nodeEditor[] A node's controls can be viewed and edited in the *NodeEditor* tab. [NOTE] Internally all of the exposed parts of a node ( its label, its input/output slots, its tweakable controls ) are known as *plugs*. In this user guide we will make reference to both plugs and controls. + 'Plugs' will be used in the general case, and 'controls' when we are indicating plugs that expose their values for user modification via the NodeEditor interface. !!!SCREEN GRAB OF A FULL NODE EDITOR!!! The top bar of the editor displays information about the node itself; the "Node Name", the "Node Type", and an info icon. * The node name is used to identify the node throughout the application, and is drawn as a label in the NodeGraph. To change the name of a node, simply click in the "Node Name" text field and type. You should see the new name reflected in the NodeGraph and other editors once you press enter. * Next to the name the "Node Type" is shown. This helps identify what kind of node you have active, especially once nodes have their names changed the default (nodes are named based on the node type when created - e.g. create a new CustomAttributes node and it will be called "CustomAttributes"). * On the far right of the top bar is the "i" icon. Hovering the mouse pointer over this will pop-up a description of the node type, detailing it's purpose and any particular usage nodes. .The "top-bar" section of the NodeEditor showing (left to right) the node name, node type, and info pop-up. image::images/chapters/interface/interface_nodeEditor_figAA.png[align="center"] Following the top-bar are the node specific controls themselves, organised into tabs. A wide range of control types are supported by the NodeEditor, with most having custom UIs designed to best accommodate the type specific input data. Available controls types include: * Integers * Floats * Vectors (with either 2 or 3 components, float or int data) * Colors (with or without an alpha component) * Booleans * Enums (offering drop-down lists of choices) * Strings * Paths (both paths to files on disk, and paths to locations in the Gaffer scene) In addition to these standard controls some nodes implement their own custom interfaces, such as the paths list used by the PathFilter node which has + and - buttons for adding and removing entries from the list. .An example node with a range of controls, plus an example of a custom interface (PathFilter) image::images/autoGenerated_target/interface_nodeEditor_figBA.png[align="center"] ==== Manipulating controls As interacting with node controls is a key part of working with Gaffer, extra effort has been made to make this process easy and effective. A range of helpful short-cuts and behaviours are available, including: ===== Up/Down arrows Numerical fields (Integer and Float controls, individual components of Colors and Vectors) provide a special interaction method to allow quick but precise value tweaking. * Whenever you are editing a numeric field, you are able to use the `up-arrow` and `down-arrow` to increment and decrement the value. The amount to which the value is increased or decreased (the precision) is determined by the location of the cursor. * e.g. with a starting value of `4.25`, if the cursor was to the immediate left of the "2" pressing `up-arrow` would increment the value by `0.1`, resulting in a value of `4.35`. * Then by moving the cursor left (using `left-arrow`) to be adjacent to the "4" and pressing `down-arrow` 'twice' the value would be decremented by `1.0` and then again by another `1.0`. Our end result would be `2.35`. ===== Virtual sliders For broader, more free-form tweaking of numerical values Gaffer implements virtual sliders that can be activated by holding down `Ctrl` then `left-click-dragging` in numerical entry boxes. * Scrubbing left will decrease the value, and right will increase the value. * You can scrub backwards and forwards as much as you like - the virtual slider will last as long as `Ctrl` is kept pressed down. ===== Ganging It is often useful to be able to tweak a Color or Vector control as if it was a single Float control. For example, the Grade node has a Gamma control which will most commonly be applied uniformly to the r,g, and b channels. To avoid users in these cases being required to enter the same value in each field of the Color/Vector, Gaffer allows for Colors and Vectors to be "ganged". This means that the first field will be configured to drive both the second and third field of the Color/Vector selected for ganging. To gang a control, simply `right-click` on its label in the NodeEditor and select "Gang" from the drop down menu. ===== Drag and drop Drag and drop can be used to share values between controls - either two controls on the same node, or on two separate nodes. There are two options available; connect or copy: * To start click and drag on the label of the control ** `left-click-drag` initiates a drag for connecting controls to other controls. Once connected any change to the first control will be reflected in the second control. ** `shift-left-click-drag` and `middle-click-drag` both initiate a drag for transferring values between controls. In this case, when you drop the drag the value is set on the destination plug, but no active link is created. This makes it useful for one off transfers. *** This one time drop also works for values picked in the 2D Viewer - so controls can be set to match colours sampled from renders or source images. [NOTE] For dragging and dropping controls between two different nodes, you will need to have more than one NodeEditor tab available in the current layout, and will need to pin at least one of them to keep the desired node(s) active. See the xref:interface_layouts[layouts section] for more details. ===== Colour picker Clicking on any colour swatch in the NodeEditor interface will pop-up a floating colour picker dialogue. This can be used to perform a range of subtle colour selections. !!!More to come after ColorChooser widget has overhaul!!! .The colour picker interface image::images/autoGenerated_target/interface_nodeEditor_figCA.png[align="center"] ===== Tab completion Path fields (both file paths and scene paths) support Tab-completion to speed up the process of typing in long paths. To make use of Tab-completion, simply start typing the first few characters of the path you want, then hit the `Tab` key. If the system can find a single matching result (e.g. a file/directory or an object/group) it will automatically enter the rest of its name into the field. For example: * I wish to load a scene cache into a SceneReader node. The cache is on disk at the path: ------------------------------------ /local/caches/myCache.scc ------------------------------------ * And here are the contents of my (very simple) file system ------------------------------------ └── local ├── blank.txt └── caches ├── myCache.scc └── myOtherThing.foo ------------------------------------ * In this case I can type the following to get quickly to file I'm after ** `/`, `l`, `Tab` *** which will return: `/local/` ** then `c`, `Tab` *** which will return: `/local/caches/` ** then `m`, `y`, `C`, `Tab` *** which will return: `/local/caches/myCache.scc` ===== Enable/disable toggles Some controls have an additional enable/disable toggle. Primarily, they are the ones that set some attribute or option, and the toggle can be used to disable the control - meaning that it has no affect on that particular attribute/option. The motivation for the toggles is to allow individual nodes to potential modify a more than one attribute or option, but without having to always modify them all. For example, a RenderManAttributes node could possibly change the shadingRate, maxSpecularDepth, displacementBound etc but you may wish to modify only the shadingRate for some specific object. To achieve this, you could disable all the other controls, activating only the shadingRate modifier control. .A range of enabled and disabled controls on the RenderManAttributes node image::images/autoGenerated_target/interface_nodeEditor_figDA.png[align="center"] ==== User tab The user tab allows for custom controls to be added to nodes. These controls can be useful for expressions or as direct connections to other nodes/controls. New controls can be given custom names then manipulated using all the same methods as described above.