Working on the canvas

Abstract

Creating and manipulating nodes and cables

Putting a node on the canvas

The node library isn’t just for reading about nodes, but for incorporating them into your compositions. Once you have found a node of interest, you may create your own copy by dragging it straight from the node library onto your canvas, or by double-clicking the node listing within the library.

Not a mouse person? Navigating the library by arrow key and pressing to copy the node to your canvas works just as well.

You may copy nodes from the library individually, or select any number or combination of nodes from the library and add them all to your canvas simultaneously with a single keypress or mouse drag — whatever best suits your work style.

You can add certain commonly used nodes — such as Share Value, Hold Value, and Allow Changes — to your composition without a trip to the node library. Just right-click on the canvas and select an item from the Insert Node menu.

Drawing cables to create a composition

You can create a cable by dragging from a node’s output port to a compatible input port or from a node’s output port to a compatible input port.

Compatible ports are those that output and accept matching or convertible types of data. Compatible ports are highlighted as you drag your cable, so you know where it’s possible to complete the connection.

If you complete your cable connection between two ports whose data types are not identical, but that are convertible using an available type converter (e.g., vuo.math.round for rounding real numbers to integers), that type converter will be automatically inserted when you complete the connection.

Sometimes existing cables may also be re-routed by dragging (or yanking) them away from the input port to which they are currently connected. It is possible to yank the cable from anywhere within its yank zone. You can tell where a cable’s yank zone begins by hovering your cursor near the cable. The yank zone is the section of the cable with the extra-bright highlighting. If no yank zone is highlighted, you’ll need to delete and add back the cable.

Adding a comment

You can add a comment to a composition by using the Edit > Insert Comment menu option, or by right-clicking on the canvas and selecting Insert Comment from the menu.

When you create a comment, you will be in editing mode, and can start typing the comment’s text. Text inside a comment uses Markdown formatting. This is especially useful if you want to include a link, or make the text larger by using headings. To start a new line, finish the line with two or more trailing spaces, then press ⌥↵ to continue on a new line. To start a new paragraph, add a blank line after the previous line of text, ⌥↵⌥↵.

To end editing, either press or click outside the comment area. To reenter editing mode, double click within the comment area or right-click on the comment and pick Edit… from the menu.

To change the color of a comment, right-click on the comment and pick Tint from the menu.

To move a comment, hover over the top edge of the comment and drag the handle that appears. To resize a comment, hover over the bottom-right corner of the comment and drag the handle that appears.

To select a comment, click on the comment’s text, click near the top edge of the comment, or rubberband-select the top edge of the comment. (Clicking or rubberbanding the part of the comment below the text does not select the comment, so when you place nodes in that area you can easily rubberband-select the nodes.)

Copying and pasting nodes, cables, and comments

You can select one or more nodes or comments, and copy or cut them using the Edit > Copy and/or Edit > Cut menu options, or their associated keyboard shortcuts. Any cables or type converters connecting the copied nodes will automatically be copied along with them.

You can paste your copied components into the same composition, a different composition, or a text editor, using the Edit > Paste menu option or its keyboard shortcut.

Select one or more nodes and drag them while holding down to duplicate and drag your selection within the same composition. Press during the drag to cancel the duplication.

Deleting nodes, cables, and comments

Delete one or more nodes, cables, and/or comments from your canvas by selecting them and either pressing or right-clicking one of your selections and selecting Delete from its context menu.

When you delete a node, any cables connected to that node are also deleted. A cable with a yank zone may also be deleted by yanking it from its connected input port and releasing it.

Any type converters that were helping to bridge non-identical port types are automatically deleted when their incoming cables are deleted.

Rearranging nodes, cables, and comments

You can move nodes and comments within your canvas by selecting one or more of them and either dragging them or pressing the arrow keys on your keyboard.

Hold down while pressing an arrow key to move the nodes even faster.

Replacing nodes

Sometimes after adding a node to a composition, you might decide to replace it with something a little different. For example, you might like to replace a Crop Image node with a Resize Image node. If there are already cables hooked up to the original node, it can be inconvenient to disconnect each one and connect it to the new node. Fortunately, there’s an alternative.

Right-click on the original node and go to the Change To menu. Here, you can select from a list of similar nodes that can be substituted in without breaking any cable connections.

Editing node settings

