diff options
Diffstat (limited to 'doc/html/layout.html')
| -rw-r--r-- | doc/html/layout.html | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/doc/html/layout.html b/doc/html/layout.html new file mode 100644 index 000000000..12de2a5cd --- /dev/null +++ b/doc/html/layout.html @@ -0,0 +1,246 @@ +<!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 retquire. (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 retquire. (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 retquirements 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 +retquirements 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 retquired 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> |