Tab Stops: Pango Reference Manual

Tab Stops

Tab Stops — Structures for storing tab stops

Functions

PangoTabArray *	pango_tab_array_new ()
PangoTabArray *	pango_tab_array_new_with_positions ()
PangoTabArray *	pango_tab_array_copy ()
void	pango_tab_array_free ()
gint	pango_tab_array_get_size ()
void	pango_tab_array_resize ()
void	pango_tab_array_set_tab ()
void	pango_tab_array_get_tab ()
void	pango_tab_array_get_tabs ()
gboolean	pango_tab_array_get_positions_in_pixels ()

Types and Values

	PangoTabArray
#define	PANGO_TYPE_TAB_ARRAY
enum	PangoTabAlign
#define	PANGO_TYPE_TAB_ALIGN

Object Hierarchy

    GBoxed
    ╰── PangoTabArray
    GEnum
    ╰── PangoTabAlign

Description

Functions in this section are used to deal with PangoTabArray objects that can be used to set tab stop positions in a PangoLayout.

Functions

pango_tab_array_new ()

PangoTabArray *
pango_tab_array_new (gint initial_size,
                     gboolean positions_in_pixels);

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.

Parameters

initial_size	Initial number of tab stops to allocate, can be 0
positions_in_pixels	whether positions are in pixel units

Returns

the newly allocated PangoTabArray, which should be freed with pango_tab_array_free().

pango_tab_array_new_with_positions ()

PangoTabArray *
pango_tab_array_new_with_positions (gint size,
                                    gboolean positions_in_pixels,
                                    PangoTabAlign first_alignment,
                                    gint first_position,
                                    ...);

This is a convenience function that 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.

Parameters

size	number of tab stops in the array
positions_in_pixels	whether positions are in pixel units
first_alignment	alignment of first tab stop
first_position	position of first tab stop
...	additional alignment/position pairs

Returns

the newly allocated PangoTabArray, which should be freed with pango_tab_array_free().

pango_tab_array_copy ()

PangoTabArray *
pango_tab_array_copy (PangoTabArray *src);

Copies a PangoTabArray

Parameters

src

PangoTabArray to copy

Returns

the newly allocated PangoTabArray, which should be freed with pango_tab_array_free().

pango_tab_array_free ()

void
pango_tab_array_free (PangoTabArray *tab_array);

Frees a tab array and associated resources.

Parameters

tab_array

a PangoTabArray

pango_tab_array_get_size ()

gint
pango_tab_array_get_size (PangoTabArray *tab_array);

Gets the number of tab stops in tab_array .

Parameters

tab_array

a PangoTabArray

Returns

the number of tab stops in the array.

pango_tab_array_resize ()

void
pango_tab_array_resize (PangoTabArray *tab_array,
                        gint new_size);

Resizes a tab array. You must subsequently initialize any tabs that were added as a result of growing the array.

Parameters

tab_array	a PangoTabArray
new_size	new size of the array

pango_tab_array_set_tab ()

void
pango_tab_array_set_tab (PangoTabArray *tab_array,
                         gint tab_index,
                         PangoTabAlign alignment,
                         gint location);

Sets the alignment and location of a tab stop. alignment must always be PANGO_TAB_LEFT in the current implementation.

Parameters

tab_array	a PangoTabArray
tab_index	the index of a tab stop
alignment	tab alignment
location	tab location in Pango units

pango_tab_array_get_tab ()

void
pango_tab_array_get_tab (PangoTabArray *tab_array,
                         gint tab_index,
                         PangoTabAlign *alignment,
                         gint *location);

Gets the alignment and position of a tab stop.

Parameters

tab_array	a PangoTabArray
tab_index	tab stop index
alignment	location to store alignment, or `NULL`.	[out][allow-none]
location	location to store tab position, or `NULL`.	[out][allow-none]

pango_tab_array_get_tabs ()

void
pango_tab_array_get_tabs (PangoTabArray *tab_array,
                          PangoTabAlign **alignments,
                          gint **locations);

If non-NULL, alignments and locations are filled with allocated arrays of length pango_tab_array_get_size(). You must free the returned array.

Parameters

tab_array	a PangoTabArray
alignments	location to store an array of tab stop alignments, or `NULL`.	[out][allow-none]
locations	location to store an array of tab positions, or `NULL`.	[out][allow-none][array]

pango_tab_array_get_positions_in_pixels ()

gboolean
pango_tab_array_get_positions_in_pixels
                               (PangoTabArray *tab_array);

Returns TRUE if the tab positions are in pixels, FALSE if they are in Pango units.

Parameters

tab_array

a PangoTabArray

Returns

whether positions are in pixels.

Types and Values

PangoTabArray

typedef struct _PangoTabArray PangoTabArray;

A PangoTabArray struct contains an array of tab stops. Each tab stop has an alignment and a position.

PANGO_TYPE_TAB_ARRAY

#define PANGO_TYPE_TAB_ARRAY (pango_tab_array_get_type ())

The GObject type for PangoTabArray.

enum PangoTabAlign

A PangoTabAlign specifies where a tab stop appears relative to the text.

Members

PANGO_TAB_LEFT

the tab stop appears to the left of the text.

PANGO_TYPE_TAB_ALIGN

#define PANGO_TYPE_TAB_ALIGN (pango_tab_align_get_type ())