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?

An annotation has a detail view if

If the document is editable, those details which are currently editable 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".

Modifying annotations and launching an annotation editor

Let's select an annotation which has some rich structure:

[menu in text]

You can see that you can modify the annotation in a number of ways:

You have a similar range of actions available when you click on an annotation in the annotation table:

[menu in table]

In the remainder of this section, we'll focus on summoning an annotation editor.

By default, the popup 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.

By default, the editor popup appears as a dialog in the upper right corner of your window:

[editor popup]

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

[editor in tab]

Note the green border around the editor; this indicates that the editor is the active editor, which becomes relevant when we want to fill annotation-valued attributes.

If none of the attributes are editable (if, e.g., the document was opened read-only, or the current step doesn't make hand annotation available, or the current step doesn't allow you to edit any of the attributes of the annotation type), the entry in the annotation popup menu will read "View..." instead of "Edit...". In all cases, the editor will allow you to edit only those attributes which are currently editable:

[readonly popup]

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. Attributes which are not currently editable will be described. Each editable attribute type has a different type of value editor:

type
editor
aggregation support
string
either a long or short type-in with "Use zero-length string" and "Unset" buttons (if no choices are available for the attribute), or a drop-down menu (if choices are available), or a value with an "Edit" button (if a custom editor is assigned)
If the attribute is a "set" aggregation and has choices, the menu will be a multi-choice menu; in all other cases, editing string aggregations is not supported yet.
int
a short type-in window (if no choices are available for the attribute), or a drop-down menu (if choices are available), or a value with an "Edit" button (if a custom editor is assigned)
If the attribute is a "set" aggregation and has choices, the menu will be a multi-choice menu; in all other cases, editing int aggregations is not supported yet.
float
a short type-in window, or a value with an "Edit" button (if a custom editor is assigned)
Editing float aggregations is not supported yet.
boolean
a pair of radio buttons ("yes"/"no") and an "Unset" button
Editing boolean aggregations is not supported yet.
annotation
a mouseable value with an "Add" or "Choose" button and an "Unset" button
Editing annotation aggregations is supported.

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, annotation editors, and choose mode

Annotation-valued attributes can be filled either via the annotation which has the attribute, or from the candidate filler. In addition, they can be filled either from the annotation editor, or directly from the annotation popup menu.

Linking annotations via the annotation editor

In annotation editors, annotation-valued attributes, when unfilled, present the string "(null)" and two buttons: "Choose", and "Unset", which clears the value.

[editor popup]

Pressing "Choose" 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 exit)", and the status line above the document text now reads "Choose mode: active", along with an option to exit:

[choose mode]

In choose mode, you have two options:

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 exit.

You can select an existing annotation as filler either by clicking on it in the annotation pane itself, or by clicking on it in the annotation table. When you click on an annotation in the annotation table, and choose mode is active, the popup menu will contain a "Choose this annotation" action; selecting this action is equivalent to clicking on the annotation in the annotation pane.

[choose mode in table]

In addition to invoking choose mode from the annotation editor itself, another way to add annotations to the active editor is to select the candidate value annotation in the annotation pane. For the active editor, the annotation popup menu will contain entries which allow you to set any eligible attribute value in the active editor. For example, in the case above, clicking on "David Asher" will bring up a menu which contains an entry "Add as actor to edited annotation". The background color of this entry will be the same as the border color of the active editor. Selecting this entry will make this annotation the value of the actor attribute in the active editor.

When an acceptable 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 editor for the value:

[editor popup with reference]

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

