diff options
Diffstat (limited to 'doc/lispref/display.texi')
| -rw-r--r-- | doc/lispref/display.texi | 754 |
1 files changed, 665 insertions, 89 deletions
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b068c7d08c6..69b752688ea 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -27,6 +27,7 @@ that Emacs presents to the user. * Window Dividers:: Separating windows visually. * Display Property:: Images, margins, text size, etc. * Images:: Displaying images in Emacs buffers. +* Icons:: Displaying icons in Emacs buffers. * Xwidgets:: Displaying native widgets in Emacs buffers. * Buttons:: Adding clickable buttons to Emacs buffers. * Abstract Display:: Emacs's Widget for Object Collections. @@ -336,7 +337,10 @@ functions call it with no arguments when their argument message is Usually this function is called when the next input event arrives after displaying an echo-area message. The function is expected to clear the message displayed by its counterpart function specified by -@code{set-message-function}. +@code{set-message-function}, but doesn't have to. If the function +wants the echo area to remain uncleared, it should return the symbol +@code{dont-clear-message}; any other value will result in the echo +area being cleared. The default value is the function that clears the message displayed in an active minibuffer. @@ -561,6 +565,26 @@ You can rewrite the previous example with this macro as follows: @end example @end defmac +@defmac with-delayed-message (timeout message) body@dots{} +Sometimes it's unclear whether an operation will take a long time to +execute or not, or it can be inconvenient to implement a progress +reporter. This macro can be used in those situations. + +@lisp +(with-delayed-message (2 (format "Gathering data for %s" entry)) + (setq data (gather-data entry))) +@end lisp + +In this example, if the body takes more than two seconds to execute, +the message will be displayed. If it takes a shorter time than that, +the message won't be displayed. In either case, the body is evaluated +as normally, and the return value of the final element in the body is +the return value of the macro. + +The @var{message} element is evaluated before @var{body}, and is +always evaluated, whether the message is displayed or not. +@end defmac + @node Logging Messages @subsection Logging Messages in @file{*Messages*} @cindex logging echo-area messages @@ -592,6 +616,16 @@ how to display a message and prevent it from being logged: @end example @end defopt +@defvar messages-buffer-name +This variable has the name of the buffer where messages should be +logged to, and defaults to @file{*Messages*}. Some packages may find +it useful to temporarily redirect the output to a different buffer +(perhaps to write the buffer out to a log file later), and they can +bind this variable to a different buffer name. (Note that this buffer +(if it doesn't exist already), will be created and put into +@code{messages-buffer-mode}.) +@end defvar + To make @file{*Messages*} more convenient for the user, the logging facility combines successive identical messages. It also combines successive related messages for the sake of two cases: question @@ -1334,6 +1368,11 @@ are not resized. By default, this mode uses @code{fit-window-to-buffer} (@pxref{Resizing Windows}) for resizing. You can specify a different function by customizing the options @code{temp-buffer-max-height} and @code{temp-buffer-max-width} below. + +The effect of this option can be overridden by providing a suitable +@code{window-height}, @code{window-width} or @code{window-size} action +alist entry for @code{display-buffer} (@pxref{Buffer Display Action +Alists}). @end defopt @defopt temp-buffer-max-height @@ -1972,6 +2011,11 @@ Tables}). The width of a tab character is usually @code{tab-width} (@pxref{Usual Display}). @end defun +@defun char-uppercase-p char +Return non-@code{nil} if @var{char} is an uppercase character +according to Unicode. +@end defun + @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. @@ -1983,7 +2027,8 @@ 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. +using @code{window-text-pixel-size} or @code{string-pixel-width}, +described below, instead. @end defun @defun truncate-string-to-width string width &optional start-column padding ellipsis ellipsis-text-property @@ -2060,23 +2105,33 @@ displayed in a given window. This function is used by (@pxref{Resizing Windows}) to make a window exactly as large as the text it contains. -@defun window-text-pixel-size &optional window from to x-limit y-limit mode-lines +@defun window-text-pixel-size &optional window from to x-limit y-limit mode-lines ignore-line-at-end This function returns the size of the text of @var{window}'s buffer in pixels. @var{window} must be a live window and defaults to the selected one. The return value is a cons of the maximum pixel-width of any text line and the maximum pixel-height of all text lines. This function exists to allow Lisp programs to adjust the dimensions of -@var{window} to the buffer text it needs to display. +@var{window} to the buffer text it needs to display, and for other +similar situations. + +The return value can also optionally (see below) include the buffer +position of the first line whose dimensions were measured. The optional argument @var{from}, if non-@code{nil}, specifies the first text position to consider, and defaults to the minimum accessible position of the buffer. If @var{from} is @code{t}, it stands for the minimum accessible position that is not a newline -character. The optional argument @var{to}, if non-@code{nil}, -specifies the last text position to consider, and defaults to the -maximum accessible position of the buffer. If @var{to} is @code{t}, -it stands for the maximum accessible position that is not a newline -character. +character. If @var{from} is a cons, its @code{car} specifies a buffer +position, and its @code{cdr} specifies the vertical offset in pixels +from that position to the first screen line whose text is to be +measured. (The measurement will start from the visual beginning of +that screen line.) In that case, the return value will instead be a +list of the pixel-width, pixel-height, and the buffer position of the +first line that was measured. The optional argument @var{to}, if +non-@code{nil}, specifies the last text position to consider, and +defaults to the maximum accessible position of the buffer. If +@var{to} is @code{t}, it stands for the maximum accessible position +that is not a newline character. The optional argument @var{x-limit}, if non-@code{nil}, specifies the maximum X coordinate beyond which text should be ignored; it is @@ -2096,7 +2151,7 @@ the buffer might contain long lines that will be truncated anyway. The optional argument @var{y-limit}, if non-@code{nil}, specifies the maximum Y coordinate beyond which text is to be ignored; it is therefore also the maximum pixel-height that the function can return. -If @var{y-limit} is nil or omitted, it means to considers all the +If @var{y-limit} is @code{nil} or omitted, it means to consider all the lines of text till the buffer position specified by @var{to}. Since calculating the pixel-height of a large buffer can take some time, it makes sense to specify this argument; in particular, if the caller @@ -2110,6 +2165,12 @@ line, if present, in the return value. If it is @code{t}, include the height of all of these lines, if present, in the return value. @end defun +The optional argument @var{ignore-line-at-end} controls whether or +not to count the height of text in @var{to}'s screen line as part of +the returned pixel-height. This is useful if your Lisp program is +only interested in the dimensions of text up to and excluding the +visual beginning of @var{to}'s screen line. + @code{window-text-pixel-size} treats the text displayed in a window as a whole and does not care about the size of individual lines. The following function does. @@ -2175,12 +2236,59 @@ though when this function is run from an idle timer with a delay of zero seconds. @end defun +@defun buffer-text-pixel-size &optional buffer-or-name window from to x-limit y-limit +This is much like @code{window-text-pixel-size}, but can be used when +the buffer isn't shown in a window. (@code{window-text-pixel-size} is +faster when it is, so this function shouldn't be used in that case.) + +@var{buffer-or-name} must specify a live buffer or the name of a live +buffer and defaults to the current buffer. @var{window} must be a +live window and defaults to the selected one; the function will +compute the text dimensions as if @var{buffer} is displayed in +@var{window}. The return value is a cons of the maximum pixel-width +of any text line and the pixel-height of all the text lines of the +buffer specified by @var{buffer-or-name}. + +The optional arguments @var{x-limit} and @var{y-limit} have the same +meaning as with @code{window-text-pixel-size}. +@end defun + +@defun string-pixel-width string +This is a convenience function that uses @code{window-text-pixel-size} +to compute the width of @var{string} (in pixels). +@end defun + @defun line-pixel-height This function returns the height in pixels of the line at point in the selected window. The value includes the line spacing of the line (@pxref{Line Height}). @end defun +@cindex grapheme cluster +@defun string-glyph-split string +When character compositions are in effect, sequence of characters can +be composed for display to form @dfn{grapheme clusters}, for example +to display accented characters, or ligatures, or Emoji, or when +complex text shaping requires that for some scripts. When that +happens, characters no longer map in a simple way to display columns, +and display layout decisions with such strings, such as truncating too +wide strings, can be a complex job. This function helps in performing +suvh jobs: it splits up its argument @var{string} into a list of +substrings, where each substring produces a single grapheme cluster +that should be displayed as a unit. Lisp programs can then use this +list to construct visually-valid substrings of @var{string} which will +look correctly on display, or compute the width of any substring of +@var{string} by adding the width of its constituents in the returned +list, etc. + +For instance, if you want to display a string without the first glyph, +you can say: + +@example +(apply #'insert (cdr (string-glyph-split string)))) +@end example +@end defun + When a buffer is displayed with line numbers (@pxref{Display Custom,,, emacs, The GNU Emacs Manual}), it is sometimes useful to know the width taken for displaying the line numbers. The following function @@ -2367,13 +2475,22 @@ Otherwise, it returns @code{nil}. The following table lists all the face attributes, their possible values, and their effects. +@cindex unspecified, face attribute value Apart from the values given below, each face attribute can have the value @code{unspecified}. This special value means that the face doesn't specify that attribute directly. An @code{unspecified} attribute tells Emacs to refer instead to a parent face (see the description @code{:inherit} attribute below); or, failing that, to an -underlying face (@pxref{Displaying Faces}). The @code{default} face -must specify all attributes. +underlying face (@pxref{Displaying Faces}). (However, +@code{unspecified} is not a valid value in @code{defface}.) + +@cindex reset, face attribute value + A face attribute can also have the value @code{reset}. This special +value stands for the value of the corresponding attribute of the +@code{default} face. + + The @code{default} face must explicitly specify all attributes, and +cannot use the special value @code{reset}. Some of these attributes are meaningful only on certain kinds of displays. If your display cannot handle a certain attribute, the @@ -2394,8 +2511,9 @@ GNU Emacs Manual}. @item :width Relative character width. This should be one of the symbols @code{ultra-condensed}, @code{extra-condensed}, @code{condensed}, -@code{semi-condensed}, @code{normal}, @code{semi-expanded}, -@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}. +@code{semi-condensed}, @code{normal}, @code{regular}, @code{medium}, +@code{semi-expanded}, @code{expanded}, @code{extra-expanded}, or +@code{ultra-expanded}. @item :height The height of the font. In the simplest case, this is an integer in @@ -2463,13 +2581,16 @@ Underline with the foreground color of the face. @item @var{color} Underline in color @var{color}, a string specifying a color. -@item @code{(:color @var{color} :style @var{style})} +@item @code{(:color @var{color} :style @var{style} :position @var{position})} @var{color} is either a string, or the symbol @code{foreground-color}, meaning the foreground color of the face. Omitting the attribute @code{:color} means to use the foreground color of the face. @var{style} should be a symbol @code{line} or @code{wave}, meaning to use a straight or wavy line. Omitting the attribute @code{:style} -means to use a straight line. +means to use a straight line. @var{position}, if non-nil, means to +display the underline at the descent of the text, instead of at the +baseline level. If it is a number, then it specifies the amount of +pixels above the descent to display the underline. @end table @cindex overlined text @@ -2502,14 +2623,17 @@ Draw a box with lines of width 1, in the foreground color. Draw a box with lines of width 1, in color @var{color}. @item @code{(:line-width (@var{vwidth} . @var{hwidth}) :color @var{color} :style @var{style})} -This way you can explicitly specify all aspects of the box. The values -@var{vwidth} and @var{hwidth} specifies respectively the width of the -vertical and horizontal lines to draw; they default to (1 . 1). -A negative horizontal or vertical width @minus{}@var{n} means to draw a line -of width @var{n} that occupies the space of the underlying text, thus -avoiding any increase in the character height or width. For simplification -the width could be specified with only a single number @var{n} instead -of a list, such case is equivalent to @code{((abs @var{n}) . @var{n})}. +You can explicitly specify all aspects of the box with a plist on this +form. Any element in this plist can be omitted. + +The values @var{vwidth} and @var{hwidth} specifies respectively the +width of the vertical and horizontal lines to draw; they default to (1 +. 1). A negative horizontal or vertical width @minus{}@var{n} means +to draw a line of width @var{n} that occupies the space of the +underlying text, thus avoiding any increase in the character height or +width. For simplification the width could be specified with only a +single number @var{n} instead of a list, such case is equivalent to +@code{((abs @var{n}) . @var{n})}. The value @var{style} specifies whether to draw a 3D box. If it is @code{released-button}, the box looks like a 3D button that is not @@ -2717,8 +2841,9 @@ apply to. Here are the possible values of @var{characteristic}: @item type The kind of window system the terminal uses---either @code{graphic} (any graphics-capable display), @code{x}, @code{pc} (for the MS-DOS -console), @code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} (a -non-graphics-capable display). @xref{Window Systems, window-system}. +console), @code{w32} (for MS Windows 9X/NT/2K/XP), @code{haiku} (for +Haiku), @code{pgtk} (for pure GTK), or @code{tty} (a non-graphics-capable +display). @xref{Window Systems, window-system}. @item class What kinds of colors the terminal supports---either @code{color}, @@ -3232,6 +3357,16 @@ if you need to remove the remapping later. ;; Increase the size of the 'default' face by 50%: (face-remap-add-relative 'default :height 1.5) @end example + +Note that buffer-local face remapping does not work reliably for +parent faces of basic faces (@pxref{Basic Faces}). (These are the +faces that are used in mode lines, header lines, and other basic +decorations of windows and frames.) For instance, +@code{mode-line-inactive} inherits from @code{mode-line}, but +remapping @code{mode-line} won't normally have the desired effect on +@code{mode-line-inactive}, especially if done locally for some +buffers. Instead you have to remap @code{mode-line-inactive} +directly. @end defun @defun face-remap-remove-relative cookie @@ -3348,6 +3483,12 @@ function finishes are the ones that really matter. For efficiency, we recommend writing these functions so that they usually assign faces to around 400 to 600 characters at each call. + +When the buffer text includes very long lines, these functions are +called with the buffer narrowed to a relatively small region around +@var{pos}, and with narrowing locked, so the functions cannot use +@code{widen} to gain access to the rest of the buffer. +@xref{Narrowing}. @end defvar @node Basic Faces @@ -3357,10 +3498,10 @@ usually assign faces to around 400 to 600 characters at each call. If your Emacs Lisp program needs to assign some faces to text, it is often a good idea to use certain existing faces or inherit from them, rather than defining entirely new faces. This way, if other users -have customized the basic faces to give Emacs a certain look, your -program will fit in without additional customization. +have customized those existing faces to give Emacs a certain look, +your program will fit in without additional customization. - Some of the basic faces defined in Emacs are listed below. In + Some of the @dfn{basic faces} defined in Emacs are listed below. In addition to these, you might want to make use of the Font Lock faces for syntactic highlighting, if highlighting is not already handled by Font Lock mode, or if some Font Lock faces are not in use. @@ -3372,6 +3513,28 @@ The default face, whose attributes are all specified. All other faces implicitly inherit from it: any unspecified attribute defaults to the attribute on this face (@pxref{Face Attributes}). +@item mode-line-active +@itemx mode-line-inactive +@itemx header-line +@itemx tab-line +Basic faces used for the mode line, header line, and tab line. + +@item tool-bar +@itemx tab-bar +@itemx fringe +@itemx scroll-bar +@itemx window-divider +@itemx border +@itemx child-frame-border +Basic faces used for the corresponding decorations of GUI frames. + +@item cursor +The basic face used for the text cursor. + +@item mouse +The basic face used for displaying mouse-sensitive text when the mouse +pointer is on that text. + @item bold @itemx italic @itemx bold-italic @@ -4466,6 +4629,7 @@ Used to indicate buffer boundaries. Used for different types of fringe cursors. @item @code{exclamation-mark}, @code{question-mark} +@itemx @code{large-circle} Not used by core Emacs features. @end table @@ -4859,9 +5023,7 @@ window on a minibuffer-less frame. The @code{display} text property (or overlay property) is used to insert images into text, and to control other aspects of how text -displays. The value of the @code{display} property should be a -display specification, or a list or vector containing several display -specifications. Display specifications in the same @code{display} +displays. Display specifications in the same @code{display} property value generally apply in parallel to the text they cover. If several sources (overlays and/or a text property) specify values @@ -4869,6 +5031,50 @@ for the @code{display} property, only one of the values takes effect, following the rules of @code{get-char-property}. @xref{Examining Properties}. + The value of the @code{display} property should be a display +specification, or a list or vector containing several display +specifications. + +@defun get-display-property position prop &optional object properties +This convenience function can be used to get a specific display +property, no matter whether the @code{display} property is a vector, a +list or a simple property. This is like @code{get-text-property} +(@pxref{Examining Properties}), but works on the @code{display} +property only. + +@var{position} is the position in the buffer or string to examine, and +@var{prop} is the @code{display} property to return. The optional +@var{object} argument should be either a string or a buffer, and +defaults to the current buffer. If the optional @var{properties} +argument is non-@code{nil}, it should be a @code{display} property, +and in that case, @var{position} and @var{object} are ignored. (This +can be useful if you've already gotten the @code{display} property +with @code{get-char-property}, for instance (@pxref{Examining +Properties}). +@end defun + +@defun add-display-text-property start end prop value &optional object +Add @code{display} property @var{prop} of @var{value} to the text from +@var{start} to @var{end}. + +If any text in the region has a non-@code{nil} @code{display} +property, those properties are retained. For instance: + +@lisp +(add-display-text-property 4 8 'height 2.0) +(add-display-text-property 2 12 'raise 0.5) +@end lisp + +After doing this, the region from 2 to 4 will have the @code{raise} +@code{display} property, the region from 4 to 8 will have both the +@code{raise} and @code{height} @code{display} properties, and finally +the region from 8 to 12 will only have the @code{raise} @code{display} +property. + +If @var{object} is non-@code{nil}, it should be a string or a buffer. +If @code{nil}, this defaults to the current buffer. +@end defun + @cindex display property, unsafe evaluation @cindex security, and display specifications Some of the display specifications allow inclusion of Lisp forms, @@ -5144,6 +5350,24 @@ text that has the specification. It displays all of these spaces be an integer or float. Characters other than spaces are not affected at all; in particular, this has no effect on tab characters. +@item (min-width (@var{width})) +This display specification ensures the text that has it takes at least +@var{width} space on display, by adding a stretch of white space to +the end of the text if the text is shorter than @var{width}. The text +is partitioned using the identity of the parameter, which is why the +parameter is a list with one element. For instance: + +@lisp +(insert (propertize "foo" 'display '(min-width (6.0)))) +@end lisp + +This will add padding after @samp{foo} bringing the total width up to +the width of six normal characters. Note that the affected characters +are identified by the @code{(6.0)} list in the display property, +compared with @code{eq}. The element @var{width} can be either an +integer or a float specifying the required minimum width of the text +(@pxref{Pixel Specification}). + @item (height @var{height}) This display specification makes the text taller or shorter. Here are the possibilities for @var{height}: @@ -5344,13 +5568,19 @@ to modify the set of known names for these dynamic libraries. Supported image formats (and the required support libraries) include PBM and XBM (which do not depend on support libraries and are always available), XPM (@code{libXpm}), GIF (@code{libgif} or -@code{libungif}), JPEG (@code{libjpeg}), TIFF -(@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}). +@code{libungif}), JPEG (@code{libjpeg}), TIFF (@code{libtiff}), PNG +(@code{libpng}), SVG (@code{librsvg}), and WebP (@code{libwebp}). Each of these image formats is associated with an @dfn{image type symbol}. The symbols for the above formats are, respectively, -@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, -@code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. +@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{jpeg}, +@code{tiff}, @code{png}, @code{svg}, and @code{webp}. + + On some platforms, the built-in image support that doesn't require +any optional libraries includes BMP images.@footnote{ +On MS-Windows, this requires @code{w32-use-native-image-API} to be set +non-@code{nil}. +} Furthermore, if you build Emacs with ImageMagick (@code{libMagickWand}) support, Emacs can display any image format @@ -5505,6 +5735,12 @@ 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 :flip @var{flip} +If this is @code{t}, the image will be horizontally flipped. +Currently it has no effect if the image type is @code{imagemagick}. +Vertical flipping can be achieved by rotating the image 180 degrees +and toggling this value. + @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 @@ -5653,6 +5889,14 @@ When you click the mouse when the mouse pointer is over a hot-spot, an event is composed by combining the @var{id} of the hot-spot with the mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's @var{id} is @code{area4}. + +Note that the map's coordinates should reflect the displayed image +after all transforms have been done (rotation, scaling and so on), and +also note that Emacs (by default) performs auto-scaling of images, so +to make things match up, you should either specify @code{:scale 1.0} +when creating the image, or use the result of +@code{image-compute-scaling-factor} to compute the elements of the +map. @end table @defun image-mask-p spec &optional frame @@ -5718,13 +5962,10 @@ There are three formats you can use for @var{data}: @itemize @bullet @item A vector of strings or bool-vectors, each specifying one line of the -image. Do specify @code{:height} and @code{:width}. +image. Do specify @code{:data-height} and @code{:data-width}. @item A string containing the same byte sequence as an XBM file would contain. -You must not specify @code{:height} and @code{:width} in this case, -because omitting them is what indicates the data has the format of an -XBM file. The file contents specify the height and width of the image. @item A string or a bool-vector containing the bits of the image (plus @@ -5732,26 +5973,11 @@ perhaps some extra bits at the end that will not be used). It should contain at least @w{@code{@var{stride} * @var{height}}} bits, where @var{stride} is the smallest multiple of 8 greater than or equal to the width of the image. In this case, you should specify -@code{:height}, @code{:width} and @code{:stride}, both to indicate -that the string contains just the bits rather than a whole XBM file, -and to specify the size of the image. +@code{:data-height}, @code{:data-width} and @code{:stride}, both to +indicate that the string contains just the bits rather than a whole +XBM file, and to specify the size of the image. @end itemize -@item :width @var{width} -The value, @var{width}, specifies the width of the image, in pixels. - -@item :height @var{height} -The value, @var{height}, specifies the height of the image, in pixels. - -Note that @code{:width} and @code{:height} can only be used if passing -in data that doesn't specify the width and height (e.g., a string or a -vector containing the bits of the image). @acronym{XBM} files usually -specify this themselves, and it's an error to use these two properties -on these files. Also note that @code{:width} and @code{:height} are -used by most other image formats to specify what the displayed image -is supposed to be, which usually means performing some sort of -scaling. This isn't supported for @acronym{XBM} images. - @item :stride @var{stride} The number of bool vector entries stored for each row; the smallest multiple of 8 greater than or equal to @var{width}. @@ -6354,6 +6580,9 @@ Image type @code{png}. @item TIFF Image type @code{tiff}. Supports the @code{:index} property. @xref{Multi-Frame Images}. + +@item WebP +Image type @code{webp}. @end table @node Defining Images @@ -6505,7 +6734,7 @@ will compute a scaling factor based on the font pixel size. property yourself, but it is easier to use the functions in this section. -@defun insert-image image &optional string area slice +@defun insert-image image &optional string area slice inhibit-isearch This function inserts @var{image} in the current buffer at point. The value @var{image} should be an image descriptor; it could be a value returned by @code{create-image}, or the value of a symbol defined with @@ -6532,7 +6761,9 @@ image. Internally, this function inserts @var{string} in the buffer, and gives it a @code{display} property which specifies @var{image}. @xref{Display -Property}. +Property}. By default, doing interactive searches in the buffer will +consider @var{string} when searching. If @var{inhibit-isearch} is +non-@code{nil}, this is inhibited. @end defun @cindex slice, image @@ -6608,6 +6839,11 @@ cache, it can always be displayed, even if the value of @code{max-image-size} is subsequently changed (@pxref{Image Cache}). @end defvar +@defun image-at-point-p +This function returns @code{t} if point is on an image, and @code{nil} +otherwise. +@end defun + Images inserted with the insertion functions above also get a local keymap installed in the text properties (or overlays) that span the displayed image. This keymap defines the following commands: @@ -6762,6 +6998,165 @@ bytes. An image of size 200x100 with 24 bits per color will have a cache size of 60000 bytes, for instance. @end defun +@node Icons +@section Icons + +Emacs sometimes uses buttons (for clicking on) or small graphics (to +illustrate something). Since Emacs is available on a wide variety of +systems with different capabilities, and users have different +preferences, Emacs provides a facility to handle this in a convenient +way, allowing customization, graceful degradation, accessibility, as +well as themability: @dfn{Icons}. + +The central macro here is @code{define-icon}, and here's a simple +example: + +@lisp +(define-icon outline-open button + '((image "right.svg" "open.xpm" "open.pbm" :height line) + (emoji "▶️") + (symbol "▶" "➤") + (text "open" :face icon-button)) + "Icon used for buttons for opening a section in outline buffers." + :version "29.1" + :help-echo "Open this section") +@end lisp + +Which alternative will actually be displayed depends on the value of +the user option @code{icon-preference} (@pxref{Icons,,, emacs, The GNU +Emacs Manual}) and on the results of run-time checks for what the +current frame's terminal can actually display. + +The macro in the example above defines @code{outline-open} as an icon, +and inherits properties from the icon called @code{button} (so this is +meant as a clickable button to be inserted in a buffer). It is +followed by a list of @dfn{icon types} along with the actual icon +shapes themselves. In addition, there's a doc string and various +keywords that contain additional information and properties. + +To instantiate an icon, you use @code{icon-string}, which will +consult the current Customize theming, and the @code{icon-preference} +user option, and finally what the Emacs is able to actually display. +If @code{icon-preference} is @code{(image emoji symbol text)} (i.e., +allowing all of these forms of icons), in this case, +@code{icon-string} will first check that Emacs is able to display +images at all, and then whether it has support for each of those +different image formats. If that fails, Emacs will check whether +Emacs can display emojis (in the current frame). If that fails, it'll +check whether it can display the symbol in question. If that fails, +it'll use the plain text version. + +For instance, if @code{icon-preference} doesn't contain @code{image} +or @code{emoji}, it'll skip those entries. + +Code can confidently call @code{icon-string} in all circumstances and +be sure that something readable will appear on the screen, no +matter whether the user is on a graphical terminal or a text terminal, +and no matter which features Emacs was built with. + +@defmac define-icon name parent specs doc &rest keywords +Define an icon @var{name}, a symbol, with the display alternatives in +@var{spec}, that can be later instantiated using @code{icon-string}. +The @var{name} is the name of the resulting keyword. + +The resulting icon will inherit specs from @var{parent}, and from +their parent's parents, and so on, and the lowest descendent element +wins. + +@var{specs} is a list of icon specifications. The first element of each +specification is the type, and the rest is something that can be used +as an icon of that type, and then optionally followed by a keyword +list. The following icon types are available: + +@cindex icon types +@table @code +@item image +In this case, there may be many images listed as candidates. Emacs +will choose the first one that the current Emacs instance can show. +If an image is listed is an absolute file name, it's used as is, but it's +otherwise looked up in the list @code{image-load-path} +(@pxref{Defining Images}). + +@item emoji +This should be a (possibly colorful) emoji. + +@item symbol +This should be a (monochrome) symbol character. + +@item text +Icons should also have a textual fallback. This can also be used for +the visually impaired: if @code{icon-preference} is just +@code{(text)}, all icons will be replaced by text. +@end table + +Various keywords may follow the list of icon specifications. For +instance: + +@example +(symbol "▶" "➤" :face icon-button) +@end example + +Unknown keywords are ignored. The following keywords are allowed: + +@cindex icon keywords +@table @code +@item :face +The face to be used for the icon. + +@item :height +This is only valid for @code{image} icons, and can be either a number +(which specifies the height in pixels), or the symbol @code{line}, +which will use the default line height in the currently selected +window. +@end table + +@var{doc} should be a doc string. + +@var{keywords} is a list of keyword/value pairs. The following +keywords are allowed: + +@table @code +@item :version +The (approximate) Emacs version this button first appeared. (This +keyword is mandatory.) + +@item :group +The customization group this icon belongs in. If not present, it is +inferred. + +@item :help-echo +The help string shown when hovering over the icon with the mouse +pointer. +@end table +@end defmac + +@defun icon-string icon +This function returns a string suitable for display in the current +buffer for @var{icon}. +@end defun + +@defun icon-elements icon +Alternatively, you can get a ``deconstructed'' version of @var{icon} +with this function. It returns a plist (@pxref{Property Lists}) where +the keys are @code{string}, @code{face} and @var{image}. (The latter +is only present if the icon is represented by an image.) This can be +useful if the icon isn't to be inserted directly in the buffer, but +needs some sort of pre-processing first. +@end defun + +Icons can be customized with @kbd{M-x customize-icon}. Themes can +specify changes to icons with, for instance: + +@lisp +(custom-theme-set-icons + 'my-theme + '(outline-open ((image :height 100) + (text " OPEN "))) + '(outline-close ((image :height 100) + (text " CLOSE " :face warning)))) +@end lisp + + @node Xwidgets @section Embedded Native Widgets @cindex xwidget @@ -6779,7 +7174,10 @@ xwidget object, and then use that object as the display specifier in a @code{display} text or overlay property (@pxref{Display Property}). -@defun make-xwidget type title width height arguments &optional buffer + Embedded widgets can send events notifying Lisp code about changes +occurring within them. (@pxref{Xwidget Events}). + +@defun make-xwidget type title width height arguments &optional buffer related This creates and returns an xwidget object. If @var{buffer} is omitted or @code{nil}, it defaults to the current buffer. If @var{buffer} names a buffer that doesn't exist, it will be @@ -6792,7 +7190,17 @@ The WebKit component. @end table The @var{width} and @var{height} arguments specify the widget size in -pixels, and @var{title}, a string, specifies its title. +pixels, and @var{title}, a string, specifies its title. @var{related} +is used internally by the WebKit widget, and specifies another WebKit +widget that the newly created widget should share settings and +subprocesses with. + +The xwidget that is returned will be killed alongside its buffer +(@pxref{Killing Buffers}). You can also kill it using +@code{kill-xwidget}. Once it is killed, the xwidget may continue to +exist as a Lisp object and act as a @code{display} property until all +references to it are gone, but most actions that can be performed on +live xwidgets will no longer be available. @end defun @defun xwidgetp object @@ -6800,6 +7208,17 @@ This function returns @code{t} if @var{object} is an xwidget, @code{nil} otherwise. @end defun +@defun xwidget-live-p object +This function returns @code{t} if @var{object} is an xwidget that +hasn't been killed, and @code{nil} otherwise. +@end defun + +@defun kill-xwidget xwidget +This function kills @var{xwidget}, by removing it from its buffer and +releasing window system resources it holds. +@end defun + +@cindex xwidget property list @defun xwidget-plist xwidget This function returns the property list of @var{xwidget}. @end defun @@ -6810,7 +7229,12 @@ property list given by @var{plist}. @end defun @defun xwidget-buffer xwidget -This function returns the buffer of @var{xwidget}. +This function returns the buffer of @var{xwidget}. If @var{xwidget} +has been killed, it returns @code{nil}. +@end defun + +@defun set-xwidget-buffer xwidget buffer +This function sets the buffer of @var{xwidget} to @var{buffer}. @end defun @defun get-buffer-xwidgets buffer @@ -6873,6 +7297,130 @@ This function returns the current setting of @var{xwidget}s query-on-exit flag, either @code{t} or @code{nil}. @end defun +@defun xwidget-perform-lispy-event xwidget event frame +Send an input event @var{event} to @var{xwidget}. The precise action +performed is platform-specific. @xref{Input Events}. + +You can optionally pass the frame on which the event was generated via +@var{frame}. On X11, modifier keys in key events will not be +considered if @var{frame} is @code{nil}, and the selected frame is not +an X-Windows frame. + +On GTK, only keyboard and function key events are supported. Mouse, +motion, and click events are dispatched to the xwidget without going +through Lisp code, and as such shouldn't require this function to be +called. +@end defun + +@defun xwidget-webkit-search query xwidget &optional case-insensitive backwards wrap-around +Start an incremental search on the WebKit widget @var{xwidget} with +the string @var{query} as the query. @var{case-insensitive} denotes +whether or not the search is case-insensitive, @var{backwards} +determines if the search is performed backwards towards the start of +the document, and @var{wrap-around} determines whether or not the +search terminates at the end of the document. + +If the function is called while a search query is already present, +then the query specified here will replace the existing query. + +To stop a search query, use @code{xwidget-webkit-finish-search}. +@end defun + +@defun xwidget-webkit-next-result xwidget +Display the next search result in @var{xwidget}. This function will +signal an error if a search query has not been already started in +@var{xwidget} through @code{xwidget-webkit-search}. + +If @code{wrap-around} was non-nil when @code{xwidget-webkit-search} +was called, then the search will restart from the beginning of the +document when its end is reached. +@end defun + +@defun xwidget-webkit-previous-result xwidget +Display the previous search result in @var{xwidget}. This function +signals an error if a search query has not been already started in +@var{xwidget} through @code{xwidget-webkit-search}. + +If @code{wrap-around} was non-nil when @code{xwidget-webkit-search} +was called, then the search will restart from the end of the +document when its beginning is reached. +@end defun + +@defun xwidget-webkit-finish-search xwidget +Finish a search operation started with @code{xwidget-webkit-search} in +@var{xwidget}. If there is no query currently ongoing, this function +signals an error. +@end defun + +@defun xwidget-webkit-load-html xwidget text &optional base-uri +Load @var{text}, a string, into @var{xwidget}, which should be a +WebKit xwidget. Any HTML markup in @var{text} will be processed +by @var{xwidget} while rendering the text. + +Optional argument @var{base-uri}, which should be a string, specifies +the absolute location of the web resources referenced by @var{text}, +to be used for resolving relative links in @var{text}. +@end defun + +@defun xwidget-webkit-goto-history xwidget rel-pos +Make @var{xwidget}, a WebKit widget, load the @var{rel-pos}th element +in its navigation history. + +If @var{rel-pos} is zero, the current page will be reloaded instead. +@end defun + +@defun xwidget-webkit-back-forward-list xwidget &optional limit +Return the navigation history of @var{xwidget}, up to @var{limit} +items in each direction. If not specified, @var{limit} defaults to +50. + +The returned value is a list of the form @w{@code{(@var{back} +@var{here} @var{forward})}}, where @var{here} is the current +navigation item, while @var{back} is a list of items containing the +items recorded by WebKit before the current navigation item, and +@var{forward} is a list of items recorded after the current navigation +item. @var{back}, @var{here} and @var{forward} can all be @code{nil}. + +When @var{here} is @code{nil}, it means that no items have been +recorded yet; if @var{back} or @var{forward} are @code{nil}, it means +that there is no history recorded before or after the current item +respectively. + +Navigation items are themselves lists of the form @w{@code{(@var{idx} +@var{title} @var{uri})}}. In these lists, @var{idx} is an index that +can be passed to @code{xwidget-webkit-goto-history}, @var{title} is +the human-readable title of the item, and @var{uri} is the URI of the +item. The user should normally have no reason to load @var{uri} +manually to reach a specific history item. Instead, @var{idx} should +be passed as an index to @code{xwidget-webkit-goto-history}. +@end defun + +@defun xwidget-webkit-estimated-load-progress xwidget +Return an estimate of how much data is remaining to be transferred +before the page displayed by the WebKit widget @var{xwidget} is fully +loaded. + +The value returned is a float ranging between 0.0 and 1.0. +@end defun + +@defun xwidget-webkit-set-cookie-storage-file xwidget file +Make the WebKit widget @var{xwidget} store cookies in @var{file}. + +@var{file} must be an absolute file name. The new setting will also +affect any xwidget that was created with @var{xwidget} as the +@code{related} argument to @code{make-xwidget}, and widgets related to +those as well. + +If this function is not called at least once on @var{xwidget} or a +related widget, @var{xwidget} will not store cookies on disk at all. +@end defun + +@defun xwidget-webkit-stop-loading xwidget +Terminate any data transfer still in progress in the WebKit widget +@var{xwidget} as part of a page-loading operation. If a page is not +being loaded, this function does nothing. +@end defun + @node Buttons @section Buttons @cindex buttons in buffers @@ -7067,7 +7615,7 @@ This inserts a button with the label @var{label} at point, using text properties. @end defun -@defun button-buttonize string callback &optional data +@defun buttonize string callback &optional data Sometimes it's more convenient to make a string into a button without inserting it into a buffer immediately, for instance when creating data structures that may then, later, be inserted into a buffer. This @@ -7195,7 +7743,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} is non-@code{nil}, return nil +buttons can be found. If @var{no-error} is non-@code{nil}, return @code{nil} instead of signaling the error. @end deffn @@ -7207,7 +7755,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} is non-@code{nil}, return nil +buttons can be found. If @var{no-error} is non-@code{nil}, return @code{nil} instead of signaling the error. @end deffn @@ -7543,16 +8091,14 @@ The string is formatted #RRGGBB (hash followed by six hex digits)." (kill-buffer nil)) (setq colorcomp-mode-map - (let ((m (make-sparse-keymap))) - (suppress-keymap m) - (define-key m "i" 'colorcomp-R-less) - (define-key m "o" 'colorcomp-R-more) - (define-key m "k" 'colorcomp-G-less) - (define-key m "l" 'colorcomp-G-more) - (define-key m "," 'colorcomp-B-less) - (define-key m "." 'colorcomp-B-more) - (define-key m " " 'colorcomp-copy-as-kill-and-exit) - m)) + (define-keymap :suppress t + "i" 'colorcomp-R-less + "o" 'colorcomp-R-more + "k" 'colorcomp-G-less + "l" 'colorcomp-G-more + "," 'colorcomp-B-less + "." 'colorcomp-B-more + "SPC" 'colorcomp-copy-as-kill-and-exit)) @end smallexample Note that we never modify the data in each node, which is fixed when the @@ -7855,7 +8401,10 @@ help buffer. The window's display table, if there is one, takes precedence over the buffer's display table. If neither exists, Emacs tries to use the standard display table; if that is @code{nil}, Emacs uses the usual -character display conventions (@pxref{Usual Display}). +character display conventions (@pxref{Usual Display}). (Emacs does +not ``merge'' display tables: For instance, if the window has a +display table, the buffer's display table and the standard display +table are completely ignored.) Note that display tables affect how the mode line is displayed, so if you want to force redisplay of the mode line using a new display @@ -7961,7 +8510,14 @@ there is no available font (on a graphical display), and characters which cannot be encoded by the terminal's coding system (on a text terminal). +@findex glyphless-display-mode +The @code{glyphless-display-mode} minor mode can be used to toggle +displaying glyphless characters in a convenient manner in the current +buffer. If this mode is enabled, all the glyphless characters are +displayed as boxes that display acronyms of their character names. + @defvar glyphless-char-display +For more fine-grained (and global) control, this variable can be used. The value of this variable is a char-table which defines glyphless characters and how they are displayed. Each entry must be one of the following display methods: @@ -7986,7 +8542,11 @@ hexadecimal notation. @item an @acronym{ASCII} string Display a box containing that string. The string should contain at -most 6 @acronym{ASCII} characters. +most 6 @acronym{ASCII} characters. As an exception, if the string +includes just one character, on text-mode terminals that character +will be displayed without a box; this allows to handle such +``acronyms'' as a replacement character for characters that cannot be +displayed by the terminal. @item a cons cell @code{(@var{graphical} . @var{text})} Display with @var{graphical} on graphical displays, and with @@ -8004,7 +8564,7 @@ square brackets, @samp{[]}. The char-table has one extra slot, which determines how to display any character that cannot be displayed with any available font, or cannot be encoded by the terminal's coding system. Its value should be one -of the above display methods, except @code{zero-width} or a cons cell. +of the above display methods, except @code{zero-width}. If a character has a non-@code{nil} entry in an active display table, the display table takes effect; in this case, Emacs does not consult @@ -8042,10 +8602,20 @@ Characters of Unicode General Category [Cf], such as U+200E @sc{left-to-right mark}, but excluding characters that have graphic images, such as U+00AD @sc{soft hyphen}. +@item bidi-control +This is a subset of @code{format-control}, but only includes +characters that are related to bidirectional formatting control, like +U+2069 @sc{pop directional isolate} and U+202A @sc{left-to-right +embedding}. @xref{Bidirectional Display}. + +Characters of Unicode General Category [Cf], such as U+200E +@sc{left-to-right mark}, but excluding characters that have graphic +images, such as U+00AD @sc{soft hyphen}. + @item variation-selectors -Unicode VS-1 through VS-16 (U+FE00 through U+FE0F), which are used to -select between different glyphs for the same codepoints (typically -emojis). +Unicode VS-1 through VS-256 (U+FE00 through U+FE0F and U+E0100 through +U+E01EF), which are used to select between different glyphs for the same +codepoints (typically emojis). @item no-font Characters for which there is no suitable font, or which cannot be @@ -8120,6 +8690,10 @@ Emacs is displaying the frame using the Nextstep interface (used on GNUstep and macOS). @item pc Emacs is displaying the frame using MS-DOS direct screen writes. +@item haiku +Emacs is displaying the frame using the Application Kit on Haiku. +@item pgtk +Emacs is displaying the frame using pure GTK facilities. @item nil Emacs is displaying the frame on a character-based terminal. @end table @@ -8166,13 +8740,15 @@ area. On text-mode (a.k.a.@: ``TTY'') frames, tooltips are always displayed in the echo area. @end defun -@vindex x-gtk-use-system-tooltips -When Emacs is built with GTK+ support, it by default displays tooltips -using GTK+ functions, and the appearance of the tooltips is then -controlled by GTK+ settings. GTK+ tooltips can be disabled by -changing the value of the variable @code{x-gtk-use-system-tooltips} to -@code{nil}. The rest of this subsection describes how to control -non-GTK+ tooltips, which are presented by Emacs itself. +@cindex system tooltips +@vindex use-system-tooltips +When Emacs is built with the GTK+ toolkit or Haiku windowing support, +it by default displays tooltips using toolkit functions, and the +appearance of the tooltips is then controlled by the toolkit's +settings. Toolkit-provided tooltips can be disabled by changing the +value of the variable @code{use-system-tooltips} to @code{nil}. The +rest of this subsection describes how to control non-toolkit tooltips, +which are presented by Emacs itself. @cindex tooltip frames Tooltips are displayed in special frames called tooltip frames, which |