GAMBAS BOOK 3.19.1

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 25.1.7.1.1.

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.

25.1.7.1 Properties

Figure 25.1.7.1.1: Fictitious text bounding box (bounding box)

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

Table 25.1.7.1.1 : Properties of the CairoTextExtents class

Comment:

• 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.

Under the → link http://en.wikipedia.org/wiki/Glyph 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 → http://www.freetype.org/freetype2/docs/glyphs/glyphs-3.html. 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.

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.Begin(PDFSurface)    
    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)
    Cairo.Stroke()
 
'-- TEXT
    Cairo.Source = Cairo.ColorPattern(Color.DarkBlue) 
    Cairo.Font.Name = "Arial"
    Cairo.Font.Size = 100
    Cairo.Font.Bold = True
 
    Print
    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))
 
    Cairo.DrawText("Ärger")
 
  Cairo.End()
 
  PDFSurface.Finish()
  Desktop.Open(sPfadPDFDatei)
 
End
 
Private Function MMToPoints(Value As Float) As Float
  Return Value * 2.83527
End
 
Private Function PointsToMM(Value As Float) As Float
  Return Value * 0.3527
End
 
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.Stroke()
    Cairo.Dash = Null
 
End

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

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

Comment:

• 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 25.1.7.1.1 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!