Nodes

Nodes are the main component of the Data Processing area in Quill. They are used to process data between an application and the GUI. The Source Node and Global Source Node are the only entry points data entering and exiting the UI, using the data api.

Nodes have four main parts:

  1. Top Component

    Some node types have a top component, which may be a Template Reference, an identifing name, etc.

  2. Node Options

    Control major functional differences of a node's behavior.

  3. User IO

    User created inputs and outputs.

  4. System IO

    Core inputs and outputs.

Global Source#

Global Source Node

Global Source nodes access a single dataset based on the Source Name option. Multiple Global Source nodes that reference the same Source Name will all interact with the same data, regardless of which template or scene they may be in.

You can add outputs using the New Field button. These outputs are accessible using the Data API.

inkd main_d = ink_global_source(ink, I_main);
inkd_charp(main_d, I_user_field, "Hello World");

Source#

Source Node

The source node is similar to the Global Source node in that it provides an access point for data to flow in and out of the UI. It differs however in that a new data set is created for each instance of the containing template. And when the instance the source node is in is removed, the data set is also destroyed. Refer to the Data Events API for information on how to handle source nodes being created and destroyed.

We recommend you use Global Source nodes over this node when you don't need per-instance data sets.

Data#

Data Node

Data nodes allow you to construct list data in Quill. List items can be created and edited from the Edit Data button.

Scene#

Scene Node

Scene nodes allow you to create new scenes on the scene stack.

Options#

  • Focus Exclusive

    When checked, the scene created by this node will disable focus on all scenes below it on the stack.

  • Captures Focus

    When checked, the scene created by this node will focus any child view that has Request Default Focus when the scene is created.

  • Exclusive

    When checked, all scenes below this one won't be drawn or receive events.

User IO#

Inputs and outputs are created to match the referenced template's inputs and outputs.

Inputs and Outputs#

  • hide

    When triggered, any scene created by this node will be removed from the scene stack.

  • show

    When triggered, this node will create a new scene. Triggering again while a scene is already created by this node will not create another scene.

  • visible

    A boolean value that is true if this node has a currently created scene on the stack. It supports backflow which can cause the scene to be created or destroyed.

Scene Stack#

Scene Stack Node

back will destroy which ever scene is currently on the top of the scene stack. This works regardless of who triggers it and where.

removeSelf will remove the scene that this template is the root of. So for example if you have a scene that instantiates a template named "Options Screen", the scene stack node would only close scene if it was in the "Options Screen" template.

Format#

Allows you to combine text, numbers, and integers into a single formatted text output. Node inputs added using the New Variable button can be substituted in the Template field using double curly brackets:

Hello {{user_input}}!

Selector#

Selector Node

The Selector Node is used to add "selected" state tracking to a list of data. Each item in the connected data have access the following special fields:

  • selected (Boolean)

    Keeps track of which item(s) in the list of data are selected.

  • selectSingle (Impulse)

    When this impulse is set, the selector node first sets selected to False for all other items in the list, then sets it to True for this item.

  • unselect (Impulse)

    Sets all selected to False for all items in the list.

  • unselectAll (Impulse)

Example

See the Selector Node Example for a step by step walk through on how to use this node.

Inputs#

  • list (List)

    Incoming list of data to add state tracking to.

  • onSelect (Boolean)

    This impulse will be set when one or more item in the list changes selected state, or if an item requests to be selected with selectSingle (even if it results in no state change.)

Outputs#

  • all (List)

    A list of data containing all items from the input list regardless of selected state.

  • selected (List)

    A list of data containing only items from the input list that have a selected member with a truthy value.

  • unselected (List)

    A list of data containing only items from the input list that do not have a selected member, or do but with a falsy value.

  • selectNext (Impulse)

    When set, the item after the last-most selected item is selected, unselecting all other items. If there is no selection, or the the last item is selected, the first item in the list will be selected.

  • selectPrevious (Impulse)

    Has the same behavior as selectNext except in reverse order. If there is no selection, the last item will be selected.

  • unselectAll (Impulse)

    Sets the selected field of each item to False.

Slice#

Slice Node

The Slice Node allows you to create a subset of list. The output list will be all items in the input list within the range of from to to. Ranges are 1 based and inclusive. For example:

from: 2
to: 3
[a, b, c, d] => [b, c]

Note

Like all nodes that operate on lists of data, all items in the new output list are only references to the items in the input list. No data is duplicated. Changes to an item in the created output list will exist in the input list as well.

Inputs#

Outputs#

Find#

Find Node

Used to find data within a list. Inputs, query in the illustration on the right, are the values to match on while output values will be set to the list entry members for the first matching entry.

In this example the list type expects two members, "query" and "found", on each item in the list.

Filter#

Filter Node

The Filter Node looks at each item in the input list and checks for a field with the name specified in the node's Filter option. If that field has a value equal to the equal_to input, the item is put into the filtered output list.

If equal_to is a Boolean type (default), the value of the field being filtered by is checked for truthiness instead of if the values are exactly equal (which requires that they be the same type).

Sort#

Sort Node

The Sort Node filters the list input based on each item's field value where the field's name matches Field.

Extract#

Extract Node

