Tab Stops: Pango Reference Manual

## Tab Stops Tab Stops — Structures for storing tab stops |

## Functions

#define | PANGO_TYPE_TAB_ARRAY
#define | PANGO_TYPE_TAB_ALIGN
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
enum | PangoTabAlign

## 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_TYPE_TAB_ARRAY

    #define PANGO_TYPE_TAB_ARRAY (pango_tab_array_get_type ())

The GObject type for PangoTabArray.

### PANGO_TYPE_TAB_ALIGN

    #define PANGO_TYPE_TAB_ALIGN (pango_tab_align_get_type ())

### 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.

### 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. |