diff options
Diffstat (limited to 'lispref/display.texi')
| -rw-r--r-- | lispref/display.texi | 1464 |
1 files changed, 0 insertions, 1464 deletions
diff --git a/lispref/display.texi b/lispref/display.texi deleted file mode 100644 index ae91f450924..00000000000 --- a/lispref/display.texi +++ /dev/null @@ -1,1464 +0,0 @@ -@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. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* 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 - - 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. - - 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. - -@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 - -@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 access or specify 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 Tables}.) - - 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 - -@defopt default-truncate-lines -This variable is the default value for @code{truncate-lines}, for -buffers that do not have local values for it. -@end defopt - -@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}. - - If your buffer contains @strong{very} long lines, and you use -continuation to display them, just thinking about them can make Emacs -redisplay slow. The column computation and indentation functions also -become slow. Then you might find it advisable to set -@code{cache-long-line-scans} to @code{t}. - -@defvar cache-long-line-scans -If this variable is non-@code{nil}, various indentation and motion -functions, and Emacs redisplay, cache the results of scanning the -buffer, and consult the cache to avoid rescanning regions of the buffer -unless they are modified. - -Turning on the cache slows down processing of short lines somewhat. - -This variable is automatically local in every buffer. -@end defvar - -@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 displays 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. - -In batch mode, @code{message} prints the message text on the standard -error stream, followed by a newline. - -@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 - -Almost all the messages displayed in the echo area are also recorded -in the @samp{*Messages*} buffer. - -@defopt message-log-max -This variable specifies how many lines to keep in the @samp{*Messages*} -buffer. The value @code{t} means there is no limit on how many lines to -keep. The value @code{nil} disables message logging entirely. Here's -how to display a message and prevent it from being logged: - -@example -(let (message-log-max) - (message @dots{})) -@end example -@end defopt - -@defvar echo-keystrokes -This variable determines how much time should elapse before command -characters echo. Its value must be an integer, which specifies the -number of seconds to wait before echoing. If the user types a prefix -key (such as @kbd{C-x}) and then delays this many seconds before -continuing, the prefix key is echoed in the echo area. Any subsequent -characters in the same command will be echoed as well. - -If the value is zero, then command input is not echoed. -@end defvar - -@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 Invisible Text -@section Invisible Text - -@cindex invisible text -You can make characters @dfn{invisible}, so that they do not appear on -the screen, with the @code{invisible} property. This can be either a -text property or a property of an overlay. - -In the simplest case, any non-@code{nil} @code{invisible} property makes -a character invisible. This is the default case---if you don't alter -the default value of @code{buffer-invisibility-spec}, this is how the -@code{invisibility} property works. This feature is much like selective -display (@pxref{Selective Display}), but more general and cleaner. - -More generally, you can use the variable @code{buffer-invisibility-spec} -to control which values of the @code{invisible} property make text -invisible. This permits you to classify the text into different subsets -in advance, by giving them different @code{invisible} values, and -subsequently make various subsets visible or invisible by changing the -value of @code{buffer-invisibility-spec}. - -Controlling visibility with @code{buffer-invisibility-spec} is -especially useful in a program to display the list of entries in a data -base. It permits the implementation of convenient filtering commands to -view just a part of the entries in the data base. Setting this variable -is very fast, much faster than scanning all the text in the buffer -looking for properties to change. - -@defvar buffer-invisibility-spec -This variable specifies which kinds of @code{invisible} properties -actually make a character invisible. - -@table @asis -@item @code{t} -A character is invisible if its @code{invisible} property is -non-@code{nil}. This is the default. - -@item a list -Each element of the list makes certain characters invisible. -Ultimately, a character is invisible if any of the elements of this list -applies to it. The list can have two kinds of elements: - -@table @code -@item @var{atom} -A character is invisible if its @code{invisible} propery value -is @var{atom} or if it is a list with @var{atom} as a member. - -@item (@var{atom} . t) -A character is invisible if its @code{invisible} propery value -is @var{atom} or if it is a list with @var{atom} as a member. -Moreover, if this character is at the end of a line and is followed -by a visible newline, it displays an ellipsis. -@end table -@end table -@end defvar - -@vindex line-move-ignore-invisible - Ordinarily, commands that operate on text or move point do not care -whether the text is invisible. The user-level line motion commands -explicitly ignore invisible newlines if -@code{line-move-ignore-invisible} is non-@code{nil}, but only because -they are explicitly programmed to do so. - -@node Selective Display -@section Selective Display -@cindex selective display - - @dfn{Selective display} is a pair of features that hide certain -lines on the screen. - - 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 has traditionally used this variant. It has -been partially replaced by the invisible text feature (@pxref{Invisible -Text}); there is a new version of Outline mode which uses that instead. - - In the second variant, the choice of lines to hide is made -automatically based on indentation. This variant is designed to be 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 that -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 to call attention to a -particular line, or @code{nil} if the arrow feature is not in use. -@end defvar - -@defvar overlay-arrow-position -This variable holds a marker that indicates where to display the overlay -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 that 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 - - You can do the same job by creating an overlay with a -@code{before-string} property. @xref{Overlay Properties}. - -@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> - ----------- Buffer: foo ---------- -20 - -#<buffer foo> - ----------- Buffer: foo ---------- -@end group -@end example -@end defspec - -@defvar temp-buffer-show-function -If this variable is 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 the string @var{string} does not contain control characters, you can -do the same job in a more general way by creating an overlay with a -@code{before-string} property. @xref{Overlay Properties}. - -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, for the sake of presentation features. An overlay is an -object that 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 category -@kindex category @r{(overlay property)} -If an overlay has a @code{category} property, we call it the -@dfn{category} of the overlay. It should be a symbol. The properties -of the symbol serve as defaults for the properties of the overlay. - -@item face -@kindex face @r{(overlay property)} -This property controls the font and color of text. Its value is a face -name or a list of face names. @xref{Faces}, for more information. This -feature may be 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. - -The hook functions are called both before and after each change. -If the functions save the information they receive, and compare notes -between calls, they can determine exactly what change has been made -in the buffer text. - -When called before a change, each function receives four arguments: the -overlay, @code{nil}, and the beginning and end of the text range to be -modified. - -When called after a change, each function receives five arguments: the -overlay, @code{t}, the beginning and end of the text range just -modified, and the length of the pre-change text replaced by that range. -(For an insertion, the pre-change length is zero; for a deletion, that -length is the number of characters deleted, and the post-change -beginning and end are equal.) - -@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 before and -after inserting text right at the beginning of the overlay. The calling -conventions are the same as for the @code{modification-hooks} functions. - -@item insert-behind-hooks -@kindex insert-behind-hooks @r{(overlay property)} -This property's value is a list of functions to be called before and -after inserting text right at the end of the overlay. The calling -conventions are the same as for the @code{modification-hooks} functions. - -@item invisible -@kindex invisible @r{(overlay property)} -The @code{invisible} property can make the text in the overlay -invisible, which means that it does not appear on the screen. -@xref{Invisible Text}, for details. - -@ignore This isn't implemented yet -@item intangible -@kindex intangible @r{(overlay property)} -The @code{intangible} property on an overlay works just like the -@code{intangible} text property. @xref{Special Properties}, for details. -@end ignore - -@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. The string should contain only characters -that display as a single column---control characters, including tabs or -newlines, will give strange results. - -@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. The string should contain only characters -that display as a single column---control characters, including tabs or -newlines, will give strange results. - -@item evaporate -@kindex evaporate @r{(overlay property)} -If this property is non-@code{nil}, the overlay is deleted automatically -if it ever becomes empty (i.e., if it spans no characters). - -@item local-map -@cindex keymap of character -@kindex local-map @r{(text property)} -If this property is non-@code{nil}, it specifies a keymap for a portion -of the text. The property's value replaces the buffer's local map, when -the character after point is within the overlay. @xref{Active Keymaps}. -@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 any. If @var{overlay} does not record any value for -that property, but it does have a @code{category} property which is a -symbol, that symbol's @var{prop} property is used. Otherwise, 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 that 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 - -@defun previous-overlay-change pos -This function returns the buffer position of the previous beginning or -end of an overlay, before @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. - -@defun facep object -This function returns @code{t} if @var{object} is a face name symbol (or -if it is a vector of the kind used internally to record face data). It -returns @code{nil} otherwise. -@end defun - -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 is 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 a region that is active. In Transient Mark mode, the region is -highlighted with a particular face (see @code{region-face}, below). - -@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 comes the face for region highlighting, if appropriate; -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 (or background, respectively) color -of face @var{face} to @var{color}. The argument @var{color} should be a -string, the name of a color. - -Certain shades of gray are implemented by stipple patterns on -black-and-white screens. -@end defun - -@defun set-face-stipple face pattern &optional frame -This function sets the background stipple pattern of face @var{face} to -@var{pattern}. The argument @var{pattern} should be the name of a -stipple pattern defined by the X server, or @code{nil} meaning don't use -stipple. - -Normally there is no need to pay attention to stipple patterns, because -they are used automatically to handle certain shades of gray. -@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, -respectively. -@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 color (or background color, -respectively) of face @var{face}, as a string. -@end defun - -@defun face-stipple face &optional frame -This function returns the name of the background stipple pattern of face -@var{face}, or @code{nil} if it doesn't have one. -@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 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 - -@defvar blink-matching-paren-delay -This variable specifies the number of seconds for the cursor to remain -at the matching parenthesis. A fraction of a second often gives -good results, but the default is 1, which works on all systems. -@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. -Otherwise, mode lines are displayed normally, just like text. The -default is @code{t}. - -For X window frames, this displays mode lines using the face named -@code{modeline}, which is normally the inverse of the default face -unless you change it. -@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 -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 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 262 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}). - - If you use the display table to change the display of newline -characters, the whole buffer will be displayed as one long ``line.'' - - The remaining six 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}. -@item 261 -The glyph used to draw the border between side-by-side windows (the -default is @samp{|}). @xref{Splitting Windows}. -@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 that displays the other -ISO characters as explanatory 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 under X windows, and on a character-only terminal provided -the terminal's Termcap entry defines the visible bell capability -(@samp{vb}). -@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-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 |