source: trunk/doc/html/layout.html@ 190

Last change on this file since 190 was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 14.1 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/layout.doc:36 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>Layout Classes</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Layout Classes</h1>
33
34
35
36<p> The Qt layout system provides a simple and powerful way of specifying
37the layout of child widgets.
38<p> By specifying the logical layout once, you get the following benefits:
39<ul>
40<li> Positioning of child widgets.
41<li> Sensible default sizes for top-level widgets.
42<li> Sensible minimum sizes for top-level widgets.
43<li> Resize handling.
44<li> Automatic update when contents change:
45<ul>
46<li> Font size, text or other contents of subwidgets.
47<li> Hiding or showing a subwidget.
48<li> Removal of subwidget.
49</ul>
50</ul>
51<p> Qt's layout classes were designed for hand-written C++ code, so
52they're easy to understand and use.
53<p> The disadvantage of hand-written layout code is that it isn't very
54convenient when you're experimenting with the design of a form and you
55have to go through the compile, link and run cycle for each change.
56Our solution is <a href="designer-manual.html">Qt Designer</a>, a GUI
57visual design tool which makes it fast and easy to experiment with
58layouts and which generates the C++ layout code for you.
59<p> <h2> Layout Widgets
60</h2>
61<a name="1"></a><p> The easiest way to give your widgets a good layout is to use the
62layout widgets: <a href="qhbox.html">QHBox</a>, <a href="qvbox.html">QVBox</a> and <a href="qgrid.html">QGrid</a>. A layout widget
63automatically lays out its child widgets in the order they are
64constructed. To create more complex layouts, you can nest layout
65widgets inside each other. (Note that <a href="qwidget.html">QWidget</a> does not have a
66layout by default, you must add one if you want to lay out widgets
67inside a <a href="qwidget.html">QWidget</a>.)
68<p> <ul>
69<li> A <a href="qhbox.html">QHBox</a> lays out its child widgets in a horizontal row, left to right.
70<p> <center><img src="qhbox-m.png" alt="Horizontal box with five child widgets"></center>
71<p> <li> A <a href="qvbox.html">QVBox</a> lays out its child widgets in a vertical column, top to bottom.
72<p> <center><img src="qvbox-m.png" alt="Vertical box with five child widgets"></center>
73<p> <li> A <a href="qgrid.html">QGrid</a> lays out its child widgets in a two dimensional grid.
74You can specify how many columns the grid has, and it is populated left to
75right, beginning a new row when the previous row is full. The grid is
76fixed; the child widgets will not flow to other rows as the widget is
77resized.
78</ul>
79<p> <center><img src="qgrid-m.png" alt="Two-column grid with five child widgets"></center>
80<p> The grid shown above can be produced by the following code:
81<pre>
82 <a href="qgrid.html">QGrid</a> *mainGrid = new <a href="qgrid.html">QGrid</a>( 2 ); // a 2 x n grid
83 new <a href="qlabel.html">QLabel</a>( "One", mainGrid );
84 new <a href="qlabel.html">QLabel</a>( "Two", mainGrid );
85 new <a href="qlabel.html">QLabel</a>( "Three", mainGrid );
86 new <a href="qlabel.html">QLabel</a>( "Four", mainGrid );
87 new <a href="qlabel.html">QLabel</a>( "Five", mainGrid );
88</pre>
89
90<p> You can adjust the layout to some extent by calling
91<a href="qwidget.html#setMinimumSize">QWidget::setMinimumSize</a>() or <a href="qwidget.html#setFixedSize">QWidget::setFixedSize</a>() on the child widgets.
92<p> <h2> Adding Widgets to a Layout
93</h2>
94<a name="2"></a><p> When you add widgets to a layout the layout process works as follows:
95<ol type=1>
96<li> All the widgets will initially be allocated an amount of space in
97accordance with their <a href="qwidget.html#sizePolicy">QWidget::sizePolicy</a>().
98<li> If any of the widgets have stretch factors set, with a value
99greater than zero, then they are allocated space in proportion to
100their <a href="#stretch">stretch factor</a>.
101<li> If any of the widgets have stretch factors set to zero they will
102only get more space if no other widgets want the space. Of these,
103space is allocated to widgets with an <tt>Expanding</tt> size policy first.
104<li> Any widgets that are allocated less space than their minimum size
105(or minimum size hint if no minimum size is specified) are allocated
106this minimum size they require. (Widgets don't have to have a minimum
107size or minimum size hint in which case the strech factor is their
108determining factor.)
109<li> Any widgets that are allocated more space than their maximum size
110are allocated the maximum size space they require. (Widgets don't have
111to have a maximum size in which case the strech factor is their
112determining factor.)
113</ol>
114<p> <a name="stretch"></a>
115<h3> Stretch Factors
116<!-- index stretch factor --><a name="stretch-factor"></a>
117</h3>
118<a name="2-1"></a><p> Widgets are normally created without any stretch factor set. When they
119are laid out in a layout the widgets are given a share of space in
120accordance with their <a href="qwidget.html#sizePolicy">QWidget::sizePolicy</a>() or their minimum size hint
121whichever is the greater. Stretch factors are used to change how much
122space widgets are given in proportion to one another.
123<p> If we have three widgets laid out using a <a href="qhbox.html">QHBox</a> with no stretch
124factors set we will get a layout like this:
125<p> <center><img src="layout1.png" alt="3 widgets in a row"></center>
126<p> If we apply stretch factors to each widget, they will be laid out in
127proportion (but never less than their minimum size hint), e.g.
128<p> <center><img src="layout2.png" alt="3 stretch factored widgets in a row"></center>
129<p> <h2> <a href="qlayout.html">QLayout</a> subclassing
130</h2>
131<a name="3"></a><p> If you need more control over the layout, use a <a href="qlayout.html">QLayout</a> subclass. The layout classes included in Qt are <a href="qgridlayout.html">QGridLayout</a> and <a href="qboxlayout.html">QBoxLayout</a>. (<a href="qhboxlayout.html">QHBoxLayout</a> and <a href="qvboxlayout.html">QVBoxLayout</a> are trivial subclasses of <a href="qboxlayout.html">QBoxLayout</a>,
132that are simpler to use and make the code easier to read.)
133<p> When you use a layout, you must insert each child both into its parent
134widget (done in the constructor) and into its layout (typically done
135with a function called addWidget()). This way, you can give layout
136parameters for each widget, specifying properties like alignment,
137stretch, and placement.
138<p> The following code makes a grid like the one above, with a couple of
139improvements:
140<pre>
141 <a href="qwidget.html">QWidget</a> *main = new <a href="qwidget.html">QWidget</a>;
142
143 // make a 1x1 grid; it will auto-expand
144 <a href="qgridlayout.html">QGridLayout</a> *grid = new <a href="qgridlayout.html">QGridLayout</a>( main, 1, 1 );
145
146 // add the first four widgets with (row, column) addressing
147 grid-&gt;<a href="qgridlayout.html#addWidget">addWidget</a>( new <a href="qlabel.html">QLabel</a>( "One", main ), 0, 0 );
148 grid-&gt;<a href="qgridlayout.html#addWidget">addWidget</a>( new <a href="qlabel.html">QLabel</a>( "Two", main ), 0, 1 );
149 grid-&gt;<a href="qgridlayout.html#addWidget">addWidget</a>( new <a href="qlabel.html">QLabel</a>( "Three", main ), 1, 0 );
150 grid-&gt;<a href="qgridlayout.html#addWidget">addWidget</a>( new <a href="qlabel.html">QLabel</a>( "Four", main ), 1, 1 );
151
152 // add the last widget on row 2, spanning from column 0 to
153 // column 1, and center aligned
154 grid-&gt;<a href="qgridlayout.html#addMultiCellWidget">addMultiCellWidget</a>( new <a href="qlabel.html">QLabel</a>( "Five", main ), 2, 2, 0, 1,
155 Qt::AlignCenter );
156
157 // let the ratio between the widths of columns 0 and 1 be 2:3
158 grid-&gt;<a href="qgridlayout.html#setColStretch">setColStretch</a>( 0, 2 );
159 grid-&gt;<a href="qgridlayout.html#setColStretch">setColStretch</a>( 1, 3 );
160</pre>
161
162<p> You can insert layouts inside a layout by giving the parent layout as
163a parameter in the constructor.
164<pre>
165 <a href="qwidget.html">QWidget</a> *main = new <a href="qwidget.html">QWidget</a>;
166 <a href="qlineedit.html">QLineEdit</a> *field = new <a href="qlineedit.html">QLineEdit</a>( main );
167 <a href="qpushbutton.html">QPushButton</a> *ok = new <a href="qpushbutton.html">QPushButton</a>( "OK", main );
168 <a href="qpushbutton.html">QPushButton</a> *cancel = new <a href="qpushbutton.html">QPushButton</a>( "Cancel", main );
169 <a href="qlabel.html">QLabel</a> *label = new <a href="qlabel.html">QLabel</a>( "Write once, compile everywhere.", main );
170
171 // a layout on a widget
172 <a href="qvboxlayout.html">QVBoxLayout</a> *vbox = new <a href="qvboxlayout.html">QVBoxLayout</a>( main );
173 vbox-&gt;<a href="qboxlayout.html#addWidget">addWidget</a>( label );
174 vbox-&gt;<a href="qboxlayout.html#addWidget">addWidget</a>( field );
175
176 // a layout inside a layout
177 <a href="qhboxlayout.html">QHBoxLayout</a> *buttons = new <a href="qhboxlayout.html">QHBoxLayout</a>( vbox );
178 buttons-&gt;<a href="qboxlayout.html#addWidget">addWidget</a>( ok );
179 buttons-&gt;<a href="qboxlayout.html#addWidget">addWidget</a>( cancel );
180</pre>
181
182If you are not satisfied with the default placement, you can create
183the layout without a parent and then insert it with addLayout().
184The inner layout then becomes a child of the layout it is inserted
185into.
186<p> <h2> Custom Layouts
187</h2>
188<a name="4"></a><p> If the built-in layout classes are not sufficient, you can define your
189own. You must make a subclass of <a href="qlayout.html">QLayout</a> that handles resizing and
190size calculations, as well as a subclass of <a href="qglayoutiterator.html">QGLayoutIterator</a> to
191iterate over your layout class.
192<p> See the <a href="customlayout.html">Custom Layout</a> page for an
193in-depth description.
194<p> <h2> Custom Widgets In Layouts
195</h2>
196<a name="5"></a><p> When you make your own widget class, you should also communicate its
197layout properties. If the widget has a <a href="qlayout.html">QLayout</a>, this is already taken
198care of. If the widget does not have any child widgets, or uses manual
199layout, you should reimplement the following <a href="qwidget.html">QWidget</a> member functions:
200<p> <ul>
201<li> <a href="qwidget.html#sizeHint">QWidget::sizeHint</a>() returns the preferred size of the widget.
202<li> <a href="qwidget.html#minimumSizeHint">QWidget::minimumSizeHint</a>() returns the smallest size the widget can have.
203<li> <a href="qwidget.html#sizePolicy">QWidget::sizePolicy</a>() returns a <a href="qsizepolicy.html">QSizePolicy</a>; a value describing
204the space requirements of the widget.
205</ul>
206<p> Call <a href="qwidget.html#updateGeometry">QWidget::updateGeometry</a>() whenever the size hint, minimum size
207hint or size policy changes. This will cause a layout recalculation.
208Multiple calls to updateGeometry() will only cause one recalculation.
209<p> If the preferred height of your widget depends on its actual width
210(e.g. a label with automatic word-breaking), set the <a href="qsizepolicy.html#hasHeightForWidth">hasHeightForWidth</a>() flag in
211<a href="qwidget.html#sizePolicy">sizePolicy</a>(), and reimplement <a href="qwidget.html#heightForWidth">QWidget::heightForWidth</a>().
212<p> Even if you implement heightForWidth(), it is still necessary to
213provide a good sizeHint(). The sizeHint() provides the preferred width
214of the widget, and it is used by <a href="qlayout.html">QLayout</a> subclasses that do not
215support heightForWidth() (both <a href="qgridlayout.html">QGridLayout</a> and <a href="qboxlayout.html">QBoxLayout</a> support it).
216<p> For further guidance when implementing these functions, see their
217implementations in existing Qt classes that have similar layout
218requirements to your new widget.
219<p> <h2> Manual Layout
220</h2>
221<a name="6"></a><p> If you are making a one-of-a-kind special layout, you can also make a
222custom widget as described above. Reimplement <a href="qwidget.html#resizeEvent">QWidget::resizeEvent</a>()
223to calculate the required distribution of sizes and call <a href="qwidget.html#setGeometry">setGeometry</a>() on each child.
224<p> The widget will get an event with <a href="qevent.html#type">type</a>
225<tt>LayoutHint</tt> when the layout needs to be recalculated. Reimplement
226<a href="qwidget.html#event">QWidget::event</a>() to be notified of <tt>LayoutHint</tt> events.
227<p> <h2> Layout Issues
228</h2>
229<a name="7"></a><p> The use of rich text in a label widget can introduce some problems to
230the layout of its parent widget. Problems occur due to the way rich text
231is handled by Qt's layout managers when the label is word wrapped.
232In certain cases the parent layout is put into QLayout::FreeResize mode,
233meaning that it will not adapt the layout of its contents to fit inside
234small sized windows, or even prevent the user from making the
235window too small to be usable. This can be overcome by subclassing
236the problematic widgets, and implementing suitable sizeHint() and
237minimumSizeHint() functions.
238<p>
239<!-- eof -->
240<p><address><hr><div align=center>
241<table width=100% cellspacing=0 border=0><tr>
242<td>Copyright &copy; 2007
243<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
244<td align=right><div align=right>Qt 3.3.8</div>
245</table></div></address></body>
246</html>
Note: See TracBrowser for help on using the repository browser.