11 Text Styles
When specifying a particular ``appearance'' for rendered characters, there is a
tension between portability and access to specific font for a display device.
CLIM provides a portable mechanism for describing the desired text style in abstract terms. Each CLIM ``port'' defines a mapping between these
abstract style specifications and particular device-specific fonts. In this
way, an application programmer can specify the desired text style in abstract
terms secure in the knowledge that an appropriate device font will be selected
at run time by CLIM. However, some programmers may require direct access to
particular device fonts. The text style mechanism supports specifying device
fonts by name, allowing the programmer to sacrifice portability for control.
11.1 Text Styles
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 ).
| 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. Subclasses of text-style must obey the text style protocol.| text-style-p | object | [Predicate] |
Returns true if object is a text style , otherwise returns
false .
| 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. The interface to text styles is as follows:
| 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 .
family is one of :fix , :serif , :sans-serif , or nil .
face is one of :roman , :bold , :italic , (:bold :italic) ,
or nil .
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 .
Implementations are permitted to extend legal values for family ,
face , and size .
Issue: York, SWM
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.
| *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.
| *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.
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.
Each of the suboptions described below has a corresponding reader accessor that
can be used to extract a particular component from a text style.
| text-style-components | text-style | [Generic function] |
Returns the components of the text style text-style as three
values, the family, face, and size.
| text-style-family | text-style | [Generic function] |
Specifies the family of the text style text-style .
| text-style-face | text-style | [Generic function] |
Specifies the face of the text style text-style .
| text-style-size | text-style | [Generic function] |
Specifies the size of the text style text-style .
| 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 .
| 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.
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 .
Issue: SWM
Need to describe face-merging properly. For example, merging a
bold face with an italic one can result in a bold-italic face.
| 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.
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.
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.
| 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.
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.
Issue: SWM
Discuss baselines? Kerning?
| 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.
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 .
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 .
All mediums and output sheets must implement a method for this generic function.
11.2 Text Style Binding Forms
| with-text-style | (medium text-style) &body body | [Macro] |
Binds the current text style of the medium designated by medium to
correspond to the new text style. text-style may either a text style
object or a style spec (that is, a list of the a family, a face code, and a
size). body is executed with the new text style in effect.
The medium argument is not evaluated, and must be a symbol that is bound
to a sheet or medium. If medium is t , *standard-output* is
used. body may have zero or more declarations as its first forms.
with-text-style must be implemented by expanding into a call to
invoke-with-text-style , supplying a function that executes body as
the continuation argument to invoke-with-text-style .
| invoke-with-text-style | medium continuation text-style | [Generic function] |
Binds the current text style of the medium medium to correspond to
the new text style, and calls the function continuation with the new text
style in effect. text-style may either a text style object or a style
spec (that is, a list of the a family, a face code, and a size). continuation is a function of one argument, the medium; it has dynamic extent.
medium can be a medium, a sheet that supports the sheet output protocol,
or a stream that outputs to such a sheet. All classes that obey the medium
protocol must implement a method for invoke-with-text-style .
| with-text-family | (medium family) &body body | [Macro] |
| with-text-face | (medium face) &body body | [Macro] |
| with-text-size | (medium size) &body body | [Macro] |
Binds the current text style of the medium designated by medium to
correspond to a new text style consisting of the current text style with the new
family, face, or size (respectively) merged in. face , family , and
size are as for make-text-style . body is executed with the new
text style in effect.
The medium argument is not evaluated, and must be a symbol that is bound
to a sheet or medium. If medium is t , *standard-output* is
used. body may have zero or more declarations as its first forms.
These macros are ``convenience'' forms of with-text-style that must expand
into calls to invoke-with-text-style .
11.3 Controlling Text Style Mappings
Text styles are mapped to fonts using the text-style-mapping function,
which takes a port, a character set, and a text style and returns a font
object. All ports must implement methods for the following generic functions,
for all classes of text style.
The objects used to represent a font mapping are unspecified and are likely to
vary from port to port. For instance, a mapping might be some sort of font
object on one type of port, or might simply be the name of a font on another.
Issue: SWM
We still need to describe what a device font is. Ditto, character
sets.
Part of initializing a port is to define the mappings between text styles and
font names for the port's host window system.
| text-style-mapping | port text-style &optional character-set | [Generic function] |
Returns the font mapping that will be used when rendering characters in the
character set character-set in the text style text-style on
any medium on the port port . If there is no mapping associated
with character-set and text-style on port , then some other
object will be returned that corresponds to the ``unmapped'' text style.
character-set defaults to the standard character set.
| (setf text-style-mapping) | mapping port text-style &optional character-set | [Generic function] |
Sets the text style mapping for port , character-set , and
text-style to mapping . port , character-set , and
text-style are as for text-style-mapping . mapping is either a
font name or a list of the form (:style family face size ) ; in the latter case, the given style is translated at runtime into
the font represented by the specified style.
character-set defaults to the standard character set.
| make-device-font-text-style | display-device device-font-name | [Function] |
Returns a text style object that will be mapped directly to the specified device
font when text is output to a to the display device with this style. Device
font styles do not merge with any other kind of style.