* @text: the text to process
* @length: length of @text in bytes (may be -1 if @text is nul-terminated)
* @analysis: #PangoAnalysis structure from pango_itemize()
- * @attrs: an array to store character information in
+ * @attrs: (array length=attrs_len): an array to store character
+ * information in
* @attrs_len: size of the array passed as @attrs
*
* Determines possible line, word, and character breaks
* pango_find_paragraph_boundary:
* @text: UTF-8 text
* @length: length of @text in bytes, or -1 if nul-terminated
- * @paragraph_delimiter_index: return location for index of delimiter
- * @next_paragraph_start: return location for start of next paragraph
+ * @paragraph_delimiter_index: (out): return location for index of
+ * delimiter
+ * @next_paragraph_start: (out): return location for start of next
+ * paragraph
*
* Locates a paragraph boundary in @text. A boundary is caused by
* delimiter characters, such as a newline, carriage return, carriage
* @length: length in bytes of @text
* @level: embedding level, or -1 if unknown
* @language: language tag
- * @log_attrs: array with one #PangoLogAttr per character in @text, plus one extra, to be filled in
+ * @log_attrs: (array length=attrs_len): array with one #PangoLogAttr
+ * per character in @text, plus one extra, to be filled in
* @attrs_len: length of @log_attrs array
*
* Computes a #PangoLogAttr for each character in @text. The @log_attrs
/**
* pango_parse_style:
* @str: a string to parse.
- * @style: a #PangoStyle to store the result in.
+ * @style: (out caller-allocates): a #PangoStyle to store the result
+ * in.
* @warn: if %TRUE, issue a g_warning() on bad input.
*
* Parses a font style. The allowed values are "normal",
/**
* pango_parse_variant:
* @str: a string to parse.
- * @variant: a #PangoVariant to store the result in.
+ * @variant: (out caller-allocates): a #PangoVariant to store the
+ * result in.
* @warn: if %TRUE, issue a g_warning() on bad input.
*
* Parses a font variant. The allowed values are "normal"
/**
* pango_parse_weight:
* @str: a string to parse.
- * @weight: a #PangoWeight to store the result in.
+ * @weight: (out caller-allocates): a #PangoWeight to store the result
+ * in.
* @warn: if %TRUE, issue a g_warning() on bad input.
*
* Parses a font weight. The allowed values are "heavy",
/**
* pango_parse_stretch:
* @str: a string to parse.
- * @stretch: a #PangoStretch to store the result in.
+ * @stretch: (out caller-allocates): a #PangoStretch to store the
+ * result in.
* @warn: if %TRUE, issue a g_warning() on bad input.
*
* Parses a font stretch. The allowed values are
*
* Computes the coverage map for a given font and language tag.
*
- * Return value: a newly-allocated #PangoCoverage object.
+ * Return value: (transfer full): a newly-allocated #PangoCoverage
+ * object.
**/
PangoCoverage *
pango_font_get_coverage (PangoFont *font,
/**
* pango_font_face_list_sizes:
* @face: a #PangoFontFace.
- * @sizes: location to store a pointer to an array of int. This array
- * should be freed with g_free().
+ * @sizes: (out) (array length=n_sizes): location to store a pointer
+ * to an array of int. This array should be freed with
+ * g_free().
* @n_sizes: location to store the number of elements in @sizes
*
* List the available sizes for a font. This is only applicable to bitmap
* @end: end index (the range is the set of bytes with
indices such that start <= index < end)
* @font: a #PangoFont
- * @ink_rect: rectangle used to store the extents of the glyph string range as drawn
- * or %NULL to indicate that the result is not needed.
- * @logical_rect: rectangle used to store the logical extents of the glyph string range
- * or %NULL to indicate that the result is not needed.
+ * @ink_rect: (out caller-allocates): rectangle used to store the
+ * extents of the glyph string range as drawn or %NULL to
+ * indicate that the result is not needed.
+ * @logical_rect: (out caller-allocates): rectangle used to store the
+ * logical extents of the glyph string range or %NULL to
+ * indicate that the result is not needed.
*
* Computes the extents of a sub-portion of a glyph string. The extents are
* relative to the start of the glyph string range (the origin of their
* @text: the text corresponding to the glyphs
* @length: the length of @text, in bytes
* @embedding_level: the embedding level of the string
- * @logical_widths: an array whose length is the number of characters in
- * text (equal to g_utf8_strlen (text, length) unless
- * text has NUL bytes)
- * to be filled in with the resulting character widths.
+ * @logical_widths: (array): an array whose length is the number of
+ * characters in text (equal to g_utf8_strlen (text,
+ * length) unless text has NUL bytes) to be filled in
+ * with the resulting character widths.
*
* Given a #PangoGlyphString resulting from pango_shape() and the corresponding
* text, determine the screen width corresponding to each character. When
* @index_: the byte index within @text
* @trailing: whether we should compute the result for the beginning (%FALSE)
* or end (%TRUE) of the character.
- * @x_pos: location to store result
+ * @x_pos: (out): location to store result
*
* Converts from character position to x position. (X position
* is measured from the left edge of the run). Character positions
* @length: the number of bytes (not characters) in text.
* @analysis: the analysis information return from pango_itemize()
* @x_pos: the x offset (in Pango units)
- * @index_: location to store calculated byte index within @text
- * @trailing: location to store a boolean indicating
+ * @index_: (out): location to store calculated byte index within @text
+ * @trailing: (out): location to store a boolean indicating
* whether the user clicked on the leading or trailing
* edge of the character.
*
*
* Make a copy of an attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attribute_copy (const PangoAttribute *attr)
*
* Create a new font family attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_family_new (const char *family)
*
* Create a new language tag attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_language_new (PangoLanguage *language)
*
* Create a new foreground color attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_foreground_new (guint16 red,
*
* Create a new background color attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_background_new (guint16 red,
*
* Create a new font-size attribute in fractional points.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_size_new (int size)
*
* Create a new font slant style attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_style_new (PangoStyle style)
*
* Create a new font weight attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_weight_new (PangoWeight weight)
*
* Create a new font variant attribute (normal or small caps)
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_variant_new (PangoVariant variant)
*
* Create a new font stretch attribute
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_stretch_new (PangoStretch stretch)
* allows setting family, style, weight, variant, stretch,
* and size simultaneously.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_font_desc_new (const PangoFontDescription *desc)
*
* Create a new underline-style attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_underline_new (PangoUnderline underline)
* modifies the color of underlines. If not set, underlines
* will use the foreground color.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
*
* Since: 1.8
**/
*
* Create a new strike-through attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_strikethrough_new (gboolean strikethrough)
* modifies the color of strikethrough lines. If not set, strikethrough
* lines will use the foreground color.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
*
* Since: 1.8
**/
*
* Create a new baseline displacement attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_rise_new (int rise)
* Create a new font size scale attribute. The base font for the
* affected text will have its size multiplied by @scale_factor.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute*
pango_attr_scale_new (double scale_factor)
* other fonts on the system that might contain the characters in the
* text.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
*
* Since: 1.4
**/
*
* Create a new letter-spacing attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
*
* Since: 1.6
**/
* particular glyph. This might be used, for instance, for
* embedding a picture or a widget inside a #PangoLayout.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
**/
PangoAttribute *
pango_attr_shape_new (const PangoRectangle *ink_rect,
*
* Create a new gravity attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
*
* Since: 1.16
**/
*
* Create a new gravity hint attribute.
*
- * Return value: the newly allocated #PangoAttribute, which should be
- * freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ * which should be freed with pango_attribute_destroy().
*
* Since: 1.16
**/
*
* Create a new empty attribute list with a reference count of one.
*
- * Return value: the newly allocated #PangoAttrList, which should
- * be freed with pango_attr_list_unref().
+ * Return value: (transfer full): the newly allocated #PangoAttrList,
+ * which should be freed with pango_attr_list_unref().
**/
PangoAttrList *
pango_attr_list_new (void)
/**
* pango_attr_list_insert:
* @list: a #PangoAttrList
- * @attr: the attribute to insert. Ownership of this value is
- * assumed by the list.
+ * @attr: (transfer full): the attribute to insert. Ownership of this
+ * value is assumed by the list.
*
* Insert the given attribute into the #PangoAttrList. It will
* be inserted after all other attributes with a matching
/**
* pango_attr_list_insert_before:
* @list: a #PangoAttrList
- * @attr: the attribute to insert. Ownership of this value is
- * assumed by the list.
+ * @attr: (transfer full): the attribute to insert. Ownership of this
+ * value is assumed by the list.
*
* Insert the given attribute into the #PangoAttrList. It will
* be inserted before all other attributes with a matching
/**
* pango_attr_list_change:
* @list: a #PangoAttrList
- * @attr: the attribute to insert. Ownership of this value is
- * assumed by the list.
+ * @attr: (transfer full): the attribute to insert. Ownership of this
+ * value is assumed by the list.
*
* Insert the given attribute into the #PangoAttrList. It will
* replace any attributes of the same type on that segment
* Create a iterator initialized to the beginning of the list.
* @list must not be modified until this iterator is freed.
*
- * Return value: the newly allocated #PangoAttrIterator, which should
+ * Return value: (transfer full): the newly allocated #PangoAttrIterator, which should
* be freed with pango_attr_iterator_destroy().
**/
PangoAttrIterator *
/**
* pango_attr_iterator_range:
* @iterator: a #PangoAttrIterator
- * @start: location to store the start of the range
- * @end: location to store the end of the range
+ * @start: (out): location to store the start of the range
+ * @end: (out): location to store the end of the range
*
* Get the range of the current segment. Note that the
* stored return values are signed, not unsigned like
*
* Copy a #PangoAttrIterator
*
- * Return value: the newly allocated #PangoAttrIterator, which should
- * be freed with pango_attr_iterator_destroy().
+ * Return value: (transfer full): the newly allocated
+ * #PangoAttrIterator, which should be freed with
+ * pango_attr_iterator_destroy().
**/
PangoAttrIterator *
pango_attr_iterator_copy (PangoAttrIterator *iterator)
* the attribute whose range starts closest to the current location
* is used.
*
- * Return value: the current attribute of the given type, or %NULL
- * if no attribute of that type applies to the current
+ * Return value: the current attribute of the given type, or %NULL if
+ * no attribute of that type applies to the current
* location.
**/
PangoAttribute *
};
typedef gboolean (*PangoAttrFilterFunc) (PangoAttribute *attribute,
- gpointer data);
+ gpointer user_data);
-typedef gpointer (*PangoAttrDataCopyFunc) (gconstpointer data);
+typedef gpointer (*PangoAttrDataCopyFunc) (gconstpointer user_data);
struct _PangoAttrClass
{
* Copy an existing #PangoCoverage. (This function may now be unnecessary
* since we refcount the structure. File a bug if you use it.)
*
- * Return value: the newly allocated #PangoCoverage,
- * with a reference count of one, which
- * should be freed with pango_coverage_unref().
+ * Return value: (transfer full): the newly allocated #PangoCoverage,
+ * with a reference count of one, which should be freed
+ * with pango_coverage_unref().
**/
PangoCoverage *
pango_coverage_copy (PangoCoverage *coverage)
/**
* pango_coverage_to_bytes:
* @coverage: a #PangoCoverage
- * @bytes: location to store result (must be freed with g_free())
- * @n_bytes: location to store size of result
+ * @bytes: (out) (array length=n_bytes) (element-type guint8):
+ * location to store result (must be freed with g_free())
+ * @n_bytes: (out): location to store size of result
*
* Convert a #PangoCoverage structure into a flat binary format
**/
/**
* pango_coverage_from_bytes:
- * @bytes: binary data representing a #PangoCoverage
+ * @bytes: (array length=n_bytes) (element-type guint8): binary data
+ * representing a #PangoCoverage
* @n_bytes: the size of @bytes in bytes
*
* Convert data generated from pango_converage_to_bytes() back
* to a #PangoCoverage
*
- * Return value: a newly allocated #PangoCoverage, or %NULL if
- * the data was invalid.
+ * Return value: (transfer full): a newly allocated #PangoCoverage, or
+ * %NULL if the data was invalid.
**/
PangoCoverage *
pango_coverage_from_bytes (guchar *bytes,
* PangoFontsetForeachFunc:
* @fontset: a #PangoFontset
* @font: a font from @fontset
- * @data: callback data
+ * @user_data: callback data
*
* A callback function used by pango_fontset_foreach() when enumerating
* the fonts in a fontset.
**/
typedef gboolean (*PangoFontsetForeachFunc) (PangoFontset *fontset,
PangoFont *font,
- gpointer data);
+ gpointer user_data);
PangoFont * pango_fontset_get_font (PangoFontset *fontset,
guint wc);
* @text: text that @glyph_item corresponds to
* (glyph_item->item->offset is an offset from the
* start of @text)
- * @log_attrs: logical attributes for the item (the
- * first logical attribute refers to the position
+ * @log_attrs: (array): logical attributes for the item
+ * (the first logical attribute refers to the position
* before the first character in the item)
* @letter_spacing: amount of letter spacing to add
* in Pango units. May be negative, though too large
* @text: text that @glyph_item corresponds to
* (glyph_item->item->offset is an offset from the
* start of @text)
- * @logical_widths: an array whose length is the number of characters in
- * glyph_item (equal to glyph_item->item->num_chars)
- * to be filled in with the resulting character widths.
+ * @logical_widths: (array): an array whose length is the number of
+ * characters in glyph_item (equal to
+ * 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
* functions automatically (by calling gtk_set_locale()).
* See <literal>man setlocale</literal> for more details.
*
- * Return value: the default language as a #PangoLanguage, must not be
- * freed.
+ * Return value: (transfer none): the default language as a
+ * #PangoLanguage, must not be freed.
*
* Since: 1.16
**/
* Use pango_language_get_default() if you want to get the #PangoLanguage for
* the current locale of the process.
*
- * Return value: an opaque pointer to a #PangoLanguage structure, or %NULL
- * if @language was %NULL. The returned pointer will be valid
- * forever after, and should not be freed.
+ * Return value: (transfer none): an opaque pointer to a
+ * #PangoLanguage structure, or %NULL if @language was
+ * %NULL. The returned pointer will be valid forever
+ * after, and should not be freed.
**/
PangoLanguage *
pango_language_from_string (const char *language)
* The pango_language_includes_script() function uses this function
* internally.
*
- * Return value: An array of #PangoScript values, with the
- * number of entries in the array stored in @num_scripts, or
- * %NULL if Pango does not have any information about this
- * particular language tag (also the case if @language is %NULL).
- * The returned array is owned by Pango and should not be modified
- * or freed.
+ * Return value: (array length=num_scripts): An array of #PangoScript
+ * values, with the number of entries in the array stored in
+ * @num_scripts, or %NULL if Pango does not have any information about
+ * this particular language tag (also the case if @language is %NULL).
+ * The returned array is owned by Pango and should not be modified or
+ * freed.
* Since: 1.22
**/
*
* Gets the attribute list for the layout, if any.
*
- * Return value: a #PangoAttrList.
+ * Return value: (transfer none): a #PangoAttrList.
**/
PangoAttrList*
pango_layout_get_attributes (PangoLayout *layout)
* @attrs: (out)(array length=n_attrs)(transfer container):
* location to store a pointer to an array of logical attributes
* This value must be freed with g_free().
- * @n_attrs: location to store the number of the attributes in the
+ * @n_attrs: (out): location to store the number of the attributes in the
* array. (The stored value will be one more than the total number
* of characters in the layout, since there need to be attributes
* corresponding to both the position before the first character
/**
* pango_layout_get_log_attrs_readonly:
* @layout: a #PangoLayout
- * @n_attrs: location to store the number of the attributes in the array
+ * @n_attrs: (out): location to store the number of the attributes in
+ * the array
*
* Retrieves an array of logical attributes for each character in
* the @layout.
* need to be attributes corresponding to both the position before
* the first character and the position after the last character.
*
- * Returns: an array of logical attributes
+ * Returns: (array length=n_attrs): an array of logical attributes
*
* Since: 1.30
*/
* but the user is not expected
* to modify the contents of the line (glyphs, glyph widths, etc.).
*
- * Return value: the current line, that should not be modified.
+ * Return value: (transfer none): the current line, that should not be
+ * modified.
*
* Since: 1.16
**/
/**
* pango_layout_iter_get_char_extents:
* @iter: a #PangoLayoutIter
- * @logical_rect: rectangle to fill with logical extents
+ * @logical_rect: (out caller-allocates): rectangle to fill with
+ * logical extents
*
* Gets the extents of the current character, in layout coordinates
* (origin is the top left of the entire layout). Only logical extents
* The returned layout line should not be modified while still being
* rendered.
*
- * Return value: the layout line, or %NULL if no layout line is being
- * rendered using @renderer at this time.
+ * Return value: (transfer none): the layout line, or %NULL if no
+ * layout line is being rendered using @renderer at this time.
*
* Since: 1.20
**/
/**
* pango_tab_array_get_tabs:
* @tab_array: a #PangoTabArray
- * @alignments: (out) (allow-none): location to store an array of tab stop
- * alignments, or %NULL
- * @locations: (out) (allow-none): location to store an array of tab positions,
- * or %NULL
+ * @alignments: (out) (allow-none): location to store an array of tab
+ * stop alignments, or %NULL
+ * @locations: (out) (allow-none) (array): location to store an array
+ * of tab positions, or %NULL
*
* If non-%NULL, @alignments and @locations are filled with allocated
* arrays of length pango_tab_array_get_size(). You must free the