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


An adornment is seen in Map views only and is used to provide a means of adding visual elements to the background of the Map view. Created via the Create Adornment menu item in the Note menu or the map context menu. A map may have one, many or no adornments. Adornments are also described under general concepts. Adornments may also be of special types: image adornments or geographic adornments. An adornment can be made into a smart adornment by giving it a query; removing the query toggles the smart adornment back to normal adornment behaviour.

An adornment, of any kind, may not have aliases.

Adornments are always excluded from agent query matches, i.e. they are not treated as notes when matching, as well as by group designators including find(), plus the view pane's Find toolbar. Altering $Searchable for an adornment will not make it appear in searches. However, agents can test inside() with an adornment name to see if any notes lie on top of the adornment.

Note that whilst adornments have a Text pane, $Text can store data but it is never drawn on screen (compared to a normal note's $Text).

Although adornments are not listed in the views like Outline, these objects do have attributes. To control display details like the border width, select an adornment and either use the [Cmd]+[Opt]+[i] shortcut or select Get Info from its pop-up menu to open the Get Info pop-over. Most attributes are irrelevant for an adornment except those in the Map section.

Note that adornments do get counted in the $OutlineOrder, even if not shown; the are counted as the last sibling(s) child(ren) of the note on whose Map view they appear but they do not affect the normal hierarchy or the links of any notes. However, adornments do not affect $SiblingOrder.

Adornments cannot be exported, although they are counted in $ChildCount and $DescendantCount. Therefore if doing export related conditional code based on $ChildCount and if adornments are in use, checking $ChildCount alone may give incorrect results. A better test in such a context is if($ChildCount & (collect(children,$Name).size >0)).

Adornments are ignored by designators.

Adornments do not support links so cannot be linked to/from notes.

When a note is created on top of an adornment, the adornment's $OnAdd action is run; prior to this, the adornment action ran only when the note was moved onto the adornment. The adornment's $OnAdd is also run on other adornments placed in or overlapping the adornment if the former is in front; if behind no $OnAdd fires.

Adornments set to zero width or height can be used to make divider lines.

If $Color is set to 'transparent' the adornment's icon is hidden and only the title shows on the map, although the adornment still functions as usual for things like $OnAdd actions. It is possible to have a visible border for a transparent adornment, but to do this $BorderColor must be set to a value other than 'automatic'.

Locked adornments are locked ($Lock) onto the map background to avoid accidental movement. The lock state can be toggled on/off using the icons top right of the adornment; if desired the icon can be substituted with a custom icon. Locked adornments are ignored from drag-selections of notes. An adornment can be selected whilst locked but to re-size it (or drag it) is must be unlocked.

Adornments may use dashed borders.

Sticky adornments ($Sticky) ensure any notes within or overlapping them move with the adornment when the latter is moved. Overlapping adornments are also moved if they lie above the sticky adornment in outline order, i.e. adornments that lie partially over (above) the sticky adornment but under (behind) it. The sticky state can be toggled on/off using the icons top right of the adornment; if desired the icon can be substituted with a custom icon.

Adornment can set a $DisplayExpression box via the Text Inspector's Title sub-tab or via the Get Info pop-over.

Adornments can have drop shadows like note icons. The $Shadow will always default to false for an adornment regardless of the app/doc setting for notes, i.e. such defaults only apply to the latter. For that reason, making a prototype adornment with a shadow and then inheriting that is an easy way to use drop-shadowed adornments.

Adornments can display badges, and $NameLeading and $NameStrike are supported.

Adornments fully respect $Opacity enabling them to be fully translucent.

New adornments are placed on top of existing adornments. This is the reverse of existing behaviour but should be more intuitive for use. The change is achieved by always adding new adornments in $OutlineOrder in front of existing ones rather than at the end, as the lowest outline order item is always drawn on top.

Adornments can show a subtitle.

Adornments show a small inner shadow (inside the the border line).

OnAdd also affects adornments created or pasted into containers and the adornment's OnRemove action is performed if a note atop it is removed or deleted.

From v8.7.0, pressing [down-arrow] no longer zooms into an adornment (an adornment cannot have child objects).

From v8.7.1, if an adornment is added inside an agent, the agent’s $CleanupAction is set to "none".