GtkTable: GTK+ 3 Reference Manual

## GtkTable GtkTable — Pack widgets in regular patterns |

## Functions

GtkWidget * | gtk_table_new ()
void | gtk_table_resize ()
void | gtk_table_get_size ()
void | gtk_table_attach ()
void | gtk_table_attach_defaults ()
void | gtk_table_set_row_spacing ()
void | gtk_table_set_col_spacing ()
void | gtk_table_set_row_spacings ()
void | gtk_table_set_col_spacings ()
void | gtk_table_set_homogeneous ()
guint | gtk_table_get_default_row_spacing ()
gboolean | gtk_table_get_homogeneous ()
guint | gtk_table_get_row_spacing ()
guint | gtk_table_get_col_spacing ()
guint | gtk_table_get_default_col_spacing ()

## Properties

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

## Child Properties

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

## Types and Values

struct | GtkTable
enum | GtkAttachOptions

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkTable

## Implemented Interfaces

GtkTable implements AtkImplementorIface and GtkBuildable.

## Includes

    #include <gtk/gtk.h>

## 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. Note that spacing is added between the children, while padding added by `gtk_table_attach()` is added on either side of the widget it belongs to.

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.

> GtkTable has been deprecated. Use GtkGrid instead. It provides the same capabilities as GtkTable for arranging widgets in a rectangular grid, but does support height-for-width geometry management.

## Functions

### gtk_table_new ()

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

`gtk_table_new` has been deprecated since version 3.4 and should not be used in newly-written code.

Use `gtk_grid_new()`.

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 1 .. 65535. For historical reasons, 0 is accepted as well and is silently interpreted as 1.

#### Parameters

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 newly created table widget.

### gtk_table_resize ()

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

`gtk_table_resize` has been deprecated since version 3.4 and should not be used in newly-written code.

GtkGrid resizes automatically.

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

#### Parameters

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

### gtk_table_get_size ()

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

`gtk_table_get_size` has been deprecated since version 3.4 and should not be used in newly-written code.

GtkGrid does not expose the number of columns and rows.

Gets the number of rows and columns in the table.

#### Parameters

table | a GtkTable |
rows | return location for the number of rows, or `NULL`. | [out][allow-none]
columns | return location for the number of columns, or `NULL`. | [out][allow-none]

Since: 2.22

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

`gtk_table_attach` has been deprecated since version 3.4 and should not be used in newly-written code.

Use `gtk_grid_attach()` with GtkGrid. Note that the attach arguments differ between those two functions.

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

To make a button occupy the lower right cell of a 2x2 table, use

    1
    2
    3
    4
    5
    gtk_table_attach (table, button,
                      1, 2, // left, right attach
                      1, 2, // top, bottom attach
                      xoptions, yoptions,
                      xpadding, ypadding);

If you want to make the button span the entire bottom row, use `left_attach` == 0 and `right_attach` = 2 instead.

#### Parameters

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);

`gtk_table_attach_defaults` has been deprecated since version 3.4 and should not be used in newly-written code.

Use `gtk_grid_attach()` with GtkGrid. Note that the attach arguments differ between those two functions.

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.

#### Parameters

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);

`gtk_table_set_row_spacing` has been deprecated since version 3.4 and should not be used in newly-written code.

Use `gtk_widget_set_margin_top()` and `gtk_widget_set_margin_bottom()` on the widgets contained in the row if you need this functionality. GtkGrid does not support per-row spacing.

Changes the space between a given table row and the subsequent row.

#### Parameters

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);

`gtk_table_set_col_spacing` has been deprecated since version 3.4 and should not be used in newly-written code.

Use `gtk_widget_set_margin_start()` and `gtk_widget_set_margin_end()` on the widgets contained in the row if you need this functionality. GtkGrid does not support per-row spacing.

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

#### Parameters

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);

`gtk_table_set_row_spacings` has been deprecated since version 3.4 and should not be used in newly-written code.

Use `gtk_grid_set_row_spacing()` with GtkGrid.

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

#### Parameters

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);

`gtk_table_set_col_spacings` has been deprecated since version 3.4 and should not be used in newly-written code.

Use `gtk_grid_set_column_spacing()` with GtkGrid.

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

#### Parameters

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);

`gtk_table_set_homogeneous` has been deprecated since version 3.4 and should not be used in newly-written code.

