11.1 Text Styles

  • 11.1.1 Text Style Protocol and Text Style Suboptions
  • Text style objects have components for family, face, and size. Not all of these attributes need be supplied for a given text style object. Text styles can be merged in much the same way as pathnames are merged; unspecified components in the style object (that is, components that have nil in them) may be filled in by the components of a "default" style object. A text style object is called fully specified if none of its components is nil, and the size component is not a relative size (that is, is neither :smaller nor :larger). [annotate]

    text-style   [Protocol Class]
              

    The protocol class for text styles. If you want to create a new class that behaves like a text style, it should be a subclass of text-style. All instantiable subclasses of text-style must obey the text style protocol. [annotate]

    [annotate]

    text-style-p  object [Protocol Predicate]
              

    Returns true if object is a text style, otherwise returns false. [annotate]

    [annotate]

    standard-text-style   [Class]
              

    An instantiable class that implements text styles. It is a subclass of text-style. This is the class that make-text-style instantiates. Members of this class are immutable. [annotate]

    The interface to text styles is as follows: [annotate]

    [annotate]

    make-text-style  family face size [Function]
              

    Returns an object of class standard-text-style with a family of family, a face of face, and a size of size. [annotate]

    family is one of :fix, :serif, :sans-serif, or nil. [annotate]

    face is one of :roman, :bold, :italic, (:bold :italic), or nil. [annotate]

    size is a real number representing the size in printer's points, one of the logical sizes (:normal, :tiny, :very-small, :small, :large, :very-large, :huge), a relative size (:smaller or :larger), or nil. [annotate]

    Note: When specifying :SMALLER or :LARGER, what is that size relative to? [edit]-- Elias Mårtenson 2018-06-10 06:46Z
     
    Note: To the text-style you merge with and/or *default-text-style*. [edit]-- Daniel Kochmanski 2018-10-09 06:08Z
     

    Implementations are permitted to extend legal values for family, face, and size. [annotate]

    Minor issue: Need to describe what family, face, size mean in terms of visual appearance. This should also be reconciled with the ISO description of the attributes of a "text style", including such things as underlining, subscripts, superscripts, etc. --- York, SWM [annotate]

    [annotate]

    *default-text-style*   [Constant]
              

    The default text style used on a CLIM medium if no text style it explicitly specified for the medium when it it created. This must be a fully merged text style. [annotate]

    [annotate]

    *undefined-text-style*   [Constant]
              

    The text style that is used as a fallback if no mapping exists for some other text style when some text is about to be rendered on a display device (via write-string and draw-string*, for example). This text style be fully merged, and it must have a mapping for all display devices. [annotate]

    [annotate]

    11.1.1 Text Style Protocol and Text Style Suboptions

    The following generic functions comprise the text style protocol. All subclasses of text-style must implement methods for each of these generic functions. [annotate]

    Each of the suboptions described below has a corresponding reader accessor that can be used to extract a particular component from a text style. [annotate]

    text-style-components  text-style [Generic Function]
              

    Returns the components of the text style text-style as three values, the family, face, and size. [annotate]

    [annotate]

    :text-family   [Option]
    text-style-family  text-style [Generic Function]
              

    Specifies the family of the text style text-style. [annotate]

    [annotate]

    :text-face   [Option]
    text-style-face  text-style [Generic Function]
              

    Specifies the face of the text style text-style. [annotate]

    [annotate]

    :text-size   [Option]
    text-style-size  text-style [Generic Function]
              

    Specifies the size of the text style text-style. [annotate]

    [annotate]

    parse-text-style  style-spec [Function]
              

    Returns a text style object. style-spec may be a text-style object or a device font, in which case it is returned as is, or it may be a list of the family, face, and size (that is, a "style spec"), in which case it is "parsed" and a text-style object is returned. This function is for efficiency, since a number of common functions that take a style object as an argument can also take a style spec, in particular draw-text. [annotate]

    [annotate]

    merge-text-styles  style1 style2 [Generic Function]
              

    Merges the text styles style1 with style2, that is, returns a new text style that is the same as style1, except that unspecified components in style1 are filled in from style2. For convenience, the two arguments may be also be style specs. [annotate]

    When merging the sizes of two text styles, if the size from style1 is a relative size, the resulting size is either the next smaller or next larger size than is specified by style2. The ordering of sizes, from smallest to largest, is :tiny, :very-small, :small, :normal, :large, :very-large, and :huge. [annotate]

    Minor issue: Need to describe face-merging properly. For example, merging a bold face with an italic one can result in a bold-italic face. --- SWM [annotate]

    [annotate]

    text-style-ascent  text-style medium [Generic Function]
    text-style-descent  text-style medium [Generic Function]
    text-style-height  text-style medium [Generic Function]
    text-style-width  text-style medium [Generic Function]
              

    Returns the ascent, descent, height, and width (respectively) of the font corresponding to the text style text-style as it would be rendered on the medium medium. text-style must be a fully specified text style. [annotate]

    The ascent of a font is the distance between the top of the tallest character in that font and the font's baseline. The descent of a font is the distance between the baseline and the bottom of the lowest descending character (usually "g", "p", "q", or "y"). The height of a font is the sum of the ascent and the descent of the font. The width of a font is the width of some representative character in the font. [annotate]

    The methods for these generic functions will typically specialize both the text-style and medium arguments. Implementations should also provide "trampoline" for these generic functions on output sheets; the trampolines will simply call the method for the medium. [annotate]

    [annotate]

    text-style-fixed-width-p  text-style medium [Generic Function]
              

    Returns true if the text styles text-style will map to a fixed-width font on the medium medium, otherwise returns false. text-style must be a fully specified text style. [annotate]

    The methods for this generic function will typically specialize both the text-style and medium arguments. Implementations should also provide a "trampoline" for this generic function for output sheets; the trampoline will simply call the method for the medium. [annotate]

    Minor issue: Discuss baselines? Kerning? --- SWM [annotate]

    [annotate]

    text-size  medium string &key text-style (start 0) end [Generic Function]
              

    Computes the "cursor motion" in device units that would take place if string (which may be either a string or a character) were output to the medium medium starting at the position (0,0). Five values are returned: the total width of the string in device units, the total height of the string in device units, the final x cursor position (which is the same as the width if there are no #\Newline characters in the string), the final y cursor position (which is 0 if the string has no #\Newline characters in it, and is incremented by the line height of medium for each #\Newline character in the string), and the string's baseline. [annotate]

    text-style specifies what text style is to be used when doing the output, and defaults to medium-merged-text-style of the medium. text-style must be a fully specified text style. start and end may be used to specify a substring of string. [annotate]

    If a programmer needs to account for kerning or the ascent or descent of the text style, he should measure the size of the bounding rectangle of the text rendered on medium. [annotate]

    All mediums and output sheets must implement a method for this generic function. [annotate]

    [annotate]