diff options
| -rw-r--r-- | pango/pango-glyph-item.c | 90 | ||||
| -rw-r--r-- | pango/pango-glyph-item.h | 53 | ||||
| -rw-r--r-- | pango/pango-glyph.h | 44 | ||||
| -rw-r--r-- | pango/pango-item.h | 9 |
4 files changed, 104 insertions, 92 deletions
diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c index 326ae37f..8cca8627 100644 --- a/pango/pango-glyph-item.c +++ b/pango/pango-glyph-item.c @@ -30,13 +30,15 @@ /** * pango_glyph_item_split: - * @orig: a #PangoItem + * @orig: a `PangoItem` * @text: text to which positions in @orig apply * @split_index: byte index of position to split item, relative to the start of the item * * Modifies @orig to cover only the text after @split_index, and * returns a new item that covers the text before @split_index that - * used to be in @orig. You can think of @split_index as the length of + * used to be in @orig. + * + * You can think of @split_index as the length of * the returned item. @split_index may not be 0, and it may not be * greater than or equal to the length of @orig (that is, there must * be at least one byte assigned to each item, you can't create a @@ -132,11 +134,11 @@ pango_glyph_item_split (PangoGlyphItem *orig, /** * pango_glyph_item_copy: - * @orig: (nullable): a #PangoGlyphItem, may be %NULL + * @orig: (nullable): a `PangoGlyphItem`, may be %NULL * - * Make a deep copy of an existing #PangoGlyphItem structure. + * Make a deep copy of an existing `PangoGlyphItem` structure. * - * Return value: (nullable): the newly allocated #PangoGlyphItem, which should + * Return value: (nullable): the newly allocated `PangoGlyphItem`, which should * be freed with pango_glyph_item_free(), or %NULL * if @orig was %NULL. * @@ -160,9 +162,9 @@ pango_glyph_item_copy (PangoGlyphItem *orig) /** * pango_glyph_item_free: - * @glyph_item: (nullable): a #PangoGlyphItem, may be %NULL + * @glyph_item: (nullable): a `PangoGlyphItem`, may be %NULL * - * Frees a #PangoGlyphItem and resources to which it points. + * Frees a `PangoGlyphItem` and resources to which it points. * * Since: 1.6 **/ @@ -187,13 +189,13 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItem, pango_glyph_item, /** * pango_glyph_item_iter_copy: - * @orig: (nullable): a #PangoGlyphItemIter, may be %NULL + * @orig: (nullable): a `PangoGlyphItem`Iter, may be %NULL * - * Make a shallow copy of an existing #PangoGlyphItemIter structure. + * Make a shallow copy of an existing `PangoGlyphItemIter` structure. * - * Return value: (nullable): the newly allocated #PangoGlyphItemIter, which should - * be freed with pango_glyph_item_iter_free(), or %NULL - * if @orig was %NULL. + * Return value: (nullable): the newly allocated `PangoGlyphItemIter`, + * which should be freed with pango_glyph_item_iter_free(), or %NULL + * if @orig was %NULL. * * Since: 1.22 **/ @@ -214,9 +216,9 @@ pango_glyph_item_iter_copy (PangoGlyphItemIter *orig) /** * pango_glyph_item_iter_free: - * @iter: (nullable): a #PangoGlyphItemIter, may be %NULL + * @iter: (nullable): a `PangoGlyphItemIter`, may be %NULL * - * Frees a #PangoGlyphItemIter created by pango_glyph_item_iter_copy(). + * Frees a `PangoGlyphItem`Iter. * * Since: 1.22 **/ @@ -235,13 +237,14 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItemIter, pango_glyph_item_iter, /** * pango_glyph_item_iter_next_cluster: - * @iter: a #PangoGlyphItemIter + * @iter: a `PangoGlyphItemIter` * * Advances the iterator to the next cluster in the glyph item. - * See #PangoGlyphItemIter for details of cluster orders. * - * Return value: %TRUE if the iterator was advanced, %FALSE if we were already on the - * last cluster. + * See `PangoGlyphItemIter` for details of cluster orders. + * + * Return value: %TRUE if the iterator was advanced, + * %FALSE if we were already on the last cluster. * * Since: 1.22 **/ @@ -325,13 +328,13 @@ pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter) /** * pango_glyph_item_iter_prev_cluster: - * @iter: a #PangoGlyphItemIter + * @iter: a `PangoGlyphItemIter` * * Moves the iterator to the preceding cluster in the glyph item. - * See #PangoGlyphItemIter for details of cluster orders. + * See `PangoGlyphItemIter` for details of cluster orders. * - * Return value: %TRUE if the iterator was moved, %FALSE if we were already on the - * first cluster. + * Return value: %TRUE if the iterator was moved, + * %FALSE if we were already on the first cluster. * * Since: 1.22 **/ @@ -418,13 +421,14 @@ pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter) /** * pango_glyph_item_iter_init_start: - * @iter: a #PangoGlyphItemIter + * @iter: a `PangoGlyphItemIter` * @glyph_item: the glyph item to iterate over * @text: text corresponding to the glyph item * - * Initializes a #PangoGlyphItemIter structure to point to the + * Initializes a `PangoGlyphItemIter` structure to point to the * first cluster in a glyph item. - * See #PangoGlyphItemIter for details of cluster orders. + * + * See `PangoGlyphItemIter` for details of cluster orders. * * Return value: %FALSE if there are no clusters in the glyph item * @@ -456,13 +460,14 @@ pango_glyph_item_iter_init_start (PangoGlyphItemIter *iter, /** * pango_glyph_item_iter_init_end: - * @iter: a #PangoGlyphItemIter + * @iter: a `PangoGlyphItemIter` * @glyph_item: the glyph item to iterate over * @text: text corresponding to the glyph item * - * Initializes a #PangoGlyphItemIter structure to point to the + * Initializes a `PangoGlyphItemIter` structure to point to the * last cluster in a glyph item. - * See #PangoGlyphItemIter for details of cluster orders. + * + * See `PangoGlyphItemIter` for details of cluster orders. * * Return value: %FALSE if there are no clusters in the glyph item * @@ -554,12 +559,14 @@ split_before_cluster_start (ApplyAttrsState *state) * pango_glyph_item_apply_attrs: * @glyph_item: a shaped item * @text: text that @list applies to - * @list: a #PangoAttrList + * @list: a `PangoAttrList` * - * Splits a shaped item (PangoGlyphItem) into multiple items based - * on an attribute list. The idea is that if you have attributes + * Splits a shaped item (`PangoGlyphItem`) into multiple items based + * on an attribute list. + * + * The idea is that if you have attributes * that don't affect shaping, such as color or underline, to avoid - * affecting shaping, you filter them out (pango_attr_list_filter()), + * affecting shaping, you filter them out ([method@Pango.AttrList.filter]), * apply the shaping process and then reapply them to the result using * this function. * @@ -567,7 +574,7 @@ split_before_cluster_start (ApplyAttrsState *state) * to that cluster; for instance, if half of a cluster is underlined * and the other-half strikethrough, then the cluster will end * up with both underline and strikethrough attributes. In these - * cases, it may happen that item->extra_attrs for some of the + * cases, it may happen that @item->extra_attrs for some of the * result items can have multiple attributes of the same type. * * This function takes ownership of @glyph_item; it will be reused @@ -575,7 +582,7 @@ split_before_cluster_start (ApplyAttrsState *state) * * Return value: (transfer full) (element-type Pango.GlyphItem): a * list of glyph items resulting from splitting @glyph_item. Free - * the elements using pango_glyph_item_free(), the list using + * the elements using [method@Pango.GlyphItem.free], the list using * g_slist_free(). * * Since: 1.2 @@ -711,7 +718,7 @@ pango_glyph_item_apply_attrs (PangoGlyphItem *glyph_item, /** * pango_glyph_item_letter_space: - * @glyph_item: a #PangoGlyphItem + * @glyph_item: a `PangoGlyphItem` * @text: text that @glyph_item corresponds to * (glyph_item->item->offset is an offset from the * start of @text) @@ -726,7 +733,7 @@ pango_glyph_item_apply_attrs (PangoGlyphItem *glyph_item, * give the effect of typographic letter spacing. * * Since: 1.6 - **/ + */ void pango_glyph_item_letter_space (PangoGlyphItem *glyph_item, const char *text, @@ -784,7 +791,7 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item, /** * pango_glyph_item_get_logical_widths: - * @glyph_item: a #PangoGlyphItem + * @glyph_item: a `PangoGlyphItem` * @text: text that @glyph_item corresponds to * (glyph_item->item->offset is an offset from the * start of @text) @@ -793,12 +800,13 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item, * glyph_item->item->num_chars) to be filled in with * the resulting character widths. * - * Given a #PangoGlyphItem and the corresponding - * text, determine the screen width corresponding to each character. When - * multiple characters compose a single cluster, the width of the entire + * Given a `PangoGlyphItem` and the corresponding text, determine the width + * corresponding to each character. + * + * When multiple characters compose a single cluster, the width of the entire * cluster is divided equally among the characters. * - * See also pango_glyph_string_get_logical_widths(). + * See also [method@Pango.GlyphString.get_logical_widths]. * * Since: 1.26 **/ diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h index 543d74bd..8a1dbff4 100644 --- a/pango/pango-glyph-item.h +++ b/pango/pango-glyph-item.h @@ -31,14 +31,15 @@ G_BEGIN_DECLS /** * PangoGlyphItem: - * @item: corresponding #PangoItem. - * @glyphs: corresponding #PangoGlyphString. - * - * A #PangoGlyphItem is a pair of a #PangoItem and the glyphs - * resulting from shaping the text corresponding to an item. - * As an example of the usage of #PangoGlyphItem, the results - * of shaping text with #PangoLayout is a list of #PangoLayoutLine, - * each of which contains a list of #PangoGlyphItem. + * @item: corresponding `PangoItem` + * @glyphs: corresponding `PangoGlyphString` + * + * A `PangoGlyphItem` is a pair of a `PangoItem` and the glyphs + * resulting from shaping the items text. + * + * As an example of the usage of `PangoGlyphItem`, the results + * of shaping text with `PangoLayout` is a list of `PangoLayoutLine`, + * each of which contains a list of `PangoGlyphItem`. */ typedef struct _PangoGlyphItem PangoGlyphItem; @@ -84,21 +85,23 @@ void pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item, /** * PangoGlyphItemIter: * - * A #PangoGlyphItemIter is an iterator over the clusters in a - * #PangoGlyphItem. The *forward direction* of the - * iterator is the logical direction of text. That is, with increasing - * @start_index and @start_char values. If @glyph_item is right-to-left - * (that is, if `glyph_item->item->analysis.level` is odd), + * A `PangoGlyphItemIter` is an iterator over the clusters in a + * `PangoGlyphItem`. + * + * The *forward direction* of the iterator is the logical direction of text. + * That is, with increasing @start_index and @start_char values. If @glyph_item + * is right-to-left (that is, if `glyph_item->item->analysis.level` is odd), * then @start_glyph decreases as the iterator moves forward. Moreover, * in right-to-left cases, @start_glyph is greater than @end_glyph. * - * An iterator should be initialized using either of - * pango_glyph_item_iter_init_start() and + * An iterator should be initialized using either + * pango_glyph_item_iter_init_start() or * pango_glyph_item_iter_init_end(), for forward and backward iteration * respectively, and walked over using any desired mixture of * pango_glyph_item_iter_next_cluster() and - * pango_glyph_item_iter_prev_cluster(). A common idiom for doing a - * forward iteration over the clusters is: + * pango_glyph_item_iter_prev_cluster(). + * + * A common idiom for doing a forward iteration over the clusters is: * * ``` * PangoGlyphItemIter cluster_iter; @@ -114,14 +117,14 @@ void pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item, * ``` * * Note that @text is the start of the text for layout, which is then - * indexed by `glyph_item->item->offset` to get to the - * text of @glyph_item. The @start_index and @end_index values can directly - * index into @text. The @start_glyph, @end_glyph, @start_char, and @end_char - * values however are zero-based for the @glyph_item. For each cluster, the - * item pointed at by the start variables is included in the cluster while - * the one pointed at by end variables is not. - * - * None of the members of a #PangoGlyphItemIter should be modified manually. + * indexed by `glyph_item->item->offset` to get to the text of @glyph_item. + * The @start_index and @end_index values can directly index into @text. The + * @start_glyph, @end_glyph, @start_char, and @end_char values however are + * zero-based for the @glyph_item. For each cluster, the item pointed at by + * the start variables is included in the cluster while the one pointed at by + * end variables is not. + * + * None of the members of a `PangoGlyphItemIter` should be modified manually. * * Since: 1.22 */ diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h index 628eac96..7c1bf7b5 100644 --- a/pango/pango-glyph.h +++ b/pango/pango-glyph.h @@ -36,8 +36,10 @@ typedef struct _PangoGlyphString PangoGlyphString; /** * PangoGlyphUnit: * - * The #PangoGlyphUnit type is used to store dimensions within - * Pango. Dimensions are stored in 1/%PANGO_SCALE of a device unit. + * The `PangoGlyphUnit` type is used to store dimensions within + * Pango. + * + * Dimensions are stored in 1/%PANGO_SCALE of a device unit. * (A device unit might be a pixel for screen display, or * a point on a printer.) %PANGO_SCALE is currently 1024, and * may change in the future (unlikely though), but you should not @@ -54,7 +56,7 @@ typedef gint32 PangoGlyphUnit; * @x_offset: horizontal offset from nominal character position. * @y_offset: vertical offset from nominal character position. * - * The #PangoGlyphGeometry structure contains width and positioning + * The `PangoGlyphGeometry` structure contains width and positioning * information for a single glyph. */ struct _PangoGlyphGeometry @@ -68,15 +70,17 @@ struct _PangoGlyphGeometry */ /** * PangoGlyphVisAttr: - * @is_cluster_start: set for the first logical glyph in each cluster. (Clusters - * are stored in visual order, within the cluster, glyphs - * are always ordered in logical order, since visual - * order is meaningless; that is, in Arabic text, accent glyphs - * follow the glyphs for the base character.) + * @is_cluster_start: set for the first logical glyph in each cluster. + * (Clusters are stored in visual order, within the cluster, glyphs + * are always ordered in logical order, since visual order is meaningless; + * that is, in Arabic text, accent glyphs follow the glyphs for the + * base character.) + * + * A `PangoGlyphVisAttr` structure communicates information between + * the shaping and rendering phases. * - * The PangoGlyphVisAttr is used to communicate information between - * the shaping phase and the rendering phase. More attributes may be - * added in the future. + * Currently, it contains only cluster start information. yMore attributes + * may be added in the future. */ struct _PangoGlyphVisAttr { @@ -91,9 +95,8 @@ struct _PangoGlyphVisAttr * @geometry: the positional information about the glyph. * @attr: the visual attributes of the glyph. * - * The #PangoGlyphInfo structure represents a single glyph together with + * A `PangoGlyphInfo` structure represents a single glyph with * positioning information and visual attributes. - * It contains the following fields. */ struct _PangoGlyphInfo { @@ -102,9 +105,6 @@ struct _PangoGlyphInfo PangoGlyphVisAttr attr; }; -/* A string of glyphs with positional information and visual attributes - - * ready for drawing - */ /** * PangoGlyphString: * @num_glyphs: number of the glyphs in this glyph string. @@ -113,10 +113,11 @@ struct _PangoGlyphInfo * @log_clusters: logical cluster info, indexed by the byte index * within the text corresponding to the glyph string. * - * The #PangoGlyphString structure is used to store strings - * of glyphs with geometry and visual attribute information. - * The storage for the glyph information is owned - * by the structure which simplifies memory management. + * A `PangoGlyphString` is used to store strings of glyphs with geometry + * and visual attribute information. + * + * The storage for the glyph information is owned by the structure + * which simplifies memory management. */ struct _PangoGlyphString { gint num_glyphs; @@ -211,7 +212,8 @@ void pango_shape_full (const char *item_text, * positioning of glyphs. * * Flags influencing the shaping process. - * These can be passed to pango_shape_with_flags(). + * + * `PangoShapeFlags` can be passed to pango_shape_with_flags(). */ typedef enum { PANGO_SHAPE_NONE = 0, diff --git a/pango/pango-item.h b/pango/pango-item.h index 638f970a..a1e95086 100644 --- a/pango/pango-item.h +++ b/pango/pango-item.h @@ -34,7 +34,8 @@ typedef struct _PangoItem PangoItem; * PANGO_ANALYSIS_FLAG_CENTERED_BASELINE: * * Whether the segment should be shifted to center around the baseline. - * Used in vertical writing directions mostly. + * + * This is mainly used in vertical writing directions. * * Since: 1.16 */ @@ -43,8 +44,7 @@ typedef struct _PangoItem PangoItem; /** * PANGO_ANALYSIS_FLAG_IS_ELLIPSIS: * - * This flag is used to mark runs that hold ellipsized text, - * in an ellipsized layout. + * Whether this run holds ellipsized text. * * Since: 1.36.7 */ @@ -53,8 +53,7 @@ typedef struct _PangoItem PangoItem; /** * PANGO_ANALYSIS_FLAG_NEED_HYPHEN: * - * This flag tells Pango to add a hyphen at the end of the - * run during shaping. + * Whether to add a hyphen at the end of the run during shaping. * * Since: 1.44 */ |