Next Prev Up Top Contents Index

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]

Arguments: text-style

Summary: Returns the family component of text-style .

text-style-face[Generic Function]

Arguments: text-style

Summary: Returns the face component of text-style .

text-style-size[Generic Function]

Arguments: text-style

Summary: Returns the size component of text-style .

text-style-ascent[Generic Function]

Arguments: text-style medium

Summary: The ascent (an integer) of text-style as it would be rendered on medium medium .

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 medium

Summary: The descent (an integer) of text-style as it would be rendered on medium medium .

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 medium

Summary: Returns the height (an integer) of the "usual character" in text-style on medium medium .

The height of a text style is the sum of its ascent and descent.

text-style-width[Generic Function]

Arguments: text-style medium

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

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

Arguments: text-style medium

Summary: Returns t if text-style will map to a fixed-width font on medium medium ; 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.


CommonLisp Interface Manager 2.0 User's Guide - 8 Aug 2003

Next Prev Up Top Contents Index