diff options
Diffstat (limited to 'pango/pango-context.c')
| -rw-r--r-- | pango/pango-context.c | 687 |
1 files changed, 344 insertions, 343 deletions
diff --git a/pango/pango-context.c b/pango/pango-context.c index ec1014fa..1db11a1c 100644 --- a/pango/pango-context.c +++ b/pango/pango-context.c @@ -10,7 +10,7 @@ * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public @@ -19,18 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:main - * @title:Rendering - * @short_description:Functions to run the rendering pipeline - * - * The Pango rendering pipeline takes a string of - * Unicode characters and converts it into glyphs. - * The functions described in this section accomplish - * various steps of this process. - * - *  - */ #include "config.h" #include <string.h> #include <stdlib.h> @@ -45,21 +33,16 @@ #include "pango-emoji-private.h" /** - * SECTION:context - * @title:Contexts - * @short_description: Global context object - * - * The #PangoContext structure stores global information - * influencing Pango's operation, such as the fontmap used - * to look up fonts, and default values such as the default - * language, default gravity, or default font. - */ - -/** * PangoContext: * - * The #PangoContext structure stores global information - * used to control the itemization process. + * A `PangoContext` stores global information used to control the + * itemization process. + * + * The information stored by `PangoContext includes the fontmap used + * to look up fonts, and default values such as the default language, + * default gravity, or default font. + * + * To obtain a `PangoContext`, use [method@Pango.FontMap.create_context]. */ struct _PangoContext { @@ -144,21 +127,21 @@ pango_context_finalize (GObject *object) /** * pango_context_new: * - * Creates a new #PangoContext initialized to default values. + * Creates a new `PangoContext` initialized to default values. * * This function is not particularly useful as it should always - * be followed by a pango_context_set_font_map() call, and the - * function pango_font_map_create_context() does these two steps + * be followed by a [method@Pango.Context.set_font_map] call, and the + * function [method@Pango.FontMap.create_context] does these two steps * together and hence users are recommended to use that. * * If you are using Pango as part of a higher-level system, - * that system may have it's own way of create a #PangoContext. - * For instance, the GTK+ toolkit has, among others, - * gtk_widget_get_pango_context(). Use those instead. + * that system may have it's own way of create a `PangoContext`. + * For instance, the GTK toolkit has, among others, + * `gtk_widget_get_pango_context()`. Use those instead. * - * Return value: the newly allocated #PangoContext, which should - * be freed with g_object_unref(). - **/ + * Return value: the newly allocated `PangoContext`, which should + * be freed with g_object_unref(). + */ PangoContext * pango_context_new (void) { @@ -180,22 +163,24 @@ update_resolved_gravity (PangoContext *context) /** * pango_context_set_matrix: - * @context: a #PangoContext - * @matrix: (allow-none): a #PangoMatrix, or %NULL to unset any existing + * @context: a `PangoContext` + * @matrix: (allow-none): a `PangoMatrix`, or %NULL to unset any existing * matrix. (No matrix set is the same as setting the identity matrix.) * * Sets the transformation matrix that will be applied when rendering - * with this context. Note that reported metrics are in the user space - * coordinates before the application of the matrix, not device-space - * coordinates after the application of the matrix. So, they don't scale - * with the matrix, though they may change slightly for different - * matrices, depending on how the text is fit to the pixel grid. + * with this context. + * + * Note that reported metrics are in the user space coordinates before + * the application of the matrix, not device-space coordinates after the + * application of the matrix. So, they don't scale with the matrix, though + * they may change slightly for different matrices, depending on how the + * text is fit to the pixel grid. * * Since: 1.6 - **/ + */ void -pango_context_set_matrix (PangoContext *context, - const PangoMatrix *matrix) +pango_context_set_matrix (PangoContext *context, + const PangoMatrix *matrix) { g_return_if_fail (PANGO_IS_CONTEXT (context)); @@ -214,17 +199,19 @@ pango_context_set_matrix (PangoContext *context, /** * pango_context_get_matrix: - * @context: a #PangoContext + * @context: a `PangoContext` * * Gets the transformation matrix that will be applied when - * rendering with this context. See pango_context_set_matrix(). + * rendering with this context. + * + * See [method@Pango.Context.set_matrix]. * * Return value: (nullable): the matrix, or %NULL if no matrix has - * been set (which is the same as the identity matrix). The returned - * matrix is owned by Pango and must not be modified or freed. + * been set (which is the same as the identity matrix). The returned + * matrix is owned by Pango and must not be modified or freed. * * Since: 1.6 - **/ + */ const PangoMatrix * pango_context_get_matrix (PangoContext *context) { @@ -235,16 +222,19 @@ pango_context_get_matrix (PangoContext *context) /** * pango_context_set_font_map: - * @context: a #PangoContext - * @font_map: the #PangoFontMap to set. + * @context: a `PangoContext` + * @font_map: the `PangoFontMap` to set. * - * Sets the font map to be searched when fonts are looked-up in this context. - * This is only for internal use by Pango backends, a #PangoContext obtained - * via one of the recommended methods should already have a suitable font map. - **/ + * Sets the font map to be searched when fonts are looked-up + * in this context. + * + * This is only for internal use by Pango backends, a `PangoContext` + * obtained via one of the recommended methods should already have a + * suitable font map. + */ void pango_context_set_font_map (PangoContext *context, - PangoFontMap *font_map) + PangoFontMap *font_map) { g_return_if_fail (PANGO_IS_CONTEXT (context)); g_return_if_fail (!font_map || PANGO_IS_FONT_MAP (font_map)); @@ -266,15 +256,15 @@ pango_context_set_font_map (PangoContext *context, /** * pango_context_get_font_map: - * @context: a #PangoContext + * @context: a `PangoContext` * - * Gets the #PangoFontMap used to look up fonts for this context. + * Gets the `PangoFontMap` used to look up fonts for this context. * - * Return value: (transfer none): the font map for the #PangoContext. - * This value is owned by Pango and should not be unreferenced. + * Return value: (transfer none): the font map for the `PangoContext`. + * This value is owned by Pango and should not be unreferenced. * * Since: 1.6 - **/ + */ PangoFontMap * pango_context_get_font_map (PangoContext *context) { @@ -285,18 +275,18 @@ pango_context_get_font_map (PangoContext *context) /** * pango_context_list_families: - * @context: a #PangoContext - * @families: (out) (array length=n_families) (transfer container): location to store a pointer to - * an array of #PangoFontFamily *. This array should be freed - * with g_free(). + * @context: a `PangoContext` + * @families: (out) (array length=n_families) (transfer container): location + * to store a pointer to an array of `PangoFontFamily`. This array should + * be freed with g_free(). * @n_families: (out): location to store the number of elements in @descs * * List all families for a context. - **/ + */ void -pango_context_list_families (PangoContext *context, - PangoFontFamily ***families, - int *n_families) +pango_context_list_families (PangoContext *context, + PangoFontFamily ***families, + int *n_families) { g_return_if_fail (context != NULL); g_return_if_fail (families == NULL || n_families != NULL); @@ -308,7 +298,7 @@ pango_context_list_families (PangoContext *context, { *n_families = 0; if (families) - *families = NULL; + *families = NULL; return; } @@ -318,18 +308,18 @@ pango_context_list_families (PangoContext *context, /** * pango_context_load_font: - * @context: a #PangoContext - * @desc: a #PangoFontDescription describing the font to load + * @context: a `PangoContext` + * @desc: a `PangoFontDescription` describing the font to load * * Loads the font in one of the fontmaps in the context * that is the closest match for @desc. * - * Returns: (transfer full) (nullable): the newly allocated #PangoFont - * that was loaded, or %NULL if no font matched. - **/ + * Returns: (transfer full) (nullable): the newly allocated `PangoFont` + * that was loaded, or %NULL if no font matched. + */ PangoFont * pango_context_load_font (PangoContext *context, - const PangoFontDescription *desc) + const PangoFontDescription *desc) { g_return_val_if_fail (context != NULL, NULL); g_return_val_if_fail (context->font_map != NULL, NULL); @@ -339,20 +329,20 @@ pango_context_load_font (PangoContext *context, /** * pango_context_load_fontset: - * @context: a #PangoContext - * @desc: a #PangoFontDescription describing the fonts to load - * @language: a #PangoLanguage the fonts will be used for + * @context: a `PangoContext` + * @desc: a `PangoFontDescription` describing the fonts to load + * @language: a `PangoLanguage` the fonts will be used for * * Load a set of fonts in the context that can be used to render * a font matching @desc. * * Returns: (transfer full) (nullable): the newly allocated - * #PangoFontset loaded, or %NULL if no font matched. - **/ + * `PangoFontset` loaded, or %NULL if no font matched. + */ PangoFontset * pango_context_load_fontset (PangoContext *context, - const PangoFontDescription *desc, - PangoLanguage *language) + const PangoFontDescription *desc, + PangoLanguage *language) { g_return_val_if_fail (context != NULL, NULL); @@ -361,14 +351,14 @@ pango_context_load_fontset (PangoContext *context, /** * pango_context_set_font_description: - * @context: a #PangoContext + * @context: a `PangoContext` * @desc: the new pango font description * * Set the default font description for the context - **/ + */ void pango_context_set_font_description (PangoContext *context, - const PangoFontDescription *desc) + const PangoFontDescription *desc) { g_return_if_fail (context != NULL); g_return_if_fail (desc != NULL); @@ -385,13 +375,13 @@ pango_context_set_font_description (PangoContext *context, /** * pango_context_get_font_description: - * @context: a #PangoContext + * @context: a `PangoContext` * * Retrieve the default font description for the context. * * Return value: (transfer none): a pointer to the context's default font - * description. This value must not be modified or freed. - **/ + * description. This value must not be modified or freed. + */ PangoFontDescription * pango_context_get_font_description (PangoContext *context) { @@ -402,16 +392,17 @@ pango_context_get_font_description (PangoContext *context) /** * pango_context_set_language: - * @context: a #PangoContext + * @context: a `PangoContext` * @language: the new language tag. * - * Sets the global language tag for the context. The default language - * for the locale of the running process can be found using - * pango_language_get_default(). - **/ + * Sets the global language tag for the context. + * + * The default language for the locale of the running process + * can be found using [type_func@Pango.Language.get_default]. + */ void -pango_context_set_language (PangoContext *context, - PangoLanguage *language) +pango_context_set_language (PangoContext *context, + PangoLanguage *language) { g_return_if_fail (context != NULL); @@ -427,12 +418,12 @@ pango_context_set_language (PangoContext *context, /** * pango_context_get_language: - * @context: a #PangoContext + * @context: a `PangoContext` * * Retrieves the global language tag for the context. * * Return value: the global language tag. - **/ + */ PangoLanguage * pango_context_get_language (PangoContext *context) { @@ -443,7 +434,7 @@ pango_context_get_language (PangoContext *context) /** * pango_context_set_base_dir: - * @context: a #PangoContext + * @context: a `PangoContext` * @direction: the new base direction * * Sets the base direction for the context. @@ -451,13 +442,13 @@ pango_context_get_language (PangoContext *context) * The base direction is used in applying the Unicode bidirectional * algorithm; if the @direction is %PANGO_DIRECTION_LTR or * %PANGO_DIRECTION_RTL, then the value will be used as the paragraph - * direction in the Unicode bidirectional algorithm. A value of + * direction in the Unicode bidirectional algorithm. A value of * %PANGO_DIRECTION_WEAK_LTR or %PANGO_DIRECTION_WEAK_RTL is used only * for paragraphs that do not contain any strong characters themselves. - **/ + */ void -pango_context_set_base_dir (PangoContext *context, - PangoDirection direction) +pango_context_set_base_dir (PangoContext *context, + PangoDirection direction) { g_return_if_fail (context != NULL); @@ -469,13 +460,14 @@ pango_context_set_base_dir (PangoContext *context, /** * pango_context_get_base_dir: - * @context: a #PangoContext + * @context: a `PangoContext` + * + * Retrieves the base direction for the context. * - * Retrieves the base direction for the context. See - * pango_context_set_base_dir(). + * See [method@Pango.Context.set_base_dir]. * * Return value: the base direction for the context. - **/ + */ PangoDirection pango_context_get_base_dir (PangoContext *context) { @@ -486,7 +478,7 @@ pango_context_get_base_dir (PangoContext *context) /** * pango_context_set_base_gravity: - * @context: a #PangoContext + * @context: a `PangoContext` * @gravity: the new base gravity * * Sets the base gravity for the context. @@ -494,10 +486,10 @@ pango_context_get_base_dir (PangoContext *context) * The base gravity is used in laying vertical text out. * * Since: 1.16 - **/ + */ void -pango_context_set_base_gravity (PangoContext *context, - PangoGravity gravity) +pango_context_set_base_gravity (PangoContext *context, + PangoGravity gravity) { g_return_if_fail (context != NULL); @@ -511,15 +503,16 @@ pango_context_set_base_gravity (PangoContext *context, /** * pango_context_get_base_gravity: - * @context: a #PangoContext + * @context: a `PangoContext` + * + * Retrieves the base gravity for the context. * - * Retrieves the base gravity for the context. See - * pango_context_set_base_gravity(). + * See [method@Pango.Context.set_base_gravity]. * * Return value: the base gravity for the context. * * Since: 1.16 - **/ + */ PangoGravity pango_context_get_base_gravity (PangoContext *context) { @@ -530,17 +523,19 @@ pango_context_get_base_gravity (PangoContext *context) /** * pango_context_get_gravity: - * @context: a #PangoContext + * @context: a `PangoContext` + * + * Retrieves the gravity for the context. * - * Retrieves the gravity for the context. This is similar to - * pango_context_get_base_gravity(), except for when the base gravity - * is %PANGO_GRAVITY_AUTO for which pango_gravity_get_for_matrix() is used - * to return the gravity from the current context matrix. + * This is similar to [method@Pango.Context.get_base_gravity], + * except for when the base gravity is %PANGO_GRAVITY_AUTO for + * which [type_func@Pango.Gravity.get_for_matrix] is used to return the + * gravity from the current context matrix. * * Return value: the resolved gravity for the context. * * Since: 1.16 - **/ + */ PangoGravity pango_context_get_gravity (PangoContext *context) { @@ -551,20 +546,21 @@ pango_context_get_gravity (PangoContext *context) /** * pango_context_set_gravity_hint: - * @context: a #PangoContext + * @context: a `PangoContext` * @hint: the new gravity hint * * Sets the gravity hint for the context. * - * The gravity hint is used in laying vertical text out, and is only relevant - * if gravity of the context as returned by pango_context_get_gravity() - * is set %PANGO_GRAVITY_EAST or %PANGO_GRAVITY_WEST. + * The gravity hint is used in laying vertical text out, and + * is only relevant if gravity of the context as returned by + * [method@Pango.Context.get_gravity] is set to %PANGO_GRAVITY_EAST + * or %PANGO_GRAVITY_WEST. * * Since: 1.16 - **/ + */ void -pango_context_set_gravity_hint (PangoContext *context, - PangoGravityHint hint) +pango_context_set_gravity_hint (PangoContext *context, + PangoGravityHint hint) { g_return_if_fail (context != NULL); @@ -576,15 +572,16 @@ pango_context_set_gravity_hint (PangoContext *context, /** * pango_context_get_gravity_hint: - * @context: a #PangoContext + * @context: a `PangoContext` + * + * Retrieves the gravity hint for the context. * - * Retrieves the gravity hint for the context. See - * pango_context_set_gravity_hint() for details. + * See [method@Pango.Context.set_gravity_hint] for details. * * Return value: the gravity hint for the context. * * Since: 1.16 - **/ + */ PangoGravityHint pango_context_get_gravity_hint (PangoContext *context) { @@ -597,7 +594,7 @@ pango_context_get_gravity_hint (PangoContext *context) static gboolean advance_attr_iterator_to (PangoAttrIterator *iterator, - int start_index) + int start_index) { int start_range, end_range; @@ -606,13 +603,13 @@ advance_attr_iterator_to (PangoAttrIterator *iterator, while (start_index >= end_range) { if (!pango_attr_iterator_next (iterator)) - return FALSE; + return FALSE; pango_attr_iterator_range (iterator, &start_range, &end_range); } if (start_range > start_index) g_warning ("In pango_itemize(), the cached iterator passed in " - "had already moved beyond the start_index"); + "had already moved beyond the start_index"); return TRUE; } @@ -659,7 +656,7 @@ retry: { cache = g_slice_new (FontCache); cache->hash = g_hash_table_new_full (g_direct_hash, NULL, - NULL, (GDestroyNotify)font_element_destroy); + NULL, (GDestroyNotify)font_element_destroy); if (!g_object_replace_qdata (G_OBJECT (fontset), cache_quark, NULL, cache, (GDestroyNotify)font_cache_destroy, NULL)) @@ -674,8 +671,8 @@ retry: static gboolean font_cache_get (FontCache *cache, - gunichar wc, - PangoFont **font) + gunichar wc, + PangoFont **font) { FontElement *element; @@ -692,8 +689,8 @@ font_cache_get (FontCache *cache, static void font_cache_insert (FontCache *cache, - gunichar wc, - PangoFont *font) + gunichar wc, + PangoFont *font) { FontElement *element = g_slice_new (FontElement); element->font = font ? g_object_ref (font) : NULL; @@ -719,11 +716,11 @@ typedef struct _PangoWidthIter PangoWidthIter; struct _PangoWidthIter { - const gchar *text_start; - const gchar *text_end; - const gchar *start; - const gchar *end; - gboolean upright; + const gchar *text_start; + const gchar *text_end; + const gchar *start; + const gchar *end; + gboolean upright; }; typedef struct _ItemizeState ItemizeState; @@ -784,7 +781,7 @@ update_embedding_end (ItemizeState *state) { state->embedding = state->embedding_levels[state->embedding_end_offset]; while (state->embedding_end < state->end && - state->embedding_levels[state->embedding_end_offset] == state->embedding) + state->embedding_levels[state->embedding_end_offset] == state->embedding) { state->embedding_end_offset++; state->embedding_end = g_utf8_next_char (state->embedding_end); @@ -795,7 +792,7 @@ update_embedding_end (ItemizeState *state) static PangoAttribute * find_attribute (GSList *attr_list, - PangoAttrType type) + PangoAttrType type) { GSList *node; @@ -830,7 +827,7 @@ update_attr_iterator (ItemizeState *state) pango_font_description_free (state->font_desc); state->font_desc = pango_font_description_copy_static (state->context->font_desc); pango_attr_iterator_get_font (state->attr_iter, state->font_desc, - &state->lang, &state->extra_attrs); + &state->lang, &state->extra_attrs); if (pango_font_description_get_set_fields (state->font_desc) & PANGO_FONT_MASK_GRAVITY) state->font_desc_gravity = pango_font_description_get_gravity (state->font_desc); else @@ -971,7 +968,9 @@ width_iter_next(PangoWidthIter* iter) } static void -width_iter_init (PangoWidthIter* iter, const char* text, int length) +width_iter_init (PangoWidthIter *iter, + const char *text, + int length) { iter->text_start = text; iter->text_end = text + length; @@ -986,15 +985,15 @@ width_iter_fini (PangoWidthIter* iter) } static void -itemize_state_init (ItemizeState *state, - PangoContext *context, - const char *text, - PangoDirection base_dir, - int start_index, - int length, - PangoAttrList *attrs, - PangoAttrIterator *cached_iter, - const PangoFontDescription *desc) +itemize_state_init (ItemizeState *state, + PangoContext *context, + const char *text, + PangoDirection base_dir, + int start_index, + int length, + PangoAttrList *attrs, + PangoAttrIterator *cached_iter, + const PangoFontDescription *desc) { state->context = context; @@ -1059,7 +1058,7 @@ itemize_state_init (ItemizeState *state, */ _pango_script_iter_init (&state->script_iter, text + start_index, length); pango_script_iter_get_range (&state->script_iter, NULL, - &state->script_end, &state->script); + &state->script_end, &state->script); width_iter_init (&state->width_iter, text + start_index, length); _pango_emoji_iter_init (&state->emoji_iter, text + start_index, length); @@ -1110,7 +1109,7 @@ itemize_state_next (ItemizeState *state) { pango_script_iter_next (&state->script_iter); pango_script_iter_get_range (&state->script_iter, NULL, - &state->script_end, &state->script); + &state->script_end, &state->script); state->changed |= SCRIPT_CHANGED; } if (state->run_end == state->emoji_iter.end) @@ -1146,7 +1145,7 @@ copy_attr_slist (GSList *attr_slist) static void itemize_state_fill_font (ItemizeState *state, - PangoFont *font) + PangoFont *font) { GList *l; @@ -1156,33 +1155,33 @@ itemize_state_fill_font (ItemizeState *state, if (item->analysis.font) break; if (font) - item->analysis.font = g_object_ref (font); + item->analysis.font = g_object_ref (font); } } static void itemize_state_add_character (ItemizeState *state, - PangoFont *font, - gboolean force_break, - const char *pos) + PangoFont *font, + gboolean force_break, + const char *pos) { if (state->item) { if (!state->item->analysis.font && font) - { - itemize_state_fill_font (state, font); - } + { + itemize_state_fill_font (state, font); + } else if (state->item->analysis.font && !font) - { - font = state->item->analysis.font; - } + { + font = state->item->analysis.font; + } if (!force_break && - state->item->analysis.font == font) - { - state->item->num_chars++; - return; - } + state->item->analysis.font == font) + { + state->item->num_chars++; + return; + } state->item->length = (pos - state->text) - state->item->offset; } @@ -1200,15 +1199,15 @@ itemize_state_add_character (ItemizeState *state, state->item->analysis.gravity = state->resolved_gravity; /* The level vs. gravity dance: - * - If gravity is SOUTH, leave level untouched. - * - If gravity is NORTH, step level one up, to - * not get mirrored upside-down text. - * - If gravity is EAST, step up to an even level, as - * it's a clockwise-rotated layout, so the rotated - * top is unrotated left. - * - If gravity is WEST, step up to an odd level, as - * it's a counter-clockwise-rotated layout, so the rotated - * top is unrotated right. + * - If gravity is SOUTH, leave level untouched. + * - If gravity is NORTH, step level one up, to + * not get mirrored upside-down text. + * - If gravity is EAST, step up to an even level, as + * it's a clockwise-rotated layout, so the rotated + * top is unrotated left. + * - If gravity is WEST, step up to an odd level, as + * it's a counter-clockwise-rotated layout, so the rotated + * top is unrotated right. * * A similar dance is performed in pango-layout.c: * line_set_resolved_dir(). Keep in synch. @@ -1217,17 +1216,17 @@ itemize_state_add_character (ItemizeState *state, { case PANGO_GRAVITY_SOUTH: default: - break; + break; case PANGO_GRAVITY_NORTH: - state->item->analysis.level++; - break; + state->item->analysis.level++; + break; case PANGO_GRAVITY_EAST: - state->item->analysis.level += 1; - state->item->analysis.level &= ~1; - break; + state->item->analysis.level += 1; + state->item->analysis.level &= ~1; + break; case PANGO_GRAVITY_WEST: - state->item->analysis.level |= 1; - break; + state->item->analysis.level |= 1; + break; } state->item->analysis.flags = state->centered_baseline ? PANGO_ANALYSIS_FLAG_CENTERED_BASELINE : 0; @@ -1256,8 +1255,8 @@ typedef struct { static gboolean get_font_foreach (PangoFontset *fontset, - PangoFont *font, - gpointer data) + PangoFont *font, + gpointer data) { GetFontInfo *info = data; @@ -1284,8 +1283,8 @@ get_base_font (ItemizeState *state) { if (!state->base_font) state->base_font = pango_font_map_load_font (state->context->font_map, - state->context, - state->font_desc); + state->context, + state->font_desc); return state->base_font; } @@ -1321,7 +1320,7 @@ get_font (ItemizeState *state, static PangoLanguage * compute_derived_language (PangoLanguage *lang, - PangoScript script) + PangoScript script) { PangoLanguage *derived_lang; @@ -1342,7 +1341,7 @@ compute_derived_language (PangoLanguage *lang, * safe here, though Keith Packard claims it is. */ if (!derived_lang) - derived_lang = pango_language_from_string ("xx"); + derived_lang = pango_language_from_string ("xx"); } return derived_lang; @@ -1357,28 +1356,28 @@ itemize_state_update_for_new_run (ItemizeState *state) { /* Font-desc gravity overrides everything */ if (state->font_desc_gravity != PANGO_GRAVITY_AUTO) - { - state->resolved_gravity = state->font_desc_gravity; - } + { + state->resolved_gravity = state->font_desc_gravity; + } else - { - PangoGravity gravity = state->gravity; - PangoGravityHint gravity_hint = state->gravity_hint; + { + PangoGravity gravity = state->gravity; + PangoGravityHint gravity_hint = state->gravity_hint; - if (G_LIKELY (gravity == PANGO_GRAVITY_AUTO)) - gravity = state->context->resolved_gravity; + if (G_LIKELY (gravity == PANGO_GRAVITY_AUTO)) + gravity = state->context->resolved_gravity; - state->resolved_gravity = pango_gravity_get_for_script_and_width (state->script, - state->width_iter.upright, - gravity, - gravity_hint); - } + state->resolved_gravity = pango_gravity_get_for_script_and_width (state->script, + state->width_iter.upright, + gravity, + gravity_hint); + } if (state->font_desc_gravity != state->resolved_gravity) - { - pango_font_description_set_gravity (state->font_desc, state->resolved_gravity); - state->changed |= FONT_CHANGED; - } + { + pango_font_description_set_gravity (state->font_desc, state->resolved_gravity); + state->changed |= FONT_CHANGED; + } } if (state->changed & (SCRIPT_CHANGED | LANG_CHANGED)) @@ -1386,7 +1385,7 @@ itemize_state_update_for_new_run (ItemizeState *state) PangoLanguage *old_derived_lang = state->derived_lang; state->derived_lang = compute_derived_language (state->lang, state->script); if (old_derived_lang != state->derived_lang) - state->changed |= DERIVED_LANG_CHANGED; + state->changed |= DERIVED_LANG_CHANGED; } if (state->changed & (EMOJI_CHANGED)) @@ -1411,9 +1410,9 @@ itemize_state_update_for_new_run (ItemizeState *state) pango_font_description_set_family_static (state->emoji_font_desc, "emoji"); } state->current_fonts = pango_font_map_load_fontset (state->context->font_map, - state->context, - is_emoji ? state->emoji_font_desc : state->font_desc, - state->derived_lang); + state->context, + is_emoji ? state->emoji_font_desc : state->font_desc, + state->derived_lang); state->cache = get_font_cache (state->current_fonts); } @@ -1470,16 +1469,16 @@ itemize_state_process_run (ItemizeState *state) (wc >= 0xfe00u && wc <= 0xfe0fu) || (wc >= 0xe0100u && wc <= 0xe01efu))) { - font = NULL; + font = NULL; } else { - get_font (state, wc, &font); - } + get_font (state, wc, &font); + } itemize_state_add_character (state, font, - is_forced_break || last_was_forced_break, - p); + is_forced_break || last_was_forced_break, + p); last_was_forced_break = is_forced_break; } @@ -1534,35 +1533,36 @@ itemize_state_finish (ItemizeState *state) /** * pango_itemize_with_base_dir: - * @context: a structure holding information that affects - * the itemization process. - * @base_dir: base direction to use for bidirectional processing - * @text: the text to itemize. + * @context: a structure holding information that affects + * the itemization process. + * @base_dir: base direction to use for bidirectional processing + * @text: the text to itemize. * @start_index: first byte in @text to process - * @length: the number of bytes (not characters) to process - * after @start_index. This must be >= 0. - * @attrs: the set of attributes that apply to @text. + * @length: the number of bytes (not characters) to process + * after @start_index. This must be >= 0. + * @attrs: the set of attributes that apply to @text. * @cached_iter: (allow-none): Cached attribute iterator, or %NULL * - * Like pango_itemize(), but the base direction to use when - * computing bidirectional levels (see pango_context_set_base_dir ()), - * is specified explicitly rather than gotten from the #PangoContext. + * Like `pango_itemize()`, but with an explicitly specified base direction. * - * Return value: (transfer full) (element-type Pango.Item): a #GList of - * #PangoItem structures. The items should be freed using - * pango_item_free() probably in combination with - * g_list_foreach(), and the list itself using g_list_free(). + * The base direction is used when computing bidirectional levels. + * (see [method@Pango.Context.set_base_dir]). [func@itemize] gets the + * base direction from the `PangoContext`. + * + * Return value: (transfer full) (element-type Pango.Item): a `GList` of + * [struct@Pango.Item] structures. The items should be freed using + * [method@Pango.Item.free] probably in combination with g_list_free_full(). * * Since: 1.4 */ GList * pango_itemize_with_base_dir (PangoContext *context, - PangoDirection base_dir, - const char *text, - int start_index, - int length, - PangoAttrList *attrs, - PangoAttrIterator *cached_iter) + PangoDirection base_dir, + const char *text, + int start_index, + int length, + PangoAttrList *attrs, + PangoAttrIterator *cached_iter) { ItemizeState state; @@ -1575,7 +1575,7 @@ pango_itemize_with_base_dir (PangoContext *context, return NULL; itemize_state_init (&state, context, text, base_dir, start_index, length, - attrs, cached_iter, NULL); + attrs, cached_iter, NULL); do itemize_state_process_run (&state); @@ -1588,10 +1588,10 @@ pango_itemize_with_base_dir (PangoContext *context, static GList * itemize_with_font (PangoContext *context, - const char *text, - int start_index, - int length, - const PangoFontDescription *desc) + const char *text, + int start_index, + int length, + const PangoFontDescription *desc) { ItemizeState state; @@ -1599,7 +1599,7 @@ itemize_with_font (PangoContext *context, return NULL; itemize_state_init (&state, context, text, context->base_dir, start_index, length, - NULL, NULL, desc); + NULL, NULL, desc); do itemize_state_process_run (&state); @@ -1612,39 +1612,39 @@ itemize_with_font (PangoContext *context, /** * pango_itemize: - * @context: a structure holding information that affects - the itemization process. - * @text: the text to itemize. Must be valid UTF-8 + * @context: a structure holding information that affects + * the itemization process. + * @text: the text to itemize. Must be valid UTF-8 * @start_index: first byte in @text to process - * @length: the number of bytes (not characters) to process - * after @start_index. - * This must be >= 0. - * @attrs: the set of attributes that apply to @text. + * @length: the number of bytes (not characters) to process + * after @start_index. This must be >= 0. + * @attrs: the set of attributes that apply to @text. * @cached_iter: (allow-none): Cached attribute iterator, or %NULL * - * Breaks a piece of text into segments with consistent - * directional level and shaping engine. Each byte of @text will - * be contained in exactly one of the items in the returned list; - * the generated list of items will be in logical order (the start - * offsets of the items are ascending). - * - * @cached_iter should be an iterator over @attrs currently positioned at a - * range before or containing @start_index; @cached_iter will be advanced to - * the range covering the position just after @start_index + @length. - * (i.e. if itemizing in a loop, just keep passing in the same @cached_iter). - * - * Return value: (transfer full) (element-type Pango.Item): a #GList of #PangoItem - * structures. The items should be freed using pango_item_free() - * probably in combination with g_list_foreach(), and the list itself - * using g_list_free(). + * Breaks a piece of text into segments with consistent directional + * level and font. + * + * Each byte of @text will be contained in exactly one of the items in the + * returned list; the generated list of items will be in logical order (the + * start offsets of the items are ascending). + * + * @cached_iter should be an iterator over @attrs currently positioned + * at a range before or containing @start_index; @cached_iter will be + * advanced to the range covering the position just after + * @start_index + @length. (i.e. if itemizing in a loop, just keep passing + * in the same @cached_iter). + * + * Return value: (transfer full) (element-type Pango.Item): a `GList` of + * [struct@Pango.Item] structures. The items should be freed using + * [method@Pango.Item.free] probably in combination with g_list_free_full(). */ GList * pango_itemize (PangoContext *context, - const char *text, - int start_index, - int length, - PangoAttrList *attrs, - PangoAttrIterator *cached_iter) + const char *text, + int start_index, + int length, + PangoAttrList *attrs, + PangoAttrIterator *cached_iter) { g_return_val_if_fail (context != NULL, NULL); g_return_val_if_fail (start_index >= 0, NULL); @@ -1652,13 +1652,13 @@ pango_itemize (PangoContext *context, g_return_val_if_fail (length == 0 || text != NULL, NULL); return pango_itemize_with_base_dir (context, context->base_dir, - text, start_index, length, attrs, cached_iter); + text, start_index, length, attrs, cached_iter); } static gboolean get_first_metrics_foreach (PangoFontset *fontset, - PangoFont *font, - gpointer data) + PangoFont *font, + gpointer data) { PangoFontMetrics *fontset_metrics = data; PangoLanguage *language = PANGO_FONTSET_GET_CLASS (fontset)->get_language (fontset); @@ -1675,7 +1675,7 @@ get_first_metrics_foreach (PangoFontset *fontset, pango_font_metrics_unref (font_metrics); - return TRUE; /* Stops iteration */ + return TRUE; /* Stops iteration */ } static PangoFontMetrics * @@ -1691,10 +1691,10 @@ get_base_metrics (PangoFontset *fontset) static void update_metrics_from_items (PangoFontMetrics *metrics, - PangoLanguage *language, - const char *text, - unsigned int text_len, - GList *items) + PangoLanguage *language, + const char *text, + unsigned int text_len, + GList *items) { GHashTable *fonts_seen = g_hash_table_new (NULL, NULL); @@ -1713,20 +1713,20 @@ update_metrics_from_items (PangoFontMetrics *metrics, PangoFont *font = item->analysis.font; if (font != NULL && g_hash_table_lookup (fonts_seen, font) == NULL) - { - PangoFontMetrics *raw_metrics = pango_font_get_metrics (font, language); - g_hash_table_insert (fonts_seen, font, font); - - /* metrics will already be initialized from the first font in the fontset */ - metrics->ascent = MAX (metrics->ascent, raw_metrics->ascent); - metrics->descent = MAX (metrics->descent, raw_metrics->descent); - metrics->height = MAX (metrics->height, raw_metrics->height); - pango_font_metrics_unref (raw_metrics); - } + { + PangoFontMetrics *raw_metrics = pango_font_get_metrics (font, language); + g_hash_table_insert (fonts_seen, font, font); + + /* metrics will already be initialized from the first font in the fontset */ + metrics->ascent = MAX (metrics->ascent, raw_metrics->ascent); + metrics->descent = MAX (metrics->descent, raw_metrics->descent); + metrics->height = MAX (metrics->height, raw_metrics->height); + pango_font_metrics_unref (raw_metrics); + } pango_shape_full (text + item->offset, item->length, - text, text_len, - &item->analysis, glyphs); + text, text_len, + &item->analysis, glyphs); metrics->approximate_char_width += pango_glyph_string_get_width (glyphs); } @@ -1740,35 +1740,34 @@ update_metrics_from_items (PangoFontMetrics *metrics, /** * pango_context_get_metrics: - * @context: a #PangoContext - * @desc: (allow-none): a #PangoFontDescription structure. %NULL means that the - * font description from the context will be used. + * @context: a `PangoContext` + * @desc: (allow-none): a `PangoFontDescription` structure. %NULL means that the + * font description from the context will be used. * @language: (allow-none): language tag used to determine which script to get - * the metrics for. %NULL means that the language tag from the context - * will be used. If no language tag is set on the context, metrics - * for the default language (as determined by pango_language_get_default()) - * will be returned. - * - * Get overall metric information for a particular font - * description. Since the metrics may be substantially different for - * different scripts, a language tag can be provided to indicate that - * the metrics should be retrieved that correspond to the script(s) - * used by that language. - * - * The #PangoFontDescription is interpreted in the same way as - * by pango_itemize(), and the family name may be a comma separated - * list of figures. If characters from multiple of these families - * would be used to render the string, then the returned fonts would - * be a composite of the metrics for the fonts loaded for the - * individual families. - * - * Return value: a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() - * when finished using the object. - **/ + * the metrics for. %NULL means that the language tag from the context + * will be used. If no language tag is set on the context, metrics + * for the default language (as determined by [type_func@Pango.Language.get_default] + * will be returned. + * + * Get overall metric information for a particular font description. + * + * Since the metrics may be substantially different for different scripts, + * a language tag can be provided to indicate that the metrics should be + * retrieved that correspond to the script(s) used by that language. + * + * The `PangoFontDescription` is interpreted in the same way as by [func@itemize], + * and the family name may be a comma separated list of names. If characters + * from multiple of these families would be used to render the string, then + * the returned fonts would be a composite of the metrics for the fonts loaded + * for the individual families. + * + * Return value: a `PangoFontMetrics` object. The caller must call + * [method@Pango.FontMetrics.unref] when finished using the object. + */ PangoFontMetrics * -pango_context_get_metrics (PangoContext *context, - const PangoFontDescription *desc, - PangoLanguage *language) +pango_context_get_metrics (PangoContext *context, + const PangoFontDescription *desc, + PangoLanguage *language) { PangoFontset *current_fonts = NULL; PangoFontMetrics *metrics; @@ -1802,7 +1801,7 @@ pango_context_get_metrics (PangoContext *context, } static void -context_changed (PangoContext *context) +context_changed (PangoContext *context) { context->serial++; if (context->serial == 0) @@ -1811,9 +1810,9 @@ context_changed (PangoContext *context) /** * pango_context_changed: - * @context: a #PangoContext + * @context: a `PangoContext` * - * Forces a change in the context, which will cause any #PangoLayout + * Forces a change in the context, which will cause any `PangoLayout` * using this context to re-layout. * * This function is only useful when implementing a new backend @@ -1824,7 +1823,7 @@ context_changed (PangoContext *context) * Since: 1.32.4 **/ void -pango_context_changed (PangoContext *context) +pango_context_changed (PangoContext *context) { context_changed (context); } @@ -1845,23 +1844,25 @@ check_fontmap_changed (PangoContext *context) /** * pango_context_get_serial: - * @context: a #PangoContext + * @context: a `PangoContext` + * + * Returns the current serial number of @context. * - * Returns the current serial number of @context. The serial number is - * initialized to an small number larger than zero when a new context - * is created and is increased whenever the context is changed using any - * of the setter functions, or the #PangoFontMap it uses to find fonts has - * changed. The serial may wrap, but will never have the value 0. Since it - * can wrap, never compare it with "less than", always use "not equals". + * The serial number is initialized to an small number larger than zero + * when a new context is created and is increased whenever the context + * is changed using any of the setter functions, or the `PangoFontMap` it + * uses to find fonts has changed. The serial may wrap, but will never + * have the value 0. Since it can wrap, never compare it with "less than", + * always use "not equals". * - * This can be used to automatically detect changes to a #PangoContext, and - * is only useful when implementing objects that need update when their - * #PangoContext changes, like #PangoLayout. + * This can be used to automatically detect changes to a `PangoContext`, + * and is only useful when implementing objects that need update when their + * `PangoContext` changes, like `PangoLayout`. * * Return value: The current serial number of @context. * * Since: 1.32.4 - **/ + */ guint pango_context_get_serial (PangoContext *context) { @@ -1871,7 +1872,7 @@ pango_context_get_serial (PangoContext *context) /** * pango_context_set_round_glyph_positions: - * @context: a #PangoContext + * @context: a `PangoContext` * @round_positions: whether to round glyph positions * * Sets whether font rendering with this context should @@ -1899,7 +1900,7 @@ pango_context_set_round_glyph_positions (PangoContext *context, /** * pango_context_get_round_glyph_positions: - * @context: a #PangoContext + * @context: a `PangoContext` * * Returns whether font rendering with this context should * round glyph positions and widths. |