@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 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2011 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/display
@node Display, System Interface, Processes, Top
immediately, but the requested 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.
+ On text-only terminals, suspending and resuming Emacs normally 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
+@defopt 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 there is no need
to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
-@end defvar
+@end defopt
@node Forcing Redisplay
@section Forcing Redisplay
@cindex forcing redisplay
Emacs normally tries to redisplay the screen whenever it waits for
-input. With this function you can request an immediate attempt to
-redisplay, in the middle of Lisp code, without actually waiting for
-input.
+input. With the following function, you can request an immediate
+attempt to redisplay, in the middle of Lisp code, without actually
+waiting for input.
@defun redisplay &optional force
This function tries immediately to redisplay, provided there are no
-pending input events. It is equivalent to @code{(sit-for 0)}.
+pending input events.
If the optional argument @var{force} is non-@code{nil}, it does all
pending redisplay work even if input is available, with no
for this; @pxref{Display Tables}).
@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 buffer-local values for it.
+If this buffer-local variable is non-@code{nil}, lines that extend
+beyond the right edge of the window are truncated; otherwise, they are
+continued. As a special exception, the variable
+@code{truncate-partial-width-windows} takes precedence in
+@dfn{partial-width} windows (i.e., windows that do not occupy the
+entire frame width).
@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.
+This variable controls line truncation in @dfn{partial-width} windows.
+A partial-width window is one that does not occupy the entire frame
+width (@pxref{Splitting Windows}). If the value is @code{nil}, line
+truncation is determined by the variable @code{truncate-lines} (see
+above). If the value is an integer @var{n}, lines are truncated if
+the partial-width window has fewer than @var{n} columns, regardless of
+the value of @code{truncate-lines}; if the partial-width window has
+@var{n} or more columns, line truncation is determined by
+@code{truncate-lines}. For any other non-@code{nil} value, lines are
+truncated in every partial-width window, regardless of the value of
+@code{truncate-lines}.
@end defopt
When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
a window, that forces truncation.
@defvar wrap-prefix
-If this buffer-local variable is non-@code{nil}, the prefix it defines
-will be added at display-time to the beginning of every continuation
-line due to text wrapping (so if lines are truncated, the wrap-prefix
-is never used). It may be a string, an image, or a stretch-glyph such
-as used by the `display' text-property. @xref{Display Property}.
-
-A wrap-prefix may also be specified for regions of text using the
-@code{wrap-prefix} text-property (which takes precedence over the
-value of the @code{wrap-prefix} variable). @xref{Special Properties}.
+If this buffer-local variable is non-@code{nil}, it defines a
+``prefix'' that is prepended to every continuation line at
+display-time. (If lines are truncated, the wrap-prefix is never
+used.) It may be a string, an image, or a stretch-glyph; the value is
+interpreted in the same way as a @code{display} text property.
+@xref{Display Property}.
+
+A wrap-prefix may also be specified for regions of text, using the
+@code{wrap-prefix} text or overlay property. This takes precedence
+over the @code{wrap-prefix} variable. @xref{Special Properties}.
@end defvar
@defvar line-prefix
-If this buffer-local variable is non-@code{nil}, the prefix it defines
-will be added at display-time to the beginning of every
-non-continuation line It may be a string, an image, or a stretch-glyph
-such as used by the `display' text-property. @xref{Display Property}.
+If this buffer-local variable is non-@code{nil}, it defines a
+``prefix'' that is prepended to every non-continuation line at
+display-time. It may be a string, an image, or a stretch-glyph; the
+value is interpreted in the same way as a @code{display} text
+property. @xref{Display Property}.
A line-prefix may also be specified for regions of text using the
-@code{line-prefix} text-property (which takes precedence over the
-value of the @code{line-prefix} variable). @xref{Special Properties}.
+@code{line-prefix} text or overlay property. This takes precedence
+over the @code{line-prefix} variable. @xref{Special Properties}.
@end defvar
If your buffer contains @emph{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
+continuation to display them, computing the continuation lines 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
@code{(message nil)} or for any other reason.
@end defvar
-@defvar echo-keystrokes
+@defopt echo-keystrokes
This variable determines how much time should elapse before command
characters echo. Its value must be an integer or floating point number,
which specifies the
sequence are echoed immediately.)
If the value is zero, then command input is not echoed.
-@end defvar
+@end defopt
@defvar message-truncate-lines
Normally, displaying a long message resizes the echo area to display
(remove-from-invisibility-spec 'my-symbol)
@end example
+ You can check for invisibility using the following function:
+
+@defun invisible-p pos-or-prop
+If @var{pos-or-prop} is a marker or number, this function returns a
+non-@code{nil} value if the text at that position is invisible.
+
+If @var{pos-or-prop} is any other kind of Lisp object, that is taken
+to mean a possible value of the @code{invisible} text or overlay
+property. In that case, this function returns a non-@code{nil} value
+if that value would cause text to become invisible, based on the
+current value of @code{buffer-invisibility-spec}.
+@end defun
+
@vindex line-move-ignore-invisible
Ordinarily, functions 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} (the default), but
-only because they are explicitly programmed to do so.
+ignore invisible newlines if @code{line-move-ignore-invisible} is
+non-@code{nil} (the default), but only because they are explicitly
+programmed to do so.
However, if a command ends with point inside or immediately before
invisible text, the main editing loop moves point further forward or
@end example
@end defvar
-@defvar selective-display-ellipses
+@defopt 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 hidden text.
This example is a continuation of the previous one.
You can use a display table to substitute other text for the ellipsis
(@samp{@dots{}}). @xref{Display Tables}.
-@end defvar
+@end defopt
@node Temporary Displays
@section Temporary Displays
@end example
@end defspec
-@defvar temp-buffer-show-function
+@defopt 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.
just as @code{with-output-to-temp-buffer} normally would, inside of
@code{save-selected-window} and with the chosen window and buffer
selected.
-@end defvar
+@end defopt
@defvar temp-buffer-setup-hook
This normal hook is run by @code{with-output-to-temp-buffer} before
beginning and end. It also has properties that you can examine and set;
these affect the display of the text within the overlay.
+@cindex scalability of overlays
+The visual effect of an overlay is the same as of the corresponding
+text property (@pxref{Text Properties}). However, due to a different
+implementation, overlays generally don't scale well (many operations
+take a time that is proportional to the number of overlays in the
+buffer). If you need to affect the visual appearance of many portions
+in the buffer, we recommend using text properties.
+
An overlay uses markers to record its beginning and end; thus,
editing the text of the buffer adjusts the beginning and end of each
overlay so that it stays with the text. When you create the overlay,
@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:
the overlay. The string does not appear in the buffer in any
sense---only on the screen.
+@item line-prefix
+This property specifies a display spec to prepend to each
+non-continuation line at display-time. @xref{Truncation}.
+
+@itemx wrap-prefix
+This property specifies a display spec to prepend to each continuation
+line at display-time. @xref{Truncation}.
+
@item evaporate
@kindex evaporate @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
There are several ways to specify the line spacing for different
parts of Emacs text.
-@vindex default-line-spacing
- You can specify the line spacing for all lines in a frame with the
-@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
-lines on graphical displays. A floating point number specifies the
-spacing relative to the frame's default line height.
+ 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 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.
@vindex line-spacing
You can specify the line spacing for all lines in a buffer via the
buffer-local @code{line-spacing} variable. An integer value specifies
-the number of pixels put below lines on graphical displays. A floating
-point number specifies the spacing relative to the default frame line
-height. This overrides line spacings specified for the frame.
+the number of pixels put below lines. A floating point number
+specifies the spacing relative to the default frame line height. This
+overrides line spacings specified for the frame.
@kindex line-spacing @r{(text property)}
Finally, a newline can have a @code{line-spacing} text or overlay
numeric height value specifies the line spacing, rather than the line
height.
+ On text-only terminals, the line spacing cannot be altered.
+
@node Faces
@section Faces
@cindex faces
@code{extra-expanded}, or @code{ultra-expanded}.
@item :height
-Font height---either an integer in units of 1/10 point, or a floating
-point number specifying the amount by which to scale the height of any
-underlying face, or a function that is called with one argument (the
-height of the underlying face) and returns the height of the new face.
-If the function is passed an integer argument, it must return an
-integer.
+The height of the font. In the simplest case, this is an integer in
+units of 1/10 point.
+
+The value can also be a floating point number or a function, which
+specifies the height relative to an @dfn{underlying face} (i.e., a
+face that has a lower priority in the list described in
+@ref{Displaying Faces}). If the value is a floating point number,
+that specifies the amount by which to scale the height of the
+underlying face. If the value is a function, that function is called
+with one argument, the height of the underlying face, and returns the
+height of the new face. If the function is passed an integer
+argument, it must return an integer.
The height of the default face must be specified using an integer;
floating point and function values are not allowed.
The name of a face from which to inherit attributes, or a list of face
names. Attributes from inherited faces are merged into the face like
an underlying face would be, with higher priority than underlying
-faces. If a list of faces is used, attributes from faces earlier in
-the list override those from later faces.
+faces (@pxref{Displaying Faces}). If a list of faces is used,
+attributes from faces earlier in the list override those from later
+faces.
@end table
For compatibility with Emacs 20, you can also specify values for two
to be displayed; if it is @code{nil}, the selected frame is used.
@end defun
-@defvar x-bitmap-file-path
+@defopt underline-minimum-offset
+This variable specifies the minimum distance between the baseline and
+the underline, in pixels, when displaying underlined text.
+@end defopt
+
+@defopt x-bitmap-file-path
This variable specifies a list of directories for searching
for bitmap files, for the @code{:stipple} attribute.
-@end defvar
+@end defopt
@defun bitmap-spec-p object
This returns @code{t} if @var{object} is a valid bitmap specification,
@item
If @var{remapping...} recursively references the same face name
@var{face}, either directly remapping entry, or via the
-@code{:inherit} attribute of some other face in
-@var{remapping...}, then that reference uses normal frame-wide
-definition of @var{face} instead of the ``remapped'' definition.
+@code{:inherit} attribute of some other face in @var{remapping...},
+then that reference uses the normal definition of @var{face} in the
+selected frame, instead of the ``remapped'' definition.
For instance, if the @code{mode-line} face is remapped using this
entry in @code{face-remapping-alist}:
(@var{face} @var{relative_specs_1} @var{relative_specs_2} @var{...} @var{base_specs})
@end example
-Everything except the @var{face} is a ``face spec'', a list of face
-names or face attribute-value pairs. All face specs are merged
-together, with earlier values taking precedence.
+Everything except @var{face} is a ``face spec'': a list of face names
+or face attribute-value pairs. All face specs are merged together,
+with earlier values taking precedence.
The @var{relative_specs_}n values are ``relative specs'', and are
added by @code{face-remap-add-relative} (and removed by
(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.
Emacs looks for the @dfn{closest matching font}. The variables in
this section control how Emacs makes this selection.
-@defvar face-font-family-alternatives
+@defopt face-font-family-alternatives
If a given family is specified but does not exist, this variable
specifies alternative font families to try. Each element should have
this form:
If @var{family} is specified but not available, Emacs will try the other
families given in @var{alternate-families}, one by one, until it finds a
family that does exist.
-@end defvar
+@end defopt
-@defvar face-font-selection-order
+@defopt face-font-selection-order
If there is no font that exactly matches all desired face attributes
(@code{:width}, @code{:height}, @code{:weight}, and @code{:slant}),
this variable specifies the order in which these attributes should be
default one. But if you put @code{:slant} before @code{:height}, the
@code{italic} face will use an italic font, even if its height is not
quite right.
-@end defvar
+@end defopt
-@defvar face-font-registry-alternatives
+@defopt face-font-registry-alternatives
This variable lets you specify alternative font registries to try, if a
given registry is specified and doesn't exist. Each element should have
this form:
If @var{registry} is specified but not available, Emacs will try the
other registries given in @var{alternate-registries}, one by one,
until it finds a registry that does exist.
-@end defvar
+@end defopt
Emacs can make use of scalable fonts, but by default it does not use
them.
-@defvar scalable-fonts-allowed
+@defopt scalable-fonts-allowed
This variable controls which scalable fonts to use. A value of
@code{nil}, the default, means do not use scalable fonts. @code{t}
means to use any scalable font that seems appropriate for the text.
@noindent
allows the use of scalable fonts with registry @code{muleindian-2}.
-@end defvar
+@end defopt
@defvar face-font-rescale-alist
This variable specifies scaling for certain faces. Its value should
Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
field.
-@defun set-fontset-font name character fontname &optional frame
-This function modifies the existing fontset @var{name} to
-use the font name @var{fontname} for the character @var{character}.
+@defun set-fontset-font name character font-spec &optional frame add
+This function modifies the existing fontset @var{name} to use the font
+matching with @var{font-spec} for the character @var{character}.
+
+If @var{name} is @code{nil}, this function modifies the fontset of the
+selected frame or that of @var{frame} if @var{frame} is not
+@code{nil}.
-If @var{name} is @code{nil}, this function modifies the default
+If @var{name} is @code{t}, this function modifies the default
fontset, whose short name is @samp{fontset-default}.
@var{character} may be a cons; @code{(@var{from} . @var{to})}, where
@var{from} and @var{to} are character codepoints. In that case, use
-@var{fontname} for all characters in the range @var{from} and @var{to}
+@var{font-spec} for all characters in the range @var{from} and @var{to}
(inclusive).
@var{character} may be a charset. In that case, use
-@var{fontname} for all character in the charsets.
+@var{font-spec} for all character in the charsets.
+
+@var{character} may be a script name. In that case, use
+@var{font-spec} for all character in the charsets.
-@var{fontname} may be a cons; @code{(@var{family} . @var{registry})},
+@var{font-spec} may be a cons; @code{(@var{family} . @var{registry})},
where @var{family} is a family name of a font (possibly including a
foundry name at the head), @var{registry} is a registry name of a font
(possibly including an encoding name at the tail).
+@var{font-spec} may be a font name string.
+
+The optional argument @var{add}, if non-@code{nil}, specifies how to
+add @var{font-spec} to the font specifications previously set. If it
+is @code{prepend}, @var{font-spec} is prepended. If it is
+@code{append}, @var{font-spec} is appended. By default,
+@var{font-spec} overrides the previous settings.
+
For instance, this changes the default fontset to use a font of which
-registry name is @samp{JISX0208.1983} for all characters belonging to
+family name is @samp{Kochi Gothic} for all characters belonging to
the charset @code{japanese-jisx0208}.
@smallexample
-(set-fontset-font nil 'japanese-jisx0208 '(nil . "JISX0208.1983"))
+(set-fontset-font t 'japanese-jisx0208
+ (font-spec :family "Kochi Gothic"))
@end smallexample
@end defun
A font object is a Lisp object that represents a font that Emacs has
@dfn{opened}. Font objects cannot be modified in Lisp, but they can
-be inspected. If you call @code{set-face-attribute} and pass a font
-spec, font entity, or font name string as the value of the
-@code{:font} attribute, Emacs opens the best ``matching'' font that is
-available for display. It then stores the corresponding font object
-as the actual value of the @code{:font} attribute for that face.
+be inspected.
@defun font-at position &optional window string
Return the font object that is being used to display the character at
@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
spec.
@end defun
+ If you call @code{set-face-attribute} and pass a font spec, font
+entity, or font name string as the value of the @code{:font}
+attribute, Emacs opens the best ``matching'' font that is available
+for display. It then stores the corresponding font object as the
+actual value of the @code{:font} attribute for that face.
+
The following functions can be used to obtain information about a
font. For these functions, the @var{font} argument can be a font
object, a font entity, or a font spec.
The values of these variables take effect when you display the
buffer in a window. If you change them while the buffer is visible,
you can call @code{set-window-buffer} to display it once again in the
-same window, to make the changes take effect.
+same window, to make the changes take effect. A buffer that does not
+specify values for these variables will use the default values
+specified for the frame; see @ref{Layout Parameters}.
@defun set-window-fringes window left &optional right outside-margins
This function sets the fringe widths of window @var{window}.
buffer-local in every buffer.
@end defopt
-@defvar indicate-buffer-boundaries
+@defopt indicate-buffer-boundaries
This buffer-local variable controls how the buffer boundaries and
window scrolling are indicated in the window fringes.
bitmap in left fringe, and the bottom angle bitmap as well as both
arrow bitmaps in right fringe. To show the angle bitmaps in the left
fringe, and no arrow bitmaps, use @code{((top . left) (bottom . left))}.
-@end defvar
-
-@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
+@end defopt
@defvar fringe-indicator-alist
This buffer-local variable specifies the mapping from logical fringe
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
normal @code{hollow-rectangle} bitmap is too tall to fit on a specific
display line.
-@defvar overflow-newline-into-fringe
+@defopt overflow-newline-into-fringe
If this is non-@code{nil}, lines exactly as wide as the window (not
counting the final newline character) are not continued. Instead,
when point is at the end of the line, the cursor appears in the right
fringe.
-@end defvar
+@end defopt
@defvar fringe-cursor-alist
This variable specifies the mapping from logical cursor type to the
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:
window take note of the new values by calling @code{set-window-buffer}
specifying the same buffer that is already displayed.
-@defvar scroll-bar-mode
+@defopt scroll-bar-mode
This variable, always local in all buffers, controls whether and where
to put scroll bars in windows displaying the buffer. The possible values
are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
the left, and @code{right} to put a scroll bar on the right.
-@end defvar
+@end defopt
@defun window-current-scroll-bars &optional window
This function reports the scroll bar type for window @var{window}.
but it is done as a special case of marginal display (@pxref{Display
Margins}).
+@item (left-fringe @var{bitmap} @r{[}@var{face}@r{]})
+@itemx (right-fringe @var{bitmap} @r{[}@var{face}@r{]})
+This display specification on any character of a line of text causes
+the specified @var{bitmap} be displayed in the left or right fringes
+for that line. The optional @var{face} specifies the colors to be
+used for the bitmap. @xref{Fringe Bitmaps}, for the details.
+
@item (space-width @var{factor})
This display specification affects all the space characters within the
text that has the specification. It displays all of these spaces
but that text does not.
A margin display specification looks like @code{((margin
-right-margin) @var{spec}} or @code{((margin left-margin) @var{spec})}.
+right-margin) @var{spec})} or @code{((margin left-margin) @var{spec})}.
Here, @var{spec} is another display specification that says what to
display in the margin. Typically it is a string of text to display,
or an image descriptor.
* GIF Images:: Special features for GIF format.
* TIFF Images:: Special features for TIFF format.
* PostScript Images:: Special features for PostScript format.
+* ImageMagick Images:: Special features available through ImageMagick.
* 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.
Emacs can display a number of different image formats; some of them
are supported only if particular support libraries are installed on
-your machine. In some environments, Emacs can load image
-libraries on demand; if so, the variable @code{image-library-alist}
-can be used to modify the set of known names for these dynamic
-libraries (though it is not possible to add new image formats).
+your machine. In some environments, Emacs can load support libraries
+on demand; if so, the variable @code{dynamic-library-alist}
+(@pxref{Dynamic Libraries}) can be used to modify the set of known
+names for these dynamic libraries (though it is not possible to add
+new image formats). Note that image types @code{pbm} and @code{xbm}
+do not depend on external libraries and are always available in Emacs.
The supported image formats include XBM, XPM (this requires the
libraries @code{libXpm} version 3.4k and @code{libz}), GIF (requiring
@code{image-type-available-p}.
@end defvar
-@defvar image-library-alist
-This in an alist of image types vs external libraries needed to
-display them.
-
-Each element is a list @code{(@var{image-type} @var{library}...)},
-where the car is a supported image format from @code{image-types}, and
-the rest are strings giving alternate filenames for the corresponding
-external libraries to load.
-
-Emacs tries to load the libraries in the order they appear on the
-list; if none is loaded, the running session of Emacs won't support
-the image type. @code{pbm} and @code{xbm} don't need to be listed;
-they're always supported.
-
-This variable is ignored if the image libraries are statically linked
-into Emacs.
-@end defvar
-
@defun image-type-available-p type
This function returns non-@code{nil} if image type @var{type} is
available, i.e., if images of this type can be loaded and displayed in
(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))
@end example
@end table
+@node ImageMagick Images
+@subsection ImageMagick Images
+@cindex ImageMagick images
+@cindex images, support for more formats
+
+ If you build Emacs with ImageMagick (@url{http://www.imagemagick.org})
+support, you can use the ImageMagick library to load many image formats.
+
+@findex imagemagick-types
+The function @code{imagemagick-types} returns a list of image file
+extensions that your installation of ImageMagick supports. To enable
+support, you must call the function @code{imagemagick-register-types}.
+
+@vindex imagemagick-types-inhibit
+The variable @code{imagemagick-types-inhibit} specifies a list of
+image types that you do @emph{not} want ImageMagick to handle. There
+may be overlap between image loaders in your Emacs installation, and
+you may prefer to use a different one for a given image type (which
+@c FIXME how is this priority determined?
+loader will be used in practice depends on the priority of the loaders).
+@c FIXME why are these uppercase when image-types is lower-case?
+@c FIXME what are the possibe options? Are these actually file extensions?
+For example, if you never want to use the ImageMagick loader to use
+JPEG files, add @code{JPG} to this list.
+
+@vindex imagemagick-render-type
+You can set the variable @code{imagemagick-render-type} to choose
+between screen render methods for the ImageMagick loader. The options
+are: @code{0}, a conservative method which works with older
+@c FIXME details of this "newer method"?
+@c Presumably it is faster but may be less "robust"?
+ImageMagick versions (it is a bit slow, but robust); and @code{1},
+a newer ImageMagick method.
+
+Images loaded with ImageMagick support a few new display specifications:
+
+@table @code
+@item :width, :height
+The @code{:width} and @code{:height} keywords are used for scaling the
+image. If only one of them is specified, the other one will be
+calculated so as to preserve the aspect ratio. If both are specified,
+aspect ratio may not be preserved.
+
+@item :rotation
+Specifies a rotation angle in degrees.
+
+@item :index
+Specifies which image to view inside an image bundle file format, such
+as TIFF or DJVM. You can use the @code{image-metadata} function to
+retrieve the total number of images in an image bundle (this is
+similar to how GIF files work).
+@end table
+
+
@node Other Image Types
@subsection Other Image Types
@cindex PBM
@subsection Image Cache
@cindex image cache
- Emacs stores images in an image cache so that it can display them
-again more 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 loaded from the given file and stored in the
-image cache. If you later display the image again, using the same
-image specification, the image is displayed from the image cache.
-Normally, this is not a problem. However, if the image file has
-changed in the meantime, Emacs would be displaying the old version of
-the image. In such a situation, it is necessary to ``refresh'' the
-image using @code{image-refresh}.
-
-@defun image-refresh spec &optional frame
-This function refreshes any images having image specifications
-@code{equal} to @var{spec} on frame @var{frame}. If @var{frame} is
-@code{nil}, the selected frame is used. If @var{frame} is @code{t},
-the refresh is applied to all existing frames.
-
-This works by removing from the image cache all the images whose image
-specifications match @var{spec}. The next time Emacs needs to display
-such an image, it will reload the image anew.
-@end defun
+ Emacs caches images so that it can display them again more
+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.
+
+@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.
+@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 the image cache. If @var{filter} is
-a frame, only the cache for that frame is cleared. If omitted or
-@code{nil}, clear the images on the selected frame. If @code{t},
-all frames' caches are cleared. Otherwise, @var{filter} is taken as
-a file name and only images that reference this file will be flushed.
+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
+the selected frame. If @var{filter} is a frame, it clears the cache
+for that frame. If @var{filter} is @code{t}, all image caches are
+cleared. Otherwise, @var{filter} is taken to be a file name, and all
+images associated with that file name are removed from all image
+caches.
@end defun
If an image in the image cache has not been displayed for a specified
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
@item follow-link
@kindex follow-link @r{(button property)}
The follow-link property, defining how a @key{Mouse-1} click behaves
-on this button, @xref{Links and Mouse-1}.
+on this button, @xref{Clickable Text}.
@item button
@kindex button @r{(button property)}
button actually part of the text instead of being a property of the
buffer. Buttons using text properties do not create markers into the
buffer, which is important for speed when you use extremely large
-numbers of buttons. Both functions return the position of the start
-of the new button:
+numbers of buttons. (However, if there is an existing face text
+property at the site of the button, the button face may not be visible.)
+Both functions return the position of the start of the new button:
@defun make-text-button beg end &rest properties
This makes a button from @var{beg} to @var{end} in the current buffer, using
If the button has a non-@code{nil} @code{follow-link} property, and
@var{mouse-1-click-follows-link} is set, a quick @key{Mouse-1} click
will also activate the @code{push-button} command.
-@xref{Links and Mouse-1}.
+@xref{Clickable Text}.
@deffn Command push-button &optional pos use-mouse-action
Perform the action specified by a button at location @var{pos}.
its associated textual description from buffer, as well.
@menu
-* Abstract Display Functions::
-* Abstract Display Example::
+* Abstract Display Functions:: Functions in the Ewoc package.
+* Abstract Display Example:: Example of using Ewoc.
@end menu
@node Abstract Display Functions
table can specify a glyph to use instead of @samp{\}.)
@item
-Multibyte character codes above 256 are displayed as themselves, or as a
-question mark or empty box if the terminal cannot display that
-character.
+Multibyte character codes above 256 are displayed as themselves, or as
+a question mark or a hex code or an empty box if the terminal cannot
+display that character.
@end itemize
The usual display conventions apply even when there is a display
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
Emacs is displaying the frame using X.
@item w32
Emacs is displaying the frame using native MS-Windows GUI.
+@item ns
+Emacs is displaying the frame using the Nextstep interface (used on
+GNUstep and Mac OS X).
@item pc
Emacs is displaying the frame using MS-DOS direct screen writes.
@item nil
one documented for the variable @code{window-system} above.
@end defun
+ Do @emph{not} use @code{window-system} and
+@code{initial-window-system} as predicates or boolean flag variables,
+if you want to write code that works differently on text terminals and
+graphic displays. That is because @code{window-system} is not a good
+indicator of Emacs capabilities on a given display type. Instead, use
+@code{display-graphic-p} or any of the other @code{display-*-p}
+predicates described in @ref{Display Feature Testing}.
+
@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
the window system, and creating the initial window. Users should not
interfere with it.
@end defvar
-
-@ignore
- arch-tag: ffdf5714-7ecf-415b-9023-fbc6b409c2c6
-@end ignore
HCoop / bpt / emacs.git / blobdiff