continuation to display them, computing the continuation lines can
make 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}.
+@code{cache-long-scans} to @code{t}.
-@defvar cache-long-line-scans
+@defvar cache-long-scans
If this variable is non-@code{nil}, various indentation and motion
functions, and Emacs redisplay, cache the results of scanning the
buffer, and consult the cache to avoid rescanning regions of the buffer
@node Overlays
@section Overlays
@cindex overlays
+@c FIXME: mention intervals in this section?
You can use @dfn{overlays} to alter the appearance of a buffer's text on
the screen, for the sake of presentation features. An overlay is an
@item face
@kindex face @r{(overlay property)}
-This property controls the way text is displayed---for example, which
-font and which colors. @xref{Faces}, for more information.
-
-In the simplest case, the value is a face name. It can also be a list;
-then each element can be any of these possibilities:
+This property controls the appearance of the text (@pxref{Faces}).
+The value of the property can be the following:
@itemize @bullet
@item
A face name (a symbol or string).
@item
-A property list of face attributes. This has the form (@var{keyword}
-@var{value} @dots{}), where each @var{keyword} is a face attribute
-name and @var{value} is a meaningful value for that attribute. With
-this feature, you do not need to create a face each time you want to
-specify a particular attribute for certain text. @xref{Face
-Attributes}.
+An anonymous face: a property list of the form @code{(@var{keyword}
+@var{value} @dots{})}, where each @var{keyword} is a face attribute
+name and @var{value} is a value for that attribute.
@item
-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.
+A list of faces. Each list element should be either a face name or an
+anonymous face. This specifies a face which is an aggregate of the
+attributes of each of the listed faces. Faces occurring earlier in
+the list have higher priority.
-@code{(foreground-color . @var{color-name})} has the same effect as
-@code{(:foreground @var{color-name})}; likewise for the background.
+@item
+A cons cell of the form @code{(foreground-color . @var{color-name})}
+or @code{(background-color . @var{color-name})}. This specifies the
+foreground or background color, similar to @code{(:foreground
+@var{color-name})} or @code{(:background @var{color-name})}. This
+form is supported for backward compatibility only, and should be
+avoided.
@end itemize
@item mouse-face
an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
it immediately.
-@item local-map
-@cindex keymap of character (and overlays)
-@kindex local-map @r{(overlay property)}
-If this property is non-@code{nil}, it specifies a keymap for a portion
-of the text. The property's value replaces the buffer's local map, when
-the character after point is within the overlay. @xref{Active Keymaps}.
-
@item keymap
+@cindex keymap of character (and overlays)
@kindex keymap @r{(overlay property)}
-The @code{keymap} property is similar to @code{local-map} but overrides the
-buffer's local map (and the map specified by the @code{local-map}
-property) rather than replacing it.
+If this property is non-@code{nil}, it specifies a keymap for a portion of the
+text. This keymap is used when the character after point is within the
+overlay, and takes precedence over most other keymaps. @xref{Active Keymaps}.
+
+@item local-map
+@kindex local-map @r{(overlay property)}
+The @code{local-map} property is similar to @code{keymap} but replaces the
+buffer's local map rather than augmenting existing keymaps. This also means it
+has lower precedence than minor mode keymaps.
@end table
-The @code{local-map} and @code{keymap} properties do not affect a
+The @code{keymap} and @code{local-map} properties do not affect a
string displayed by the @code{before-string}, @code{after-string}, or
@code{display} properties. This is only relevant for mouse clicks and
other mouse events that fall on the string, since point is never on
the string. To bind special mouse events for the string, assign it a
-@code{local-map} or @code{keymap} text property. @xref{Special
+@code{keymap} or @code{local-map} text property. @xref{Special
Properties}.
@node Finding Overlays
@section Faces
@cindex faces
- A @dfn{face} is a collection of graphical @dfn{attributes} for
-displaying text: font, foreground color, background color, optional
-underlining, etc. Faces control how Emacs displays text in buffers,
-as well as other parts of the frame such as the mode line.
+ A @dfn{face} is a collection of graphical attributes for displaying
+text: font, foreground color, background color, optional underlining,
+etc. Faces control how Emacs displays text in buffers, as well as
+other parts of the frame such as the mode line.
@cindex anonymous face
One way to represent a face is as a property list of attributes,
-like @code{(:foreground "red" :weight bold)}. For example, you can
-assign such an @dfn{anonymous face} as the value of the @code{face}
-text property; this causes Emacs to display the underlying text with
-the specified attributes. @xref{Special Properties}.
+like @code{(:foreground "red" :weight bold)}. Such a list is called
+an @dfn{anonymous face}. For example, you can assign an anonymous
+face as the value of the @code{face} text property, and Emacs will
+display the underlying text with the specified attributes.
+@xref{Special Properties}.
@cindex face name
More commonly, a face is referred to via a @dfn{face name}: a Lisp
-symbol which is associated with a set of face attributes. Named faces
-are defined using the @code{defface} macro (@pxref{Defining Faces}).
-Emacs defines several standard named faces; @xref{Standard Faces,,,
-emacs, The GNU Emacs Manual}.
-
- Many parts of Emacs require named faces, and do not accept anonymous
-faces. These include the functions documented in @ref{Attribute
-Functions}, and the variable @code{font-lock-keywords}
+symbol associated with a set of face attributes@footnote{For backward
+compatibility, you can also use a string to specify a face name; that
+is equivalent to a Lisp symbol with the same name.}. Named faces are
+defined using the @code{defface} macro (@pxref{Defining Faces}).
+Emacs comes with several standard named faces (@pxref{Basic Faces}).
+
+ Many parts of Emacs required named faces, and do not accept
+anonymous faces. These include the functions documented in
+@ref{Attribute Functions}, and the variable @code{font-lock-keywords}
(@pxref{Search-based Fontification}). Unless otherwise stated, we
will use the term @dfn{face} to refer only to named faces.
- For backward compatibility, you can also use a string to specify a
-face name; that is equivalent to a Lisp symbol with the same name.
-
@defun facep object
This function returns a non-@code{nil} value if @var{object} is a
named face: a Lisp symbol or string which serves as a face name.
Otherwise, it returns @code{nil}.
@end defun
- By default, each face name corresponds to the same set of attributes
-in all frames. But you can also assign a face name a special set of
-attributes in one frame (@pxref{Attribute Functions}).
-
@menu
* Face Attributes:: What is in a face?
* Defining Faces:: How to define a face.
@item :font
The font used to display the face. Its value should be a font object.
-@xref{Font Selection}, for information about font objects.
+@xref{Low-Level Font}, for information about font objects, font specs,
+and font entities.
When specifying this attribute using @code{set-face-attribute}
(@pxref{Attribute Functions}), you may also supply a font spec, a font
@node Defining Faces
@subsection Defining Faces
+@cindex face spec
The usual way to define a face is through the @code{defface} macro.
-This macro defines a face name, and associates that name with a set of
-face attributes. It also sets up the face so that the user can
-customize it via the Customize interface (@pxref{Customization}).
+This macro associates a face name (a symbol) with a default @dfn{face
+spec}. A face spec is a construct which specifies what attributes a
+face should have on any given terminal; for example, a face spec might
+specify one foreground color on high-color terminals, and a different
+foreground color on low-color terminals.
+
+ People are sometimes tempted to create a variable whose value is a
+face name. In the vast majority of cases, this is not necessary; the
+usual procedure is to define a face with @code{defface}, and then use
+its name directly.
@defmac defface face spec doc [keyword value]@dots{}
-This macro declares @var{face} as a customizable face whose default
-attributes are given by @var{spec}. You should not quote the symbol
-@var{face}, and it should not end in @samp{-face} (that would be
-redundant). The argument @var{doc} is a documentation string for the
-face. The additional @var{keyword} arguments have the same meanings
-as in @code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
-
-When @code{defface} executes, it defines the face according to
-@var{spec}, then uses any customizations that were read from the
-init file (@pxref{Init File}) to override that specification.
-
-When you evaluate a @code{defface} form with @kbd{C-M-x} in Emacs
-Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun}
-overrides any customizations of the face. This way, the face reflects
-exactly what the @code{defface} says.
-
-@cindex face specification
-The @var{spec} argument is a @dfn{face specification}, which states
-how the face should appear on different kinds of terminals. It should
-be an alist whose elements each have the form
+This macro declares @var{face} as a named face whose default face spec
+is given by @var{spec}. You should not quote the symbol @var{face},
+and it should not end in @samp{-face} (that would be redundant). The
+argument @var{doc} is a documentation string for the face. The
+additional @var{keyword} arguments have the same meanings as in
+@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
+
+If @var{face} already has a default face spec, this macro does
+nothing.
+
+The default face spec determines @var{face}'s appearance when no
+customizations are in effect (@pxref{Customization}). If @var{face}
+has already been customized (via Custom themes or via customizations
+read from the init file), its appearance is determined by the custom
+face spec(s), which override the default face spec @var{spec}.
+However, if the customizations are subsequently removed, the
+appearance of @var{face} will again be determined by its default face
+spec.
+
+As an exception, if you evaluate a @code{defface} form with
+@kbd{C-M-x} in Emacs Lisp mode (@code{eval-defun}), a special feature
+of @code{eval-defun} overrides any custom face specs on the face,
+causing the face to reflect exactly what the @code{defface} says.
+
+The @var{spec} argument is a @dfn{face spec}, which states how the
+face should appear on different kinds of terminals. It should be an
+alist whose elements each have the form
@example
(@var{display} . @var{plist})
@end table
@end defmac
- Here's how the standard face @code{highlight} is defined:
+ For example, here's the definition of the standard face
+@code{highlight}:
@example
(defface highlight
:group 'basic-faces)
@end example
- Internally, Emacs stores the face's default specification in its
+ Internally, Emacs stores each face's default spec in its
@code{face-defface-spec} symbol property (@pxref{Symbol Properties}).
-The @code{saved-face} property stores the face specification saved by
-the user, using the customization buffer; the @code{customized-face}
-property stores the face specification customized for the current
-session, but not saved; and the @code{theme-face} property stores an
-alist associating the active customization settings and Custom themes
-with their specifications for that face. The face's documentation
-string is stored in the @code{face-documentation} property. But
-normally you should not try to set any of these properties directly.
-@xref{Applying Customizations}, for the @code{custom-set-faces}
-function, which is used to apply customized face settings.
-
- People are sometimes tempted to create variables whose values
-specify a face to use. In the vast majority of cases, this is not
-necessary; it is preferable to simply use faces directly.
+The @code{saved-face} property stores any face spec saved by the user
+using the customization buffer; the @code{customized-face} property
+stores the face spec customized for the current session, but not
+saved; and the @code{theme-face} property stores an alist associating
+the active customization settings and Custom themes with the face
+specs for that face. The face's documentation string is stored in the
+@code{face-documentation} property.
+
+ Normally, a face is declared just once, using @code{defface}, and
+any further changes to its appearance are applied using the Customize
+framework (e.g., via the Customize user interface or via the
+@code{custom-set-faces} function; @pxref{Applying Customizations}), or
+by face remapping (@pxref{Face Remapping}). In the rare event that
+you need to change a face spec directly from Lisp, you can use the
+@code{face-spec-set} function.
+
+@defun face-spec-set face spec &optional spec-type
+This function applies @var{spec} as a face spec for @code{face}.
+@var{spec} should be a face spec, as described in the above
+documentation for @code{defface}.
+
+@cindex override spec @r{(for a face)}
+The argument @var{spec-type} determines which spec to set. If it is
+@code{nil} or @code{face-override-spec}, this function sets the
+@dfn{override spec}, which overrides over all other face specs on
+@var{face}. If it is @code{face-defface-spec}, this function sets the
+default face spec (the same one set by @code{defface}). If it is
+@code{reset}, this function clears out all customization specs and
+override specs from @var{face} (in this case, the value of @var{spec}
+is ignored). Any other value of @var{spec-type} is reserved for
+internal use.
+@end defun
@node Attribute Functions
@subsection Face Attribute Functions
- This section describes the functions for accessing and modifying the
-attributes of an existing named face.
-
-@defun set-face-attribute face frame &rest arguments
-This function sets one or more attributes of @var{face} for
-@var{frame}. The attributes you specify this way override whatever
-the @code{defface} says.
-
-The extra arguments @var{arguments} specify the attributes to set, and
-the values for them. They should consist of alternating attribute
-names (such as @code{:family} or @code{:underline}) and values. Thus,
-
-@example
-(set-face-attribute 'foo nil
- :width 'extended
- :weight 'bold)
-@end example
-
-@noindent
-sets the attribute @code{:width} to @code{extended} and the attribute
-@code{:weight} to @code{bold}.
-
-If @var{frame} is @code{t}, this function sets the default attributes
-for new frames. Default attribute values specified this way override
-the @code{defface} for newly created frames.
-
-If @var{frame} is @code{nil}, this function sets the attributes for
-all existing frames, and the default for new frames.
-@end defun
+ This section describes functions for directly accessing and
+modifying the attributes of a named face.
@defun face-attribute face attribute &optional frame inherit
-This returns the value of the @var{attribute} attribute of @var{face}
-on @var{frame}. If @var{frame} is @code{nil}, that means the selected
-frame (@pxref{Input Focus}).
+This function returns the value of the @var{attribute} attribute for
+@var{face} on @var{frame}.
-If @var{frame} is @code{t}, this returns whatever new-frames default
-value you previously specified with @code{set-face-attribute} for the
-@var{attribute} attribute of @var{face}. If you have not specified
-one, it returns @code{nil}.
+If @var{frame} is @code{nil}, that means the selected frame
+(@pxref{Input Focus}). If @var{frame} is @code{t}, this function
+returns the value of the specified attribute for newly-created frames
+(this is normally @code{unspecified}, unless you have specified some
+value using @code{set-face-attribute}; see below).
If @var{inherit} is @code{nil}, only attributes directly defined by
@var{face} are considered, so the return value may be
@var{attribute}, returns it merged with the underlying value
@var{value2}; otherwise, if @var{value1} is an absolute value for the
face attribute @var{attribute}, returns @var{value1} unchanged.
+@end defun
+
+ Normally, Emacs uses the face specs of each face to automatically
+calculate its attributes on each frame (@pxref{Defining Faces}). The
+function @code{set-face-attribute} can override this calculation by
+directly assigning attributes to a face, either on a specific frame or
+for all frames. This function is mostly intended for internal usage.
+
+@defun set-face-attribute face frame &rest arguments
+This function sets one or more attributes of @var{face} for
+@var{frame}. The attributes specifies in this way override the face
+spec(s) belonging to @var{face}.
+
+The extra arguments @var{arguments} specify the attributes to set, and
+the values for them. They should consist of alternating attribute
+names (such as @code{:family} or @code{:underline}) and values. Thus,
+
+@example
+(set-face-attribute 'foo nil :weight 'bold :slant 'italic)
+@end example
+
+@noindent
+sets the attribute @code{:weight} to @code{bold} and the attribute
+@code{:slant} to @code{italic}.
+
+
+If @var{frame} is @code{t}, this function sets the default attributes
+for newly created frames. If @var{frame} is @code{nil}, this function
+sets the attributes for all existing frames, as well as for newly
+created frames.
@end defun
The following commands and functions mostly provide compatibility
This swaps the foreground and background colors of face @var{face}.
@end deffn
- The following functions examine the attributes of a face. If you
-don't specify @var{frame}, they refer to the selected frame; @code{t}
-refers to the default data for new frames. They return the symbol
-@code{unspecified} if the face doesn't define any value for that
-attribute. If @var{inherit} is @code{nil}, only an attribute directly
-defined by the face is returned. If @var{inherit} is non-@code{nil},
-any faces specified by its @code{:inherit} attribute are considered as
-well, and if @var{inherit} is a face or a list of faces, then they are
-also considered, until a specified attribute is found. To ensure that
-the return value is always specified, use a value of @code{default} for
+ The following functions examine the attributes of a face. They
+mostly provide compatibility with old versions of Emacs. If you don't
+specify @var{frame}, they refer to the selected frame; @code{t} refers
+to the default data for new frames. They return @code{unspecified} if
+the face doesn't define any value for that attribute. If
+@var{inherit} is @code{nil}, only an attribute directly defined by the
+face is returned. If @var{inherit} is non-@code{nil}, any faces
+specified by its @code{:inherit} attribute are considered as well, and
+if @var{inherit} is a face or a list of faces, then they are also
+considered, until a specified attribute is found. To ensure that the
+return value is always specified, use a value of @code{default} for
@var{inherit}.
@defun face-font face &optional frame
any text having the face @var{face} with @var{remapping}, rather than
the ordinary definition of @var{face}.
-@var{remapping} may be any face specification suitable for a
-@code{face} text property: either a face (i.e., a face name or a
-property list of attribute/value pairs), or a list of faces. For
-details, see the description of the @code{face} text property in
-@ref{Special Properties}. @var{remapping} serves as the complete
-specification for the remapped face---it replaces the normal
-definition of @var{face}, instead of modifying it.
+@var{remapping} may be any face spec suitable for a @code{face} text
+property: either a face (i.e., a face name or a property list of
+attribute/value pairs), or a list of faces. For details, see the
+description of the @code{face} text property in @ref{Special
+Properties}. @var{remapping} serves as the complete specification for
+the remapped face---it replaces the normal definition of @var{face},
+instead of modifying it.
If @code{face-remapping-alist} is buffer-local, its local value takes
effect only within that buffer.
modes to remap faces in the buffers they control.
@defun face-remap-add-relative face &rest specs
-This functions adds the face specifications in @var{specs} as relative
+This functions adds the face spec in @var{specs} as relative
remappings for face @var{face} in the current buffer. The remaining
arguments, @var{specs}, should form either a list of face names, or a
property list of attribute/value pairs.
@end defun
@cindex face alias
+@cindex alias, for faces
A @dfn{face alias} provides an equivalent name for a face. You can
define a face alias by giving the alias symbol the @code{face-alias}
property, with a value of the target face name. The following example
properties are intermediate between a font object and a font spec:
like a font object, and unlike a font spec, it refers to a single,
specific font. Unlike a font object, creating a font entity does not
-load the contents of that font into computer memory.
+load the contents of that font into computer memory. Emacs may open
+multiple font objects of different sizes from a single font entity
+referring to a scalable font.
@defun find-font font-spec &optional frame
This function returns a font entity that best matches the font spec
variables:
@defvar left-margin-width
-This variable specifies the width of the left margin.
-It is buffer-local in all buffers.
+This variable specifies the width of the left margin, in character
+cell (a.k.a.@: ``column'') units. It is buffer-local in all buffers.
+A value of @code{nil} means no left marginal area.
@end defvar
@defvar right-margin-width
-This variable specifies the width of the right margin.
-It is buffer-local in all buffers.
+This variable specifies the width of the right margin, in character
+cell units. It is buffer-local in all buffers. A value of @code{nil}
+means no right marginal area.
@end defvar
Setting these variables does not immediately affect the window. These
You can also set the margin widths immediately.
@defun set-window-margins window left &optional right
-This function specifies the margin widths for window @var{window}.
-The argument @var{left} controls the left margin and
-@var{right} controls the right margin (default @code{0}).
+This function specifies the margin widths for window @var{window}, in
+character cell units. The argument @var{left} controls the left
+margin, and @var{right} controls the right margin (default @code{0}).
@end defun
@defun window-margins &optional window
-This function returns the left and right margins of @var{window}
-as a cons cell of the form @code{(@var{left} . @var{right})}.
-If @var{window} is @code{nil}, the selected window is used.
+This function returns the width of the left and right margins of
+@var{window} as a cons cell of the form @w{@code{(@var{left}
+. @var{right})}}. If one of the two marginal areas does not exist,
+its width is returned as @code{nil}; if neither of the two margins exist,
+the function returns @code{(nil)}. If @var{window} is @code{nil}, the
+selected window is used.
@end defun
@node Images
* Image Descriptors:: How to specify an image for use in @code{:display}.
* XBM Images:: Special features for XBM format.
* XPM Images:: Special features for XPM format.
-* GIF Images:: Special features for GIF format.
-* 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.
-* Animated Images:: Some image formats can be animated.
+* Multi-Frame Images:: Some images contain more than one frame.
* Image Cache:: Internal mechanisms of image display.
@end menu
specifies the actual color to use for displaying that name.
@end table
-@node GIF Images
-@subsection GIF Images
-@cindex GIF
-
- For GIF images, specify image type @code{gif}.
-
-@table @code
-@item :index @var{index}
-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
-
-@node TIFF Images
-@subsection TIFF Images
-@cindex TIFF
-
- For TIFF images, specify image type @code{tiff}.
-
-@table @code
-@item :index @var{index}
-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
@subsection PostScript Images
@cindex postscript images
calculated so as to preserve the aspect ratio. If both are specified,
aspect ratio may not be preserved.
+@item :max-width, :max-height
+The @code{:max-width} and @code{:max-height} keywords are used for
+scaling if the size of the image of the image exceeds these values.
+If @code{:width} is set it will have precedence over @code{max-width},
+and if @code{:height} is set it will have precedence over
+@code{max-height}, but you can otherwise mix these keywords as you
+wish. @code{:max-width} and @code{:max-height} will always preserve
+the aspect ratio.
+
+@item :format
+ImageMagick tries to auto-detect the image type, but it isn't always
+able to. By using @code{:format-type}, we can give ImageMagick a hint
+to try to help it. It's used in conjunction with the
+@code{image-format-suffixes} variable, which provides a mapping from
+content types to file name suffixes. This is then given to
+ImageMagick as a file name hint.
+
@item :rotation
Specifies a rotation angle in degrees.
@item :index
@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.
+@xref{Multi-Frame Images}.
@end table
@node Other Image Types
background color.
@end table
- For JPEG images, specify image type @code{jpeg}.
+@noindent
+The remaining image types that Emacs can support are:
- For TIFF images, specify image type @code{tiff}.
+@table @asis
+@item GIF
+Image type @code{gif}.
+Supports the @code{:index} property. @xref{Multi-Frame Images}.
- For PNG images, specify image type @code{png}.
+@item JPEG
+Image type @code{jpeg}.
- For SVG images, specify image type @code{svg}.
+@item PNG
+Image type @code{png}.
+
+@item SVG
+Image type @code{svg}.
+
+@item TIFF
+Image type @code{tiff}.
+Supports the @code{:index} property. @xref{Multi-Frame Images}.
+@end table
@node Defining Images
@subsection Defining Images
@var{max-image-size} is subsequently changed (@pxref{Image Cache}).
@end defvar
-@node Animated Images
-@subsection Animated Images
+@node Multi-Frame Images
+@subsection Multi-Frame 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.
+@cindex image frames
+Some image files can contain more than one image. We say that there
+are multiple ``frames'' in the image. At present, Emacs supports
+multiple frames for GIF, TIFF, and certain ImageMagick formats such as
+DJVM@.
+
+The frames can be used either to represent multiple ``pages'' (this is
+usually the case with multi-frame TIFF files, for example), or to
+create animation (usually the case with multi-frame GIF files).
+
+A multi-frame image has a property @code{:index}, whose value is an
+integer (counting from 0) that specifies which frame is being displayed.
+
+@defun image-multi-frame-p image
+This function returns non-@code{nil} if @var{image} contains more than
+one frame. 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, or @code{nil}
+if the image does not specify a delay. Images that are intended to be
+animated usually specify a frame delay, whereas ones that are intended
+to be treated as multiple pages do not.
+@end defun
-@defun image-animated-p image
-This function returns non-@code{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.
+@defun image-current-frame image
+This function returns the index of the current frame number for
+@var{image}, counting from 0.
+@end defun
+
+@defun image-show-frame image n &optional nocheck
+This function switches @var{image} to frame number @var{n}. It
+replaces a frame number outside the valid range with that of the end
+of the range, unless @var{nocheck} is non-@code{nil}. If @var{image}
+does not contain a frame with the specified number, the image displays
+as a hollow box.
@end defun
@defun image-animate image &optional index limit
@end defun
@noindent Animation operates by means of a timer. Note that Emacs imposes a
-minimum frame delay of 0.01 seconds.
+minimum frame delay of 0.01 (@code{image-minimum-frame-delay}) seconds.
+If the image itself does not specify a delay, Emacs uses
+@code{image-default-frame-delay}.
@defun image-animate-timer image
This function returns the timer responsible for animating @var{image},
buffers, this function always returns @code{left-to-right}.
@end defun
+@cindex visual-order cursor motion
+ Sometimes there's a need to move point in strict visual order,
+either to the left or to the right of its current screen position.
+Emacs provides a primitive to do that.
+
+@defun move-point-visually direction
+This function moves point of the currently selected window to the
+buffer position that appears immediately to the right or to the left
+of point on the screen. If @var{direction} is positive, point will
+move one screen position to the right, otherwise it will move one
+screen position to the left. Note that, depending on the surrounding
+bidirectional context, this could potentially move point many buffer
+positions away. If invoked at the end of a screen line, the function
+moves point to the rightmost or leftmost screen position of the next
+or previous screen line, as appropriate for the value of
+@var{direction}.
+
+The function returns the new buffer position as its value.
+@end defun
+
@cindex layout on display, and bidirectional text
@cindex jumbled display of bidirectional text
@cindex concatenating bidirectional strings
HCoop / bpt / emacs.git / blobdiff