summaryrefslogtreecommitdiffstats
path: root/doc/src/qsizepolicy.qdoc
blob: c91c9e02f52bd0ce45d5f9e14d3322b626ef4eba (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights.  These rights are described in the Nokia Qt LGPL
** Exception version 1.1, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \class QSizePolicy
    \brief The QSizePolicy class is a layout attribute describing horizontal
    and vertical resizing policy.

    \ingroup appearance
    \ingroup geomanagement

    The size policy of a widget is an expression of its willingness to
    be resized in various ways, and affects how the widget is treated
    by the \l{Layout Management}{layout engine}. Each widget returns a
    QSizePolicy that describes the horizontal and vertical resizing
    policy it prefers when being laid out. You can change this for
    a specific widget by changing its QWidget::sizePolicy property.

    QSizePolicy contains two independent QSizePolicy::Policy values
    and two stretch factors; one describes the widgets's horizontal
    size policy, and the other describes its vertical size policy. It
    also contains a flag to indicate whether the height and width of
    its preferred size are related.

    The horizontal and vertical policies can be set in the
    constructor, and altered using the setHorizontalPolicy() and
    setVerticalPolicy() functions. The stretch factors can be set
    using the setHorizontalStretch() and setVerticalStretch()
    functions. The flag indicating whether the widget's
    \l{QWidget::sizeHint()}{sizeHint()} is width-dependent (such as a
    menu bar or a word-wrapping label) can be set using the
    setHeightForWidth() function.

    The current size policies and stretch factors be retrieved using
    the horizontalPolicy(), verticalPolicy(), horizontalStretch() and
    verticalStretch() functions. Alternatively, use the transpose()
    function to swap the horizontal and vertical policies and
    stretches. The hasHeightForWidth() function returns the current
    status of the flag indicating the size hint dependencies.

    Use the expandingDirections() function to determine whether the
    associated widget can make use of more space than its
    \l{QWidget::sizeHint()}{sizeHint()} function indicates, as well as
    find out in which directions it can expand.

    Finally, the QSizePolicy class provides operators comparing this
    size policy to a given policy, as well as a QVariant operator
    storing this QSizePolicy as a QVariant object.

    \sa QSize, QWidget::sizeHint(), QWidget::sizePolicy,
    QLayoutItem::sizeHint()
*/

/*!
    \enum QSizePolicy::PolicyFlag

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

    \value GrowFlag  The widget can grow beyond its size hint if necessary.
    \value ExpandFlag  The widget should get as much space as possible.
    \value ShrinkFlag  The widget can shrink below its size hint if necessary.
    \value IgnoreFlag  The widget's size hint is ignored. The widget will get
        as much space as possible.

    \sa Policy
*/

/*!
    \enum QSizePolicy::Policy

    This enum describes the various per-dimension sizing types used
    when constructing a QSizePolicy.

    \value Fixed  The QWidget::sizeHint() is the only acceptable
        alternative, so the widget can never grow or shrink (e.g. the
        vertical direction of a push button).

    \value Minimum  The sizeHint() is minimal, and sufficient. The
        widget can be expanded, but there is no advantage to it being
        larger (e.g. the horizontal direction of a push button).
        It cannot be smaller than the size provided by sizeHint().

    \value Maximum  The sizeHint() is a maximum. The widget can be
        shrunk any amount without detriment if other widgets need the
        space (e.g. a separator line).
        It cannot be larger than the size provided by sizeHint().

    \value Preferred  The sizeHint() is best, but the widget can be
        shrunk and still be useful. The widget can be expanded, but there
        is no advantage to it being larger than sizeHint() (the default
        QWidget policy).

    \value Expanding  The sizeHint() is a sensible size, but the
        widget can be shrunk and still be useful. The widget can make use
        of extra space, so it should get as much space as possible (e.g.
        the horizontal direction of a horizontal slider).

    \value MinimumExpanding  The sizeHint() is minimal, and sufficient.
        The widget can make use of extra space, so it should get as much
        space as possible (e.g. the horizontal direction of a horizontal
        slider).

    \value Ignored  The sizeHint() is ignored. The widget will get as
        much space as possible.

    \sa PolicyFlag, setHorizontalPolicy(), setVerticalPolicy()
*/

/*!
    \fn QSizePolicy::QSizePolicy()

    Constructs a QSizePolicy object with \l Fixed as its horizontal
    and vertical policies.

    The policies can be altered using the setHorizontalPolicy() and
    setVerticalPolicy() functions. Use the setHeightForWidth()
    function if the preferred height of the widget is dependent on the
    width of the widget (for example, a QLabel with line wrapping).

    \sa setHorizontalStretch(), setVerticalStretch()
*/

/*!
    \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical)

    Constructs a QSizePolicy object with the given \a horizontal and
    \a vertical policies, and DefaultType as the control type.

    Use setHeightForWidth() if the preferred height of the widget is
    dependent on the width of the widget (for example, a QLabel with
    line wrapping).

    \sa setHorizontalStretch(), setVerticalStretch()
*/

/*!
    \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, ControlType type)
    \since 4.3

    Constructs a QSizePolicy object with the given \a horizontal and
    \a vertical policies, and the specified control \a type.

    Use setHeightForWidth() if the preferred height of the widget is
    dependent on the width of the widget (for example, a QLabel with
    line wrapping).

    \sa setHorizontalStretch(), setVerticalStretch(), controlType()
*/

/*!
    \fn QSizePolicy::Policy QSizePolicy::horizontalPolicy() const

    Returns the horizontal component of the size policy.

    \sa setHorizontalPolicy(), verticalPolicy(), horizontalStretch()
*/

/*!
    \fn QSizePolicy::Policy QSizePolicy::verticalPolicy() const

    Returns the vertical component of the size policy.

    \sa setVerticalPolicy(), horizontalPolicy(), verticalStretch()
*/

/*!
    \fn void QSizePolicy::setHorizontalPolicy(Policy policy)

    Sets the horizontal component to the given \a policy.

    \sa horizontalPolicy(), setVerticalPolicy(), setHorizontalStretch()
*/

/*!
    \fn void QSizePolicy::setVerticalPolicy(Policy policy)

    Sets the vertical component to the given \a policy.

    \sa verticalPolicy(), setHorizontalPolicy(), setVerticalStretch()
*/

/*!
    \fn Qt::Orientations QSizePolicy::expandingDirections() const

    Returns whether a widget can make use of more space than the
    QWidget::sizeHint() function indicates.

    A value of Qt::Horizontal or Qt::Vertical means that the widget
    can grow horizontally or vertically (i.e., the horizontal or
    vertical policy is \l Expanding or \l MinimumExpanding), whereas
    Qt::Horizontal | Qt::Vertical means that it can grow in both
    dimensions.

    \sa horizontalPolicy(), verticalPolicy()
*/

/*!
    \fn ControlType QSizePolicy::controlType() const
    \since 4.3

    Returns the control type associated with the widget for which
    this size policy applies.
*/

/*!
    \fn void QSizePolicy::setControlType(ControlType type)
    \since 4.3

    Sets the control type associated with the widget for which this
    size policy applies to \a type.

    The control type specifies the type of the widget for which this
    size policy applies. It is used by some styles, notably
    QMacStyle, to insert proper spacing between widgets. For example,
    the Mac OS X Aqua guidelines specify that push buttons should be
    separated by 12 pixels, whereas vertically stacked radio buttons
    only require 6 pixels.

    \sa QStyle::layoutSpacing()
*/

/*!
    \fn void QSizePolicy::setHeightForWidth(bool dependent)

    Sets the flag determining whether the widget's preferred height
    depends on its width, to \a dependent.

    \sa hasHeightForWidth()
*/

/*!
    \fn bool QSizePolicy::hasHeightForWidth() const

    Returns true if the widget's preferred height depends on its
    width; otherwise returns false.

    \sa setHeightForWidth()
*/

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

    Returns true if this policy is equal to \a other; otherwise
    returns false.

    \sa operator!=()
*/

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

    Returns true if this policy is different from \a other; otherwise
    returns false.

    \sa operator==()
*/

/*!
    \fn int QSizePolicy::horizontalStretch() const

    Returns the horizontal stretch factor of the size policy.

    \sa setHorizontalStretch(), verticalStretch(), horizontalPolicy()
*/

/*!
    \fn int QSizePolicy::verticalStretch() const

    Returns the vertical stretch factor of the size policy.

    \sa setVerticalStretch(), horizontalStretch(), verticalPolicy()
*/

/*!
    \fn void QSizePolicy::setHorizontalStretch(uchar stretchFactor)

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

    \sa horizontalStretch(), setVerticalStretch(), setHorizontalPolicy()
*/

/*!
    \fn void QSizePolicy::setVerticalStretch(uchar stretchFactor)

    Sets the vertical stretch factor of the size policy to the given
    \a stretchFactor.

    \sa verticalStretch(), setHorizontalStretch(), setVerticalPolicy()
*/

/*!
    \fn void QSizePolicy::transpose()

    Swaps the horizontal and vertical policies and stretches.
*/

/*!
    \enum QSizePolicy::ControlType
    \since 4.3

    This enum specifies the different types of widgets in terms of
    layout interaction:

    \value DefaultType  The default type, when none is specified.
    \value ButtonBox  A QDialogButtonBox instance.
    \value CheckBox  A QCheckBox instance.
    \value ComboBox  A QComboBox instance.
    \value Frame  A QFrame instance.
    \value GroupBox  A QGroupBox instance.
    \value Label  A QLabel instance.
    \value Line  A QFrame instance with QFrame::HLine or QFrame::VLine.
    \value LineEdit  A QLineEdit instance.
    \value PushButton  A QPushButton instance.
    \value RadioButton  A QRadioButton instance.
    \value Slider  A QAbstractSlider instance.
    \value SpinBox  A QAbstractSpinBox instance.
    \value TabWidget  A QTabWidget instance.
    \value ToolButton  A QToolButton instance.

    \sa setControlType(), controlType()
*/

#ifdef QT3_SUPPORT
/*!
    \typedef QSizePolicy::SizeType
    \compat

    Use the QSizePolicy::Policy enum instead.
*/

/*!
    \enum QSizePolicy::ExpandData
    \compat

    Use the Qt::Orientations enum instead.

    \value NoDirection  Use 0 instead.
    \value Horizontally  Use Qt::Horizontal instead.
    \value Vertically  Use Qt::Vertical instead.
    \value BothDirections  Use Qt::Horizontal | Qt::Vertical instead.
*/

/*!
    \fn bool QSizePolicy::mayShrinkHorizontally() const

    Use the horizontalPolicy() function combined with the
    QSizePolicy::PolicyFlag enum instead.

    \oldcode
        bool policy = mayShrinkHorizontally();
    \newcode
        bool policy = horizontalPolicy() & QSizePolicy::ShrinkFlag;
    \endcode
*/

/*!
    \fn bool QSizePolicy::mayShrinkVertically() const

    Use the verticalPolicy() function combined with the
    QSizePolicy::PolicyFlag enum instead.

    \oldcode
        bool policy = mayShrinkVertically();
    \newcode
        bool policy = verticalPolicy() & QSizePolicy::ShrinkFlag;
    \endcode
*/

/*!
    \fn bool QSizePolicy::mayGrowHorizontally() const

    Use the horizontalPolicy() function combined with the
    QSizePolicy::PolicyFlag enum instead.

    \oldcode
        bool policy = mayGrowHorizontally();
    \newcode
        bool policy = horizontalPolicy() & QSizePolicy::GrowFlag;
    \endcode
*/

/*!
    \fn bool QSizePolicy::mayGrowVertically() const

    Use the verticalPolicy() function combined with the
    QSizePolicy::PolicyFlag enum instead.

    \oldcode
        bool policy = mayGrowVertically();
    \newcode
        bool policy = verticalPolicy() & QSizePolicy::GrowFlag;
    \endcode
*/

/*!
    \fn Qt::QSizePolicy::Orientations QSizePolicy::expanding() const

    Use expandingDirections() instead.
*/

/*!
    \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, bool dependent)

    Use the QSizePolicy() constructor and the setHeightForWidth()
    function instead.

    \oldcode
        QSizePolicy *policy = new QSizePolicy(horizontal, vertical, dependent);
    \newcode
        QSizePolicy *policy = new QSizePolicy(horizontal, vertical);
        policy->setHeightForWidth(dependent);
    \endcode
*/

/*!
    \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, uchar horizontalStretch,
                                 uchar verticalStretch, bool dependent)

    Use the QSizePolicy() constructor and call the
    setHorizontalStretch(), setVerticalStretch(), and
    setHeightForWidth() functions instead.

    \oldcode
        QSizePolicy *policy = new QSizePolicy(horizontal, vertical,
                                                                 horizontalStretch, verticalStretch,
                                                                 dependent);
    \newcode
        QSizePolicy *policy = new QSizePolicy(horizontal, vertical);
        policy->setHorizontalStretch(horizontalStretch);
        policy->setVerticalStretch(verticalStretch);
        policy->setHeightForWidth(dependent);
    \endcode
*/

/*!
    \fn QSizePolicy::Policy QSizePolicy::horData() const

    Use horizontalPolicy() instead.
*/

/*!
    \fn QSizePolicy::Policy QSizePolicy::verData() const

    Use verticalPolicy() instead.
*/

/*!
    \fn void QSizePolicy::setHorData(Policy policy)

    Use setHorizontalPolicy() instead.
*/

/*!
    \fn void QSizePolicy::setVerData(Policy policy)

    Use setVerticalPolicy() instead.
*/

/*!
    \fn uint QSizePolicy::horStretch() const

    Use horizontalStretch() instead.
*/

/*!
    \fn uint QSizePolicy::verStretch() const

    Use verticalStretch() instead.
*/

/*!
    \fn void QSizePolicy::setHorStretch(uchar stretch)

    Use setHorizontalStretch() instead.
*/

/*!
    \fn void QSizePolicy::setVerStretch(uchar stretch)

    Use setVerticalStretch() instead.
*/
#endif