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 Extents); but you can work with annotations without knowing how extents work.

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.

Annotation Primitives
=====================

 -- Function: make-annotation glyph &optional position layout buffer with-event d-glyph rightp
     This function creates a marginal annotation at position POS 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 POS 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.

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.

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.

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

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.