The Extract Node is used to access individual fields on a single item in a list. Index is used to specify which item in list to access. 1 being the first item, 2 being the second and so on. The Index value is clamped to the list's length, so if you ask for the 7th item but there are only 5 it will give you the 5th item.

Billboard Set#

Billboard Set Node

The top component of a Billboard Set node is its name. Multiple Billboard Set nodes across any number of templates have the same data set if they have the same name. When add is true, the value of identifier is added to the data set. contains is true if the identifier is currently in the data set, and total if there are any values period in the data set.

Billboard Sets are incredibly useful for sharing information about state across a UI.

Focus Navigation#

Focus Navigation Node

Triggering the impulse causes the focus system to navigate in the specified direction. Navigation events generated by this node do not get intercepted by event filters.

Event Filter#

Event Filter Node

Allows you to create event filters separate from in a view. The onEvent output may only be connected to a On Event property.

Text Event Filter#

Text Event Filter Node

When the onEvent output is connected to an On Event property, any text events not handled by event filters specified on the view are matched against this nodes options. If the event matches impulse is fired, otherwise unhandled is fired with the event information.

Text Edit#

Text Edit Node

Inputs#

Outputs#

  • cursor (Integer)

    Current index of the cursor. 0 is before the first glyph, 1 is before the second glyph etc. A value of -1 indicates that the text is not currently being edited by the user.

  • event (Impulse)

    Feeds events directly to the text widget. Only useful for impulses created by Simulate Text Event and Simulate Action Event nodes, or the impulses on the event filter nodes.

  • selection_end (Integer) Same indexing rules as cursor.

  • selection_start (Integer) Same indexing rules as cursor.

Simulate Text Event#

Simulate Text Event Node

When simulate's output (on the right side) is triggered, the impulse will be passed on with the value text associated with it with the INK_TEXT_INPUT key state.

If Send To Focused is true, then the impulse is also sent to the focused view just the same as though the user had typed the text value on a keyboard (except no UP or DOWN key states are sent, only INSERT.)

Simulate Action Event#

Simulate Action Event Node

When simulate's output (on the right side) is triggered, simulates's input will fire twice with the associated KEY_DOWN and KEY_UP key states with the specified Action.

Feedback#

Feedback Node

Connect the feedback output to a Feedback property. The other outputs will relate to various state information of the connected view.

Layout Result#

Layout Result Node

width and height will be the measured size of the referenced view.

Concat#

Concatenates list A and list B into a single list.

Map#

Uses a Processing Template to operate on each item in a list. When Pass Data Through is set, the input's type (on the left side of the map node) will include all the members of the output's type, in addition to the referenced template's inputs.

Overrides, added using the "New Override" button, allow you to set a single value that is used for each item in the list.

Call#

A call node instantiates a single instance of a processing template and provide inputs and outputs that match the referenced template's inputs and outputs. Call nodes are useful for encapsulating complex node collections to re-use in multiple locations.

Discard#

Discard Node

While the discard input is true, the template instance is hidden from its containing list. For example if the template is being used as an inline list template, you can use this node to filter out list entries.

Lua#

Refer to the Lua Scripting section for behavior information.

Gif Animator#

Gif Animator Node

Takes a gif image and animates it over time, outputting the current frame which may then be connected to an image property. Triggering start causes the animation to begin running starting at the first frame. Triggering stop halts the animation immediately and reverts the image output to the gif's first frame. If the input image is not a gif with multiple frames, it simply passes the image through ignoring animations.

Backflow Transaction#

Backflow Transaction Node

When a value is backflowed to editing, it doesn't automatically backflow on input. Instead, the value is stored and if commit is triggered it is backflowed on input. If revert is triggered the editing value is discarded and set to the value of input.

modified will be true once any value is backflowed on editing, and won't be false until either commit or revert is triggered. While modified is true, any change to the input value is not passed on to editing.

Change Trigger#

Change Trigger Node

When the input value changes, changed triggers.

Impulse Delay#

Impulse Delay Node

When the output impulse (on the right side) is triggered, after delay seconds the input impulse will fire, unless cancel is triggered.

When Impulse Restarts is true, the delay timer is reset if the output impulse is triggered again while counting down.

Impulse Gate#

Impulse Gate Node

Passes an impulse through right to left if allow (Boolean) is true.

Trigger Gate#

Trigger Gate Node

Passes an trigger through left to right if allow (Boolean) is true.

Toggle#

Toggle Node

When impulse is triggered input's boolean value is reversed.

Boolean And#

Boolean And Node

The AND output is true when both inputs are true.

Boolean Or#

Boolean Or Node

The OR output is true when one of its inputs are true.

Boolean Not#

Boolean Not Node

The NOT output is true when the input is false.

Switch#

Switch Node

When switch is true, if_true is assigned to out, otherwise if_false's value is assigned.

Number Parser#

Number Parser Node

Converts between a number and a text value. The editing output is typically connected to an editable text property.

Number Math#

Performs a math operation on two numbers.

Integer Math#

Performs a math operation on two integers.

Dimension Math#

Performs a math operation on two dimensions.

Number Dimension#

Converts a number to a dimension.

Integer Dimension#

Converts an integer to a dimension.