Inputting data

Abstract

Constant values, input editors, and drawers

You’ve learned how data flows through a composition (How events and data travel through a composition). But how does the data get into the composition in the first place?

There are two main ways. One is to pull in data from the world outside the composition — files on your computer, input devices such as a mouse or video camera, information communicated over a network, and so on. A good starting point to learn about this is to search the Node Library for nodes whose titles begin with Receive.

The other way to get data into a composition is to enter it yourself. This section explains how.

Editing data in a node’s input port

If an input port doesn’t have a data-and-event cable connected to it, then it has a constant value. Rather than being replaced with new data coming in from a cable, the port’s value remains the same as the composition runs.

For many data types, the constant value is displayed alongside the input port. You can double-click on the constant value to open an input editor and edit the value.

Different data types have different kinds of input editors. Some data types aren’t editable. Double-clicking on them doesn’t open an input editor. The only way to change their value is by connecting a cable.

You can close most input editors (keeping the edits) by clicking on the canvas or pressing . In input editors for Text data, since the key is taken, you can enter a linebreak with ⌥↵. You can cancel edits by pressing .

After you edit an input port’s data, the new data will take effect the next time the node executes. If there’s already a steady stream of events flowing through the node, like the Outline Image node below, the new data will naturally enter into the flow.

If events only rarely hit the node, like the Make Text Layer node below, then, in order to see the results of the new data, you’ll have to either restart the composition or fire an event into the node manually. To fire an event manually, right-click on one of the node’s input ports and select Fire Event.

If you edit an input port value on a node that has a trigger port, the new data will take affect immediately. You don’t have to fire an event into the node. For example, after you edit the Seconds input port of a Fire Periodically node, the node immediately adjusts the rate at which it fires.

Editing data in a published input port

Like an input port on a node, a published input port can have a constant value. (The exception is protocol published input ports, which are explained in Making compositions fit a mold with protocols.)

You can edit a published input port’s constant value by double-clicking on the port, which brings up an input editor.

If the published input port has a numerical data type, you can also edit the input editor’s range. Right-click on the published port and go to Edit Details…. Suggested Min and Suggested Max are the recommended lower and upper bounds of the data value. If both are set, then the input editor will have a slider, a text field, and up and down arrows. Otherwise, the input editor will only have a text field and up and down arrows. Suggested Step controls the step size of the up and down arrows.

If you’re running the composition as a standalone composition (not a subcomposition), after you edit a published input port’s data, the new data will immediately flow through any cables directly connected to the published input port — but no farther. This is a rare case in which data flows without an event.

For example, in the composition below, if you change the value of TextPosition from (0, 0) to (1, 1), the value of the Position port on Make Text Layer immediately changes to (1, 1). But the Make Text Layer node doesn’t execute and doesn’t affect any nodes downstream — so the text in the window remains at (0, 0) for the moment. The next time Fire Periodically fires an event, the event hits Make Text Layer, causes the node to execute with the new Position value, and travels onward along with the resulting data to Render Layers to Window — so the text in the window now appears at (1, 1).

To learn about constant values of published input ports in subcompositions, see this section.

Inputting lists

When an input port has a list data type, you can either input the list as a whole (by connecting a cable to the list port) or input each list item separately via the drawer attached to the port.

You can change the number of list items by dragging the drawer’s handle (bar along the bottom) up or down, or by right-clicking on the drawer and selecting Remove Input Port or Add Input Port.

Inputting dictionaries

The Calculate and Calculate List nodes each have a drawer attached to their dictionary input port. The keys of the drawer adjust automatically when you edit the Expression input port’s data. (You can’t resize this drawer like you can a list drawer.)

On other nodes, dictionary input ports don’t have drawers. Instead, you can connect a cable from the output of a Make Dictionary node.