[ << ] | [ < ] | [ 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 are implemented using extents (@pxref{Extents}); but you can work with annotations without knowing how extents work.
1.1 Annotation Basics | ||
1.2 Annotation Primitives | ||
1.3 Margin Primitives | ||
1.4 Annotation Hooks |
[ << ] | [ < ] | [ 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 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:
This may be either a bitmap/pixmap object or a string.
The face with which to display the glyph.
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.
Not used internally. This field can contain any Elisp object. It is passed as the lone argument to action described above.
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] | [ ? ] |
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.
Remove annotation from its buffer. This does not modify the buffer text. Returns the annotation deleted.
Return t
if annotation is an annotation, nil
otherwise.
Return t
if there is enough available space to display
annotation, nil
otherwise.
Return the annotation at position in buffer. If
position is nil
point is used. If buffer is
nil
the current buffer is used.
Return the layout policy of annotation.
Set the layout policy of annotation to layout.
Returns the display type of annotation. The type will be one of following symbols:
pixmap
bitmap
string
nil (object is not an annotation)
Return the width of annotation in pixels.
If annotation is of type string
return the string.
Otherwise return the bitmap or pixmap object of the glyph representing
annotation.
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
.
Return the data associated with annotation.
Set the data field of annotation to data. Returns data.
Return the action associated with annotation.
Set the action field of annotation to action. Returns action.
Return the face associated with annotation.
Set the face associated with annotation to face.
Return a list of all annotations in buffer which are between start and end inclusively.
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.
Returns a list of all annotations in buffer. If buffer
is nil
, the current buffer is used.
Returns a list of all annotations in all buffers in existence.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
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.
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.
Return the width of the left outside margin, in characters, of
buffer. If buffer is nil
, the current buffer is
used.
Return the width of the right outside margin, in characters, of
buffer. If buffer is nil
, the current buffer is
used.
Return the width of the left outside margin, in pixels, of buffer.
If buffer is nil
, the current buffer is used.
Return the width of the right outside margin, in pixels, of
buffer. If buffer is nil
, the current buffer is
used.
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] | [ ? ] |
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] | [ ? ] |
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.