## Tab Stops

Tab Stops — Structures for storing tab stops

## Synopsis

                        PangoTabArray;
    #define             PANGO_TYPE_TAB_ARRAY
    enum                PangoTabAlign;
    #define             PANGO_TYPE_TAB_ALIGN
    PangoTabArray*      pango_tab_array_new                 (gint initial_size,
                                                             gboolean positions_in_pixels);
    PangoTabArray*      pango_tab_array_new_with_positions  (gint size,
                                                             gboolean positions_in_pixels,
                                                             PangoTabAlign first_alignment,
                                                             gint first_position,
                                                             ...);
    PangoTabArray*      pango_tab_array_copy                (PangoTabArray *src);
    void                pango_tab_array_free                (PangoTabArray *tab_array);
    gint                pango_tab_array_get_size            (PangoTabArray *tab_array);
    void                pango_tab_array_resize              (PangoTabArray *tab_array,
                                                             gint new_size);
    void                pango_tab_array_set_tab             (PangoTabArray *tab_array,
                                                             gint tab_index,
                                                             PangoTabAlign alignment,
                                                             gint location);
    void                pango_tab_array_get_tab             (PangoTabArray *tab_array,
                                                             gint tab_index,
                                                             PangoTabAlign *alignment,
                                                             gint *location);
    void                pango_tab_array_get_tabs            (PangoTabArray *tab_array,
                                                             PangoTabAlign **alignments,
                                                             gint **locations);
    gboolean            pango_tab_array_get_positions_in_pixels
                                                            (PangoTabArray *tab_array);

## Description

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

## Details

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

    typedef enum
    {
      PANGO_TAB_LEFT

      /* These are not supported now, but may be in the
       * future.
       *
       *  PANGO_TAB_RIGHT,
       *  PANGO_TAB_CENTER,
       *  PANGO_TAB_NUMERIC
       */
    } PangoTabAlign;

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

`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())

The GObject type for PangoTabAlign.

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

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

`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

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

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

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

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

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

`tab_array` : | a PangoTabArray
`tab_index` : | tab stop index
`alignment` : | location to store alignment, or `NULL`
`location` : | location to store tab position, or `NULL`

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

`tab_array` : | a PangoTabArray
`alignments` : | location to store an array of tab stop alignments, or `NULL`
`locations` : | location to store an array of tab positions, or `NULL`

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

`tab_array` : | a PangoTabArray
Returns : | whether positions are in pixels.