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