51.1 Annotation Basics

Marginal annotations are notes associated with a particular location in a buffer. They may be displayed in a margin created on the left-hand or right-hand side of the frame, in any whitespace at the beginning or end of a line, or inside of the text itself. Every annotation may have an associated action to be performed when the annotation is selected. The term annotation is used to refer to an individual note. The term margin is generically used to refer to the whitespace before the first character on a line or after the last character on a line.

Each annotation has the following characteristics:

glyph

This is a glyph object and is used as the displayed representation of the annotation.

down-glyph

If given, this glyph is used as the displayed representation of the annotation when the mouse is pressed down over the annotation.

face

The face with which to display the glyph.

side

Which side of the text (left or right) the annotation is displayed at.

action

If non-nil, this field must contain a function capable of being the first argument to funcall. This function is normally evaluated with a single argument, the value of the data field, each time the annotation is selected. However, if the with-event parameter to make-annotation is non-nil, the function is called with two arguments. The first argument is the same as before, and the second argument is the event (a button-up event, usually) that activated the annotation.

data

Not used internally. This field can contain any elisp object. It is passed as the first argument to action described above.

menu

A menu displayed when the right mouse button is pressed over the annotation.

The margin is divided into outside and inside. The outside margin is space on the left or right side of the frame which normal text cannot be displayed in. The inside margin is that space between the leftmost or rightmost point at which text can be displayed and where the first or last character actually is.

There are four different layout types which affect the exact location an annotation appears.

outside-margin

The annotation is placed in the outside margin area. as close as possible to the edge of the frame. If the outside margin is not wide enough for an annotation to fit, it is not displayed.

inside-margin

The annotation is placed in the inside margin area, as close as possible to the edge of the frame. If the inside margin is not wide enough for the annotation to fit, it will be displayed using any available outside margin space if and only if the specifier use-left-overflow or use-right-overflow (depending on which side the annotation appears in) is non-nil.

whitespace

The annotation is placed in the inside margin area, as close as possible to the first or last non-whitespace character on a line. If the inside margin is not wide enough for the annotation to fit, it will be displayed if and only if the specifier use-left-overflow or use-right-overflow (depending on which side the annotation appears in) is non-nil.

text

The annotation is placed at the position it is inserted. It will create enough space for itself inside of the text area. It does not take up a place in the logical buffer, only in the display of the buffer.

The current layout policy is that all whitespace annotations are displayed first. Next, all inside-margin annotations are displayed using any remaining space. Finally as many outside-margin annotations are displayed as possible. The text annotations will always display as they create their own space to display in.