Info Catalog elisp: Size of Displayed Text elisp: Display elisp: Faces

elisp: Line Height

 
 37.11 Line Height
 =================
 
 The total height of each display line consists of the height of the
 contents of the line, plus optional additional vertical line spacing
 above or below the display line.
 
    The height of the line contents is the maximum height of any
 character or image on that display line, including the final newline if
 there is one.  (A display line that is continued doesn’t include a final
 newline.)  That is the default line height, if you do nothing to specify
 a greater height.  (In the most common case, this equals the height of
 the corresponding frame’s default font, see Frame Font.)
 
    There are several ways to explicitly specify a larger line height,
 either by specifying an absolute height for the display line, or by
 specifying vertical space.  However, no matter what you specify, the
 actual line height can never be less than the default.
 
    A newline can have a ‘line-height’ text or overlay property that
 controls the total height of the display line ending in that newline.
 
    If the property value is ‘t’, the newline character has no effect on
 the displayed height of the line—the visible contents alone determine
 the height.  The ‘line-spacing’ property, described below, is also
 ignored in this case.  This is useful for tiling small images (or image
 slices) without adding blank areas between the images.
 
    If the property value is a list of the form ‘(HEIGHT TOTAL)’, that
 adds extra space _below_ the display line.  First Emacs uses HEIGHT as a
 height spec to control extra space _above_ the line; then it adds enough
 space _below_ the line to bring the total line height up to TOTAL.  In
 this case, any value of ‘line-spacing’ property for the newline is
 ignored.
 
    Any other kind of property value is a height spec, which translates
 into a number—the specified line height.  There are several ways to
 write a height spec; here’s how each of them translates into a number:
 
 ‘INTEGER’
      If the height spec is a positive integer, the height value is that
      integer.
 ‘FLOAT’
      If the height spec is a float, FLOAT, the numeric height value is
      FLOAT times the frame’s default line height.
 ‘(FACE . RATIO)’
      If the height spec is a cons of the format shown, the numeric
      height is RATIO times the height of face FACE.  RATIO can be any
      type of number, or ‘nil’ which means a ratio of 1.  If FACE is ‘t’,
      it refers to the current face.
 ‘(nil . RATIO)’
      If the height spec is a cons of the format shown, the numeric
      height is RATIO times the height of the contents of the line.
 
    Thus, any valid height spec determines the height in pixels, one way
 or another.  If the line contents’ height is less than that, Emacs adds
 extra vertical space above the line to achieve the specified total
 height.
 
    If you don’t specify the ‘line-height’ property, 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.
 
    On graphical terminals, you can specify the line spacing for all
 lines in a frame, using the ‘line-spacing’ frame parameter (Layout
 Parameters).  However, if the default value of ‘line-spacing’ is
 non-‘nil’, it overrides the frame’s ‘line-spacing’ parameter.  An
 integer specifies the number of pixels put below lines.  A
 floating-point number specifies the spacing relative to the frame’s
 default line height.
 
    You can specify the line spacing for all lines in a buffer via the
 buffer-local ‘line-spacing’ variable.  An integer specifies the number
 of pixels put below lines.  A floating-point number specifies the
 spacing relative to the default frame line height.  This overrides line
 spacings specified for the frame.
 
    Finally, a newline can have a ‘line-spacing’ text or overlay property
 that can enlarge the default frame line spacing and the buffer local
 ‘line-spacing’ variable: if its value is larger than the buffer or frame
 defaults, that larger value is used instead, for the display line ending
 in that newline.
 
    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.
 
    On text terminals, the line spacing cannot be altered.
 

Info Catalog elisp: Size of Displayed Text elisp: Display elisp: Faces