When is an Action an OnAdd and when is it not?

Q & A - getting started with Tinderbox
1

I’m wondering about something that I suppose has an obvious answer somewhere, but it has not leapt out at me in the Getting Started doc.

Suppose I want note A to take Prototype X. My first impulse is to go to Command-1 and then the Action pane, and enter $Prototype=X. But this can’t be right, because that is the same syntax for creating an OnAdd action, which instructs Tinderbox to assign the prototype not to A, but to new notes within A. So, what is the correct syntax for telling a note to take the prototype itself?

I have been able to use OnAdd actions and stamps (where, it seems, somewhat confusingly, $Prototype=X applies to the note and is not an OnAdd) to assign prototypes to notes, so I’m not stymied by this, but I do find it a little perplexing. And I suspect my not understanding it could cause problems down the line. So I really would like to learn what I’ve missed here.)

David

2

OnAdd is a property of containers (and maybe adornments but I’m not sure). They’re run when you add a note as a child to the note that has OnAdd defined (Action in the inspector pane).

To set a prototype, you can right-click the note and choose from the prototype list. You can also pull up the properties inspector (third tab when you cmd+1), choose the prototype sub-tab, and select the prototype from the list. Or you can use a stamp.

3

Further to @pat’s answer, the OnAdd is an action applied to an item placed into, or created within a container. The latter can be a note or as a special case in maps, an adornment. In the latter case, dragging an item onto an adornment fires it’s OnAdd. In fact, agents do the same thing to aliases they create for notes matching their query, but the action is termed the ‘agent action’.

Whereas an OnAdd is stored in the attribute $OnAdd, an agent’s action is stored in $AgentAction. However, depending on where the selected item is an agent or a note, the ‘action’; sub-tab of the Action Inspector shows the $OnAdd or $AgentAction code in the same place. That may seem odd until you realise no item has both forms of action.

I think @dberreby is ask how to carry out an action. IOW, “I have a note selected and wish to apply an action to it.”. If so there are 2 main methods:

*Quickstamp. This is useful for short/quick actions. The action code used (as opposed to the effect of its use) is lost as soon as note focus changes.
*Stamp. Does the same thing but you define and save the action code for the stamp before use and it is available for later re-use.

So, QuickStamp/Stamp are applied manually once per press of the ‘Apply’ button.

OnAdd actions apply at least once on an item appearing (created or moved) in a container.

Agent actions apply every time the agent cycle runs.

A rule is an action applied to itself by a note every time the rule cycle runs.

An edict is essentially a lazy form of rule. Stored separately from the rule, the edict’s action is run infrequently on the note: i.e. for tasks that aren’t urgent but shouldn’t be forgotten.

I’m still not 100% sure of which of these action contexts is desired but hopefully that gives an indication of how they differ. All are written as action code.

Lastly, although (for legacy support reasons) Tinderbox will work with (some) unquoted strings of text, to set a note’s prototype to ‘X’ use code like this:

$Prototype="X";

The closing semi-colon is only mandatory if the action includes more than one discrete expresiion within it. Thus:

$Prototype="X";$Width=2

Here the ‘2’ is a number (not string) so is not quoted and as thelast expression no semi-colon is needed. But, the semi-colon after “X” is needed so that Tinderbox understands there are two discrete expressions within the action.

4

An OnAdd action is performed when this note is added to a container, or when this note is moved onto an adornment.

An AgentAction is performed when this note’s alias is added by an agent.

A Rule is performed when this note’s Rule is run; this happens from time to time, typically every few seconds.

An Edict is performed when this note’s Edict is run; this happens from time to time, typically about once an hour.

A Stamp is an action that is run on each selected note when selected from the Stamp menu or applied in the Inspector.

If you want A to use a prototype named X:

  • In Map view, right-click the prototype tab and select X
  • In outline view, right-click the outline and select X
  • In any view, select the note, open the Prototype inspector, and select X
  • In any view, select the note and use the Quickstamp inspector to set $Prototype to be X.
  • If you frequently need to set X as a prototype, make a stamp that sets $Prototype to be X and use the stamp.
  • If most or all the notes in a container use the same prototype, use the container’s $OnAdd action to set the prototype, saving you the bother of doing it yourself.
  • If all the notes that meet some criterion use the same prototype, create an agent whose action sets the prototype of notes that meet this criterion.
2 Likes
5

Thanks, all. I see I had sort of bumbled into the right practice. I have been setting prototypes with stamps and the OnAdd actions of containers. I guess I was trying to do it in a way that made sense to me but that isn’t the way Tinderbox syntax works. Probably the root of my confusion is that OnAdd actions happen in situations where I never see the $OnAdd command.

As I said, this was not a problem that was interfering with my day to day use, but I did want to understand these distinctions, so I can be sure I know what I am doing as things get more elaborate. Appreciate the fast thorough answers!

David

1 Like
6

to capture some of the points raised here, I’ve updated the ‘Actions & Rules’ page of aTbRef and added a new page on ‘Setting a prototype’.