Use `gtk_grid_set_row_homogeneous()` and `gtk_grid_set_column_homogeneous()` with GtkGrid.

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

#### Parameters

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);

`gtk_table_get_default_row_spacing` has been deprecated since version 3.4 and should not be used in newly-written code.

Use `gtk_grid_get_row_spacing()` with GtkGrid.

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

#### Parameters

table | a GtkTable |

#### Returns

the default row spacing

### gtk_table_get_homogeneous ()

    gboolean
    gtk_table_get_homogeneous (GtkTable *table);

`gtk_table_get_homogeneous` has been deprecated since version 3.4 and should not be used in newly-written code.

Use `gtk_grid_get_row_homogeneous()` and `gtk_grid_get_column_homogeneous()` with GtkGrid.

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

#### Parameters

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);

`gtk_table_get_row_spacing` has been deprecated since version 3.4 and should not be used in newly-written code.

GtkGrid does not offer a replacement for this functionality.

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

#### Parameters

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);

`gtk_table_get_col_spacing` has been deprecated since version 3.4 and should not be used in newly-written code.

GtkGrid does not offer a replacement for this functionality.

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

#### Parameters

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);

`gtk_table_get_default_col_spacing` has been deprecated since version 3.4 and should not be used in newly-written code.

Use `gtk_grid_get_column_spacing()` with GtkGrid.

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

#### Parameters

table | a GtkTable |

#### Returns

the default column spacing

## Types and Values

### struct GtkTable

    struct GtkTable;

### enum GtkAttachOptions

Denotes the expansion properties that a widget will have when it (or its parent) is resized.

#### Members

GTK_EXPAND | the widget should expand to take up any extra space in its container that has been allocated. |
GTK_SHRINK | the widget should shrink as and when possible. |
GTK_FILL | the widget should fill the space allocated to it. |

## Property Details

### The `“column-spacing”` property

      “column-spacing”           guint

The amount of space between two consecutive columns.

Owner: GtkTable

Flags: Read / Write

Allowed values: <= 65535

Default value: 0

### The `“homogeneous”` property

      “homogeneous”              gboolean

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

Owner: GtkTable

Flags: Read / Write

Default value: FALSE

### The `“n-columns”` property

      “n-columns”                guint

The number of columns in the table.

Owner: GtkTable

Flags: Read / Write

Allowed values: [1,65535]

Default value: 1

### The `“n-rows”` property

      “n-rows”                   guint

The number of rows in the table.

Owner: GtkTable

Flags: Read / Write

Allowed values: [1,65535]

Default value: 1

### The `“row-spacing”` property

      “row-spacing”              guint

The amount of space between two consecutive rows.

Owner: GtkTable

Flags: Read / Write

Allowed values: <= 65535

Default value: 0

## Child Property Details

### The `“bottom-attach”` child property

      “bottom-attach”            guint

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

Owner: GtkTable

Flags: Read / Write

Allowed values: [1,65535]

Default value: 1

### The `“left-attach”` child property

      “left-attach”              guint

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

Owner: GtkTable

Flags: Read / Write

Allowed values: <= 65535

Default value: 0

### The `“right-attach”` child property

      “right-attach”             guint

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

Owner: GtkTable

Flags: Read / Write

Allowed values: [1,65535]

Default value: 1

### The `“top-attach”` child property

      “top-attach”               guint

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

Owner: GtkTable

Flags: Read / Write

Allowed values: <= 65535

Default value: 0

### The `“x-options”` child property

      “x-options”                GtkAttachOptions

Options specifying the horizontal behaviour of the child.

Owner: GtkTable

Flags: Read / Write

Default value: GTK_EXPAND | GTK_FILL

### The `“x-padding”` child property

      “x-padding”                guint

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

Owner: GtkTable

Flags: Read / Write

Allowed values: <= 65535

Default value: 0

### The `“y-options”` child property

      “y-options”                GtkAttachOptions

Options specifying the vertical behaviour of the child.

Owner: GtkTable

Flags: Read / Write

Default value: GTK_EXPAND | GTK_FILL

### The `“y-padding”` child property

      “y-padding”                guint

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

Owner: GtkTable

Flags: Read / Write

Allowed values: <= 65535

Default value: 0

## See Also

GtkGrid