diff options
Diffstat (limited to 'doc/lispref/display.texi')
| -rw-r--r-- | doc/lispref/display.texi | 494 |
1 files changed, 410 insertions, 84 deletions
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 5d3202e67ef..14a98f32ffb 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -23,7 +23,7 @@ that Emacs presents to the user. * Faces:: A face defines a graphics style for text characters: font, colors, etc. * Fringes:: Controlling window fringes. -* Scroll Bars:: Controlling vertical scroll bars. +* Scroll Bars:: Controlling scroll bars. * Window Dividers:: Separating windows visually. * Display Property:: Enabling special display features. * Images:: Displaying images in Emacs buffers. @@ -87,7 +87,10 @@ 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 if input is pending. +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. The function returns @code{t} if it actually tried to redisplay, and @code{nil} otherwise. A value of @code{t} does not mean that @@ -95,6 +98,28 @@ 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. @@ -1169,12 +1194,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 @@ -1182,14 +1201,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 @@ -1198,6 +1217,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 @@ -3348,9 +3417,9 @@ The script that the font must support (a symbol). @item :otf @cindex OpenType font The font must be an OpenType font that supports these OpenType -features, provided Emacs is compiled with support for @samp{libotf} (a -library for performing complex text layout in certain scripts). The -value must be a list of the form +features, provided Emacs is compiled with a library, such as +@samp{libotf} on GNU/Linux, that supports complex text layout for +scripts which need that. The value must be a list of the form @smallexample @code{(@var{script-tag} @var{langsys-tag} @var{gsub} @var{gpos})} @@ -3449,6 +3518,124 @@ If the optional argument @var{fold-wildcards} is non-@code{nil}, consecutive wildcards in the XLFD are folded into one. @end defun +The following two functions return important information about a font. + +@defun font-info name &optional frame +This function returns information about a font specified by its +@var{name}, a string, as it is used on @var{frame}. If @var{frame} is +omitted or @code{nil}, it defaults to the selected frame. + +The value returned by the function is a vector of the form +@code{[@var{opened-name} @var{full-name} @var{size} @var{height} +@var{baseline-offset} @var{relative-compose} @var{default-ascent} +@var{max-width} @var{ascent} @var{descent} @var{space-width} +@var{average-width} @var{filename} @var{capability}]}. Here's the +description of each components of this vector: + +@table @var +@item opened-name +The name used to open the font, a string. + +@item full-name +The full name of the font, a string. + +@item size +The pixel size of the font. + +@item height +The height of the font in pixels. + +@item baseline-offset +The offset in pixels from the @acronym{ASCII} baseline, positive +upward. + +@item relative-compose +@itemx default-ascent +Numbers controlling how to compose characters. + +@item ascent +@itemx descent +The ascent and descent of this font. The sum of these two numbers +should be equal to the value of @var{height} above. + +@item space-width +The width, in pixels, of the font's space character. + +@item average-width +The average width of the font characters. If this is zero, Emacs uses +the value of @var{space-width} instead, when it calculates text layout +on display. + +@item filename +The file name of the font as a string. This can be @code{nil} if the +font back-end does not provide a way to find out the font's file name. + +@item capability +A list whose first element is a symbol representing the font type, one +of @code{x}, @code{opentype}, @code{truetype}, @code{type1}, +@code{pcf}, or @code{bdf}. For OpenType fonts, the list includes 2 +additional elements describing the @sc{gsub} and @sc{gpos} features +supported by the font. Each of these elements is a list of the form +@code{((@var{script} (@var{langsys} @var{feature} @dots{}) @dots{}) +@dots{})}, where @var{script} is a symbol representing an OpenType +script tag, @var{langsys} is a symbol representing an OpenType langsys +tag (or @code{nil}, which stands for the default langsys), and each +@var{feature} is a symbol representing an OpenType feature tag. +@end table +@end defun + +@defun query-font font-object +This function returns information about a @var{font-object}. (This is +in contrast to @code{font-info}, which takes the font name, a string, +as its argument.) + +The value returned by the function is a vector of the form +@code{[@var{name} @var{filename} @var{pixel-size} @var{max-width} +@var{ascent} @var{descent} @var{space-width} @var{average-width} +@var{capability}]}. Here's the description of each components of this +vector: + +@table @var +@item name +The font name, a string. + +@item filename +The file name of the font as a string. This can be @code{nil} if the +font back-end does not provide a way to find out the font's file name. + +@item pixel-size +The pixel size of the font used to open the font. + +@item max-width +The maximum advance width of the font. + +@item ascent +@itemx descent +The ascent and descent of this font. The sum of these two numbers +gives the font height. + +@item space-width +The width, in pixels, of the font's space character. + +@item average-width +The average width of the font characters. If this is zero, Emacs uses +the value of @var{space-width} instead, when it calculates text layout +on display. + +@item capability +A list whose first element is a symbol representing the font type, one +of @code{x}, @code{opentype}, @code{truetype}, @code{type1}, +@code{pcf}, or @code{bdf}. For OpenType fonts, the list includes 2 +additional elements describing the @sc{gsub} and @sc{gpos} features +supported by the font. Each of these elements is a list of the form +@code{((@var{script} (@var{langsys} @var{feature} @dots{}) @dots{}) +@dots{})}, where @var{script} is a symbol representing an OpenType +script tag, @var{langsys} is a symbol representing an OpenType langsys +tag (or @code{nil}, which stands for the default langsys), and each +@var{feature} is a symbol representing an OpenType feature tag. +@end table +@end defun + @node Fringes @section Fringes @cindex fringes @@ -3865,102 +4052,164 @@ arrow position. If either property is not set, the default @code{overlay-arrow-string} or @code{overlay-arrow} fringe indicator is used. + @node Scroll Bars @section Scroll Bars @cindex scroll bars Normally the frame parameter @code{vertical-scroll-bars} controls -whether the windows in the frame have vertical scroll bars, and -whether they are on the left or right. The frame parameter -@code{scroll-bar-width} specifies how wide they are (@code{nil} -meaning the default). @xref{Layout Parameters}. +whether the windows in the frame have vertical scroll bars, and whether +they are on the left or right. The frame parameter +@code{scroll-bar-width} specifies how wide they are (@code{nil} meaning +the default). + + The frame parameter @code{horizontal-scroll-bars} controls whether +the windows in the frame have horizontal scroll bars. The frame +parameter @code{scroll-bar-height} specifies how high they are +(@code{nil} meaning the default). @xref{Layout Parameters}. + +@vindex horizontal-scroll-bars-available-p + Horizontal scroll bars are not available on all platforms. The +function @code{horizontal-scroll-bars-available-p} which takes no +argument returns non-@code{nil} if they are available on your system. + + The following three functions take as argument a live frame which +defaults to the selected one. @defun frame-current-scroll-bars &optional frame -This function reports the scroll bar type settings for frame -@var{frame}. The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}, where -@var{vertical-type} is either @code{left}, @code{right}, or @code{nil} -(which means no scroll bar.) @var{horizontal-type} is meant to -specify the horizontal scroll bar type, but since they are not -implemented, it is always @code{nil}. -@end defun - -@vindex vertical-scroll-bar - You can enable or disable scroll bars for a particular buffer, -by setting the variable @code{vertical-scroll-bar}. This variable -automatically becomes buffer-local when set. The possible values are -@code{left}, @code{right}, @code{t}, which means to use the -frame's default, and @code{nil} for no scroll bar. +This function reports the scroll bar types for frame @var{frame}. The +value is a cons cell @code{(@var{vertical-type} .@: +@var{horizontal-type})}, where @var{vertical-type} is either +@code{left}, @code{right}, or @code{nil} (which means no vertical scroll +bar.) @var{horizontal-type} is either @code{bottom} or @code{nil} +(which means no horizontal scroll bar). +@end defun - You can also control this for individual windows. Call the function -@code{set-window-scroll-bars} to specify what to do for a specific window: +@defun frame-scroll-bar-width &optional Lisp_Object &optional frame +This function returns the width of vertical scroll bars of @var{frame} +in pixels. +@end defun -@defun set-window-scroll-bars window width &optional vertical-type horizontal-type -This function sets the width and type of scroll bars for window -@var{window}. +@defun frame-scroll-bar-height &optional Lisp_Object &optional frame +This function returns the height of horizontal scroll bars of +@var{frame} in pixels. +@end defun -@var{width} specifies the scroll bar width in pixels (@code{nil} means -use the width specified for the frame). @var{vertical-type} specifies -whether to have a vertical scroll bar and, if so, where. The possible -values are @code{left}, @code{right} and @code{nil}, just like the -values of the @code{vertical-scroll-bars} frame parameter. +You can override the frame specific settings for individual windows by +using the following function: -The argument @var{horizontal-type} is meant to specify whether and -where to have horizontal scroll bars, but since they are not -implemented, it has no effect. If @var{window} is @code{nil}, the -selected window is used. +@defun set-window-scroll-bars window &optional width vertical-type height horizontal-type +This function sets the width and/or height and the types of scroll bars +for window @var{window}. + +@var{width} specifies the width of the vertical scroll bar in pixels +(@code{nil} means use the width specified for the frame). +@var{vertical-type} specifies whether to have a vertical scroll bar and, +if so, where. The possible values are @code{left}, @code{right}, +@code{t}, which means to use the frame's default, and @code{nil} for no +vertical scroll bar. + +@var{height} specifies the height of the horizontal scroll bar in pixels +(@code{nil} means use the height specified for the frame). +@var{horizontal-type} specifies whether to have a horizontal scroll bar. +The possible values are @code{bottom}, @code{t}, which means to use the +frame's default, and @code{nil} for no horizontal scroll bar. + +If @var{window} is @code{nil}, the selected window is used. @end defun +The following four functions take as argument a live window which +defaults to the selected one. + @defun window-scroll-bars &optional window -Report the width and type of scroll bars specified for @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a list of the form @code{(@var{width} -@var{cols} @var{vertical-type} @var{horizontal-type})}. The value -@var{width} is the value that was specified for the width (which may -be @code{nil}); @var{cols} is the number of columns that the scroll -bar actually occupies. +This function returns a list of the form @code{(@var{width} +@var{columns} @var{vertical-type} @var{height} @var{lines} +@var{horizontal-type})}. + +The value @var{width} is the value that was specified for the width of +the vertical scroll bar (which may be @code{nil}); @var{columns} is the +(possibly rounded) number of columns that the vertical scroll bar +actually occupies. -@var{horizontal-type} is not actually meaningful. +The value @var{height} is the value that was specified for the height of +the horizontal scroll bar (which may be @code{nil}); @var{lines} is the +(possibly rounded) number of lines that the horizontally scroll bar +actually occupies. +@end defun + +@defun window-current-scroll-bars &optional window +This function reports the scroll bar type for window @var{window}. The +value is a cons cell @code{(@var{vertical-type} .@: +@var{horizontal-type})}. Unlike @code{window-scroll-bars}, this reports +the scroll bar type actually used, once frame defaults and +@code{scroll-bar-mode} are taken into account. @end defun @defun window-scroll-bar-width &optional window This function returns the width in pixels of @var{window}'s vertical -scrollbar. @var{window} must be a live window, and defaults to the -selected window. +scrollbar. +@end defun + +@defun window-scroll-bar-height &optional window +This function returns the height in pixels of @var{window}'s horizontal +scrollbar. @end defun If you don't specify these values for a window with @code{set-window-scroll-bars}, the buffer-local variables -@code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being -displayed control the window's vertical scroll bars. The function +@code{vertical-scroll-bar}, @code{horizontal-scroll-bar}, +@code{scroll-bar-width} and @code{scroll-bar-height} in the buffer being +displayed control the window's scroll bars. The function @code{set-window-buffer} examines these variables. If you change them -in a buffer that is already visible in a window, you can make the -window take note of the new values by calling @code{set-window-buffer} +in a buffer that is already visible in a window, you can make the window +take note of the new values by calling @code{set-window-buffer} specifying the same buffer that is already displayed. -@defopt scroll-bar-mode -This variable, always local in all buffers, controls whether and where -to put scroll bars in windows displaying the buffer. The possible values -are @code{nil} for no scroll bar, @code{left} to put a scroll bar on -the left, and @code{right} to put a scroll bar on the right. -@end defopt +You can control the appearance of scroll bars for a particular buffer by +setting the following variables which automatically become buffer-local +when set. -@defun window-current-scroll-bars &optional window -This function reports the scroll bar type for window @var{window}. -If @var{window} is omitted or @code{nil}, the selected window is used. -The value is a cons cell -@code{(@var{vertical-type} .@: @var{horizontal-type})}. Unlike -@code{window-scroll-bars}, this reports the scroll bar type actually -used, once frame defaults and @code{scroll-bar-mode} are taken into -account. -@end defun +@defvar vertical-scroll-bar +This variable specifies the location of the vertical scroll bar. The +possible values are @code{left}, @code{right}, @code{t}, which means to +use the frame's default, and @code{nil} for no scroll bar. +@end defvar + +@defvar horizontal-scroll-bar +This variable specifies the location of the horizontal scroll bar. The +possible values are @code{bottom}, @code{t}, which means to use the +frame's default, and @code{nil} for no scroll bar. +@end defvar @defvar scroll-bar-width -This variable, always local in all buffers, specifies the width of the -buffer's scroll bars, measured in pixels. A value of @code{nil} means -to use the value specified by the frame. +This variable specifies the width of the buffer's vertical scroll bars, +measured in pixels. A value of @code{nil} means to use the value +specified by the frame. +@end defvar + +@defvar scroll-bar-height +This variable specifies the height of the buffer's horizontal scroll +bar, measured in pixels. A value of @code{nil} means to use the value +specified by the frame. @end defvar +Finally you can toggle the display of scroll bars on all frames by +customizing the variables @code{scroll-bar-mode} and +@code{horizontal-scroll-bar-mode}. + +@defopt scroll-bar-mode +This variable controls whether and where to put vertical scroll bars in +all frames. The possible values are @code{nil} for no scroll bars, +@code{left} to put scroll bars on the left and @code{right} to put +scroll bars on the right. +@end defopt + +@defopt horizontal-scroll-bar-mode +This variable controls whether to display horizontal scroll bars on all +frames. +@end defopt + + @node Window Dividers @section Window Dividers @cindex window dividers @@ -6553,10 +6802,9 @@ positions do not increase monotonically with string or buffer position. In performing this @dfn{bidirectional reordering}, Emacs follows the Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}), which is described in Annex #9 of the Unicode standard -(@url{http://www.unicode.org/reports/tr9/}). Emacs currently provides -a ``Non-isolate Bidirectionality'' class implementation of the -@acronym{UBA}: it does not yet support the isolate directional -formatting characters introduced with Unicode Standard v6.3.0. +(@url{http://www.unicode.org/reports/tr9/}). Emacs provides a ``Full +Bidirectionality'' class implementation of the @acronym{UBA}, +consistent with the requirements of the Unicode Standard v7.0. @defvar bidi-display-reordering If the value of this buffer-local variable is non-@code{nil} (the @@ -6741,3 +6989,81 @@ affect all Emacs frames and windows. appropriate mirrored character in the reordered text. Lisp programs can affect the mirrored display by changing this property. Again, any such changes affect all of Emacs display. + +@cindex overriding bidirectional properties +@cindex directional overrides +@cindex LRO +@cindex RLO + The bidirectional properties of characters can be overridden by +inserting into the text special directional control characters, +LEFT-TO-RIGHT OVERRIDE (@acronym{LRO}) and RIGHT-TO-LEFT OVERRIDE +(@acronym{RLO}). Any characters between a @acronym{RLO} and the +following newline or POP DIRECTIONAL FORMATTING (@acronym{PDF}) +control character, whichever comes first, will be displayed as if they +were strong right-to-left characters, i.e.@: they will be reversed on +display. Similarly, any characters between @acronym{LRO} and +@acronym{PDF} or newline will display as if they were strong +left-to-right, and will @emph{not} be reversed even if they are strong +right-to-left characters. + +@cindex phishing using directional overrides +@cindex malicious use of directional overrides + These overrides are useful when you want to make some text +unaffected by the reordering algorithm, and instead directly control +the display order. But they can also be used for malicious purposes, +known as @dfn{phishing}. Specifically, a URL on a Web page or a link +in an email message can be manipulated to make its visual appearance +unrecognizable, or similar to some popular benign location, while the +real location, interpreted by a browser in the logical order, is very +different. + + Emacs provides a primitive that applications can use to detect +instances of text whose bidirectional properties were overridden so as +to make a left-to-right character display as if it were a +right-to-left character, or vise versa. + +@defun bidi-find-overridden-directionality from to &optional object +This function looks at the text of the specified @var{object} between +positions @var{from} (inclusive) and @var{to} (exclusive), and returns +the first position where it finds a strong left-to-right character +whose directional properties were forced to display the character as +right-to-left, or for a strong right-to-left character that was forced +to display as left-to-right. If it finds no such characters in the +specified region of text, it returns @code{nil}. + +The optional argument @var{object} specifies which text to search, and +defaults to the current buffer. If @var{object} is non-@code{nil}, it +can be some other buffer, or it can be a string or a window. If it is +a string, the function searches that string. If it is a window, the +function searches the buffer displayed in that window. If a buffer +whose text you want to examine is displayed in some window, we +recommend to specify it by that window, rather than pass the buffer to +the function. This is because telling the function about the window +allows it to correctly account for window-specific overlays, which +might change the result of the function if some text in the buffer is +covered by overlays. +@end defun + +@cindex copying bidirectional text, preserve visual order +@cindex visual order, preserve when copying bidirectional text + When text that includes mixed right-to-left and left-to-right +characters and bidirectional controls is copied into a different +location, it can change its visual appearance, and also can affect the +visual appearance of the surrounding text at destination. This is +because reordering of bidirectional text specified by the +@acronym{UBA} has non-trivial context-dependent effects both on the +copied text and on the text at copy destination that will surround it. + + Sometimes, a Lisp program may need to preserve the exact visual +appearance of the copied text at destination, and of the text that +surrounds the copy. Lisp programs can use the following function to +achieve that effect. + +@defun buffer-substring-with-bidi-context start end &optional no-properties +This function works similar to @code{buffer-substring} (@pxref{Buffer +Contents}), but it prepends and appends to the copied text bidi +directional control characters necessary to preserve the visual +appearance of the text when it is inserted at another place. Optional +argument @var{no-properties}, if non-@code{nil}, means remove the text +properties from the copy of the text. +@end defun |