# Designators

Designators specify to which note an attribute reference refers. For example, in the expression

> `$Width(parent)`

the designator “parent” refers to the note that contains this note. If the designator is omitted, the reference refers to `this` note.

- In rules, `this` refers to the note whose rule is running.
- In agent queries, `this` refers to the note being examined by the agent.
- In agent actions, `this` refers to the newly-created alias that satisfies the agent’s query.
- In OnAdd actions, `this` refers to the note that is being added.

`this` | The note being examined by an agent, the note being added to an adornment, or the note whose rule is being run
`next` | The note that follows this note in outline order
`previous` | The note that precedes this note in outline order
`prevSibling` | The next older sibling of this note
`nextSibling` | The next younger sibling of this note
`firstSibling` | The first sibling of this note
`lastSibling` | The last sibling of this note
`parent` | The parent of this note
`grandparent` | The parent of the parent of this note
`child` | The first child of this note
`child[n]` | The nth child of this note, where n is a number. The first child is child[0]. If n is negative, the nth youngest child of this note: child[-1] is the youngest child.
`lastChild` | The last child of this note
`randomChild` | A randomly selected child of this note
`current` | The note that is currently being exported. When not used in an export template, current is equivalent to this. Where a note is exported to its own page, current is the same as this. If the note is included in another note's page, however, current refers to the page being exported.
`cover` | The first note in the document.
`source` | The link source (used only in link expressions)
`destination` | The link destination (used only in link expressions)
`agent` | Available only in agent queries and agent actions; refers to the agent that is currently examining the note.
`adornment` | Available only in adornment queries and adornment actions; refers to the smart adornment that is currently examining or performing an action on the note.
`original` | In aliases, refers to the original note associated with the alias and useful for addressing properties of the original such as `$Xpos` and `$Ypos` that are not inherent to the alias. Otherwise synonymous with this.
`source` | In guard fields, refers to the source of the link.
`destination` | In guard fields, refers to the destination of the link.

Designators may be combined. For example, `$Name(nextSibling(parent))` is the name of the next sibling of this note's container.

### Group Designators

Some operators accept a group designator that designates multiple notes. For example, `any(child,$Checked)` is true if the $Checked attribute of any of this note's children is set to true. Group designators include:

`children` | the immediate children of a note
`descendants` | all descendants of a note
`siblings` | all siblings of a note
`ancestors` | all ancestors of a note
`all` | all notes in the document

A list or set of pathnames may be used anywhere a group designator is required.

### find()

The special designator find() searches through the entire document to locate notes that satisfy an expression. For example:

`$Color( find($Status="Urgent"))="red"`

will locate every note whose $Status is "Urgent" and turn is red.

The find() designator acts in many ways like an agent. In general, prefer agents to using find(), because the agent’s results can be reused by other agents.