Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtktable.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkTable
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Pack widgets in regular patterns
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkTable functions allow the programmer to arrange widgets in rows and
  10 columns, making it easy to align many widgets next to each other,
  11 horizontally and vertically.
  12 </para>
  13 <para>
  14 Tables are created with a call to gtk_table_new(), the size of which can
  15 later be changed with gtk_table_resize().
  16 </para>
  17 <para>
  18 Widgets can be added to a table using gtk_table_attach() or the more
  19 convenient (but slightly less flexible) gtk_table_attach_defaults().
  20 </para>
  21 <para>
  22 To alter the space next to a specific row, use gtk_table_set_row_spacing(),
  23 and for a column, gtk_table_set_col_spacing().</para>
  24 <para>
  25 The gaps between <emphasis>all</emphasis> rows or columns can be changed by
  26 calling gtk_table_set_row_spacings() or gtk_table_set_col_spacings()
  27 respectively. Note that spacing is added <emphasis>between</emphasis> the
  28 children, while padding added by gtk_table_atach() is added <emphasis>on
  29 either side</emphasis> of the widget it belongs to.
  30 </para>
  31 <para>
  32 gtk_table_set_homogeneous(), can be used to set whether all cells in the
  33 table will resize themselves to the size of the largest widget in the table.
  34 </para>
  35 <note>
  36 <para>
  37 Note that #GtkGrid provides the same capabilities as GtkTable for arranging
  38 widgets in a rectangular grid, and additionally supports height-for-width
  39 geometry management.
  40 </para>
  41 </note>
  42
  43 <!-- ##### SECTION See_Also ##### -->
  44 <para>
  45 <variablelist>
  46 <varlistentry>
  47 <term>#GtkBox</term>
  48 <listitem><para>For packing widgets in a single row.</para></listitem>
  49 </varlistentry>
  50 <varlistentry>
  51 <term>#GtkGrid</term>
  52 <listitem><para>For packing widgets in a grid with height-for-width geometry management.</para></listitem>
  53 </varlistentry>
  54 </variablelist>
  55 </para>
  56
  57 <!-- ##### SECTION Stability_Level ##### -->
  58
  59
  60 <!-- ##### SECTION Image ##### -->
  61
  62
  63 <!-- ##### STRUCT GtkTable ##### -->
  64 <para>
  65 The <structname>GtkTable</structname> structure holds the data for the actual table itself.
  66
  67 <structfield>children</structfield> is a #GList of all the widgets the table contains. <structfield>rows</structfield> and <structfield>columns</structfield> are pointers to #GtkTableRowCol structures, which contain the default spacing and expansion details for the #GtkTable's rows and columns, respectively.
  68 </para>
  69 <para>
  70 <structfield>nrows</structfield> and <structfield>ncols</structfield> are 16bit integers storing the number of rows and columns the table has.
  71 </para>
  72
  73
  74 <!-- ##### ARG GtkTable:column-spacing ##### -->
  75 <para>
  76
  77 </para>
  78
  79 <!-- ##### ARG GtkTable:homogeneous ##### -->
  80 <para>
  81
  82 </para>
  83
  84 <!-- ##### ARG GtkTable:n-columns ##### -->
  85 <para>
  86
  87 </para>
  88
  89 <!-- ##### ARG GtkTable:n-rows ##### -->
  90 <para>
  91
  92 </para>
  93
  94 <!-- ##### ARG GtkTable:row-spacing ##### -->
  95 <para>
  96
  97 </para>
  98
  99 <!-- ##### ARG GtkTable:bottom-attach ##### -->
 100 <para>
 101
 102 </para>
 103
 104 <!-- ##### ARG GtkTable:left-attach ##### -->
 105 <para>
 106
 107 </para>
 108
 109 <!-- ##### ARG GtkTable:right-attach ##### -->
 110 <para>
 111
 112 </para>
 113
 114 <!-- ##### ARG GtkTable:top-attach ##### -->
 115 <para>
 116
 117 </para>
 118
 119 <!-- ##### ARG GtkTable:x-options ##### -->
 120 <para>
 121
 122 </para>
 123
 124 <!-- ##### ARG GtkTable:x-padding ##### -->
 125 <para>
 126
 127 </para>
 128
 129 <!-- ##### ARG GtkTable:y-options ##### -->
 130 <para>
 131
 132 </para>
 133
 134 <!-- ##### ARG GtkTable:y-padding ##### -->
 135 <para>
 136
 137 </para>
 138
 139 <!-- ##### FUNCTION gtk_table_new ##### -->
 140 <para>
 141 Used to create a new table widget. An initial size must be given by
 142 specifying how many rows and columns the table should have, although
 143 this can be changed later with gtk_table_resize().  @rows and @columns
 144 must both be in the range 1 .. 65535. For historical reasons, 0 is accepted
 145 as well and is silently interpreted as 1.
 146 </para>
 147
 148 @rows: The number of rows the new table should have.
 149 @columns: The number of columns the new table should have.
 150 @homogeneous: If set to %TRUE, all table cells are resized to the size of the cell
 151 containing the largest widget.
 152 @Returns: A pointer to the the newly created table widget.
 153
 154
 155 <!-- ##### FUNCTION gtk_table_resize ##### -->
 156 <para>
 157 If you need to change a table's size <emphasis>after</emphasis> it has been created, this function allows you to do so.
 158 </para>
 159
 160 @table: The #GtkTable you wish to change the size of.
 161 @rows: The new number of rows.
 162 @columns: The new number of columns.
 163
 164
 165 <!-- ##### FUNCTION gtk_table_get_size ##### -->
 166 <para>
 167
 168 </para>
 169
 170 @table:
 171 @rows:
 172 @columns:
 173
 174
 175 <!-- ##### FUNCTION gtk_table_attach ##### -->
 176 <para>
 177 Adds a widget to a table. The number of 'cells' that a widget will occupy is
 178 specified by @left_attach, @right_attach, @top_attach and @bottom_attach.
 179 These each represent the leftmost, rightmost, uppermost and lowest column
 180 and row numbers of the table. (Columns and rows are indexed from zero).
 181 </para>
 182 <para>
 183 To make a button occupy the lower right cell of a 2x2 table, use
 184 <informalexample><programlisting>
 185 gtk_table_attach (table, button,
 186                   1, 2, /* left, right attach */
 187                   1, 2, /* top, bottom attach */
 188                   xoptions, yoptions,
 189                   xpadding, ypadding);
 190 </programlisting></informalexample>
 191 If you want to make the button span the entire bottom row, use @left_attach == 0 and @right_attach = 2 instead.
 192 </para>
 193
 194 @table: The #GtkTable to add a new widget to.
 195 @child: The widget to add.
 196 @left_attach: the column number to attach the left side of a child widget to.
 197 @right_attach: the column number to attach the right side of a child widget to.
 198 @top_attach: the row number to attach the top of a child widget to.
 199 @bottom_attach: the row number to attach the bottom of a child widget to.
 200 @xoptions: Used to specify the properties of the child widget when the table is resized.
 201 @yoptions: The same as xoptions, except this field determines behaviour of vertical resizing.
 202 @xpadding: An integer value specifying the padding on the left and right of the widget being added to the table.
 203 @ypadding: The amount of padding above and below the child widget.
 204
 205
 206 <!-- ##### FUNCTION gtk_table_attach_defaults ##### -->
 207 <para>
 208 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 <literal>GTK_EXPAND | GTK_FILL</literal>, and the padding is set to 0.
 209 </para>
 210
 211 @table: The table to add a new child widget to.
 212 @widget: The child widget to add.
 213 @left_attach: The column number to attach the left side of the child widget to.
 214 @right_attach: The column number to attach the right side of the child widget to.
 215 @top_attach: The row number to attach the top of the child widget to.
 216 @bottom_attach: The row number to attach the bottom of the child widget to.
 217
 218
 219 <!-- ##### FUNCTION gtk_table_set_row_spacing ##### -->
 220 <para>
 221 Changes the space between a given table row and the subsequent row.
 222 </para>
 223
 224 @table: a #GtkTable containing the row whose properties you wish to change.
 225 @row: row number whose spacing will be changed.
 226 @spacing: number of pixels that the spacing should take up.
 227
 228
 229 <!-- ##### FUNCTION gtk_table_set_col_spacing ##### -->
 230 <para>
 231 Alters the amount of space between a given table column and the following
 232 column.
 233 </para>
 234
 235 @table: a #GtkTable.
 236 @column: the column whose spacing should be changed.
 237 @spacing: number of pixels that the spacing should take up.
 238
 239
 240 <!-- ##### FUNCTION gtk_table_set_row_spacings ##### -->
 241 <para>
 242 Sets the space between every row in @table equal to @spacing.
 243 </para>
 244
 245 @table: a #GtkTable.
 246 @spacing: the number of pixels of space to place between every row in the table.
 247
 248
 249 <!-- ##### FUNCTION gtk_table_set_col_spacings ##### -->
 250 <para>
 251 Sets the space between every column in @table equal to @spacing.
 252 </para>
 253
 254 @table: a #GtkTable.
 255 @spacing: the number of pixels of space to place between every column in the table.
 256
 257
 258 <!-- ##### FUNCTION gtk_table_set_homogeneous ##### -->
 259 <para>
 260 Changes the homogenous property of table cells, ie. whether all cells are an equal size or not.
 261 </para>
 262
 263 @table: The #GtkTable you wish to set the homogeneous properties of.
 264 @homogeneous: Set to %TRUE to ensure all table cells are the same size. Set
 265 to %FALSE if this is not your desired behaviour.
 266
 267
 268 <!-- ##### FUNCTION gtk_table_get_default_row_spacing ##### -->
 269 <para>
 270
 271 </para>
 272
 273 @table:
 274 @Returns:
 275
 276
 277 <!-- ##### FUNCTION gtk_table_get_homogeneous ##### -->
 278 <para>
 279
 280 </para>
 281
 282 @table:
 283 @Returns:
 284
 285
 286 <!-- ##### FUNCTION gtk_table_get_row_spacing ##### -->
 287 <para>
 288
 289 </para>
 290
 291 @table:
 292 @row:
 293 @Returns:
 294
 295
 296 <!-- ##### FUNCTION gtk_table_get_col_spacing ##### -->
 297 <para>
 298
 299 </para>
 300
 301 @table:
 302 @column:
 303 @Returns:
 304
 305
 306 <!-- ##### FUNCTION gtk_table_get_default_col_spacing ##### -->
 307 <para>
 308
 309 </para>
 310
 311 @table:
 312 @Returns:
 313
 314