@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-2011 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/display
@node Display, System Interface, Processes, Top
* Display Tables:: How to specify other conventions.
* Beeping:: Audible signal to the user.
* Window Systems:: Which window system is being used.
+* Bidirectional Display:: Display of bidirectional scripts, such as
+ Arabic and Farsi.
+* Glyphless Chars:: How glyphless characters are drawn.
@end menu
@node Refresh Screen
to put more work on the queue to be done by redisplay whenever there
is a chance.
- Emacs redisplay normally stops if input arrives, and does not happen
-at all if input is available before it starts. Most of the time, this
-is exactly what you want. However, you can prevent preemption by
-binding @code{redisplay-dont-pause} to a non-@code{nil} value.
-
@defvar redisplay-dont-pause
-If this variable is non-@code{nil}, pending input does not
-prevent or halt redisplay; redisplay occurs, and finishes,
-regardless of whether input is available.
+If this variable is non-@code{nil}, pending input does not prevent or
+halt redisplay; redisplay occurs, and finishes, regardless of whether
+input is available. If it is @code{nil}, Emacs redisplay stops if
+input arrives, and does not happen at all if input is available before
+it starts. The default is @code{t}.
@end defvar
@defvar redisplay-preemption-period
@defvar wrap-prefix
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}.
+display time. (If lines are truncated, the wrap-prefix is never
+used.) It may be a string or an image (@pxref{Other Display Specs}),
+or a stretch of whitespace such as specified by the @code{:width} or
+@code{:align-to} display properties (@pxref{Specified Space}). 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
@defvar line-prefix
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}.
+display time. It may be a string or an image (@pxref{Other Display
+Specs}), or a stretch of whitespace such as specified by the
+@code{:width} or @code{:align-to} display properties (@pxref{Specified
+Space}). 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 or overlay property. This takes precedence
When an operation can take a while to finish, you should inform the
user about the progress it makes. This way the user can estimate
remaining time and clearly see that Emacs is busy working, not hung.
+A convenient way to do this is to use a @dfn{progress reporter}.
- Functions listed in this section provide simple and efficient way of
-reporting operation progress. Here is a working example that does
-nothing useful:
+ Here is a working example that does nothing useful:
@smallexample
(let ((progress-reporter
(progress-reporter-done progress-reporter))
@end smallexample
-@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
-This function creates and returns a @dfn{progress reporter}---an
-object you will use as an argument for all other functions listed
-here. The idea is to precompute as much data as possible to make
-progress reporting very fast.
+@defun make-progress-reporter message &optional min-value max-value current-value min-change min-time
+This function creates and returns a progress reporter object, which
+you will use as an argument for the other functions listed below. The
+idea is to precompute as much data as possible to make progress
+reporting very fast.
When this progress reporter is subsequently used, it will display
@var{message} in the echo area, followed by progress percentage.
on a filename, for instance, use @code{format} before calling this
function.
-@var{min-value} and @var{max-value} arguments stand for starting and
-final states of your operation. For instance, if you scan a buffer,
-they should be the results of @code{point-min} and @code{point-max}
-correspondingly. It is required that @var{max-value} is greater than
-@var{min-value}. If you create progress reporter when some part of
-the operation has already been completed, then specify
-@var{current-value} argument. But normally you should omit it or set
-it to @code{nil}---it will default to @var{min-value} then.
-
-Remaining arguments control the rate of echo area updates. Progress
-reporter will wait for at least @var{min-change} more percents of the
-operation to be completed before printing next message.
-@var{min-time} specifies the minimum time in seconds to pass between
-successive prints. It can be fractional. Depending on Emacs and
-system capabilities, progress reporter may or may not respect this
-last argument or do it with varying precision. Default value for
-@var{min-change} is 1 (one percent), for @var{min-time}---0.2
-(seconds.)
+The arguments @var{min-value} and @var{max-value} should be numbers
+standing for the starting and final states of the operation. For
+instance, an operation that ``scans'' a buffer should set these to the
+results of @code{point-min} and @code{point-max} correspondingly.
+@var{max-value} should be greater than @var{min-value}.
+
+Alternatively, you can set @var{min-value} and @var{max-value} to
+@code{nil}. In that case, the progress reporter does not report
+process percentages; it instead displays a ``spinner'' that rotates a
+notch each time you update the progress reporter.
+
+If @var{min-value} and @var{max-value} are numbers, you can give the
+argument @var{current-value} a numerical value specifying the initial
+progress; if omitted, this defaults to @var{min-value}.
+
+The remaining arguments control the rate of echo area updates. The
+progress reporter will wait for at least @var{min-change} more
+percents of the operation to be completed before printing next
+message; the default is one percent. @var{min-time} specifies the
+minimum time in seconds to pass between successive prints; the default
+is 0.2 seconds. (On some operating systems, the progress reporter may
+handle fractions of seconds with varying precision).
This function calls @code{progress-reporter-update}, so the first
message is printed immediately.
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
-further backward (in the same direction that the command already moved
-it) until that condition is no longer true. Thus, if the command
-moved point back into an invisible range, Emacs moves point back to
-the beginning of that range, and then back one more character. If the
-command moved point forward into an invisible range, Emacs moves point
-forward up to the first visible character that follows the invisible
-text.
+ However, if a command ends with point inside or at the boundary of invisible
+text, the main editing loop moves point to one of the two ends of the invisible
+text. Which end to move to is chosen based on the following factors: make sure
+that the overall movement of the command is still in the same direction, and
+prefer a position where an inserted char would not inherit the @code{invisible}
+property. Additionally, if the text is not replaced by an ellipsis and the
+command only moved within the invisible text, then point is moved one extra
+character so as to try and reflect the command's movement by a visible movement
+of the cursor.
+
+ Thus, if the command moved point back to an invisible range (with the usual
+stickiness), Emacs moves point back to the beginning of that range. If the
+command moved point forward into an invisible range, Emacs moves point forward
+to the first visible character that follows the invisible text and then forward
+one more character.
Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text. To enable
Attributes}.
@item
-A cons cell, either of the form @code{(foreground-color . @var{color-name})} or
-@code{(background-color . @var{color-name})}. These elements specify
-just the foreground color or just the background color.
+A cons cell, of the form @code{(foreground-color . @var{color-name})}
+or @code{(background-color . @var{color-name})}. These elements
+specify just the foreground color or just the background color.
@code{(foreground-color . @var{color-name})} has the same effect as
@code{(:foreground @var{color-name})}; likewise for the background.
@item mouse-face
@kindex mouse-face @r{(overlay property)}
This property is used instead of @code{face} when the mouse is within
-the range of the overlay.
+the range of the overlay. However, Emacs ignores all face attributes
+from this property that alter the text size (e.g. @code{:height},
+@code{:weight}, and @code{:slant}). Those attributes are always the
+same as in the unhighlighted text.
@item display
@kindex display @r{(overlay property)}
@cindex faces
A @dfn{face} is a collection of graphical attributes for displaying
-text: font family, foreground color, background color, optional
-underlining, and so on. Faces control how buffer text is displayed,
-and how some parts of the frame, such as the mode-line, are displayed.
+text: font, foreground color, background color, optional underlining,
+and so on. Faces control how buffer text is displayed, and how some
+parts of the frame, such as the mode-line, are displayed.
@xref{Standard Faces,,, emacs, The GNU Emacs Manual}, for the list of
faces Emacs normally comes with.
* Face Attributes:: What is in a face?
* Attribute Functions:: Functions to examine and set face attributes.
* Displaying Faces:: How Emacs combines the faces specified for a character.
-* Face Remapping:: Remapping faces to alternative definitions.
+* Face Remapping:: Remapping faces to alternative definitions.
* Face Functions:: How to define and examine faces.
* Auto Faces:: Hook for automatic face assignment.
+* Basic Faces:: Faces that are defined by default.
* Font Selection:: Finding the best available font for a face.
* Font Lookup:: Looking up the names of available fonts
and information about them.
@table @code
@item :family
-Font family name or fontset name (a string). If you specify a font
-family name, the wild-card characters @samp{*} and @samp{?} are
-allowed. The function @code{font-family-list}, described below,
-returns a list of available family names. @xref{Fontsets}, for
-information about fontsets.
+Font family or fontset (a string). @xref{Fonts,,, emacs, The GNU
+Emacs Manual}. If you specify a font family name, the wild-card
+characters @samp{*} and @samp{?} are allowed. The function
+@code{font-family-list}, described below, returns a list of available
+family names. @xref{Fontsets}, for information about fontsets.
@item :foundry
-The name of the @dfn{font foundry} in which the font family specified
-by the @code{:family} attribute is located (a string). The wild-card
-characters @samp{*} and @samp{?} are allowed.
+The name of the @dfn{font foundry} for the font family specified by
+the @code{:family} attribute (a string). The wild-card characters
+@samp{*} and @samp{?} are allowed. @xref{Fonts,,, emacs, The GNU
+Emacs Manual}.
@item :width
Relative proportionate character width, also known as the character
@item @code{(:line-width @var{width} :color @var{color} :style @var{style})}
This way you can explicitly specify all aspects of the box. The value
-@var{width} specifies the width of the lines to draw; it defaults to 1.
+@var{width} specifies the width of the lines to draw; it defaults to
+1. A negative width @var{-n} means to draw a line of width @var{n}
+that occupies the space of the underlying text, thus avoiding any
+increase in the character height or width.
The value @var{color} specifies the color to draw with. The default is
the foreground color of the face for simple boxes, and the background
entity, or a string. Emacs converts such values to an appropriate
font object, and stores that font object as the actual attribute
value. If you specify a string, the contents of the string should be
-a font name (@pxref{Font X,, Font Specification Options, emacs, The
-GNU Emacs Manual}); if the font name is an XLFD containing wildcards,
-Emacs chooses the first font matching those wildcards. Specifying
-this attribute also changes the values of the @code{:family},
-@code{:foundry}, @code{:width}, @code{:height}, @code{:weight}, and
-@code{:slant} attributes.
+a font name (@pxref{Fonts,,, emacs, The GNU Emacs Manual}); if the
+font name is an XLFD containing wildcards, Emacs chooses the first
+font matching those wildcards. Specifying this attribute also changes
+the values of the @code{:family}, @code{:foundry}, @code{:width},
+@code{:height}, @code{:weight}, and @code{:slant} attributes.
@item :inherit
The name of a face from which to inherit attributes, or a list of face
@end defun
@defun face-list
-This function returns a list of all defined face names.
+This function returns a list of all defined faces.
@end defun
@defun copy-face old-face new-name &optional frame new-frame
usually assign faces to around 400 to 600 characters at each call.
@end defvar
+@node Basic Faces
+@subsection Basic Faces
+
+If your Emacs Lisp program needs to assign some faces to text, it is
+often a good idea to use certain existing faces or inherit from them,
+rather than defining entirely new faces. This way, if other users
+have customized the basic faces to give Emacs a certain look, your
+program will ``fit in'' without additional customization.
+
+ Some of the basic faces defined in Emacs are listed below. In
+addition to these, you might want to make use of the Font Lock faces
+for syntactic highlighting, if highlighting is not already handled by
+Font Lock mode, or if some Font Lock faces are not in use.
+@xref{Faces for Font Lock}.
+
+@table @code
+@item default
+The default face, whose attributes are all specified. All other faces
+implicitly inherit from it: any unspecified attribute defaults to the
+attribute on this face (@pxref{Face Attributes}).
+
+@item bold
+@itemx italic
+@itemx bold-italic
+@itemx underline
+@itemx fixed-pitch
+@itemx variable-pitch
+These have the attributes indicated by their names (e.g. @code{bold}
+has a bold @code{:weight} attribute), with all other attributes
+unspecified (and so given by @code{default}).
+
+@item shadow
+For ``dimmed out'' text. For example, it is used for the ignored
+part of a filename in the minibuffer (@pxref{Minibuffer File,,
+Minibuffers for File Names, emacs, The GNU Emacs Manual}).
+
+@item link
+@itemx link-visited
+For clickable text buttons that send the user to a different
+buffer or ``location''.
+
+@item highlight
+For stretches of text that should temporarily stand out. For example,
+it is commonly assigned to the @code{mouse-face} property for cursor
+highlighting (@pxref{Special Properties}).
+
+@item match
+For text matching a search command.
+
+@item error
+@itemx warning
+@itemx success
+For text concerning errors, warnings, or successes. For example,
+these are used for messages in @samp{*Compilation*} buffers.
+@end table
+
@node Font Selection
@subsection Font Selection
Before Emacs can draw a character on a particular display, it must
select a @dfn{font} for that character@footnote{In this context, the
term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock
-Mode}).}. Normally, Emacs automatically chooses a font based on the
-faces assigned to that character---specifically, the face attributes
-@code{:family}, @code{:weight}, @code{:slant}, and @code{:width}
-(@pxref{Face Attributes}). The choice of font also depends on the
-character to be displayed; some fonts can only display a limited set
-of characters. If no available font exactly fits the requirements,
-Emacs looks for the @dfn{closest matching font}. The variables in
-this section control how Emacs makes this selection.
+Mode}).}. @xref{Fonts,,, emacs, The GNU Emacs Manual}. Normally,
+Emacs automatically chooses a font based on the faces assigned to that
+character---specifically, the face attributes @code{:family},
+@code{:weight}, @code{:slant}, and @code{:width} (@pxref{Face
+Attributes}). The choice of font also depends on the character to be
+displayed; some fonts can only display a limited set of characters.
+If no available font exactly fits the requirements, Emacs looks for
+the @dfn{closest matching font}. The variables in this section
+control how Emacs makes this selection.
@defopt face-font-family-alternatives
If a given family is specified but does not exist, this variable
@defun x-list-fonts name &optional reference-face frame maximum width
This function returns a list of available font names that match
@var{name}. @var{name} should be a string containing a font name in
-either the Fontconfig, GTK, or XLFD format (@pxref{Font X,, Font
-Specification Options, emacs, The GNU Emacs Manual}). Within an XLFD
-string, wildcard characters may be used: the @samp{*} character
-matches any substring, and the @samp{?} character matches any single
-character. Case is ignored when matching font names.
+either the Fontconfig, GTK, or XLFD format (@pxref{Fonts,,, emacs, The
+GNU Emacs Manual}). Within an XLFD string, wildcard characters may be
+used: the @samp{*} character matches any substring, and the @samp{?}
+character matches any single character. Case is ignored when matching
+font names.
If the optional arguments @var{reference-face} and @var{frame} are
specified, the returned list includes only fonts that are the same
@table @code
@item :name
The font name (a string), in either XLFD, Fontconfig, or GTK format.
-@xref{Font X,, Font Specification Options, emacs, The GNU Emacs
-Manual}.
+@xref{Fonts,,, emacs, The GNU Emacs Manual}.
@item :family
@itemx :foundry
@defun font-xlfd-name font &optional fold-wildcards
This function returns the XLFD (X Logical Font Descriptor), a string,
-matching @var{font}. @xref{Font X,, Font Specification Options,
-emacs, The GNU Emacs Manual}, for information about XLFDs. If the
-name is too long for an XLFD (which can contain at most 255
-characters), the function returns @code{nil}.
+matching @var{font}. @xref{Fonts,,, emacs, The GNU Emacs Manual}, for
+information about XLFDs. If the name is too long for an XLFD (which
+can contain at most 255 characters), the function returns @code{nil}.
If the optional argument @var{fold-wildcards} is non-@code{nil},
consecutive wildcards in the XLFD are folded into one.
@defvar fringe-indicator-alist
This buffer-local variable specifies the mapping from logical fringe
-indicators to the actual bitmaps displayed in the window fringes.
+indicators to the actual bitmaps displayed in the window fringes. The
+value is an alist of elements @code{(@var{indicator}
+. @var{bitmaps})}, where @var{indicator} specifies a logical indicator
+type and @var{bitmaps} specifies the fringe bitmaps to use for that
+indicator.
-These symbols identify the logical fringe indicators:
+ Each @var{indicator} should be one of the following symbols:
@table @asis
-@item Truncation and continuation line indicators:
-@code{truncation}, @code{continuation}.
-
-@item Buffer position indicators:
-@code{up}, @code{down},
-@code{top}, @code{bottom},
-@code{top-bottom}.
-
-@item Empty line indicator:
-@code{empty-line}.
-
-@item Overlay arrow indicator:
-@code{overlay-arrow}.
-
-@item Unknown bitmap indicator:
-@code{unknown}.
+@item @code{truncation}, @code{continuation}.
+Used for truncation and continuation lines.
+
+@item @code{up}, @code{down}, @code{top}, @code{bottom}, @code{top-bottom}
+Used to indicate buffer boundaries when
+@code{indicate-buffer-boundaries} is non-@code{nil}: @code{up} and
+@code{down} indicate a buffer boundary lying above or below the window
+edge; @code{top} and @code{bottom} indicate the topmost and bottommost
+buffer text line; and @code{top-bottom} indicates where there is just
+one line of text in the buffer.
+
+@item @code{empty-line}
+Used to indicate empty lines when @code{indicate-empty-lines} is
+non-@code{nil}.
+
+@item @code{overlay-arrow}
+Used for overlay arrows (@pxref{Overlay Arrow}).
+@c Is this used anywhere?
+@c @item Unknown bitmap indicator:
+@c @code{unknown}.
@end table
- The value is an alist where each element @code{(@var{indicator} . @var{bitmaps})}
-specifies the fringe bitmaps used to display a specific logical
-fringe indicator.
-
-Here, @var{indicator} specifies the logical indicator type, and
-@var{bitmaps} is list of symbols @code{(@var{left} @var{right}
-[@var{left1} @var{right1}])} which specifies the actual bitmap shown
-in the left or right fringe for the logical indicator.
+ Each @var{bitmaps} value may be a list of symbols @code{(@var{left}
+@var{right} [@var{left1} @var{right1}])}. The @var{left} and
+@var{right} symbols specify the bitmaps shown in the left and/or right
+fringe, for the specific indicator. @var{left1} and @var{right1} are
+specific to the @code{bottom} and @code{top-bottom} indicators, and
+are used to indicate that the last text line has no final newline.
+Alternatively, @var{bitmaps} may be a single symbol which is used in
+both left and right fringes.
-The @var{left} and @var{right} symbols specify the bitmaps shown in
-the left and/or right fringe for the specific indicator. The
-@var{left1} or @var{right1} bitmaps are used only for the `bottom' and
-`top-bottom indicators when the last (only) line in has no final
-newline. Alternatively, @var{bitmaps} may be a single symbol which is
-used in both left and right 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 default value of
-@code{fringe-indicator-alist} is used.
-
-To completely hide a specific indicator, set the bitmap to @code{nil}.
-@end defvar
+ The standard symbols for fringe bitmaps are:
-Standard fringe bitmaps for indicators:
@example
left-arrow right-arrow up-arrow down-arrow
left-curly-arrow right-curly-arrow
empty-line question-mark
@end example
+@noindent
+In addition, @code{nil} represents the empty bitmap (i.e.@: an
+indicator that is not shown).
+
+ 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 default value of
+@code{fringe-indicator-alist} is used.
+@end defvar
+
@node Fringe Cursors
@subsection Fringe Cursors
@cindex fringe cursors
non-graphic terminals, but the other space properties in this section
are not.
+ Note that space properties are treated as paragraph separators for
+the purposes of reordering bidirectional text for display.
+@xref{Bidirectional Display}, for the details.
+
@node Pixel Specification
@subsection Pixel Specification for Spaces
@cindex spaces, pixel specification
and height of the current face. An image specification @code{image}
corresponds to the width or height of the image.
- The @code{left-fringe}, @code{right-fringe}, @code{left-margin},
-@code{right-margin}, @code{scroll-bar}, and @code{text} elements
-specify to the width of the corresponding area of the window.
+ The elements @code{left-fringe}, @code{right-fringe},
+@code{left-margin}, @code{right-margin}, @code{scroll-bar}, and
+@code{text} specify to the width of the corresponding area of the
+window.
The @code{left}, @code{center}, and @code{right} positions can be
used with @code{:align-to} to specify a position relative to the left
@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
+for that line, instead of the characters that have the display
+specification. The optional @var{face} specifies the colors to be
used for the bitmap. @xref{Fringe Bitmaps}, for the details.
@item (space-width @var{factor})
* 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.
+* Animated Images:: Some image formats can be animated.
* Image Cache:: Internal mechanisms of image display.
@end menu
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{libungif} 4.1.0), PostScript, PBM, JPEG (requiring the
-@code{libjpeg} library version v6a), TIFF (requiring @code{libtiff}
-v3.4), PNG (requiring @code{libpng} 1.0.2), and SVG (requiring
-@code{librsvg} 2.0.0).
+ The supported image formats (and the necessary library files)
+include XBM, XPM (@code{libXpm} and @code{libz}), GIF (@code{libgif}
+or @code{libungif}), PostScript, PBM, JPEG (@code{libjpeg}), TIFF
+(@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}).
You specify one of these formats with an image type symbol. The image
type symbols are @code{xbm}, @code{xpm}, @code{gif}, @code{postscript},
@table @code
@item :index @var{index}
-You can use @code{:index} to specify one image from a GIF file that
-contains more than one image. This property specifies use of image
-number @var{index} from the file. If the GIF file doesn't contain an
-image with index @var{index}, the image displays as a hollow box.
+You can use @code{:index} to specify image number @var{index} from a
+GIF file that contains more than one image. If the GIF file doesn't
+contain an image with the specified index, the image displays as a
+hollow box. GIF files with more than one image can be animated,
+@pxref{Animated Images}.
@end table
-@ignore
-This could be used to implement limited support for animated GIFs.
-For example, the following function displays a multi-image GIF file
-at point-min in the current buffer, switching between sub-images
-every 0.1 seconds.
-
-(defun show-anim (file max)
- "Display multi-image GIF file FILE which contains MAX subimages."
- (display-anim (current-buffer) file 0 max t))
-
-(defun display-anim (buffer file idx max first-time)
- (when (= idx max)
- (setq idx 0))
- (let ((img (create-image file nil :image idx)))
- (with-current-buffer buffer
- (goto-char (point-min))
- (unless first-time (delete-char 1))
- (insert-image img))
- (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil)))
-@end ignore
-
@node TIFF Images
@subsection TIFF Images
@cindex TIFF
@table @code
@item :index @var{index}
-You can use @code{:index} to specify one image from a TIFF file that
-contains more than one image. This property specifies use of image
-number @var{index} from the file. If the TIFF file doesn't contain an
-image with index @var{index}, the image displays as a hollow box.
+You can use @code{:index} to specify image number @var{index} from a
+TIFF file that contains more than one image. If the TIFF file doesn't
+contain an image with the specified index, the image displays as a
+hollow box.
@end table
@node PostScript Images
support, you can use the ImageMagick library to load many image formats.
@findex imagemagick-types
+@findex imagemagick-register-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}.
+This enables Emacs to visit these file types in @code{image-mode}
+(@pxref{File Conveniences,,, emacs, The GNU Emacs Manual}).
+If your Emacs was not compiled with ImageMagick support, then
+@code{imagemagick-types} will be undefined and
+@code{imagemagick-register-types} will do nothing.
@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
+image types that you do @emph{not} want ImageMagick to handle. It is
+a list of symbols, each of which has the same name as one of the
+format tags used internally by ImageMagick (i.e., as
+@code{imagemagick-types} returns). ImageMagick has a very broad
+definition of what an image is, for example it includes such file
+types as C files and HTML files. It is not appropriate to treat these
+as images in Emacs. You can add any other ImageMagick type that you
+wish to this list.
+@ignore
+@c I don't know what this means. I suspect it means eg loading jpg
+@c images via libjpeg or ImageMagick. But it doesn't work.
+@c If you don't have libjpeg support compiled in, you cannot
+@c view jpeg images, even if you have imagemagick support:
+@c http://debbugs.gnu.org/9045
+@c And if you have both compiled in, then you always get
+@c the libjpeg version:
+@c http://debbugs.gnu.org/10746
+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 loader will be used in practice depends on the priority of the
+loaders).
+For example, if you never want to use the ImageMagick loader to view
JPEG files, add @code{JPG} to this list.
+@end ignore
+Note that ImageMagick often distinguishes between several different
+types of a particular format (e.g., @code{JPG}, @code{JPEG},
+@code{PJPEG}, etc.), and you may need to add all versions to this
+list.
+@c Not sure this should even be in the manual at all.
@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.
+If you wish to experiment with the performance of the ImageMagick
+loader, see the variable @code{imagemagick-render-type}.
Images loaded with ImageMagick support a few new display specifications:
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).
+@c Doesn't work: http://debbugs.gnu.org/7978
+This has the same meaning as it does for GIF images (@pxref{GIF Images}),
+i.e. it specifies which image to view inside an image bundle file format
+such as DJVM. You can use the @code{image-metadata} function to
+retrieve the total number of images in an image bundle.
@end table
found, don't signal an error. Instead, return a list of directories as
before, except that @code{nil} appears in place of the image directory.
-Here is an example that uses a common idiom to provide compatibility
-with versions of Emacs that lack the variable @code{image-load-path}:
+Here is an example of using @code{image-load-path-for-library}:
@example
(defvar image-load-path) ; shush compiler
(let* ((load-path (image-load-path-for-library
- "mh-e" "mh-logo.xpm"))
+ "mh-e" "mh-logo.xpm"))
(image-load-path (cons (car load-path)
- (when (boundp 'image-load-path)
- image-load-path))))
+ image-load-path)))
(mh-tool-bar-folder-buttons-init))
@end example
@end defun
Property}.
@end defun
+@cindex slice, image
+@cindex image slice
@defun insert-sliced-image image &optional string area rows cols
This function inserts @var{image} in the current buffer at point, like
@code{insert-image}, but splits the image into @var{rows}x@var{cols}
equally sized slices.
+
+If an image is inserted ``sliced'', then the Emacs display engine will
+treat each slice as a separate image, and allow more intuitive
+scrolling up/down, instead of jumping up/down the entire image when
+paging through a buffer that displays (large) images.
@end defun
@defun put-image image pos &optional string area
@var{max-image-size} is subsequently changed (@pxref{Image Cache}).
@end defvar
+@node Animated Images
+@subsection Animated Images
+
+@cindex animation
+@cindex image animation
+Some image files can contain more than one image. This can be used to
+create animation. Currently, Emacs only supports animated GIF files.
+The following functions related to animated images are available.
+
+@defun image-animated-p image
+This function returns non-nil if @var{image} can be animated.
+The actual return value is a cons @code{(@var{nimages} . @var{delay})},
+where @var{nimages} is the number of frames and @var{delay} is the
+delay in seconds between them.
+@end defun
+
+@defun image-animate image &optional index limit
+This function animates @var{image}. The optional integer @var{index}
+specifies the frame from which to start (default 0). The optional
+argument @var{limit} controls the length of the animation. If omitted
+or @code{nil}, the image animates once only; if @code{t} it loops
+forever; if a number animation stops after that many seconds.
+@end defun
+
+@noindent Animation operates by means of a timer. Note that Emacs imposes a
+minimum frame delay of 0.01 seconds.
+
+@defun image-animate-timer image
+This function returns the timer responsible for animating @var{image},
+if there is one.
+@end defun
+
+
@node Image Cache
@subsection Image Cache
@cindex image cache
(aref colorcomp-data 2)))
(samp " (sample text) "))
(insert "Color\t: "
- (propertize samp 'face `(foreground-color . ,cstr))
- (propertize samp 'face `(background-color . ,cstr))
+ (propertize samp 'face
+ `(foreground-color . ,cstr))
+ (propertize samp 'face
+ `(background-color . ,cstr))
"\n"))))
(defun colorcomp (color)
@itemize @bullet
@item
Character codes 32 through 126 map to glyph codes 32 through 126.
-Normally this means they display as themselves.
+Normally this means they display as themselves, but a display table
+can change that.
@item
Character code 9 is a horizontal tab. It displays as whitespace
up to a position determined by @code{tab-width}.
@item
-Character code 10 is a newline.
+Character code 10 is a newline. It is normally invisible on display,
+and has the effect of ending the preceding line and starting a new
+line.
@item
-All other codes in the range 0 through 31, and code 127, display in one
-of two ways according to the value of @code{ctl-arrow}. If it is
-non-@code{nil}, these codes map to sequences of two glyphs, where the
-first glyph is the @acronym{ASCII} code for @samp{^}. (A display table can
-specify a glyph to use instead of @samp{^}.) Otherwise, these codes map
-just like the codes in the range 128 to 255.
-
-On MS-DOS terminals, Emacs arranges by default for the character code
-127 to be mapped to the glyph code 127, which normally displays as an
-empty polygon. This glyph is used to display non-@acronym{ASCII} characters
-that the MS-DOS terminal doesn't support. @xref{MS-DOS and MULE,,,
-emacs, The GNU Emacs Manual}.
-
+All other codes in the range 0 through 31 display in one of two ways
+according to the value of @code{ctl-arrow}. If it is non-@code{nil},
+these codes map to sequences of two glyphs, where the first glyph is
+the @acronym{ASCII} code for @samp{^}. (A display table can specify a
+glyph to use instead of @samp{^}.) Otherwise, these codes map just
+like the raw bytes in the range 128 to 255 (described below).
+
+@cindex octal escapes
@item
-Character codes 128 through 255 map to sequences of four glyphs, where
-the first glyph is the @acronym{ASCII} code for @samp{\}, and the others are
-digit characters representing the character code in octal. (A display
-table can specify a glyph to use instead of @samp{\}.)
+Raw bytes (@pxref{Text Representations}) with codes 128 through 255,
+and the @acronym{ASCII} control character with code 127, display as
+sequences of four glyphs, where the first glyph is the @acronym{ASCII}
+code for @samp{\}, and the others are digit characters representing
+the character code in octal. (A display table can specify a glyph to
+use instead of @samp{\}.) This is known as the @dfn{octal escape}
+display.
@item
-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.
+Non-@acronym{ASCII} character codes above 127 are displayed as
+themselves, if the terminal and the available fonts support them.
+Characters that are not supported by the terminal, or (on window
+systems) have no fonts available for them, are displayed as a question
+mark or a hex code or an empty box. @xref{Glyphless Chars}, for how
+to control display of the characters not supported by the terminal or
+fonts. Display tables can change how a character is displayed, even
+if it is supported.
@end itemize
The usual display conventions apply even when there is a display
This buffer-local variable controls how control characters are
displayed. If it is non-@code{nil}, they are displayed as a caret
followed by the character: @samp{^A}. If it is @code{nil}, they are
-displayed as a backslash followed by three octal digits: @samp{\001}.
+displayed as octal escapes: a backslash followed by three octal
+digits, as in @samp{\001}.
@end defopt
@defopt tab-width
concerned; the individual Emacs windows are not known to X at all.
@defvar window-system
-This frame-local variable tells Lisp programs what window system Emacs is using
-for displaying the frame. The possible values are
+This terminal-local variable tells Lisp programs what window system
+Emacs is using for displaying the frame. The possible values are
@table @code
@item x
the window system, and creating the initial window. Users should not
interfere with it.
@end defvar
+
+@node Bidirectional Display
+@section Bidirectional Display
+@cindex bidirectional display
+@cindex right-to-left text
+
+ Emacs can display text written in scripts, such as Arabic, Farsi,
+and Hebrew, whose natural ordering of horizontal text for display is
+from right to left. However, digits and Latin text embedded in these
+scripts are still displayed left to right. It is also not uncommon to
+have small portions of text in Arabic or Hebrew embedded in otherwise
+Latin document, e.g., as comments and strings in a program source
+file. Likewise, small portions of Latin text can be embedded in an
+Arabic or Farsi document. For these reasons, text that uses these
+scripts is actually @dfn{bidirectional}: a mixture of runs of
+left-to-right and right-to-left characters.
+
+ This section describes the facilities and options provided by Emacs
+for editing and displaying bidirectional text.
+
+@cindex logical order
+@cindex reading order
+@cindex visual order
+@cindex unicode bidirectional algorithm
+ Emacs stores right-to-left and bidirectional text in the so-called
+@dfn{logical} (or @dfn{reading}) order: the buffer or string position
+of the first character you read precedes that of the next character.
+Reordering of bidirectional text into the @dfn{visual} order happens
+at display time. As result, character positions no longer increase
+monotonically with their positions on display. Emacs implements the
+Unicode Bidirectional Algorithm (a.k.a.@: @acronym{UBA}) described in
+the Unicode Standard Annex #9, for reordering of bidirectional text
+for display. Reordering of bidirectional text for display in Emacs is
+a ``Full bidirectionality'' class implementation of the @acronym{UBA}.
+
+@defvar bidi-display-reordering
+ This buffer-local variable controls whether text in the buffer is
+reordered for display. If its value is non-@code{nil}, Emacs reorders
+characters that have right-to-left directionality when they are
+displayed. The default value is @code{t}. Text in overlay strings
+(@pxref{Overlay Properties,,before-string}), display strings
+(@pxref{Overlay Properties,,display}), and @code{display} text
+properties (@pxref{Display Property}) is also reordered for display if
+the buffer whose text includes these strings is reordered. Turning
+off @code{bidi-display-reordering} for a buffer turns off reordering
+of all the overlay and display strings in that buffer.
+
+ Reordering of strings that are unrelated to any buffer, such as text
+displayed on the mode line (@pxref{Mode Line Format}) or header line
+(@pxref{Header Lines}), is controlled by the default value of
+@code{bidi-display-reordering}.
+@end defvar
+
+@cindex unibyte buffers, and bidi reordering
+ Emacs does not reorder text in unibyte buffers, even if
+@code{bidi-display-reordering} is non-@code{nil} in such a buffer.
+This is because unibyte buffers contain raw bytes, not characters, and
+thus don't have bidirectional properties defined for them which are
+required for correct reordering. Therefore, to test whether text in a
+buffer will be reordered for display, it is not enough to test the
+value of @code{bidi-display-reordering} alone. The correct test is
+this:
+
+@example
+ (if (and enable-multibyte-characters
+ bidi-display-reordering)
+ ;; Buffer is being reordered for display
+ )
+@end example
+
+ In contrast to unibyte buffers, unibyte display and overlay strings
+@emph{are} reordered, if their parent buffer is reordered. This is
+because plain-@sc{ascii} strings are stored by Emacs as unibyte
+strings. If a unibyte display or overlay string includes
+non-@sc{ascii} characters, these characters are assumed to have
+left-to-right direction.
+
+@cindex display properties, and bidi reordering of text
+ Text covered by @code{display} text properties, by overlays with
+@code{display} properties whose value is a string, and by any other
+properties that replace buffer text, is treated as a single unit when
+it is reordered for display. That is, the entire chunk of text
+covered by these properties is reordered together. Moreover, the
+bidirectional properties of the characters in this chunk of text are
+ignored, and Emacs reorders them as if they were replaced with a
+single character @code{U+FFFC}, known as the @dfn{Object Replacement
+Character}. This means that placing a display property over a portion
+of text may change the way that the surrounding text is reordered for
+display. To prevent this unexpected effect, always place such
+properties on text whose directionality is identical with text that
+surrounds it.
+
+@cindex base direction of a paragraph
+ Each paragraph of bidirectional text can have its own @dfn{base
+direction}, either right-to-left or left-to-right. Text in
+left-to-right paragraphs is displayed beginning at the left margin of
+the window and is truncated or continued when it reaches the right
+margin. By contrast, display of text in right-to-left paragraphs
+begins at the right margin and is continued or truncated at the left
+margin.
+
+@defvar bidi-paragraph-direction
+ By default, Emacs determines the base direction of each paragraph
+dynamically, based on the text at the beginning of the paragraph. The
+precise method of determining the base direction is specified by the
+@acronym{UBA}; in a nutshell, the first character in a paragraph that
+has an explicit directionality determines the base direction of the
+paragraph. However, sometimes a buffer may need to force a certain
+base direction for its paragraphs. For example, a buffer that visits
+a source code of a program should force all its paragraphs to be
+displayed left to right. The variable
+@code{bidi-paragraph-direction}, if non-@code{nil}, disables the
+dynamic determination of the base direction, and instead forces all
+paragraphs in the buffer to have the direction specified by its
+buffer-local value. The value can be either @code{right-to-left} or
+@code{left-to-right}. Any other value is interpreted as @code{nil}.
+The default is @code{nil}.
+
+@cindex @code{prog-mode}, and @code{bidi-paragraph-direction}
+Modes that are meant to display program source code should force a
+@code{left-to-right} paragraph direction. The easiest way of doing so
+is to derive the mode from Prog Mode, which already sets
+@code{bidi-paragraph-direction} to that value.
+@end defvar
+
+@defun current-bidi-paragraph-direction &optional buffer
+This function returns the paragraph direction at point in the named
+@var{buffer}. The returned value is a symbol, either
+@code{left-to-right} or @code{right-to-left}. If @var{buffer} is
+omitted or @code{nil}, it defaults to the current buffer. If the
+buffer-local value of the variable @code{bidi-paragraph-direction} is
+non-@code{nil}, the returned value will be identical to that value;
+otherwise, the returned value reflects the paragraph direction
+determined dynamically by Emacs. For buffers whose value of
+@code{bidi-display-reordering} is @code{nil} as well as unibyte
+buffers, this function always returns @code{left-to-right}.
+@end defun
+
+@cindex layout on display, and bidirectional text
+@cindex jumbled display of bidirectional text
+@cindex concatenating bidirectional strings
+ Reordering of bidirectional text for display can have surprising and
+unpleasant effects when two strings with bidirectional content are
+juxtaposed in a buffer, or otherwise programmatically concatenated
+into a string of text. A typical example is a buffer whose lines are
+actually sequences of items, or fields, separated by whitespace or
+punctuation characters. This is used in specialized modes such as
+Buffer-menu Mode or various email summary modes, like Rmail Summary
+Mode. Because these separator characters are @dfn{weak}, i.e.@: have
+no strong directionality, they take on the directionality of
+surrounding text. As result, a numeric field that follows a field
+with bidirectional content can be displayed @emph{to the left} of the
+preceding field, producing a jumbled display and messing up the
+expected layout.
+
+ To countermand this, we recommend that you use one of the following
+techniques for forcing correct order of fields on display:
+
+@itemize @minus
+@item
+Append the special character @code{U+200E}, LEFT-TO-RIGHT MARK, or
+@acronym{LRM}, to the end of each field that may have bidirectional
+content, or prepend it to the beginning of the following field. The
+function @code{bidi-string-mark-left-to-right}, described below, comes
+in handy for this purpose. (In a right-to-left paragraph, use
+@code{U+200F}, RIGHT-TO-LEFT MARK, or @acronym{RLM}, instead.) This
+is one of the solutions recommended by
+@uref{http://www.unicode.org/reports/tr9/#Separators, the
+@acronym{UBA}}.
+
+@item
+Include the tab character in the field separator. The tab character
+plays the role of @dfn{segment separator} in the @acronym{UBA}
+reordering, whose effect is to make each field a separate segment, and
+thus reorder them separately.
+
+@cindex @code{space} display spec, and bidirectional text
+@item
+Separate fields with a @code{display} property or overlay with the
+property value of the form @code{(space . PROPS)} (@pxref{Specified
+Space}). This display specification is treated by Emacs as a
+@dfn{paragraph separator}; the text before and after the separator is
+reordered separately, which avoids the influence of any field on its
+neighboring fields.
+@end itemize
+
+@defun bidi-string-mark-left-to-right string
+This subroutine returns its argument @var{string}, possibly modified,
+such that the result can be safely concatenated with another string,
+or juxtaposed with another string in a buffer, without disrupting the
+relative layout of this string and the next one on display. If the
+string returned by this function is displayed as part of a
+left-to-right paragraph, it will always appear on display to the left
+of the text that follows it. The function works by examining the
+characters of its argument, and if any of those characters could cause
+reordering on display, the function appends the @acronym{LRM}
+character to the string. The appended @acronym{LRM} character is made
+@emph{invisible} (@pxref{Invisible Text}), to hide it on display.
+@end defun
+
+ The reordering algorithm uses the bidirectional properties of the
+characters stored as their @code{bidi-class} property
+(@pxref{Character Properties}). Lisp programs can change these
+properties by calling the @code{put-char-code-property} function.
+However, doing this requires a thorough understanding of the
+@acronym{UBA}, and is therefore not recommended. Any changes to the
+bidirectional properties of a character have global effect: they
+affect all Emacs frames and windows.
+
+ Similarly, the @code{mirroring} property is used to display the
+appropriate mirrored character in the reordered text. Lisp programs
+can affect the mirrored display by changing this property. Again, any
+such changes affect all of Emacs display.
+
+@node Glyphless Chars
+@section Glyphless Character Display
+@cindex glyphless characters
+
+ @dfn{Glyphless characters} are not displayed in the usual way when
+they appear in a buffer, but in some special way (e.g. as a box
+containing a hexadecimal code). These include characters that cannot
+be displayed with any available font (on a graphical display), or that
+cannot be encoded by the terminal's coding system (on a text-only
+terminal). Specific characters can also be defined to be glyphless.
+
+@defvar glyphless-char-display
+The value of this variable is a char-table that defines glyphless
+characters and how they are displayed. If an entry is @code{nil}, the
+corresponding character is displayed in its usual way. Otherwise, an
+entry should be one of the following display methods:
+
+@table @asis
+@item @code{zero-width}
+Don't display the character.
+
+@item @code{thin-space}
+Display a thin space, 1-pixel wide on graphical displays, or
+1-character wide on text-only terminals.
+
+@item @code{empty-box}
+Display an empty box.
+
+@item @code{hex-code}
+Display a box containing the Unicode codepoint of the character, in
+hexadecimal notation.
+
+@item an @acronym{ASCII} string
+Display a box containing that string.
+@end table
+
+@noindent
+Except for @code{zero-width}, these methods display using the
+@code{glyphless-char} face.
+
+An entry can also be a cons cell @code{(@var{graphical}
+. @var{text})}, where @var{graphical} and @var{text} are the display
+methods on graphical displays and text-only terminals respectively.
+
+The char-table has one extra slot, which determines how to display any
+character that cannot be displayed with any available font, or cannot
+be encoded by the terminal's coding system. Its value should be one
+of the above display methods, except @code{zero-width} or a cons cell.
+@end defvar
+
+@defopt glyphless-char-display-control
+This user option provides a convenient way to set
+@code{glyphless-char-display} for groups of similar characters. It
+takes effect via a custom @code{:set} function (@pxref{Variable
+Definitions}), which update @code{glyphless-char-display}.
+
+Its value should be an alist of elements @code{(@var{group}
+. @var{method})}, where @var{group} is a symbol specifying a group of
+characters, and @var{method} is a symbol specifying how to display
+them.
+
+@var{group} should be one of the following:
+
+@table @code
+@item c0-control
+@acronym{ASCII} control characters @code{U+0000} to @code{U+001F},
+excluding the newline and tab characters (normally displayed as escape
+sequences like @samp{^A}; @pxref{Text Display,, How Text Is Displayed,
+emacs, The GNU Emacs Manual}).
+
+@item c1-control
+Non-@acronym{ASCII}, non-printing characters @code{U+0080} to
+@code{U+009F} (normally displayed as octal escape sequences like
+@samp{\230}).
+
+@item format-control
+Characters of Unicode General Category `Cf', such as @samp{U+200E}
+(Left-to-Right Mark), but excluding characters that have graphic
+images, such as @samp{U+00AD} (Soft Hyphen).
+
+@item no-font
+Characters for there is no suitable font, or which cannot be encoded
+by the terminal's coding system.
+@end table
+
+@c FIXME: this can also be `acronym', but that's not currently
+@c completely implemented; it applies only to the format-control
+@c group, and only works if the acronym is in `char-acronym-table'.
+The @var{method} symbol should be one of @code{zero-width},
+@code{thin-space}, @code{empty-box}, or @code{hex-code}. These have
+the same meanings as in @code{glyphless-char-display}, above.
+@end defopt