8.5. How events travel through a subcomposition

8.5.1. Events into a subcomposition

When an event hits any input port of a subcomposition node, the event travels into the subcomposition through all of its published input ports.

To illustrate, here’s a composition that uses a subcomposition node called Connect Recent Points to draw a series of connected line segments behind the mouse cursor as it moves. Below that is the Connect Recent Points subcomposition.

When an event hits the Add Point input port of the Connect Recent Points node (in the first composition above), it travels into the subcomposition (second composition above) through both of the subcomposition’s published input ports, Add Point and Max Recent Points.

If you were to edit the Connect Recent Points node’s Max Recent Points port’s constant value, the Enqueue node’s Max Item Count port’s value would immediately change, but the Enqueue node wouldn’t execute. The next event into the Connect Recent Points node’s Add Point port would cause the Enqueue node to execute and, thus, the new Max Item Count port value to take effect.

Here’s a modification of the first composition above that allows the user to toggle between a short tail and a long tail by pressing any key.

If the user stops moving the mouse and repeatedly presses a key to change the number of recent points, something unintended happens: each time the user toggles back to the short tail, the tail gets even shorter than it was before. After several keypresses, the tail disappears completely. Why?

When the event fired from the Receive Keyboard Buttons node hits the Connect Recent Points node’s Max Recent Points port, it goes into the subcomposition through both of the subcomposition’s published input ports. Inside the subcomposition, the event hits both the Max Item Count and Add Item port of the Enqueue node. This means that not only is the maximum number of points altered, but the most recently added point is added to the queue again — bumping the least recent point out of the queue. Since changing the maximum number of points has the unintended side effect of deleting the oldest point in the tail, the tail gets shorter and shorter.

To avoid this problem, you can modify the subcomposition to block the event into the Enqueue node’s Add Item port when it carries the same point twice in a row. The modified subcomposition below accomplishes this with an Allow Changes node.

8.5.2. Events out of a subcomposition

If an event reaches the published output port of a subcomposition, it travels out of the corresponding output port of the subcomposition node.

If an event into a subcomposition node reaches multiple published output ports of the subcomposition, it travels out of all of the subcomposition node’s output ports simultaneously. For example, in the subcomposition below, even though the Calculate nodes can execute concurrently and may not output their values at exactly the same time, the Convert Cartesian To Polar subcomposition node always outputs the event from its R and Theta ports simultaneously.

If an event that comes in through a subcomposition’s published input ports reaches at least one of the subcomposition’s published output ports, then the event comes out of all of the subcomposition node’s output ports.

If an event that comes in through a subcomposition’s published input ports doesn’t reach any of the subcomposition’s published output ports (because of wall or door ports within the subcomposition), then the event doesn’t come of out any of the subcomposition node’s output ports. The subcomposition node blocks the event.

The refresh port is an exception. When an event hits the subcomposition node’s refresh port, the event always comes out of all of the subcomposition node’s output ports.

A subcomposition can fire events, as demonstrated below. The Fire At Tempo subcomposition node is set to fire at a rate of 120 beats per minute.

8.5.3. Constant input port values

A variation on the previous example demonstrates an important point about how events flow into and through a subcomposition.

In the composition above, when the event from Fire on Start hits the Fire At Tempo subcomposition node, the event travels through the Convert Beats Per Minute to Seconds node and on to the Fire Periodically node, changing that node’s firing rate to 120 times per minute. But if you edit the constant value of the Fire At Tempo node’s Beats Per Minute input port, the firing rate doesn’t change. Why?

When you edit the Fire At Tempo node’s Beats Per Minute port’s value, the Convert Beats Per Minute to Seconds node’s Beats per Minute port’s value immediately changes. But there’s no event to make the Convert Beats Per Minute to Seconds node execute and carry its output data to the Fire Periodically node. For the new tempo to take effect after you’ve edited the input port value, you have to manually fire an event from Fire on Start.