From 42b8555467c9831a0a3bab50e4b7980f482bc0ec Mon Sep 17 00:00:00 2001 From: "Richard M. Stallman" Date: Wed, 30 Mar 1994 18:36:47 +0000 Subject: [PATCH] Initial revision --- lispref/display.texi | 1249 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1249 insertions(+) create mode 100644 lispref/display.texi diff --git a/lispref/display.texi b/lispref/display.texi new file mode 100644 index 0000000000..ac8875a590 --- /dev/null +++ b/lispref/display.texi @@ -0,0 +1,1249 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/display +@node Display, Calendar, System Interface, Top +@chapter Emacs Display + + This chapter describes a number of features related to the display +that Emacs presents to the user. + +@menu +* Refresh Screen:: Clearing the screen and redrawing everything on it. +* Screen Size:: How big is the Emacs screen. +* Truncation:: Folding or wrapping long text lines. +* The Echo Area:: Where messages are displayed. +* Selective Display:: Hiding part of the buffer text. +* Overlay Arrow:: Display of an arrow to indicate position. +* Temporary Displays:: Displays that go away automatically. +* Overlays:: Use overlays to highlight parts of the buffer. +* Faces:: A face defines a graphics appearance: font, color, etc. +* Blinking:: How Emacs shows the matching open parenthesis. +* Inverse Video:: Specifying how the screen looks. +* Usual Display:: The usual conventions for displaying nonprinting chars. +* Display Tables:: How to specify other conventions. +* Beeping:: Audible signal to the user. +* Window Systems:: Which window system is being used. +@end menu + +@node Refresh Screen +@section Refreshing the Screen + +The function @code{redraw-frame} redisplays the entire contents of a +given frame. @xref{Frames}. + +@c Emacs 19 feature +@defun redraw-frame frame +This function clears and redisplays frame @var{frame}. +@end defun + +Even more powerful is @code{redraw-display}: + +@deffn Command redraw-display +This function clears and redisplays all visible frames. +@end deffn + + Normally, suspending and resuming Emacs also refreshes the screen. +Some terminal emulators record separate contents for display-oriented +programs such as Emacs and for ordinary sequential display. If you are +using such a terminal, you might want to inhibit the redisplay on +resumption. @xref{Suspending Emacs}. + +@defvar no-redraw-on-reenter +@cindex suspend (cf. @code{no-redraw-on-reenter}) +@cindex resume (cf. @code{no-redraw-on-reenter}) +This variable controls whether Emacs redraws the entire screen after it +has been suspended and resumed. Non-@code{nil} means yes, @code{nil} +means no. +@end defvar + + Processing user input takes absolute priority over redisplay. If you +call these functions when input is available, they do nothing +immediately, but a full redisplay does happen eventually---after all the +input has been processed. + +@node Screen Size +@section Screen Size +@cindex size of screen +@cindex screen size +@cindex display lines +@cindex display columns +@cindex resize redisplay + + The screen size functions report or tell Emacs the height or width of +the terminal. When you are using multiple frames, they apply to the +selected frame (@pxref{Frames}). + +@defun screen-height +This function returns the number of lines on the screen that are +available for display. + +@example +@group +(screen-height) + @result{} 50 +@end group +@end example +@end defun + +@defun screen-width +This function returns the number of columns on the screen that are +available for display. + +@example +@group +(screen-width) + @result{} 80 +@end group +@end example +@end defun + +@defun set-screen-height lines &optional not-actual-size +This function declares that the terminal can display @var{lines} lines. +The sizes of existing windows are altered proportionally to fit. + +If @var{not-actual-size} is non-@code{nil}, then Emacs displays +@var{lines} lines of output, but does not change its value for the +actual height of the screen. (Knowing the correct actual size may be +necessary for correct cursor positioning.) Using a smaller height than +the terminal actually implements may be useful to reproduce behavior +observed on a smaller screen, or if the terminal malfunctions when using +its whole screen. + +If @var{lines} is different from what it was previously, then the +entire screen is cleared and redisplayed using the new size. + +This function returns @code{nil}. +@end defun + +@defun set-screen-width columns &optional not-actual-size +This function declares that the terminal can display @var{columns} +columns. The details are as in @code{set-screen-height}. +@end defun + +@node Truncation +@section Truncation +@cindex line wrapping +@cindex continuation lines +@cindex @samp{$} in display +@cindex @samp{\} in display + + When a line of text extends beyond the right edge of a window, the +line can either be continued on the next screen line, or truncated to +one screen line. The additional screen lines used to display a long +text line are called @dfn{continuation} lines. Normally, a @samp{$} in +the rightmost column of the window indicates truncation; a @samp{\} on +the rightmost column indicates a line that ``wraps'' or is continued +onto the next line. (The display table can specify alternative +indicators; see @ref{Display Table}.) + + Note that continuation is different from filling; continuation happens +on the screen only, not in the buffer contents, and it breaks a line +precisely at the right margin, not at a word boundary. @xref{Filling}. + +@defopt truncate-lines +This buffer-local variable controls how Emacs displays lines that extend +beyond the right edge of the window. The default is @code{nil}, which +specifies continuation. If the value is non-@code{nil}, then these +lines are truncated. + +If the variable @code{truncate-partial-width-windows} is non-@code{nil}, +then truncation is always used for side-by-side windows (within one +frame) regardless of the value of @code{truncate-lines}. +@end defopt + +@defvar default-truncate-lines +This variable is the default value for @code{truncate-lines}, for +buffers that do not have local values for it. +@end defvar + +@defopt truncate-partial-width-windows +This variable controls display of lines that extend beyond the right +edge of the window, in side-by-side windows (@pxref{Splitting Windows}). +If it is non-@code{nil}, these lines are truncated; otherwise, +@code{truncate-lines} says what to do with them. +@end defopt + + You can override the images that indicate continuation or truncation +with the display table; see @ref{Display Tables}. + +@node The Echo Area +@section The Echo Area +@cindex error display +@cindex echo area + + The @dfn{echo area} is used for displaying messages made with the +@code{message} primitive, and for echoing keystrokes. It is not the +same as the minibuffer, despite the fact that the minibuffer appears +(when active) in the same place on the screen as the echo area. The +@cite{GNU Emacs Manual} specifies the rules for resolving conflicts +between the echo area and the minibuffer for use of that screen space +(@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}). +Error messages appear in the echo area; see @ref{Errors}. + +You can write output in the echo area by using the Lisp printing +functions with @code{t} as the stream (@pxref{Output Functions}), or as +follows: + +@defun message string &rest arguments +This function prints a one-line message in the echo area. The +argument @var{string} is similar to a C language @code{printf} control +string. See @code{format} in @ref{String Conversion}, for the details +on the conversion specifications. @code{message} returns the +constructed string. + +@c Emacs 19 feature +If @var{string} is @code{nil}, @code{message} clears the echo area. If +the minibuffer is active, this brings the minibuffer contents back onto +the screen immediately. +@example +@group +(message "Minibuffer depth is %d." + (minibuffer-depth)) + @print{} Minibuffer depth is 0. +@result{} "Minibuffer depth is 0." +@end group + +@group +---------- Echo Area ---------- +Minibuffer depth is 0. +---------- Echo Area ---------- +@end group +@end example +@end defun + +@defvar cursor-in-echo-area +This variable controls where the cursor appears when a message is +displayed in the echo area. If it is non-@code{nil}, then the cursor +appears at the end of the message. Otherwise, the cursor appears at +point---not in the echo area at all. + +The value is normally @code{nil}; Lisp programs bind it to @code{t} +for brief periods of time. +@end defvar + +@node Selective Display +@section Selective Display +@cindex selective display + + @dfn{Selective display} is a class of minor modes in which specially +marked lines do not appear on the screen, or in which highly indented +lines do not appear. + + The first variant, explicit selective display, is designed for use in +a Lisp program. The program controls which lines are hidden by altering +the text. Outline mode uses this variant. In the second variant, the +choice of lines to hide is made automatically based on indentation. +This variant is designed as a user-level feature. + + The way you control explicit selective display is by replacing a +newline (control-j) with a carriage return (control-m). The text which +was formerly a line following that newline is now invisible. Strictly +speaking, it is temporarily no longer a line at all, since only newlines +can separate lines; it is now part of the previous line. + + Selective display does not directly affect editing commands. For +example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into +invisible text. However, the replacement of newline characters with +carriage return characters affects some editing commands. For example, +@code{next-line} skips invisible lines, since it searches only for +newlines. Modes that use selective display can also define commands +that take account of the newlines, or that make parts of the text +visible or invisible. + + When you write a selectively displayed buffer into a file, all the +control-m's are output as newlines. This means that when you next read +in the file, it looks OK, with nothing invisible. The selective display +effect is seen only within Emacs. + +@defvar selective-display +This buffer-local variable enables selective display. This means that +lines, or portions of lines, may be made invisible. + +@itemize @bullet +@item +If the value of @code{selective-display} is @code{t}, then any portion +of a line that follows a control-m is not displayed. + +@item +If the value of @code{selective-display} is a positive integer, then +lines that start with more than that many columns of indentation are not +displayed. +@end itemize + +When some portion of a buffer is invisible, the vertical movement +commands operate as if that portion did not exist, allowing a single +@code{next-line} command to skip any number of invisible lines. +However, character movement commands (such as @code{forward-char}) do +not skip the invisible portion, and it is possible (if tricky) to insert +or delete text in an invisible portion. + +In the examples below, we show the @emph{display appearance} of the +buffer @code{foo}, which changes with the value of +@code{selective-display}. The @emph{contents} of the buffer do not +change. + +@example +@group +(setq selective-display nil) + @result{} nil + +---------- Buffer: foo ---------- +1 on this column + 2on this column + 3n this column + 3n this column + 2on this column +1 on this column +---------- Buffer: foo ---------- +@end group + +@group +(setq selective-display 2) + @result{} 2 + +---------- Buffer: foo ---------- +1 on this column + 2on this column + 2on this column +1 on this column +---------- Buffer: foo ---------- +@end group +@end example +@end defvar + +@defvar selective-display-ellipses +If this buffer-local variable is non-@code{nil}, then Emacs displays +@samp{@dots{}} at the end of a line that is followed by invisible text. +This example is a continuation of the previous one. + +@example +@group +(setq selective-display-ellipses t) + @result{} t + +---------- Buffer: foo ---------- +1 on this column + 2on this column ... + 2on this column +1 on this column +---------- Buffer: foo ---------- +@end group +@end example + +You can use a display table to substitute other text for the ellipsis +(@samp{@dots{}}). @xref{Display Tables}. +@end defvar + +@node Overlay Arrow +@section The Overlay Arrow +@cindex overlay arrow + + The @dfn{overlay arrow} is useful for directing the user's attention +to a particular line in a buffer. For example, in the modes used for +interface to debuggers, the overlay arrow indicates the line of code +about to be executed. + +@defvar overlay-arrow-string +This variable holds the string to display as an arrow, or @code{nil} if +the arrow feature is not in use. +@end defvar + +@defvar overlay-arrow-position +This variable holds a marker which indicates where to display the arrow. +It should point at the beginning of a line. The arrow text appears at +the beginning of that line, overlaying any text that would otherwise +appear. Since the arrow is usually short, and the line usually begins +with indentation, normally nothing significant is overwritten. + +The overlay string is displayed only in the buffer which this marker +points into. Thus, only one buffer can have an overlay arrow at any +given time. +@c !!! overlay-arrow-position: but the overlay string may remain in the display +@c of some other buffer until an update is required. This should be fixed +@c now. Is it? +@end defvar + +@node Temporary Displays +@section Temporary Displays + + Temporary displays are used by commands to put output into a buffer +and then present it to the user for perusal rather than for editing. +Many of the help commands use this feature. + +@defspec with-output-to-temp-buffer buffer-name forms@dots{} +This function executes @var{forms} while arranging to insert any +output they print into the buffer named @var{buffer-name}. The buffer +is then shown in some window for viewing, displayed but not selected. + +The string @var{buffer-name} specifies the temporary buffer, which +need not already exist. The argument must be a string, not a buffer. +The buffer is erased initially (with no questions asked), and it is +marked as unmodified after @code{with-output-to-temp-buffer} exits. + +@code{with-output-to-temp-buffer} binds @code{standard-output} to the +temporary buffer, then it evaluates the forms in @var{forms}. Output +using the Lisp output functions within @var{forms} goes by default to +that buffer (but screen display and messages in the echo area, although +they are ``output'' in the general sense of the word, are not affected). +@xref{Output Functions}. + +The value of the last form in @var{forms} is returned. + +@example +@group +---------- Buffer: foo ---------- + This is the contents of foo. +---------- Buffer: foo ---------- +@end group + +@group +(with-output-to-temp-buffer "foo" + (print 20) + (print standard-output)) +@result{} # + +---------- Buffer: foo ---------- +20 + +# + +---------- Buffer: foo ---------- +@end group +@end example +@end defspec + +@defvar temp-buffer-show-function +If this variable, if non-@code{nil}, @code{with-output-to-temp-buffer} +calls it as a function to do the job of displaying a help buffer. The +function gets one argument, which is the buffer it should display. + +In Emacs versions 18 and earlier, this variable was called +@code{temp-buffer-show-hook}. +@end defvar + +@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 +modification status. + +The momentary display remains until the next input event. If the next +input event is @var{char}, @code{momentary-string-display} ignores it +and returns. Otherwise, that event remains buffered for subsequent use +as input. Thus, typing @var{char} will simply remove the string from +the display, while typing (say) @kbd{C-f} will remove the string from +the display and later (presumably) move point forward. The argument +@var{char} is a space by default. + +The return value of @code{momentary-string-display} is not meaningful. + +If @var{message} is non-@code{nil}, it is displayed in the echo area +while @var{string} is displayed in the buffer. If it is @code{nil}, a +default message says to type @var{char} to continue. + +In this example, point is initially located at the beginning of the +second line: + +@example +@group +---------- Buffer: foo ---------- +This is the contents of foo. +@point{}Second line. +---------- Buffer: foo ---------- +@end group + +@group +(momentary-string-display + "**** Important Message! ****" + (point) ?\r + "Type RET when done reading") +@result{} t +@end group + +@group +---------- Buffer: foo ---------- +This is the contents of foo. +**** Important Message! ****Second line. +---------- Buffer: foo ---------- + +---------- Echo Area ---------- +Type RET when done reading +---------- Echo Area ---------- +@end group +@end example +@end defun + +@node Overlays +@section Overlays +@cindex overlays + +You can use @dfn{overlays} to alter the appearance of a buffer's text on +the screen. An overlay is an object which belongs to a particular +buffer, and has a specified beginning and end. It also has properties +that you can examine and set; these affect the display of the text +within the overlay. + +@menu +* Overlay Properties:: How to read and set properties. + What properties do to the screen display. +* Managing Overlays:: Creating, moving, finding overlays. +@end menu + +@node Overlay Properties +@subsection Overlay Properties + +Overlay properties are like text properties in some respects, but the +differences are more important than the similarities. Text properties +are considered a part of the text; overlays are specifically considered +not to be part of the text. Thus, copying text between various buffers +and strings preserves text properties, but does not try to preserve +overlays. Changing a buffer's text properties marks the buffer as +modified, while moving an overlay or changing its properties does not. +Unlike text propery changes, overlay changes are not recorded in the +buffer's undo list. + +@table @code +@item priority +@kindex priority @r{(overlay property)} +This property's value (which should be a nonnegative number) determines +the priority of the overlay. The priority matters when two or more +overlays cover the same character and both specify a face for display; +the one whose @code{priority} value is larger takes priority over the +other, and its face attributes override the face attributes of the lower +priority overlay. + +Currently, all overlays take priority over text properties. Please +avoid using negative priority values, as we have not yet decided just +what they should mean. + +@item window +@kindex window @r{(overlay property)} +If the @code{window} property is non-@code{nil}, then the overlay +applies only on that window. + +@item face +@kindex face @r{(overlay property)} +This property controls the font and color of text. @xref{Faces}, for +more information. This feature is temporary; in the future, we may +replace it with other ways of specifying how to display text. + +@item mouse-face +@kindex mouse-face @r{(overlay property)} +This property is used instead of @code{face} when the mouse is within +the range of the overlay. This feature may be temporary, like +@code{face}. + +@item modification-hooks +@kindex modification-hooks @r{(overlay property)} +This property's value is a list of functions to be called if any +character within the overlay is changed or if text is inserted strictly +within the overlay. Each function receives two arguments: the beginning +and end of the part of the buffer being modified. + +@item insert-in-front-hooks +@kindex insert-in-front-hooks @r{(overlay property)} +This property's value is a list of functions to be called +if text is inserted right at the beginning of the overlay. + +@item insert-behind-hooks +@kindex insert-behind-hooks @r{(overlay property)} +This property's value is a list of functions to be called if text is +inserted right at the end of the overlay. + +@item invisible +@kindex invisible @r{(overlay property)} +A non-@code{nil} @code{invisible} property means that the text in the +overlay does not appear on the screen. This works much like selective +display. Details of this feature are likely to change in future +versions, so check the @file{etc/NEWS} file in the version you are +using. + +@item before-string +@kindex before-string @r{(overlay property)} +This property's value is a string to add to the display at the beginning +of the overlay. The string does not appear in the buffer in any +sense---only on the screen. This is not yet implemented, but will be. + +@item after-string +@kindex after-string @r{(overlay property)} +This property's value is a string to add to the display at the end of +the overlay. The string does not appear in the buffer in any +sense---only on the screen. This is not yet implemented, but will be. +@end table + + These are the functions for reading and writing the properties of an +overlay. + +@defun overlay-get overlay prop +This function returns the value of property @var{prop} recorded in +@var{overlay}. If @var{overlay} does not record any value for that +property, then the value is @code{nil}. +@end defun + +@defun overlay-put overlay prop value +This function sets the value of property @var{prop} recorded in +@var{overlay} to @var{value}. It returns @var{value}. +@end defun + + See also the function @code{get-char-property} which checks both +overlay properties and text properties for a given character. +@xref{Examining Properties}. + +@node Managing Overlays +@subsection Managing Overlays + + This section describes the functions to create, delete and move +overlays, and to examine their contents. + +@defun make-overlay start end &optional buffer +This function creates and returns an overlay which belongs to +@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start} +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. +@end defun + +@defun overlay-start overlay +This function returns the position at which @var{overlay} starts. +@end defun + +@defun overlay-end overlay +This function returns the position at which @var{overlay} ends. +@end defun + +@defun overlay-buffer overlay +This function returns the buffer that @var{overlay} belongs to. +@end defun + +@defun delete-overlay overlay +This function deletes @var{overlay}. The overlay continues to exist as +a Lisp object, but ceases to be part of the buffer it belonged to, and +ceases to have any effect on display. +@end defun + +@defun move-overlay overlay start end &optional buffer +This function moves @var{overlay} to @var{buffer}, and places its bounds +at @var{start} and @var{end}. Both arguments @var{start} and @var{end} +must specify buffer positions; they may be integers or markers. If +@var{buffer} is omitted, the overlay stays in the same buffer. + +The return value is @var{overlay}. + +This is the only valid way to change the endpoints of an overlay. Do +not try modifying the markers in the overlay by hand, as that fails to +update other vital data structures and can cause some overlays to be +``lost''. +@end defun + +@defun overlays-at pos +This function returns a list of all the overlays that contain position +@var{pos} in the current buffer. The list is in no particular order. +An overlay contains position @var{pos} if it begins at or before +@var{pos}, and ends after @var{pos}. +@end defun + +@defun next-overlay-change pos +This function returns the buffer position of the next beginning or end +of an overlay, after @var{pos}. +@end defun + +@node Faces +@section Faces +@cindex face + +A @dfn{face} is a named collection of graphical attributes: font, +foreground color, background color and optional underlining. Faces +control the display of text on the screen. + +@cindex face id +Each face has its own @dfn{face id number} which distinguishes faces at +low levels within Emacs. However, for most purposes, you can refer to +faces in Lisp programs by their names. + +Each face name is meaningful for all frames, and by default it has the +same meaning in all frames. But you can arrange to give a particular +face name a special meaning in one frame if you wish. + +@menu +* Standard Faces:: The faces Emacs normally comes with. +* Merging Faces:: How Emacs decides which face to use for a character. +* Face Functions:: How to define and examine faces. +@end menu + +@node Standard Faces +@subsection Standard Faces + + This table lists all the standard faces and their uses. + +@table @code +@item default +@kindex default @r{(face name)} +This face is used for ordinary text. + +@item modeline +@kindex modeline @r{(face name)} +This face is used for mode lines and menu bars. + +@item region +@kindex region @r{(face name)} +This face is used for highlighting the region in Transient Mark mode. + +@item secondary-selection +@kindex secondary-selection @r{(face name)} +This face is used to show any secondary selection you have made. + +@item highlight +@kindex highlight @r{(face name)} +This face is meant to be used for highlighting for various purposes. + +@item underline +@kindex underline @r{(face name)} +This face underlines text. + +@item bold +@kindex bold @r{(face name)} +This face uses a bold font, if possible. It uses the bold variant of +the frame's font, if it has one. It's up to you to choose a default +font that has a bold variant, if you want to use one. + +@item italic +@kindex italic @r{(face name)} +This face uses the italic variant of the frame's font, if it has one. + +@item bold-italic +@kindex bold-italic @r{(face name)} +This face uses the bold italic variant of the frame's font, if it has +one. +@end table + +@node Merging Faces +@subsection Merging Faces for Display + + Here are all the ways to specify which face to use for display of text: + +@itemize @bullet +@item +With defaults. Each frame has a @dfn{default face}, whose id number is +zero, which is used for all text that doesn't somehow specify another +face. + +@item +With text properties. A character may have a @code{face} property; if so, +it's displayed with that face. @xref{Special Properties}. + +If the character has a @code{mouse-face} property, that is used instead +of the @code{face} property when the mouse is ``near enough'' to the +character. + +@item +With overlays. An overlay may have @code{face} and @code{mouse-face} +properties too; they apply to all the text covered by the overlay. + +@item +With special glyphs. Each glyph can specify a particular face id +number. @xref{Glyphs}. +@end itemize + + If these various sources together specify more than one face for a +particular character, Emacs merges the attributes of the various faces +specified. The attributes of the faces of special glyphs come first; +then come attributes of faces from overlays, followed by those from text +properties, and last the default face. + + When multiple overlays cover one character, an overlay with higher +priority overrides those with lower priority. @xref{Overlays}. + + If an attribute such as the font or a color is not specified in any of +the above ways, the frame's own font or color is used. + +@node Face Functions +@subsection Functions for Working with Faces + + The attributes a face can specify include the font, the foreground +color, the background color, and underlining. The face can also leave +these unspecified by giving the value @code{nil} for them. + + Here are the primitives for creating and changing faces. + +@defun make-face name +This function defines a new face named @var{name}, initially with all +attributes @code{nil}. It does nothing if there is already a face named +@var{name}. +@end defun + +@defun face-list +This function returns a list of all defined face names. +@end defun + +@defun copy-face old-face new-name &optional frame new-frame +This function defines the face @var{new-name} as a copy of the existing +face named @var{old-face}. It creates the face @var{new-name} if that +doesn't already exist. + +If the optional argument @var{frame} is given, this function applies +only to that frame. Otherwise it applies to each frame individually, +copying attributes from @var{old-face} in each frame to @var{new-face} +in the same frame. + +If the optional argument @var{new-frame} is given, then @code{copy-face} +copies the attributes of @var{old-face} in @var{frame} to @var{new-name} +in @var{new-frame}. +@end defun + + You can modify the attributes of an existing face with the following +functions. If you specify @var{frame}, they affect just that frame; +otherwise, they affect all frames as well as the defaults that apply to +new frames. + +@defun set-face-foreground face color &optional frame +@defunx set-face-background face color &optional frame +These functions set the foreground (respectively, background) color of +face @var{face} to @var{color}. The argument @var{color} should be a +string, the name of a color. +@end defun + +@defun set-face-font face font &optional frame +This function sets the font of face @var{face}. The argument @var{font} +should be a string. +@end defun + +@defun set-face-underline-p face underline-p &optional frame +This function sets the underline attribute of face @var{face}. +Non-@code{nil} means do underline; @code{nil} means don't. +@end defun + +@defun invert-face face &optional frame +Swap the foreground and background colors of face @var{face}. If the +face doesn't specify both foreground and background, then its foreground +and background are set to the default background and foreground. +@end defun + + These functions examine the attributes of a face. If you don't +specify @var{frame}, they refer to the default data for new frames. + +@defun face-foreground face &optional frame +@defunx face-background face &optional frame +These functions return the foreground (respectively, background) color +of face @var{face}, as a string. +@end defun + +@defun face-font face &optional frame +This function returns the name of the font of face @var{face}. +@end defun + +@defun face-underline-p face &optional frame +This function returns the underline attribute of face @var{face}. +@end defun + +@defun face-id-number face +This function returns the face id number of face @var{face}. +@end defun + +@defun face-equal face1 face2 &optional frame +This returns @code{t} if the faces @var{face1} and @var{face2} have the +same attributes for display. +@end defun + +@defun face-differs-from-default-p face &optional frame +This returns @code{t} if the face @var{face} displays differently from +the default face. A face is considered to be ``the same'' as the normal +face if each attribute is either the same as that of the default face or +@code{nil} (meaning to inherit from the default). +@end defun + +@defvar region-face +This variable's value specifies the face id to use to display characters +in the region when it is active (in Transient Mark mode only). The face +thus specified takes precedence over all faces that come from text +properties and overlays, for characters in the region. @xref{The Mark}, +for more information about Transient Mark mode. + +Normally, the value is the id number of the face named @code{region}. +@end defvar + +@node Blinking +@section Blinking Parentheses +@cindex parenthesis matching +@cindex blinking +@cindex balancing parentheses +@cindex close parenthesis + + This section describes the mechanism by which Emacs shows a matching +open parenthesis when the user inserts a close parenthesis. + +@vindex blink-paren-hook +@defvar blink-paren-function +The value of this variable should be a function (of no arguments) to +be called whenever a character with close parenthesis syntax is inserted. +The value of @code{blink-paren-function} may be @code{nil}, in which +case nothing is done. + +@quotation +@strong{Please note:} this variable was named @code{blink-paren-hook} in +older Emacs versions, but since it is not called with the standard +convention for hooks, it was renamed to @code{blink-paren-function} in +version 19. +@end quotation +@end defvar + +@defvar blink-matching-paren +If this variable is @code{nil}, then @code{blink-matching-open} does +nothing. +@end defvar + +@defvar blink-matching-paren-distance +This variable specifies the maximum distance to scan for a matching +parenthesis before giving up. +@end defvar + +@defun blink-matching-open +This function is the default value of @code{blink-paren-function}. It +assumes that point follows a character with close parenthesis syntax and +moves the cursor momentarily to the matching opening character. If that +character is not already on the screen, it displays the character's +context in the echo area. To avoid long delays, this function does not +search farther than @code{blink-matching-paren-distance} characters. + +Here is an example of calling this function explicitly. + +@smallexample +@group +(defun interactive-blink-matching-open () +@c Do not break this line! -- rms. +@c The first line of a doc string +@c must stand alone. + "Indicate momentarily the start of sexp before point." + (interactive) +@end group +@group + (let ((blink-matching-paren-distance + (buffer-size)) + (blink-matching-paren t)) + (blink-matching-open))) +@end group +@end smallexample +@end defun + +@node Inverse Video +@section Inverse Video +@cindex Inverse Video + +@defopt inverse-video +@cindex highlighting +This variable controls whether Emacs uses inverse video for all text +on the screen. Non-@code{nil} means yes, @code{nil} means no. The +default is @code{nil}. +@end defopt + +@defopt mode-line-inverse-video +This variable controls the use of inverse video for mode lines. If it +is non-@code{nil}, then mode lines are displayed in inverse video (under +X, this uses the face named @code{modeline}, which you can set as you +wish). Otherwise, mode lines are displayed normally, just like text. +The default is @code{t}. +@end defopt + +@node Usual Display +@section Usual Display Conventions + + The usual display conventions define how to display each character +code. You can override these conventions by setting up a display table +(@pxref{Display Tables}). Here are the usual display conventions: + +@itemize @bullet +@item +Character codes 32 through 126 map to glyph codes 32 through 126. +Normally this means they display as themselves. + +@item +Character code 9 is a horizontal tab. It displays as whitespace +up to a position determined by @code{tab-width}. + +@item +Character code 10 is a newline. + +@item +All other codes in the range 0 through 31, and code 127, display in one +of two ways according to the value of @code{ctl-arrow}. If it is is +non-@code{nil}, these codes map to sequences of two glyphs, where the +first glyph is the @sc{ASCII} code for @samp{^}. (A display table can +specify a glyph to use instead of @samp{^}.) Otherwise, these codes map +just like the codes in the range 128 to 255. + +@item +Character codes 128 through 255 map to sequences of four glyphs, where +the first glyph is the @sc{ASCII} code for @samp{\}, and the others are +digit characters representing the code in octal. (A display table can +specify a glyph to use instead of @samp{\}.) +@end itemize + + The usual display conventions apply even when there is a display +table, for any character whose entry in the active display table is +@code{nil}. Thus, when you set up a display table, you need only +specify the the characters for which you want unusual behavior. + + These variables affect the way certain characters are displayed on the +screen. Since they change the number of columns the characters occupy, +they also affect the indentation functions. + +@defopt ctl-arrow +@cindex control characters in display +This buffer-local variable controls how control characters are +displayed. If it is non-@code{nil}, they are displayed as a caret +followed by the character: @samp{^A}. If it is @code{nil}, they are +displayed as a backslash followed by three octal digits: @samp{\001}. +@end defopt + +@c Following may have overfull hbox. +@defvar default-ctl-arrow +The value of this variable is the default value for @code{ctl-arrow} in +buffers that do not override it. @xref{Default Value}. +@end defvar + +@defopt tab-width +The value of this variable is the spacing between tab stops used for +displaying tab characters in Emacs buffers. The default is 8. Note +that this feature is completely independent from the user-settable tab +stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}. +@end defopt + +@node Display Tables +@section Display Tables + +@cindex display table +You can use the @dfn{display table} feature to control how all 256 +possible character codes display on the screen. This is useful for +displaying European languages that have letters not in the @sc{ASCII} +character set. + +The display table maps each character code into a sequence of +@dfn{glyphs}, each glyph being an image that takes up one character +position on the screen. You can also define how to display each glyph +on your terminal, using the @dfn{glyph table}. + +@menu +* Display Table Format:: What a display table consists of. +* Active Display Table:: How Emacs selects a display table to use. +* Glyphs:: How to define a glyph, and what glyphs mean. +* ISO Latin 1:: How to use display tables + to support the ISO Latin 1 character set. +@end menu + +@node Display Table Format +@subsection Display Table Format + + A display table is actually an array of 261 elements. + +@defun make-display-table +This creates and returns a display table. The table initially has +@code{nil} in all elements. +@end defun + + The first 256 elements correspond to character codes; the @var{n}th +element says how to display the character code @var{n}. The value +should be @code{nil} or a vector of glyph values (@pxref{Glyphs}). If +an element is @code{nil}, it says to display that character according to +the usual display conventions (@pxref{Usual Display}). + + The remaining five elements of a display table serve special purposes, +and @code{nil} means use the default stated below. + +@table @asis +@item 256 +The glyph for the end of a truncated screen line (the default for this +is @samp{$}). @xref{Glyphs}. +@item 257 +The glyph for the end of a continued line (the default is @samp{\}). +@item 258 +The glyph for indicating a character displayed as an octal character +code (the default is @samp{\}). +@item 259 +The glyph for indicating a control character (the default is @samp{^}). +@item 260 +A vector of glyphs for indicating the presence of invisible lines (the +default is @samp{...}). @xref{Selective Display}. +@end table + + For example, here is how to construct a display table that mimics the +effect of setting @code{ctl-arrow} to a non-@code{nil} value: + +@example +(setq disptab (make-display-table)) +(let ((i 0)) + (while (< i 32) + (or (= i ?\t) (= i ?\n) + (aset disptab i (vector ?^ (+ i 64)))) + (setq i (1+ i))) + (aset disptab 127 (vector ?^ ??))) +@end example + +@node Active Display Table +@subsection Active Display Table +@cindex active display table + + Each window can specify a display table, and so can each buffer. When +a buffer @var{b} is displayed in window @var{w}, display uses the +display table for window @var{w} if it has one; otherwise, the display +table for buffer @var{b} if it has one; otherwise, the standard display +table if any. The display table chosen is called the @dfn{active} +display table. + +@defun window-display-table window +This function returns @var{window}'s display table, or @code{nil} +if @var{window} does not have an assigned display table. +@end defun + +@defun set-window-display-table window table +This function sets the display table of @var{window} to @var{table}. +The argument @var{table} should be either a display table or +@code{nil}. +@end defun + +@defvar buffer-display-table +This variable is automatically local in all buffers; its value in a +particular buffer is the display table for that buffer, or @code{nil} if +the buffer does not have an assigned display table. +@end defvar + +@defvar standard-display-table +This variable's value is the default display table, used whenever a +window has no display table and neither does the buffer displayed in +that window. This variable is @code{nil} by default. +@end defvar + + If there is no display table to use for a particular window---that is, +if the window has none, its buffer has none, and +@code{standard-display-table} has none---then Emacs uses the usual +display conventions for all character codes in that window. @xref{Usual +Display}. + +@node Glyphs +@subsection Glyphs + +@cindex glyph + A @dfn{glyph} is a generalization of a character; it stands for an +image that takes up a single character position on the screen. Glyphs +are represented in Lisp as integers, just as characters are. + +@cindex glyph table + The meaning of each integer, as a glyph, is defined by the glyph +table, which is the value of the variable @code{glyph-table}. + +@defvar glyph-table +The value of this variable is the current glyph table. It should be a +vector; the @var{g}th element defines glyph code @var{g}. If the value +is @code{nil} instead of a vector, then all glyphs are simple (see +below). +@end defvar + + Here are the possible types of elements in the glyph table: + +@table @var +@item string +Send the characters in @var{string} to the terminal to output +this glyph. This alternative is available on character terminals, +but not under X. + +@item integer +Define this glyph code as an alias for code @var{integer}. You can use +an alias to specify a face code for the glyph; see below. + +@item @code{nil} +This glyph is simple. On an ordinary terminal, the glyph code mod 256 +is the character to output. With X, the glyph code mod 256 is the +character to output, and the glyph code divided by 256 specifies the +@dfn{face id number} to use while outputting it. @xref{Faces}. +@end table + + If a glyph code is greater than or equal to the length of the glyph +table, that code is automatically simple. + +@node ISO Latin 1 +@subsection ISO Latin 1 + +If you have a terminal that can handle the entire ISO Latin 1 character +set, you can arrange to use that character set as follows: + +@example +(require 'disp-table) +;; @r{Set char codes 160--255 to display as themselves.} +;; @r{(Codes 128--159 are the additional control characters.)} +(standard-display-8bit 160 255) +@end example + +If you are editing buffers written in the ISO Latin 1 character set and +your terminal doesn't handle anything but @sc{ASCII}, you can load the file +@file{iso-ascii} to set up a display table which makes the other ISO +characters display as sequences of @sc{ASCII} characters. For example, the +character ``o with umlaut'' displays as @samp{@{"o@}}. + +Some European countries have terminals that don't support ISO Latin 1 +but do support the special characters for that country's language. You +can define a display table to work one language using such terminals. +For an example, see @file{lisp/iso-swed.el}, which handles certain +Swedish terminals. + +You can load the appropriate display table for your terminal +automatically by writing a terminal-specific Lisp file for the terminal +type. + +@node Beeping +@section Beeping +@cindex beeping +@cindex bell + + You can make Emacs ring a bell (or blink the screen) to attract the +user's attention. Be conservative about how often you do this; frequent +bells can become irritating. Also be careful not to use beeping alone +when signaling an error is appropriate. (@xref{Errors}.) + +@defun ding &optional dont-terminate +@cindex keyboard macro termination +This function beeps, or flashes the screen (see @code{visible-bell} below). +It also terminates any keyboard macro currently executing unless +@var{dont-terminate} is non-@code{nil}. +@end defun + +@defun beep &optional dont-terminate +This is a synonym for @code{ding}. +@end defun + +@defvar visible-bell +This variable determines whether Emacs should flash the screen to +represent a bell. Non-@code{nil} means yes, @code{nil} means no. This +is effective only if the Termcap entry for the terminal in use has the +visible bell flag (@samp{vb}) set. +@end defvar + +@node Window Systems +@section Window Systems + + Emacs works with several window systems, most notably the X Window +System. Both Emacs and X use the term ``window'', but use it +differently. An Emacs frame is a single window as far as X is +concerned; the individual Emacs windows are not known to X at all. + +@defvar window-system +@cindex X Window System +This variable tells Lisp programs what window system Emacs is running +under. Its value should be a symbol such as @code{x} (if Emacs is +running under X) or @code{nil} (if Emacs is running on an ordinary +terminal). +@end defvar + +@defvar window-system-version +This variable distinguishes between different versions of the X Window +System. Its value is 10 or 11 when using X; @code{nil} otherwise. +@end defvar + +@defvar window-setup-hook +This variable is a normal hook which Emacs runs after loading your +@file{.emacs} file and the default initialization file (if any), after +loading terminal-specific Lisp code, and after running the hook +@code{term-setup-hook}. + +This hook is used for internal purposes: setting up communication with +the window system, and creating the initial window. Users should not +interfere with it. +@end defvar -- 2.20.1