diff options
Diffstat (limited to 'pango/pango-tabs.c')
| -rw-r--r-- | pango/pango-tabs.c | 160 |
1 files changed, 77 insertions, 83 deletions
diff --git a/pango/pango-tabs.c b/pango/pango-tabs.c index 56a34468..2c2717ee 100644 --- a/pango/pango-tabs.c +++ b/pango/pango-tabs.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,14 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:tab-stops - * @short_description:Structures for storing tab stops - * @title:Tab Stops - * - * Functions in this section are used to deal with #PangoTabArray objects - * that can be used to set tab stop positions in a #PangoLayout. - */ #include "config.h" #include "pango-tabs.h" #include "pango-impl-utils.h" @@ -36,19 +28,21 @@ typedef struct _PangoTab PangoTab; struct _PangoTab { - gint location; /* Offset in pixels of this tab stop - * from the left margin of the text. - */ + gint location; /* Offset in pixels of this tab stop + * from the left margin of the text. + */ PangoTabAlign alignment; /* Where the tab stop appears relative - * to the text. - */ + * to the text. + */ }; /** * PangoTabArray: * - * A #PangoTabArray struct contains an array - * of tab stops. Each tab stop has an alignment and a position. + * A `PangoTabArray` contains an array of tab stops. + * + * `PangoTabArray` can be used to set tab stops in a `PangoLayout`. + * Each tab stop has an alignment and a position. */ struct _PangoTabArray { @@ -74,16 +68,17 @@ init_tabs (PangoTabArray *array, gint start, gint end) * @initial_size: Initial number of tab stops to allocate, can be 0 * @positions_in_pixels: whether positions are in pixel units * - * Creates an array of @initial_size tab stops. Tab stops are specified in - * pixel units if @positions_in_pixels is %TRUE, otherwise in Pango - * units. All stops are initially at position 0. + * Creates an array of @initial_size tab stops. + * + * Tab stops are specified in pixel units if @positions_in_pixels is %TRUE, + * otherwise in Pango units. All stops are initially at position 0. * - * Return value: the newly allocated #PangoTabArray, which should - * be freed with pango_tab_array_free(). - **/ + * Return value: the newly allocated `PangoTabArray`, which should + * be freed with [method@Pango.TabArray.free]. + */ PangoTabArray* -pango_tab_array_new (gint initial_size, - gboolean positions_in_pixels) +pango_tab_array_new (gint initial_size, + gboolean positions_in_pixels) { PangoTabArray *array; @@ -95,8 +90,7 @@ pango_tab_array_new (gint initial_size, * optimization. */ array = g_slice_new (PangoTabArray); - array->size = initial_size; - array->allocated = initial_size; + array->size = initial_size; array->allocated = initial_size; if (array->allocated > 0) { @@ -119,20 +113,20 @@ pango_tab_array_new (gint initial_size, * @first_position: position of first tab stop * @...: additional alignment/position pairs * - * This is a convenience function that creates a #PangoTabArray - * and allows you to specify the alignment and position of each - * tab stop. You <emphasis>must</emphasis> provide an alignment - * and position for @size tab stops. + * Creates * a `PangoTabArray` and allows you to specify the alignment + * and position of each tab stop. + * + * You **must** provide an alignment and position for @size tab stops. * - * Return value: the newly allocated #PangoTabArray, which should - * be freed with pango_tab_array_free(). - **/ + * Return value: the newly allocated `PangoTabArray`, which should + * be freed with [method@Pango.TabArray.free]. + */ PangoTabArray * pango_tab_array_new_with_positions (gint size, - gboolean positions_in_pixels, - PangoTabAlign first_alignment, - gint first_position, - ...) + gboolean positions_in_pixels, + PangoTabAlign first_alignment, + gint first_position, + ...) { PangoTabArray *array; va_list args; @@ -176,13 +170,13 @@ G_DEFINE_BOXED_TYPE (PangoTabArray, pango_tab_array, /** * pango_tab_array_copy: - * @src: #PangoTabArray to copy + * @src: `PangoTabArray` to copy * - * Copies a #PangoTabArray + * Copies a `PangoTabArray`. * - * Return value: the newly allocated #PangoTabArray, which should - * be freed with pango_tab_array_free(). - **/ + * Return value: the newly allocated `PangoTabArray`, which should + * be freed with [method@Pango.TabArray.free]. + */ PangoTabArray* pango_tab_array_copy (PangoTabArray *src) { @@ -200,13 +194,12 @@ pango_tab_array_copy (PangoTabArray *src) /** * pango_tab_array_free: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * * Frees a tab array and associated resources. - * - **/ + */ void -pango_tab_array_free (PangoTabArray *tab_array) +pango_tab_array_free (PangoTabArray *tab_array) { g_return_if_fail (tab_array != NULL); @@ -217,12 +210,12 @@ pango_tab_array_free (PangoTabArray *tab_array) /** * pango_tab_array_get_size: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * * Gets the number of tab stops in @tab_array. * * Return value: the number of tab stops in the array. - **/ + */ gint pango_tab_array_get_size (PangoTabArray *tab_array) { @@ -233,16 +226,17 @@ pango_tab_array_get_size (PangoTabArray *tab_array) /** * pango_tab_array_resize: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * @new_size: new size of the array * - * Resizes a tab array. You must subsequently initialize any tabs that - * were added as a result of growing the array. + * Resizes a tab array. * - **/ + * You must subsequently initialize any tabs + * that were added as a result of growing the array. + */ void pango_tab_array_resize (PangoTabArray *tab_array, - gint new_size) + gint new_size) { if (new_size > tab_array->allocated) { @@ -250,13 +244,13 @@ pango_tab_array_resize (PangoTabArray *tab_array, /* Ratchet allocated size up above the index. */ if (tab_array->allocated == 0) - tab_array->allocated = 2; + tab_array->allocated = 2; while (new_size > tab_array->allocated) - tab_array->allocated = tab_array->allocated * 2; + tab_array->allocated = tab_array->allocated * 2; tab_array->tabs = g_renew (PangoTab, tab_array->tabs, - tab_array->allocated); + tab_array->allocated); init_tabs (tab_array, current_end, tab_array->allocated); } @@ -266,21 +260,21 @@ pango_tab_array_resize (PangoTabArray *tab_array, /** * pango_tab_array_set_tab: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * @tab_index: the index of a tab stop * @alignment: tab alignment * @location: tab location in Pango units * * Sets the alignment and location of a tab stop. - * @alignment must always be #PANGO_TAB_LEFT in the current - * implementation. * - **/ + * @alignment must always be %PANGO_TAB_LEFT in the current + * implementation. + */ void -pango_tab_array_set_tab (PangoTabArray *tab_array, - gint tab_index, - PangoTabAlign alignment, - gint location) +pango_tab_array_set_tab (PangoTabArray *tab_array, + gint tab_index, + PangoTabAlign alignment, + gint location) { g_return_if_fail (tab_array != NULL); g_return_if_fail (tab_index >= 0); @@ -296,19 +290,18 @@ pango_tab_array_set_tab (PangoTabArray *tab_array, /** * pango_tab_array_get_tab: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * @tab_index: tab stop index * @alignment: (out) (allow-none): location to store alignment, or %NULL * @location: (out) (allow-none): location to store tab position, or %NULL * * Gets the alignment and position of a tab stop. - * - **/ + */ void -pango_tab_array_get_tab (PangoTabArray *tab_array, - gint tab_index, - PangoTabAlign *alignment, - gint *location) +pango_tab_array_get_tab (PangoTabArray *tab_array, + gint tab_index, + PangoTabAlign *alignment, + gint *location) { g_return_if_fail (tab_array != NULL); g_return_if_fail (tab_index < tab_array->size); @@ -323,21 +316,22 @@ pango_tab_array_get_tab (PangoTabArray *tab_array, /** * pango_tab_array_get_tabs: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * @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 - * returned array. + * arrays. * - **/ + * The arrays are of length [method@Pango.TabArray.get_size]. + * You must free the returned array. + */ void pango_tab_array_get_tabs (PangoTabArray *tab_array, - PangoTabAlign **alignments, - gint **locations) + PangoTabAlign **alignments, + gint **locations) { gint i; @@ -353,9 +347,9 @@ pango_tab_array_get_tabs (PangoTabArray *tab_array, while (i < tab_array->size) { if (alignments) - (*alignments)[i] = tab_array->tabs[i].alignment; + (*alignments)[i] = tab_array->tabs[i].alignment; if (locations) - (*locations)[i] = tab_array->tabs[i].location; + (*locations)[i] = tab_array->tabs[i].location; ++i; } @@ -363,13 +357,13 @@ pango_tab_array_get_tabs (PangoTabArray *tab_array, /** * pango_tab_array_get_positions_in_pixels: - * @tab_array: a #PangoTabArray + * @tab_array: a `PangoTabArray` * - * Returns %TRUE if the tab positions are in pixels, %FALSE if they are - * in Pango units. + * Returns %TRUE if the tab positions are in pixels, + * %FALSE if they are in Pango units. * * Return value: whether positions are in pixels. - **/ + */ gboolean pango_tab_array_get_positions_in_pixels (PangoTabArray *tab_array) { |