QDockWidget Class
QDockWidget类提供了一个小部件,可以停靠在QMainWindow中,也可以作为桌面上的顶级窗口浮动。
Header | #include < QDockWidget > |
---|---|
qmake | QT += widgets |
Inherits | QWidget |
Inherited By |
详细说明
QDockWidget提供了dock Widget的概念,也称为工具选项板或实用程序窗口。停靠窗口是放置在QMainWindow中心小部件周围的停靠小部件区域中的辅助窗口。
停靠窗口可以在其当前区域内移动,移动到新区域,并由最终用户浮动(例如,取消停靠)。QDockWidget API允许程序员限制dock小部件移动、浮动和关闭的能力,以及它们可以放置的区域。
外观
QDockWidget由标题栏和内容区域组成。标题栏显示dock widgets窗口标题、浮动按钮和关闭按钮。根据QDockWidget的状态,浮动和关闭按钮可以被禁用,也可以根本不显示。
标题栏和按钮的视觉外观取决于所使用的样式。
QDockWidget充当其子小部件的包装器,用setWidget() 设置。自定义大小提示、最小和最大大小以及大小策略应该在子小部件中实现。QDockWidget将尊重它们,调整自己的约束以包括框架和标题。不应该对QDockWidget本身设置大小限制,因为它们会根据是否停靠而改变;停靠的QDockWidget没有框架和较小的标题栏。
公共类型
enum DockWidgetFeature
flags DockWidgetFeatures
Constant | Value | Description |
---|---|---|
NoDockWidgetFeatures | 0x00 | 无法关闭、移动或浮动dock小部件。 |
DockWidgetClosable | 0x01 | 可以关闭dock小部件。在某些系统上,dock小部件在浮动时总是有一个close按钮(例如在macos10.5上)。 |
DockWidgetMovable | 0x02 | dock小部件可以由用户在dock之间移动。 |
DockWidgetFloatable | 0x04 | dock小部件可以从主窗口分离,并作为独立窗口浮动。 |
DockWidgetVerticalTitleBar | 0x08 | dock小部件在其左侧显示一个垂直标题栏。这可用于增加QMainWindow中的垂直空间量。 |
AllDockWidgetFeatures | DockWidgetClosable |DockWidgetMovable |DockWidgetFloatable | (已弃用)由于新特性可能会在将来的版本中添加,因此如果使用此标志,dock小部件的外观和行为可能会发生变化。请指定单个标志。 |
属性
-
allowedAreas: Qt::DockWidgetAreas 可放置dock小部件的区域
默认值是Qt::AllDockWidgetAreas。Access functions:
- Qt::DockWidgetAreas allowedAreas() const
- void setAllowedAreas(Qt::DockWidgetAreas areas)
enum Qt::DockWidgetArea
flags Qt::DockWidgetAreasConstant Value Qt::NoDockWidgetArea 0 Qt::LeftDockWidgetArea 0x1 Qt::RightDockWidgetArea 0x2 Qt::TopDockWidgetArea 0x4 Qt::BottomDockWidgetArea 0x8 Qt::AllDockWidgetAreas DockWidgetArea_Mask Notifier signal:
- void allowedAreasChanged(Qt::DockWidgetAreas allowedAreas)
-
features: DockWidgetFeatures dock小部件是否可移动、可关闭和可浮动
默认情况下,此属性设置为DockWidgetClosable、DockWidgetMovable和DockWidgetFloatable的组合。
- QDockWidget::DockWidgetFeatures features() const
- void setFeatures(QDockWidget::DockWidgetFeatures features)
Notifier signal:
- void featuresChanged(QDockWidget::DockWidgetFeatures features)
-
floating: bool 此dock小部件是否浮动
浮动窗口小部件作为独立窗口呈现给用户,它位于其父QMainWindow的“on top”,而不是停靠在QMainWindow中。
默认情况下,此属性为true。当此属性更改时,将发出topLevelChanged() 信号。
- bool isFloating() const
- void setFloating(bool floating)
-
windowTitle: QString dock小部件标题(标题)
默认情况下,此属性包含空字符串。- QString windowTitle() const
- void setWindowTitle(const QString &)
Notifier signal:
- void windowTitleChanged(const QString &title)
公共函数
构造和析构
- QDockWidget(QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())
- QDockWidget(const QString &title, QWidget *parent = nullptr, Qt::WindowFlags flags = Qt::WindowFlags())
- virtual ~QDockWidget()
属性相关
- Qt::DockWidgetAreas allowedAreas() const
void setAllowedAreas(Qt::DockWidgetAreas areas) - QDockWidget::DockWidgetFeatures features() const
void setFeatures(QDockWidget::DockWidgetFeatures features) - bool isFloating() const
void setFloating(bool floating) - QString windowTitle() const
void setWindowTitle(const QString &)
其他
-
bool isAreaAllowed(Qt::DockWidgetArea area) const 此dock小部件是否可以放置在给定区域中
-
QAction * toggleViewAction() const 返回添加到菜单和工具栏的可检查操作,以便显示或关闭此dock小部件
操作的文本设置为dock小部件的窗口标题。
注意:该操作不能用于以编程方式显示或隐藏dock小部件。使用visible属性。 -
QWidget * titleBarWidget() const
void setTitleBarWidget(QWidget *widget) 将任意小部件设置为dock小部件的标题栏如果widget是nullptr,那么先前在dock小部件上设置的任何自定义标题栏小部件都将被删除,但不会被删除,而是使用默认标题栏。
如果设置了标题栏小部件,当它浮动时,QDockWidget将不使用本机窗口装饰。
以下是实现自定义标题栏的一些技巧:
-
必须通过调用QMouseEvent::ignore() 忽略标题栏小部件未显式处理的鼠标事件。然后,这些事件传播到QDockWidget父级,该父级以通常的方式处理它们,在拖动标题栏时移动,在双击标题栏时停靠和取消停靠,等等。
-
当在QDockWidget上设置DockWidgetVerticalTitleBar时,标题栏小部件将相应地重新定位。在resizeEvent() 中,标题栏应检查其应采用的方向:
QDockWidget *dockWidget = qobject_cast<QDockWidget*>(parentWidget()); if (dockWidget->features() & QDockWidget::DockWidgetVerticalTitleBar) { // I need to be vertical } else { // I need to be horizontal }
-
标题栏小部件必须具有有效的QWidget::sizeHint() 和QWidget::minimumSizeHint() 。这些函数应考虑标题栏的当前方向。
-
无法从dock小部件中删除标题栏。但是,通过将默认构造的QWidget设置为标题栏小部件,可以实现类似的效果。
使用如上所示的qobject_cast() ,标题栏小部件可以完全访问其父QDockWidget。因此,它可以执行诸如停靠和隐藏等操作来响应用户操作。
-
-
QWidget * widget() const
void setWidget(QWidget *widget) 将dock小部件的内容小部件设置为widget如果添加小部件时dock小部件可见,则必须显式显示它。
请注意,在调用此函数之前必须添加小部件的布局;否则,小部件将不可见。
信号
- void allowedAreasChanged(Qt::DockWidgetAreas allowedAreas)
- void dockLocationChanged(Qt::DockWidgetArea area)
- void featuresChanged(QDockWidget::DockWidgetFeatures features)
- void topLevelChanged(bool topLevel)
- void visibilityChanged(bool visible)
受保护的函数
- void initStyleOption(QStyleOptionDockWidget *option) const
重写的受保护的函数
- virtual void changeEvent(QEvent *event) override
- virtual void closeEvent(QCloseEvent *event) override
- virtual bool event(QEvent *event) override
- virtual void paintEvent(QPaintEvent *event) override
演示代码
#include <QtWidgets>
void setMenuTool(QMainWindow *mw){
QCommonStyle cs;
QIcon icon = cs.standardIcon ((QStyle::StandardPixmap)0);
QAction *newAct = new QAction(icon,"&New", mw);
newAct->setShortcuts(QKeySequence::New);
newAct->setStatusTip("Create a new file");
icon = cs.standardIcon ((QStyle::StandardPixmap)33);
QAction *openAct = new QAction(icon,"&Open...", mw);
openAct->setShortcuts(QKeySequence::Open);
openAct->setStatusTip("Open an existing file");
QMenu *fileMenu = mw->menuBar()->addMenu("&File");
fileMenu->addAction(newAct);
fileMenu->addSeparator();
fileMenu->addAction(openAct);
QToolBar *fileToolBar = mw->addToolBar("File");
fileToolBar->addAction(newAct);
fileToolBar->addSeparator ();
fileToolBar->addAction(openAct);
}
void setDock( QMainWindow *mw ){
for (int i = 0,j=1; i < 10; ++i,j*=2) {
QString str = QString("Dock %1").arg (i);
QDockWidget *dock = new QDockWidget(str, mw);
dock->setMinimumWidth (120);
dock->setAllowedAreas (Qt::AllDockWidgetAreas);
mw->addDockWidget((Qt::DockWidgetArea)(1), dock);
QLabel *label = new QLabel(str,dock);
label->setStyleSheet ("background:cyan");
dock->setWidget (label);
if(i == 3){ // i==3 停靠窗口 设置 不能浮动、移动、关闭,可以当作中央控件
dock->setWindowTitle ("Central");
dock->setFeatures (QDockWidget::NoDockWidgetFeatures);
}
}
}
int main(int argc, char *argv[])
{
QApplication a(argc, argv);
a.setApplicationName ("QMainWindow");
QMainWindow w;
setMenuTool(&w);
setDock (&w);
w.setDockNestingEnabled (true);
w.statusBar ()->showMessage ("QMainWindow");
w.resize (350,200);
w.show();
return a.exec();
}