[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 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 are implemented using extents (@pxref{Extents}); but you can work with annotations without knowing how extents work.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.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 side of the frame, in any whitespace at the beginning 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.

annotation

Each annotation has the following characteristics:

glyph

This may be either a bitmap/pixmap object or a string.

face

The face with which to display the glyph.

action

If non-nil this field must contain a function capable of being the first argument to funcall. This function is evaluated with a single argument, the value of the data field, each time the annotation is selected.

data

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

type

Valid types are: bitmap, pixmap and string.

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

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

outside-margin

The annotation is placed, left-justified, into the outside margin area. If the outside margin is not wide enough for an annotation to fit it is not displayed.

inside-margin

The annotation is placed, left-justified, into the inside margin area. 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 variable use-left-overflow is non-nil.

whitespace

The annotation is placed, right-justified, into the inside margin area. This puts the annotation as close as possible to the first 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 variable use-left-overflow 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Annotation Primitives

Function: make-annotation glyph &optional position layout buffer

Create a marginal annotation with glyph, which may be a bitmap/pixmap or a string at position pos. Use layout policy layout and place the annotation in buffer buffer. If pos is nil, point is used. If layout is nil, whitespace is used. If buffer is nil, the current buffer is used. Returns the newly created annotation.

Function: delete-annotation annotation

Remove annotation from its buffer. This does not modify the buffer text. Returns the annotation deleted.

Function: annotationp annotation

Return t if annotation is an annotation, nil otherwise.

Function: annotation-visible annotation

Return t if there is enough available space to display annotation, nil otherwise.

Function: annotation-at &optional position buffer

Return the annotation at position in buffer. If position is nil point is used. If buffer is nil the current buffer is used.

Function: annotation-layout annotation

Return the layout policy of annotation.

Function: set-annotation-layout annotation layout

Set the layout policy of annotation to layout.

Function: annotation-type annotation

Returns the display type of annotation. The type will be one of following symbols:

pixmap

bitmap

string

nil (object is not an annotation)

Function: annotation-width annotation

Return the width of annotation in pixels.

Function: annotation-glyph annotation

If annotation is of type string return the string. Otherwise return the bitmap or pixmap object of the glyph representing annotation.

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

Set the glyph image of annotation to glyph. If layout is non-nil set the layout policy of annotation to layout. Returns the new value of annotation-glyph.

Function: annotation-data annotation

Return the data associated with annotation.

Function: set-annotation-data annotation data

Set the data field of annotation to data. Returns data.

Function: annotation-action annotation

Return the action associated with annotation.

Function: set-annotation-action annotation action

Set the action field of annotation to action. Returns action.

Function: annotation-face annotation

Return the face associated with annotation.

Function: set-annotation-face annotation face

Set the face associated with annotation to face.

Function: annotations-in-region start end buffer

Return a list of all annotations in buffer which are between start and end inclusively.

Function: annotation-at &optional position buffer

Return 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

Returns a list of all annotations in buffer. If buffer is nil, the current buffer is used.

Function: all-annotations

Returns a list of all annotations in all buffers in existence.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Margin Primitives

It is possible to set values for both a left and a right hand side margin. Only the left side has been implemented. All margin settings are buffer-local at the moment.

Function: set-buffer-left-margin-width width &optional buffer

Set the width, in characters, of the left outside margin of buffer to width. If buffer is nil, the current buffer is used. Returns the new width.

Function: set-buffer-right-margin-width width &optional buffer

Set the width, in characters, of the right outside margin of buffer to width. If buffer is nil, the current buffer is used. Returns the new width.

Function: buffer-left-margin-width &optional buffer

Return the width of the left outside margin, in characters, of buffer. If buffer is nil, the current buffer is used.

Function: buffer-right-margin-width &optional buffer

Return the width of the right outside margin, in characters, of buffer. If buffer is nil, the current buffer is used.

Function: buffer-left-margin-pixwidth &optional buffer

Return the width of the left outside margin, in pixels, of buffer. If buffer is nil, the current buffer is used.

Function: buffer-right-margin-pixwidth &optional buffer

Return the width of the right outside margin, in pixels, of buffer. If buffer is nil, the current buffer is used.

Variable: use-left-overflow

If non-nil use the left outside margin as extra whitespace when displaying whitespace and inside-margin annotations. Defaults to nil.

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 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 hook is called immediately after an annotation is destroyed. It may contain any number of functions to run. No arguments are passed to any of the functions on the hook.

make-annotation-hook

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


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on December 6, 2024 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on December 6, 2024 using texi2html 5.0.