51. Annotations

An annotation is a pixmap or string that is not part of a buffer's text but is displayed next to a particular location in a buffer. Annotations can be displayed intermixed with text, in any whitespace at the beginning or end of a line, or in a special area at the left or right side of the frame called a margin, whose size is controllable. Annotations are implemented using extents (see section 47. Extents); but you can work with annotations without knowing how extents work.

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 E-Lisp 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.

51.2 Annotation Primitives

Function: make-annotation glyph &optional position layout buffer with-event d-glyph rightp

This function creates a marginal annotation at position position in buffer. The annotation is displayed using glyph, which should be a glyph object or a string, and is positioned using layout policy layout. If position is nil, point is used. If layout is nil, whitespace is used. If buffer is nil, the current buffer is used.

If with-event is non-nil, then when an annotation is activated, the triggering event is passed as the second arg to the annotation function. If d-glyph is non-nil then it is used as the glyph that will be displayed when button1 is down. If rightp is non-nil then the glyph will be displayed on the right side of the buffer instead of the left.

The newly created annotation is returned.

Function: delete-annotation annotation

This function removes annotation from its buffer. This does not modify the buffer text.

Function: annotationp annotation

This function returns t if annotation is an annotation, nil otherwise.

51.3 Annotation Properties

Function: annotation-glyph annotation

This function returns the glyph object used to display annotation.

Function: set-annotation-glyph annotation glyph &optional layout side

This function sets the glyph of annotation to glyph, which should be a glyph object. If layout is non-nil, set the layout policy of annotation to layout. If side is left or right, change the side of the buffer at which the annotation is displayed to the given side. The new value of annotation-glyph is returned.

Function: annotation-down-glyph annotation

This function returns the glyph used to display annotation when the left mouse button is depressed on the annotation.

Function: set-annotation-down-glyph annotation glyph

This function returns the glyph used to display annotation when the left mouse button is depressed on the annotation to glyph, which should be a glyph object.

Function: annotation-face annotation

This function returns the face associated with annotation.

Function: set-annotation-face annotation face

This function sets the face associated with annotation to face.

Function: annotation-layout annotation

This function returns the layout policy of annotation.

Function: set-annotation-layout annotation layout

This function sets the layout policy of annotation to layout.

Function: annotation-side annotation

This function returns the side of the buffer that annotation is displayed on. Return value is a symbol, either left or right.

Function: annotation-data annotation

This function returns the data associated with annotation.

Function: set-annotation-data annotation data

This function sets the data field of annotation to data. data is returned.

Function: annotation-action annotation

This function returns the action associated with annotation.

Function: set-annotation-action annotation action

This function sets the action field of annotation to action. action is returned..

Function: annotation-menu annotation

This function returns the menu associated with annotation.

Function: set-annotation-menu annotation menu

This function sets the menu associated with annotation to menu. This menu will be displayed when the right mouse button is pressed over the annotation.

Function: annotation-visible annotation

This function returns t if there is enough available space to display annotation, nil otherwise.

Function: annotation-width annotation

This function returns the width of annotation in pixels.

Function: hide-annotation annotation

This function removes annotation's glyph, making it invisible.

Function: reveal-annotation annotation

This function restores annotation's glyph, making it visible.

51.4 Locating Annotations

Function: annotations-in-region start end buffer

This function returns a list of all annotations in buffer which are between start and end inclusively.

Function: annotations-at &optional position buffer

This function returns a list of all annotations at position in buffer. If position is nil point is used. If buffer is nil the current buffer is used.

Function: annotation-list &optional buffer

This function returns a list of all annotations in buffer. If buffer is nil, the current buffer is used.

Function: all-annotations

This function returns a list of all annotations in all buffers in existence.

51.5 Margin Primitives

The margin widths are controllable on a buffer-local, window-local, frame-local, device-local, or device-type-local basis through the use of specifiers. See section 48. Specifiers.

Specifier: left-margin-width

This is a specifier variable controlling the width of the left outside margin, in characters. Use set-specifier to change its value.

Specifier: right-margin-width

This is a specifier variable controlling the width of the right outside margin, in characters. Use set-specifier to change its value.

Specifier: use-left-overflow

If non-nil, use the left outside margin as extra whitespace when displaying whitespace and inside-margin annotations. Defaults to nil. This is a specifier variable; use set-specifier to change its value.

Specifier: use-right-overflow

If non-nil, use the right outside margin as extra whitespace when displaying whitespace and inside-margin annotations. Defaults to nil. This is a specifier variable; use set-specifier to change its value.

Function: window-left-margin-pixel-width &optional window

This function returns the width in pixels of the left outside margin of window. If window is nil, the selected window is assumed.

Function: window-right-margin-pixel-width &optional window

This function returns the width in pixels of the right outside margin of window. If window is nil, the selected window is assumed.

The margin colors are controlled by the faces left-margin and right-margin. These can be set using the X resources Emacs.left-margin.background and Emacs.left-margin.foreground; likewise for the right margin.

51.6 Annotation Hooks

The following three hooks are provided for use with the marginal annotations:

before-delete-annotation-hook

This hook is called immediately before an annotation is destroyed. It is passed a single argument, the annotation being destroyed.

after-delete-annotation-hook

This normal hook is called immediately after an annotation is destroyed.

make-annotation-hook

This hook is called immediately after an annotation is created. It is passed a single argument, the newly created annotation.