HelpSource/Classes/GridLayout.schelp

   1 CLASS:: GridLayout
   2 summary:: A layout that organizes views in a grid
   3 categories:: GUI>Layout
   4 related:: Classes/HLayout, Classes/VLayout, Classes/StackLayout, Guides/GUI-Layout-Management
   5 redirect:: implClass
   6
   7 DESCRIPTION::
   8
   9 note:: GridLayout is only implemented in strong::Qt GUI:: ::
  10
  11 GridLayout distributes its space into a strong::grid of rows and columns::, where each item can occupy strong::one or more cells::.
  12
  13 You can construct the layout in two ways using link::#*rows:: and link::#*columns::. In the former constructor you pass arrays of items by rows, and in the latter by columns. Items can also be added later using link::#-add:: and link::#-addSpanning::. To remove an item, simply use link::Classes/View#-remove:: for views, or link::Classes/QObject#-destroy:: for views or layouts.
  14
  15 It is possible to add more than one view into the same cell. The last added view will be the top-most. However, it is most probably more convenient to use a link::Classes/StackLayout:: for that purpose.
  16
  17 The layout manages the grid size automatically: you can add an item at any row and cell number. When items are added or removed, the grid will re-adjust according to the last occupied row and column.
  18
  19 subsection:: Fine tuning
  20
  21 Each item can be assigned an strong::alignment:: either at layout link::#*rows#construction:: or later using link::#-setAlignment::. An item will then get at most its default size, if available (see: link::Classes/View#-sizeHint::), and will be aligned within its cell according to the specified alignment.
  22
  23 Each row or column can be assigned a strong::stretch factor:: using link::#-setRowStretch:: and link::#-setColumnStretch::. Rows or columns that would otherwise get equal space are then distributed according to the relative proportions of their stretch factors.
  24
  25 Each row or column can also be assigned a strong::minimum:: size using link::#-setMinRowHeight:: and link::#-setMinColumnWidth::, to override the size contraints imposed by the contained views.
  26
  27 In addition to adjusting the spacing between cells using link::Classes/QLayout#-spacing:: you can control the spacing between rows and between columns separately using link::#-hSpacing:: and link::#-vSpacing::.
  28
  29 subsection:: Leaving empty space
  30
  31 You can leave any cell empty by not placing any item into it, or at link::#*rows#construction:: using code::nil:: instead of a view or another layout. Note though that the empty cells will always be regarded as freely stretchable and will not impose any constraints on space distribution.
  32
  33
  34
  35 CLASSMETHODS::
  36
  37 PRIVATE:: key
  38 PRIVATE:: qtClass
  39
  40 METHOD:: rows
  41
  42     Creates a GridLayout and fills each row with an array of items given as arguments.
  43
  44     argument:: rows
  45
  46     Each argument is an Array of items to form a consecutive row. An item can be a strong::view::, another strong::layout::, or strong::nil:: for an empty cell.
  47
  48     discussion::
  49
  50     You can make an item span more than one cell by wrapping it into an Array, followed by pairs of (\rows, number) and/or (\columns, number). You can also assign an alignment to an item by following it with a pair of (\align, alignment). \rows, \columns, and \align can be abbreviated with \r, \c, and \a, respectively.
  51
  52     The simplified syntax for placing key-value pairs into an array comes handy (see link::Reference/Syntax-Shortcuts#creating_arrays_with_key-value_pairs::, and the example below).
  53
  54     Example:
  55 Code::
  56 (
  57 w=Window().layout_( GridLayout.rows(
  58     [Slider2D(), Slider2D(), [Slider(), rows:2]],
  59     [Slider2D(), Slider2D()],
  60     [[Slider().orientation_(\horizontal), columns:2]]
  61 )).front;
  62 )
  63 ::
  64
  65 METHOD:: columns
  66
  67     Creates a GridLayout and fills each column with an array of items given as arguments.
  68
  69     argument:: columns
  70
  71     Each argument is an Array of items to form a consecutive column. An item can be a strong::view::, another strong::layout::, or strong::nil:: for an empty cell.
  72
  73     discussion::
  74
  75     To make an item span several cells, or assign an alignment to it, the same instructions as for link::#*rows:: apply.
  76
  77
  78
  79 INSTANCEMETHODS::
  80
  81 METHOD:: add
  82
  83     Adds an item into the cell at specified row and column.
  84
  85     argument:: item
  86     The item can be a strong::view:: or another strong::layout::.
  87
  88     argument:: row
  89     The row index.
  90
  91     argument:: column
  92     The column index.
  93
  94     argument:: align
  95     A symbol denoting the alignment, or nil.
  96
  97 METHOD:: addSpanning
  98
  99     Adds an item into the grid so as to occupy several cells.
 100
 101     argument:: item
 102     The item can be a strong::view:: or another strong::layout::.
 103
 104     argument:: row
 105     The row index.
 106
 107     argument:: column
 108     The column index.
 109
 110     argument:: rowSpan
 111     The amount of cells to occupy in vertical direction.
 112
 113     argument:: columnSpan
 114     The amount of cells to occpy in horizontal direction.
 115
 116     argument:: align
 117     A symbol denoting the alignment, or nil.
 118
 119 METHOD:: hSpacing
 120
 121     The spacing between columns, in Integer amount of pixels.
 122
 123 METHOD:: vSpacing
 124
 125     The spacing between rows, in Integer amount of pixels.
 126
 127 METHOD:: setRowStretch
 128
 129     Sets the stretch factor of a row. By default rows have a stretch factor of 0. If a larger factor is assigned to a row, rows will get their space redistributed according to the relative proportions of their factors.
 130
 131     argument:: row
 132     The index of a row.
 133
 134     argument:: factor
 135     An Integer.
 136
 137 METHOD:: setColumnStretch
 138
 139     Sets the stretch factor of a column. By default columns have a stretch factor of 0. If a larger factor is assigned to a column, columns will get their space redistributed according to the relative proportions of their factors.
 140
 141     argument:: column
 142     The index of a column.
 143
 144     argument:: factor
 145     An Integer.
 146
 147 METHOD:: setAlignment
 148
 149     Sets the alignment of an item managed by the layout.
 150
 151     argument:: item
 152     A view or a layout managed by this layout, or a Point of which x denotes the column index and y the row index of an item.
 153
 154     argument:: align
 155     A symbol denoting the alignment.
 156
 157 METHOD:: minRowHeight
 158
 159     Gets the minimum height assigned to a row.
 160
 161     argument:: row
 162     The index of a row.
 163
 164 METHOD:: setMinRowHeight
 165
 166     Sets the minimum height of row.
 167
 168     argument:: row
 169     The index of a row.
 170
 171     argument:: height
 172     An Integer amount of pixels.
 173
 174 METHOD:: minColumnWidth
 175
 176     Gets the minimum width assigned to a column.
 177
 178     argument:: column
 179     The index of a column.
 180
 181 METHOD:: setMinColumnWidth
 182
 183     Sets the minimum width of a column.
 184
 185     argument:: column
 186     The index of a column.
 187
 188     argument:: width
 189     An Integer amount of pixels.