User Tools

Site Tools


25.1.7 CairoTextExtents

The properties of the two classes CairoTextExtents and → 25.1.8 CairoFontExtents store the dimensions of a single glyph or a sequence of several glyphs. The numerous, quite different font dimensions are described in the so-called typographic metrics.

In this chapter and in the → chapter CairoFontExtents, only the typographic metrics for a horizontal layout of a font are discussed. This also includes the font of the text you are currently reading. A horizontal layout is characterised by a (virtual) horizontal (text) base line → Figure

In Gambas, certain font dimensions are grouped and described in the properties of the two classes CairoTextExtents and → 25.1.8 CairoFontExtents. One group refers only to the font used, while the other refers to the drawn glyphs of the specified text. Which properties of the two classes you choose when drawing text is largely determined by your design ideas for the drawing. Properties


Figure Fictitious text bounding box (bounding box)

The class CairoTextExtents describes properties of the typographic metric of type float:

HeightSpecifies the height of the glyphs - as they are drawn.
WidthSpecifies the width of the glyphs - as they are drawn.
YBearingSpecifies the vertical distance from the BaseLine to the uppermost part of the glyphs - as drawn. The distance is only positive if the glyphs are completely below the origin. As a rule, this value is negative.
XAdvanceSpecifies the spacing in the x-direction after drawing the glyphs.
XBearingSpecifies the horizontal distance from the BasePoint (Origin) to the leftmost part of the glyphs - as drawn. The distance is positive if the glyphs are completely to the right of the BasePoint.
YAdvanceSpecifies the distance in the y-direction after drawing these glyphs. The value is zero for a horizontal layout.

Table : Properties of the CairoTextExtents class


  • The drawing of text should primarily be used for labelling selected details of a drawing. Exceptions could be texts with a clear structure in the form of rows and columns - as is typical for tables, for example. In the projects for Cairo you will therefore also find a project for a simple database report that was drawn using methods from classes of the Cairo component.
  • For drawing text, you can get by with the width, height and YBearing properties, as the values for XBearing are sufficiently zero for font sizes up to 100 and YAdvance is generally zero for the horizontal font layout considered here. Notes

Under the → link you will find information on the term 'Glyph', which is repeatedly used in connection with properties and methods of different classes of the Cairo component (gb.cairo). There it is emphasised, among other things, that in typography a glyph is the graphic representation of a character, for example a letter, a syllable character, a ligature or a part of a letter. The glyph forms a graphic unit in itself, whereby the character is the abstract idea of a letter and the glyph is its concrete graphic representation. You can find a lot of information on typographic metrics on this website → It can be recommended to take a look at this page in any case, because the content especially supports the understanding of the many terms of typographic metrics.

Since text dimensions are specified in user-space coordinates, these are usually - but not always - independent of the current transformation matrix. For example, if you call the Cairo.Scale (2.0, 2.0) method, the text will be drawn twice as large - but the determined text size will not be doubled. Example

The example demonstrates the use of all properties of the CairoTextExtents class and the reading of the values for these properties:

Private Sub GeneratePDF()
  Dim PDFSurface As CairoPdfSurface
  Dim fXOffset As Float = 20
  Dim fYOffset As Float = 20
  PDFSurface = New CairoPdfSurface(sPfadPDFDatei, 210, 297) ' → DIN A4-Format
    Cairo.Matrix = Cairo.Matrix.Translate(MMToPoints(fXOffset), MMToPoints(fYOffset))
    Cairo.Matrix = Cairo.Matrix.Scale(1, 1) '-- Zoom factor = 1  
    Cairo.AntiAlias = False
    Line(MMToPoints(0), MMToPoints(0), MMToPoints(0), MMToPoints(297 - fYOffset), 0.1, [1, 1], Color.Red)
    Line(MMToPoints(0), MMToPoints(0), MMToPoints(210 - fXOffset), MMToPoints(0), 0.1, [1, 1], Color.Red)
'-- TEXT
    Cairo.Source = Cairo.ColorPattern(Color.DarkBlue) 
    Cairo.Font.Name = "Arial"
    Cairo.Font.Size = 100
    Cairo.Font.Bold = True
    Print "TEXT"
    Print "----------------------------------"
    Print "Height = ", PointsToMM(Cairo.TextExtents("Ärger").Height)
    Print "Width = ", PointsToMM(Cairo.TextExtents("Ärger").Width)
    Print "XAdvance = ", PointsToMM(Cairo.TextExtents("Ärger").XAdvance)
    Print "YAdvance = ", PointsToMM(Cairo.TextExtents("Ärger").YAdvance)
    Print "XBearing = ", PointsToMM(Cairo.TextExtents("Ärger").XBearing)
    Print "YBearing = ", PointsToMM(Cairo.TextExtents("Ärger").YBearing)
    Cairo.MoveTo(MMToPoints(0), MMToPoints(50))
Private Function MMToPoints(Value As Float) As Float
  Return Value * 2.83527
Private Function PointsToMM(Value As Float) As Float
  Return Value * 0.3527
Private Sub Line(Xa As Float, Ya As Float, Xe As Float, Ye As Float, fWidth As Float, Optional fDash As Float[], Optional cColor As Integer)
'-- Coloured line from point A to point E - A(xa|ya), E(xe|ye) - in millimetres!
    Cairo.MoveTo(MMToPoints(Xa), MMToPoints(Ya))
    Cairo.LineTo(MMToPoints(Xe), MMToPoints(Ye))
    Cairo.Source = Cairo.ColorPattern(cColor)
    Cairo.LineWidth = fWidth
    Cairo.Dash = fDash
    Cairo.Dash = Null

With the above source code excerpt, this output - rounded and provided with the unit millimetre - results in the console of the IDE:

Height   = 	38,39 mm
Width    = 	94,53 mm
XAdvance = 	94,08 mm
YAdvance = 	0 mm
XBearing = 	0 mm
YBearing = 	-30,97


  • Using the two functions MMToPoints(Value As Float) and PointsToMM(Value As Float), you can easily convert user coordinates to millimetres and coordinates in millimetres to user coordinates.
  • If you print out the generated PDF file and draw the (fictitious) bounding box specified in → Figure for the word 'Trouble' and measure the height, width and the dimension |YBearing| above the BaseLine, you will obtain the calculated values in the above overview with sufficient accuracy.
  • Please note that the value yBearing is negative!
The website uses a temporary session cookie. This technically necessary cookie is deleted when the browser is closed. You can find information on cookies in our privacy policy.
k25/k25.1.7/start.txt · Last modified: 20.02.2024 by emma

Page Tools