## GtkTable

GtkTable — Pack widgets in regular patterns

## Synopsis

    #include <gtk/gtk.h>

                GtkTable;
                GtkTableChild;
                GtkTableRowCol;
    GtkWidget*  gtk_table_new                   (guint rows,
                                                 guint columns,
                                                 gboolean homogeneous);
    void        gtk_table_resize                (GtkTable *table,
                                                 guint rows,
                                                 guint columns);
    void        gtk_table_attach                (GtkTable *table,
                                                 GtkWidget *child,
                                                 guint left_attach,
                                                 guint right_attach,
                                                 guint top_attach,
                                                 guint bottom_attach,
                                                 GtkAttachOptions xoptions,
                                                 GtkAttachOptions yoptions,
                                                 guint xpadding,
                                                 guint ypadding);
    void        gtk_table_attach_defaults       (GtkTable *table,
                                                 GtkWidget *widget,
                                                 guint left_attach,
                                                 guint right_attach,
                                                 guint top_attach,
                                                 guint bottom_attach);
    void        gtk_table_set_row_spacing       (GtkTable *table,
                                                 guint row,
                                                 guint spacing);
    void        gtk_table_set_col_spacing       (GtkTable *table,
                                                 guint column,
                                                 guint spacing);
    void        gtk_table_set_row_spacings      (GtkTable *table,
                                                 guint spacing);
    void        gtk_table_set_col_spacings      (GtkTable *table,
                                                 guint spacing);
    void        gtk_table_set_homogeneous       (GtkTable *table,
                                                 gboolean homogeneous);
    guint       gtk_table_get_default_row_spacing
                                                (GtkTable *table);
    gboolean    gtk_table_get_homogeneous       (GtkTable *table);
    guint       gtk_table_get_row_spacing       (GtkTable *table,
                                                 guint row);
    guint       gtk_table_get_col_spacing       (GtkTable *table,
                                                 guint column);
    guint       gtk_table_get_default_col_spacing
                                                (GtkTable *table);

## Object Hierarchy

      GObject
       +----GtkObject
             +----GtkWidget
                   +----GtkContainer
                         +----GtkTable

## Implemented Interfaces

GtkTable implements AtkImplementorIface.

## Properties

      "column-spacing"       guint                 : Read / Write
      "homogeneous"          gboolean              : Read / Write
      "n-columns"            guint                 : Read / Write
      "n-rows"               guint                 : Read / Write
      "row-spacing"          guint                 : Read / Write

## Child Properties

      "bottom-attach"        guint                 : Read / Write
      "left-attach"          guint                 : Read / Write
      "right-attach"         guint                 : Read / Write
      "top-attach"           guint                 : Read / Write
      "x-options"            GtkAttachOptions      : Read / Write
      "x-padding"            guint                 : Read / Write
      "y-options"            GtkAttachOptions      : Read / Write
      "y-padding"            guint                 : Read / Write

## Description

The GtkTable functions allow the programmer to arrange widgets in rows and columns, making it easy to align many widgets next to each other, horizontally and vertically.

Tables are created with a call to `gtk_table_new()`, the size of which can later be changed with `gtk_table_resize()`.

Widgets can be added to a table using `gtk_table_attach()` or the more convenient (but slightly less flexible) `gtk_table_attach_defaults()`.

To alter the space next to a specific row, use `gtk_table_set_row_spacing()`, and for a column, `gtk_table_set_col_spacing()`.

The gaps between all rows or columns can be changed by calling `gtk_table_set_row_spacings()` or `gtk_table_set_col_spacings()` respectively.

`gtk_table_set_homogeneous()`, can be used to set whether all cells in the table will resize themselves to the size of the largest widget in the table.

## Details

### GtkTable

    typedef struct _GtkTable GtkTable;

The GtkTable structure holds the data for the actual table itself. `children` is a GList of all the widgets the table contains. `rows` and `columns` are pointers to GtkTableRowCol structures, which contain the default spacing and expansion details for the GtkTable's rows and columns, respectively.

`nrows` and `ncols` are 16bit integers storing the number of rows and columns the table has.

### GtkTableChild

    typedef struct {
      GtkWidget *widget;
      guint16 left_attach;
      guint16 right_attach;
      guint16 top_attach;
      guint16 bottom_attach;
      guint16 xpadding;
      guint16 ypadding;
      guint xexpand : 1;
      guint yexpand : 1;
      guint xshrink : 1;
      guint yshrink : 1;
      guint xfill : 1;
      guint yfill : 1;
    } GtkTableChild;

