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