X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/9fb9136398821ed5f3a8b4405bbc222964f54028..eb0f65b4fbbea60100b53cb40a1d7138d47ad0d2:/doc/lispref/display.texi diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index e26d649185..9e9f8e3ca4 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2014 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2015 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Display @chapter Emacs Display @@ -87,10 +87,7 @@ waiting for input. @defun redisplay &optional force This function tries immediately to redisplay. The optional argument @var{force}, if non-@code{nil}, forces the redisplay to be performed, -instead of being preempted, even if input is pending and the variable -@code{redisplay-dont-pause} is @code{nil} (see below). If -@code{redisplay-dont-pause} is non-@code{nil} (the default), this -function redisplays in any case, i.e., @var{force} does nothing. +instead of being preempted if input is pending. The function returns @code{t} if it actually tried to redisplay, and @code{nil} otherwise. A value of @code{t} does not mean that @@ -98,28 +95,6 @@ redisplay proceeded to completion; it could have been preempted by newly arriving input. @end defun -@defvar redisplay-dont-pause -If this variable is @code{nil}, arriving input events preempt -redisplay; Emacs avoids starting a redisplay, and stops any redisplay -that is in progress, until the input has been processed. In -particular, @code{(redisplay)} returns @code{nil} without actually -redisplaying, if there is pending input. - -The default value is @code{t}, which means that pending input does not -preempt redisplay. -@end defvar - -@defvar redisplay-preemption-period -If @code{redisplay-dont-pause} is @code{nil}, this variable specifies -how many seconds Emacs waits between checks for new input during -redisplay; if input arrives during this interval, redisplay stops and -the input is processed. The default value is 0.1; if the value is -@code{nil}, Emacs does not check for input during redisplay. - -This variable has no effect when @code{redisplay-dont-pause} is -non-@code{nil} (the default). -@end defvar - @defvar pre-redisplay-function A function run just before redisplay. It is called with one argument, the set of windows to redisplay. @@ -282,6 +257,9 @@ text properties (@pxref{Logging Messages}). In batch mode, the message is printed to the standard error stream, followed by a newline. +When @code{inhibit-message} is non-@code{nil}, no message will be displayed +in the echo area, it will only be logged to @samp{*Messages*}. + If @var{format-string} is @code{nil} or the empty string, @code{message} clears the echo area; if the echo area has been expanded automatically, this brings it back to its normal size. If @@ -307,6 +285,11 @@ To automatically display a message in the echo area or in a pop-buffer, depending on its size, use @code{display-message-or-buffer} (see below). @end defun +@defvar inhibit-message +When this variable is non-@code{nil}, @code{message} and related functions +will not use the Echo Area to display messages. +@end defvar + @defmac with-temp-message message &rest body This construct displays a message in the echo area temporarily, during the execution of @var{body}. It displays @var{message}, executes @@ -1194,12 +1177,6 @@ it prints into the buffer named @var{buffer-or-name} and displays that buffer in some window. Unlike @code{with-output-to-temp-buffer}, however, it does not automatically switch that buffer to Help mode. -Like @code{with-output-to-temp-buffer} it neither makes the buffer -specified by @var{buffer-or-name} current when executing @var{body}. -@findex with-current-buffer-window -The otherwise identical macro @code{with-current-buffer-window} can be -used to execute @var{body} with that buffer current. - The argument @var{buffer-or-name} specifies the temporary buffer. It can be either a buffer, which must already exist, or a string, in which case a buffer of that name is created, if necessary. The buffer is @@ -1207,14 +1184,14 @@ marked as unmodified and read-only when @code{with-temp-buffer-window} exits. This macro does not call @code{temp-buffer-show-function}. Rather, it -passes the @var{action} argument to @code{display-buffer} in order to -display the buffer. +passes the @var{action} argument to @code{display-buffer} +(@pxref{Choosing Window}) in order to display the buffer. The value of the last form in @var{body} is returned, unless the argument @var{quit-function} is specified. In that case, it is called with two arguments: the window showing the buffer and the result of -@var{body}. The final return value is then whatever -@var{quit-function} returns. +@var{body}. The final return value is then whatever @var{quit-function} +returns. @vindex temp-buffer-window-setup-hook @vindex temp-buffer-window-show-hook @@ -1223,6 +1200,56 @@ and @code{temp-buffer-window-show-hook} in place of the analogous hooks run by @code{with-output-to-temp-buffer}. @end defmac +The two constructs described next are mostly identical to +@code{with-temp-buffer-window} but differ from it as specified: + +@defmac with-current-buffer-window buffer-or-name action quit-function &rest body +This macro is like @code{with-temp-buffer-window} but unlike that makes +the buffer specified by @var{buffer-or-name} current for running +@var{body}. +@end defmac + +@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body +This macro is like @code{with-current-buffer-window} but unlike that +displays the buffer specified by @var{buffer-or-name} @emph{before} +running @var{body}. +@end defmac + +A window showing a temporary buffer can be fit to the size of that +buffer using the following mode: + +@defopt temp-buffer-resize-mode +When this minor mode is enabled, windows showing a temporary buffer are +automatically resized to fit their buffer's contents. + +A window is resized if and only if it has been specially created for the +buffer. In particular, windows that have shown another buffer before +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. +@end defopt + +@defopt temp-buffer-max-height +This option specifies the maximum height (in lines) of a window +displaying a temporary buffer when @code{temp-buffer-resize-mode} is +enabled. It can also be a function to be called to choose the height +for such a buffer. It gets one argument, the buffer, and should return +a positive integer. At the time the function is called, the window to +be resized is selected. +@end defopt + +@defopt temp-buffer-max-width +This option specifies the maximum width of a window (in columns) +displaying a temporary buffer when @code{temp-buffer-resize-mode} is +enabled. It can also be a function to be called to choose the width for +such a buffer. It gets one argument, the buffer, and should return a +positive integer. At the time the function is called, the window to be +resized is selected. +@end defopt + +The following function uses the current buffer for temporal display: + @defun momentary-string-display string position &optional char message This function momentarily displays @var{string} in the current buffer at @var{position}. It has no effect on the undo list or on the buffer's @@ -1291,6 +1318,7 @@ beginning and end. It also has properties that you can examine and set; these affect the display of the text within the overlay. @cindex scalability of overlays +@cindex overlays, scalability The visual effect of an overlay is the same as of the corresponding text property (@pxref{Text Properties}). However, due to a different implementation, overlays generally don't scale well (many operations @@ -1332,6 +1360,15 @@ and @var{end} must specify buffer positions; they may be integers or markers. If @var{buffer} is omitted, the overlay is created in the current buffer. +@cindex empty overlay +@cindex overlay, empty +An overlay whose @var{start} and @var{end} specify the same buffer +position is known as @dfn{empty}. A non-empty overlay can become +empty if the text between its @var{start} and @var{end} is deleted. +When that happens, the overlay is by default not deleted, but you can +cause it to be deleted by giving it the @samp{evaporate} property +(@pxref{Overlay Properties, evaporate property}). + The arguments @var{front-advance} and @var{rear-advance} specify the marker insertion type for the start of the overlay and for the end of the overlay, respectively. @xref{Marker Insertion Types}. If they @@ -1701,8 +1738,11 @@ line at display-time. @xref{Truncation}. @kindex evaporate @r{(overlay property)} If this property is non-@code{nil}, the overlay is deleted automatically if it becomes empty (i.e., if its length becomes zero). If you give -an empty overlay a non-@code{nil} @code{evaporate} property, that deletes -it immediately. +an empty overlay (@pxref{Managing Overlays, empty overlay}) a +non-@code{nil} @code{evaporate} property, that deletes it immediately. +Note that, unless an overlay has this property, it will not be deleted +when the text between its starting and ending positions is deleted +from the buffer. @item keymap @cindex keymap of character (and overlays) @@ -1758,10 +1798,10 @@ overlays that specify property @var{prop} for the character at point: This function returns a list of the overlays that overlap the region @var{beg} through @var{end}. ``Overlap'' means that at least one character is contained within the overlay and also contained within the -specified region; however, empty overlays are included in the result if -they are located 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. +specified region; however, empty overlays (@pxref{Managing Overlays, +empty overlay}) are included in the result if they are located 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. @end defun @defun next-overlay-change pos @@ -2135,7 +2175,7 @@ stipple patterns. Alternative foreground color, a string. This is like @code{:foreground} but the color is only used as a foreground when the background color is near to the foreground that would have been used. This is useful for -example when marking text (i.e. the region face). If the text has a foreground +example when marking text (i.e., the region face). If the text has a foreground that is visible with the region face, that foreground is used. If the foreground is near the region face background, @code{:distant-foreground} is used instead so the text is readable. @@ -2771,7 +2811,7 @@ then the new definition of the @code{mode-line} face inherits from the functions instead of setting @code{face-remapping-alist} directly, to avoid trampling on remappings applied elsewhere. These functions are intended for buffer-local remappings, so they all make -@code{face-remapping-alist} buffer-local as a side-effect. They manage +@code{face-remapping-alist} buffer-local as a side-effect. They manage @code{face-remapping-alist} entries of the form @example @@ -2801,11 +2841,11 @@ pass this object as an argument to @code{face-remap-remove-relative} if you need to remove the remapping later. @example -;; Remap the `escape-glyph' face into a combination -;; of the `highlight' and `italic' faces: +;; Remap the 'escape-glyph' face into a combination +;; of the 'highlight' and 'italic' faces: (face-remap-add-relative 'escape-glyph 'highlight 'italic) -;; Increase the size of the `default' face by 50%: +;; Increase the size of the 'default' face by 50%: (face-remap-add-relative 'default :height 1.5) @end example @end defun @@ -3244,7 +3284,7 @@ field. @defun set-fontset-font name character font-spec &optional frame add This function modifies the existing fontset @var{name} to use the font -matching with @var{font-spec} for the character @var{character}. +matching with @var{font-spec} for the specified @var{character}. If @var{name} is @code{nil}, this function modifies the fontset of the selected frame or that of @var{frame} if @var{frame} is not @@ -3253,10 +3293,10 @@ selected frame or that of @var{frame} if @var{frame} is not If @var{name} is @code{t}, this function modifies the default fontset, whose short name is @samp{fontset-default}. -@var{character} may be a cons; @code{(@var{from} . @var{to})}, where -@var{from} and @var{to} are character codepoints. In that case, use -@var{font-spec} for all characters in the range @var{from} and @var{to} -(inclusive). +In addition to specifying a single codepoint, @var{character} may be a +cons @code{(@var{from} . @var{to})}, where @var{from} and @var{to} are +character codepoints. In that case, use @var{font-spec} for all the +characters in the range @var{from} and @var{to} (inclusive). @var{character} may be a charset. In that case, use @var{font-spec} for all character in the charsets. @@ -3264,6 +3304,9 @@ fontset, whose short name is @samp{fontset-default}. @var{character} may be a script name. In that case, use @var{font-spec} for all character in the charsets. +@var{font-spec} may be a font-spec object created by the function +@code{font-spec} (@pxref{Low-Level Font}). + @var{font-spec} may be a cons; @code{(@var{family} . @var{registry})}, where @var{family} is a family name of a font (possibly including a foundry name at the head), @var{registry} is a registry name of a font @@ -3271,6 +3314,12 @@ foundry name at the head), @var{registry} is a registry name of a font @var{font-spec} may be a font name string. +@var{font-spec} may be @code{nil}, which explicitly specifies that +there's no font for the specified @var{character}. This is useful, +for example, to avoid expensive system-wide search for fonts for +characters that have no glyphs, like those from the Unicode Private +Use Area (PUA). + The optional argument @var{add}, if non-@code{nil}, specifies how to add @var{font-spec} to the font specifications previously set. If it is @code{prepend}, @var{font-spec} is prepended. If it is @@ -3370,6 +3419,15 @@ The charset registry and encoding of the font, such as @item :script The script that the font must support (a symbol). +@item :lang +The language that the font should support. The value should be a +symbol whose name is a two-letter ISO-639 language name. On X, the +value is matched against the ``Additional Style'' field of the XLFD +name of a font, if it is non-empty. On MS-Windows, fonts matching the +spec are required to support codepages needed for the language. +Currently, only a small set of CJK languages is supported with this +property: @samp{ja}, @samp{ko}, and @samp{zh}. + @item :otf @cindex OpenType font The font must be an OpenType font that supports these OpenType @@ -4538,7 +4596,7 @@ not affect the amount of raising or lowering, which is based on the faces used for the text. @end table -@c We put all the `@code{(when ...)}' on one line to encourage +@c We put all the '@code{(when ...)}' on one line to encourage @c makeinfo's end-of-sentence heuristics to DTRT. Previously, the dot @c was at eol; the info file ended up w/ two spaces rendered after it. You can make any display specification conditional. To do that, @@ -5609,7 +5667,7 @@ so that it's easy to define special-purpose types of buttons for specific tasks. @defun define-button-type name &rest properties -Define a `button type' called @var{name} (a symbol). +Define a ``button type'' called @var{name} (a symbol). The remaining arguments form a sequence of @var{property value} pairs, specifying default property values for buttons with this type (a button's type may be set @@ -5716,10 +5774,12 @@ Set @var{button}'s @var{prop} property to @var{val}. @end defun @defun button-activate button &optional use-mouse-action -Call @var{button}'s @code{action} property (i.e., invoke it). If -@var{use-mouse-action} is non-@code{nil}, try to invoke the button's -@code{mouse-action} property instead of @code{action}; if the button -has no @code{mouse-action} property, use @code{action} as normal. +Call @var{button}'s @code{action} property (i.e., invoke the function +that is the value of that property, passing it the single argument +@var{button}). If @var{use-mouse-action} is non-@code{nil}, try to +invoke the button's @code{mouse-action} property instead of +@code{action}; if the button has no @code{mouse-action} property, use +@code{action} as normal. @end defun @defun button-label button @@ -5760,7 +5820,7 @@ Return @code{t} if button-type @var{type} is a subtype of @var{supertype}. These are commands and functions for locating and operating on buttons in an Emacs buffer. -@code{push-button} is the command that a user uses to actually `push' +@code{push-button} is the command that a user uses to actually ``push'' a button, and is bound by default in the button itself to @key{RET} and to @key{mouse-2} using a local keymap in the button's overlay or text properties. Commands that are useful outside the buttons itself, @@ -6471,8 +6531,9 @@ no buffer display table. @defvar standard-display-table The value of this variable is the standard display table, which is used when Emacs is displaying a buffer in a window with neither a -window display table nor a buffer display table defined. Its default -is @code{nil}. +window display table nor a buffer display table defined, or when Emacs +is outputting text to the standard output or error streams. Its +default is @code{nil}. @end defvar The @file{disp-table} library defines several functions for changing @@ -6572,7 +6633,8 @@ Display a box containing the Unicode codepoint of the character, in hexadecimal notation. @item an @acronym{ASCII} string -Display a box containing that string. +Display a box containing that string. The string should contain at +most 6 @acronym{ASCII} characters. @item a cons cell @code{(@var{graphical} . @var{text})} Display with @var{graphical} on graphical displays, and with @@ -6583,7 +6645,8 @@ must be one of the display methods described above. @noindent The @code{thin-space}, @code{empty-box}, @code{hex-code}, and @acronym{ASCII} string display methods are drawn with the -@code{glyphless-char} face. +@code{glyphless-char} face. On text terminals, a box is emulated by +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 @@ -6622,7 +6685,7 @@ Non-@acronym{ASCII}, non-printing characters @code{U+0080} to @samp{\230}). @item format-control -Characters of Unicode General Category `Cf', such as @samp{U+200E} +Characters of Unicode General Category ``Cf'', such as @samp{U+200E} (Left-to-Right Mark), but excluding characters that have graphic images, such as @samp{U+00AD} (Soft Hyphen). @@ -6631,9 +6694,9 @@ Characters for there is no suitable font, or which cannot be encoded by the terminal's coding system. @end table -@c FIXME: this can also be `acronym', but that's not currently +@c FIXME: this can also be 'acronym', but that's not currently @c completely implemented; it applies only to the format-control -@c group, and only works if the acronym is in `char-acronym-table'. +@c group, and only works if the acronym is in 'char-acronym-table'. The @var{method} symbol should be one of @code{zero-width}, @code{thin-space}, @code{empty-box}, or @code{hex-code}. These have the same meanings as in @code{glyphless-char-display}, above. @@ -6707,8 +6770,9 @@ Emacs is displaying the frame on a character-based terminal. This variable holds the value of @code{window-system} used for the first frame created by Emacs during startup. (When Emacs is invoked with the @option{--daemon} option, it does not create any initial -frames, so @code{initial-window-system} is @code{nil}. @xref{Initial -Options, daemon,, emacs, The GNU Emacs Manual}.) +frames, so @code{initial-window-system} is @code{nil}, except on +MS-Windows, where it is still @code{w32}. @xref{Initial Options, +daemon,, emacs, The GNU Emacs Manual}.) @end defvar @defun window-system &optional frame