A Tinderbox document has a number of ways to change attribute values. First it is useful to draw a distinction between the following:
- a literal value. This is the actual stored value of an attribute and as seen when displayed in contexts like a note's Displayed Attributes table.
- an evaluated value based on action code. Here it is code that is stored and then evaluated when applied so as to render a literal (above) stored value.
Attribute value changes can happen in various contexts:
- via action code (also allows literal value input)
- container-based:
- OnAdd action
- OnRemove
- Agent action.
- selection-based (note: selected items do not need to be in the same container):
- Stamp.
- container-based:
- via literal value of an attribute:
- selection-based (note: selected items do not need to be in the same container):
- Quickstamp.
- single item only:
- Get Info/attributes.
- Displayed Attributes.
- selection-based (note: selected items do not need to be in the same container):
OnAdd
This an action applied once to each note that is added to, or created in, a container note. The OnAdd action also takes effect when the note containing the on-add code is converted into a container: that is, when another note (or notes) is dragged onto it, creating new child notes. In the latter case the OnAdd is applied to the newly added/created note after it has been moved in situ; this is important so code evaluating things like the parent note's title are resolved correctly.
If a selection of multiple notes are moved into a container, the same action is run once on each discrete note. Removing a note from a container does not trigger this action but see the OnRemove action below. Map adornments also have an OnAdd that is run when note(s) are moved onto an adornment.
The OnAdd action is stored in a note's $OnAdd attribute. The action can be manually set via the Action Inspector's Action tab, Get Info's attributes/General tab, or by displaying $OnAdd as a displayed attribute. Otherwise, the attribute can be set via any action code method, such as stamps or quickstamp.
OnRemove
The action is the mirror opposite of OnAdd and is an action applied once to each note that is removed from, or deleted from, a container. Map adornments also have an OnRemove action.
Agents also have an OnRemove action but note that it is applied to an alias of a note, so pay attention if altering intrinsic attributes.
Note: As this action is a much more recent feature than OnAdd, older articles & tutorials on actions my (now) incorrectly state that the is no remove action.
The OnRemove action is stored in a note's $OnRemove attribute. The action can be manually set via the Action Inspector's Remove tab, Get Info's attributes/General tab, or by displaying $OnRemove as a displayed attribute. Otherwise, the attribute can be set via any action code method, such as stamps or quickstamp.
OnJoin
This action is evaluated when a note is first added to a composite. If an existing composite note is touched by the drag and it has $OnJoin code, it is run upon the newly joined note.
OnVisit
The $OnVisit action is primarily for Storyspace compatibility but may be used as an 'Upon Selection' event trigger.
Agent action
Agents have no OnAdd action, but instead an agent 'action' and this also functions slightly differently. The agent action is run on each discrete child alias in an agent, but is run every cycle of the agent update.
The agent action is stored in a note's $AgentAction attribute. The action can be manually set via the Action Inspector's Action tab, the AgentAction box of Get Info's agent1 tab Get Info's attributes/Agent tab, or by displaying $AgentAction as a Displayed Attributes. Otherwise, the attribute can be set via any action code method, such as stamps or quickstamp.
Note: although an agent can ostensibly have an $OnAdd attribute value, it is never used. If a selection includes both notes and agents and the Action Inspector's Action tab has code added, Tinderbox will apply the code to $OnAdd or $AgentAction as appropriate.
Stamp
A stamp is one or more complete action code expressions (i.e. complete actions) stored for ad hoc use. Stamps are created and saved via the Document Inspector's Stamps. Once created, a stamp can be applied from this Inspector, by clicking the stamp's name in the Stamps menu, or can be called via action code. All the stamps for a document are stored in the document's TBX file
When used a stamp is applied once only to each selected item. This can be a useful alternative to an agent if the code is needed only occasionally. By applying a stamp to an alias inside an agent, the stamp can be used to simulate/test a possible agent action whilst acting on a single item.
Quickstamp
A Quickstamp is a fast method to (re-)set the value once for a single attribute for every note currently selected. Unlike the methods above, Quickstamp can only change the literal value of an attribute, i.e. the input cannot be action code but must be the actual final value itself. Also, unlike a stamp, the applied value is not saved, e.g. for later re-use, and cannot act on more than one selected attribute at a time. Quickstamp can only be used via the Properties Inspector's Quickstamp tab.
One small exception to the literal value rule in Quickstamp is that if the selected attribute is Date-type, date designators are evaluated when entered (i.e. 'now' will become a date/time string in the Quickstamp value input box when return is entered, the latter string then being applied when the Apply button is pressed. However, this is a niche exception to the general fact that Quickstamp is intended for inserting literal values.
Get Info/attributes & Displayed Attributes
These offer different UI routes to the same interaction by changing the literal value of a single attribute in a single selected item. In each case the user selects the desired attribute and manually edits the actual value. UI: Get Info/attributes, Displayed Attributes.
Unlike Quickstamp, the context menu in these input UIs does offer an 'evaluate' method which will evaluate action code in the input box and replace it with a literal value. Although this allows use of (simple) code on an ad hoc basis, the primary edit means of these UIs is attribute literal values.