@end defvar
@defvar warning-prefix-function
-If non-@code{nil}, te value is a function to generate prefix text for
+If non-@code{nil}, the value is a function to generate prefix text for
warnings. Programs can bind the variable to a suitable function.
@code{display-warning} calls this function with the warnings buffer
current, and the function can insert text in it. That text becomes
The function is called with two arguments, the severity level and its
entry in @code{warning-levels}. It should return a list to use as the
entry (this value need not be an actual member of
-@code{warning-levels}). By constructing this value, the function to
+@code{warning-levels}). By constructing this value, the function can
change the severity of the warning, or specify different handling for
a given severity level.
Programs can bind this variable to @code{t} to say that the next
warning should begin a series. When several warnings form a series,
that means to leave point on the first warning of the series, rather
-than keep move it for each warning so that it appears on the last one.
+than keep moving it for each warning so that it appears on the last one.
The series ends when the local binding is unbound and
@code{warning-series} becomes @code{nil} again.
@defvar buffer-invisibility-spec
This variable specifies which kinds of @code{invisible} properties
-actually make a character invisible.
+actually make a character invisible. Setting this variable makes it
+buffer-local.
@table @asis
@item @code{t}
@end defun
@defun remove-from-invisibility-spec element
-This removeds the element @var{element} from
+This removes the element @var{element} from
@code{buffer-invisibility-spec}. This does nothing if @var{element}
is not in the list.
@end defun
beginning and end. It also has properties that you can examine and set;
these affect the display of the text within the overlay.
+An overlays 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,
+you can specify whether text inserted at the beginning should be
+inside the overlay or outside, and likewise for the end of the overlay.
+
@menu
* Overlay Properties:: How to read and set properties.
What properties do to the screen display.
@item evaporate
@kindex evaporate @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
-if it becomes empty (i.e., if its length becomes zero). However,
-if the overlay is @emph{already} empty, @code{evaporate} does not
-delete it.
+if it becomes empty (i.e., if its length becomes zero). If you give
+an empty overlay a non-@code{nil} @code{evaporate} property, that deletes
+it immediately.
@item local-map
@cindex keymap of character (and overlays)
The arguments @var{front-advance} and @var{rear-advance} specify the
insertion type for the start of the overlay and for the end of the
-overlay, respectively. @xref{Marker Insertion Types}.
+overlay, respectively. @xref{Marker Insertion Types}. If
+@var{front-advance} is non-@code{nil}, text inserted at the beginning
+of the overlay is excluded from the overlay. If @var{read-advance} is
+non-@code{nil}, text inserted at the beginning of the overlay is
+included in the overlay.
@end defun
@defun overlay-start overlay
@item background
The kind of background---either @code{light} or @code{dark}.
+@item min-colors
+An integer that represents the minimum number of colors the frame should
+support, it is compared with the result of @code{display-color-cells}.
+
@item supports
Whether or not the frame can display the face attributes given in
@var{value}@dots{} (@pxref{Face Attributes}). See the documentation
@example
@group
-(defface region
- `((((type tty) (class color))
- (:background "blue" :foreground "white"))
+ '((((class color) (min-colors 88) (background dark))
+ :background "blue3")
@end group
+ (((class color) (min-colors 88) (background light))
+ :background "lightgoldenrod2")
+ (((class color) (min-colors 16) (background dark))
+ :background "blue3")
+ (((class color) (min-colors 16) (background light))
+ :background "lightgoldenrod2")
+ (((class color) (min-colors 8))
+ :background "blue" :foreground "white")
(((type tty) (class mono))
- (:inverse-video t))
- (((class color) (background dark))
- (:background "blue"))
- (((class color) (background light))
- (:background "lightblue"))
- (t (:background "gray")))
+ :inverse-video t)
+ (t :background "gray"))
@group
"Basic face for highlighting the region."
:group 'basic-faces)
@tindex face-attribute-relative-p
@defun face-attribute-relative-p attribute value
-This function returns non-@code{nil} if @var{value}, when used as a
+This function returns non-@code{nil} if @var{value}, when used as
the value of the face attribute @var{attribute}, is relative (that is,
if it modifies an underlying or inherited value of @var{attribute}).
@end defun
These functions return the foreground color (or background color,
respectively) of face @var{face}, as a string.
-If @var{inherit} is nil, only a color directly defined by the face is
-returned. If @var{inherit} is non-nil, any faces specified by its
+If @var{inherit} is @code{nil}, only a color 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 color is found. To ensure that the return value is always
@end defun
@defun face-differs-from-default-p face &optional frame
-This returns @code{t} if the face @var{face} displays differently from
-the default face. A face is considered to be ``the same'' as the
-default face if each attribute is either the same as that of the default
-face, or unspecified (meaning to inherit from the default).
+This returns non-@code{nil} if the face @var{face} displays
+differently from the default face.
@end defun
@node Auto Faces
use the font name @var{fontname} for the character @var{character}.
If @var{name} is @code{nil}, this function modifies the default
-fontset of which short name is @samp{fontset-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 non-generic characters. In that case, use
The @dfn{fringes} of a window are thin vertical strips down the
sides that are used for displaying bitmaps that indicate truncation,
-continuation, and horizontal scrolling, the overlay arrow. The
+continuation, horizontal scrolling, and the overlay arrow. The
fringes normally appear between the display margins and the window
text, but you can put them outside the display margins for a specific
buffer by setting @code{fringes-outside-margins} buffer-locally to a
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 in a window again.
+you can call @code{set-window-buffer} to display it once again in the
+same window, to make the changes take effect.
@defun set-window-fringes window left &optional right outside-margins
-This function sets the fringe widthes of window @var{window}.
-If window is @code{nil}, that stands for the selected window.
+This function sets the fringe widths of window @var{window}.
+If @var{window} is @code{nil}, the selected window is used.
The argument @var{left} specifies the width in pixels of the left
fringe, and likewise @var{right} for the right fringe. A value of
should appear outside of the display margins.
@end defun
-@defun window-fringes window
+@defun window-fringes &optional window
This function returns information about the fringes of a window
-@var{window}. The value has the form @code{(@var{left-width}
+@var{window}. If @var{window} is omitted or @code{nil}, the selected
+window is used. The value has the form @code{(@var{left-width}
@var{right-width} @var{frames-outside-margins})}.
@end defun
@code{set-window-scroll-bars} to specify what to do for a specific window:
@defun set-window-scroll-bars window width &optional vertical-type horizontal-type
-Set width and type of scroll bars of window @var{window}. (If
-@var{window} is @code{nil}, this applies to the selected window.)
+Set width and type of scroll bars of window @var{window}.
+If @var{window} is @code{nil}, the selected window is used.
@var{width} specifies the scroll bar width in pixels (@code{nil} means
use whatever is specified for width for the frame).
@var{vertical-type} specifies whether to have a vertical scroll bar
@defun window-scroll-bars &optional window
Report the width and type of scroll bars specified for @var{window}.
-If @var{window} is omitted or @code{nil}, it defaults to the currently
-selected window. The value is a list of the form @code{(@var{width}
+If @var{window} is omitted or @code{nil}, the selected window is used.
+The value is a list of the form @code{(@var{width}
@var{cols} @var{vertical-type} @var{horizontal-type})}. The value
@var{width} is the value that was specified for the width (which may
be @code{nil}); @var{cols} is the number of columns that the scroll
@code{display} property, this feature is available starting in Emacs 21.
Emacs can display a number of different image formats; some of them
-are supported only if particular support libraries are installed on your
-machine. The supported image formats include XBM, XPM (needing the
+are supported only if particular support libraries are installed on
+your machine. In some environments, Emacs allows loading 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 posible to add new image formats).
+
+ The supported image formats include XBM, XPM (needing the
libraries @code{libXpm} version 3.4k and @code{libz}), GIF (needing
@code{libungif} 4.1.0), Postscript, PBM, JPEG (needing the
@code{libjpeg} library version v6a), TIFF (needing @code{libtiff} v3.4),
@defvar image-types
This variable contains a list of those image type symbols that are
-supported in the current configuration.
+potentially supported in the current configuration.
+@emph{Potentially} here means that Emacs knows about the image types,
+not necessarily that they can be loaded (they could depend on
+unavailable dynamic libraries, for example).
+
+To know which image types are really available, use
+@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
+@findex image-type-available-p
+
+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
+Emacs. @var{type} should be one of the types contained in
+@code{image-types}.
+
+For image types whose support libraries are statically linked, this
+function always returns @code{t}; for other image types, it returns
+@code{t} if the dynamic library could be loaded, @code{nil} otherwise.
+@end defun
+
@menu
* Image Descriptors:: How to specify an image for use in @code{:display}.
* XBM Images:: Special features for XBM format.
For GIF images, specify image type @code{gif}. Because of the patents
in the US covering the LZW algorithm, the continued use of GIF format is
a problem for the whole Internet; to end this problem, it is a good idea
-for everyone, even outside the US, to stop using GIFS right away
+for everyone, even outside the US, to stop using GIFs right away
(@uref{http://www.burnallgifs.org/}). But if you still want to use
them, Emacs can display them.
@node Buttons
@section Buttons
+@cindex buttons
@cindex buttons in buffers
@cindex clickable buttons in buffers
The @emph{button} package defines functions for inserting and
manipulating clickable (with the mouse, or via keyboard commands)
-buttons in Emacs buffers, such as might be used for help hyperlinks,
-etc. Emacs uses buttons for the hyperlinks in help text and the like.
+buttons in Emacs buffers, such as might be used for help hyper-links,
+etc. Emacs uses buttons for the hyper-links in help text and the like.
A button is essentially a set of properties attached (via text
-properties or overlays) to a region of text in an emacs buffer, which
+properties or overlays) to a region of text in an Emacs buffer, which
are called its button properties. @xref{Button Properties}.
One of the these properties (@code{action}) is a function, which will
The invoked function may then examine the button and use its other
properties as desired.
-In some ways the emacs button package duplicates functionality offered
+In some ways the Emacs button package duplicates functionality offered
by the widget package (@pxref{Top, , Introduction, widget, The Emacs
Widget Library}), but the button package has the advantage that it is
much faster, much smaller, and much simpler to use (for elisp
@menu
* Button Properties:: Button properties with special meanings.
* Button Types:: Defining common properties for classes of buttons.
-* Making buttons:: Adding buttons to emacs buffers.
+* Making Buttons:: Adding buttons to Emacs buffers.
* Manipulating Buttons:: Getting and setting properties of buttons.
* Button Buffer Commands:: Buffer-wide commands and bindings for buttons.
* Manipulating Button Types::
@table @code
@item action
+@kindex action @r{(button property)}
The function to call when the user invokes the button, which is passed
the single argument @var{button}. By default this is @code{ignore},
which does nothing.
@item mouse-action
+@kindex mouse-action @r{(button property)}
This is similar to @code{action}, and when present, will be used
instead of @code{action} for button invocations resulting from
mouse-clicks (instead of the user hitting @key{RET}). If not
present, mouse-clicks use @code{action} instead.
@item face
-This is an emacs face controlling how buttons of this type are
+@kindex face @r{(button property)}
+This is an Emacs face controlling how buttons of this type are
displayed; by default this is the @code{button} face.
@item mouse-face
+@kindex mouse-face @r{(button property)}
This is an additional face which controls appearance during
mouse-overs (merged with the usual button face); by default this is
-the usual emacs @code{highlight} face.
+the usual Emacs @code{highlight} face.
@item keymap
+@kindex keymap @r{(button property)}
The button's keymap, defining bindings active within the button
region. By default this is the usual button region keymap, stored
in the variable @code{button-map}, which defines @key{RET} and
-@key{down-mouse-1} to invoke the button.
+@key{mouse-2} to invoke the button.
@item type
+@kindex type @r{(button property)}
The button-type of the button. When creating a button, this is
usually specified using the @code{:type} keyword argument.
@xref{Button Types}.
@item help-echo
-A string displayed by the emacs tooltip help system; by default,
+@kindex help-index @r{(button property)}
+A string displayed by the Emacs tool-tip help system; by default,
@code{"mouse-2, RET: Push this button"}.
@item button
+@kindex button @r{(button property)}
All buttons have a non-@code{nil} @code{button} property, which may be useful
in finding regions of text that comprise buttons (which is what the
standard button functions do).
@cindex button types
Every button has a button @emph{type}, which defines default values
-for the button's properties; button types are arranged in a hierarchy,
-with specialized types inheriting from more general types, so that
-it's easy to define special-purpose types of buttons for specific
-tasks.
+for the button's properties. Button types are arranged in a
+hierarchy, with specialized types inheriting from more general types,
+so that it's easy to define special-purpose types of buttons for
+specific tasks.
@defun define-button-type name &rest properties
@tindex define-button-type
@end defun
Using @code{define-button-type} to define default properties for
-buttons is not necessary, but it is is encouraged, since doing so
-usually makes the resulting code clearer and more efficient.
+buttons is not necessary---buttons without any specified type use the
+built-in button-type @code{button}---but it is is encouraged, since
+doing so usually makes the resulting code clearer and more efficient.
-@node Making buttons
-@subsection Making buttons
+@node Making Buttons
+@subsection Making Buttons
@cindex making buttons
Buttons are associated with a region of text, using an overlay or
text-properties to hold button-specific information, all of which are
initialized from the button's type (which defaults to the built-in
-button type @code{button}). Like all emacs text, the appearance of
+button type @code{button}). Like all Emacs text, the appearance of
the button is governed by the @code{face} property; by default (via
the @code{face} property inherited from the @code{button} button-type)
this is a simple underline, like a typical web-page link.
Insert a button with the label @var{label}.
@end defun
-The following functions are similar, but use emacs text-properties
+The following functions are similar, but use Emacs text-properties
(@pxref{Text Properties}) to hold the button properties, making the
button actually part of the text instead of being a property of the
buffer (using text-properties is usually faster than using overlays,
@tindex button-activate
Call @var{button}'s @code{action} property (i.e., invoke it). If
@var{use-mouse-action} is non-@code{nil}, try to invoke the button's
-@code{mouse-action} property instead of @code{action}, but if the
-button has no @code{mouse-action} property, use @code{action} as
-normal.
+@code{mouse-action} property instead of @code{action}; if the button
+has no @code{mouse-action} property, use @code{action} as normal.
@end defun
@defun button-label button
@cindex button buffer commands
These are commands and functions for locating and operating on
-buttons in an emacs buffer.
+buttons in an Emacs buffer.
@code{push-button} is the command that a user uses to actually `push'
a button, and is bound by default in the button itself to @key{RET}
-and to @key{mouse-down-1} using a region-specific keymap. Commands
+and to @key{mouse-2} using a region-specific keymap. Commands
that are useful outside the buttons itself, such as
@code{forward-button} and @code{backward-button} are additionally
available in the keymap stored in @code{button-buffer-map}; a mode
@tindex push-button
Perform the action specified by a button at location @var{pos}.
@var{pos} may be either a buffer position or a mouse-event. If
-@var{use-mouse-action} is non-@code{nil}, try to invoke the button's
-@code{mouse-action} property instead of @code{action}, but if the
-button has no @code{mouse-action} property, use @code{action} as
-normal. @var{pos} defaults to point, except when `push-button' is
-invoked interactively as the result of a mouse-event, in which case,
-the mouse event is used. If there's no button at @var{pos}, do
+@var{use-mouse-action} is non-@code{nil}, or @var{pos} is a
+mouse-event (@pxref{Mouse Events}), try to invoke the button's
+@code{mouse-action} property instead of @code{action}; if the button
+has no @code{mouse-action} property, use @code{action} as normal.
+@var{pos} defaults to point, except when @code{push-button} is invoked
+interactively as the result of a mouse-event, in which case, the mouse
+event's position is used. If there's no button at @var{pos}, do
nothing and return @code{nil}, otherwise return @code{t}.
@end deffn
button at point. If @var{wrap} is non-@code{nil}, moving past either
end of the buffer continues from the other end. If
@var{display-message} is non-@code{nil}, the button's help-echo string
-is displayed. Any button with a non-@code{nil} `skip' property is
-skipped over. Returns the button found.
+is displayed. Any button with a non-@code{nil} @code{skip} property
+is skipped over. Returns the button found.
@end deffn
@deffn Command backward-button n &optional wrap display-message
button at point. If @var{wrap} is non-@code{nil}, moving past either
end of the buffer continues from the other end. If
@var{display-message} is non-@code{nil}, the button's help-echo string
-is displayed. Any button with a non-@code{nil} `skip' property is
-skipped over. Returns the button found.
+is displayed. Any button with a non-@code{nil} @code{skip} property
+is skipped over. Returns the button found.
@end deffn
@defun next-button pos &optional count-current
HCoop / bpt / emacs.git / blobdiff