@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
@node Display, Calendar, Processes, Top
@end defun
@defun current-message
-@tindex current-message
This function returns the message currently being displayed in the
echo area, or @code{nil} if there is none.
@end defun
@end defvar
@defvar echo-area-clear-hook
-@tindex echo-area-clear-hook
This normal hook is run whenever the echo area is cleared---either by
@code{(message nil)} or for any other reason.
@end defvar
@defvar echo-keystrokes
This variable determines how much time should elapse before command
-characters echo. Its value must be an integer, which specifies the
+characters echo. Its value must be an integer or floating point number,
+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. (Once echoing
@code{buffer-invisibility-spec} and removing elements from it.
@defun add-to-invisibility-spec element
-@tindex add-to-invisibility-spec
Add the element @var{element} to @code{buffer-invisibility-spec}
(if it is not already present in that list).
@end defun
@defun remove-from-invisibility-spec element
-@tindex remove-from-invisibility-spec
Remove the element @var{element} from @code{buffer-invisibility-spec}.
This does nothing if @var{element} is not in the list.
@end defun
want this to be done differently for a certain overlay, give it an
@code{isearch-open-invisible-temporary} property which is a function.
The function is called with two arguments: the first is the overlay, and
-the second is @code{t} to make the overlay visible, or @code{nil} to
+the second is @code{nil} to make the overlay visible, or @code{t} to
make it invisible again.
@node Selective Display
@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.
+On a graphical display the contents of the string are ignored; instead a
+glyph is displayed in the fringe area to the left of the display area.
@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
+arrow. It should point at the beginning of a line. On a non-graphical
+display 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
@result{} 20
(overlay-buffer foo)
@result{} #<buffer display.texi>
-;; @r{Moving and deleting the overlay don't change its properties.}
+;; @r{Moving and deleting the overlay does not change its properties.}
(overlay-get foo 'happy)
@result{} t
@end example
@end defun
@defun overlays-in beg end
-@tindex overlays-in
This function returns a list of the overlays that overlap the region
@var{beg} through @var{end}. ``Overlap'' means that at least one
character is contained within the overlay and also contained within the
@ref{Screen Lines}, for related functions.
@defun char-width char
-@tindex char-width
This function returns the width in columns of the character @var{char},
if it were displayed in the current buffer and the selected window.
@end defun
@defun string-width string
-@tindex string-width
This function returns the width in columns of the string @var{string},
if it were displayed in the current buffer and the selected window.
@end defun
@defun truncate-string-to-width string width &optional start-column padding
-@tindex truncate-string-to-width
This function returns the part of @var{string} that fits within
@var{width} columns, as a new string.
emacs, The GNU Emacs Manual}).
@defmac defface face spec doc [keyword value]...
-@tindex defface
This declares @var{face} as a customizable face that defaults according
to @var{spec}. You should not quote the symbol @var{face}. The
argument @var{doc} specifies the face documentation. The keywords you
with the customization buffer, and @code{face-documentation} for the
documentation string.
-@tindex frame-background-mode
@defopt frame-background-mode
This option, if non-@code{nil}, specifies the background type to use for
interpreting face definitions. If it is @code{dark}, then Emacs treats
@code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
or @code{ultra-light}.
-On a text-only terminal, any weight greater than normal is displayed as
-extra bright, and any weight less than normal is displayed as
-half-bright (This is provided the terminal supports the feature.)
-
On a text-only terminal, any weight greater than normal is displayed as
extra bright, and any weight less than normal is displayed as
half-bright (provided the terminal supports the feature).
@end defun
@defun set-face-bold-p face bold-p &optional frame
-@tindex set-face-bold-p
This function specifies whether @var{face} should be bold. If
@var{bold-p} is non-@code{nil}, that means yes; @code{nil} means no.
@end defun
@defun set-face-italic-p face italic-p &optional frame
-@tindex set-face-italic-p
This function specifies whether @var{face} should be italic. If
@var{italic-p} is non-@code{nil}, that means yes; @code{nil} means no.
@end defun
@defun face-bold-p face &optional frame
-@tindex face-bold-p
This function returns @code{t} if @var{face} is bold---that is, if it is
bolder than normal. It returns @code{nil} otherwise.
@end defun
@defun face-italic-p face &optional frame
-@tindex face-italic-p
This function returns @code{t} if @var{face} is italic or oblique,
@code{nil} otherwise.
@end defun
and character's registry and encoding. If there is a font that matches
exactly, it is used, of course. The hard case is when no available font
exactly fits the specification. Then Emacs looks for one that is
-``close''---one attribute at a time. You can specify the order
-to consider the attributes.
+``close''---one attribute at a time. You can specify the order to
+consider the attributes. In the case where a specified font family is
+not available, you can specify a set of mappings for alternatives to
+try.
@defvar face-font-selection-order
@tindex face-font-selection-order
@end defun
@defun face-documentation face
-@tindex face-documentation
This function returns the documentation string of face @var{face}, or
@code{nil} if none was specified for it.
@end defun
@end example
@noindent
-the font specification for ASCII characters would be this:
+the font specification for @sc{ascii} characters would be this:
@example
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
@cindex conditional display specifications
You can make any display specification conditional. To do that,
-package it in another list of the form @code{(when @var{condition}
+package it in another list of the form @code{(when @var{condition} .
@var{spec})}. Then the specification @var{spec} applies only when
@var{condition} evaluates to a non-@code{nil} value. During the
evaluation, point is temporarily set at the end position of the text
@table @code
@item :ascent @var{ascent}
-The @code{:ascent} property specifies the percentage of the image's
-height to use for its ascent---that is, the part above the baseline. The
-value, @var{ascent}, must be a number in the range 0 to 100. If this
-property is omitted, it defaults to 50.
+The @code{:ascent} property specifies the amount of the image's
+height to use for its ascent---that is, the part above the baseline.
+The value, @var{ascent}, must be a number in the range 0 to 100, or
+the symbol @code{center}.
+
+If @var{ascent} is a number, that percentage of the image's height is
+used for its ascent.
+
+If @var{ascent} is @code{center}, the image is vertically centered
+around a centerline which would be the vertical centerline of text drawn
+at the position of the image, in the manner specified by the text
+properties and overlays that apply to the image.
+
+If this property is omitted, it defaults to 50.
@item :margin @var{margin}
The @code{:margin} property specifies how many pixels to add as an extra
@item :data @var{data}
The @code{:data} property specifies the actual contents of the image.
Each image must use either @code{:data} or @code{:file}, but not both.
-However, only certain image types support @code{:data}; for other types,
-you must use @code{:file}.
-
-The formats that support @code{:data} include XBM and XPM.
-Before using @code{:data}, see the section describing the specific
-format you wish to use for further information.
+For most image types, the value of the @code{:data} property should be a
+string containing the image data; we recommend using a unibyte string.
+
+Before using @code{:data}, look for further information in the section
+below describing the specific image format. For some image types,
+@code{:data} may not be supported; for some, it allows other data types;
+for some, @code{:data} alone is not enough, so you need to use other
+image properties along with @code{:data}.
@end table
@node XBM Images
0. The default is the frame's background color.
@end table
- You can specify an XBM image using data within Emacs instead
-of an external file. To do this, don't use @code{:file}; instead,
-use the following three properties (all of them):
+ If you specify an XBM image using data within Emacs instead of an
+external file, use the following three properties:
@table @code
-@item :width @var{width}
-The value, @var{width}, specifies the width the image in pixels.
+@item :data @var{data}
+The value, @var{data}, specifies the contents of the image.
+There are three formats you can use for @var{data}:
-@item :height @var{height}
-The value, @var{height}, specifies the height of the image in pixels.
+@itemize @bullet
+@item
+A vector of strings or bool-vectors, each specifying one line of the
+image. Do specify @code{:height} and @code{:width}.
-@item :data @var{data}
-The value, @var{data}, is normally a string or a bool-vector. Either
-way, it must contain enough bits for the area of the image: at least
-@var{width} * @code{height}.
+@item
+A string containing the same byte sequence as an XBM file would contain.
+You must not specify @code{:height} and @code{:width} in this case,
+because omitting them is what indicates the data has the format of an
+XBM file. The file contents specify the height and width of the image.
+
+@item
+A string or a bool-vector containing the bits of the image (plus perhaps
+some extra bits at the end that will not be used). It should contain at
+least @var{width} * @code{height} bits. In this case, you must specify
+@code{:height} and @code{:width}, both to indicate that the string
+contains just the bits rather than a whole XBM file, and to specify the
+size of the image.
+@end itemize
-Alternatively, @var{data} can be a vector of strings or bool-vectors,
-each specifying one line of the image.
+@item :width @var{width}
+The value, @var{width}, specifies the width of the image, in pixels.
+
+@item :height @var{height}
+The value, @var{height}, specifies the height of the image, in pixels.
@end table
@node XPM Images
@subsection XPM Images
@cindex XPM
- To use XPM format, specify @code{xpm} as the image type. These
-additional image properties are meaningful with the @code{xpm} image
-type:
+ To use XPM format, specify @code{xpm} as the image type. The
+additional image property @code{:color-symbols} is also meaningful with
+the @code{xpm} image type:
@table @code
@item :color-symbols @var{symbols}
form @code{(@var{name} . @var{color})}. In each element, @var{name} is
the name of a color as it appears in the image file, and @var{color}
specifies the actual color to use for displaying that name.
-
-@item :data @var{data}
-XPM images can be displayed from data instead of files. In that case,
-use the @code{:data} property instead of the @code{:file} property.
-
-The value @var{data} must be a string containing an XPM image. The
-contents of the string have same format as an external XPM file.
@end table
@node GIF Images
@end example
@end table
+ Displaying Postscript images from Lisp data is not currently
+implemented, but it may be implemented by the time you read this.
+See the @file{etc/NEWS} file to make sure.
+
@node Other Image Types
@subsection Other Image Types
@cindex PBM
For PBM images, specify image type @code{pbm}. Color, gray-scale and
monochromatic images are supported.
- For JPEG images, specify image type @code{jpeg}. There are no
-additional image properties defined.
+ For JPEG images, specify image type @code{jpeg}.
For TIFF images, specify image type @code{tiff}.
property yourself, but it is easier to use the functions in this
section.
-@defun insert-image image string &optional area
+@defun insert-image image &optional string area
This function inserts @var{image} in the current buffer at point. The
value @var{image} should be an image descriptor; it could be a value
returned by @code{create-image}, or the value of a symbol defined with
Property}.
@end defun
-@defun put-image image pos string &optional area
+@defun put-image image pos &optional string area
This function puts image @var{image} in front of @var{pos} in the
current buffer. The argument @var{pos} should be an integer or a
marker. It specifies the buffer position where the image should appear.
-The argument @var{string} specifies the text that should hold the image.
+The argument @var{string} specifies the text that should hold the image
+as an alternative to the default.
The argument @var{image} must be an image descriptor, perhaps returned
by @code{create-image} or stored by @code{defimage}.
@var{start} and @var{end}. If @var{buffer} is omitted or @code{nil},
images are removed from the current buffer.
-This remove only images that were put into @var{buffer} the way
+This removes only images that were put into @var{buffer} the way
@code{put-image} does it, not images that were inserted with
@code{insert-image} or in other ways.
@end defun
display them again more efficiently. It removes an image from the cache
when it hasn't been displayed for a specified period of time.
+When an image is looked up in the cache, its specification is compared
+with cached image specifications using @code{equal}. This means that
+all images with equal specifications share the same image in the cache.
+
@defvar image-cache-eviction-delay
@tindex image-cache-eviction-delay
This variable specifies the number of seconds an image can remain in the
only the cache for that frame is cleared. Otherwise all frames' caches
are cleared.
@end defun
+
@node Blinking
@section Blinking Parentheses
@cindex parenthesis matching
@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
-inverse video. Otherwise, they lines are displayed normally, just like
+inverse video. Otherwise, these lines are displayed normally, just like
other text. The default is @code{t}.
For window frames, this feature actually applies the face named
@end example
@defun display-table-slot display-table slot
-@tindex display-table-slot
This function returns the value of the extra slot @var{slot} of
@var{display-table}. The argument @var{slot} may be a number from 0 to
5 inclusive, or a slot name (symbol). Valid symbols are
@end defun
@defun set-display-table-slot display-table slot value
-@tindex set-display-table-slot
This function stores @var{value} in the extra slot @var{slot} of
@var{display-table}. The argument @var{slot} may be a number from 0 to
5 inclusive, or a slot name (symbol). Valid symbols are
mod 524288 is the character to output, and the glyph code divided by
524288 specifies the face number (@pxref{Face Functions}) to use while
outputting it. (524288 is
-@ifinfo
+@ifnottex
2**19.)
-@end ifinfo
+@end ifnottex
@tex
$2^{19}$.)
@end tex
@end defopt
@defvar ring-bell-function
-@tindex ring-bell-function
If this is non-@code{nil}, it specifies how Emacs should ``ring the
bell.'' Its value should be a function of no arguments. If this is
non-@code{nil}, it takes precedence over the @code{visible-bell}
@item pc
Emacs is displaying using MS-DOS.
@item w32
-Emacs is displaying using Windows NT or Windows 9x.
+Emacs is displaying using Windows.
@item mac
Emacs is displaying using a Macintosh.
@item nil
HCoop / bpt / emacs.git / blobdiff