You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
247 lines
14 KiB
247 lines
14 KiB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/layout.doc:36 -->
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>Layout Classes</title>
|
|
<style type="text/css"><!--
|
|
fn { margin-left: 1cm; text-indent: -1cm; }
|
|
a:link { color: #004faf; text-decoration: none }
|
|
a:visited { color: #672967; text-decoration: none }
|
|
body { background: #ffffff; color: black; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
|
|
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
|
<tr bgcolor="#E5E5E5">
|
|
<td valign=center>
|
|
<a href="index.html">
|
|
<font color="#004faf">Home</font></a>
|
|
| <a href="classes.html">
|
|
<font color="#004faf">All Classes</font></a>
|
|
| <a href="mainclasses.html">
|
|
<font color="#004faf">Main Classes</font></a>
|
|
| <a href="annotated.html">
|
|
<font color="#004faf">Annotated</font></a>
|
|
| <a href="groups.html">
|
|
<font color="#004faf">Grouped Classes</font></a>
|
|
| <a href="functions.html">
|
|
<font color="#004faf">Functions</font></a>
|
|
</td>
|
|
<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>
|
|
|
|
|
|
|
|
<p> The TQt layout system provides a simple and powerful way of specifying
|
|
the layout of child widgets.
|
|
<p> By specifying the logical layout once, you get the following benefits:
|
|
<ul>
|
|
<li> Positioning of child widgets.
|
|
<li> Sensible default sizes for top-level widgets.
|
|
<li> Sensible minimum sizes for top-level widgets.
|
|
<li> Resize handling.
|
|
<li> Automatic update when contents change:
|
|
<ul>
|
|
<li> Font size, text or other contents of subwidgets.
|
|
<li> Hiding or showing a subwidget.
|
|
<li> Removal of subwidget.
|
|
</ul>
|
|
</ul>
|
|
<p> TQt's layout classes were designed for hand-written C++ code, so
|
|
they're easy to understand and use.
|
|
<p> The disadvantage of hand-written layout code is that it isn't very
|
|
convenient when you're experimenting with the design of a form and you
|
|
have to go through the compile, link and run cycle for each change.
|
|
Our solution is <a href="designer-manual.html">TQt Designer</a>, a GUI
|
|
visual design tool which makes it fast and easy to experiment with
|
|
layouts and which generates the C++ layout code for you.
|
|
<p> <h2> Layout Widgets
|
|
</h2>
|
|
<a name="1"></a><p> The easiest way to give your widgets a good layout is to use the
|
|
layout widgets: <a href="qhbox.html">TQHBox</a>, <a href="qvbox.html">TQVBox</a> and <a href="qgrid.html">TQGrid</a>. A layout widget
|
|
automatically lays out its child widgets in the order they are
|
|
constructed. To create more complex layouts, you can nest layout
|
|
widgets inside each other. (Note that <a href="qwidget.html">TQWidget</a> does not have a
|
|
layout by default, you must add one if you want to lay out widgets
|
|
inside a <a href="qwidget.html">TQWidget</a>.)
|
|
<p> <ul>
|
|
<li> A <a href="qhbox.html">TQHBox</a> lays out its child widgets in a horizontal row, left to right.
|
|
<p> <center><img src="qhbox-m.png" alt="Horizontal box with five child widgets"></center>
|
|
<p> <li> A <a href="qvbox.html">TQVBox</a> lays out its child widgets in a vertical column, top to bottom.
|
|
<p> <center><img src="qvbox-m.png" alt="Vertical box with five child widgets"></center>
|
|
<p> <li> A <a href="qgrid.html">TQGrid</a> lays out its child widgets in a two dimensional grid.
|
|
You can specify how many columns the grid has, and it is populated left to
|
|
right, beginning a new row when the previous row is full. The grid is
|
|
fixed; the child widgets will not flow to other rows as the widget is
|
|
resized.
|
|
</ul>
|
|
<p> <center><img src="qgrid-m.png" alt="Two-column grid with five child widgets"></center>
|
|
<p> The grid shown above can be produced by the following code:
|
|
<pre>
|
|
<a href="qgrid.html">TQGrid</a> *mainGrid = new <a href="qgrid.html">TQGrid</a>( 2 ); // a 2 x n grid
|
|
new <a href="qlabel.html">TQLabel</a>( "One", mainGrid );
|
|
new <a href="qlabel.html">TQLabel</a>( "Two", mainGrid );
|
|
new <a href="qlabel.html">TQLabel</a>( "Three", mainGrid );
|
|
new <a href="qlabel.html">TQLabel</a>( "Four", mainGrid );
|
|
new <a href="qlabel.html">TQLabel</a>( "Five", mainGrid );
|
|
</pre>
|
|
|
|
<p> You can adjust the layout to some extent by calling
|
|
<a href="qwidget.html#setMinimumSize">TQWidget::setMinimumSize</a>() or <a href="qwidget.html#setFixedSize">TQWidget::setFixedSize</a>() on the child widgets.
|
|
<p> <h2> Adding Widgets to a Layout
|
|
</h2>
|
|
<a name="2"></a><p> When you add widgets to a layout the layout process works as follows:
|
|
<ol type=1>
|
|
<li> All the widgets will initially be allocated an amount of space in
|
|
accordance with their <a href="qwidget.html#sizePolicy">TQWidget::sizePolicy</a>().
|
|
<li> If any of the widgets have stretch factors set, with a value
|
|
greater than zero, then they are allocated space in proportion to
|
|
their <a href="#stretch">stretch factor</a>.
|
|
<li> If any of the widgets have stretch factors set to zero they will
|
|
only get more space if no other widgets want the space. Of these,
|
|
space is allocated to widgets with an <tt>Expanding</tt> size policy first.
|
|
<li> Any widgets that are allocated less space than their minimum size
|
|
(or minimum size hint if no minimum size is specified) are allocated
|
|
this minimum size they require. (Widgets don't have to have a minimum
|
|
size or minimum size hint in which case the strech factor is their
|
|
determining factor.)
|
|
<li> Any widgets that are allocated more space than their maximum size
|
|
are allocated the maximum size space they require. (Widgets don't have
|
|
to have a maximum size in which case the strech factor is their
|
|
determining factor.)
|
|
</ol>
|
|
<p> <a name="stretch"></a>
|
|
<h3> Stretch Factors
|
|
<!-- index stretch factor --><a name="stretch-factor"></a>
|
|
</h3>
|
|
<a name="2-1"></a><p> Widgets are normally created without any stretch factor set. When they
|
|
are laid out in a layout the widgets are given a share of space in
|
|
accordance with their <a href="qwidget.html#sizePolicy">TQWidget::sizePolicy</a>() or their minimum size hint
|
|
whichever is the greater. Stretch factors are used to change how much
|
|
space widgets are given in proportion to one another.
|
|
<p> If we have three widgets laid out using a <a href="qhbox.html">TQHBox</a> with no stretch
|
|
factors set we will get a layout like this:
|
|
<p> <center><img src="layout1.png" alt="3 widgets in a row"></center>
|
|
<p> If we apply stretch factors to each widget, they will be laid out in
|
|
proportion (but never less than their minimum size hint), e.g.
|
|
<p> <center><img src="layout2.png" alt="3 stretch factored widgets in a row"></center>
|
|
<p> <h2> <a href="qlayout.html">TQLayout</a> subclassing
|
|
</h2>
|
|
<a name="3"></a><p> If you need more control over the layout, use a <a href="qlayout.html">TQLayout</a> subclass. The layout classes included in TQt are <a href="qgridlayout.html">TQGridLayout</a> and <a href="qboxlayout.html">TQBoxLayout</a>. (<a href="qhboxlayout.html">TQHBoxLayout</a> and <a href="qvboxlayout.html">TQVBoxLayout</a> are trivial subclasses of <a href="qboxlayout.html">TQBoxLayout</a>,
|
|
that are simpler to use and make the code easier to read.)
|
|
<p> When you use a layout, you must insert each child both into its parent
|
|
widget (done in the constructor) and into its layout (typically done
|
|
with a function called addWidget()). This way, you can give layout
|
|
parameters for each widget, specifying properties like alignment,
|
|
stretch, and placement.
|
|
<p> The following code makes a grid like the one above, with a couple of
|
|
improvements:
|
|
<pre>
|
|
<a href="qwidget.html">TQWidget</a> *main = new <a href="qwidget.html">TQWidget</a>;
|
|
|
|
// make a 1x1 grid; it will auto-expand
|
|
<a href="qgridlayout.html">TQGridLayout</a> *grid = new <a href="qgridlayout.html">TQGridLayout</a>( main, 1, 1 );
|
|
|
|
// add the first four widgets with (row, column) addressing
|
|
grid-><a href="qgridlayout.html#addWidget">addWidget</a>( new <a href="qlabel.html">TQLabel</a>( "One", main ), 0, 0 );
|
|
grid-><a href="qgridlayout.html#addWidget">addWidget</a>( new <a href="qlabel.html">TQLabel</a>( "Two", main ), 0, 1 );
|
|
grid-><a href="qgridlayout.html#addWidget">addWidget</a>( new <a href="qlabel.html">TQLabel</a>( "Three", main ), 1, 0 );
|
|
grid-><a href="qgridlayout.html#addWidget">addWidget</a>( new <a href="qlabel.html">TQLabel</a>( "Four", main ), 1, 1 );
|
|
|
|
// add the last widget on row 2, spanning from column 0 to
|
|
// column 1, and center aligned
|
|
grid-><a href="qgridlayout.html#addMultiCellWidget">addMultiCellWidget</a>( new <a href="qlabel.html">TQLabel</a>( "Five", main ), 2, 2, 0, 1,
|
|
TQt::AlignCenter );
|
|
|
|
// let the ratio between the widths of columns 0 and 1 be 2:3
|
|
grid-><a href="qgridlayout.html#setColStretch">setColStretch</a>( 0, 2 );
|
|
grid-><a href="qgridlayout.html#setColStretch">setColStretch</a>( 1, 3 );
|
|
</pre>
|
|
|
|
<p> You can insert layouts inside a layout by giving the parent layout as
|
|
a parameter in the constructor.
|
|
<pre>
|
|
<a href="qwidget.html">TQWidget</a> *main = new <a href="qwidget.html">TQWidget</a>;
|
|
<a href="qlineedit.html">TQLineEdit</a> *field = new <a href="qlineedit.html">TQLineEdit</a>( main );
|
|
<a href="qpushbutton.html">TQPushButton</a> *ok = new <a href="qpushbutton.html">TQPushButton</a>( "OK", main );
|
|
<a href="qpushbutton.html">TQPushButton</a> *cancel = new <a href="qpushbutton.html">TQPushButton</a>( "Cancel", main );
|
|
<a href="qlabel.html">TQLabel</a> *label = new <a href="qlabel.html">TQLabel</a>( "Write once, compile everywhere.", main );
|
|
|
|
// a layout on a widget
|
|
<a href="qvboxlayout.html">TQVBoxLayout</a> *vbox = new <a href="qvboxlayout.html">TQVBoxLayout</a>( main );
|
|
vbox-><a href="qboxlayout.html#addWidget">addWidget</a>( label );
|
|
vbox-><a href="qboxlayout.html#addWidget">addWidget</a>( field );
|
|
|
|
// a layout inside a layout
|
|
<a href="qhboxlayout.html">TQHBoxLayout</a> *buttons = new <a href="qhboxlayout.html">TQHBoxLayout</a>( vbox );
|
|
buttons-><a href="qboxlayout.html#addWidget">addWidget</a>( ok );
|
|
buttons-><a href="qboxlayout.html#addWidget">addWidget</a>( cancel );
|
|
</pre>
|
|
|
|
If you are not satisfied with the default placement, you can create
|
|
the layout without a parent and then insert it with addLayout().
|
|
The inner layout then becomes a child of the layout it is inserted
|
|
into.
|
|
<p> <h2> Custom Layouts
|
|
</h2>
|
|
<a name="4"></a><p> If the built-in layout classes are not sufficient, you can define your
|
|
own. You must make a subclass of <a href="qlayout.html">TQLayout</a> that handles resizing and
|
|
size calculations, as well as a subclass of <a href="qglayoutiterator.html">TQGLayoutIterator</a> to
|
|
iterate over your layout class.
|
|
<p> See the <a href="customlayout.html">Custom Layout</a> page for an
|
|
in-depth description.
|
|
<p> <h2> Custom Widgets In Layouts
|
|
</h2>
|
|
<a name="5"></a><p> When you make your own widget class, you should also communicate its
|
|
layout properties. If the widget has a <a href="qlayout.html">TQLayout</a>, this is already taken
|
|
care of. If the widget does not have any child widgets, or uses manual
|
|
layout, you should reimplement the following <a href="qwidget.html">TQWidget</a> member functions:
|
|
<p> <ul>
|
|
<li> <a href="qwidget.html#sizeHint">TQWidget::sizeHint</a>() returns the preferred size of the widget.
|
|
<li> <a href="qwidget.html#minimumSizeHint">TQWidget::minimumSizeHint</a>() returns the smallest size the widget can have.
|
|
<li> <a href="qwidget.html#sizePolicy">TQWidget::sizePolicy</a>() returns a <a href="qsizepolicy.html">TQSizePolicy</a>; a value describing
|
|
the space requirements of the widget.
|
|
</ul>
|
|
<p> Call <a href="qwidget.html#updateGeometry">TQWidget::updateGeometry</a>() whenever the size hint, minimum size
|
|
hint or size policy changes. This will cause a layout recalculation.
|
|
Multiple calls to updateGeometry() will only cause one recalculation.
|
|
<p> If the preferred height of your widget depends on its actual width
|
|
(e.g. a label with automatic word-breaking), set the <a href="qsizepolicy.html#hasHeightForWidth">hasHeightForWidth</a>() flag in
|
|
<a href="qwidget.html#sizePolicy">sizePolicy</a>(), and reimplement <a href="qwidget.html#heightForWidth">TQWidget::heightForWidth</a>().
|
|
<p> Even if you implement heightForWidth(), it is still necessary to
|
|
provide a good sizeHint(). The sizeHint() provides the preferred width
|
|
of the widget, and it is used by <a href="qlayout.html">TQLayout</a> subclasses that do not
|
|
support heightForWidth() (both <a href="qgridlayout.html">TQGridLayout</a> and <a href="qboxlayout.html">TQBoxLayout</a> support it).
|
|
<p> For further guidance when implementing these functions, see their
|
|
implementations in existing TQt classes that have similar layout
|
|
requirements to your new widget.
|
|
<p> <h2> Manual Layout
|
|
</h2>
|
|
<a name="6"></a><p> If you are making a one-of-a-kind special layout, you can also make a
|
|
custom widget as described above. Reimplement <a href="qwidget.html#resizeEvent">TQWidget::resizeEvent</a>()
|
|
to calculate the required distribution of sizes and call <a href="qwidget.html#setGeometry">setGeometry</a>() on each child.
|
|
<p> The widget will get an event with <a href="qevent.html#type">type</a>
|
|
<tt>LayoutHint</tt> when the layout needs to be recalculated. Reimplement
|
|
<a href="qwidget.html#event">TQWidget::event</a>() to be notified of <tt>LayoutHint</tt> events.
|
|
<p> <h2> Layout Issues
|
|
</h2>
|
|
<a name="7"></a><p> The use of rich text in a label widget can introduce some problems to
|
|
the layout of its parent widget. Problems occur due to the way rich text
|
|
is handled by TQt's layout managers when the label is word wrapped.
|
|
In certain cases the parent layout is put into TQLayout::FreeResize mode,
|
|
meaning that it will not adapt the layout of its contents to fit inside
|
|
small sized windows, or even prevent the user from making the
|
|
window too small to be usable. This can be overcome by subclassing
|
|
the problematic widgets, and implementing suitable sizeHint() and
|
|
minimumSizeHint() functions.
|
|
<p>
|
|
<!-- eof -->
|
|
<p><address><hr><div align=center>
|
|
<table width=100% cellspacing=0 border=0><tr>
|
|
<td>Copyright © 2007
|
|
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
|
<td align=right><div align=right>TQt 3.3.8</div>
|
|
</table></div></address></body>
|
|
</html>
|