diff options
Diffstat (limited to 'doc/lispref/display.texi')
| -rw-r--r-- | doc/lispref/display.texi | 95 |
1 files changed, 79 insertions, 16 deletions
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 93e935ccf86..7ab2896778d 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -646,9 +646,9 @@ If the value is zero, then command input is not echoed. @defvar message-truncate-lines Normally, displaying a long message resizes the echo area to display -the entire message. But if the variable @code{message-truncate-lines} -is non-@code{nil}, the echo area does not resize, and the message is -truncated to fit it. +the entire message, wrapping long line as needed. But if the variable +@code{message-truncate-lines} is non-@code{nil}, long lines of +echo-area message are instead truncated to fit the mini-window width. @end defvar The variable @code{max-mini-window-height}, which specifies the @@ -1861,9 +1861,12 @@ from the buffer. @item keymap @cindex keymap of character (and overlays) @kindex keymap @r{(overlay property)} -If this property is non-@code{nil}, it specifies a keymap for a portion of the -text. This keymap is used when the character after point is within the -overlay, and takes precedence over most other keymaps. @xref{Active Keymaps}. +If this property is non-@code{nil}, it specifies a keymap for a +portion of the text. This keymap takes precedence over most other +keymaps (@pxref{Active Keymaps}), and it is used when point is within +the overlay, where the front- +and rear-advance properties define whether the boundaries are +considered as being @emph{within} or not. @item local-map @kindex local-map @r{(overlay property)} @@ -1914,7 +1917,8 @@ This function returns a list of the overlays that overlap the region contains one or more characters in the region; empty overlays (@pxref{Managing Overlays, empty overlay}) overlap if they are at @var{beg}, strictly between @var{beg} and @var{end}, or at @var{end} -when @var{end} denotes the position at the end of the buffer. +when @var{end} denotes the position at the end of the accessible part +of the buffer. @end defun @defun next-overlay-change pos @@ -1965,9 +1969,18 @@ Tables}). The width of a tab character is usually @code{tab-width} (@pxref{Usual Display}). @end defun -@defun string-width string +@defun string-width string &optional from to This function returns the width in columns of the string @var{string}, if it were displayed in the current buffer and the selected window. +Optional arguments @var{from} and @var{to} specify the substring of +@var{string} to consider, and are interpreted as in @code{substring} +(@pxref{Creating Strings}). + +The return value is an approximation: it only considers the values +returned by @code{char-width} for the constituent characters, always +takes a tab character as taking @code{tab-width} columns, ignores +display properties and fonts, etc. For these reasons, we recommend +using @code{window-text-pixel-size}, described below, instead. @end defun @defun truncate-string-to-width string width &optional start-column padding ellipsis ellipsis-text-property @@ -1997,7 +2010,7 @@ the beginning of the result if a multi-column character in If @var{ellipsis} is non-@code{nil}, it should be a string which will replace the end of @var{string} when it is truncated. In this case, -more charcaters will be removed from @var{string} to free enough space +more characters will be removed from @var{string} to free enough space for @var{ellipsis} to fit within @var{width} columns. However, if the display width of @var{string} is less than the display width of @var{ellipsis}, @var{ellipsis} will not be appended to the result. If @@ -2998,9 +3011,10 @@ This function returns non-@code{nil} if face @var{face} specifies a non-@code{nil} @code{:inverse-video} attribute. @end defun -@defun face-extend-p face &optional frame +@defun face-extend-p face &optional frame inherit This function returns non-@code{nil} if face @var{face} specifies -a non-@code{nil} @code{:extend} attribute. +a non-@code{nil} @code{:extend} attribute. The @var{inherit} argument +is passed to @code{face-attribute}. @end defun @@ -4752,6 +4766,7 @@ window on a minibuffer-less frame. @node Display Property @section The @code{display} Property @cindex display specification +@cindex display property @kindex display @r{(text property)} The @code{display} text property (or overlay property) is used to @@ -5289,6 +5304,16 @@ where @var{props} is a property list of alternating keyword symbols and values, including at least the pair @code{:type @var{type}} that specifies the image type. + Image descriptors which define image dimensions, @code{:width}, +@code{:height}, @code{:max-width} and @code{:max-height}, may take +either an integer, which represents the dimension in pixels, or a pair +@code{(@var{value} . em)}, where @var{value} is the dimension's +length in @dfn{ems}@footnote{In typography an em is a distance +equivalent to the height of the type. For example when using 12 point +type 1 em is equal to 12 points. Its use ensures distances and type +remain proportional.}. One em is equivalent to the height of the font +and @var{value} may be an integer or a float. + The following is a list of properties that are meaningful for all image types (there are also properties which are meaningful only for certain image types, as documented in the following subsections): @@ -5392,6 +5417,21 @@ are supported, unless the image type is @code{imagemagick}. Positive values rotate clockwise, negative values counter-clockwise. Rotation is performed after scaling and cropping. +@item :transform-smoothing @var{smooth} +If this is @code{t}, any image transform will have smoothing applied; +if @code{nil}, no smoothing will be applied. The exact algorithm used +is platform dependent, but should be equivalent to bilinear +filtering. Disabling smoothing will use the nearest neighbor +algorithm. + +If this property is not specified, @code{create-image} will use the +@code{image-transform-smoothing} user option to say whether scaling +should be done or not. This option can be @code{nil} (no smoothing), +@code{t} (use smoothing) or a predicate function that's called with +the image object as the only parameter, and should return either +@code{nil} or @code{t}. The default is for down-scaling to apply +smoothing, and for large up-scaling to not apply smoothing. + @item :index @var{frame} @xref{Multi-Frame Images}. @@ -5736,6 +5776,28 @@ Cropping is performed after scaling but before rotation. @cindex SVG images SVG (Scalable Vector Graphics) is an XML format for specifying images. +SVG images support the following additional image descriptor +properties: + +@table @code +@item :foreground @var{foreground} +@var{foreground}, if non-@code{nil}, should be a string specifying a +color, which is used as the image's foreground color. If the value is +@code{nil}, it defaults to the current face's foreground color. + +@item :background @var{background} +@var{background}, if non-@code{nil}, should be a string specifying a +color, which is used as the image's background color if the image +supports transparency. If the value is @code{nil}, it defaults to the +current face's background color. + +@item :css @var{css} +@var{css}, if non-@code{nil}, should be a string specifying the CSS to +override the default CSS used when generating the image. +@end table + +@subsubheading SVG library + If your Emacs build has SVG support, you can create and manipulate these images with the following functions from the @file{svg.el} library. @@ -7041,11 +7103,11 @@ end of the buffer continues from the other end. If @var{display-message} is non-@code{nil}, the button's help-echo string is displayed. Any button with a non-@code{nil} @code{skip} property is skipped over. Returns the button found, and signals an error if no -buttons can be found. If @var{no-error} in non-@code{nil}, return nil +buttons can be found. If @var{no-error} is non-@code{nil}, return nil instead of signaling the error. @end deffn -@deffn Command backward-button n &optional wrap display-message +@deffn Command backward-button n &optional wrap display-message no-error Move to the @var{n}th previous button, or @var{n}th next button if @var{n} is negative. If @var{n} is zero, move to the start of any button at point. If @var{wrap} is non-@code{nil}, moving past either @@ -7053,7 +7115,7 @@ end of the buffer continues from the other end. If @var{display-message} is non-@code{nil}, the button's help-echo string is displayed. Any button with a non-@code{nil} @code{skip} property is skipped over. Returns the button found, and signals an error if no -buttons can be found. If @var{no-error} in non-@code{nil}, return nil +buttons can be found. If @var{no-error} is non-@code{nil}, return nil instead of signaling the error. @end deffn @@ -7558,7 +7620,7 @@ Chars}. The above display conventions apply even when there is a display table, for any character whose entry in the active display table is @code{nil}. Thus, when you set up a display table, you need only -specify the characters for which you want special behavior. +specify the characters for which you want special display behavior. The following variables affect how certain characters are displayed on the screen. Since they change the number of columns the characters @@ -7592,7 +7654,8 @@ command @code{tab-to-tab-stop}. @xref{Indent Tabs}. (@pxref{Char-Tables}), with @code{display-table} as its subtype, which is used to override the usual character display conventions. This section describes how to make, inspect, and assign elements to a -display table object. +display table object. The next section (@pxref{Active Display Table}) +describes the various standard display tables and their precedence. @defun make-display-table This creates and returns a display table. The table initially has |