1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** GNU Free Documentation License
10 ** Alternatively, this file may be used under the terms of the GNU Free
11 ** Documentation License version 1.3 as published by the Free Software
12 ** Foundation and appearing in the file included in the packaging of
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
30 \brief The QSizePolicy class is a layout attribute describing horizontal
31 and vertical resizing policy.
33 \ingroup geomanagement
36 The size policy of a widget is an expression of its willingness to
37 be resized in various ways, and affects how the widget is treated
38 by the \l{Layout Management}{layout engine}. Each widget returns a
39 QSizePolicy that describes the horizontal and vertical resizing
40 policy it prefers when being laid out. You can change this for
41 a specific widget by changing its QWidget::sizePolicy property.
43 QSizePolicy contains two independent QSizePolicy::Policy values
44 and two stretch factors; one describes the widgets's horizontal
45 size policy, and the other describes its vertical size policy. It
46 also contains a flag to indicate whether the height and width of
47 its preferred size are related.
49 The horizontal and vertical policies can be set in the
50 constructor, and altered using the setHorizontalPolicy() and
51 setVerticalPolicy() functions. The stretch factors can be set
52 using the setHorizontalStretch() and setVerticalStretch()
53 functions. The flag indicating whether the widget's
54 \l{QWidget::sizeHint()}{sizeHint()} is width-dependent (such as a
55 menu bar or a word-wrapping label) can be set using the
56 setHeightForWidth() function.
58 The current size policies and stretch factors be retrieved using
59 the horizontalPolicy(), verticalPolicy(), horizontalStretch() and
60 verticalStretch() functions. Alternatively, use the transpose()
61 function to swap the horizontal and vertical policies and
62 stretches. The hasHeightForWidth() function returns the current
63 status of the flag indicating the size hint dependencies.
65 Use the expandingDirections() function to determine whether the
66 associated widget can make use of more space than its
67 \l{QWidget::sizeHint()}{sizeHint()} function indicates, as well as
68 find out in which directions it can expand.
70 Finally, the QSizePolicy class provides operators comparing this
71 size policy to a given policy, as well as a QVariant operator
72 storing this QSizePolicy as a QVariant object.
74 \sa QSize, QWidget::sizeHint(), QWidget::sizePolicy,
75 QLayoutItem::sizeHint()
79 \enum QSizePolicy::PolicyFlag
81 These flags are combined together to form the various \l{Policy}
84 \value GrowFlag The widget can grow beyond its size hint if necessary.
85 \value ExpandFlag The widget should get as much space as possible.
86 \value ShrinkFlag The widget can shrink below its size hint if necessary.
87 \value IgnoreFlag The widget's size hint is ignored. The widget will get
88 as much space as possible.
94 \enum QSizePolicy::Policy
96 This enum describes the various per-dimension sizing types used
97 when constructing a QSizePolicy.
99 \value Fixed The QWidget::sizeHint() is the only acceptable
100 alternative, so the widget can never grow or shrink (e.g. the
101 vertical direction of a push button).
103 \value Minimum The sizeHint() is minimal, and sufficient. The
104 widget can be expanded, but there is no advantage to it being
105 larger (e.g. the horizontal direction of a push button).
106 It cannot be smaller than the size provided by sizeHint().
108 \value Maximum The sizeHint() is a maximum. The widget can be
109 shrunk any amount without detriment if other widgets need the
110 space (e.g. a separator line).
111 It cannot be larger than the size provided by sizeHint().
113 \value Preferred The sizeHint() is best, but the widget can be
114 shrunk and still be useful. The widget can be expanded, but there
115 is no advantage to it being larger than sizeHint() (the default
118 \value Expanding The sizeHint() is a sensible size, but the
119 widget can be shrunk and still be useful. The widget can make use
120 of extra space, so it should get as much space as possible (e.g.
121 the horizontal direction of a horizontal slider).
123 \value MinimumExpanding The sizeHint() is minimal, and sufficient.
124 The widget can make use of extra space, so it should get as much
125 space as possible (e.g. the horizontal direction of a horizontal
128 \value Ignored The sizeHint() is ignored. The widget will get as
129 much space as possible.
131 \sa PolicyFlag, setHorizontalPolicy(), setVerticalPolicy()
135 \fn QSizePolicy::QSizePolicy()
137 Constructs a QSizePolicy object with \l Fixed as its horizontal
138 and vertical policies.
140 The policies can be altered using the setHorizontalPolicy() and
141 setVerticalPolicy() functions. Use the setHeightForWidth()
142 function if the preferred height of the widget is dependent on the
143 width of the widget (for example, a QLabel with line wrapping).
145 \sa setHorizontalStretch(), setVerticalStretch()
149 \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical)
151 Constructs a QSizePolicy object with the given \a horizontal and
152 \a vertical policies, and DefaultType as the control type.
154 Use setHeightForWidth() if the preferred height of the widget is
155 dependent on the width of the widget (for example, a QLabel with
158 \sa setHorizontalStretch(), setVerticalStretch()
162 \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, ControlType type)
165 Constructs a QSizePolicy object with the given \a horizontal and
166 \a vertical policies, and the specified control \a type.
168 Use setHeightForWidth() if the preferred height of the widget is
169 dependent on the width of the widget (for example, a QLabel with
172 \sa setHorizontalStretch(), setVerticalStretch(), controlType()
176 \fn QSizePolicy::Policy QSizePolicy::horizontalPolicy() const
178 Returns the horizontal component of the size policy.
180 \sa setHorizontalPolicy(), verticalPolicy(), horizontalStretch()
184 \fn QSizePolicy::Policy QSizePolicy::verticalPolicy() const
186 Returns the vertical component of the size policy.
188 \sa setVerticalPolicy(), horizontalPolicy(), verticalStretch()
192 \fn void QSizePolicy::setHorizontalPolicy(Policy policy)
194 Sets the horizontal component to the given \a policy.
196 \sa horizontalPolicy(), setVerticalPolicy(), setHorizontalStretch()
200 \fn void QSizePolicy::setVerticalPolicy(Policy policy)
202 Sets the vertical component to the given \a policy.
204 \sa verticalPolicy(), setHorizontalPolicy(), setVerticalStretch()
208 \fn Qt::Orientations QSizePolicy::expandingDirections() const
210 Returns whether a widget can make use of more space than the
211 QWidget::sizeHint() function indicates.
213 A value of Qt::Horizontal or Qt::Vertical means that the widget
214 can grow horizontally or vertically (i.e., the horizontal or
215 vertical policy is \l Expanding or \l MinimumExpanding), whereas
216 Qt::Horizontal | Qt::Vertical means that it can grow in both
219 \sa horizontalPolicy(), verticalPolicy()
223 \fn ControlType QSizePolicy::controlType() const
226 Returns the control type associated with the widget for which
227 this size policy applies.
231 \fn void QSizePolicy::setControlType(ControlType type)
234 Sets the control type associated with the widget for which this
235 size policy applies to \a type.
237 The control type specifies the type of the widget for which this
238 size policy applies. It is used by some styles, notably
239 QMacStyle, to insert proper spacing between widgets. For example,
240 the Mac OS X Aqua guidelines specify that push buttons should be
241 separated by 12 pixels, whereas vertically stacked radio buttons
242 only require 6 pixels.
244 \sa QStyle::layoutSpacing()
248 \fn void QSizePolicy::setHeightForWidth(bool dependent)
250 Sets the flag determining whether the widget's preferred height
251 depends on its width, to \a dependent.
253 \sa hasHeightForWidth(), setWidthForHeight()
257 \fn bool QSizePolicy::hasHeightForWidth() const
259 Returns true if the widget's preferred height depends on its
260 width; otherwise returns false.
262 \sa setHeightForWidth()
266 \fn void QSizePolicy::setWidthForHeight(bool dependent)
268 Sets the flag determining whether the widget's width
269 depends on its height, to \a dependent.
271 This is only supported for QGraphicsLayout's subclasses.
272 It is not possible to have a layout with both height-for-width
273 and width-for-height constraints at the same time.
275 \sa hasWidthForHeight(), setHeightForWidth()
279 \fn bool QSizePolicy::hasWidthForHeight() const
281 Returns true if the widget's width depends on its
282 height; otherwise returns false.
284 \sa setWidthForHeight()
288 \fn bool QSizePolicy::operator==(const QSizePolicy &other) const
290 Returns true if this policy is equal to \a other; otherwise
297 \fn bool QSizePolicy::operator!=(const QSizePolicy &other) const
299 Returns true if this policy is different from \a other; otherwise
306 \fn int QSizePolicy::horizontalStretch() const
308 Returns the horizontal stretch factor of the size policy.
310 \sa setHorizontalStretch(), verticalStretch(), horizontalPolicy()
314 \fn int QSizePolicy::verticalStretch() const
316 Returns the vertical stretch factor of the size policy.
318 \sa setVerticalStretch(), horizontalStretch(), verticalPolicy()
322 \fn void QSizePolicy::setHorizontalStretch(int stretchFactor)
324 Sets the horizontal stretch factor of the size policy to the given \a
325 stretchFactor. \a stretchFactor must be in the range [0,255].
327 \sa horizontalStretch(), setVerticalStretch(), setHorizontalPolicy()
331 \fn void QSizePolicy::setVerticalStretch(int stretchFactor)
333 Sets the vertical stretch factor of the size policy to the given
334 \a stretchFactor. \a stretchFactor must be in the range [0,255].
336 \sa verticalStretch(), setHorizontalStretch(), setVerticalPolicy()
340 \fn void QSizePolicy::transpose()
342 Swaps the horizontal and vertical policies and stretches.
346 \enum QSizePolicy::ControlType
349 This enum specifies the different types of widgets in terms of
352 \value DefaultType The default type, when none is specified.
353 \value ButtonBox A QDialogButtonBox instance.
354 \value CheckBox A QCheckBox instance.
355 \value ComboBox A QComboBox instance.
356 \value Frame A QFrame instance.
357 \value GroupBox A QGroupBox instance.
358 \value Label A QLabel instance.
359 \value Line A QFrame instance with QFrame::HLine or QFrame::VLine.
360 \value LineEdit A QLineEdit instance.
361 \value PushButton A QPushButton instance.
362 \value RadioButton A QRadioButton instance.
363 \value Slider A QAbstractSlider instance.
364 \value SpinBox A QAbstractSpinBox instance.
365 \value TabWidget A QTabWidget instance.
366 \value ToolButton A QToolButton instance.
368 \sa setControlType(), controlType()