This version is out of date, covering development from v8.0.0 to v8.x.x. It is maintained here only for inbound reference links from elsewhere. It is no longer actively updated.

Jump to the current version of aTbRef

Tinderbox v8 Icon

Stamps

Stamps are a method for manually applying action code to the currently selected item(s) in the view pane of the front document. If multiple items are selected, every item in the selection discretely has the same action code run upon it.

Stamps are action code 'expressions', i.e. one or more complete action(s) to be effected by the code. The concept of a stamp allows easy (manual) application and re-use of such code. They enable the user to:

Stamps are defined/edited via the Stamps tab of the Document Inspector. Stamps can be called by:

Stamps are essentially an entirely manual way to apply actions that might otherwise as easily be effected automatically via rules, edicts, OnAdd events, or agent actions. Stamps are thus useful for when a known change needs to be made to some attributes but the scope or timing of such a change cannot easily be predicted or automated and so manual application is the best method.

Stamps requiring long/complex code can store the action in a code note and call it via the action() operator.

If stamps are just being used to easily apply a consistent look and layout to notes, consider using prototypes instead for the greater flexibility they offer when you subsequently need to make changes.

A document's stamps can be used in any action (AgentAction, Rule, Edict, DisplayExpression, OnAdd, HoverExpression, TableExpression and ^action()^).

The stamp is called as an expression containing only the name of the stamp. The name is case-sensitive. Do not enclose it in quotes or Tinderbox will read it as a literal string (i.e. actual text). It must be terminated with a semicolon is followed by another expression. However, it is a good idea in this particular case of always using s semi-colon to help indicate your intent to the app.

Defined stamps with no code (a rare edge case when setting up a large document) will show in the Stamps Inspector but not in the Stamps menu.

The stamp name may be enclosed in quotes; unquoted and quoted forms both work. For a stamp called 'A test', the action would be be:

A test; 

or

"A test"; 

The same stamp called, but now as one of 3 discrete expressions within an action:

$Color="blue";A test;$Width=4; 

From v8.8.0, unlike editing attributes via a note's Displayed Attributes table or Get Info's attributes tab, altering an attribute via a stamp (or Quickstamp) does not alter $Modified.

From v8.9.0, if a stamp changes the text, Tinderbox will immediately expand any ziplinks mark-up found in the revised text.

Stamp Groups

From v8.2.1, the Stamps menu supports hierarchical organisation of stamps. To group stamps, include a colon in the stamps title:

Colour:red border 

This will cause the Stamps menu to add a group named 'Colour' and with submenu for the groups members, e.g. 'red border'. This method allows organising groupings of related stamps without creating unwieldy menus. Stamps cannot be nested more deeply than in groups, i.e. 1 level of nesting. Group names are case-sensitive, so 'Colour Map:blue' and 'Colour map:green' would list in separate groups.

The Stamps menu lists stamps in the order shown in the Stamps Inspector. Where a group occurs, it it is listed where the first group member occurs in the Inspector List and within the sub-menu, the items are listed as in Inspector listing order. Grouped items do no need to be contiguous in the Inspector listing.

Note that pre-existing stamp names containing colons will form their own group, with the second part of the original name as a sub-menu, but they otherwise function the same way.