[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 Extents); but you can work with annotations without knowing how extents work.
51.1 Annotation Basics | Introduction to annotations. | |
51.2 Annotation Primitives | Creating and deleting annotations. | |
51.3 Annotation Properties | Retrieving and changing the characteristics of an annotation. | |
51.5 Margin Primitives | Controlling the size of the margins. | |
51.4 Locating Annotations | Looking for annotations in a buffer. | |
51.6 Annotation Hooks | Hooks called at certain times during an annotation’s lifetime. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
This is a glyph object and is used as the displayed representation of the annotation.
If given, this glyph is used as the displayed representation of the annotation when the mouse is pressed down over the annotation.
The face with which to display the glyph.
Which side of the text (left or right) the annotation is displayed at.
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.
Not used internally. This field can contain any E-Lisp object. It is passed as the first argument to action described above.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
This function removes annotation from its buffer. This does not modify the buffer text.
This function returns t
if annotation is an annotation,
nil
otherwise.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This function returns the glyph object used to display annotation.
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.
This function returns the glyph used to display annotation when the left mouse button is depressed on the annotation.
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.
This function returns the face associated with annotation.
This function sets the face associated with annotation to face.
This function returns the layout policy of annotation.
This function sets the layout policy of annotation to layout.
This function returns the side of the buffer that annotation is
displayed on. Return value is a symbol, either left
or
right
.
This function returns the data associated with annotation.
This function sets the data field of annotation to data. data is returned.
This function returns the action associated with annotation.
This function sets the action field of annotation to action. action is returned..
This function returns the menu associated with annotation.
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.
This function returns t
if there is enough available space to
display annotation, nil
otherwise.
This function returns the width of annotation in pixels.
This function removes annotation’s glyph, making it invisible.
This function restores annotation’s glyph, making it visible.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This function returns a list of all annotations in buffer which are between start and end inclusively.
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.
This function returns a list of all annotations in buffer. If
buffer is nil
, the current buffer is used.
This function returns a list of all annotations in all buffers in existence.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 Specifiers.
This is a specifier variable controlling the width of the left outside
margin, in characters. Use set-specifier
to change its value.
This is a specifier variable controlling the width of the right outside
margin, in characters. Use set-specifier
to change its value.
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.
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.
This function returns the width in pixels of the left outside margin of
window. If window is nil
, the selected window is
assumed.
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.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.