Any adornment is made into a smart adornment simply by giving it a query (stored in $AgentQuery) using agent query syntax - i.e. action code. Importantly, the scope of the query in a smart adornment is always the current map, the map on which the adornment lies. All other notes are automatically out of scope. The following facts apply:
- Notes within the current map matching the query are moved onto the adornment. Unlike an agent, the smart adornment does not create an alias of the matched note but rather moves the original note itself onto the adornment - which is why the scope of the query is limited to the current map. In this context, 'original note' could also be a container, agent or an alias.
- Notes moved onto the adornment as a result of the query fire the adornments's $OnAdd code.
- Adornments don't auto-expand to encompass notes. In some cases where there are so many matching notes that they fill the adornment, some notes may be placed around the adornment.
- Matched notes are sorted as per the adornment's sort attributes.
- Matching obeys the smart adornment's $AgentPriority setting.
- Matched notes have their $Xpos/$Ypos altered as the original is being moved.
- The outline order of matched notes is not affected.
- Matched notes are laid out in a grid (sort) order on the adornment until the available areas is filled. Thereafter notes may be stacked on top of one another or alongside the adornment until the latter is manually resized to accommodate all matched notes.
- $CleanupAction is ignored. When a query is set the user cannot re-arrange items on the adornment.
- Notes no longer matching the query are moved off the adornment and placed alongside it. They are not restored to their location when first moved by the adornment.
- Notes/containers/agents that are locked are ignored.
- Other attributes are ignored. Notes 'in' other adornment will be moved (even if the original adornment's sticky flag is set).
- To read or set adornment attributes via $OnAdd actions, use the 'adornment' designator (it operates analogously to the 'agent' designator used in agents).
- A note on the map can only move onto one smart adornment. In the case of conflict, where two or more smart adornments match a given note, the adornment with the highest $OutlineOrder will match the note. An adornment's $OutlineOrder can be looked up via its Get Info pop-over (attributes tab: General section). Normally, a duplication conflict resolves to the lowest outline order but in adornments the z-order and thus outline ordering is reversed (further explanation).
If a smart adornment is made larger (manually or via an action) and in doing so overlaps non-matching notes then the latter are displaced to one side so as to remain outside the adornment. Re-sizing a normal adornment the notes would simply lie inside the new adornment boundary.
Smart adornments cannot be used to move or act on notes outside the current map. So, for instance, it can not move a note into a (container's) subordinate map or promote it to a parent map, or indeed pull it from another map. Put another way, it can only act on its siblings.
From v7.3.0, Smart adornments now allow space for multi-line subtitles ($Subtitle), assuming that the adornment is drawn at or near standard magnification.