* 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.
-* Width:: How wide is a character or string.
-* Faces:: A face defines a graphics appearance: font, color, etc.
+* Width:: How wide a character or string is on the screen.
+* Faces:: A face defines a graphics style for text characters:
+ font, colors, etc.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Blinking:: How Emacs shows the matching open parenthesis.
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.
+especially useful in a program to display the list of entries in a
+database. It permits the implementation of convenient filtering
+commands to view just a part of the entries in the database. 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
@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
One convention about the use of @code{buffer-invisibility-spec} is
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
@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. This is explicit
-selective display.
+If the value of @code{selective-display} is @code{t}, then the character
+control-m marks the start of invisible text; the control-m, and the rest
+of the line following it, are not displayed. This is explicit selective
+display.
@item
If the value of @code{selective-display} is a positive integer, then
@menu
* Overlay Properties:: How to read and set properties.
What properties do to the screen display.
-* Managing Overlays:: Creating, moving, finding overlays.
+* Managing Overlays:: Creating and moving overlays.
+* Finding Overlays:: Searching for overlays.
@end menu
@node Overlay Properties
font and which colors. @xref{Faces}, for more information.
In the simplest case, the value is a face name. It can also be a list;
-then each element can be any of these possibilities;
+then each element can be any of these possibilities:
@itemize @bullet
@item
@kindex help-echo @r{(text property)}
If an overlay has a string as its @code{help-echo} property, then when
you move the mouse onto the text in the overlay, Emacs displays that
-string in the echo area, or in the tooltip window. It is available
-starting in Emacs 21.
+string in the echo area, or in the tooltip window. This feature is
+available starting in Emacs 21.
@item modification-hooks
@kindex modification-hooks @r{(overlay property)}
@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.
+sense---only on the screen.
@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.
+sense---only on the screen.
@item evaporate
@kindex evaporate @r{(overlay property)}
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. @xref{Marker Insertion Types}.
+overlay, respectively. @xref{Marker Insertion Types}.
@end defun
@defun overlay-start overlay
@defun delete-overlay overlay
This function deletes @var{overlay}. The overlay continues to exist as
-a Lisp object, but ceases to be attached to the buffer it belonged to,
-and ceases to have any effect on display.
+a Lisp object, and its property list is unchanged, but it ceases to be
+attached to the buffer it belonged to, and ceases to have any effect on
+display.
-A deleted overlay is not permanently useless. You can give it
-a new buffer position by calling @code{move-overlay}.
+A deleted overlay is not permanently disconnected. You can give it a
+position in a buffer again by calling @code{move-overlay}.
@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.
+must specify buffer positions; they may be integers or markers.
+
+If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
+was already associated with; if @var{overlay} was deleted, it goes into
+the current buffer.
The return value is @var{overlay}.
``lost''.
@end defun
+ Here are some examples:
+
+@example
+;; @r{Create an overlay.}
+(setq foo (make-overlay 1 10))
+ @result{} #<overlay from 1 to 10 in display.texi>
+(overlay-start foo)
+ @result{} 1
+(overlay-end foo)
+ @result{} 10
+(overlay-buffer foo)
+ @result{} #<buffer display.texi>
+;; @r{Give it a property we can check later.}
+(overlay-put foo 'happy t)
+ @result{} t
+;; @r{Verify the property is present.}
+(overlay-get foo 'happy)
+ @result{} t
+;; @r{Move the overlay.}
+(move-overlay foo 5 20)
+ @result{} #<overlay from 5 to 20 in display.texi>
+(overlay-start foo)
+ @result{} 5
+(overlay-end foo)
+ @result{} 20
+;; @r{Delete the overlay.}
+(delete-overlay foo)
+ @result{} nil
+;; @r{Verify it is deleted.}
+foo
+ @result{} #<overlay in no buffer>
+;; @r{A deleted overlay has no position.}
+(overlay-start foo)
+ @result{} nil
+(overlay-end foo)
+ @result{} nil
+(overlay-buffer foo)
+ @result{} nil
+;; @r{Undelete the overlay.}
+(move-overlay foo 1 20)
+ @result{} #<overlay from 1 to 20 in display.texi>
+;; @r{Verify the results.}
+(overlay-start foo)
+ @result{} 1
+(overlay-end foo)
+ @result{} 20
+(overlay-buffer foo)
+ @result{} #<buffer display.texi>
+;; @r{Moving and deleting the overlay don't change its properties.}
+(overlay-get foo 'happy)
+ @result{} t
+@end example
+
+@node Finding Overlays
+@subsection Searching for Overlays
+
@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}.
+This function returns a list of all the overlays that cover the
+character at 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}.
+
+To illustrate usage, here is a Lisp function that returns a list of the
+overlays that specify property @var{prop} for the character at point:
+
+@smallexample
+(defun find-overlays-specifying (prop)
+ (let ((overlays (overlays-at (point)))
+ found)
+ (while overlays
+ (let ((overlay (cdr overlays)))
+ (if (overlay-get overlay prop)
+ (setq found (cons overlay found))))
+ (setq overlays (cdr overlays)))
+ found))
+@end smallexample
@end defun
@defun overlays-in beg end
@var{beg} through @var{end}. ``Overlap'' means that at least one
character is contained within the overlay and also contained within the
specified region; however, empty overlays are included in the result if
-they are located at @var{beg} or between @var{beg} and @var{end}.
+they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
@end defun
@defun next-overlay-change pos
end of an overlay, before @var{pos}.
@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
+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)))
+ (goto-char (min (next-overlay-change (point))
+ (next-single-property-change (point) 'happy))))
+ (point)))
+@end smallexample
+
@node Width
@section Width
@item mode-line
@kindex mode-line @r{(face name)}
-This face is used for mode lines, and for menu bars
-when toolkit menus are not used.
+This face is used for mode lines, 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)}
@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 colors of window fringes, the thin areas on
@item trailing-whitespace
@kindex trailing-whitespace @r{(face name)}
-This face is used to display excess whitespace at the end of a line.
+This face is used to display excess whitespace at the end of a line,
+if @code{show-trailing-whitespace} is non-@code{nil}.
@end table
In contrast, these faces are provided to change the appearance of text
@item variable-patch
@kindex variable-patch @r{(face name)}
This face forces use of a particular variable-width font. It's
-reasonable to customize this to use a diffrent variable-width font, if
+reasonable to customize this to use a different variable-width font, if
you like, but you should not make it a fixed-width font.
@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
@defmac defface face spec doc [keyword value]...
@tindex defface
-Declare @var{face} as a customizable face that defaults according to
-@var{spec}. Do not quote the symbol @var{face}. The argument @var{doc}
-specifies the face documentation.
+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
+can use in @code{defface} are the same ones that are meaningful in both
+@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
When @code{defface} executes, it defines the face according to
@var{spec}, then uses any customizations that were read from the
-@file{.emacs} file to override that specification.
+init file (@pxref{Init File}) to override that specification.
The purpose of @var{spec} is to specify how the face should appear on
different kinds of terminals. It should be an alist whose elements have
-the form @code{(@var{display} @var{atts})}. The element's @sc{car},
-@var{display}, specifies a class of terminals. The @sc{cdr},
+the form @code{(@var{display} @var{atts})}. Each element's @sc{car},
+@var{display}, specifies a class of terminals. The element's second element,
@var{atts}, is a list of face attributes and their values; it specifies
what the face should look like on that kind of terminal. The possible
attributes are defined in the value of @code{custom-face-attributes}.
@end table
@end defmac
- Here's how the standard face @code{region} could be defined
-with @code{defface}:
+ Here's how the standard face @code{region} is defined:
@example
+@group
(defface region
- ((((class color) (background dark))
- (:background "blue"))
- (t (:background "gray")))
- "Used for displaying the region.")
+ `((((type tty) (class color))
+ (:background "blue" :foreground "white"))
+@end group
+ (((type tty) (class mono))
+ (:inverse-video t))
+ (((class color) (background dark))
+ (:background "blue"))
+ (((class color) (background light))
+ (:background "lightblue"))
+ (t (:background "gray")))
+@group
+ "Basic face for highlighting the region."
+ :group 'basic-faces)
+@end group
@end example
Internally, @code{defface} uses the symbol property
The effect of using a face is determined by a fixed set of @dfn{face
attributes}. This table lists all the face attributes, and what they
-mean. Note that in general, more than one face be specified for a given
-piece of text; when that happens, the attributes of all the faces are
-merged to specify how to display the text. @xref{Merging Faces}.
+mean. Note that in general, more than one face can be specified for a
+given piece of text; when that happens, the attributes of all the faces
+are merged to specify how to display the text. @xref{Merging Faces}.
In Emacs 21, any attribute in a face can have the value
@code{unspecified}. This means the face doesn't specify that attribute.
attribute, that means the next face gets a chance. However, the
@code{default} face must specify all attributes.
- Some of these font attributes are meaningful only on certain
-kinds of displays---if your display cannot handle a certain attribute,
-the attribute is ignored.
+ Some of these font attributes are meaningful only on certain kinds of
+displays---if your display cannot handle a certain attribute, the
+attribute is ignored. (The attributes @code{:family}, @code{:width},
+@code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
+an X Logical Font Descriptor.)
@table @code
@item :family
Font family name, or fontset name (@pxref{Fontsets}). If you specify a
-font family name, the wild-cards @samp{*} and @samp{?} are allowed.
+font family name, the wild-card characters @samp{*} and @samp{?} are
+allowed.
@item :width
Relative proportionate width, also known as the character set width or
@code{extra-expanded}, or @code{ultra-expanded}.
@item :height
-Font height, an integer in units of 1/10pt.
+Font height, an integer in units of 1/10 point.
@item :weight
Font weight---a symbol from this series (from most dense to most faint):
@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
@code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
-@code{ultra-light}, or else @code{nil} meaning this attribute is not
-specified.
-
+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).
+
@item :slant
Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
@code{reverse-italic}, or @code{reverse-oblique}.
-
+
+On a text-only terminal, slanted text is displayed as half-bright, if
+the terminal supports the feature.
+
@item :foreground
Foreground color, a string.
value should be @code{t} (yes) or @code{nil} (no).
@item :stipple
-The background stipple, a bitmap name.
+The background stipple, a bitmap.
-The value can be a string; then is the name of a file of pixmap data.
-The file is found in the directories listed in the variable
-@code{x-bitmap-file-path}.
+The value can be a string; that should be the name of a file containing
+external-format X bitmap data. The file is found in the directories
+listed in the variable @code{x-bitmap-file-path}.
-Alternatively, the value can be a list of the form @code{(@var{width}
-@var{height} @var{data})}. Here, width and height are the size in
-pixels, and @var{data} is a string containing the raw bits of the
-bitmap.
+Alternatively, the value can specify the bitmap directly, with a list of
+the form @code{(@var{width} @var{height} @var{data})}. Here,
+@var{width} and @var{height} specify the size in pixels, and @var{data}
+is a string containing the raw bits of the bitmap, row by row. Each row
+occupies @math{(@var{width} + 7) / 8} consecutie bytes in the string
+(which should be a unibyte string for best results).
If the value is @code{nil}, that means use no stipple pattern.
@item :box
Whether or not a box should be drawn around characters, its color, the
-width of the box lines, and 3D appearance. See below for the possible
-values and what they mean.
+width of the box lines, and 3D appearance.
@end table
Here are the possible values of the @code{:box} attribute, and what
The attributes @code{:overline}, @code{:strike-through} and
@code{:box} are new in Emacs 21. The attributes @code{:family},
@code{:height}, @code{:width}, @code{:weight}, @code{:slant} are also
-new, previous versions had another way to specify some of the same
-information.
+new; previous versions used the following attributes, now semi-obsolete,
+to specify some of the same information:
@table @code
@item :font
-This attribute specified the font name.
+This attribute specifies the font name.
@item :bold
A non-@code{nil} value specifies a bold font.
@table @code
@item :font
-@code{:font} is not really a font attribute, but you can use it in
-@code{set-face-attribute} to specify several attributes at once. You
-specify an X font name as the value, and based on this font name, and
-it sets the attributes @code{:family}, @code{:width}, @code{:height},
-@code{:weight}, and @code{:slant} according to the font name.
+You can specify an X font name as the ``value'' of this ``attribute'';
+that sets the @code{:family}, @code{:width}, @code{:height},
+@code{:weight}, and @code{:slant} attributes according to the font name.
If the value is a pattern with wildcards, the first font that matches
the pattern is used to set these attributes.
for bitmap files, for the @code{:stipple} attribute.
@end defvar
+@defun bitmap-spec-p object
+This returns @code{t} if @var{object} is a valid bitmap
+specification, suitable for use with @code{:stipple}.
+It returns @code{nil} otherwise.
+@end defun
+
@node Attribute Functions
@subsection Face Attribute Functions
The extra arguments @var{arguments} specify the attributes to set, and
the values for them. They should consist of alternating attribute names
-(such as @code{:family} or @code{:underline} and corresponding values.
+(such as @code{:family} or @code{:underline}) and corresponding values.
Thus,
@example
@end example
@end defun
- For older Emacs versions, you can these functions to set
+ The functions above did not exist before Emacs 21. For compatibility
+with older Emacs versions, you can use the following functions to set
and examine the face attributes which existed in those versions.
@defun set-face-foreground face color &optional frame
These functions examine the attributes of a face. If you don't
specify @var{frame}, they refer to the default data for new frames.
+They return the symbol @code{unspecified} if the face doesn't define any
+value for that attribute.
@defun face-foreground face &optional frame
@defunx face-background face &optional frame
@noindent
allows the use of scalable fonts with registry @code{muleindian-2}.
-@end example
+@end defvar
@defun clear-face-cache &optional unload-p
@tindex clear-face-cache
@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
-
-@tindex frame-update-face-colors
-@defun frame-update-face-colors frame
-This function updates the way faces display on @var{frame}, for a change
-in @var{frame}'s foreground or background color.
+the default face. A face is considered to be ``the same'' as the
+default face if each attribute is either the same as that of the default
+face, or unspecified (meaning to inherit from the default).
@end defun
@node Auto Faces
@cindex display specification
@kindex display @r{(text property)}
- The @code{display} text property is used to insert images into text,
-and also control other aspects of how text displays. These features are
-available starting in Emacs 21. The value of the @code{display}
-property should be a display specification, or a list or vector
-containing several display specifications. The rest of this section
-describes several kinds of display specifications and what they mean.
+ The @code{display} text property (or overlay property) is used to
+insert images into text, and also control other aspects of how text
+displays. These features are available starting in Emacs 21. The value
+of the @code{display} property should be a display specification, or a
+list or vector containing several display specifications. The rest of
+this section describes several kinds of display specifications and what
+they mean.
@menu
-* Specified Space::
-* Other Display Specs::
-* Display Margins::
-* Conditional Display::
+* Specified Space:: Displaying one space with a specified width.
+* Other Display Specs:: Displaying an image; magnifying text; moving it
+ up or down on the page; adjusting the width
+ of spaces within text.
+* Display Margins:: Displaying text or images to the side of the main text.
+* Conditional Display:: Making any of the above features conditional
+ depending on some Lisp expression.
@end menu
@node Specified Space
@cindex variable-width spaces
To display a space of specified width and/or height, use a display
-specification of the form @code{(space @var{props})}, where @var{props}
-is a property list (see below). You can put this property on one or
-more consecutive characters; a space of the specified height and width
-is displayed in place of @emph{all} of those characters.
+specification of the form @code{(space . @var{props})}, where
+@var{props} is a property list (a list of alternating properties and
+values). You can put this property on one or more consecutive
+characters; a space of the specified height and width is displayed in
+place of @emph{all} of those characters. These are the properties you
+can use to specify the weight of the space:
@table @code
@item :width @var{width}
@item :align-to @var{hpos}
Specifies that the space should be wide enough to reach @var{hpos}. The
-value @var{hpos} is measured in units of the normal character width.
+value @var{hpos} is measured in units of the normal character width. It
+may be an interer or a floating point number.
@end table
Exactly one of the above properties should be used. You can also
@item :ascent @var{ascent}
Specifies that @var{ascent} percent of the height of the space should be
-considered as the ascent of the space. The value of @var{ascent} must
-be a non-negative number no greater than 100.
+considered as the ascent of the space---that is, the part above the
+baseline. The value of @var{ascent} must be a non-negative number no
+greater than 100.
@end table
You should not use both @code{:height} and @code{:relative-height}
that has the display specification.
@item (space-width @var{factor})
-This display specification affects all the spaces in the text that has
-the specification. It displays all of these spaces @var{factor} times
-as wide as normal. The element @var{factor} should be an integer or
-float.
+This display specification affects all the space characters within the
+text that has the specification. It displays all of these spaces
+@var{factor} times as wide as normal. The element @var{factor} should
+be an integer or float. Characters other than spaces are not affected
+at all; in particular, this has no effect on tab characters.
@item (height @var{height})
This display specification makes the text taller or shorter.
@table @asis
@item @code{(+ @var{n})}
This means to use a font that is @var{n} steps larger. A ``step'' is
-defined by the set of available fonts; each size for which a font is
-available counts as a step. @var{n} should be an integer.
+defined by the set of available fonts---specifically, those that match
+what was otherwise specified for this text, in all attributes except
+height. Each size for which a suitable font is available counts as
+another step. @var{n} should be an integer.
@item @code{(- @var{n})}
This means to use a font that is @var{n} steps smaller.
@end defvar
@menu
-* Image Descriptors::
-* XBM Images::
-* XPM Images::
-* GIF Images::
-* Postscript Images::
-* Other Image Types::
-* Defining Images::
-* Showing Images::
-* Image Cache::
+* Image Descriptors:: How to specify an image for use in @code{:display}.
+* XBM Images:: Special features for XBM format.
+* XPM Images:: Special features for XPM format.
+* GIF Images:: Special features for GIF format.
+* Postscript Images:: Special features for Postscript format.
+* Other Image Types:: Various other formats are supported.
+* Defining Images:: Convenient ways to define an image for later use.
+* Showing Images:: Convenient ways to display an image once it is defined.
+* Image Cache:: Internal mechanisms of image display.
@end menu
@node Image Descriptors
An image description is a list of the form @code{(image
. @var{props})}, where @var{props} is a property list containing
alternating keyword symbols (symbols whose names start with a colon) and
-their values. Every image descriptor must contain the property
-@code{:type @var{type}} to specify the format of the image. The value
-of @var{type} should be an image type symbol; for example, @code{xpm}
-for an image in XPM format.
+their values. You can use any Lisp object as a property, but the only
+properties that have any special meaning are certain symbols, all of
+them keywords.
+
+ Every image descriptor must contain the property @code{:type
+@var{type}} to specify the format of the image. The value of @var{type}
+should be an image type symbol; for example, @code{xpm} for an image in
+XPM format.
Here is a list of other properties that are meaningful for all image
types:
@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 (all of them):
@table @code
@item :width @var{width}
The value, @var{height}, specifies the height of the image in pixels.
@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}.
+The value, @var{data}, should normally be 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} bits.
Alternatively, @var{data} can be a vector of strings or bool-vectors,
each specifying one line of the image.
@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}.
one should specify at least the @code{:type} property and the
@code{:file} property. Here is an example:
-@smallexample
-(defimage test-image ((:type xpm :file \"~/test1.xpm\")
- (:type xbm :file \"~/test1.xbm\")))"
-@end smallexample
+@example
+(defimage test-image
+ '((:type xpm :file "~/test1.xpm")
+ (:type xbm :file "~/test1.xbm")))
+@end example
@code{defimage} tests each argument, one by one, to see if it is
usable---that is, if the type is supported and the file exists. The
property yourself, but it is easier to use the functions in this
section.
-@defun insert-image image &optional area
+@defun insert-image image string &optional 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
-@code{defimage}.
+@code{defimage}. The argument @var{string} specifies the text to put in
+the buffer to hold the image.
The argument @var{area} specifies whether to put the image in a margin.
If it is @code{left-margin}, the image appears in the left margin;
@code{nil} or omitted, the image is displayed at point within the
buffer's text.
-Internally, this function inserts an @samp{x} in the buffer, and gives
-it a @code{display} property which specifies this image. @xref{Display
+Internally, this function inserts @var{string} in the buffer, and gives
+it a @code{display} property which specifies @var{image}. @xref{Display
Property}.
@end defun
-@defun put-image image pos &optional area
+@defun put-image image pos string &optional 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{image} must be an image descriptor, perhaps returned
by @code{create-image} or stored by @code{defimage}.
@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 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.
+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
+other text. The default is @code{t}.
+
+For window frames, this feature actually applies the face named
+@code{mode-line}; that face is normally set up as the inverse of the
+default face, unless you change it.
@end defopt
@node Usual Display
buffers that do not override it. @xref{Default Value}.
@end defvar
+@defopt indicate-empty-lines
+@tindex indicate-empty-lines
+When this is non-@code{nil}, Emacs displays a special glyph in
+each empty line at the end of the buffer, on terminals that
+support it (window systems).
+@end defopt
+
@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 of the user-settable tab
-stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
+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
@node Display Tables
@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.
+bell.'' Its value should be a function of no arguments. If this is
+non-@code{nil}, it takes precedence over the @code{visible-bell}
+variable.
@end defvar
@node Window Systems
@defvar window-setup-hook
This variable is a normal hook which Emacs runs after handling the
initialization files. Emacs runs this hook after it has completed
-loading your @file{.emacs} file, the default initialization file (if
+loading your init file, the default initialization file (if
any), and the terminal-specific Lisp code, and running the hook
@code{term-setup-hook}.
HCoop / bpt / emacs.git / blobdiff