* Truncation:: Folding or wrapping long text lines.
* The Echo Area:: Where messages are displayed.
* Warnings:: Displaying warning messages for the user.
+* Progress:: Informing user about progress of a long operation.
* Invisible Text:: Hiding part of the buffer text.
* Selective Display:: Hiding part of the buffer text (the old way).
* Overlay Arrow:: Display of an arrow to indicate position.
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
* Width:: How wide a character or string is on the screen.
+* Line Height:: Controlling the height of lines.
* Faces:: A face defines a graphics style for text characters:
font, colors, etc.
* Fringes:: Controlling window fringes.
that warning is not logged.
@end defopt
+@node Progress
+@section Reporting Operation Progress
+@cindex progress reporting
+
+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.
+
+Functions listed in this section provide simple and efficient way of
+reporting operation progress. Here is a working example that does
+nothing useful:
+
+@example
+(let ((progress-reporter
+ (make-progress-reporter "Collecting some mana for Emacs..."
+ 0 500)))
+ (dotimes (k 500)
+ (sit-for 0.01)
+ (progress-reporter-update progress-reporter k))
+ (progress-reporter-done progress-reporter))
+@end example
+
+@defun make-progress-reporter message min-value max-value &optional current-value min-change min-time
+This function creates a progress reporter---the 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.
+
+The @var{message} will be displayed in the echo area, followed by
+progress percentage. @var{message} is treated as a simple string. If
+you need it to depend 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.)
+
+This function calls @code{progress-reporter-update}, so the first
+message is printed immediately.
+@end defun
+
+@defun progress-reporter-update reporter value
+This function does the main work of reporting progress of your
+operation. It print the message of @var{reporter} followed by
+progress percentage determined by @var{value}. If percentage is zero,
+then it is not printed at all.
+
+@var{reporter} must be the result of a call to
+@code{make-progress-reporter}. @var{value} specifies the current
+state of your operation and must be between @var{min-value} and
+@var{max-value} (inclusive) as passed to
+@code{make-progress-reporter}. For instance, if you scan a buffer,
+then @var{value} should be the result of a call to @code{point}.
+
+This function respects @var{min-change} and @var{min-time} as passed
+to @code{make-progress-reporter} and so does not output new messages
+on every invocation. It is thus very fast and normally you should not
+try to reduce the number of calls to it: resulting overhead will most
+likely negate your effort.
+@end defun
+
+@defun progress-reporter-force-update reporter value &optional new-message
+This function is similar to @code{progress-reporter-update} except
+that it prints a message in the echo area unconditionally.
+
+The first two arguments have the same meaning as for
+@code{progress-reporter-update}. Optional @var{new-message} allows
+you to change the message of the @var{reporter}. Since this functions
+always updates the echo area, such a change will be immediately
+presented to the user.
+@end defun
+
+@defun progress-reporter-done reporter
+This function should be called when the operation is finished. It
+prints the message of @var{reporter} followed by word ``done'' in the
+echo area.
+
+You should always call this function and not hope for
+@code{progress-reporter-update} to print ``100%.'' Firstly, it may
+never print it, there are many good reasons for this not to happen.
+Secondly, ``done'' is more explicit.
+@end defun
+
@node Invisible Text
@section Invisible Text
@end example
@end defun
+@node Line Height
+@section Line Height
+@cindex line height
+
+ The total height of each display line consists of the height of the
+contents of the line, and additional vertical line spacing below the
+display row.
+
+ The height of the line contents is normally determined from the
+maximum height of any character or image on that display line,
+including the final newline if there is one. (A line that is
+continued doesn't include a final newline.) In the most common case,
+the line height equals the height of the default frame font.
+
+ There are several ways to explicitly control or change the line
+height, either by specifying an absolute height for the display line,
+or by adding additional vertical space below one or all lines.
+
+@kindex line-height @r{(text property)}
+ A newline can have a @code{line-height} text or overlay property
+that controls the total height of the display line ending in that
+newline.
+
+ If the property value is a list @code{(@var{height} @var{total})},
+then @var{height} is used as the actual property value for the
+@code{line-height}, and @var{total} specifies the total displayed
+height of the line, so the line spacing added below the line equals
+the @var{total} height minus the actual line height. In this case,
+the other ways to specify the line spacing are ignored.
+
+ If the property value is @code{t}, the displayed height of the
+line is exactly what its contents demand; no line-spacing is added.
+This case is useful for tiling small images or image slices without
+adding blank areas between the images.
+
+ If the property value is not @code{t}, it is a height spec. A height
+spec stands for a numeric height value; this heigh spec specifies the
+actual line height, @var{line-height}. There are several ways to
+write a height spec; here's how each of them translates into a numeric
+height:
+
+@table @code
+@item @var{integer}
+If the height spec is a positive integer, the height value is that integer.
+@item @var{float}
+If the height spec is a float, @var{float}, the numeric height value
+is @var{float} times the frame's default line height.
+@item (@var{face} . @var{ratio})
+If the height spec is a cons of the format shown, the numeric height
+is @var{ratio} times the height of face @var{face}. @var{ratio} can
+be any type of number, or @code{nil} which means a ratio of 1.
+If @var{face} is @code{t}, it refers to the current face.
+@item (@code{nil} . @var{ratio})
+If the height spec is a cons of the format shown, the numeric height
+is @var{ratio} times the height of the contents of the line.
+@end table
+
+ Thus, any valid non-@code{t} property value specifies a height in pixels,
+@var{line-height}, one way or another. If the line contents' height
+is less than @var{line-height}, Emacs adds extra vertical space above
+the line to achieve the total height @var{line-height}. Otherwise,
+@var{line-height} has no effect.
+
+ If you don't specify the @code{line-height} propery, the line's
+height consists of the contents' height plus the line spacing.
+There are several ways to specify the line spacing for different
+parts of Emacs text.
+
+@vindex default-line-spacing
+ You can specify the line spacing for all lines in a frame with the
+@code{line-spacing} frame parameter, @xref{Window Frame Parameters}.
+However, if the variable @code{default-line-spacing} is
+non-@code{nil}, it overrides the frame's @code{line-spacing}
+parameter. An integer value specifies the number of pixels put below
+lines on window systems. A floating point number specifies the
+spacing relative to the frame's default line height.
+
+@vindex line-spacing
+ You can specify the line spacing for all lines in a buffer via the
+buffer-local @code{line-spacing} variable. An integer value specifies
+the number of pixels put below lines on window systems. A floating
+point number specifies the spacing relative to the default frame line
+height. This overrides line spacings specified for the frame.
+
+@kindex line-spacing @r{(text property)}
+ Finally, a newline can have a @code{line-spacing} text or overlay
+property that controls the height of the display line ending with that
+newline. The property value overrides the default frame line spacing
+and the buffer local @code{line-spacing} variable.
+
+ One way or another, these mechanisms specify a Lisp value for the
+spacing of each line. The value is a height spec, and it translates
+into a Lisp value as described above. However, in this case the
+numeric height value specifies the line spacing, rather than the line
+height.
+
@node Faces
@section Faces
@cindex faces
* Defining Faces:: How to define a face with @code{defface}.
* Face Attributes:: What is in a face?
* Attribute Functions:: Functions to examine and set face attributes.
-* Merging Faces:: How Emacs combines the faces specified for a character.
+* Displaying Faces:: How Emacs combines the faces specified for a character.
* Font Selection:: Finding the best available font for a face.
* Face Functions:: How to define and examine faces.
* Auto Faces:: Hook for automatic face assignment.
attributes}. This table lists all the face attributes, and what they
mean. Note that in general, more than one face can be specified for a
given piece of text; when that happens, the attributes of all the faces
-are merged to specify how to display the text. @xref{Merging Faces}.
+are merged to specify how to display the text. @xref{Displaying Faces}.
In Emacs 21, any attribute in a face can have the value
@code{unspecified}. This means the face doesn't specify that attribute.
the terminal supports the feature.
@item :foreground
-Foreground color, a string.
+Foreground color, a string. The value can be a system-defined color
+name, or a hexadecimal color specification of the form
+@samp{#@var{rr}@var{gg}@var{bb}}. (@samp{#000000} is black,
+@samp{#ff0000} is red, @samp{#00ff00} is green, @samp{#0000ff} is
+blue, and @samp{#ffffff} is white.)
@item :background
-Background color, a string.
+Background color, a string, like the foreground color.
@item :inverse-video
Whether or not characters should be displayed in inverse video. The
This function returns the @code{:inverse-video} attribute of face @var{face}.
@end defun
-@node Merging Faces
-@subsection Merging Faces for Display
+@node Displaying Faces
+@subsection Displaying Faces
Here are the ways to specify which faces to use for display of text:
fringe (on a graphic display) to indicate truncated or continued
lines, buffer boundaries, overlay arrow, etc. The fringe bitmaps are
shared by all frames and windows. You can redefine the built-in
-fringe bitmaps, and you can define new fringe bitmaps. However, Emacs
-can handle only 255 different fringe bitmaps.
+fringe bitmaps, and you can define new fringe bitmaps.
The way to display a bitmap in the left or right fringes for a given
line in a window is by specifying the @code{display} property for one
of the characters that appears in it. Use a display specification of
the form @code{(left-fringe @var{bitmap} [@var{face}])} or
@code{(right-fringe @var{bitmap} [@var{face}])} (@pxref{Display
-Property}). Here, @var{bitmap} is an integer identifying the bitmap
+Property}). Here, @var{bitmap} is a symbol identifying the bitmap
you want, and @var{face} (which is optional) is the name of the face
whose colors should be used for displaying the bitmap.
-@c ??? Shouldn't the symbol name be used?
These are the symbols identify the standard fringe bitmaps.
-Evaluate @code{(require 'fringe)} to define them. Each symbol's
-value is an integer that identifies the corresponding bitmap.
+Evaluate @code{(require 'fringe)} to define them. Fringe bitmap
+symbols have their own name space.
@table @asis
@item Truncation and continuation line bitmaps:
-@code{left-truncation-fringe-bitmap},
-@code{right-truncation-fringe-bitmap},
-@code{continued-line-fringe-bitmap},
-@code{continuation-line-fringe-bitmap}.
+@code{left-truncation}, @code{right-truncation},
+@code{continued-line}, @code{continuation-line}.
@item Buffer indication bitmaps:
-@code{up-arrow-fringe-bitmap},
-@code{down-arrow-fringe-bitmap},
-@code{top-left-angle-fringe-bitmap},
-@code{top-right-angle-fringe-bitmap},
-@code{bottom-left-angle-fringe-bitmap},
-@code{bottom-right-angle-fringe-bitmap},
-@code{left-bracket-fringe-bitmap},
-@code{right-bracket-fringe-bitmap}.
+@code{up-arrow}, @code{down-arrow},
+@code{top-left-angle}, @code{top-right-angle},
+@code{bottom-left-angle}, @code{bottom-right-angle},
+@code{left-bracket}, @code{right-bracket}.
@item Empty line indication bitmap:
-@code{empty-line-fringe-bitmap}.
+@code{empty-line}.
@item Overlay arrow bitmap:
-@code{overlay-arrow-fringe-bitmap}.
+@code{overlay-arrow}.
@item Bitmaps for displaying the cursor in right fringe:
-@code{filled-box-cursor-fringe-bitmap},
-@code{hollow-box-cursor-fringe-bitmap},
-@code{hollow-square-fringe-bitmap}, @code{bar-cursor-fringe-bitmap},
-@code{hbar-cursor-fringe-bitmap}.
-
-@item Value indicating that no fringe bitmap is present:
-@code{no-fringe-bitmap}.
-@c ??? I don't understand what that means.
-@c ??? Where would you find that value?
-
-@item Value indicating a reference to an undefined bitmap:
-@code{undef-fringe-bitmap}.
-@c ??? I don't understand what that means.
-@c ??? Where would you find that value?
+@code{filled-box-cursor}, @code{hollow-box-cursor}, @code{hollow-square},
+@code{bar-cursor}, @code{hbar-cursor}.
@end table
@defun fringe-bitmaps-at-pos &optional pos window
This function returns the fringe bitmaps of the display line
containing position @var{pos} in window @var{window}. The return
-value has the form @code{(@var{left} . @var{right})}, where @var{left}
-is a list of fringe bitmap numbers for left fringe, and @var{right} is
-similar for the right fringe. These bitmap numbers are usually values
-of symbols such as the ones listed above.
-
-@c ??? Why not return a list of symbols that identify the bitmaps?
-@c ??? This is Lisp, not C.
+value has the form @code{(@var{left} @var{right} @var{ov})}, where @var{left}
+is the symbol for the fringe bitmap in the left fringe (or @code{nil}
+if no bitmap), @var{right} is similar for the right fringe, and @var{ov}
+is non-@code{nil} if there is an overlay arrow in the left fringe.
The value is @code{nil} if @var{pos} is not visible in @var{window}.
If @var{window} is @code{nil}, that stands for the selected window.
@node Customizing Bitmaps
@section Customizing Fringe Bitmaps
-@c ??? Why not pass a symbol as the first argument
-@c ??? and define that symbol. It would be cleaner.
-
-@defun define-fringe-bitmap bits &optional height width align bitmap
-This function defines a new fringe bitmap, or replaces an existing
-bitmap.
+@defun define-fringe-bitmap bitmap bits &optional height width align
+This function defines the symbol @var{bitmap} as a new fringe bitmap,
+or replaces an existing bitmap with that name.
The argument @var{bits} specifies the image to use. It should be
either a string or a vector of integers, where each element (an
integer) corresponds to one row of the bitmap. Each bit of an integer
-corresponds to one pixel of the bitmap.
-@c ??? Is the low bit the leftmost or the rightmost bit?
+corresponds to one pixel of the bitmap, where the low bit corresponds
+to the rightmost pixel of the bitmap.
The height is normally the length of @var{bits}. However, you
can specify a different height with non-@code{nil} @var{height}. The width
@code{bits} should be repeated enough times to reach the specified
height.
-The argument @var{bitmap} specifies an existing bitmap to redefine.
-You should pass the value of the symbol that identifies the bitmap.
-
The return value on success is an integer identifying the new bitmap.
You should save that integer in a variable so it can be used to select
-this bitmap. The value can also be @code{nil} of there are no more
-free bitmap slots.
-@c ??? Why not signal an error? That would be cleaner.
+this bitmap.
+
+This function signals an error if there are no more free bitmap slots.
@end defun
@defun destroy-fringe-bitmap bitmap
specify only the foreground color.
@end defun
-@defvar indicate-buffer-boundaries
-This buffer-local variable controls how the buffer boundaries and
-window scrolling are indicated in the window fringes.
-
-Emacs can indicate the buffer boundaries---that is, the first and last
-line in the buffer---with angle icons when they appear on the screen.
-In addition, Emacs can display an up-arrow in the fringe to show
-that there is text above the screen, and a down-arrow to show
-there is text below the screen.
-
-There are four kinds of basic values:
-
-@table @asis
-@item @code{nil}
-Don't display the icons.
-@item @code{left}
-Display them in the left fringe.
-@item @code{right}
-Display them in the right fringe.
-@item @var{anything-else}
-Display the icon at the top of the window top in the left fringe, and other
-in the right fringe.
-@end table
-
-If value is a cons @code{(@var{angles} . @var{arrows})}, @var{angles}
-controls the angle icons, and @var{arrows} controls the arrows. Both
-@var{angles} and @var{arrows} work according to the table above.
-Thus, @code{(t . right)} places the top angle icon in the left
-fringe, the bottom angle icon in the right fringe, and both arrows in
-the right fringe.
-@end defvar
-
-@defvar default-indicate-buffer-boundaries
-The value of this variable is the default value for
-@code{indicate-buffer-boundaries} in buffers that do not override it.
-@end defvar
-
@node Scroll Bars
@section Scroll Bars
@code{scroll-bar-width} specifies how wide they are (@code{nil}
meaning the default). @xref{Window Frame Parameters}.
-You can also control this for individual windows. Call the function
+@vindex vertical-scroll-bar
+ You can enable or disable scroll bars for a particular buffer,
+by setting the variable @code{vertical-scroll-bar}. This variable
+automatically becomes buffer-local when set. The possible values are
+@code{left}, @code{right}, @code{t}, which means to use the
+frame's default, and @code{nil} for no scroll bar.
+
+ You can also control this for individual windows. Call the function
@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
window take note of the new values by calling @code{set-window-buffer}
specifying the same buffer that is already displayed.
+@defvar scroll-bar-mode
+This variable, always local in all buffers, controls whether and where
+to put scroll bars in windows displaying the buffer. The possible values
+are @code{nil} for no scroll bar, @code{left} to put a scroll bar on
+the left, and @code{right} to put a scroll bar on the right.
+@end defvar
+
+@defvar scroll-bar-width
+This variable, always local in all buffers, specifies the width of the
+buffer's scroll bars, measured in pixels. A value of @code{nil} means
+to use the value specified by the frame.
+@end defvar
+
@node Pointer Shape
@section Pointer Shape
@example
@group
- @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | IMAGE | @var{form}
+ @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form}
@var{num} ::= @var{integer} | @var{float} | @var{symbol}
@var{unit} ::= in | mm | cm | width | height
@var{elem} ::= left-fringe | right-fringe | left-margin | right-margin
The @code{in}, @code{mm}, and @code{cm} units specify the number of
pixels per inch, millimeter, and centimeter, respectively. The
@code{width} and @code{height} units correspond to the default width
-and height of the current face. An image specification @code{IMAGE}
+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},
A value of the form @code{(@var{num} . @var{expr})} stands
multiplying the values of @var{num} and @var{expr}. For example,
@code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 .
-IMAGE)} specifies half the width (or height) of the specified image.
+@var{image})} specifies half the width (or height) of the specified image.
The form @code{(+ @var{expr} ...)} adds up the value of the
expressions. The form @code{(- @var{expr} ...)} negates or subtracts
@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{mouse-2} to invoke the button.
+in the variable @code{button-map}, which defines @key{RET},
+@key{mouse-1} (if @var{mouse-1-click-follows-link} is set),
+and @key{mouse-2} to invoke the button.
@item type
@kindex type @r{(button property)}
A string displayed by the Emacs tool-tip help system; by default,
@code{"mouse-2, RET: Push this button"}.
+@item follow-link
+@kindex follow-link @r{(button property)}
+The follow-link property, defining how a @key{mouse-1} click behaves
+on this button, @xref{Enabling Mouse-1 to Follow Links}.
@item button
@kindex button @r{(button property)}
All buttons have a non-@code{nil} @code{button} property, which may be useful
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}
+a button, and is bound by default in the button itself to @key{RET},
+to @key{mouse-1} (if @var{mouse-1-click-follows-link} is set),
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
buffers that do not override it. @xref{Default Value}.
@end defvar
+@defopt tab-width
+The value of this variable is the spacing between tab stops used for
+displaying tab characters in Emacs buffers. The value is in units of
+columns, and the default is 8. Note that this feature is completely
+independent of the user-settable tab stops used by the command
+@code{tab-to-tab-stop}. @xref{Indent Tabs}.
+@end defopt
+
@defopt indicate-empty-lines
@tindex indicate-empty-lines
@cindex fringes, and empty line indication
support it (window systems). @xref{Fringes}.
@end defopt
-@defopt tab-width
-The value of this variable is the spacing between tab stops used for
-displaying tab characters in Emacs buffers. The value is in units of
-columns, and the default is 8. Note that this feature is completely
-independent of the user-settable tab stops used by the command
-@code{tab-to-tab-stop}. @xref{Indent Tabs}.
-@end defopt
+@defvar indicate-buffer-boundaries
+This buffer-local variable controls how the buffer boundaries and
+window scrolling are indicated in the window fringes.
+
+Emacs can indicate the buffer boundaries---that is, the first and last
+line in the buffer---with angle icons when they appear on the screen.
+In addition, Emacs can display an up-arrow in the fringe to show
+that there is text above the screen, and a down-arrow to show
+there is text below the screen.
+
+There are four kinds of basic values:
+
+@table @asis
+@item @code{nil}
+Don't display the icons.
+@item @code{left}
+Display them in the left fringe.
+@item @code{right}
+Display them in the right fringe.
+@item @var{anything-else}
+Display the icon at the top of the window top in the left fringe, and other
+in the right fringe.
+@end table
+
+If value is a cons @code{(@var{angles} . @var{arrows})}, @var{angles}
+controls the angle icons, and @var{arrows} controls the arrows. Both
+@var{angles} and @var{arrows} work according to the table above.
+Thus, @code{(t . right)} places the top angle icon in the left
+fringe, the bottom angle icon in the right fringe, and both arrows in
+the right fringe.
+@end defvar
+
+@defvar default-indicate-buffer-boundaries
+The value of this variable is the default value for
+@code{indicate-buffer-boundaries} in buffers that do not override it.
+@end defvar
@node Display Tables
@section Display Tables
@item 1
The glyph for the end of a continued line (the default is @samp{\}).
Newer Emacs versions, on some platforms, display curved arrows to
-indicate truncation---the display table has no effect in these
+indicate continuation---the display table has no effect in these
situations.
@item 2
The glyph for indicating a character displayed as an octal character