A buffer can have blank areas called display margins on the
left and on the right. Ordinary text never appears in these areas,
but you can put things into the display margins using the
display property. There is currently no way to make text or
images in the margin mouse-sensitive.
The way to display something in the margins is to specify it in a
margin display specification in the
display property of some
text. This is a replacing display specification, meaning that the
text you put it on does not get displayed; the margin display appears,
but that text does not.
A margin display specification looks like
right-margin) spec) or
((margin left-margin) spec).
Here, spec is another display specification that says what to
display in the margin. Typically it is a string of text to display,
or an image descriptor.
To display something in the margin in association with
certain buffer text, without altering or preventing the display of
that text, put a
before-string property on the text and put the
margin display specification on the contents of the before-string.
Before the display margins can display anything, you must give them a nonzero width. The usual way to do that is to set these variables:
This variable specifies the width of the left margin, in character
cell (a.k.a. “column”) units. It is buffer-local in all buffers.
A value of
nil means no left marginal area.
This variable specifies the width of the right margin, in character
cell units. It is buffer-local in all buffers. A value of
means no right marginal area.
Setting these variables does not immediately affect the window. These
variables are checked when a new buffer is displayed in the window.
Thus, you can make changes take effect by calling
You can also set the margin widths immediately.
This function specifies the margin widths for window window, in
character cell units. The argument left controls the left
margin, and right controls the right margin (default
This function returns the width of the left and right margins of
window as a cons cell of the form
(left . right). If one of the two marginal areas does not exist,
its width is returned as
nil; if neither of the two margins exist,
the function returns
(nil). If window is
selected window is used.