@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
-@c 2002, 2005 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
@node Display, System Interface, Processes, Top
* Images:: Displaying images in Emacs buffers.
* Buttons:: Adding clickable buttons to Emacs buffers.
* 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.
@menu
* Displaying Messages:: Explicitly displaying text in the echo area.
-* Progress Reports:: Informing user about progress of a long operation.
+* Progress:: Informing user about progress of a long operation.
* Logging Messages:: Echo area messages are logged for the user.
* Echo Area Customization:: Controlling the echo area.
@end menu
This section describes the functions for explicitly producing echo
area messages. Many other Emacs features display messages there, too.
-@defun message string &rest arguments
-This function displays a message in the echo area. The
-argument @var{string} is similar to a C language @code{printf} control
+@defun message format-string &rest arguments
+This function displays a message in the echo area. The argument
+@var{format-string} is similar to a C language @code{printf} format
string. See @code{format} in @ref{Formatting Strings}, 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.
-If @var{string}, or strings among the @var{arguments}, have @code{face}
-text properties, these affect the way the message is displayed.
+If @var{format-string}, or strings among the @var{arguments}, have
+@code{face} text properties, these affect the way the message is displayed.
@c Emacs 19 feature
-If @var{string} is @code{nil}, @code{message} clears the echo area; if
-the echo area has been expanded automatically, this brings it back to
-its normal size. If the minibuffer is active, this brings the
-minibuffer contents back onto the screen immediately.
+If @var{format-string} is @code{nil} or the empty string,
+@code{message} clears the echo area; if the echo area has been
+expanded automatically, this brings it back to its normal size.
+If the minibuffer is active, this brings the minibuffer contents back
+onto the screen immediately.
@example
@group
the previous echo area contents.
@end defmac
-@defun message-or-box string &rest arguments
+@defun message-or-box format-string &rest arguments
This function displays a message like @code{message}, but may display it
in a dialog box instead of the echo area. If this function is called in
a command that was invoked using the mouse---more precisely, if
@code{last-nonmenu-event} to a suitable value around the call.
@end defun
-@defun message-box string &rest arguments
+@defun message-box format-string &rest arguments
This function displays a message like @code{message}, but uses a dialog
box (or a pop-up menu) whenever that is possible. If it is impossible
to use a dialog box or pop-up menu, because the terminal does not
Secondly, ``done'' is more explicit.
@end defun
-@defmac dotimes-with-progress-reporter (var count [result]) message body...
+@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{}
This is a convenience macro that works the same way as @code{dotimes}
does, but also reports loop progress using the functions described
above. It allows you to save some typing.
If the value is zero, then command input is not echoed.
@end defvar
-@defopt max-mini-window-height
-This variable specifies the maximum height for resizing minibuffer
-windows. If a float, it specifies a fraction of the height of the
-frame. If an integer, it specifies a number of lines.
-@end defopt
-
@defvar message-truncate-lines
Normally, displaying a long message resizes the echo area to display
the entire message. But if the variable @code{message-truncate-lines}
truncated to fit it, as in Emacs 20 and before.
@end defvar
+ The variable @code{max-mini-window-height}, which specifies the
+maximum height for resizing minibuffer windows, also applies to the
+echo area (which is really a special use of the minibuffer window.
+@xref{Minibuffer Misc}.
+
@node Warnings
@section Reporting Warnings
@cindex warnings
current buffer.
The arguments @var{front-advance} and @var{rear-advance} specify the
-insertion type for the start of the overlay and for the end of the
-overlay, respectively. @xref{Marker Insertion Types}. If
-@var{front-advance} is non-@code{nil}, text inserted at the beginning
-of the overlay is excluded from the overlay. If @var{read-advance} is
-non-@code{nil}, text inserted at the beginning of the overlay is
-included in the overlay.
+marker insertion type for the start of the overlay and for the end of
+the overlay, respectively. @xref{Marker Insertion Types}. If they
+are both @code{nil}, the default, then the overlay extends to include
+any text inserted at the beginning, but not text inserted at the end.
+If @var{front-advance} is non-@code{nil}, text inserted at the
+beginning of the overlay is excluded from the overlay. If
+@var{rear-advance} is non-@code{nil}, text inserted at the end of the
+overlay is included in the overlay.
@end defun
@defun overlay-start overlay
length is the number of characters deleted, and the post-change
beginning and end are equal.)
+If these functions modify the buffer, they should bind
+@code{inhibit-modification-hooks} to @code{t} around doing so, to
+avoid confusing the internal mechanism that calls these hooks.
+
@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
@code{(point-min)}.
@end defun
- Here's an easy way to use @code{next-overlay-change} to search for the
-next character which gets a non-@code{nil} @code{happy} property from
+ Here's a function which uses @code{next-overlay-change} to search
+for the next character which gets a given property @code{prop} from
either its overlays or its text properties (@pxref{Property Search}):
@smallexample
(defun find-overlay-prop (prop)
(save-excursion
(while (and (not (eobp))
- (not (get-char-property (point) 'happy)))
+ (not (get-char-property (point) prop)))
(goto-char (min (next-overlay-change (point))
- (next-single-property-change (point) 'happy))))
+ (next-single-property-change (point) prop))))
(point)))
@end smallexample
+ Now you can search for a @code{happy} property like this:
+
+@smallexample
+(find-overlay-prop 'happy)
+@end smallexample
+
@node Width
@section Width
@vindex default-line-spacing
You can specify the line spacing for all lines in a frame with the
-@code{line-spacing} frame parameter, @xref{Window Frame Parameters}.
+@code{line-spacing} frame parameter (@pxref{Layout Parameters}).
However, if the variable @code{default-line-spacing} is
non-@code{nil}, it overrides the frame's @code{line-spacing}
parameter. An integer value specifies the number of pixels put below
A @dfn{face} is a named collection of graphical attributes: font
family, foreground color, background color, optional underlining, and
many others. Faces are used in Emacs to control the style of display of
-particular parts of the text or the frame.
+particular parts of the text or the frame. @xref{Standard Faces,,,
+emacs, The GNU Emacs Manual}, for the list of faces Emacs normally
+comes with.
@cindex face id
Each face has its own @dfn{face number}, which distinguishes faces at
face name a special meaning in one frame if you wish.
@menu
-* Standard Faces:: The faces Emacs normally comes with.
* Defining Faces:: How to define a face with @code{defface}.
* Face Attributes:: What is in a face?
* Attribute Functions:: Functions to examine and set face attributes.
that handle a range of character sets.
@end menu
-@node Standard Faces
-@subsection Standard Faces
-
- This table lists all the standard faces and their uses. Most of them
-are used for displaying certain parts of the frames or certain kinds of
-text; you can control how those places look by customizing these faces.
-
-@table @code
-@item default
-@kindex default @r{(face name)}
-This face is used for ordinary text.
-
-@item mode-line
-@kindex mode-line @r{(face name)}
-This face is used for the mode line of the selected window, and for
-menu bars when toolkit menus are not used---but only if
-@code{mode-line-inverse-video} is non-@code{nil}.
-
-@item modeline
-@kindex modeline @r{(face name)}
-This is an alias for the @code{mode-line} face, for compatibility with
-old Emacs versions.
-
-@item mode-line-inactive
-@kindex mode-line-inactive @r{(face name)}
-This face is used for mode lines of non-selected windows.
-This face inherits from @code{mode-line}, so changes
-in that face affect all windows.
-
-@item header-line
-@kindex header-line @r{(face name)}
-This face is used for the header lines of windows that have them.
-
-@item menu
-This face controls the display of menus, both their colors and their
-font. (This works only on certain systems.)
-
-@item fringe
-@kindex fringe @r{(face name)}
-This face controls the default colors of window fringes, the thin
-areas on either side that are used to display continuation and
-truncation glyphs. Other faces used to display bitmaps in the fringe
-are implicitly merged with this face.
-
-@item minibuffer-prompt
-@kindex minibuffer-prompt @r{(face name)}
-@vindex minibuffer-prompt-properties
-This face is used for the text of minibuffer prompts. By default,
-Emacs automatically adds this face to the value of
-@code{minibuffer-prompt-properties}, which is a list of text
-properties used to display the prompt text.
-
-@item scroll-bar
-@kindex scroll-bar @r{(face name)}
-This face controls the colors for display of scroll bars.
-
-@item tool-bar
-@kindex tool-bar @r{(face name)}
-This face is used for display of the tool bar, if any.
-
-@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 mode-line-highlight
-@kindex mode-line-highlight @r{(face name)}
-This face is used for highlighting something on @code{mode-line} or
-@code{header-line} for various purposes.
-
-@item trailing-whitespace
-@kindex trailing-whitespace @r{(face name)}
-This face is used to display excess whitespace at the end of a line,
-if @code{show-trailing-whitespace} is non-@code{nil}.
-
-@item escape-glyph
-@kindex escape-glyph @r{(face name)}
-This face is used to display control characters and escape glyphs.
-@end table
-
- In contrast, these faces are provided to change the appearance of text
-in specific ways. You can use them on specific text, when you want
-the effects they produce.
-
-@table @code
-@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.
-
-@item underline
-@kindex underline @r{(face name)}
-This face underlines text.
-
-@item fixed-pitch
-@kindex fixed-pitch @r{(face name)}
-This face forces use of a particular fixed-width font.
-
-@item variable-pitch
-@kindex variable-pitch @r{(face name)}
-This face forces use of a particular variable-width font. It's
-reasonable to customize this to use a different variable-width font, if
-you like, but you should not make it a fixed-width font.
-
-@item shadow
-@kindex shadow @r{(face name)}
-This face is used for making the text less noticeable than the
-surrounding ordinary text.
-@end table
-
-@defvar show-trailing-whitespace
-@tindex show-trailing-whitespace
-If this variable is non-@code{nil}, Emacs uses the
-@code{trailing-whitespace} face to display any spaces and tabs at the
-end of a line.
-@end defvar
-
@node Defining Faces
@subsection Defining Faces
customize using the Customization buffer (@pxref{Easy Customization,,,
emacs, The GNU Emacs Manual}).
-@defmac defface face spec doc [keyword value]...
+@defmac defface face spec doc [keyword value]@dots{}
This declares @var{face} as a customizable face that defaults
according to @var{spec}. You should not quote the symbol @var{face},
and it should not end in @samp{-face} (that would be redundant). The
Non-@code{nil} means do underline; @code{nil} means don't.
@end defun
+@defun set-face-inverse-video-p face inverse-video-p &optional frame
+This function sets the @code{:inverse-video} attribute of face
+@var{face}.
+@end defun
+
@defun invert-face face &optional frame
-This function inverts the @code{:inverse-video} attribute of face
-@var{face}. If the attribute is @code{nil}, this function sets it to
-@code{t}, and vice versa.
+This function swaps the foreground and background colors of face
+@var{face}.
@end defun
These functions examine the attributes of a face. If you don't
value for that attribute.
@defun face-foreground face &optional frame inherit
-@defunx face-background face &optional frame
+@defunx face-background face &optional frame inherit
These functions return the foreground color (or background color,
respectively) of face @var{face}, as a string.
@item
With a region that is active. In Transient Mark mode, the region is
-highlighted with the face @code{region} (@pxref{Standard Faces}).
+highlighted with the face @code{region} (@pxref{Standard Faces,,,
+emacs, The GNU Emacs Manual}).
@item
With special glyphs. Each glyph can specify a particular face
@node Fringe Size/Pos
@subsection Fringe Size and Position
- Here's how to control the position and width of the window fringes.
+ The following buffer-local variables control the position and width
+of the window fringes.
@defvar fringes-outside-margins
-If the value is non-@code{nil}, the frames appear outside the display
-margins. The fringes normally appear between the display margins and
-the window text. It works to set @code{fringes-outside-margins}
-buffer-locally. @xref{Display Margins}.
+The fringes normally appear between the display margins and the window
+text. If the value is non-@code{nil}, they appear outside the display
+margins. @xref{Display Margins}.
@end defvar
@defvar left-fringe-width
This variable, if non-@code{nil}, specifies the width of the left
-fringe in pixels.
+fringe in pixels. A value of @code{nil} means to use the left fringe
+width from the window's frame.
@end defvar
@defvar right-fringe-width
This variable, if non-@code{nil}, specifies the width of the right
-fringe in pixels.
+fringe in pixels. A value of @code{nil} means to use the right fringe
+width from the window's frame.
@end defvar
The values of these variables take effect when you display the
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.
+The overlay-arrow string is displayed in any given buffer if the value
+of @code{overlay-arrow-position} in that buffer points into that
+buffer. Thus, it works to can display multiple overlay arrow strings
+by creating buffer-local bindings of @code{overlay-arrow-position}.
+However, it is usually cleaner to use
+@code{overlay-arrow-variable-list} to achieve this result.
@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?
whether the windows in the frame have vertical scroll bars, and
whether they are on the left or right. The frame parameter
@code{scroll-bar-width} specifies how wide they are (@code{nil}
-meaning the default). @xref{Window Frame Parameters}.
+meaning the default). @xref{Layout Parameters}.
@defun frame-current-scroll-bars &optional frame
This function reports the scroll bar type settings for frame
@var{file} exists, is used to construct the image specification to be
returned. If no specification is satisfied, @code{nil} is returned.
-The image is looked for first on @code{load-path} and then in
-@code{data-directory}.
+The image is looked for in @code{image-load-path}.
@end defun
+@defvar image-load-path
+@tindex image-load-path
+This variable's value is a list of locations in which to search for
+image files. If an element is a string or a variable symbol whose
+value is a string, the string is taken to be the name of a directory
+to search. If an element is a variable symbol whose value is a list,
+that is taken to be a list of directory names to search.
+
+The default is to search in the @file{images} subdirectory of the
+directory specified by @code{data-directory}, then the directory
+specified by @code{data-directory}, and finally in the directories in
+@code{load-path}. Subdirectories are not automatically included in
+the search, so if you put an image file in a subdirectory, you have to
+supply the subdirectory name explicitly. For example, to find the
+image @file{images/foo/bar.xpm} within @code{data-directory}, you
+should specify the image as follows:
+
+@example
+(defimage foo-image '((:type xpm :file "foo/bar.xpm")))
+@end example
+@end defvar
+
@node Showing Images
@subsection Showing Images
Focus}).
@end defun
+@defvar max-image-size
+@tindex max-image-size
+This variable is used to define the maximum size of image that Emacs
+will load. Emacs will refuse to load (and display) any image that is
+larger than this limit.
+
+If the value is an integer, it directly specifies the maximum
+image height and width, measured in pixels. If it is a floating
+point number, it specifies the maximum image height and width
+as a ratio to the frame height and width. If the value is
+non-numeric, there is no explicit limit on the size of images.
+
+The purpose of this variable is to prevent unreasonably large images
+from accidentally being loaded into Emacs. It only takes effect the
+first time an image is loaded. Once an image is placed in the image
+cache, it can always be displayed, even if the value of
+@var{max-image-size} is subsequently changed (@pxref{Image Cache}).
+@end defvar
+
@node Image Cache
@subsection Image Cache
@end smallexample
@end deffn
-@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 and
-menu bars. If it is non-@code{nil}, then these lines are displayed in
-the face @code{mode-line}. Otherwise, these lines are displayed
-normally, just like other text. The default is @code{t}.
-@end defopt
-
@node Usual Display
@section Usual Display Conventions
@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 value is in units of
-columns, and the default is 8. Note that this feature is completely
-independent of the user-settable tab stops used by the command
-@code{tab-to-tab-stop}. @xref{Indent Tabs}.
+The value of this buffer-local variable is the spacing between tab
+stops used for displaying tab characters in Emacs buffers. The value
+is in units of columns, and the default is 8. Note that this feature
+is completely independent of the user-settable tab stops used by the
+command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
@end defopt
@defopt indicate-empty-lines
When this is non-@code{nil}, Emacs displays a special glyph in the
fringe of each empty line at the end of the buffer, on terminals that
support it (window systems). @xref{Fringes}.
+This variable is automatically buffer-local in every buffer.
@end defopt
@defvar indicate-buffer-boundaries
HCoop / bpt / emacs.git / blobdiff