Package pango

The Pango rendering pipeline takes a string of Unicode characters and converts it into glyphs. The functions described in this section accomplish various steps of this process.

Pango supports a flexible architecture where a particular rendering architecture can supply an implementation of fonts. The pango:font class represents an abstract rendering-system-independent font. Pango provides routines to list available fonts, and to load a font of a given description.

Structures for storing information about glyphs. The pango:shape function produces a string of glyphs which can be measured or drawn to the screen. The following structures are used to store information about glyphs.

Attributed text is used in a number of places in Pango. It is used as the input to the itemization process and also when creating a Pango layout. The data types and functions in this section are used to represent and manipulate sets of attributes applied to a portion of text.

Simple markup language for text with attributes.

Frequently, you want to display some text to the user with attributes applied to part of the text. For example, you might want bold or italicized words. With the base Pango interfaces, you could create a pango:attr-list instance and apply it to the text. The problem is that you would need to apply attributes to some numeric range of characters, for example "characters 12-17." This is broken from an internationalization standpoint. Once the text is translated, the word you wanted to italicize could be in a different position.

The solution is to include the text attributes in the string to be translated. Pango provides this feature with a small markup language. You can parse a marked-up string into the string text plus a pango:attr-list instance using the pango:parse-markup function.

A simple example of a marked-up string might be:

<span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!      

Pango uses GMarkup to parse this language, which means that XML features such as numeric character entities such as © for © can be used too.

The root tag of a marked-up document is <markup>, but the pango:parse-markup function allows you to omit this tag, so you will most likely never need to use it. The most general markup tag is <span>, then there are some convenience tags.

Span attributes

<span> has the following attributes:

font_desc

A font description string, such as "Sans Italic 12". See the pango:font-description-from-string function for a description of the format of the string representation. Note that any other span attributes will override this description. So if you have "Sans Italic" and also a style="normal" attribute, you will get Sans normal, not italic.

font_family

A font family name.

font_size, size

Font size in 1024ths of a point, or one of the absolute sizes xx-small, x-small, small, medium, large, x-large, xx-large, or one of the relative sizes smaller or larger. If you want to specify a absolute size, it is usually easier to take advantage of the ability to specify a partial font description using font. You can use font='12.5' rather than size='12800'.

font_style

One of normal, oblique, italic.

font_weight

One of ultralight, light, normal, bold, ultrabold, heavy, or a numeric weight.

font_variant

One of normal or smallcaps.

font_stretch, stretch

One of ultracondensed, extracondensed, condensed, semicondensed, normal, semiexpanded, expanded, extraexpanded, ultraexpanded.

font_features

A comma-separated list of OpenType font feature settings, in the same syntax as accepted by CSS, e.g. font_features='dlig=1, -kern, afrc on'.

foreground, fgcolor

An RGB color specification such as #00FF00 or a color name such as red. An RGBA color specification such as #00FF007F will be interpreted as specifying both a foreground color and foreground alpha.

background, bgcolor

An RGB color specification such as #00FF00 or a color name such as red. An RGBA color specification such as #00FF007F will be interpreted as specifying both a background color and background alpha.

alpha, fgalpha

An alpha value for the foreground color, either a plain integer between 1 and 65536 or a percentage value like 50 %.

background_alpha, bgalpha

An alpha value for the background color, either a plain integer between 1 and 65536 or a percentage value like 50 %.

underline

One of none, single, double, low, error, single-line, double-line or error-line.

underline_color

The color of underlines. An RGB color specification such as #00FF00 or a color name such as red.

overline

One of none or single.

overline_color

The color of overlines. An RGB color specification such as #00FF00 or a color name such as red.

rise

Vertical displacement, in Pango units. Can be negative for subscript, positive for superscript.

strikethrough

True or false whether to strike through the text.

strikethrough_color

The color of strikethrough lines. An RGB color specification such as #00FF00 or a color name such as red.

fallback

True or false whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.

allow_breaks

True or false whether to allow line breaks or not. If not allowed, the range will be kept in a single run as far as possible. Breaks are allowed by default.

insert_hyphens

True or false whether to insert hyphens when breaking lines in the middle of a word. Hyphens are inserted by default.

show

A value determining how invisible characters are treated. Possible values are spaces, line-breaks, ignorables or combinations, such as spaces and line-breaks.

lang

A language code, indicating the text language.

letter_spacing

Inter-letter spacing in 1024ths of a point.

gravity

One of south, east, north, west, auto.

gravity_hint

One of natural, strong, line.

Convenience tags

The following convenience tags are provided:

<b>

