How events travel through a node

Abstract

Cables, input ports (sometimes with walls, doors, and port actions), and output ports (sometimes trigger ports)

An event can come into a node through cables connected to one or more of its input ports. When an event reaches the node’s input ports, the node executes, and it may or may not send the event through its output ports.

Input ports

An input port is the location on the left side of the node where you can enter data directly, connect a data-and-event cable, or connect an event-only cable. When an event arrives at an input port, it causes the node to execute and perform its function based on the data present at the node’s input ports.

Event walls and doors

Some nodes, like the ones shown below, have input ports that block an event. This means the node will execute, but the event associated with that data won’t travel through any output ports. Event blocking is useful when you want part of your composition to execute in response to events from one trigger port but not events from another trigger port, or when you’re creating a feedback loop.

Ports that always block events have a solid semi-circle (like the URL port above) or a solid chevron (like the Start port above). This is called an event wall. The node must receive an event from another port without an event wall for the results of the node’s execution to be available to other nodes.

The event wall is visually placed inside the node to indicate that the event gets blocked inside the node (as it executes) — rather than getting blocked before it reaches the node.

Ports that sometimes block events have a broken semi-circle (like the Which port above) or a broken chevron (like the Time port above). This is called an event door. Event doors are useful when you want to take events from a trigger port and filter some of them out or route them to different parts of the composition. For example, in the Select Output node, the value at the Which port will determine whether the data-and-event coming into the In port will be transmitted to the Option 1 port or the Option 2 port.

The manual section How events travel through a composition has more information on how events move through a composition.

Port actions

Some input ports cause the node to do something special when they receive an event. In the Count within Range node shown below, the Increment, Decrement, and Set Count ports each uniquely affect the count stored by the node — upon receiving an event, they increment the count, decrement the count, or change the count to a specific number. Likewise, in the Display Console Window node, the Write Line input port does something special when it receives an event — it writes a line of text to the console window. Each of these ports has a port action.

If an input port has a port action, then the node does something different when that input port receives an event than it does when any other input port receives an event. What counts as something different? Either the node outputs different data (immediately or later) or the node affects the world outside the composition differently.

Looking again at the Count within Range node, you can see that the node has some input ports with port actions and some without. For the ports without port actions — Minimum, Maximum, and Wrap Mode — the node will output the same number regardless of whether the event causing the node to execute has hit one of these ports. The node uses the data from these ports and doesn’t care if they received an event. For each of the ports with port actions, however, it makes a difference whether the event has hit the port. The Increment port, for example, only affects the count if the event came in through that input port.

Rather than affecting the node’s output data, as in the Count within Range node, the Display Console Window node’s port action affects the world outside the composition. When the Write Line input port receives an event, it doesn’t affect the data coming out of the node’s output ports. Rather, it affects what you see in the console window.

You can recognize an input port with a port action by the little triangle to the right of the port name. In Vuo, the triangle shape symbolizes events. The little triangle for the port action reminds you that this port does something unique when it receives an event.

Output ports

When an event executes a node, the event can travel to downstream nodes using the output ports. Like input ports, output ports can be data-and-event or event-only.

Trigger ports

Although trigger ports can create events, they never transmit events that came into the node through an input port (hence the thick line to the left of each trigger port — an event wall), nor do they cause any other output ports to emit events.