28-容器和容器控件-分割容器QSplitter

分割容器QSplitter

分割器控件QSplitter 中可以加人多个控件,在两个相邻的控件之间自动用一个分隔条把这两个控件分开,可以拖拽分割条改变它的位置。

分割器可以分为水平分割和竖直分割两种,分割器中还可以加入其他分割器,这样形成多级分割。只能往分割器中加控件,不能直接加布局。分割器的外观如图所示。

在往窗体或布局中添加分割器控件时,应以控件形式而不能以布局形式加入,因此应该将分割器当成控件而不是布局。

QSplitter 继承自QFrame。用QSplitter 类创建实例对象的方法如下所示其中 parent是窗口或容器控件;Qt.Orientation 是分方向,可以取 Qt.Vertical或 Qt.Horizontal。

from PySide6.QtWidgets import QSplitter

QSplitter(arg__1: PySide6.QtCore.Qt.Orientation,parent: Union[PySide6.QtWidgets.QWidget,NoneType]=None)-> None
QSplitter(parent: Union[PySide6.QtWidgets.QWidget,NoneType]=None)-> None 

拆分器允许用户通过拖动子小部件之间的边界来控制子小部件的大小。任何数量的小部件都可以由单个拆分器控制。QSplitter的典型用途是创建多个小部件,并使用insertWidget()或addWidget()添加它们。

以下示例将并排显示QListView、QTreeView和QTextEdit,并带有两个拆分器句柄:

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

如果在调用insertWidget()或addWidget()时小部件已经在QSplitter中,它将移动到新位置。这可用于稍后对拆分器中的小部件重新排序。您可以使用indexOf()、widget()和count()访问拆分器中的小部件。

默认的QSplitter水平布局其子级(并排); 您可以使用设置方向(垂直)垂直布局其子级。

默认情况下,在小部件的minimumSizeHint()(或minimumSize())和maximumSize()之间,所有小部件都可以根据用户的意愿大小或大小。

默认情况下,QSplitter会动态调整其子级的大小。如果您希望QSplitter仅在调整大小操作结束时调整子级大小,请调用setOpaqueResize(false)。

小部件之间大小的初始分布是通过将初始大小与拉伸因子相乘来确定的。您还可以使用setsize()设置所有小部件的大小。函数size()返回用户设置的大小。或者,您可以分别使用saveState()和restore estate()从QByteArray保存和恢复小部件的大小。

当你隐藏()一个孩子时,它的空间将分布在其他孩子之间。当您再次显示()它时,它将被恢复。

不支持向QSplitter添加 QLayout(通过setLayout()或使QSplitter成为QLayout的父级); 而是使用addWidget()(请参见上面的示例)。

分割器控件QSplitter 的属性

属性	描述	访问功能
QtWidgets.QSplitter.childrenCollapsible: bool	此属性保存用户是否可以将子小部件的大小缩小到大小0。 默认情况下,儿童是可折叠的。可以使用settucable()启用和禁用单个孩子的折叠。	childrenCollapsible() setChildrenCollapsible(arg__1)
QtWidgets.QSplitter.handleWidth: int	此属性包含拆分器手柄的宽度。 默认情况下,此属性包含一个值,该值取决于用户的平台和样式首选项。 如果将handleWidth设置为1或0,则实际抓取区域将增加到与其各自小部件的几个像素重叠。	handleWidth() setHandleWidth(arg__1)
QtWidgets.QSplitter.opaqueResize: bool	如果在交互移动拆分器时动态(不可见)调整小部件的大小,则返回true。否则返回false。 默认的调整大小行为取决于样式(由SH_Splitter_OpaqueResize样式提示确定)。但是,您可以通过调用setOpaqueResize()来覆盖它	opaqueResize() setOpaqueResize([opaque=true])
QtWidgets.QSplitter.orientation: Orientation	此属性保存拆分器的方向。 默认情况下,方向是水平的(即,小部件并排放置)。可能的方向是水平和垂直。	orientation() setOrientation(arg__1)

分割器控件QSplitter 的常用方法

分割器控件 QSplitter 的常用方法如表所示,主要方法介绍如下。

• 控件添加

  • 用addWidget(QWidget)方法在末尾添加控件;

  • 用insertWidget(index:int,QWidget)方法插人控件,不能添加布局;

  • 用replaceWidget(index:int,QWidget)方法替换指定索引的控件;

  • 用widget(index:int)方法获取索引值是index的控件;

  • 用indexOf(QWidget)方法获取指定控件的索引值

  • 用count()方法获取控件的数量。

• 分割方向

  • 用setOrientation(Qt.Orientation)方法设置分制方向;
  • 用setOpaqueResize(bool)方法设置移动分割条时,是否是动态显示的,动态显示时控件随鼠标的移动进行缩放,非动态显示时释放鼠标后才缩放控件。

• 用setChildrenCollapsible(bool)和 setCollapsible(int,bool)方法设置控件是否是可以折叠的,在折叠情况下,两个分隔条可以合并在一起。

以下方法中涉及Orientation的均代表PySide6.QtCore.Qt.Orientation枚举类可取以下值:

PySide6.QtCore.Qt.Orientation	描述
Horizontal	水平
Vertical	垂直

QSplitter的方法及参数类型	说 明
addWidget(QWidget)	在末尾添加控件 在所有其他项目之后,将给定小部件添加到拆分器的布局中。 如果小部件已经在拆分器中,它将被移动到新位置。
widget(index:int)->PySide6.QtWidgets.QWidget	返回拆分器布局中给定索引处的小部件,如果没有这样的小部件,则返回None。
insertWidget(index:int,QWidget)	在指定索引位置插人控件
widget(index: int)	获取指定索引的控件
replaceWidget(index:int,QWidget)	替换指定索引的控件
count()	返回拆分器布局中包含的小部件数量。
indexOf(QWidget)	获取控件的索引值
setOrientation(PySide6.QtCore.Qt.Orientation)	设置分割方向,Orientation用于表示对象的方向。可选Qt.Horizontal或Qt.Vertical
orientation()	获取分割方向
setOpaqueResize([opaque=true])	设置拖动分隔条时,是否是动态的 如果在交互移动拆分器时动态(不可见)调整小部件的大小,则返回true。否则返回false。 默认的调整大小行为取决于样式(由SH_Splitter_OpaqueResize样式提示确定)。但是,您可以通过调用setOpaqueResize()来覆盖它
setStretchFactor(index:int,stretch:int)	设置分割区在窗口缩放时的缩放系数 在位置索引处更新小部件的大小策略,使其具有拉伸因子。 拉伸不是有效的拉伸因子; 有效拉伸因子是通过获取小部件的初始大小并将其与拉伸相乘来计算的。 此功能是为了方便起见而提供的。它相当于 widget = splitter.widget(index) policy = widget.sizePolicy() policy.setHorizontalStretch(stretch) policy.setVerticalStretch(stretch) widget.setSizePolicy(policy)
setHandJeWidth(int)	设置分隔条的宽度
setChildrenCollapsible(bool)	设置内部控件是否可以折叠,默认为True
childrenCollapsible()->bool	获取内部控件是否可以折叠,默认为True
setCollapsible(index:int,bool)	设置索引号为int的控件是否可以折叠
setSizes(list: Sequence[int])	使用可迭代序列(列表、元组等)设置内部控件的宽度(水平分 割)或高度(竖直分割) 将子小部件的相应大小设置为列表中给定的值。 如果拆分器是水平的,则值将从左到右设置每个小部件的宽度(以像素为单位)。如果分离器是垂直的,则设置每个小部件从上到下的高度。 列表中的额外值将被忽略。如果list包含的值太少,则结果未定义,但程序仍将运行良好。 拆分器小部件的整体大小不受影响。取而代之的是,根据尺寸的相对权重在小部件之间分配任何额外/缺失的空间。 如果指定大小为0,则小部件将不可见。保留小部件的大小策略。也就是说,小于相应小部件的最小大小提示的值将被提示的值替换。
sizes()	获取分割器中控件的宽度(水平分割)列表或高度(竖直分割)列表 返回此拆分器中所有小部件的大小参数列表。 如果拆分器的方向是水平的,则列表包含从左到右以像素为单位的小部件宽度; 如果方向是垂直的,则列表包含以像素为单位的小部件高度,从上到下。 将值提供给另一个拆分器的setsize()函数将生成具有与此相同布局的拆分器。 请注意,不可见的小部件的大小为0。
setRubberBand(position:int)	设置橡皮筋到指定位置,如果分割条不是动态的,则会看到橡皮筋 在位置位置显示橡皮筋。如果pos为负,橡皮筋将被移除。
moveSplitter(pos:int,index; int)	将索引为index的分割线移到pos处
getRange(index: int)	获取索引为int的分割线的可调节范围,返回元组 如果min和max不为0,则返回索引为 *"min"和 *"max"的拆分器的有效范围。
saveState()	保存状态到QByteArray
restoreState(QByteArray)	恢复保存的状态
closestLegalPosition(arg__1:int,arg__2:int)	返回最接近索引处小部件的位置。 对于从右到左的语言,如阿拉伯语和希伯来语,水平分配器的布局是相反的。然后从小部件的右边缘测量位置。
createHandle()->QtWidgets.QSplitterHandle	作为此拆分器的子小部件返回新的拆分器句柄。可以在子类中重新实现此函数,以提供对自定义句柄的支持。
handle(index:int)->QtWidgets.QSplitterHandle	在给定索引处返回拆分器布局中项目左侧(或上方)的句柄,如果没有此类项目,则返回None。索引0处的句柄始终隐藏。 对于从右到左的语言,如阿拉伯语和希伯来语,水平分配器的布局是相反的。句柄将位于索引处的小部件的右侧。
handleWidth()->int	此属性包含拆分器手柄的宽度。 默认情况下,此属性包含一个值,该值取决于用户的平台和样式首选项。 如果将handleWidth设置为1或0,则实际抓取区域将增加到与其各自小部件的几个像素重叠。
setHandleWidth(arg__1:int)	设置拆分器手柄的宽度
splitterMoved(pos:int,index:int)	当特定索引处的分离器手柄已移动到位置时,会发出该信号。 对于从右到左的语言,如阿拉伯语和希伯来语,水平分配器的布局是相反的。pos是距小部件右边缘的距离。

分割器控件QSplitter 的信号

分割器控件QSplitter 只有一个信号 splitterMoved(pos:int,index:int),当分隔条移动时发送信号,信号的参数是分割条的位置和索引值。

当特定索引处的分离器手柄已移动到位置时,会发出该信号。
对于从右到左的语言,如阿拉伯语和希伯来语,水平分配器的布局是相反的。pos是距小部件右边缘的距离。

分割手柄QSplitterHandle

QSplitterHandle说明

QSplitterHandle类为拆分器提供句柄功能。

from PySide6.QtWidgets import QSplitterHandle

QSplitterHandle(o: PySide6.QtCore.Qt.Orientation, parent: PySide6.QtWidgets.QSplitter)

QSplitterHandle通常是人们在考虑拆分器时所想到的。它是用于调整小部件大小的句柄。

使用QSplitter的典型开发人员永远不必担心QSplitterHandle。它是为那些想要提供额外功能（如弹出菜单）的拆分器句柄的开发人员提供的。

创建拆分器句柄的典型方法是子类QSplitter，然后重新实现createHandle（）来实例化自定义拆分器句柄。例如，最小的QSplitter子类可能如下所示：

class Splitter(QSplitter):

# public
    Splitter(Qt.Orientation orientation, QWidget parent = None)
# protected
    createHandle = QSplitterHandle()

createHandle（）实现简单地构造了一个自定义拆分器句柄，在本例中称为splitter：

Splitter::createHandle = QSplitterHandle()

    return SplitterHandle(orientation(), self)

关于给定句柄的信息可以使用orientation（）和opaqueResize（）等函数获得，并从其父拆分器中检索。根据拆分器的方向，可以使用类似的细节为自定义控制柄提供不同的外观。
自定义句柄子类的复杂性取决于它需要执行的任务。一个简单的子类可能只提供paintEvent（）实现：

def paintEvent(self, event):

    painter = QPainter(self)
    if orientation() == Qt.Horizontal:
        gradient.setStart(rect().left(), rect().height()/2)
        gradient.setFinalStop(rect().right(), rect().height()/2)
    else:
        gradient.setStart(rect().width()/2, rect().top())
        gradient.setFinalStop(rect().width()/2, rect().bottom())

    painter.fillRect(event.rect(), QBrush(gradient))

在本例中，预定义的渐变会根据控制柄的方向进行不同的设置。QSplitterHandle为句柄提供了合理的大小提示，因此子类不需要重新实现sizeHint（），除非句柄有特殊的大小要求。

QSplitterHandle方法

方法	描述
closestLegalPosition(self, p: int) -> int	返回离拆分器句柄的位置最近的合法位置。位置是从拆分器的左边缘或上边缘开始测量的，即使对于从右到左的语言也是如此。
moveSplitter(self, p: int)	告诉拆分器将这个手柄移动到pos位置，pos是与小部件左侧或顶部边缘的距离。 注意，对于从右到左的语言，pos也是从左（或顶部）测量的。此函数将在调用moveSplitter（）之前将pos映射到适当的位置。
opaqueResize(self) -> bool	如果在交互式移动拆分器时动态（不透明）调整小部件的大小，则返回true。否则返回false。该值由Q拆分器控制。
orientation(self) -> PySide6.QtCore.Qt.Orientation	返回控制柄的方向。这通常是从QSplitter传播的。
setOrientation(self, o: PySide6.QtCore.Qt.Orientation)	将拆分器控制柄的方向设置为方向。这通常是从QSplitter传播的。
splitter(self) -> PySide6.QtWidgets.QSplitter	返回与此拆分器句柄关联的拆分器。

分割器控件QSplitter 的应用实例

下面的程序用两个 QSplitter 分割器将窗日分成三部分,每部分显示一个图片。

# -*- coding: UTF-8 -*-
# File date: Hi_2023/2/28 21:53
# File_name: 01-分割器控件QSplitter 的应用实例.py
from PySide6.QtWidgets import QApplication,QWidget,QSplitter,QLabel,QHBoxLayout
from PySide6.QtCore import Qt
import sys
from PySide6.QtGui import QPixmap


class MyWindow(QWidget):
    def __init__(self,parent=None):
        super().__init__(parent)
        self.widget_setupUi()

    def widget_setupUi(self):  # 建立主程序界面
        label_1 = QLabel()
        label_2 = QLabel()
        label_3 = QLabel()

        label_1.setPixmap(QPixmap('../../Resources/animal/m1.png'))
        label_2.setPixmap(QPixmap('../../Resources/animal/m2.png'))
        label_3.setPixmap(QPixmap('../../Resources/animal/m3.png'))

        splitter_H = QSplitter(Qt.Orientation.Horizontal)
        splitter_V = QSplitter(Qt.Orientation.Vertical)
        h = QHBoxLayout(self)
        h.addWidget(splitter_H)
        splitter_H.addWidget(label_1)
        splitter_H.addWidget(splitter_V)
        splitter_V.addWidget(label_2)
        splitter_V.addWidget(label_3)


if __name__ =='__main__':
    app = QApplication(sys.argv)
    win = MyWindow()

    win.show()
    sys.exit(app.exec())