[reference 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:

[annot menu]

We'll discuss scrolling below.

Atomic vs. set- or list-valued annotation attributes

For simple annotation-valued attributes, the button to enter choose mode will be labeled "Choose"; once you select an acceptable value, the UI exits choose mode automatically.

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.

The button to enter choose mode will be named "Add" rather than "Choose". When you enter choose mode, the UI will remain in choose mode until you explicitly exit, allowing you to select multiple fillers without having to re-enter choose mode each time.

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:

[actions menu]

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. InIf you enter choose mode, you will be able to exit by choosing the orange "Choosing (press to exit)" button that will appear immediately under the "Actions" button, or by clicking the orange "Exit" button in the status line as in the previous choose mode example.

Linking annotations via the annotation popup menus

As we saw here, you can also use the annotation popup menus to link annotations together. If you're starting with the candidate filler, you can attach it to other annotations in the same way you can use the "Actions" menu, as we just saw. No annotation editor needs to be involved. Let's return to our original example:

[menu in text]

If you select "Add as location to LOCATED_EVENT...", you'll enter choose mode, but the contextual information you need is provided not by an annotation editor, but by a separate popup:

[choose mode parent]

You can see this popup in the upper right corner; you can now either select an existing LOCATED_EVENT, either by clicking on an annotation in the annotation panel or by selecting "Choose annotation" in the popup menu in the annotation tables, or you can create a new LOCATED_EVENT (if permitted in the current workflow step), by swiping in the usual way. Making a selection dismisses the popup; and you can also exit choose mode by pressing the "Cancel" button in the popup, closing the popup, or pressing "Exit" in the status bar at the top of the annotation pane.

Similarly, if you have an element which has annotation-valued attributes, you can fill those attributes from the annotation popup menu:

[choose mode child]

The LOCATED_RELATION "in" has two entries "Set actor slot..." and "Replace location slot..." (the latter slot was filled in the previous step). If you select one of these, you'll be prompted with a choose mode popup very much like the one in the previous step, and you'll be able to select or create a filler in the analogous way.

Guided navigation mode

While the annotation editors are easily navigable, experienced annotators might prefer to navigate through them more quickly. To support this activity, we've introduced guided navigation mode. In this mode, you can navigate through your annotation editor almost exclusively via the keyboard (the lone exception is annotation-valued attributes, which require mouse interaction).

To enter guided navigation mode, you will most likely have to modify the UI settings. Select "View -> All settings...", and change the setting labeled "When to enter guided navigation mode in annotation editors". There are three possible values:

You can change the default value as described here.

Here's what your annotation window will look like when you edit the first instance of "North Korea", and you've selected "on request" as the UI setting:

[kbd navigation on request]

As you can see, the annotation editor bears the instruction "Press '*' to enter guided navigation mode, or '+' to also enter automatically for this label in the future" at the top.

Once you're in guided navigation mode (either because you pressed "*" or "+", or you've entered guided navigation mode automatically), your window will look like this:

[kbd navigation start]

Note that the annotation editor now says "In guided navigation mode" at the top, and the first attribute is outlined. Note, too, that the menu associated with this attribute has been changed from a native HTML menu to a more feature-rich menu which better supports this mode, and that this menu is open.

When you choose a value for an attribute in guided navigation mode, you'll be automatically advanced to the next attribute. So in this case, if you press "2", you'll choose the value "Proper name" for the "nomtype" attribute, and you'll be advanced to the boolean "is_political_entity" attribute:

[kbd navigation step 2]

Note that the instructions have changed. Press 'y' to identify this element as a political entity; once you do this, the annotation editor will close automatically, since there are no other attributes to set.

There are multiple ways to navigate through the attributes in keyboard navigation mode:

Each attribute provides different facilities for setting the value via the keyboard. The interaction instructions are provided as each attribute is edited.

Attribute type
UI element
Interaction method
single-line string (non-choice), int (non-choice), float
single-line type-in
The cursor will be positioned at the end of the current value. Edit or set the value as you choose. Press <return> to advance.
multi-line string
multi-line text area
The cursor will be positioned at the end of the current value. Edit or set the value as you choose. Press the right arrow to advance.
singleton string (choice), int (choice)
menu
The current value of the attribute serves as the anchor of an open menu presenting all the choices. The first 10 choices will have numeric keyboard accelerators (or whatever keyboard accelerators are defined for these choice attributes). Select a value by pressing the corresponding keyboard accelerator; choosing an item from the menu using the mouse; navigating to an item using the up and down arrows and selecting the current value with the <return> key. Or, if you want to skip the attribute without changing its value, press the <return> key.
set-valued string (choice), int (choice)
multiple-selection menu
The current values of the attribute serve as the anchor of an open menu presenting all the choices. The currently active choices The first 10 choices will have numeric keyboard accelerators (or whatever keyboard accelerators are defined for these choice attributes). Toggle the values by pressing the accelerators and then the <return> key, or toggle a single value by selecting it with the mouse or navigating to it with the up and down arrows and pressing the <return> key. Or, if you want to skip the attribute without changing its value, press the <return> key.
boolean
radio buttons
Press 'y' to select "yes", 'n' to select "no", or 'u' to unset the value. If you want to skip the attribute without changing its value, press the <return> key.
annotation
choose mode controls
When an annotation-valued attribute is activated, it will enter choose mode automatically. At any point, you may hit the <return> key to exit choose mode and advance to the next attribute. You may also press 'u' to unset the value. If the annotation-valued attribute is not a set- or list-valued attribute, you'll advance automatically to the next attribute when you choose or create a legal attribute value; if it is a set-valued attribute you may choose or create as many values as you like, and then advance by pressing the <return> key.

When you advance out of the final navigable attribute, one of two things will happen. If there are no more editable attributes, the annotation editor will close automatically. If, on the other hand, there are editable, non-navigable attributes (e.g., attributes with custom editors) which follow the final navigable attribute, you'll exit guided navigation mode but the editor will remain open.

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:

[highlight annotation]

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:

[attribute highlighting]

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.