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

用给定的orientation 和parent 创建QSplitter 句柄。

[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 的位置，即与 widget 左边缘或顶边缘的距离。

请注意，对于从右到左的语言，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()。

© 2025 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.