QSplitter Class

Member Function Documentation

[explicit] QSplitter::QSplitter(QWidget *parent = nullptr)

Constructs a horizontal splitter with the parent argument passed on to the QFrame constructor.

See also setOrientation().

[explicit] QSplitter::QSplitter(Qt::Orientation orientation, QWidget *parent = nullptr)

Constructs a splitter with the given orientation and parent.

See also setOrientation().

[virtual] QSplitter::~QSplitter()

Destroys the splitter. All children are deleted.

void QSplitter::addWidget(QWidget *widget)

Adds the given widget to the splitter's layout after all the other items.

If widget is already in the splitter, it will be moved to the new position.

See also insertWidget(), widget(), and indexOf().

[override virtual protected] void QSplitter::changeEvent(QEvent *ev)

Reimplements: QFrame::changeEvent(QEvent *ev).

[override virtual protected] void QSplitter::childEvent(QChildEvent *c)

Reimplements: QObject::childEvent(QChildEvent *event).

Tells the splitter that the child widget described by c has been inserted or removed.

This method is also used to handle the situation where a widget is created with the splitter as a parent but not explicitly added with insertWidget() or addWidget(). This is for compatibility and not the recommended way of putting widgets into a splitter in new code. Please use insertWidget() or addWidget() in new code.

See also addWidget() and insertWidget().

[protected] int QSplitter::closestLegalPosition(int pos, int index)

Returns the closest legal position to pos of the widget at index.

For right-to-left languages such as Arabic and Hebrew, the layout of horizontal splitters is reversed. Positions are then measured from the right edge of the widget.

See also getRange().

int QSplitter::count() const

Returns the number of widgets contained in the splitter's layout.

See also widget() and handle().

[virtual protected] QSplitterHandle *QSplitter::createHandle()

Returns a new splitter handle as a child widget of this splitter. This function can be reimplemented in subclasses to provide support for custom handles.

See also handle() and indexOf().

[override virtual protected] bool QSplitter::event(QEvent *e)

Reimplements: QFrame::event(QEvent *e).

void QSplitter::getRange(int index, int *min, int *max) const

Returns the valid range of the splitter at index in *min and *max if min and max are not 0.

QSplitterHandle *QSplitter::handle(int index) const

Returns the handle to the left of (or above) the item in the splitter's layout at the given index, or nullptr if there is no such item. The handle at index 0 is always hidden.

For right-to-left languages such as Arabic and Hebrew, the layout of horizontal splitters is reversed. The handle will be to the right of the widget at index.

See also count(), widget(), indexOf(), createHandle(), and setHandleWidth().

int QSplitter::indexOf(QWidget *widget) const

Returns the index in the splitter's layout of the specified widget, or -1 if widget is not found. This also works for handles.

Handles are numbered from 0. There are as many handles as there are child widgets, but the handle at position 0 is always hidden.

See also count() and widget().

void QSplitter::insertWidget(int index, QWidget *widget)

Inserts the widget specified into the splitter's layout at the given index.

If widget is already in the splitter, it will be moved to the new position.

If index is an invalid index, then the widget will be inserted at the end.

See also addWidget(), indexOf(), and widget().

bool QSplitter::isCollapsible(int index) const

Returns true if the widget at index is collapsible, otherwise returns false.

[override virtual] QSize QSplitter::minimumSizeHint() const

Reimplements an access function for property: QWidget::minimumSizeHint.

[protected] void QSplitter::moveSplitter(int pos, int index)

Moves the left or top edge of the splitter handle at index as close as possible to position pos, which is the distance from the left or top edge of the widget.

For right-to-left languages such as Arabic and Hebrew, the layout of horizontal splitters is reversed. pos is then the distance from the right edge of the widget.

See also splitterMoved(), closestLegalPosition(), and getRange().

void QSplitter::refresh()

Updates the splitter's state. You should not need to call this function.

QWidget *QSplitter::replaceWidget(int index, QWidget *widget)

Replaces the widget in the splitter's layout at the given index by widget.

