# HG changeset patch # User Richard M. Stallman # Date 1096096774 0 # Node ID f0af4b0029b57f9d7fc0c6b6d488bde977075a36 # Parent 18bdf278f1481734912848614424d1defc2bf13f (Special Properties): Cleanups in `cursor'. Rewrites in `line-height' and `line-spacing'; exchange them. diff -r 18bdf278f148 -r f0af4b0029b5 lispref/text.texi --- a/lispref/text.texi Sat Sep 25 07:18:08 2004 +0000 +++ b/lispref/text.texi Sat Sep 25 07:19:34 2004 +0000 @@ -2977,8 +2977,8 @@ @item cursor @kindex cursor @r{(text property)} Normally, the cursor is displayed at the end of any overlay and text -property string that may be present at the current window position. -The cursor may be placed on any character of such strings by giving +property strings present at the current window position. You can +place the cursor on any desired character of these strings by giving that character a non-@code{nil} @var{cursor} text property. @item pointer @@ -2987,55 +2987,56 @@ this text or image. See the variable @var{void-area-text-pointer} for possible pointer shapes. +@item line-spacing +@kindex line-spacing @r{(text property)} +A newline can have a @code{line-spacing} text or overlay property +that controls the height of the corresponding display line. +@c ??? Which display line is "corresponding"? +The @code{line-spacing} property overrides the default frame line +spacing and the buffer local @code{line-spacing} variable. We will +call the property value @var{line-spacing}. + +If @var{line-spacing} is a positive integer, the value specifies +additional vertical space, below the display line, in pixels. + +If @var{line-spacing} is a floating point number or cons, the +additional vertical space is the product of @var{line-spacing} and the +default frame line height. + +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. + @item line-height @kindex line-height @r{(text property)} -A newline may have @code{line-height} text or overlay properties that -controls the height of the corresponding display row. - -If the @code{line-height} property value is @samp{0}, the newline does -not contribute to the height of the display row; instead the height of -the newline glyph is reduced. Also, a @code{line-spacing} property on +A newline can have a @code{line-height} text or overlay property that +controls the total height of the corresponding display line. +@c ??? Which display line is "corresponding"? +We will call the property value @var{line-height}. + +If @var{line-height} is 0, the newline does not contribute to the +height of the display row; instead the height of the newline glyph is +reduced. +@c ??? That is not clear. Reduced how much? +In that case, any @code{line-spacing} property on this newline is ignored. This can be used to tile small images or image slices without adding blank areas between the images. - -If the @code{line-height} property value is a positive integer, the -value specifies the minimum line height in pixels. If necessary, the -line height it increased by increasing the line's ascent. - -If the @code{line-height} property value is a floating point number, -the minimum line height is calculated by multiplying the default frame -line height by the given value. - -If the @code{line-height} property value is a cons @code{(@var{ratio} -. @var{face})}, the minimum line height is calculated as @var{ratio} * -height of named face @var{face}. The @var{ ratio} is an integer or a -floating point number. If @var{face} is @code{t}, it specifies the -current face. - -@item line-spacing -@kindex line-spacing @r{(text property)} -A newline may also have a @code{line-spacing} text or overlay -properties that controls the height of the corresponding display row. - -If the @code{line-spacing} property value is an positive integer, the -value is used as additional pixels to insert after the display line; -this overrides the default frame line-spacing and any buffer local -value of the @var{line-spacing} variable. - -If the @code{line-spacing} property is a floating point number or -cons, the line spacing is calculated as specified above for the -@code{line-height} property. - -If the @code{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} is used as the total height of the line, i.e. a varying -number of pixels are inserted after each line to make each line -exactly that many pixels high. - -Using the @code{line-spacing} property overrides the buffer local -@var{line-spacing} variable. That value of that variable may be an -integer that specifies a number of pixels, or a floating point -number which gives the spacing relative to the default frame line height. +@c ??? Precisely which of these features does ``this'' mean? + +If @var{line-height} 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. + +If @var{line-height} is a floating point number, the minimum line +height is the product of @var{line-height} and the default frame line +height. + +If @var{line-height} 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. @item modification-hooks @cindex change hooks for a character