You can change a node’s title (displayed at the top of the node) by double-clicking or hovering over the title and pressing , then entering the new title in the node title editor that pops up. You may save or dismiss your changes by pressing or , respectively, just as you would using a port’s input editor. You can also select one or more nodes from your canvas and press to edit the node titles for each of the selected nodes in sequence. If you delete the title and don’t enter a new title, the node will default to its original title.

You can change a node’s tint color by right-clicking on the node, selecting Tint from its context menu, and selecting your color of choice. Tint colors can be a useful tool in organizing your composition. For example, they can be used to visually associate nodes working together to perform a particular task.

Editing port values and settings

You can change the constant value for an input port by double-clicking the port, then entering the new value into the input editor that pops up. (Or you can open the input editor by hovering the cursor over the port and pressing .) When the input editor is open, press to accept the new value or to cancel.

Input editors take on various forms depending on the data type of the specific input being edited — they may present as a text field, a menu, or a widget (such as color picker wheel), for example.

Some ports take lists as input. These ports have special attached drawers containing 0 or more input ports whose values will make up the contents of the list. Drawers contain two input ports by default, but may be resized to include more or fewer ports by dragging the drag handle.

You can change how a trigger port should behave when it’s firing events faster than downstream nodes can process them. Do this by right-clicking on the port, selecting Set Event Throttling from its context menu, and selecting either Enqueue Events or Drop Events.

Finding nodes on the canvas

Using Edit > Find > Find…, you can search the canvas for nodes matching a search phrase.

Type of search Example search phrase Example search results
Node title blur image rad Blur Image Radially
Node class name vuo.mouse Receive Mouse Moves (vuo.mouse.move2),
Receive Mouse Buttons (vuo.mouse.button2),
and others
Port name month Get Date-Time Values,
Make Date-Time,
and others
Subcompositions .vuo Nodes that are subcompositions
Community nodes .vuonode, .fs, or .c Nodes installed as .vuonode, .fs, or .c files
Deprecated nodes deprecated Nodes that are deprecated

Viewing a composition

If your composition is too large to be displayed within a single viewport, you can use the Zoom buttons within the composition window’s menubar, or the View > Actual Size / Zoom In / Zoom Out / Zoom to Fit menu options, or a pinch gesture on your trackpad, to adjust your view. You can use the scrollbars to scroll horizontally or vertically within the composition. Alternatively, if you have no nodes or cables selected, you can scroll by pressing the arrow keys on your keyboard. You can also grab the workspace by holding down the spacebar while dragging.

Hold down while pressing an arrow key to scroll even faster.

Publishing ports

A composition’s published ports are displayed in sidebars, which you can show and hide using the menu View > Show/Hide Published Ports.

You can publish any input or output port in a composition. Do this by right-clicking on the port and selecting Publish Port from the context menu. Alternatively, drag a cable from the port to the Publish well that appears in the sidebar when you start dragging. You can unpublish the port by right-clicking on the port again and selecting Delete Port.

You can create a published port without immediately connecting it to a port inside the composition by clicking on the New Port button in the sidebar. This pops up a menu for you to choose the data type of the published port. Once the published port has been created, you can drag a cable from it and connect the cable to any compatible port within the composition.

In the sidebars, you can rename a published port by double-clicking on the name or by right-clicking on the published port and selecting Rename Port…. You can reorder published ports (except those that are part of a protocol) by dragging the name of a published port up or down in the sidebar.

For published ports with numerical data types (integers, real numbers, 2D points, 3D points, and 4D points), you can modify the behavior of their input editors by right-clicking on the published port in the sidebar and selecting Edit Details…. The Suggested Min and Suggested Max determine the range of values provided by the input editor’s slider or spinbox (arrow buttons). The Suggested Step controls the amount by which each click on a spinbox button increments or decrements the value.

Using a protocol for published ports

To create a composition with a predetermined set of published ports defined by a protocol, go to the File menu, select New Composition from Template, and select the protocol you want. Typically, a protocol is used when running a Vuo composition inside another application, such as a VJ or video postproduction app. That application should instruct you about the protocol to select.

The published ports in a protocol appear in a tinted area of the published port sidebars, with the protocol name at the top. You can’t rename or delete these published ports. However, you can add other published ports to the composition and rename or delete them as usual.