Returns the widget that has just been replaced if index is valid and widget is not already a child of the splitter. Otherwise, it returns null and no replacement or addition is made.

The geometry of the newly inserted widget will be the same as the widget it replaces. Its visible and collapsed states are also inherited.

See also insertWidget() and indexOf().

[override virtual protected] void QSplitter::resizeEvent(QResizeEvent *)

Reimplements: QWidget::resizeEvent(QResizeEvent *event).

bool QSplitter::restoreState(const QByteArray &state)

Restores the splitter's layout to the state specified. Returns true if the state is restored; otherwise returns false.

Typically this is used in conjunction with QSettings to restore the size from a past session. Here is an example:

Restore the splitter's state:

    QSettings settings;
    splitter->restoreState(settings.value("splitterSizes").toByteArray());

A failure to restore the splitter's layout may result from either invalid or out-of-date data in the supplied byte array.

See also saveState().

QByteArray QSplitter::saveState() const

Saves the state of the splitter's layout.

Typically this is used in conjunction with QSettings to remember the size for a future session. A version number is stored as part of the data. Here is an example:

    QSettings settings;
    settings.setValue("splitterSizes", splitter->saveState());

See also restoreState().

void QSplitter::setCollapsible(int index, bool collapse)

Sets whether the child widget at index is collapsible to collapse.

By default, children are collapsible, meaning that the user can resize them down to size 0, even if they have a non-zero minimumSize() or minimumSizeHint(). This behavior can be changed on a per-widget basis by calling this function, or globally for all the widgets in the splitter by setting the childrenCollapsible property.

See also isCollapsible() and childrenCollapsible.

[protected] void QSplitter::setRubberBand(int pos)

Displays a rubber band at position pos. If pos is negative, the rubber band is removed.

void QSplitter::setSizes(const QList<int> &list)

Sets the child widgets' respective sizes to the values given in the list.

If the splitter is horizontal, the values set the width of each widget in pixels, from left to right. If the splitter is vertical, the height of each widget is set, from top to bottom.

Extra values in the list are ignored. If list contains too few values, the result is undefined, but the program will still be well-behaved.

The overall size of the splitter widget is not affected. Instead, any additional/missing space is distributed amongst the widgets according to the relative weight of the sizes.

If you specify a size of 0, the widget will be invisible. The size policies of the widgets are preserved. That is, a value smaller than the minimal size hint of the respective widget will be replaced by the value of the hint.

See also sizes().

void QSplitter::setStretchFactor(int index, int stretch)

Updates the size policy of the widget at position index to have a stretch factor of stretch.

stretch is not the effective stretch factor; the effective stretch factor is calculated by taking the initial size of the widget and multiplying it with stretch.

This function is provided for convenience. It is equivalent to

QWidget *widget = splitter->widget(index);
QSizePolicy policy = widget->sizePolicy();
policy.setHorizontalStretch(stretch);
policy.setVerticalStretch(stretch);
widget->setSizePolicy(policy);

See also setSizes() and widget().

[override virtual] QSize QSplitter::sizeHint() const

Reimplements: QFrame::sizeHint() const.

QList<int> QSplitter::sizes() const

Returns a list of the size parameters of all the widgets in this splitter.

If the splitter's orientation is horizontal, the list contains the widgets width in pixels, from left to right; if the orientation is vertical, the list contains the widgets' heights in pixels, from top to bottom.

Giving the values to another splitter's setSizes() function will produce a splitter with the same layout as this one.

Note that invisible widgets have a size of 0.

See also setSizes().

[signal] void QSplitter::splitterMoved(int pos, int index)

This signal is emitted when the splitter handle at a particular index has been moved to position pos.

For right-to-left languages such as Arabic and Hebrew, the layout of horizontal splitters is reversed. pos is then the distance from the right edge of the widget.

See also moveSplitter().

QWidget *QSplitter::widget(int index) const

Returns the widget at the given index in the splitter's layout, or nullptr if there is no such widget.

See also count(), handle(), indexOf(), and insertWidget().