Viewing and editing annotation details

The MAT UI provides a full range of functionality for editing (and viewing) annotation details.

• Which annotations have annotation detail views?
• Launching an annotation editor
• The annotation editor
• Annotation-valued attributes and choose mode
• The "Actions" menu in the annotation editor
  
• Highlighting and scrolling
  

Which annotations have annotation detail views?

An annotation has a detail view if

• it has any attributes (including attributes which define effective labels); or
  
• it can serve as the value of another annotation's annotation-valued attribute.

If the document is editable, these details will be editable in the detail view.

We refer to these views as annotation editors, and we refer (perhaps confusingly) to summoning these views as "editing (or viewing) an annotation".

Launching an annotation editor

If an annotation has a detail view, you'll be able to access the annotation editor by clicking on the annotation, either in the annotation text or in the annotation table:

By default, the menu gives you the option of editing the annotation in a popup, or in a tab. You can provide a default via the "View -> Edit/view annotations in tabs" or "View -> Edit/view annotations in popups" option from the top menubar. If you choose one or the other of these, the popup menu will have a single "Edit annotation" entry, which will open an annotation editor in your preferred mode.

The editor popup appears as a dialog in the center of your window:

The editor tab appears in the detail tab area at the bottom, where the annotation tables appear:

If the document can't currently be edited (if, e.g., it was opened read-only, or the current step doesn't make hand annotation available), the entry in the annotation popup menu will read "View..." instead of "Edit...", and the resulting view will not allow you to edit the elements:

The annotation editor

The annotation editor contains a brief description of the annotation, either in the title bar (if editing in a popup) or the tab itself (if editing in a tab). This description supplements the attribute details in the editor itself.

At the top of the editor is a two-column table, with the attributes and their types on the left and the value editor elements on the right. Each attribute type has a different type of value editor:

Below this table is an optional "References" section, which we'll see exemplified below, and then an "Actions" menu.

You can dismiss an editor a popup by pressing "Done" or pressing the "x" in the title bar, and you can dismiss an editor in a tab by pressing the "x" in the tab label.

Annotation-valued attributes and choose mode

Annotation-valued attributes, when unfilled, present the string "(null)" and two buttons: "Choose" (if the attribute has no aggregation) or "Add" (if the attribute is a set or list attribute), and "Unset", which clears the value.

Pressing "Choose" or "Add" causes the document to enter choose mode. Choose mode allows you to create or select an annotation which can be the value of this attribute. In choose mode, the "Choose" button now reads "Choosing (press to cancel)", and the status line above the document text now reads "Choose mode: active", along with an option to cancel:

In choose mode, you can either swipe text, to create a new annotation to serve as the attribute value, or select an existing annotation, to choose it as the value. If you're creating a new annotation, the annotation will be created immediately (if there's only one kind of annotation that can fill the attribute) or you'll get a popup menu corresponding to your choices (if there are multiple kinds).

One difference between choose mode and normal annotation mode is that clicking on a token will not create a swipe spanning that token; you must actually swipe the text.

Unfortunately, the UI doesn't provide immediate feedback, when hovering over an annotation, whether it's an acceptable value for the attribute in choose mode. You'll see the annotation details, as usual, in the status line immediately below the annotation text, but it's up to you to determine whether the annotation you're about to select is appropriate. If it's not (e.g., if it's a LOCATION, but the attribute is limited to PERSON), you'll get a popup dialog informing you that the choice is incorrect, and giving you the option to try again, or cancel.

When an annotation is selected as an attribute value, the annotation and attribute which point to it are listed in the "References" column in the annotation tables, and in the "References" section of the annotation popup editor for the value:

These references are mouseable, and will present a popup menu:

The important menu item here is "Detach from this location". If you select this item, the annotation will be removed from the specified attribute value. The parallel situation arises with the attribute values themselves; they too are mouseable, and you can detach the values via the popup menu:

We'll discuss scrolling below.

If the annotation attribute is a set or list attribute, the presentation will be slightly different. The value(s) will be enclosed in curly brackets ({...}), and each value will be separately mouseable. If you detach all the annotation values, your result will be an empty list or set, which is not equivalent to a null value; to clear the value entirely, use the "Unset" button.

The "Actions" menu in the annotation editor

The "Actions" menu in the annotation editor allows you to delete annotations, but also to attach annotations to other annotation attribute values, if the task allows:

If you select one of the "Add..." items, you'll enter choose mode again, but this time, you'll be selecting or creating the annotation to attach this annotation to, rather than the annotation to attach to this annotation. Note that each "Add..." entry specifies an attribute into which this attribute will be inserted. In choose mode, the annotation editor will make available, immediately under the "Actions" button, a button allowing you to cancel, and the annotation status line above the document text will be updated as you saw in the previous choose mode example.

Highlighting and scrolling

The various annotation popup menus give you the option to "Scroll to annotation". If you select this action, the UI will do its best to vertically center the selected annotation in the main editor window.

In conjunction with scrolling, the UI provides highlighting so you can find the annotation you're looking for. When you hover over an annotation just about anywhere other than the main document window - in the title of an annotation editor, or over a row in the annotation table, or in the "References" section of the annotation editor, or the "References" column of the annotation table, or the value of an annotation-valued attribute in the annotation editor - the annotation itself will be highlighted in the main annotation window:

Notice here that "he" in the third paragraph is surrounded by a box as the mouse hovers over the annotation attribute value.

You can also examine links between annotations using highlighting. When you highlight an annotation in the document window which has annotation attribute values, its attribute values will be highlighted, along with the attribute that the value fills:

Similarly, if you hover over an annotation which is the value of another annotation attribute, the annotation it's linked to will be highlighted, along with the attribute it fills in that other annotation.