[pango/gi-docs: 32/43] docs: Start porting PangoContext to the new doc format
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [pango/gi-docs: 32/43] docs: Start porting PangoContext to the new doc format
- Date: Mon, 15 Feb 2021 06:21:55 +0000 (UTC)
commit 8e0bf7957c0cb1c304b2c38bb2c3d205ec4148b3
Author: Matthias Clasen <mclasen redhat com>
Date: Sun Feb 14 17:42:44 2021 -0500
docs: Start porting PangoContext to the new doc format
Replace gtk-doc'isms and use gi-docgen links instead.
pango/pango-context.c | 637 +++++++++++++++++++++++++-------------------------
1 file changed, 323 insertions(+), 314 deletions(-)
---
diff --git a/pango/pango-context.c b/pango/pango-context.c
index fbeb4894..6956a38c 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
@@ -49,16 +49,18 @@
* @title:Contexts
* @short_description: Global context object
*
- * The #PangoContext structure stores global information
+ * 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.
+ *
+ * To obtain a `PangoContext`, use [method@Pango.FontMap.create_context].
*/
/**
* PangoContext:
*
- * The #PangoContext structure stores global information
+ * The `PangoContext` structure stores global information
* used to control the itemization process.
*/
struct _PangoContext
@@ -144,21 +146,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,8 +182,8 @@ 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
@@ -192,10 +194,10 @@ update_resolved_gravity (PangoContext *context)
* 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 +216,17 @@ 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 +237,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 +271,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 +290,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 +313,7 @@ pango_context_list_families (PangoContext *context,
{
*n_families = 0;
if (families)
- *families = NULL;
+ *families = NULL;
return;
}
@@ -318,18 +323,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 +344,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 +366,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 +390,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 +407,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 [func@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 +433,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 +449,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 +457,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 +475,13 @@ 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. See
- * pango_context_set_base_dir().
+ * Retrieves the base direction for the context.
+ * 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 +492,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 +500,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 +517,15 @@ 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. See
- * pango_context_set_base_gravity().
+ * Retrieves the base gravity for the context.
+ * 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 +536,19 @@ pango_context_get_base_gravity (PangoContext *context)
/**
* pango_context_get_gravity:
- * @context: a #PangoContext
+ * @context: a `PangoContext`
*
- * 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.
+ * Retrieves the gravity for the context.
+ *
+ * This is similar to [method@Pango.Context.get_base_gravity],
+ * except for when the base gravity is %PANGO_GRAVITY_AUTO for
+ * which [func@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 +559,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 +585,15 @@ 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. See
- * pango_context_set_gravity_hint() for details.
+ * [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 +606,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 +615,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 +668,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 +683,8 @@ retry:
static gboolean
font_cache_get (FontCache *cache,
- gunichar wc,
- PangoFont **font)
+ gunichar wc,
+ PangoFont **font)
{
FontElement *element;
@@ -692,8 +701,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 +728,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 +793,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 +804,7 @@ update_embedding_end (ItemizeState *state)
static PangoAttribute *
find_attribute (GSList *attr_list,
- PangoAttrType type)
+ PangoAttrType type)
{
GSList *node;
@@ -830,7 +839,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 +980,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 +997,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 +1070,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 +1121,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 +1157,7 @@ copy_attr_slist (GSList *attr_slist)
static void
itemize_state_fill_font (ItemizeState *state,
- PangoFont *font)
+ PangoFont *font)
{
GList *l;
@@ -1156,33 +1167,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 +1211,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 +1228,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 +1267,8 @@ typedef struct {
static gboolean
get_font_foreach (PangoFontset *fontset,
- PangoFont *font,
- gpointer data)
+ PangoFont *font,
+ gpointer data)
{
GetFontInfo *info = data;
@@ -1284,8 +1295,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 +1332,7 @@ get_font (ItemizeState *state,
static PangoLanguage *
compute_derived_language (PangoLanguage *lang,
- PangoScript script)
+ PangoScript script)
{
PangoLanguage *derived_lang;
@@ -1342,7 +1353,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 +1368,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 +1397,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 +1422,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 +1481,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 +1545,34 @@ 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 [func@itemize], but the base direction to use when computing
+ * bidirectional levels (see [method@Pango.Context.set_base_dir]),
+ * is specified explicitly rather than gotten from the `PangoContext`.
*
- * 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().
+ * 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 +1585,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 +1598,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 +1609,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 +1622,37 @@ 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 +1660,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 +1683,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 +1699,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 +1721,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 +1748,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 [func@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 +1809,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 +1818,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 +1831,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 +1852,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 +1880,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 +1908,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.
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
