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:
Property | Description |
---|---|
Height | Specifies the height of the glyphs - as they are drawn. |
Width | Specifies the width of the glyphs - as they are drawn. |
YBearing | Specifies 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. |
XAdvance | Specifies the spacing in the x-direction after drawing the glyphs. |
XBearing | Specifies 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. |
YAdvance | Specifies the distance in the y-direction after drawing these glyphs. The value is zero for a horizontal layout. |
Table 25.1.7.1.1 : Properties of the CairoTextExtents class
Comment:
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: