Back to Qt.io
Contact Us Blog Download Qt
本页内容

QSplitterHandle Class

QSplitterHandle 类为分隔符提供了句柄功能。更多内容...

头文件： #include <QSplitterHandle>
CMake： find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake： QT += widgets
继承自： QWidget

公共函数

QSplitterHandle(Qt::Orientation orientation, QSplitter *parent)
virtual ~QSplitterHandle()
bool opaqueResize() const
Qt::Orientation orientation() const
void setOrientation(Qt::Orientation orientation)
QSplitter *splitter() const

重新实现的公共函数

virtual QSize sizeHint() const override

受保护函数

int closestLegalPosition(int pos)
void moveSplitter(int pos)

重新实现的受保护函数

virtual bool event(QEvent *event) override
virtual void mouseMoveEvent(QMouseEvent *e) override
virtual void mousePressEvent(QMouseEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual void paintEvent(QPaintEvent *) override
virtual void resizeEvent(QResizeEvent *event) override

详细说明

提到分隔条时，人们通常想到的就是 QSplitterHandle。它是用于调整小部件大小的控件。

普通开发者在使用QSplitter 时，完全无需担心QSplitterHandle。它专为需要具备额外功能（如弹出菜单）的分隔符控件手柄的开发者而提供。

创建分隔符控件的典型方法是继承QSplitter ，然后重写QSplitter::createHandle()方法来实例化自定义的分隔符控件。例如，一个最简单的QSplitter 子类可能如下所示：

class Splitter : public QSplitter
{
public:
    Splitter(Qt::Orientation orientation, QWidget *parent = nullptr);

protected:
    QSplitterHandle *createHandle() override;
};

createHandle() 的实现只需构造一个自定义分隔符句柄，本例中称为Splitter ：

QSplitterHandle *Splitter::createHandle()
{
    return new SplitterHandle(orientation(), this);
}

可以通过orientation() 和opaqueResize() 等函数获取给定句柄的信息，这些信息来自其父级拆分器。利用这些细节，可以根据拆分器的方向为自定义句柄赋予不同的外观。

自定义控件子类的复杂程度取决于其需要执行的任务。一个简单的子类可能仅提供paintEvent() 的实现：

void SplitterHandle::paintEvent(QPaintEvent *event)
{
    QPainter painter(this);
    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() 方法。

另请参阅 QSplitter 。

成员函数文档

[explicit] QSplitterHandle::QSplitterHandle(Qt::Orientation orientation, QSplitter *parent)

创建一个QSplitter 句柄，其orientation 和parent 参数分别为给定的值。

[virtual noexcept] QSplitterHandle::~QSplitterHandle()

析构函数。

[protected] int QSplitterHandle::closestLegalPosition(int pos)

返回拆分器控件中距离pos 最近的合法位置。这些位置是从拆分器的左边缘或顶部边缘开始测量的，即使是右向左书写的语言也是如此。

另请参阅 QSplitter::closestLegalPosition() 和moveSplitter()。

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

重写了：QWidget::event(QEvent *event)。

[override virtual protected] void QSplitterHandle::mouseMoveEvent(QMouseEvent *e)

重写了：QWidget::mouseMoveEvent(QMouseEvent *event)。

[override virtual protected] void QSplitterHandle::mousePressEvent(QMouseEvent *e)

重写了：QWidget::mousePressEvent(QMouseEvent *event)。

[override virtual protected] void QSplitterHandle::mouseReleaseEvent(QMouseEvent *e)

重写了：QWidget::mouseReleaseEvent(QMouseEvent *event)。

[protected] void QSplitterHandle::moveSplitter(int pos)

指示分割器将此控点移动到位置pos ，该位置是距控件左边缘或顶边缘的距离。

请注意，对于从右向左书写的语言，pos 同样是从左侧（或顶部）开始测量的。该函数会在调用QSplitter::moveSplitter() 之前，将pos 映射到相应的位置。

另请参阅 QSplitter::moveSplitter() 和closestLegalPosition()。

bool QSplitterHandle::opaqueResize() const

如果在交互式移动分隔线时小部件被动态（不透明地）调整大小，则返回true ；否则返回false 。该值由QSplitter 控制。

另请参阅 QSplitter::opaqueResize()。

Qt::Orientation QSplitterHandle::orientation() const

返回句柄的朝向。该信息通常由QSplitter 传递而来。

另请参阅 setOrientation() 和QSplitter::orientation()。

[override virtual protected] void QSplitterHandle::paintEvent(QPaintEvent *)

重写了：QWidget::paintEvent(QPaintEvent *event)。

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

重写了：QWidget::resizeEvent(QResizeEvent *event)。

void QSplitterHandle::setOrientation(Qt::Orientation orientation)

将拆分器控件的取向设置为orientation 。该取向通常由QSplitter 传递而来。

另请参阅 orientation() 和QSplitter::setOrientation()。

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

重新实现了属性QWidget::sizeHint 的访问函数。

QSplitter *QSplitterHandle::splitter() const

返回与该分割器句柄关联的分割器。

另请参阅 QSplitter::handle()。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.