CLX provides functions for drawing text using text fonts provided by the X server. An X font is array of character bit maps indexed by integer codes. See Section 8 for a complete discussion of the CLX functions used to manage fonts and characters.
Since Common Lisp programs typically represent text as sequences of characters (that is, strings), CLX text functions must be prepared to convert a Common Lisp character into the integer code used to index the appropriate character bitmap in a given font. The :translate argument to a text function is a function which performs this conversion. The default :translate function handles all characters that satisfy graphic-char-p by converting each character into its ASCII code. Note that the assumption made by the default :translate function--that is, that an X font indexes bitmaps by ASCII codes--is often valid, but other encodings are possible. In general, a :translate function can perform complex transformations. It can be used to convert non-character input, to handle non-ASCII character encodings, and to change the fonts used to access character bitmaps. The complete behavior of a :translate function is given below by describing a prototypical translate-function .
CLX offers two different ways to draw text--filled text and block text. The draw-glyph and draw-glyphs functions create filled text, in which each character image is treated as an area to be filled according to the fill-style of the given graphics context, without otherwise disturbing the surrounding background. In addition, filled text sends a complex type of server request which allows a series of font indices, font changes, and horizontal position changes to be compiled into a single request. Filled text functions use the following graphics context attributes: background, clip-mask, clip-x-origin, clip-y-origin, fill-style, font, foreground, function, plane-mask, stipple, subwindow-mode, tile, ts-x-origin, ts-y-origin.
Block text is a rendering style commonly used by display terminals, in which each character image appears in the foreground pixel inside a rectangular character cell drawn in the graphics context background pixel. The draw-image-glyph and draw-image-glyphs functions create block text. Block text functions use the following graphics context attributes: background, clip-mask, clip-x-origin, clip-y-origin, font, foreground, plane-mask, stipple, subwindow-mode, tile, ts-x-origin, ts-y-origin.
| draw-glyph | drawable gcontext x y element &key :translate :width (:size :default ) | Function |
Draws a single character of filled text represented by the given element. The given x and y specify the left baseline position for the character. The first return value is true if the character is successfully translated and drawn, or nil if the :translate function did not translate it. The second return value gives the total pixel width of the character actually drawn, if known. Specifying a :width is a hint to improve performance. The :width is assumed to be the total pixel width of the character actually drawn. Specifying :width permits appending the output of subsequent calls to the same protocol request, provided gcontext has not been modified in the interim. If :width is not specified, appending of subsequent output might not occur (unless :translate returns the character width). The :size specifies the element size of the destination buffer given to :translate (either 8, 16, or :default ). If :default is specified, the size is based on the current font, if known; otherwise, 16 is used. |
| draw-glyphs | drawable gcontext x y sequence &key (:start 0) :end :translate :width (:size :default) | Function |
Draws the filled text characters represented by the given sequence. :start and :end define the elements of the sequence which are drawn. The given x and y specify the left baseline position for the first character. The first return value is nil if all characters are successfully translated and drawn; otherwise, the index of the first untranslated sequence element is returned. The second return value gives the total pixel width of the characters actually drawn, if known. Specifying a :width is a hint to improve performance. The :width is assumed to be the total pixel width of the character sequence actually drawn. Specifying :width permits appending the output of subsequent calls to the same protocol request, provided gcontext has not been modified in the interim. If :width is not specified, appending of subsequent output might not occur (unless :translate returns the character width). The :size specifies the element size of the destination buffer given to:translate (either 8, 16, or :default ). If :default is specified, the size is based on the current font, if known; otherwise, 16 is used.
|
| draw-image-glyph | drawable gcontext x y element &key :translate :width (:size :default ) | Function |
Draws a single character of block text represented by the given element. The given x and y specify the left baseline position for the character. The first return value is true if the character is successfully translated and drawn, or nil if the :translate function did not translate it. The :translate function is allowed to return an initial font change. The second return value gives the total pixel width of the character actually drawn, if known. The :translate function may not return a horizontal position change, since draw-image-glyph does not generate complex output requests. Specifying a :width is a hint to improve performance. The :width is assumed to be the total pixel width of the character actually drawn. Specifying :width permits appending the output of subsequent calls to the same protocol request, provided gcontext has not been modified in the interim. If :width is not specified, appending of subsequent output might not occur (unless :translate returns the character width). The :size specifies the element size of the destination buffer given to :translate (either 8, 16, or :default ). If :default is specified, the size is based on the current font, if known; otherwise, 16 is used. |
| draw-image-glyphs | drawable gcontext x y sequence &key (:start 0) :end :translate :width (:size :default) | Function |
Draws the block text characters represented by the given sequence. :start and :end define the elements of the sequence which are drawn. The given x and y specify the left baseline position for the first character. The first return value is nil if all characters are successfully translated and drawn; otherwise, the index of the first untranslated sequence element is returned. The :translate function is allowed to return an initial font change. The second return value gives the total pixel width of the characters actually drawn, if known. The :translate function may not return a horizontal position change, since draw-image-glyphs does not generate complex output requests. Specifying a :width is a hint to improve performance. The :width is assumed to be the total pixel width of the character sequence actually drawn. Specifying :width permits appending the output of subsequent calls to the same protocol request, provided gcontext has not been modified in the interim. If :width is not specified, appending of subsequent output might not occur (unless :translate returns the character width). The :size specifies the element size of the destination buffer given to :translate (either 8, 16, or :default ). If :default is specified, the size will be based on the current font, if known; otherwise, 16 is used.
|
| translate-function | source source-start source-end font destination destination-start | Function |
A function used as the :translate argument for text functions. Converts elements of the source (sub)sequence into font indexes for the given font and stores them into the destination vector. The destination vector is created automatically by CLX. destination is guaranteed to have room for (- source-end source-start) integer elements, starting at destination-start. Elements of destination can be either card8 or card16 integers, depending on the context. font is the current font, if known, or nil otherwise. Starting with the element at source-start, translate-function should translate as many elements of source as possible (up to the source-end element) into indexes in the current font, and store them into destination. The first return value should be the source index of the first untranslated element. The second return value indicates the changes which should be made to the current text output request before translating the remaining source elements. If no further elements need to be translated, the second return value should be nil. If a horizontal motion is required before further translation, the second return value should be the change in x position. If a font change is required for further translation, the second return value should be the new font. If known, the pixel width of the translated text can be returned as the third value; this can allow for appending of subsequent output to the same protocol request, if no overall width has been specified at the higher level.
|