This version is out of date, covering development from v5.0.0 to v5.12.2. It is maintained here only for inbound reference links from elsewhere.

Jump to the current version of aTbRef.

Tinderbox 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 dialog accessible only from the Map pop-up menu. A map may have one, many or no adornments. Adornments are also described under general concepts. Adornments can be picture adornments.

An adornment my not have aliases and can't be found by agent queries. Adornments can be found via the Find view using the attribute name. 'Opening' an adornment from the Find view listing results in the adornment's Rename dialog being shown. Note that adornments have no $Text; at least, they have no accessible Text window and thus no easily usable $Text - though the attribute does exist and can store data.

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 Info view. Most attributes are irrelevant for an adornment except those in the Map section.

Adornments are ignored by agents, i.e. they are not treated as notes when matching. However, agents can test inside() with an adornment name to see if any notes lie on top of the adornment.

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.

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. From v5.8.0, 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 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.

Adornments may use dashed borders.

Sticky adornments move any notes within or overlapping them 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 Create/Rename dialogs have no space for a $DisplayExpression box but code can still be set via the Info view.

From v5.7.1, 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.

From v5.8.0, adornments can display badges, and $NameLeading and $NameStrike are supported.

From v5.9.2, adornments fully respect $Opacity enabling them to be fully translucent.

From v5.9.2, 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.

From v5.10.0 adornments can show a subtitle.

From v5.10.2, adornments show a small inner shadow (inside the the border line).

from v5.11.0, adornments are always excluded from agent query matches and group designators including find(), plus the Find view. Altering $Searchable for an adornment will not make it appear in searches.

Possible relevant notes (via "Similar Notes" feature):

A Tinderbox Reference File : Misc. User Interface Aspects : Map view interface : Adornments