The `widget` field is a pointer to the widget that this `GtkTableChild` structure is keeping track of. The `left_attach`, `right_attach`, `top_attach`, and `bottom_attach` fields specify the row and column numbers which make up the invisible rectangle that the child widget is packed into.

`xpadding` and `ypadding` specify the space between this widget and the surrounding table cells.

### GtkTableRowCol

    typedef struct {
      guint16 requisition;
      guint16 allocation;
      guint16 spacing;
      guint need_expand : 1;
      guint need_shrink : 1;
      guint expand : 1;
      guint shrink : 1;
      guint empty : 1;
    } GtkTableRowCol;

These fields should be considered read-only and not be modified directly.

### gtk_table_new ()

    GtkWidget*  gtk_table_new                   (guint rows,
                                                 guint columns,
                                                 gboolean homogeneous);

Used to create a new table widget. An initial size must be given by specifying how many rows and columns the table should have, although this can be changed later with `gtk_table_resize()`. `rows` and `columns` must both be in the range 0 .. 65535.

`rows` : | The number of rows the new table should have.
`columns` : | The number of columns the new table should have.
`homogeneous` : | If set to `TRUE`, all table cells are resized to the size of the cell containing the largest widget.
Returns : | A pointer to the the newly created table widget.

### gtk_table_resize ()

    void        gtk_table_resize                (GtkTable *table,
                                                 guint rows,
                                                 guint columns);

If you need to change a table's size after it has been created, this function allows you to do so.

`table` : | The GtkTable you wish to change the size of.
`rows` : | The new number of rows.
`columns` : | The new number of columns.

### gtk_table_attach ()

    void        gtk_table_attach                (GtkTable *table,
                                                 GtkWidget *child,
                                                 guint left_attach,
                                                 guint right_attach,
                                                 guint top_attach,
                                                 guint bottom_attach,
                                                 GtkAttachOptions xoptions,
                                                 GtkAttachOptions yoptions,
                                                 guint xpadding,
                                                 guint ypadding);

Adds a widget to a table. The number of 'cells' that a widget will occupy is specified by `left_attach`, `right_attach`, `top_attach` and `bottom_attach`. These each represent the leftmost, rightmost, uppermost and lowest column and row numbers of the table. (Columns and rows are indexed from zero).

`table` : | The GtkTable to add a new widget to.
`child` : | The widget to add.
`left_attach` : | the column number to attach the left side of a child widget to.
`right_attach` : | the column number to attach the right side of a child widget to.
`top_attach` : | the row number to attach the top of a child widget to.
`bottom_attach` : | the row number to attach the bottom of a child widget to.
`xoptions` : | Used to specify the properties of the child widget when the table is resized.
`yoptions` : | The same as xoptions, except this field determines behaviour of vertical resizing.
`xpadding` : | An integer value specifying the padding on the left and right of the widget being added to the table.
`ypadding` : | The amount of padding above and below the child widget.

### gtk_table_attach_defaults ()

    void        gtk_table_attach_defaults       (GtkTable *table,
                                                 GtkWidget *widget,
                                                 guint left_attach,
                                                 guint right_attach,
                                                 guint top_attach,
                                                 guint bottom_attach);

As there are many options associated with `gtk_table_attach()`, this convenience function provides the programmer with a means to add children to a table with identical padding and expansion options. The values used for the GtkAttachOptions are `GTK_EXPAND | GTK_FILL`, and the padding is set to 0.

`table` : | The table to add a new child widget to.
`widget` : | The child widget to add.
`left_attach` : | The column number to attach the left side of the child widget to.
`right_attach` : | The column number to attach the right side of the child widget to.
`top_attach` : | The row number to attach the top of the child widget to.
`bottom_attach` : | The row number to attach the bottom of the child widget to.

### gtk_table_set_row_spacing ()

    void        gtk_table_set_row_spacing       (GtkTable *table,
                                                 guint row,
                                                 guint spacing);

Changes the space between a given table row and its surrounding rows.

`table` : | a GtkTable containing the row whose properties you wish to change.
`row` : | row number whose spacing will be changed.
`spacing` : | number of pixels that the spacing should take up.

### gtk_table_set_col_spacing ()

    void        gtk_table_set_col_spacing       (GtkTable *table,
                                                 guint column,
                                                 guint spacing);

Alters the amount of space between a given table column and the adjacent columns.

`table` : | a GtkTable.
`column` : | the column whose spacing should be changed.
`spacing` : | number of pixels that the spacing should take up.

### gtk_table_set_row_spacings ()

    void        gtk_table_set_row_spacings      (GtkTable *table,
                                                 guint spacing);

Sets the space between every row in `table` equal to `spacing`.

`table` : | a GtkTable.
`spacing` : | the number of pixels of space to place between every row in the table.

