1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \class QSizePolicy

    44     \brief The QSizePolicy class is a layout attribute describing horizontal

    45     and vertical resizing policy.

    46 

    47     \ingroup geomanagement

    48 

    49     The size policy of a widget is an expression of its willingness to

    50     be resized in various ways, and affects how the widget is treated

    51     by the \l{Layout Management}{layout engine}. Each widget returns a

    52     QSizePolicy that describes the horizontal and vertical resizing

    53     policy it prefers when being laid out. You can change this for

    54     a specific widget by changing its QWidget::sizePolicy property.

    55 

    56     QSizePolicy contains two independent QSizePolicy::Policy values

    57     and two stretch factors; one describes the widgets's horizontal

    58     size policy, and the other describes its vertical size policy. It

    59     also contains a flag to indicate whether the height and width of

    60     its preferred size are related.

    61 

    62     The horizontal and vertical policies can be set in the

    63     constructor, and altered using the setHorizontalPolicy() and

    64     setVerticalPolicy() functions. The stretch factors can be set

    65     using the setHorizontalStretch() and setVerticalStretch()

    66     functions. The flag indicating whether the widget's

    67     \l{QWidget::sizeHint()}{sizeHint()} is width-dependent (such as a

    68     menu bar or a word-wrapping label) can be set using the

    69     setHeightForWidth() function.

    70 

    71     The current size policies and stretch factors be retrieved using

    72     the horizontalPolicy(), verticalPolicy(), horizontalStretch() and

    73     verticalStretch() functions. Alternatively, use the transpose()

    74     function to swap the horizontal and vertical policies and

    75     stretches. The hasHeightForWidth() function returns the current

    76     status of the flag indicating the size hint dependencies.

    77 

    78     Use the expandingDirections() function to determine whether the

    79     associated widget can make use of more space than its

    80     \l{QWidget::sizeHint()}{sizeHint()} function indicates, as well as

    81     find out in which directions it can expand.

    82 

    83     Finally, the QSizePolicy class provides operators comparing this

    84     size policy to a given policy, as well as a QVariant operator

    85     storing this QSizePolicy as a QVariant object.

    86 

    87     \sa QSize, QWidget::sizeHint(), QWidget::sizePolicy,

    88     QLayoutItem::sizeHint()

    89 */

    90 

    91 /*!

    92     \enum QSizePolicy::PolicyFlag

    93 

    94     These flags are combined together to form the various \l{Policy}

    95     values:

    96 

    97     \value GrowFlag  The widget can grow beyond its size hint if necessary.

    98     \value ExpandFlag  The widget should get as much space as possible.

    99     \value ShrinkFlag  The widget can shrink below its size hint if necessary.

   100     \value IgnoreFlag  The widget's size hint is ignored. The widget will get

   101         as much space as possible.

   102 

   103     \sa Policy

   104 */

   105 

   106 /*!

   107     \enum QSizePolicy::Policy

   108 

   109     This enum describes the various per-dimension sizing types used

   110     when constructing a QSizePolicy.

   111 

   112     \value Fixed  The QWidget::sizeHint() is the only acceptable

   113         alternative, so the widget can never grow or shrink (e.g. the

   114         vertical direction of a push button).

   115 

   116     \value Minimum  The sizeHint() is minimal, and sufficient. The

   117         widget can be expanded, but there is no advantage to it being

   118         larger (e.g. the horizontal direction of a push button).

   119         It cannot be smaller than the size provided by sizeHint().

   120 

   121     \value Maximum  The sizeHint() is a maximum. The widget can be

   122         shrunk any amount without detriment if other widgets need the

   123         space (e.g. a separator line).

   124         It cannot be larger than the size provided by sizeHint().

   125 

   126     \value Preferred  The sizeHint() is best, but the widget can be

   127         shrunk and still be useful. The widget can be expanded, but there

   128         is no advantage to it being larger than sizeHint() (the default

   129         QWidget policy).

   130 

   131     \value Expanding  The sizeHint() is a sensible size, but the

   132         widget can be shrunk and still be useful. The widget can make use

   133         of extra space, so it should get as much space as possible (e.g.

   134         the horizontal direction of a horizontal slider).

   135 

   136     \value MinimumExpanding  The sizeHint() is minimal, and sufficient.

   137         The widget can make use of extra space, so it should get as much

   138         space as possible (e.g. the horizontal direction of a horizontal

   139         slider).

   140 

   141     \value Ignored  The sizeHint() is ignored. The widget will get as

   142         much space as possible.

   143 

   144     \sa PolicyFlag, setHorizontalPolicy(), setVerticalPolicy()

   145 */

   146 

   147 /*!

   148     \fn QSizePolicy::QSizePolicy()

   149 

   150     Constructs a QSizePolicy object with \l Fixed as its horizontal

   151     and vertical policies.

   152 

   153     The policies can be altered using the setHorizontalPolicy() and

   154     setVerticalPolicy() functions. Use the setHeightForWidth()

   155     function if the preferred height of the widget is dependent on the

   156     width of the widget (for example, a QLabel with line wrapping).

   157 

   158     \sa setHorizontalStretch(), setVerticalStretch()

   159 */

   160 

   161 /*!

   162     \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical)

   163 

   164     Constructs a QSizePolicy object with the given \a horizontal and

   165     \a vertical policies, and DefaultType as the control type.

   166 

   167     Use setHeightForWidth() if the preferred height of the widget is

   168     dependent on the width of the widget (for example, a QLabel with

   169     line wrapping).

   170 

   171     \sa setHorizontalStretch(), setVerticalStretch()

   172 */

   173 

   174 /*!

   175     \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, ControlType type)

   176     \since 4.3

   177 

   178     Constructs a QSizePolicy object with the given \a horizontal and

   179     \a vertical policies, and the specified control \a type.

   180 

   181     Use setHeightForWidth() if the preferred height of the widget is

   182     dependent on the width of the widget (for example, a QLabel with

   183     line wrapping).

   184 

   185     \sa setHorizontalStretch(), setVerticalStretch(), controlType()

   186 */

   187 

   188 /*!

   189     \fn QSizePolicy::Policy QSizePolicy::horizontalPolicy() const

   190 

   191     Returns the horizontal component of the size policy.

   192 

   193     \sa setHorizontalPolicy(), verticalPolicy(), horizontalStretch()

   194 */

   195 

   196 /*!

   197     \fn QSizePolicy::Policy QSizePolicy::verticalPolicy() const

   198 

   199     Returns the vertical component of the size policy.

   200 

   201     \sa setVerticalPolicy(), horizontalPolicy(), verticalStretch()

   202 */

   203 

   204 /*!

   205     \fn void QSizePolicy::setHorizontalPolicy(Policy policy)

   206 

   207     Sets the horizontal component to the given \a policy.

   208 

   209     \sa horizontalPolicy(), setVerticalPolicy(), setHorizontalStretch()

   210 */

   211 

   212 /*!

   213     \fn void QSizePolicy::setVerticalPolicy(Policy policy)

   214 

   215     Sets the vertical component to the given \a policy.

   216 

   217     \sa verticalPolicy(), setHorizontalPolicy(), setVerticalStretch()

   218 */

   219 

   220 /*!

   221     \fn Qt::Orientations QSizePolicy::expandingDirections() const

   222 

   223     Returns whether a widget can make use of more space than the

   224     QWidget::sizeHint() function indicates.

   225 

   226     A value of Qt::Horizontal or Qt::Vertical means that the widget

   227     can grow horizontally or vertically (i.e., the horizontal or

   228     vertical policy is \l Expanding or \l MinimumExpanding), whereas

   229     Qt::Horizontal | Qt::Vertical means that it can grow in both

   230     dimensions.

   231 

   232     \sa horizontalPolicy(), verticalPolicy()

   233 */

   234 

   235 /*!

   236     \fn ControlType QSizePolicy::controlType() const

   237     \since 4.3

   238 

   239     Returns the control type associated with the widget for which

   240     this size policy applies.

   241 */

   242 

   243 /*!

   244     \fn void QSizePolicy::setControlType(ControlType type)

   245     \since 4.3

   246 

   247     Sets the control type associated with the widget for which this

   248     size policy applies to \a type.

   249 

   250     The control type specifies the type of the widget for which this

   251     size policy applies. It is used by some styles, notably

   252     QMacStyle, to insert proper spacing between widgets. For example,

   253     the Mac OS X Aqua guidelines specify that push buttons should be

   254     separated by 12 pixels, whereas vertically stacked radio buttons

   255     only require 6 pixels.

   256 

   257     \sa QStyle::layoutSpacing()

   258 */

   259 

   260 /*!

   261     \fn void QSizePolicy::setHeightForWidth(bool dependent)

   262 

   263     Sets the flag determining whether the widget's preferred height

   264     depends on its width, to \a dependent.

   265 

   266     \sa hasHeightForWidth()

   267 */

   268 

   269 /*!

   270     \fn bool QSizePolicy::hasHeightForWidth() const

   271 

   272     Returns true if the widget's preferred height depends on its

   273     width; otherwise returns false.

   274 

   275     \sa setHeightForWidth()

   276 */

   277 

   278 /*!

   279     \fn bool QSizePolicy::operator==(const QSizePolicy &other) const

   280 

   281     Returns true if this policy is equal to \a other; otherwise

   282     returns false.

   283 

   284     \sa operator!=()

   285 */

   286 

   287 /*!

   288     \fn bool QSizePolicy::operator!=(const QSizePolicy &other) const

   289 

   290     Returns true if this policy is different from \a other; otherwise

   291     returns false.

   292 

   293     \sa operator==()

   294 */

   295 

   296 /*!

   297     \fn int QSizePolicy::horizontalStretch() const

   298 

   299     Returns the horizontal stretch factor of the size policy.

   300 

   301     \sa setHorizontalStretch(), verticalStretch(), horizontalPolicy()

   302 */

   303 

   304 /*!

   305     \fn int QSizePolicy::verticalStretch() const

   306 

   307     Returns the vertical stretch factor of the size policy.

   308 

   309     \sa setVerticalStretch(), horizontalStretch(), verticalPolicy()

   310 */

   311 

   312 /*!

   313     \fn void QSizePolicy::setHorizontalStretch(uchar stretchFactor)

   314 

   315     Sets the horizontal stretch factor of the size policy to the given \a

   316     stretchFactor.

   317 

   318     \sa horizontalStretch(), setVerticalStretch(), setHorizontalPolicy()

   319 */

   320 

   321 /*!

   322     \fn void QSizePolicy::setVerticalStretch(uchar stretchFactor)

   323 

   324     Sets the vertical stretch factor of the size policy to the given

   325     \a stretchFactor.

   326 

   327     \sa verticalStretch(), setHorizontalStretch(), setVerticalPolicy()

   328 */

   329 

   330 /*!

   331     \fn void QSizePolicy::transpose()

   332 

   333     Swaps the horizontal and vertical policies and stretches.

   334 */

   335 

   336 /*!

   337     \enum QSizePolicy::ControlType

   338     \since 4.3

   339 

   340     This enum specifies the different types of widgets in terms of

   341     layout interaction:

   342 

   343     \value DefaultType  The default type, when none is specified.

   344     \value ButtonBox  A QDialogButtonBox instance.

   345     \value CheckBox  A QCheckBox instance.

   346     \value ComboBox  A QComboBox instance.

   347     \value Frame  A QFrame instance.

   348     \value GroupBox  A QGroupBox instance.

   349     \value Label  A QLabel instance.

   350     \value Line  A QFrame instance with QFrame::HLine or QFrame::VLine.

   351     \value LineEdit  A QLineEdit instance.

   352     \value PushButton  A QPushButton instance.

   353     \value RadioButton  A QRadioButton instance.

   354     \value Slider  A QAbstractSlider instance.

   355     \value SpinBox  A QAbstractSpinBox instance.

   356     \value TabWidget  A QTabWidget instance.

   357     \value ToolButton  A QToolButton instance.

   358 

   359     \sa setControlType(), controlType()

   360 */

   361 

   362 #ifdef QT3_SUPPORT

   363 /*!

   364     \typedef QSizePolicy::SizeType

   365     \compat

   366 

   367     Use the QSizePolicy::Policy enum instead.

   368 */

   369 

   370 /*!

   371     \enum QSizePolicy::ExpandData

   372     \compat

   373 

   374     Use the Qt::Orientations enum instead.

   375 

   376     \value NoDirection  Use 0 instead.

   377     \value Horizontally  Use Qt::Horizontal instead.

   378     \value Vertically  Use Qt::Vertical instead.

   379     \value BothDirections  Use Qt::Horizontal | Qt::Vertical instead.

   380 */

   381 

   382 /*!

   383     \fn bool QSizePolicy::mayShrinkHorizontally() const

   384 

   385     Use the horizontalPolicy() function combined with the

   386     QSizePolicy::PolicyFlag enum instead.

   387 

   388     \oldcode

   389         bool policy = mayShrinkHorizontally();

   390     \newcode

   391         bool policy = horizontalPolicy() & QSizePolicy::ShrinkFlag;

   392     \endcode

   393 */

   394 

   395 /*!

   396     \fn bool QSizePolicy::mayShrinkVertically() const

   397 

   398     Use the verticalPolicy() function combined with the

   399     QSizePolicy::PolicyFlag enum instead.

   400 

   401     \oldcode

   402         bool policy = mayShrinkVertically();

   403     \newcode

   404         bool policy = verticalPolicy() & QSizePolicy::ShrinkFlag;

   405     \endcode

   406 */

   407 

   408 /*!

   409     \fn bool QSizePolicy::mayGrowHorizontally() const

   410 

   411     Use the horizontalPolicy() function combined with the

   412     QSizePolicy::PolicyFlag enum instead.

   413 

   414     \oldcode

   415         bool policy = mayGrowHorizontally();

   416     \newcode

   417         bool policy = horizontalPolicy() & QSizePolicy::GrowFlag;

   418     \endcode

   419 */

   420 

   421 /*!

   422     \fn bool QSizePolicy::mayGrowVertically() const

   423 

   424     Use the verticalPolicy() function combined with the

   425     QSizePolicy::PolicyFlag enum instead.

   426 

   427     \oldcode

   428         bool policy = mayGrowVertically();

   429     \newcode

   430         bool policy = verticalPolicy() & QSizePolicy::GrowFlag;

   431     \endcode

   432 */

   433 

   434 /*!

   435     \fn Qt::QSizePolicy::Orientations QSizePolicy::expanding() const

   436 

   437     Use expandingDirections() instead.

   438 */

   439 

   440 /*!

   441     \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, bool dependent)

   442 

   443     Use the QSizePolicy() constructor and the setHeightForWidth()

   444     function instead.

   445 

   446     \oldcode

   447         QSizePolicy *policy = new QSizePolicy(horizontal, vertical, dependent);

   448     \newcode

   449         QSizePolicy *policy = new QSizePolicy(horizontal, vertical);

   450         policy->setHeightForWidth(dependent);

   451     \endcode

   452 */

   453 

   454 /*!

   455     \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, uchar horizontalStretch,

   456                                  uchar verticalStretch, bool dependent)

   457 

   458     Use the QSizePolicy() constructor and call the

   459     setHorizontalStretch(), setVerticalStretch(), and

   460     setHeightForWidth() functions instead.

   461 

   462     \oldcode

   463         QSizePolicy *policy = new QSizePolicy(horizontal, vertical,

   464                                                                  horizontalStretch, verticalStretch,

   465                                                                  dependent);

   466     \newcode

   467         QSizePolicy *policy = new QSizePolicy(horizontal, vertical);

   468         policy->setHorizontalStretch(horizontalStretch);

   469         policy->setVerticalStretch(verticalStretch);

   470         policy->setHeightForWidth(dependent);

   471     \endcode

   472 */

   473 

   474 /*!

   475     \fn QSizePolicy::Policy QSizePolicy::horData() const

   476 

   477     Use horizontalPolicy() instead.

   478 */

   479 

   480 /*!

   481     \fn QSizePolicy::Policy QSizePolicy::verData() const

   482 

   483     Use verticalPolicy() instead.

   484 */

   485 

   486 /*!

   487     \fn void QSizePolicy::setHorData(Policy policy)

   488 

   489     Use setHorizontalPolicy() instead.

   490 */

   491 

   492 /*!

   493     \fn void QSizePolicy::setVerData(Policy policy)

   494 

   495     Use setVerticalPolicy() instead.

   496 */

   497 

   498 /*!

   499     \fn uint QSizePolicy::horStretch() const

   500 

   501     Use horizontalStretch() instead.

   502 */

   503 

   504 /*!

   505     \fn uint QSizePolicy::verStretch() const

   506 

   507     Use verticalStretch() instead.

   508 */

   509 

   510 /*!

   511     \fn void QSizePolicy::setHorStretch(uchar stretch)

   512 

   513     Use setHorizontalStretch() instead.

   514 */

   515 

   516 /*!

   517     \fn void QSizePolicy::setVerStretch(uchar stretch)

   518 

   519     Use setVerticalStretch() instead.

   520 */

   521 #endif