Bold.

<big>

Makes font relatively larger, equivalent to <span size="larger">.

<i>

Italic.

<s>

Strikethrough.

<sub>

Subscript.

<sup>

Superscript.

<small>

Makes font relatively smaller, equivalent to <span size="smaller">.

<tt>

Monospace.

<u>

Underline.

While complete access to the layout capabilities of Pango is provided using the detailed interfaces for itemization and shaping, using that functionality directly involves writing a fairly large amount of code. The objects and functions in this section provide a high-level driver for formatting entire paragraphs of text at once. This includes paragraph-level functionality such as line-breaking, justification, alignment and ellipsization.

Types and functions to help with handling bidirectional text.

Pango supports bidirectional text (like Arabic and Hebrew) automatically. Some applications however, need some help to correctly handle bidirectional text.

The pango:direction enumeration can be used with the pango:context-base-dir function to instruct Pango about direction of text, though in most cases Pango detects that correctly and automatically. The rest of the facilities in this section are used internally by Pango already, and are provided to help applications that need more direct control over bidirectional setting of text.

Laying text out in vertical directions.

The Cairo library is a vector graphics library with a powerful rendering model. It has such features as anti-aliased primitives, alpha-compositing, and gradients. Multiple backends for Cairo are available, to allow rendering to images, to PDF files, and to the screen on X and on other windowing systems. The functions in this section allow using Pango to render to Cairo surfaces.

Using Pango with Cairo is straightforward. A pango:context object created with the pango:font-map-create-context function can be used on any cairo:context-t instance, but needs to be updated to match the current transformation matrix and target surface of the Cairo context using the pango:cairo-update-context function. The convenience pango:cairo-create-layout and pango:cairo-update-layout functions handle the common case where the program does not need to manipulate the properties of the pango:context object.

When you get the metrics of a layout or of a piece of a layout using functions such as the pango:layout-extents function, the reported metrics are in user-space coordinates. If a piece of text is 10 units long, and you call (cairo:scale cr 2.0), it still is more-or-less 10 units long. However, the results will be affected by hinting (that is, the process of adjusting the text to look good on the pixel grid), so you should not assume they are completely independent of the current transformation matrix. Note that the basic metrics functions in Pango report results in integer Pango units. To get to the floating point units used in Cairo divide by the pango:+scale+ value. Using Pango with Cairo

(defun draw-cairo-rendering (cr width height)
  (let ((radius (- (/ (min width height) 2) 20))
        (circle 260)
        (n-words 12)
        (font "Sans Bold 16"))
    ;; Set up a transformation matrix so that the user space
    ;; coordinates for where we are drawing are [-RADIUS, RADIUS],
    ;; [-RADIUS, RADIUS] We first center, then change the scale
    (cairo:translate cr (+ radius (/ (- width (* 2 radius)) 2))
                        (+ radius (/ (- height (* 2 radius)) 2)))
    (cairo:scale cr (/ radius circle) (/ radius circle))
    ;; Clear surface
    (cairo:set-source-rgb cr 1.0 1.0 1.0)
    (cairo:paint cr)
    ;; Create a PangoLayout, set the font and text
    (let ((layout (pango:cairo-create-layout cr))
          (desc (pango:font-description-from-string font)))
      (setf (pango:layout-text layout) "Crategus")
      (setf (pango:layout-font-description layout) desc)
      ;; Draw the layout n-words times in a circle
      (do* ((i 0 (+ i 1))
            (angle 0 (/ (* 360 i) n-words))
            ;; Gradient color
            (color (/ (+ 1 (cos (* (/ pi 180) (- angle 60)))) 2)
                   (/ (+ 1 (cos (* (/ pi 180) (- angle 60)))) 2)))
           ((>= i n-words))
           (cairo:save cr)
           (cairo:set-source-rgb cr (/ #xFF 255) (/ #x99 255) color)
           (cairo:rotate cr (/ (* angle pi) 180))
           ;; Inform Pango to re-layout the text with the new
           ;; transformation matrix
           (pango:cairo-update-layout cr layout)
           (multiple-value-bind (width height)
               (pango:layout-size layout)
             (declare (ignore height))
             (cairo:move-to cr (- (/ width 2 pango:+scale+)) (- circle)))
             (pango:cairo-show-layout cr layout)
             (cairo:restore cr)))))        

Global context object.

Structures for storing tab stops. Functions in this section are used to deal with pango:tab-array instances that can be used to set tab stop positions in a pango:layout object.

Unicode character range coverage storage.

Rendering driver base class.

Tools for checking Pango version at compile and run time.