Stamps were originally a method for storing action code to be invoked manually via the app UI (see below), the code being run on 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. As action code usage expanded, stamps could also be invoked via other actions, but the resulting action still only runs once per invocation.
Stamps are stored as stamp notes within the built-in Hints container (the latter is not default content in a new TBX document). Each stamp note holds a single stamp's code. The title of the stamp note is the name of the stamp. Stamp names are case-sensitive.
If there pre-existing stamps before the built-in Hints container is added, these stamps are automatically added as stamp notes. Stamps may be managed/edited either in stamp notes or in the Stamps Inspector. since the Hints container became available, this is the preferred mathod of adding/editing stamps.
Stamps comprise one or more complete action(s) to be carried out when the code is called. The concept of a stamp allows easy (manual) application and re-use of such code.
Stamps can be called by:
- The Stamps menu.
- The Stamps tab of the Document Inspector (use the 'Apply' button).
- In action code via the stamp() 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.
If invoking a stamp via action code, the name of the stamp is used; 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 action. 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 here as one of 3 discrete expressions within an action:
$Color="blue";A test;$Width=4;
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.
If a stamp changes the text, Tinderbox will immediately expand any ziplinks mark-up found in the revised text.
When applying a stamp to a note that is on exactly one adornment, the designator 'adornment' implies that adornment. If the note is on several adornments, the designator 'adornment' reflects only one of those adornments (the front-most?).
Stamps run from the Stamps menu (but not those run from the Inspector’s Apply button) show a progress bar when invoked. When using extremely slow stamps, this can help ensure that the stamp is completed before it is invoked again.
Stamp Groups
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. Use of more than one colon in the name causes the stamp to not list as part of a Group. Names are case-sensitive, so 'Colour Map:blue' and 'Colour map:green' would list in separate groups.
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 work the same way.
Stamps menu order
The Stamps menu lists stamps in the order shown in the Stamps Inspector. Where a group occurs, 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 not need to be contiguous in the Inspector listing.
Currently, although Inspector-created stamps are replicated in the /Hints/Stamps container, the ordering of both is independent; re-ordering in one location does not update it in the other. If differing, the order in the Stamps menu is that of the Inspector and not the Stamps container.
See also—notes linking to here: