cairoScaledFontTextToGlyphs: cairoScaledFontTextToGlyphs
In RGtk2: R Bindings for Gtk 2.8.0 and Above

Description Usage Arguments Details Value Author(s)

Converts UTF-8 text to a list of glyphs, optionally with cluster mapping, that can be used to render later using scaled.font.

1	cairoScaledFontTextToGlyphs(scaled.font, x, y, utf8, utf8.len = -1)

`scaled.font`	[`CairoScaledFont`] a `CairoScaledFont`
`x`	[numeric] X position to place first glyph
`y`	[numeric] Y position to place first glyph
`utf8`	[char] a string of text encoded in UTF-8
`utf8.len`	[integer] length of `utf8` in bytes, or -1 if it is NUL-terminated

If glyphs initially points to a non-NULL value, that list is used as a glyph buffer, and num.glyphs should point to the number of glyph entries available there. If the provided glyph list is too short for the conversion, Upon return, num.glyphs always contains the number of generated glyphs. If the value glyphs points to has changed after the call, This may happen even if the provided array was large enough.

If clusters is not NULL, num.clusters and cluster.flags should not be NULL, and cluster mapping will be computed. The semantics of how cluster list allocation works is similar to the glyph array. That is, if clusters initially points to a non-NULL value, that list is used as a cluster buffer, and num.clusters should point to the number of cluster entries available there. If the provided cluster list is too short for the conversion, Upon return, num.clusters always contains the number of generated clusters. If the value clusters points at has changed after the call, This may happen even if the provided array was large enough.

In the simplest case, glyphs and clusters can point to NULL initially and a suitable list will be allocated. In code:

glyphs <- scaled_font$textToGlyphs(x, y, utf8, utf8_len)

if (glyphs$retval == CairoStatus["success"])
  cr$showTextGlyphs(utf8, utf8_len,
                    glyphs$glyphs, glyphs$num_glyphs,
                    glyphs$clusters, glyphs$num_clusters,
                    glyphs$cluster_flags)

If no cluster mapping is needed:

glyphs <- scaled_font$textToGlyphs(x, y, utf8, utf8_len)

if (glyphs$retval == CairoStatus["success"]) {
  cr$showGlyphs(glyphs$glyphs, glyphs$num_glyphs)
}

If stack-based glyph and cluster lists are to be used for small arrays:

## R user obviously does not allocate things on the stack.
## This is the same as the first example.

glyphs <- scaled_font$textToGlyphs(x, y, utf8, utf8_len)

if (glyphs$retval == CairoStatus["success"])
  cr$showTextGlyphs(utf8, utf8_len,
                    glyphs$glyphs, glyphs$num_glyphs,
                    glyphs$clusters, glyphs$num_clusters,
                    glyphs$cluster_flags)

For details of how clusters, num.clusters, and cluster.flags map input UTF-8 text to the output glyphs see cairoShowTextGlyphs.

The output values can be readily passed to cairoShowTextGlyphs cairoShowGlyphs, or related functions, assuming that the exact same scaled.font is used for the operation. Since 1.8

A list containing the following elements:

`retval`	[`CairoStatus`] `CAIRO_STATUS_SUCCESS` upon success, or an error status if the input values are wrong or if conversion failed. If the input values are correct but the conversion failed, the error status is also set on `scaled.font`.
`glyphs`	[`CairoGlyph`] pointer to list of glyphs to fill
`num.glyphs`	[integer] pointer to number of glyphs
`clusters`	[`CairoTextCluster`] pointer to list of cluster mapping information to fill, or `NULL`
`num.clusters`	[integer] pointer to number of clusters, or `NULL`
`cluster.flags`	[`CairoTextClusterFlags`] pointer to location to store cluster flags corresponding to the output `clusters`, or `NULL`