Chapter 4 Text Styles

4.3 CLIM Text Style Functions

The following functions can be used to parse, merge, and create text-style objects, as well as to read the components of the objects.

parse-text-style [Generic Function]

Arguments:: style-spec
Summary:: 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.

merge-text-styles [Generic Function]

Arguments:: style1 style2
Summary:: 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.
: 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.
: Merging font faces is also possible. For example, merging bold and italic faces results in a bold-italic face. When the faces are mutually exclusive, the face specified by style1 prevails.

text-style-components [Generic Function]

Arguments:: text-style
Summary:: Returns the components of text-style as three values (family, face, and size).

text-style-family [Generic Function]

text-style-face [Generic Function]

text-style-size [Generic Function]

text-style-ascent [Generic Function]

Arguments:: text-style port
Summary:: The ascent (an integer) of text-style as it would be rendered on any medium of port port.
Summary:: The ascent of a text style is the ascent of the medium's font corresponding to text-style. The ascent of a font is the distance between the top of the tallest character in that font and the baseline.

text-style-descent [Generic Function]

Arguments:: text-style port
Summary:: The descent (an integer) of text-style as it would be rendered on any medium of port port.
: The descent of a text style is the descent of the medium's font corresponding to text-style. The descent of a font is the distance between the baseline and the bottom of the lowest descending character (usually "y," "q," "p," or "g").

text-style-height [Generic Function]

Arguments:: text-style port
Summary:: Returns the height (an integer) of the "usual character" in text-style on any medium of port port.
: The height of a text style is the sum of its ascent and descent.

text-style-width [Generic Function]

Arguments:: text-style port
Summary:: Returns the width (an integer) of the "usual character" in text-style on any medium of port port.

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

Arguments:: text-style port
Summary:: Returns t if text-style will map to a fixed-width font on any medium of port port; otherwise, it returns nil.
: The methods for this generic function will typically specialize both the text-style and port arguments. CLIM provides a "trampoline" for this generic function for mediums and output sheets which will simply call the method for the port.

text-size [Generic Function]

Arguments:: medium string&key text-style (start 0) end
Summary:: 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.
: 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.
: Programmers needing to account for kerning or the ascent or descent of the text style should measure the size of the bounding rectangle of the text rendered on medium.
: All mediums and output sheets implement a method for this generic function.

CLIM 2.0 User's Guide - OCT 1998