src/widgets/kernel/qsizepolicy.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   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
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \class QSizePolicy
  30     \brief The QSizePolicy class is a layout attribute describing horizontal
  31     and vertical resizing policy.
  32
  33     \ingroup geomanagement
  34     \inmodule QtWidgets
  35
  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.
  42
  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.
  48
  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.
  57
  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.
  64
  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.
  69
  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.
  73
  74     \sa QSize, QWidget::sizeHint(), QWidget::sizePolicy,
  75     QLayoutItem::sizeHint()
  76 */
  77
  78 /*!
  79     \enum QSizePolicy::PolicyFlag
  80
  81     These flags are combined together to form the various \l{Policy}
  82     values:
  83
  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.
  89
  90     \sa Policy
  91 */
  92
  93 /*!
  94     \enum QSizePolicy::Policy
  95
  96     This enum describes the various per-dimension sizing types used
  97     when constructing a QSizePolicy.
  98
  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).
 102
 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().
 107
 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().
 112
 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
 116         QWidget policy).
 117
 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).
 122
 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
 126         slider).
 127
 128     \value Ignored  The sizeHint() is ignored. The widget will get as
 129         much space as possible.
 130
 131     \sa PolicyFlag, setHorizontalPolicy(), setVerticalPolicy()
 132 */
 133
 134 /*!
 135     \fn QSizePolicy::QSizePolicy()
 136
 137     Constructs a QSizePolicy object with \l Fixed as its horizontal
 138     and vertical policies.
 139
 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).
 144
 145     \sa setHorizontalStretch(), setVerticalStretch()
 146 */
 147
 148 /*!
 149     \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical)
 150
 151     Constructs a QSizePolicy object with the given \a horizontal and
 152     \a vertical policies, and DefaultType as the control type.
 153
 154     Use setHeightForWidth() if the preferred height of the widget is
 155     dependent on the width of the widget (for example, a QLabel with
 156     line wrapping).
 157
 158     \sa setHorizontalStretch(), setVerticalStretch()
 159 */
 160
 161 /*!
 162     \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, ControlType type)
 163     \since 4.3
 164
 165     Constructs a QSizePolicy object with the given \a horizontal and
 166     \a vertical policies, and the specified control \a type.
 167
 168     Use setHeightForWidth() if the preferred height of the widget is
 169     dependent on the width of the widget (for example, a QLabel with
 170     line wrapping).
 171
 172     \sa setHorizontalStretch(), setVerticalStretch(), controlType()
 173 */
 174
 175 /*!
 176     \fn QSizePolicy::Policy QSizePolicy::horizontalPolicy() const
 177
 178     Returns the horizontal component of the size policy.
 179
 180     \sa setHorizontalPolicy(), verticalPolicy(), horizontalStretch()
 181 */
 182
 183 /*!
 184     \fn QSizePolicy::Policy QSizePolicy::verticalPolicy() const
 185
 186     Returns the vertical component of the size policy.
 187
 188     \sa setVerticalPolicy(), horizontalPolicy(), verticalStretch()
 189 */
 190
 191 /*!
 192     \fn void QSizePolicy::setHorizontalPolicy(Policy policy)
 193
 194     Sets the horizontal component to the given \a policy.
 195
 196     \sa horizontalPolicy(), setVerticalPolicy(), setHorizontalStretch()
 197 */
 198
 199 /*!
 200     \fn void QSizePolicy::setVerticalPolicy(Policy policy)
 201
 202     Sets the vertical component to the given \a policy.
 203
 204     \sa verticalPolicy(), setHorizontalPolicy(), setVerticalStretch()
 205 */
 206
 207 /*!
 208     \fn Qt::Orientations QSizePolicy::expandingDirections() const
 209
 210     Returns whether a widget can make use of more space than the
 211     QWidget::sizeHint() function indicates.
 212
 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
 217     dimensions.
 218
 219     \sa horizontalPolicy(), verticalPolicy()
 220 */
 221
 222 /*!
 223     \fn ControlType QSizePolicy::controlType() const
 224     \since 4.3
 225
 226     Returns the control type associated with the widget for which
 227     this size policy applies.
 228 */
 229
 230 /*!
 231     \fn void QSizePolicy::setControlType(ControlType type)
 232     \since 4.3
 233
 234     Sets the control type associated with the widget for which this
 235     size policy applies to \a type.
 236
 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.
 243
 244     \sa QStyle::layoutSpacing()
 245 */
 246
 247 /*!
 248     \fn void QSizePolicy::setHeightForWidth(bool dependent)
 249
 250     Sets the flag determining whether the widget's preferred height
 251     depends on its width, to \a dependent.
 252
 253     \sa hasHeightForWidth(), setWidthForHeight()
 254 */
 255
 256 /*!
 257     \fn bool QSizePolicy::hasHeightForWidth() const
 258
 259     Returns true if the widget's preferred height depends on its
 260     width; otherwise returns false.
 261
 262     \sa setHeightForWidth()
 263 */
 264
 265 /*!
 266     \fn void QSizePolicy::setWidthForHeight(bool dependent)
 267
 268     Sets the flag determining whether the widget's width
 269     depends on its height, to \a dependent.
 270
 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.
 274
 275     \sa hasWidthForHeight(), setHeightForWidth()
 276 */
 277
 278 /*!
 279     \fn bool QSizePolicy::hasWidthForHeight() const
 280
 281     Returns true if the widget's width depends on its
 282     height; otherwise returns false.
 283
 284     \sa setWidthForHeight()
 285 */
 286
 287 /*!
 288     \fn bool QSizePolicy::operator==(const QSizePolicy &other) const
 289
 290     Returns true if this policy is equal to \a other; otherwise
 291     returns false.
 292
 293     \sa operator!=()
 294 */
 295
 296 /*!
 297     \fn bool QSizePolicy::operator!=(const QSizePolicy &other) const
 298
 299     Returns true if this policy is different from \a other; otherwise
 300     returns false.
 301
 302     \sa operator==()
 303 */
 304
 305 /*!
 306     \fn int QSizePolicy::horizontalStretch() const
 307
 308     Returns the horizontal stretch factor of the size policy.
 309
 310     \sa setHorizontalStretch(), verticalStretch(), horizontalPolicy()
 311 */
 312
 313 /*!
 314     \fn int QSizePolicy::verticalStretch() const
 315
 316     Returns the vertical stretch factor of the size policy.
 317
 318     \sa setVerticalStretch(), horizontalStretch(), verticalPolicy()
 319 */
 320
 321 /*!
 322     \fn void QSizePolicy::setHorizontalStretch(int stretchFactor)
 323
 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].
 326
 327     \sa horizontalStretch(), setVerticalStretch(), setHorizontalPolicy()
 328 */
 329
 330 /*!
 331     \fn void QSizePolicy::setVerticalStretch(int stretchFactor)
 332
 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].
 335
 336     \sa verticalStretch(), setHorizontalStretch(), setVerticalPolicy()
 337 */
 338
 339 /*!
 340     \fn void QSizePolicy::transpose()
 341
 342     Swaps the horizontal and vertical policies and stretches.
 343 */
 344
 345 /*!
 346     \enum QSizePolicy::ControlType
 347     \since 4.3
 348
 349     This enum specifies the different types of widgets in terms of
 350     layout interaction:
 351
 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.
 367
 368     \sa setControlType(), controlType()
 369 */
 370