diff options
Diffstat (limited to 'devdocs/elisp/display-margins.html')
| -rw-r--r-- | devdocs/elisp/display-margins.html | 17 |
1 files changed, 17 insertions, 0 deletions
diff --git a/devdocs/elisp/display-margins.html b/devdocs/elisp/display-margins.html new file mode 100644 index 00000000..d4b5e42a --- /dev/null +++ b/devdocs/elisp/display-margins.html @@ -0,0 +1,17 @@ + <h4 class="subsection">Displaying in the Margins</h4> <p>A buffer can have blank areas called <em>display margins</em> 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 <code>display</code> property. There is currently no way to make text or images in the margin mouse-sensitive. </p> <p>The way to display something in the margins is to specify it in a margin display specification in the <code>display</code> 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. </p> <p>A margin display specification looks like <code>((margin +right-margin) <var>spec</var>)</code> or <code>((margin left-margin) <var>spec</var>)</code>. Here, <var>spec</var> 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. </p> <p>To display something in the margin <em>in association with</em> certain buffer text, without altering or preventing the display of that text, put a <code>before-string</code> property on the text and put the margin display specification on the contents of the before-string. </p> <p>Note that if the string to be displayed in the margin doesn’t specify a face, its face is determined using the same rules and priorities as it is for strings displayed in the text area (see <a href="displaying-faces">Displaying Faces</a>). If this results in undesirable “leaking” of faces into the margin, make sure the string has an explicit face specified for it. </p> <p>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: </p> <dl> <dt id="left-margin-width">Variable: <strong>left-margin-width</strong> +</dt> <dd><p>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 <code>nil</code> means no left marginal area. </p></dd> +</dl> <dl> <dt id="right-margin-width">Variable: <strong>right-margin-width</strong> +</dt> <dd><p>This variable specifies the width of the right margin, in character cell units. It is buffer-local in all buffers. A value of <code>nil</code> means no right marginal area. </p></dd> +</dl> <p>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 <code>set-window-buffer</code>. Do not use these variables to try to determine the current width of the left or right margin. Instead, use the function <code>window-margins</code>. </p> <p>You can also set the margin widths immediately. </p> <dl> <dt id="set-window-margins">Function: <strong>set-window-margins</strong> <em>window left &optional right</em> +</dt> <dd> +<p>This function specifies the margin widths for window <var>window</var>, in character cell units. The argument <var>left</var> controls the left margin, and <var>right</var> controls the right margin (default <code>0</code>). </p> <p>If <var>window</var> is not large enough to accommodate margins of the desired width, this leaves the margins of <var>window</var> unchanged. </p> <p>The values specified here may be later overridden by invoking <code>set-window-buffer</code> (see <a href="buffers-and-windows">Buffers and Windows</a>) on <var>window</var> with its <var>keep-margins</var> argument <code>nil</code> or omitted. </p> +</dd> +</dl> <dl> <dt id="window-margins">Function: <strong>window-margins</strong> <em>&optional window</em> +</dt> <dd><p>This function returns the width of the left and right margins of <var>window</var> as a cons cell of the form <code>(<var>left</var> . <var>right</var>)</code>. If one of the two marginal areas does not exist, its width is returned as <code>nil</code>; if neither of the two margins exist, the function returns <code>(nil)</code>. If <var>window</var> is <code>nil</code>, the selected window is used. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br> + <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Display-Margins.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Display-Margins.html</a> + </p> +</div> |