@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001, 2002
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2000, 2001,
+@c 2002, 2005 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
@node Display, Calendar, Processes, Top
Secondly, ``done'' is more explicit.
@end defun
+@defmac dotimes-with-progress-reporter (var count [result]) message body...
+This is a convenience macro that works the same way as @code{dotimes}
+does, but also reports loop progress using the functions described
+above. It allows you to save some typing.
+
+You can rewrite the example in the beginning of this node using
+this macro this way:
+
+@example
+(dotimes-with-progress-reporter
+ (k 500)
+ "Collecting some mana for Emacs..."
+ (sit-for 0.01))
+@end example
+@end defmac
+
@node Invisible Text
@section Invisible Text
@xref{Display Property}.
@item help-echo
-@kindex help-echo @r{(text property)}
+@kindex help-echo @r{(overlay property)}
If an overlay has a @code{help-echo} property, then when you move the
mouse onto the text in the overlay, Emacs displays a help string in the
echo area, or in the tooltip window. For details see @ref{Text
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 other ways to change the line height, either by
-specifying an absolute height for the display line, or by adding
-additional vertical space below each line.
+ 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.
-We will call the property value @var{line-height}.
+ 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:
- If @var{line-height} property is 0, the height of the line is
-determined solely from its contents; nothing is added. Any
-@code{line-spacing} property on this newline is ignored. This case is
-useful for tiling small images or image slices without adding blank
-areas between the images.
-
- If @var{line-height} property is a positive integer, the value
-specifies the minimum line height in pixels. The line's ascent height
-is increased as necessary to achieve the specified 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
- If @var{line-height} property is a floating point number, the
-minimum line height is the product of @var{line-height} and the
-default frame line height.
+ 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 @var{line-height} property is a cons @code{(@var{ratio} . @var{face})},
-the minimum line height is calculated as @var{ratio} times the height
-of face @var{face}. The @var{ratio} is an integer or a floating point
-number. If @var{face} is @code{t}, it refers to the current face.
+ 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 additional 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
+ 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 default frame line height.
+spacing relative to the frame's default line height.
@vindex line-spacing
- You can specify additional 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.
+ 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. We will call the
-property value @var{line-spacing}.
-
- If the @var{line-spacing} value is a positive integer, the value
-specifies additional vertical space, below the display line, in
-pixels.
-
- If the @var{line-spacing} value is a floating point number or cons,
-the additional vertical space is the product of @var{line-spacing} and
-the default frame line height.
+and the buffer local @code{line-spacing} variable.
- If the @var{line-spacing} value is a cons @code{(total . @var{spacing})}
-where @var{spacing} is any of the forms described above, the value of
-@var{spacing} specifies the total displayed height of the line,
-regardless of the height of the characters in it. This is equivalent
-to using the @code{line-height} property.
+ 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
* 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:
The functions @code{create-image}, @code{defimage} and
@code{find-image} provide convenient ways to create image descriptors.
-@defun create-image file &optional type &rest props
+@defun create-image file-or-data &optional type data-p &rest props
@tindex create-image
This function creates and returns an image descriptor which uses the
-data in @var{file}.
+data in @var{file-or-data}. @var{file-or-data} can be a file name or
+a string containing the image data; @var{data-p} should be @code{nil}
+for the former case, non-@code{nil} for the latter case.
The optional argument @var{type} is a symbol specifying the image type.
If @var{type} is omitted or @code{nil}, @code{create-image} tries to
properties---for example,
@example
-(create-image "foo.xpm" 'xpm :heuristic-mask t)
+(create-image "foo.xpm" 'xpm nil :heuristic-mask t)
@end example
The function returns @code{nil} if images of this type are not
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{Links and Mouse-1}.
+
@item button
@kindex button @r{(button property)}
All buttons have a non-@code{nil} @code{button} property, which may be useful
which uses buttons may want to use @code{button-buffer-map} as a
parent keymap for its keymap.
+If the button has a non-@code{nil} @code{follow-link} property, and
+@var{mouse-1-click-follows-link} is set, a @key{Mouse-1} click will
+also activate the @code{push-button} command.
+
@deffn Command push-button &optional pos use-mouse-action
@tindex push-button
Perform the action specified by a button at location @var{pos}.