Loading document parsing libraries...
# Annotations
Class
## About
`Annotations` holds a document's discussion threads. Read it from `Editor.Annotations`; the editor creates it. Annotations never change the document's content, so they can be added and answered in a read-only editor. Set `Editor.AllowAnnotations` to False to turn them off: the margin icons, Add Comment, the popover, and the Inspector's Comments tab are hidden, and `Add`, `AddPrepared`, `Reply`, and `Show` do nothing, while threads already in the document are kept, saved, resolvable, and removable.
```xojo
'// Comments carry their author: these when set, otherwise the connected
'// collaboration user, otherwise TextDefaultAuthorCaption, "Author".
Editor.Annotations.AuthorID = currentUser.ID
Editor.Annotations.AuthorName = currentUser.Name
'// The selected text, or the selected node when no text is selected.
If Editor.Annotations.CanAdd Then Call Editor.Annotations.Add("Can we check this figure?")
'// A range of a node's text, or a whole node.
Var thread As GraffitiProEditor.Annotation = Editor.Annotations.Add(paragraph, 0, 12, "Reword this?")
Call Editor.Annotations.Reply(thread, "Done.")
Editor.Annotations.Resolve(thread)
```
- **Adding:** `Add(text)` annotates the selected text while a node is being edited, or the one selected node. `Add(node, text)` annotates a whole node, and `Add(node, start, length, text, segment)` a range of its text. `CanAdd` says whether `Add(text)` has something to annotate.
- **Discussing:** `Reply` adds a comment, `RemoveComment` removes one, and removing a thread's last comment removes the thread. `Resolve` and `Reopen` close and open a discussion.
- **Reading:** `Item(id)`, `ItemAt`, `Items`, `IndexOf`, `LastIndex`, and `AnnotationsAt(node)`.
- **Removing:** `Remove(annotation)`, `Remove(id)`, `RemoveAt`, and `RemoveAll`.
- **Popover:** `Show(annotation)` opens a thread in the comment popover, and `Show` with no annotation starts a new one on the selection. `Close` and `Visible` work like the editor's other popovers. `Selected` is the annotation whose text is highlighted.
Each change raises `Editor.AnnotationAdded`, `AnnotationChanged`, or `AnnotationRemoved`, so an application can show threads in its own panel, and sets `Editor.IsChanged`, since annotations are saved with the document.
## Enumerations
| Name | Value | Description |
| --- | :---: | --- |
| Commands | SelectionAnchor <br > ContainsNode <br > Added <br > Changed <br > Removed <br > Redraw <br > WillChange <br > Reveal | (None) |
## Delegates
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| CommandHandler | command As GraffitiProEditor . Annotations . Commands <br> annotation As GraffitiProEditor . Annotation <br> node As GraffitiProEditor . Node) As Boolean | command As GraffitiProEditor . Annotations . Commands, annotation As GraffitiProEditor . Annotation, node As GraffitiProEditor . Node) As Boolean | (None) |
## Methods
| Name | Parameters | Return Type | Description |
| --- | :---: | :---: | --- |
| Add | node As Node <br> start As Integer <br> length As Integer <br> text As String <br> segment As Integer = 0 | Annotation | Starts a discussion on a range of a node's text and returns it, or Nil when the range is not in the node's text or the text is empty. |
| Add | node As Node <br> text As String | Annotation | Starts a discussion on a whole node in the editor's document and returns it, or Nil when the node is not in the document or the text is empty. |
| Add | text As String | Annotation | Starts a discussion on the selected text, or on the selected node when no text is selected, and returns it. Returns Nil when nothing is selected or the text is empty. |
| AnnotationsAt | node As Node | Annotation | Returns the annotations attached to the supplied node, in the order they were added. |
| CanAdd | (None) | Boolean | Returns True when Add(text) has something to annotate: selected text, or one selected node. |
| Close | (None) | (None) | Closes the comment popover when it is open. |
| IndexOf | annotation As Annotation | Integer | Returns the index of the supplied annotation, or -1. |
| Item | identifier As String | Annotation | Returns the annotation with the supplied ID, or Nil. |
| ItemAt | index As Integer | Annotation | Returns the annotation at the supplied index, or Nil. |
| Items | (None) | Annotation | Returns every annotation, in the order they were added. |
| LastIndex | (None) | Integer | Returns the index of the last annotation, or -1 when there are none. |
| Remove | annotation As Annotation | (None) | Removes the supplied annotation and its comments. |
| Remove | identifier As String | (None) | Removes the annotation with the supplied ID and its comments. |
| RemoveAll | (None) | (None) | Removes every annotation. |
| RemoveAt | index As Integer | (None) | Removes the annotation at the supplied index and its comments. |
| RemoveComment | annotation As Annotation <br> comment As Comment | (None) | Removes a comment from an annotation's thread, and removes the annotation when it was the last one. |
| Reopen | annotation As Annotation | (None) | Marks a resolved discussion as open again. |
| Reply | annotation As Annotation <br> text As String | Comment | Adds a reply by the current author to an annotation's thread and returns it, or Nil when the text is empty. |
| Resolve | annotation As Annotation | (None) | Marks a discussion as resolved. It stays visible, drawn in the muted color, and can be reopened. |
| Show | annotation As Annotation = Nil | (None) | Opens the comment popover on an annotation's thread, or on a new thread for the selection when annotation is Nil. |
## Properties
| Name | Type | Default Value | Description |
| --- | :---: | :---: | --- |
| AuthorID | String | (None) | Gets or sets the collaborator ID recorded as the author of new comments. When it and AuthorName are empty, the connected collaboration user is recorded, or TextDefaultAuthorCaption outside a session. |
| AuthorName | String | (None) | Gets or sets the name recorded as the author of new comments. When it and AuthorID are empty, the connected collaboration user is recorded, or TextDefaultAuthorCaption outside a session. |
| Owner | GraffitiProEditor.Editor | (None) | Returns the editor these annotations belong to. |
| Selected | Annotation | (None) | Gets or sets the annotation whose text is highlighted, as when its thread is open. |
| Visible | Boolean | (None) | Returns whether the comment popover is open. |
## Notes
### Display and Storage
Comments are marked in the document's trailing margin, or its leading margin in a right-to-left document: a speech-bubble icon beside each line that has threads, counting its open threads. When all of a line's threads are resolved, the icon is muted and counts the resolved threads, so they stay reachable. Icons that would overlap, on neighboring lines, merge into one at the topmost line with the combined count; pointing at it highlights the text of every thread it covers, and clicking it opens the first open one. The popover pages through all of the node's threads, open and resolved. Threads on a whole node, and orphans whose node remains, are marked beside the node's first line. Text is not highlighted until it is relevant: pointing at an icon highlights the text its threads are on, and the thread open in the popover, `Selected`, stays highlighted. Clicking an icon opens the line's first open thread.
Annotations are saved in an `annotations` array beside the nodes in the document's JSON, so a document without them is unchanged. `FromJSON` restores them; `FromHTML` and `FromMarkdown` start without any. They are not part of Markdown, PDF, or printed output, nor of HTML unless `Editor.ToHTML` is called with `includeAnnotations` True, which it is not by default. Then `ToHTML` appends a `section` marked with `data-graffiti-annotations` after the document's content: an ordered list with one item per thread, carrying its anchor in `data-` attributes, the quoted text in a `blockquote`, and each comment's author, date in a `time` element, and text. Resolved threads are included, marked with `data-resolved`. HTML import skips the section, so it never comes back as content.
**Inspector.** An `Inspector` attached to the editor has a Comments tab that lists the inspected node's threads, or the document's, as cards with their status, and opens, resolves, reopens, and deletes them.
**Collaboration.** In a collaboration session each change is sent to the server, which checks it against the user's access and sends everyone the result; see the Collaboration Protocol notes. Users with `Annotate` access can comment in a read-only editor. Changes other users make raise the same events but are not undo steps.
**Popover.** Clicking a comment icon raises `Editor.AnnotationSelected` and, unless the application returns True, opens the comment popover on the thread. The popover pages through the node's threads, starts another thread on the same text or node with New, resolves, reopens, and deletes them, and adds a reply when Return is pressed in its field. The Add Comment toolbar item, which the contextual toolbar shows while a node is selected, and Option-Command-M (Control-Alt-M elsewhere) open it on the selection. Its anchor is taken when it opens, so the selection may change while the comment is typed.
Adding, replying, resolving, reopening, and removing are each one step in `Editor.History`, so Undo and Redo reverse them like any other change, and raise `AnnotationAdded`, `AnnotationChanged`, and `AnnotationRemoved` for what they restore. `RemoveAll` and removing a thread's last comment are one step. Undoing an edit to annotated text moves its anchor with the text.