Legend:
Library
Module
Module type
Parameter
Class
Class type
Library
Module
Module type
Parameter
Class
Class type
This is Cairo low-level text API. The low-level API relies on the user to convert text to a set of glyph indexes and positions. This is a very hard problem and is best handled by external libraries, like the pangocairo that is part of the Pango text layout and rendering library. Pango is available from http://www.pango.org/
See also the "Toy" text API.
type t = {
index : int;
glyph index in the font. The exact interpretation of the glyph index depends on the font technology being used.
*)x : float;
the offset in the X direction between the origin used for drawing or measuring the string and the origin of this glyph.
*)y : float;
the offset in the Y direction between the origin used for drawing or measuring the string and the origin of this glyph.
*)}
The Glyph.t
structure holds information about a single glyph when drawing or measuring text. A font is (in simple terms) a collection of shapes used to draw text. A glyph is one of these shapes. There can be multiple glyphs for a single character (alternates to be used in different contexts, for example), or a glyph can be a ligature of multiple characters. Cairo doesn't expose any way of converting input text into glyphs, so in order to use the Cairo interfaces that take arrays of glyphs, you must directly access the appropriate underlying font system.
Note that the offsets given by x and y are not cumulative. When drawing or measuring text, each glyph is individually positioned with respect to the overall origin.
type cluster = {
num_bytes : int;
the number of bytes of UTF-8 text covered by cluster
*)num_glyphs : int;
the number of glyphs covered by cluster
*)}
The cluster
record holds information about a single text cluster. A text cluster is a minimal mapping of some glyphs corresponding to some UTF-8 text.
For a cluster to be valid, both num_bytes
and num_glyphs
should be non-negative, and at least one should be non-zero. Note that clusters with zero glyphs are not as well supported as normal clusters. For example, PDF rendering applications typically ignore those clusters when PDF text is being selected.
See Cairo.Glyph.show_text
for how clusters are used in advanced text operations.
val extents : context -> t array -> text_extents
Gets the extents for an array of glyphs. The extents describe a user-space rectangle that encloses the "inked" portion of the glyphs (as they would be drawn by Cairo.Glyph.show
). Additionally, the x_advance
and y_advance
values indicate the amount by which the current point would be advanced by Cairo.Glyph.show
.
Note that whitespace glyphs do not contribute to the size of the rectangle (extents.width and extents.height).
A drawing operator that generates the shape from an array of glyphs, rendered according to the current font face, font size (font matrix), and font options.
val show_text :
context ->
string ->
t array ->
cluster array ->
cluster_flags ->
unit
show_text cr utf8 glyphs clusters cluster_flags
: This operation has rendering effects similar to Cairo.Glyph.show
but, if the target surface supports it, uses the provided text and cluster mapping to embed the text for the glyphs shown in the output. If the target does not support the extended attributes, this function acts like the basic Cairo.Glyph.show
as if it had been passed glyphs
.
The mapping between utf8
and glyphs
is provided by an array of clusters
. Each cluster covers a number of text bytes and glyphs, and neighboring clusters cover neighboring areas of utf8
and glyphs
. The clusters should collectively cover utf8
and glyphs
in entirety.
The first cluster always covers bytes from the beginning of utf8
. If cluster_flags
do not have the BACKWARD
set, the first cluster also covers the beginning of glyphs, otherwise it covers the end of the glyphs array and following clusters move backward.
See Cairo.Glyph.cluster
for constraints on valid clusters.