diff options
Diffstat (limited to 'doc/lispref/display.texi')
| -rw-r--r-- | doc/lispref/display.texi | 381 |
1 files changed, 352 insertions, 29 deletions
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b1fb9f8b956..98a15404f91 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -561,6 +561,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 @@ -1334,6 +1354,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 @@ -1983,7 +2008,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,7 +2086,7 @@ 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 @@ -2110,6 +2136,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 +2207,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 @@ -2372,8 +2451,10 @@ 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}.) + + The @code{default} face must specify all attributes. Some of these attributes are meaningful only on certain kinds of displays. If your display cannot handle a certain attribute, the @@ -2709,8 +2790,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 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}, @@ -4798,9 +4880,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 @@ -4808,6 +4888,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, @@ -5083,6 +5207,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}: @@ -5283,13 +5425,13 @@ 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}. Furthermore, if you build Emacs with ImageMagick (@code{libMagickWand}) support, Emacs can display any image format @@ -6293,6 +6435,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 @@ -6444,7 +6589,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 @@ -6469,7 +6614,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 @@ -6545,6 +6692,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: @@ -6716,7 +6868,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 @@ -6729,7 +6884,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 @@ -6737,6 +6902,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 @@ -6747,7 +6923,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 @@ -6810,6 +6991,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 @@ -7003,7 +7308,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 @@ -7478,16 +7783,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 @@ -7896,7 +8199,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). +@vindex 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: @@ -7976,6 +8286,16 @@ 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 @@ -8053,6 +8373,8 @@ 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 nil Emacs is displaying the frame on a character-based terminal. @end table @@ -8099,6 +8421,7 @@ area. On text-mode (a.k.a.@: ``TTY'') frames, tooltips are always displayed in the echo area. @end defun +@cindex system tooltips @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 |