### gtk_table_set_col_spacings ()

    void        gtk_table_set_col_spacings      (GtkTable *table,
                                                 guint spacing);

Sets the space between every column in `table` equal to `spacing`.

`table` : | a GtkTable.
`spacing` : | the number of pixels of space to place between every column in the table.

### gtk_table_set_homogeneous ()

    void        gtk_table_set_homogeneous       (GtkTable *table,
                                                 gboolean homogeneous);

Changes the homogenous property of table cells, ie. whether all cells are an equal size or not.

`table` : | The GtkTable you wish to set the homogeneous properties of.
`homogeneous` : | Set to `TRUE` to ensure all table cells are the same size. Set to `FALSE` if this is not your desired behaviour.

### gtk_table_get_default_row_spacing ()

    guint       gtk_table_get_default_row_spacing
                                                (GtkTable *table);

Gets the default row spacing for the table. This is the spacing that will be used for newly added rows. (See `gtk_table_set_row_spacings()`)

`table` : | a GtkTable
Returns : | value: the default row spacing

### gtk_table_get_homogeneous ()

    gboolean    gtk_table_get_homogeneous       (GtkTable *table);

Returns whether the table cells are all constrained to the same width and height. (See `gtk_table_set_homogenous()`)

`table` : | a GtkTable
Returns : | `TRUE` if the cells are all constrained to the same size

### gtk_table_get_row_spacing ()

    guint       gtk_table_get_row_spacing       (GtkTable *table,
                                                 guint row);

Gets the amount of space between row `row`, and row `row` + 1. See `gtk_table_set_row_spacing()`.

`table` : | a GtkTable
`row` : | a row in the table, 0 indicates the first row
Returns : | the row spacing

### gtk_table_get_col_spacing ()

    guint       gtk_table_get_col_spacing       (GtkTable *table,
                                                 guint column);

Gets the amount of space between column `col`, and column `col` + 1. See `gtk_table_set_col_spacing()`.

`table` : | a GtkTable
`column` : | a column in the table, 0 indicates the first column
Returns : | the column spacing

### gtk_table_get_default_col_spacing ()

    guint       gtk_table_get_default_col_spacing
                                                (GtkTable *table);

Gets the default column spacing for the table. This is the spacing that will be used for newly added columns. (See `gtk_table_set_col_spacings()`)

`table` : | a GtkTable
Returns : | value: the default column spacing

## Properties

### The "`column-spacing`" property

      "column-spacing"       guint                 : Read / Write

The amount of space between two consecutive columns.

Default value: 0

### The "`homogeneous`" property

      "homogeneous"          gboolean              : Read / Write

If TRUE this means the table cells are all the same width/height.

Default value: FALSE

### The "`n-columns`" property

      "n-columns"            guint                 : Read / Write

The number of columns in the table.

Default value: 0

### The "`n-rows`" property

      "n-rows"               guint                 : Read / Write

The number of rows in the table.

Default value: 0

### The "`row-spacing`" property

      "row-spacing"          guint                 : Read / Write

The amount of space between two consecutive rows.

Default value: 0

## Child Properties

### The "`bottom-attach`" child property

      "bottom-attach"        guint                 : Read / Write

The row number to attach the bottom of the child to.

Allowed values: [1,65535]

Default value: 1

### The "`left-attach`" child property

      "left-attach"          guint                 : Read / Write

The column number to attach the left side of the child to.

Allowed values: <= 65535

Default value: 0

### The "`right-attach`" child property

      "right-attach"         guint                 : Read / Write

The column number to attach the right side of a child widget to.

Allowed values: [1,65535]

Default value: 1

### The "`top-attach`" child property

      "top-attach"           guint                 : Read / Write

The row number to attach the top of a child widget to.

Allowed values: <= 65535

Default value: 0

### The "`x-options`" child property

      "x-options"            GtkAttachOptions      : Read / Write

Options specifying the horizontal behaviour of the child.

Default value: GTK_EXPAND|GTK_FILL

### The "`x-padding`" child property

      "x-padding"            guint                 : Read / Write

Extra space to put between the child and its left and right neighbors, in pixels.

Allowed values: <= 65535

Default value: 0

### The "`y-options`" child property

      "y-options"            GtkAttachOptions      : Read / Write

Options specifying the vertical behaviour of the child.

Default value: GTK_EXPAND|GTK_FILL

### The "`y-padding`" child property

      "y-padding"            guint                 : Read / Write

Extra space to put between the child and its upper and lower neighbors, in pixels.

Allowed values: <= 65535

Default value: 0

## See Also

GtkVBox | For packing widgets vertically only.
GtkHBox | For packing widgets horizontally only.