@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, 2003, 2004, 2005, 2006, 2007, 2008, 2009
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/display
entire frame width).
@end defopt
-@defopt default-truncate-lines
-This variable is the default value for @code{truncate-lines}, for
-buffers that do not have buffer-local values for it.
-@end defopt
-
@defopt truncate-partial-width-windows
This variable controls line truncation in @dfn{partial-width} windows.
A partial-width window is one that does not occupy the entire frame
@menu
* Managing Overlays:: Creating and moving overlays.
* Overlay Properties:: How to read and set properties.
- What properties do to the screen display.
+ What properties do to the screen display.
* Finding Overlays:: Searching for overlays.
@end menu
@code{nil}, that means the beginning and end of the buffer respectively.
Therefore, @code{(remove-overlays)} removes all the overlays in the
current buffer.
+@end defun
+
+@defun copy-overlay overlay
+This function returns a copy of @var{overlay}. The copy has the same
+endpoints and properties as @var{overlay}. However, the marker
+insertion type for the start of the overlay and for the end of the
+overlay are set to their default values (@pxref{Marker Insertion
+Types}).
@end defun
Here are some examples:
There are several ways to specify the line spacing for different
parts of Emacs text.
-@vindex default-line-spacing
On graphical terminals, you can specify the line spacing for all
lines in a frame, using the @code{line-spacing} frame parameter
-(@pxref{Layout Parameters}). However, if the variable
-@code{default-line-spacing} is non-@code{nil}, it overrides the
+(@pxref{Layout Parameters}). However, if the default value of
+@code{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 lines. A floating point number specifies
the spacing relative to the frame's default line height.
(put 'modeline 'face-alias 'mode-line)
@end example
+@defun define-obsolete-face-alias obsolete-face current-face &optional when
+This function defines a face alias and marks it as obsolete, indicating
+that it may be removed in future. The optional string @var{when}
+indicates when the face was made obsolete (for example, a release number).
+@end defun
+
@node Auto Faces
@subsection Automatic Face Assignment
@cindex automatic face assignment
@defvar fontification-functions
This variable holds a list of functions that are called by Emacs
-redisplay as needed to assign faces automatically to text in the buffer.
+redisplay as needed, just before doing redisplay. They are called even
+when Font Lock Mode isn't enabled. When Font Lock Mode is enabled, this
+variable usually holds just one function, @code{jit-lock-function}.
The functions are called in the order listed, with one argument, a
-buffer position @var{pos}. Each function should attempt to assign faces
-to the text in the current buffer starting at @var{pos}.
+buffer position @var{pos}. Collectively they should attempt to assign
+faces to the text in the current buffer starting at @var{pos}.
-Each function should record the faces they assign by setting the
-@code{face} property. It should also add a non-@code{nil}
-@code{fontified} property for all the text it has assigned faces to.
+The functions should record the faces they assign by setting the
+@code{face} property. They should also add a non-@code{nil}
+@code{fontified} property to all the text they have assigned faces to.
That property tells redisplay that faces have been assigned to that text
already.
-It is probably a good idea for each function to do nothing if the
+It is probably a good idea for the functions to do nothing if the
character after @var{pos} already has a non-@code{nil} @code{fontified}
property, but this is not required. If one function overrides the
-assignments made by a previous one, the properties as they are
-after the last function finishes are the ones that really matter.
+assignments made by a previous one, the properties after the last
+function finishes are the ones that really matter.
For efficiency, we recommend writing these functions so that they
usually assign faces to around 400 to 600 characters at each call.
@var{character} may be a charset. In that case, use
@var{font-spec} for all character in the charsets.
-@var{character} may be a script anme. In that case, use
+@var{character} may be a script name. In that case, use
@var{font-spec} for all character in the charsets.
@var{font-spec} may be a cons; @code{(@var{family} . @var{registry})},
@item :script
The script that the font must support (a symbol).
+
+@item :otf
+The font must be an OpenType font that supports these OpenType
+features, provided Emacs is compiled with support for @samp{libotf} (a
+library for performing complex text layout in certain scripts). The
+value must be a list of the form
+
+@smallexample
+@code{(@var{script-tag} @var{langsys-tag} @var{gsub} @var{gpos})}
+@end smallexample
+
+where @var{script-tag} is the OpenType script tag symbol;
+@var{langsys-tag} is the OpenType language system tag symbol, or
+@code{nil} to use the default language system; @code{gsub} is a list
+of OpenType GSUB feature tag symbols, or @code{nil} if none is
+required; and @code{gpos} is a list of OpenType GPOS feature tag
+symbols, or @code{nil} if none is required. If @code{gsub} or
+@code{gpos} is a list, a @code{nil} element in that list means that
+the font must not match any of the remaining tag symbols. The
+@code{gpos} element may be omitted.
@end table
@end defun
fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}.
@end defopt
-@defvar default-indicate-buffer-boundaries
-The value of this variable is the default value for
-@code{indicate-buffer-boundaries} in buffers that do not override it.
-@end defvar
-
@defvar fringe-indicator-alist
This buffer-local variable specifies the mapping from logical fringe
indicators to the actual bitmaps displayed in the window fringes.
When @code{fringe-indicator-alist} has a buffer-local value, and there
is no bitmap defined for a logical indicator, or the bitmap is
-@code{t}, the corresponding value from the (non-local)
-@code{default-fringe-indicator-alist} is used.
+@code{t}, the corresponding value from the default value of
+@code{fringe-indicator-alist} is used.
To completely hide a specific indicator, set the bitmap to @code{nil}.
@end defvar
-@defvar default-fringe-indicator-alist
-The value of this variable is the default value for
-@code{fringe-indicator-alist} in buffers that do not override it.
-@end defvar
-
Standard fringe bitmaps for indicators:
@example
left-arrow right-arrow up-arrow down-arrow
When @code{fringe-cursor-alist} has a buffer-local value, and there is
no bitmap defined for a cursor type, the corresponding value from the
-(non-local) @code{default-fringes-indicator-alist} is used.
-@end defvar
-
-@defvar default-fringes-cursor-alist
-The value of this variable is the default value for
-@code{fringe-cursor-alist} in buffers that do not override it.
+default value of @code{fringes-indicator-alist} is used.
@end defvar
Standard bitmaps for displaying the cursor in right fringe:
(when (= idx max)
(setq idx 0))
(let ((img (create-image file nil :image idx)))
- (save-excursion
- (set-buffer buffer)
+ (with-current-buffer buffer
(goto-char (point-min))
(unless first-time (delete-char 1))
(insert-image img))
efficiently. When Emacs displays an image, it searches the image
cache for an existing image specification @code{equal} to the desired
specification. If a match is found, the image is displayed from the
-cache; otherwise, Emacs loads the image normally.
-
- Occasionally, you may need to tell Emacs to refresh the images
-associated with a given image specification. For example, suppose you
-display an image using a specification that contains a @code{:file}
-property. The image is automatically cached, and subsequent displays
-of that image, with the same image specification, will use the image
-cache. If the image file changes in the meantime, Emacs would be
-displaying the old version of the image. In such a situation, you can
-``refresh'' the image by calling @code{image-refresh}.
-
- In Emacs' current implementation, each graphical terminal possesses
-an image cache, which is shared by all the frames on that terminal
+cache. Otherwise, Emacs loads the image normally.
+
+@defun image-flush spec &optional frame
+This function removes the image with specification @var{spec} from the
+image cache of frame @var{frame}. Image specifications are compared
+using @code{equal}. If @var{frame} is @code{nil}, it defaults to the
+selected frame. If @var{frame} is @code{t}, the image is flushed on
+all existing frames.
+
+In Emacs' current implementation, each graphical terminal possesses an
+image cache, which is shared by all the frames on that terminal
(@pxref{Multiple Terminals}). Thus, refreshing an image in one frame
also refreshes it in all other frames on the same terminal.
-
-@defun image-refresh spec &optional frame
-This function refreshes any images with image specifications
-@code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is
-@code{nil}, it defaults to the selected frame. If @var{frame} is
-@code{t}, the refresh is applied to all existing frames.
@end defun
+ One use for @code{image-flush} is to tell Emacs about a change in an
+image file. If an image specification contains a @code{:file}
+property, the image is cached based on the file's contents when the
+image is first displayed. Even if the file subsequently changes,
+Emacs continues displaying the old version of the image. Calling
+@code{image-flush} flushes the image from the cache, forcing Emacs to
+re-read the file the next time it needs to display that image.
+
+ Another use for @code{image-flush} is for memory conservation. If
+your Lisp program creates a large number of temporary images over a
+period much shorter than @code{image-cache-eviction-delay} (see
+below), you can opt to flush unused images yourself, instead of
+waiting for Emacs to do it automatically.
+
@defun clear-image-cache &optional filter
This function clears an image cache, removing all the images stored in
it. If @var{filter} is omitted or @code{nil}, it clears the cache for
associated memory.
@defvar image-cache-eviction-delay
-This variable specifies the number of seconds an image can remain in the
-cache without being displayed. When an image is not displayed for this
-length of time, Emacs removes it from the image cache.
+This variable specifies the number of seconds an image can remain in
+the cache without being displayed. When an image is not displayed for
+this length of time, Emacs removes it from the image cache.
+
+Under some circumstances, if the number of images in the cache grows
+too large, the actual eviction delay may be shorter than this.
If the value is @code{nil}, Emacs does not remove images from the cache
except when you explicitly clear it. This mode can be useful for
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 buffer-local variable is the spacing between tab
stops used for displaying tab characters in Emacs buffers. The value