PySide6.QtWidgets.QSplitter

class QSplitter

The QSplitter class implements a splitter widget. More…

Inheritance diagram of PySide6.QtWidgets.QSplitter

Synopsis

Properties

Methods

Virtual methods

Signals

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

A splitter lets the user control the size of child widgets by dragging the boundary between them. Any number of widgets may be controlled by a single splitter. The typical use of a QSplitter is to create several widgets and add them using insertWidget() or addWidget() .

The following example will show a QListView , QTreeView , and QTextEdit side by side, with two splitter handles:

splitter = QSplitter(parent)
listview = QListView()
treeview = QTreeView()
textedit = QTextEdit()
splitter.addWidget(listview)
splitter.addWidget(treeview)
splitter.addWidget(textedit)

If a widget is already inside a QSplitter when insertWidget() or addWidget() is called, it will move to the new position. This can be used to reorder widgets in the splitter later. You can use indexOf() , widget() , and count() to get access to the widgets inside the splitter.

A default QSplitter lays out its children horizontally (side by side); you can use setOrientation (Qt::Vertical) to lay its children out vertically.

By default, all widgets can be as large or as small as the user wishes, between the minimumSizeHint() (or minimumSize() ) and maximumSize() of the widgets.

QSplitter resizes its children dynamically by default. If you would rather have QSplitter resize the children only at the end of a resize operation, call setOpaqueResize (false).

The initial distribution of size between the widgets is determined by multiplying the initial size with the stretch factor. You can also use setSizes() to set the sizes of all the widgets. The function sizes() returns the sizes set by the user. Alternatively, you can save and restore the sizes of the widgets from a QByteArray using saveState() and restoreState() respectively.

When you hide() a child, its space will be distributed among the other children. It will be reinstated when you show() it again.

Note

Adding a QLayout to a QSplitter is not supported (either through setLayout() or making the QSplitter a parent of the QLayout ); use addWidget() instead (see example above).

See also

QSplitterHandle QHBoxLayout QVBoxLayout QTabWidget

Note

Properties can be used directly when from __feature__ import true_property is used or via accessor functions otherwise.

property childrenCollapsibleᅟ: bool

This property holds whether child widgets can be resized down to size 0 by the user.

By default, children are collapsible. It is possible to enable and disable the collapsing of individual children using setCollapsible() .

See also

setCollapsible()

Access functions:
property handleWidthᅟ: int

This property holds the width of the splitter handles.

By default, this property contains a value that depends on the user’s platform and style preferences.

If you set handleWidth to 1 or 0, the actual grab area will grow to overlap a few pixels of its respective widgets.

Access functions:
property opaqueResizeᅟ: bool

Returns true if widgets are resized dynamically (opaquely) while interactively moving the splitter. Otherwise returns false.

The default resize behavior is style dependent (determined by the SH_Splitter_OpaqueResize style hint). However, you can override it by calling setOpaqueResize()

See also

StyleHint

Access functions:
property orientationᅟ: Qt.Orientation

This property holds the orientation of the splitter.

By default, the orientation is horizontal (i.e., the widgets are laid out side by side). The possible orientations are Qt::Horizontal and Qt::Vertical.

See also

orientation()

Access functions:
__init__([parent=None])
Parameters:

parent – QWidget

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

See also

setOrientation()

__init__(orientation[, parent=None])
Parameters:

Constructs a splitter with the given orientation and parent.

See also

setOrientation()

addWidget(widget)
Parameters:

widget – QWidget

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.

Note

The splitter takes ownership of the widget.

See also

insertWidget() widget() indexOf()

childrenCollapsible()
Return type:

bool

See also

setChildrenCollapsible()

Getter of property childrenCollapsibleᅟ .

closestLegalPosition(pos, index)
Parameters:

  • pos – int

  • index – int

Return type:

int

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()

count()
Return type:

int

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

See also

widget() handle()

createHandle()
Return type:

QSplitterHandle

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() indexOf()

getRange(index)
Parameters:

index – int

Return type:

PyObject

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

handle(index)
Parameters:

index – int

Return type:

QSplitterHandle

Returns the handle to the left of (or above) the item in the splitter’s layout at the given index, or None 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.

handleWidth()
Return type:

int

See also

setHandleWidth()

Getter of property handleWidthᅟ .

indexOf(w)
Parameters:

w – QWidget

Return type:

int

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() widget()

insertWidget(index, widget)
Parameters:

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.

Note

The splitter takes ownership of the widget.

See also

addWidget() indexOf() widget()

isCollapsible(index)
Parameters:

index – int

Return type:

bool

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

moveSplitter(pos, index)
Parameters:

  • pos – int

  • index – int

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.

opaqueResize()
Return type:

bool

See also

setOpaqueResize()

Getter of property opaqueResizeᅟ .

orientation()
Return type:

Orientation

See also

setOrientation()

Getter of property orientationᅟ .

refresh()

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

replaceWidget(index, widget)
Parameters:
Return type:

QWidget

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.

Note

The splitter takes ownership of widget and sets the parent of the replaced widget to null.

Note

Because widget gets reparented into the splitter, its geometry may not be set right away, but only after widget will receive the appropriate events.

See also

insertWidget() indexOf()

restoreState(state)
Parameters:

state – QByteArray

Return type:

bool

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

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:

settings = QSettings()
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()

saveState()
Return type:

QByteArray

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

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:

settings = QSettings()
settings.setValue("splitterSizes", splitter.saveState())

See also

restoreState()

setChildrenCollapsible(arg__1)
Parameters:

arg__1 – bool

See also

childrenCollapsible()

Setter of property childrenCollapsibleᅟ .

setCollapsible(index, collapse)
Parameters:

  • index – int

  • collapse – bool

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.

setHandleWidth(arg__1)
Parameters:

arg__1 – int

See also

handleWidth()

Setter of property handleWidthᅟ .

setOpaqueResize([opaque=true])
Parameters:

opaque – bool

See also

opaqueResize()

Setter of property opaqueResizeᅟ .

setOrientation(arg__1)
Parameters:

arg__1 – Orientation

See also

orientation()

Setter of property orientationᅟ .

setRubberBand(position)
Parameters:

position – int

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

setSizes(list)
Parameters:

list – .list of int

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()

setStretchFactor(index, stretch)
Parameters:

  • index – int

  • stretch – int

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

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

widget = splitter.widget(index)
policy = widget.sizePolicy()
policy.setHorizontalStretch(stretch)
policy.setVerticalStretch(stretch)
widget.setSizePolicy(policy)

See also

setSizes() widget()

sizes()
Return type:

.list of int

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()

splitterMoved(pos, index)
Parameters:

  • pos – int

  • index – int

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()

widget(index)
Parameters:

index – int

Return type:

QWidget

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