diff options
Diffstat (limited to 'src/widgets/doc')
91 files changed, 1512 insertions, 937 deletions
diff --git a/src/widgets/doc/images/addressbook-tutorial-part1-labeled-layout.png b/src/widgets/doc/images/addressbook-tutorial-part1-labeled-layout.png Binary files differdeleted file mode 100644 index b19cb360a1..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part1-labeled-layout.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part1-labeled-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-part1-labeled-screenshot.png Binary files differdeleted file mode 100644 index f9b91eebe6..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part1-labeled-screenshot.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part1-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-part1-screenshot.png Binary files differdeleted file mode 100644 index 454b0959e6..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part1-screenshot.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part2-add-contact.png b/src/widgets/doc/images/addressbook-tutorial-part2-add-contact.png Binary files differdeleted file mode 100644 index 6f2b947b21..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part2-add-contact.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part2-add-flowchart.png b/src/widgets/doc/images/addressbook-tutorial-part2-add-flowchart.png Binary files differdeleted file mode 100644 index ca9af3720d..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part2-add-flowchart.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part2-add-successful.png b/src/widgets/doc/images/addressbook-tutorial-part2-add-successful.png Binary files differdeleted file mode 100644 index 99a2154007..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part2-add-successful.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part2-labeled-layout.png b/src/widgets/doc/images/addressbook-tutorial-part2-labeled-layout.png Binary files differdeleted file mode 100644 index 1e000c8f31..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part2-labeled-layout.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part2-signals-and-slots.png b/src/widgets/doc/images/addressbook-tutorial-part2-signals-and-slots.png Binary files differdeleted file mode 100644 index e49f8dc262..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part2-signals-and-slots.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part2-stretch-effects.png b/src/widgets/doc/images/addressbook-tutorial-part2-stretch-effects.png Binary files differdeleted file mode 100644 index d9f7f31227..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part2-stretch-effects.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part3-labeled-layout.png b/src/widgets/doc/images/addressbook-tutorial-part3-labeled-layout.png Binary files differdeleted file mode 100644 index 1981ba8cb6..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part3-labeled-layout.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part3-linkedlist.png b/src/widgets/doc/images/addressbook-tutorial-part3-linkedlist.png Binary files differdeleted file mode 100644 index e7f4725dce..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part3-linkedlist.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part3-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-part3-screenshot.png Binary files differdeleted file mode 100644 index 75159b4045..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part3-screenshot.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part4-remove.png b/src/widgets/doc/images/addressbook-tutorial-part4-remove.png Binary files differdeleted file mode 100644 index 8eb259ef02..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part4-remove.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part5-finddialog.png b/src/widgets/doc/images/addressbook-tutorial-part5-finddialog.png Binary files differdeleted file mode 100644 index 743d92ef6f..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part5-finddialog.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part5-notfound.png b/src/widgets/doc/images/addressbook-tutorial-part5-notfound.png Binary files differdeleted file mode 100644 index 2d35766ab5..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part5-notfound.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part5-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-part5-screenshot.png Binary files differdeleted file mode 100644 index 3abe2775c2..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part5-screenshot.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part5-signals-and-slots.png b/src/widgets/doc/images/addressbook-tutorial-part5-signals-and-slots.png Binary files differdeleted file mode 100644 index 1771e7bbbf..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part5-signals-and-slots.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part6-load.png b/src/widgets/doc/images/addressbook-tutorial-part6-load.png Binary files differdeleted file mode 100644 index a027a1decb..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part6-load.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part6-save.png b/src/widgets/doc/images/addressbook-tutorial-part6-save.png Binary files differdeleted file mode 100644 index 757feeb9ac..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part6-save.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part6-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-part6-screenshot.png Binary files differdeleted file mode 100644 index 7bb2f749bf..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part6-screenshot.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-part7-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-part7-screenshot.png Binary files differdeleted file mode 100644 index 3e7b3ca522..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-part7-screenshot.png +++ /dev/null diff --git a/src/widgets/doc/images/addressbook-tutorial-screenshot.png b/src/widgets/doc/images/addressbook-tutorial-screenshot.png Binary files differdeleted file mode 100644 index 3fba6e849e..0000000000 --- a/src/widgets/doc/images/addressbook-tutorial-screenshot.png +++ /dev/null diff --git a/src/widgets/doc/images/collapsed_combobox.png b/src/widgets/doc/images/collapsed_combobox.png Binary files differnew file mode 100644 index 0000000000..1400090f42 --- /dev/null +++ b/src/widgets/doc/images/collapsed_combobox.png diff --git a/src/widgets/doc/images/cuberhiwidget-example.jpg b/src/widgets/doc/images/cuberhiwidget-example.jpg Binary files differnew file mode 100644 index 0000000000..70baab8beb --- /dev/null +++ b/src/widgets/doc/images/cuberhiwidget-example.jpg diff --git a/src/widgets/doc/images/expanded_combobox.png b/src/widgets/doc/images/expanded_combobox.png Binary files differnew file mode 100644 index 0000000000..6df0cecbbd --- /dev/null +++ b/src/widgets/doc/images/expanded_combobox.png diff --git a/src/widgets/doc/images/msgbox1.png b/src/widgets/doc/images/msgbox1.png Binary files differindex 1380e20a5f..ded1d295b6 100644 --- a/src/widgets/doc/images/msgbox1.png +++ b/src/widgets/doc/images/msgbox1.png diff --git a/src/widgets/doc/images/msgbox2.png b/src/widgets/doc/images/msgbox2.png Binary files differindex e7946996e4..9afd3282f3 100644 --- a/src/widgets/doc/images/msgbox2.png +++ b/src/widgets/doc/images/msgbox2.png diff --git a/src/widgets/doc/images/msgbox3.png b/src/widgets/doc/images/msgbox3.png Binary files differindex bd81f4d4da..50a4a124c4 100644 --- a/src/widgets/doc/images/msgbox3.png +++ b/src/widgets/doc/images/msgbox3.png diff --git a/src/widgets/doc/images/msgbox4.png b/src/widgets/doc/images/msgbox4.png Binary files differindex dbe6701cdd..337b3553e9 100644 --- a/src/widgets/doc/images/msgbox4.png +++ b/src/widgets/doc/images/msgbox4.png diff --git a/src/widgets/doc/images/qrhiwidget-intro.jpg b/src/widgets/doc/images/qrhiwidget-intro.jpg Binary files differnew file mode 100644 index 0000000000..20f931a723 --- /dev/null +++ b/src/widgets/doc/images/qrhiwidget-intro.jpg diff --git a/src/widgets/doc/images/qtquickdialogs-filedialog-gtk.png b/src/widgets/doc/images/qtquickdialogs-filedialog-gtk.png Binary files differnew file mode 100644 index 0000000000..9360d747a2 --- /dev/null +++ b/src/widgets/doc/images/qtquickdialogs-filedialog-gtk.png diff --git a/src/widgets/doc/images/simplerhiwidget-example.jpg b/src/widgets/doc/images/simplerhiwidget-example.jpg Binary files differnew file mode 100644 index 0000000000..3f0a1b355c --- /dev/null +++ b/src/widgets/doc/images/simplerhiwidget-example.jpg diff --git a/src/widgets/doc/images/spinboxdelegate-example.png b/src/widgets/doc/images/spinboxdelegate-example.png Binary files differdeleted file mode 100644 index 5e57a9c12b..0000000000 --- a/src/widgets/doc/images/spinboxdelegate-example.png +++ /dev/null diff --git a/src/widgets/doc/images/spinboxdelegate-example.webp b/src/widgets/doc/images/spinboxdelegate-example.webp Binary files differnew file mode 100644 index 0000000000..35b5770394 --- /dev/null +++ b/src/widgets/doc/images/spinboxdelegate-example.webp diff --git a/src/widgets/doc/images/stylesheet-coffee-cleanlooks.png b/src/widgets/doc/images/stylesheet-coffee-cleanlooks.png Binary files differdeleted file mode 100644 index e75df0d80a..0000000000 --- a/src/widgets/doc/images/stylesheet-coffee-cleanlooks.png +++ /dev/null diff --git a/src/widgets/doc/images/stylesheet-pagefold-mac.png b/src/widgets/doc/images/stylesheet-pagefold-mac.png Binary files differdeleted file mode 100644 index 5c061b9cfd..0000000000 --- a/src/widgets/doc/images/stylesheet-pagefold-mac.png +++ /dev/null diff --git a/src/widgets/doc/images/system-tray.png b/src/widgets/doc/images/system-tray.png Binary files differdeleted file mode 100644 index 298b193cf7..0000000000 --- a/src/widgets/doc/images/system-tray.png +++ /dev/null diff --git a/src/widgets/doc/images/system-tray.webp b/src/widgets/doc/images/system-tray.webp Binary files differnew file mode 100644 index 0000000000..ae509ccad3 --- /dev/null +++ b/src/widgets/doc/images/system-tray.webp diff --git a/src/widgets/doc/qtwidgets.qdocconf b/src/widgets/doc/qtwidgets.qdocconf index a63a2f5f2d..5f68179a36 100644 --- a/src/widgets/doc/qtwidgets.qdocconf +++ b/src/widgets/doc/qtwidgets.qdocconf @@ -26,7 +26,21 @@ qhp.QtWidgets.subprojects.classes.sortPages = true tagfile = ../../../doc/qtwidgets/qtwidgets.tags -depends += qtcore qtgui qtdoc qtsql qtdesigner qtquick qmake qtcmake qtsvg qtlinguist qthelp +depends += \ + qtcore \ + qtgui \ + qtdoc \ + qtsql \ + qtdesigner \ + qtquick \ + qmake \ + qtcmake \ + qtsvg \ + qtlinguist \ + qthelp \ + qtopengl \ + qtshadertools \ + qttestlib headerdirs += .. @@ -60,7 +74,16 @@ imagedirs += images \ navigation.landingpage = "Qt Widgets" navigation.cppclassespage = "Qt Widgets C++ Classes" -manifestmeta.highlighted.names = "QtWidgets/Qt Widgets - Application Example" -# Fail the documentation build if there are more warnings than the limit +# Highlighted examples for User Interface Components category +manifestmeta.highlighted.names = \ + "QtWidgets/Editable Tree Model Example" \ + "QtWidgets/Menus Example" + +# Highlighted examples for Desktop category +manifestmeta.highlighted.names += \ + "QtWidgets/System Tray Icon Example" \ + "QtWidgets/Taking a Screenshot" + +# Enforce zero documentation warnings warninglimit = 0 diff --git a/src/widgets/doc/snippets/CMakeLists.txt b/src/widgets/doc/snippets/CMakeLists.txt index 73e0e58f59..6274244db0 100644 --- a/src/widgets/doc/snippets/CMakeLists.txt +++ b/src/widgets/doc/snippets/CMakeLists.txt @@ -1,5 +1,5 @@ # Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0 +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #! [cmake_use] find_package(Qt6 REQUIRED COMPONENTS Widgets) diff --git a/src/widgets/doc/snippets/cmake-macros/examples.cmake b/src/widgets/doc/snippets/cmake-macros/examples.cmake index eb08663540..3c58509fdf 100644 --- a/src/widgets/doc/snippets/cmake-macros/examples.cmake +++ b/src/widgets/doc/snippets/cmake-macros/examples.cmake @@ -4,5 +4,5 @@ #! [qt_wrap_ui] set(SOURCES mainwindow.cpp main.cpp) qt_wrap_ui(SOURCES mainwindow.ui) -add_executable(myapp ${SOURCES}) +qt_add_executable(myapp ${SOURCES}) #! [qt_wrap_ui] diff --git a/src/widgets/doc/snippets/code/doc_src_qt4-mainwindow.cpp b/src/widgets/doc/snippets/code/doc_src_qt4-mainwindow.cpp index 7ac3577648..2c8a892511 100644 --- a/src/widgets/doc/snippets/code/doc_src_qt4-mainwindow.cpp +++ b/src/widgets/doc/snippets/code/doc_src_qt4-mainwindow.cpp @@ -26,48 +26,3 @@ setCorner(Qt::BottomRightCorner, Qt::RightDockWidgetArea); QWidget *centralWidget = new QWidget(this); setCentralWidget(centralWidget); //! [3] - - -//! [4] -QPopupMenu *fileMenu = new QPopupMenu(this); -openAction->addTo(fileMenu); -saveAction->addTo(fileMenu); -... -menuBar()->insertItem(tr("&File"), fileMenu); -//! [4] - - -//! [5] -QMenu *fileMenu = menuBar()->addMenu(tr("&File")); -fileMenu->addAction(openAction); -fileMenu->addAction(saveAction); -... -//! [5] - - -//! [6] -QToolBar *fileTools = new QToolBar(this, "file toolbar"); -openAction->addTo(fileTools); -saveAction->addTo(fileTools); -... -//! [6] - - -//! [7] -QToolBar *fileTools = addToolBar(tr("File Tool Bar")); -fileTools->addAction(openAction); -fileTools->addAction(saveAction); -... -//! [7] - - -//! [8] -QDockWidget *dockWidget = new QDockWidget(this); -mainWin->moveDockWidget(dockWidget, Qt::DockLeft); -//! [8] - - -//! [9] -QDockWidget *dockWidget = new QDockWidget(mainWindow); -mainWindow->addDockWidget(Qt::LeftDockWidgetArea, dockWidget); -//! [9] diff --git a/src/widgets/doc/snippets/code/doc_src_qt4-styles.cpp b/src/widgets/doc/snippets/code/doc_src_qt4-styles.cpp index 3620c261a5..2ec3afba01 100644 --- a/src/widgets/doc/snippets/code/doc_src_qt4-styles.cpp +++ b/src/widgets/doc/snippets/code/doc_src_qt4-styles.cpp @@ -24,22 +24,3 @@ void MyWidget::paintEvent(QPaintEvent *event) this); } //! [1] - - -//! [2] -void drawControl(ControlElement element, - QPainter *painter, - const QWidget *widget, - const QRect &rect, - const QColorGroup &colorGroup, - SFlags how = Style_Default, - const QStyleOption &option = QStyleOption::Default) const; -//! [2] - - -//! [3] -void drawControl(ControlElement element, - const QStyleOption *option, - QPainter *painter, - const QWidget *widget = nullptr) const; -//! [3] diff --git a/src/widgets/doc/snippets/code/doc_src_stylesheet.cpp b/src/widgets/doc/snippets/code/doc_src_stylesheet.cpp index 7fbcc493de..91851f8f07 100644 --- a/src/widgets/doc/snippets/code/doc_src_stylesheet.cpp +++ b/src/widgets/doc/snippets/code/doc_src_stylesheet.cpp @@ -51,7 +51,7 @@ qApp->setStyleSheet("ns--MyPushButton { background: yellow; }"); void CustomWidget::paintEvent(QPaintEvent *) { QStyleOption opt; - opt.init(this); + opt.initFrom(this); QPainter p(this); style()->drawPrimitive(QStyle::PE_Widget, &opt, &p, this); } diff --git a/src/widgets/doc/snippets/code/doc_src_stylesheet.qdoc b/src/widgets/doc/snippets/code/doc_src_stylesheet.qdoc index 6b4a472275..388e9d1f7c 100644 --- a/src/widgets/doc/snippets/code/doc_src_stylesheet.qdoc +++ b/src/widgets/doc/snippets/code/doc_src_stylesheet.qdoc @@ -1,5 +1,5 @@ // Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only //! [0] QLineEdit { background: yellow } @@ -450,32 +450,48 @@ QDialog { etch-disabled-text: 1 } //! [82] -QLabel { border-color: red } /* red red red red */ -QLabel { border-color: red blue } /* red blue red blue */ -QLabel { border-color: red blue green } /* red blue green blue */ -QLabel { border-color: red blue green yellow } +/* red red red red */ +QLabel { border-color: red } +/* red blue red blue */ +QLabel { border-color: red blue } +/* red blue green blue */ +QLabel { border-color: red blue green } /* red blue green yellow */ +QLabel { border-color: red blue green yellow } //! [82] //! [83] -QLabel { border-width: 1px } /* 1px 1px 1px 1px */ -QLabel { border-width: 1px 2px } /* 1px 2px 1px 2px */ -QLabel { border-width: 1px 2px 3px } /* 1px 2px 3px 2px */ -QLabel { border-width: 1px 2px 3px 4px } /* 1px 2px 3px 4px */ +/* 1px 1px 1px 1px */ +QLabel { border-width: 1px } +/* 1px 2px 1px 2px */ +QLabel { border-width: 1px 2px } +/* 1px 2px 3px 2px */ +QLabel { border-width: 1px 2px 3px } +/* 1px 2px 3px 4px */ +QLabel { border-width: 1px 2px 3px 4px } //! [83] //! [84] -QLabel { border-color: red } /* opaque red */ -QLabel { border-color: #FF0000 } /* opaque red */ -QLabel { border-color: rgba(255, 0, 0, 75%) } /* 75% opaque red */ -QLabel { border-color: rgb(255, 0, 0) } /* opaque red */ -QLabel { border-color: rgb(100%, 0%, 0%) } /* opaque red */ -QLabel { border-color: hsv(60, 100%, 100%) } /* opaque yellow */ -QLabel { border-color: hsva(240, 255, 255, 75%) } /* 75% blue */ -QLabel { border-color: hsl(60, 100%, 50%) } /* opaque yellow */ -QLabel { border-color: hsla(240, 255, 50%, 75%) } /* 75% blue */ +/* opaque red */ +QLabel { border-color: red } +/* opaque red */ +QLabel { border-color: #FF0000 } +/* 75% opaque red */ +QLabel { border-color: rgba(255, 0, 0, 75%) } +/* opaque red */ +QLabel { border-color: rgb(255, 0, 0) } +/* opaque red */ +QLabel { border-color: rgb(100%, 0%, 0%) } +/* opaque yellow */ +QLabel { border-color: hsv(60, 100%, 100%) } +/* 75% blue */ +QLabel { border-color: hsva(240, 255, 255, 75%) } +/* opaque yellow */ +QLabel { border-color: hsl(60, 100%, 50%) } +/* 75% blue */ +QLabel { border-color: hsla(240, 255, 50%, 75%) } //! [84] @@ -1223,7 +1239,7 @@ QScrollBar::sub-line:horizontal { //! [135] -QScrollBar:left-arrow:horizontal, QScrollBar::right-arrow:horizontal { +QScrollBar::left-arrow:horizontal, QScrollBar::right-arrow:horizontal { border: 2px solid grey; width: 3px; height: 3px; @@ -1267,7 +1283,7 @@ QScrollBar::sub-line:horizontal { right: 20px; } -QScrollBar:left-arrow:horizontal, QScrollBar::right-arrow:horizontal { +QScrollBar::left-arrow:horizontal, QScrollBar::right-arrow:horizontal { width: 3px; height: 3px; background: pink; @@ -1849,3 +1865,6 @@ QTableView::indicator:unchecked { * { widget-animation-duration: 100 } //! [162] +//! [163] +QLineEdit { placeholder-text-color: #800000ff } /* semi-transparent blue */ +//! [163] diff --git a/src/widgets/doc/snippets/code/src_gui_dialogs_qfiledialog.cpp b/src/widgets/doc/snippets/code/src_gui_dialogs_qfiledialog.cpp index dbf776cf70..197c23f247 100644 --- a/src/widgets/doc/snippets/code/src_gui_dialogs_qfiledialog.cpp +++ b/src/widgets/doc/snippets/code/src_gui_dialogs_qfiledialog.cpp @@ -110,5 +110,7 @@ QFileDialog::getOpenFileContent("Images (*.png *.xpm *.jpg)", fileContentReady) //! [16] QByteArray imageData; // obtained from e.g. QImage::save() -QFileDialog::saveFile("myimage.png", imageData); +QFileDialog::saveFileContent(imageData, "myimage.png"); // with filename hint +// OR +QFileDialog::saveFileContent(imageData); // no filename hint //! [16] diff --git a/src/widgets/doc/snippets/code/src_gui_dialogs_qmessagebox.cpp b/src/widgets/doc/snippets/code/src_gui_dialogs_qmessagebox.cpp index 014a9dfeb0..ebc07025ec 100644 --- a/src/widgets/doc/snippets/code/src_gui_dialogs_qmessagebox.cpp +++ b/src/widgets/doc/snippets/code/src_gui_dialogs_qmessagebox.cpp @@ -11,23 +11,6 @@ int ret = QMessageBox::warning(this, tr("My Application"), //! [0] -//! [1] -QMessageBox msgBox; -msgBox.setStandardButtons(QMessageBox::Yes | QMessageBox::No); -switch (msgBox.exec()) { -case QMessageBox::Yes: - // yes was clicked - break; -case QMessageBox::No: - // no was clicked - break; -default: - // should never be reached - break; -} -//! [1] - - //! [2] QMessageBox msgBox; QPushButton *connectButton = msgBox.addButton(tr("Connect"), QMessageBox::ActionRole); @@ -100,12 +83,3 @@ switch (ret) { break; } //! [7] - -//! [9] -QMessageBox msgBox(this); -msgBox.setText(tr("The document has been modified.\n" - "Do you want to save your changes?")); -msgBox.setStandardButtons(QMessageBox::Save | QMessageBox::Discard - | QMessageBox::Cancel); -msgBox.setDefaultButton(QMessageBox::Save); -//! [9] diff --git a/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsgridlayout.cpp b/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsgridlayout.cpp index 7c55e1c4c9..3b46c54bad 100644 --- a/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsgridlayout.cpp +++ b/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsgridlayout.cpp @@ -6,11 +6,10 @@ QGraphicsScene scene; QGraphicsWidget *textEdit = scene.addWidget(new QTextEdit); QGraphicsWidget *pushButton = scene.addWidget(new QPushButton); -QGraphicsGridLayout *layout = new QGraphicsGridLayout; -layout->addItem(textEdit, 0, 0); -layout->addItem(pushButton, 0, 1); - QGraphicsWidget *form = new QGraphicsWidget; -form->setLayout(layout); scene.addItem(form); + +QGraphicsGridLayout *layout = new QGraphicsGridLayout(form); +layout->addItem(textEdit, 0, 0); +layout->addItem(pushButton, 0, 1); //! [0] diff --git a/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp b/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp index e9e8b95847..bcf675d8af 100644 --- a/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp +++ b/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp @@ -71,24 +71,6 @@ rect.deviceTransform(view->viewportTransform()).inverted().map(QPointF(100, 100) //! [5] -//! [6] -// Rotate an item 45 degrees around (0, 0). -item->rotate(45); - -// Rotate an item 45 degrees around (x, y). -item->setTransform(QTransform().translate(x, y).rotate(45).translate(-x, -y)); -//! [6] - - -//! [7] -// Scale an item by 3x2 from its origin -item->scale(3, 2); - -// Scale an item by 3x2 from (x, y) -item->setTransform(QTransform().translate(x, y).scale(3, 2).translate(-x, -y)); -//! [7] - - //! [8] QRectF CircleItem::boundingRect() const { @@ -223,19 +205,3 @@ QTransform xform = item->deviceTransform(view->viewportTransform()); QRect deviceRect = xform.mapRect(rect).toAlignedRect(); view->viewport()->scroll(dx, dy, deviceRect); //! [19] - -//! [20] -item->setTransform(QTransform().rotate(angle), true); -//! [20] - -//! [21] -setTransform(QTransform::fromScale(sx, sy), true); -//! [21] - -//! [22] -setTransform(QTransform().shear(sh, sv), true); -//! [22] - -//! [23] -setTransform(QTransform::fromTranslate(dx, dy), true); -//! [23] diff --git a/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicslinearlayout.cpp b/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicslinearlayout.cpp index 8632fa9037..cc3b1678d0 100644 --- a/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicslinearlayout.cpp +++ b/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicslinearlayout.cpp @@ -6,11 +6,10 @@ QGraphicsScene scene; QGraphicsWidget *textEdit = scene.addWidget(new QTextEdit); QGraphicsWidget *pushButton = scene.addWidget(new QPushButton); -QGraphicsLinearLayout *layout = new QGraphicsLinearLayout; -layout->addItem(textEdit); -layout->addItem(pushButton); - QGraphicsWidget *form = new QGraphicsWidget; -form->setLayout(layout); scene.addItem(form); + +QGraphicsLinearLayout *layout = new QGraphicsLinearLayout(form); +layout->addItem(textEdit); +layout->addItem(pushButton); //! [0] diff --git a/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsproxywidget.cpp b/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsproxywidget.cpp index b57a6f0e83..b8cb7b493c 100644 --- a/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsproxywidget.cpp +++ b/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsproxywidget.cpp @@ -23,9 +23,8 @@ QGroupBox *groupBox = new QGroupBox("Contact Details"); QLabel *numberLabel = new QLabel("Telephone number"); QLineEdit *numberEdit = new QLineEdit; -QFormLayout *layout = new QFormLayout; +QFormLayout *layout = new QFormLayout(groupBox); layout->addRow(numberLabel, numberEdit); -groupBox->setLayout(layout); QGraphicsScene scene; QGraphicsProxyWidget *proxy = scene.addWidget(groupBox); diff --git a/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsview.cpp b/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsview.cpp index 9f48c4e06b..0b757cf0a2 100644 --- a/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsview.cpp +++ b/src/widgets/doc/snippets/code/src_gui_graphicsview_qgraphicsview.cpp @@ -27,16 +27,6 @@ view.setCacheMode(QGraphicsView::CacheBackground); //! [2] -//! [3] -QGraphicsScene scene; -scene.addText("GraphicsView rotated clockwise"); - -QGraphicsView view(&scene); -view.rotate(90); // the text is rendered with a 90 degree clockwise rotation -view.show(); -//! [3] - - //! [4] QGraphicsScene scene; scene.addItem(... diff --git a/src/widgets/doc/snippets/code/src_gui_itemviews_qitemeditorfactory.cpp b/src/widgets/doc/snippets/code/src_gui_itemviews_qitemeditorfactory.cpp index d314c88fd9..1a311015c4 100644 --- a/src/widgets/doc/snippets/code/src_gui_itemviews_qitemeditorfactory.cpp +++ b/src/widgets/doc/snippets/code/src_gui_itemviews_qitemeditorfactory.cpp @@ -14,12 +14,16 @@ QItemEditorFactory *factory = new QItemEditorFactory; //! [1] +//! [setDefaultFactory] //! [2] QItemEditorFactory *editorFactory = new QItemEditorFactory; QItemEditorCreatorBase *creator = new QStandardItemEditorCreator<MyFancyDateTimeEdit>(); editorFactory->registerEditor(QMetaType::QDateTime, creator); //! [2] +QItemEditorFactory::setDefaultFactory(editorFactory); +//! [setDefaultFactory] + //! [3] Q_PROPERTY(QColor color READ color WRITE setColor USER true) diff --git a/src/widgets/doc/snippets/code/src_gui_kernel_qapplication.cpp b/src/widgets/doc/snippets/code/src_gui_kernel_qapplication.cpp index a31e720fb1..0d14b086cc 100644 --- a/src/widgets/doc/snippets/code/src_gui_kernel_qapplication.cpp +++ b/src/widgets/doc/snippets/code/src_gui_kernel_qapplication.cpp @@ -31,26 +31,6 @@ QApplication::setStyle(QStyleFactory::create("Fusion")); //! [1] -// ### fixme: Qt 6: Remove [2] -//! [2] -int main(int argc, char *argv[]) -{ - QApplication::setColorSpec(QApplication::ManyColor); - QApplication app(argc, argv); - ... - return app.exec(); -} -//! [2] - - -//! [3] -QSize MyWidget::sizeHint() const -{ - return QSize(80, 25); -} -//! [3] - - //! [4] void showAllHiddenTopLevelWidgets() { @@ -73,82 +53,8 @@ void updateAllWidgets() //! [5] -//! [6] -int main(int argc, char *argv[]) -{ - QApplication::setDesktopSettingsAware(false); - QApplication app(argc, argv); - ... - return app.exec(); -} -//! [6] - - //! [7] if ((startPos - currentPos).manhattanLength() >= QApplication::startDragDistance()) startTheDrag(); //! [7] - - -//! [8] -void MyApplication::commitData(QSessionManager& manager) -{ - if (manager.allowsInteraction()) { - int ret = QMessageBox::warning( - mainWindow, - tr("My Application"), - tr("Save changes to document?"), - QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel); - - switch (ret) { - case QMessageBox::Save: - manager.release(); - if (!saveDocument()) - manager.cancel(); - break; - case QMessageBox::Discard: - break; - case QMessageBox::Cancel: - default: - manager.cancel(); - } - } else { - // we did not get permission to interact, then - // do something reasonable instead - } -} -//! [8] - - -//! [9] -appname -session id -//! [9] - - -//! [10] -const QStringList commands = mySession.restartCommand(); -for (const QString &command : commands) - do_something(command); -//! [10] - - -//! [11] -const QStringList commands = mySession.discardCommand(); -for (const QString &command : commands) - do_something(command); -//! [11] - - -//! [12] -QWidget *widget = QApplication::widgetAt(x, y); -if (widget) - widget = widget->window(); -//! [12] - - -//! [13] -QWidget *widget = QApplication::widgetAt(point); -if (widget) - widget = widget->window(); -//! [13] diff --git a/src/widgets/doc/snippets/code/src_gui_kernel_qformlayout.cpp b/src/widgets/doc/snippets/code/src_gui_kernel_qformlayout.cpp index 67dc4556ae..cb90436462 100644 --- a/src/widgets/doc/snippets/code/src_gui_kernel_qformlayout.cpp +++ b/src/widgets/doc/snippets/code/src_gui_kernel_qformlayout.cpp @@ -1,16 +1,19 @@ // Copyright (C) 2016 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause +#include <QtCore/qpointer.h> + //! [0] -QFormLayout *formLayout = new QFormLayout; +QFormLayout *formLayout = new QFormLayout(this); formLayout->addRow(tr("&Name:"), nameLineEdit); formLayout->addRow(tr("&Email:"), emailLineEdit); formLayout->addRow(tr("&Age:"), ageSpinBox); -setLayout(formLayout); //! [0] //! [1] +QGridLayout *gridLayout = new QGridLayout(this); + nameLabel = new QLabel(tr("&Name:")); nameLabel->setBuddy(nameLineEdit); @@ -20,14 +23,12 @@ emailLabel->setBuddy(emailLineEdit); ageLabel = new QLabel(tr("&Name:")); ageLabel->setBuddy(ageSpinBox); -QGridLayout *gridLayout = new QGridLayout; gridLayout->addWidget(nameLabel, 0, 0); gridLayout->addWidget(nameLineEdit, 0, 1); gridLayout->addWidget(emailLabel, 1, 0); gridLayout->addWidget(emailLineEdit, 1, 1); gridLayout->addWidget(ageLabel, 2, 0); gridLayout->addWidget(ageSpinBox, 2, 1); -setLayout(gridLayout); //! [1] diff --git a/src/widgets/doc/snippets/code/src_gui_kernel_qwidget.cpp b/src/widgets/doc/snippets/code/src_gui_kernel_qwidget.cpp index 8f0c296873..21703c7395 100644 --- a/src/widgets/doc/snippets/code/src_gui_kernel_qwidget.cpp +++ b/src/widgets/doc/snippets/code/src_gui_kernel_qwidget.cpp @@ -22,19 +22,6 @@ aWidget->window()->setWindowTitle("New Window Title"); //! [3] -//! [4] -QFont font("Helvetica", 12, QFont::Bold); -setFont(font); -//! [4] - - -//! [5] -QFont font; -font.setBold(false); -setFont(font); -//! [5] - - //! [6] setCursor(Qt::IBeamCursor); //! [6] @@ -61,6 +48,11 @@ setTabOrder(c, d); // a to b to c to d //! [9] +//! [9.list] +setTabOrder({a, b, c, d}); // a to b to c to d +//! [9.list] + + //! [10] // WRONG setTabOrder(c, d); // c to d diff --git a/src/widgets/doc/snippets/code/src_gui_widgets_qgroupbox.cpp b/src/widgets/doc/snippets/code/src_gui_widgets_qgroupbox.cpp index 1298147de1..cff537c862 100644 --- a/src/widgets/doc/snippets/code/src_gui_widgets_qgroupbox.cpp +++ b/src/widgets/doc/snippets/code/src_gui_widgets_qgroupbox.cpp @@ -4,3 +4,20 @@ //! [0] g->setTitle("&User information"); //! [0] + +//! [Set up QGroupBox with layout] +QGroupBox *groupBox = new QGroupBox(tr("Group Box with Layout")); + +QRadioButton *radio1 = new QRadioButton(tr("&Radio button 1")); +QRadioButton *radio2 = new QRadioButton(tr("R&adio button 2")); +QRadioButton *radio3 = new QRadioButton(tr("Ra&dio button 3")); + +radio1->setChecked(true); + +QVBoxLayout *vbox = new QVBoxLayout; +vbox->addWidget(radio1); +vbox->addWidget(radio2); +vbox->addWidget(radio3); +vbox->addStretch(1); +groupBox->setLayout(vbox); +//! [Set up QGroupBox with layout] diff --git a/src/widgets/doc/snippets/code/src_gui_widgets_qmenu.cpp b/src/widgets/doc/snippets/code/src_gui_widgets_qmenu.cpp index 70fb1fe62d..eb0897d5c5 100644 --- a/src/widgets/doc/snippets/code/src_gui_widgets_qmenu.cpp +++ b/src/widgets/doc/snippets/code/src_gui_widgets_qmenu.cpp @@ -12,7 +12,7 @@ exec(somewidget.mapToGlobal(QPoint(0,0))); //! [2] -exec(e->globalPos()); +exec(e->globalPosition().toPoint()); //! [2] @@ -27,14 +27,14 @@ exec(somewidget.mapToGlobal(QPoint(0, 0))); //! [5] -exec(e->globalPos()); +exec(e->globalPosition().toPoint()); //! [5] //! [6] QMenu menu; QAction *at = actions[0]; // Assumes actions is not empty -for (QAction *a : qAsConst(actions)) +for (QAction *a : std::as_const(actions)) menu.addAction(a); menu.exec(pos, at); //! [6] diff --git a/src/widgets/doc/snippets/code/src_gui_widgets_qspinbox.cpp b/src/widgets/doc/snippets/code/src_gui_widgets_qspinbox.cpp index d660d605a1..ec4b5bf27f 100644 --- a/src/widgets/doc/snippets/code/src_gui_widgets_qspinbox.cpp +++ b/src/widgets/doc/snippets/code/src_gui_widgets_qspinbox.cpp @@ -41,3 +41,23 @@ setRange(minimum, maximum); setMinimum(minimum); setMaximum(maximum); //! [7] + +//! [8] +int IconSizeSpinBox::valueFromText(const QString &text) const +{ + static const QRegularExpression regExp(tr("(\\d+)(\\s*[xx]\\s*\\d+)?")); + Q_ASSERT(regExp.isValid()); + + const QRegularExpressionMatch match = regExp.match(text); + if (match.isValid()) + return match.captured(1).toInt(); + return 0; +} +//! [8] + +//! [9] +QString IconSizeSpinBox::textFromValue(int value) const +{ + return tr("%1 x %1").arg(value); +} +//! [9] diff --git a/src/widgets/doc/snippets/code/src_gui_widgets_qstatusbar.cpp b/src/widgets/doc/snippets/code/src_gui_widgets_qstatusbar.cpp index 8f5db27c9f..e05d27353a 100644 --- a/src/widgets/doc/snippets/code/src_gui_widgets_qstatusbar.cpp +++ b/src/widgets/doc/snippets/code/src_gui_widgets_qstatusbar.cpp @@ -4,3 +4,11 @@ //! [0] statusBar()->addWidget(new MyReadWriteIndication); //! [0] + +//! [1] +statusBar()->showMessage(tr("Ready")); +//! [1] + +//! [2] +statusBar()->showMessage(tr("Ready"), 2000); +//! [2] diff --git a/src/widgets/doc/snippets/code/src_widgets_util_qscroller.cpp b/src/widgets/doc/snippets/code/src_widgets_util_qscroller.cpp index 03e2a710a4..36e77bf371 100644 --- a/src/widgets/doc/snippets/code/src_widgets_util_qscroller.cpp +++ b/src/widgets/doc/snippets/code/src_widgets_util_qscroller.cpp @@ -1,5 +1,5 @@ // Copyright (C) 2018 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] QWidget *w = ...; diff --git a/src/widgets/doc/snippets/code/src_widgets_widgets_qmainwindow.cpp b/src/widgets/doc/snippets/code/src_widgets_widgets_qmainwindow.cpp index f9f9c6c338..9734f2fed0 100644 --- a/src/widgets/doc/snippets/code/src_widgets_widgets_qmainwindow.cpp +++ b/src/widgets/doc/snippets/code/src_widgets_widgets_qmainwindow.cpp @@ -1,5 +1,5 @@ // Copyright (C) 2018 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] void MainWindow::createMenus() diff --git a/src/widgets/doc/snippets/customviewstyle/CMakeLists.txt b/src/widgets/doc/snippets/customviewstyle/CMakeLists.txt index 37173b20fe..f37de58edc 100644 --- a/src/widgets/doc/snippets/customviewstyle/CMakeLists.txt +++ b/src/widgets/doc/snippets/customviewstyle/CMakeLists.txt @@ -1,5 +1,5 @@ # Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0 +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause add_library(widgets_customviewstyle_snippets OBJECT ../customstyle/customstyle.h @@ -12,3 +12,5 @@ target_link_libraries(widgets_customviewstyle_snippets PRIVATE Qt::Gui Qt::Widgets ) + +set_target_properties(widgets_customviewstyle_snippets PROPERTIES UNITY_BUILD OFF) diff --git a/src/widgets/doc/snippets/dialogs/dialogs.cpp b/src/widgets/doc/snippets/dialogs/dialogs.cpp index 441ca8f795..0990d7d7c4 100644 --- a/src/widgets/doc/snippets/dialogs/dialogs.cpp +++ b/src/widgets/doc/snippets/dialogs/dialogs.cpp @@ -227,6 +227,35 @@ void Operation::cancel() } //! [6] +void extension() +{ + using ExtendedControls = QWidget; + QPushButton *findButton; + QPushButton *moreButton; + QWidget *extension; + QVBoxLayout *mainLayout; + +//! [extension] + mainLayout->setSizeConstraint(QLayout::SetFixedSize); + + findButton = new QPushButton(tr("&Find")); + moreButton = new QPushButton(tr("&More...")); + moreButton->setCheckable(true); + + extension = new ExtendedControls; + mainLayout->addWidget(extension); + extension->hide(); + + connect(moreButton, &QAbstractButton::toggled, extension, &QWidget::setVisible); +//! [extension] + +//! [buttonbox] + QDialogButtonBox *buttonBox = new QDialogButtonBox(Qt::Vertical); + buttonBox->addButton(findButton, QDialogButtonBox::ActionRole); + buttonBox->addButton(moreButton, QDialogButtonBox::ActionRole); +//! [buttonbox] +} + int main() { } diff --git a/src/widgets/doc/snippets/filedialogurls/CMakeLists.txt b/src/widgets/doc/snippets/filedialogurls/CMakeLists.txt index 8ee22ba8c4..4c64ff3288 100644 --- a/src/widgets/doc/snippets/filedialogurls/CMakeLists.txt +++ b/src/widgets/doc/snippets/filedialogurls/CMakeLists.txt @@ -1,5 +1,5 @@ # Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0 +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause add_library(widgets_filedialogurl_snippets OBJECT filedialogurls.cpp diff --git a/src/widgets/doc/snippets/graphicssceneadditem/CMakeLists.txt b/src/widgets/doc/snippets/graphicssceneadditem/CMakeLists.txt index fa5856d7ab..a2d391d629 100644 --- a/src/widgets/doc/snippets/graphicssceneadditem/CMakeLists.txt +++ b/src/widgets/doc/snippets/graphicssceneadditem/CMakeLists.txt @@ -1,5 +1,5 @@ # Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0 +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause add_library(widgets_graphicssceneadditem_snippets OBJECT graphicssceneadditemsnippet.cpp diff --git a/src/widgets/doc/snippets/graphicsview/CMakeLists.txt b/src/widgets/doc/snippets/graphicsview/CMakeLists.txt index 00e18430b8..e395eda045 100644 --- a/src/widgets/doc/snippets/graphicsview/CMakeLists.txt +++ b/src/widgets/doc/snippets/graphicsview/CMakeLists.txt @@ -1,5 +1,5 @@ # Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0 +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause add_library(widgets_graphicsview_snippets OBJECT graphicsview.cpp diff --git a/src/widgets/doc/snippets/mainwindowsnippet.cpp b/src/widgets/doc/snippets/mainwindowsnippet.cpp index f26b66f2cc..5608dc96ba 100644 --- a/src/widgets/doc/snippets/mainwindowsnippet.cpp +++ b/src/widgets/doc/snippets/mainwindowsnippet.cpp @@ -41,9 +41,8 @@ void MainWindow::createToolBars() void MainWindow::createDockWidgets() { QWidget *dockWidgetContents = new QWidget; - QVBoxLayout *layout = new QVBoxLayout; + QVBoxLayout *layout = new QVBoxLayout(dockWidgetContents); layout->addWidget(new QPushButton("My Button.")); - dockWidgetContents->setLayout(layout); //! [0] QDockWidget *dockWidget = new QDockWidget(tr("Dock Widget"), this); diff --git a/src/widgets/doc/snippets/mdiarea/CMakeLists.txt b/src/widgets/doc/snippets/mdiarea/CMakeLists.txt index 0eba91cfd3..3edb2d1b36 100644 --- a/src/widgets/doc/snippets/mdiarea/CMakeLists.txt +++ b/src/widgets/doc/snippets/mdiarea/CMakeLists.txt @@ -1,5 +1,5 @@ # Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0 +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause add_library(widgets_mdiarea_snippets OBJECT mdiareasnippets.cpp diff --git a/src/widgets/doc/snippets/myscrollarea/CMakeLists.txt b/src/widgets/doc/snippets/myscrollarea/CMakeLists.txt index dc358f7684..9e7e14dc8d 100644 --- a/src/widgets/doc/snippets/myscrollarea/CMakeLists.txt +++ b/src/widgets/doc/snippets/myscrollarea/CMakeLists.txt @@ -1,5 +1,5 @@ # Copyright (C) 2022 The Qt Company Ltd. -# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0 +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause add_library(widgets_myscrollarea_snippets OBJECT myscrollarea.cpp diff --git a/src/widgets/doc/snippets/qitemdelegate/CMakeLists.txt b/src/widgets/doc/snippets/qitemdelegate/CMakeLists.txt new file mode 100644 index 0000000000..9aad7026c7 --- /dev/null +++ b/src/widgets/doc/snippets/qitemdelegate/CMakeLists.txt @@ -0,0 +1,12 @@ +# Copyright (C) 2023 The Qt Company Ltd. +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +add_library(widgets_qitemdelegate_snippets OBJECT + spinbox-delegate.cpp +) + +target_link_libraries(widgets_qitemdelegate_snippets PRIVATE + Qt::Core + Qt::Gui + Qt::Widgets +) diff --git a/src/widgets/doc/snippets/qitemdelegate/spinbox-delegate.cpp b/src/widgets/doc/snippets/qitemdelegate/spinbox-delegate.cpp new file mode 100644 index 0000000000..efe8a16733 --- /dev/null +++ b/src/widgets/doc/snippets/qitemdelegate/spinbox-delegate.cpp @@ -0,0 +1,79 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#include <QStyledItemDelegate> +#include <QSpinBox> + +//! [declaration] +class SpinBoxDelegate : public QStyledItemDelegate +{ + Q_OBJECT + +public: + SpinBoxDelegate(QObject *parent = nullptr); + + QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &option, + const QModelIndex &index) const override; + + void setEditorData(QWidget *editor, const QModelIndex &index) const override; + void setModelData(QWidget *editor, QAbstractItemModel *model, + const QModelIndex &index) const override; + + void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, + const QModelIndex &index) const override; +}; +//! [declaration] + +//! [constructor] +SpinBoxDelegate::SpinBoxDelegate(QObject *parent) + : QStyledItemDelegate(parent) +{ +} +//! [constructor] + +//! [createEditor] +QWidget *SpinBoxDelegate::createEditor(QWidget *parent, + const QStyleOptionViewItem &/* option */, + const QModelIndex &/* index */) const +{ + QSpinBox *editor = new QSpinBox(parent); + editor->setFrame(false); + editor->setMinimum(0); + editor->setMaximum(100); + + return editor; +} +//! [createEditor] + +//! [setEditorData] +void SpinBoxDelegate::setEditorData(QWidget *editor, + const QModelIndex &index) const +{ + int value = index.model()->data(index, Qt::EditRole).toInt(); + + QSpinBox *spinBox = static_cast<QSpinBox*>(editor); + spinBox->setValue(value); +} +//! [setEditorData] + +//! [setModelData] +void SpinBoxDelegate::setModelData(QWidget *editor, QAbstractItemModel *model, + const QModelIndex &index) const +{ + QSpinBox *spinBox = static_cast<QSpinBox*>(editor); + spinBox->interpretText(); + int value = spinBox->value(); + + model->setData(index, value, Qt::EditRole); +} +//! [setModelData] + +//! [updateEditorGeometry] +void SpinBoxDelegate::updateEditorGeometry(QWidget *editor, + const QStyleOptionViewItem &option, + const QModelIndex &/* index */) const +{ + editor->setGeometry(option.rect); +} +//! [updateEditorGeometry] + diff --git a/src/widgets/doc/snippets/qlistview-dnd/model.cpp b/src/widgets/doc/snippets/qlistview-dnd/model.cpp index 045d1e81f9..be2189d1be 100644 --- a/src/widgets/doc/snippets/qlistview-dnd/model.cpp +++ b/src/widgets/doc/snippets/qlistview-dnd/model.cpp @@ -74,7 +74,7 @@ bool DragDropListModel::dropMimeData(const QMimeData *data, //! [6] insertRows(beginRow, rows, QModelIndex()); - for (const QString &text : qAsConst(newItems)) { + for (const QString &text : std::as_const(newItems)) { QModelIndex idx = index(beginRow, 0, QModelIndex()); setData(idx, text); beginRow++; diff --git a/src/widgets/doc/snippets/qrhiwidget/rhiwidgetintro.cpp b/src/widgets/doc/snippets/qrhiwidget/rhiwidgetintro.cpp new file mode 100644 index 0000000000..1cd583e294 --- /dev/null +++ b/src/widgets/doc/snippets/qrhiwidget/rhiwidgetintro.cpp @@ -0,0 +1,109 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#include <QRhiWidget> +#include <QFile> +#include <rhi/qrhi.h> + +//![0] +class ExampleRhiWidget : public QRhiWidget +{ +public: + ExampleRhiWidget(QWidget *parent = nullptr) : QRhiWidget(parent) { } + void initialize(QRhiCommandBuffer *cb) override; + void render(QRhiCommandBuffer *cb) override; +private: + QRhi *m_rhi = nullptr; + std::unique_ptr<QRhiBuffer> m_vbuf; + std::unique_ptr<QRhiBuffer> m_ubuf; + std::unique_ptr<QRhiShaderResourceBindings> m_srb; + std::unique_ptr<QRhiGraphicsPipeline> m_pipeline; + QMatrix4x4 m_viewProjection; + float m_rotation = 0.0f; +}; + +float vertexData[] = { + 0.0f, 0.5f, 1.0f, 0.0f, 0.0f, + -0.5f, -0.5f, 0.0f, 1.0f, 0.0f, + 0.5f, -0.5f, 0.0f, 0.0f, 1.0f, +}; + +QShader getShader(const QString &name) +{ + QFile f(name); + return f.open(QIODevice::ReadOnly) ? QShader::fromSerialized(f.readAll()) : QShader(); +} + +void ExampleRhiWidget::initialize(QRhiCommandBuffer *cb) +{ + if (m_rhi != rhi()) { + m_pipeline.reset(); + m_rhi = rhi(); + } + + if (!m_pipeline) { + m_vbuf.reset(m_rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData))); + m_vbuf->create(); + + m_ubuf.reset(m_rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 64)); + m_ubuf->create(); + + m_srb.reset(m_rhi->newShaderResourceBindings()); + m_srb->setBindings({ + QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage, m_ubuf.get()), + }); + m_srb->create(); + + m_pipeline.reset(m_rhi->newGraphicsPipeline()); + m_pipeline->setShaderStages({ + { QRhiShaderStage::Vertex, getShader(QLatin1String(":/shader_assets/color.vert.qsb")) }, + { QRhiShaderStage::Fragment, getShader(QLatin1String(":/shader_assets/color.frag.qsb")) } + }); + QRhiVertexInputLayout inputLayout; + inputLayout.setBindings({ + { 5 * sizeof(float) } + }); + inputLayout.setAttributes({ + { 0, 0, QRhiVertexInputAttribute::Float2, 0 }, + { 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) } + }); + m_pipeline->setVertexInputLayout(inputLayout); + m_pipeline->setShaderResourceBindings(m_srb.get()); + m_pipeline->setRenderPassDescriptor(renderTarget()->renderPassDescriptor()); + m_pipeline->create(); + + QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch(); + resourceUpdates->uploadStaticBuffer(m_vbuf.get(), vertexData); + cb->resourceUpdate(resourceUpdates); + } + + const QSize outputSize = colorTexture()->pixelSize(); + m_viewProjection = m_rhi->clipSpaceCorrMatrix(); + m_viewProjection.perspective(45.0f, outputSize.width() / (float) outputSize.height(), 0.01f, 1000.0f); + m_viewProjection.translate(0, 0, -4); +} + +void ExampleRhiWidget::render(QRhiCommandBuffer *cb) +{ + QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch(); + m_rotation += 1.0f; + QMatrix4x4 modelViewProjection = m_viewProjection; + modelViewProjection.rotate(m_rotation, 0, 1, 0); + resourceUpdates->updateDynamicBuffer(m_ubuf.get(), 0, 64, modelViewProjection.constData()); + + const QColor clearColor = QColor::fromRgbF(0.4f, 0.7f, 0.0f, 1.0f); + cb->beginPass(renderTarget(), clearColor, { 1.0f, 0 }, resourceUpdates); + + cb->setGraphicsPipeline(m_pipeline.get()); + const QSize outputSize = colorTexture()->pixelSize(); + cb->setViewport(QRhiViewport(0, 0, outputSize.width(), outputSize.height())); + cb->setShaderResources(); + const QRhiCommandBuffer::VertexInput vbufBinding(m_vbuf.get(), 0); + cb->setVertexInput(0, 1, &vbufBinding); + cb->draw(3); + + cb->endPass(); + + update(); +} +//![0] diff --git a/src/widgets/doc/snippets/qrhiwidget/rhiwidgetintro.frag b/src/widgets/doc/snippets/qrhiwidget/rhiwidgetintro.frag new file mode 100644 index 0000000000..d86bcf7386 --- /dev/null +++ b/src/widgets/doc/snippets/qrhiwidget/rhiwidgetintro.frag @@ -0,0 +1,10 @@ +//![0] +#version 440 +layout(location = 0) in vec3 v_color; +layout(location = 0) out vec4 fragColor; + +void main() +{ + fragColor = vec4(v_color, 1.0); +} +//![0] diff --git a/src/widgets/doc/snippets/qrhiwidget/rhiwidgetintro.vert b/src/widgets/doc/snippets/qrhiwidget/rhiwidgetintro.vert new file mode 100644 index 0000000000..610df304b1 --- /dev/null +++ b/src/widgets/doc/snippets/qrhiwidget/rhiwidgetintro.vert @@ -0,0 +1,15 @@ +//![0] +#version 440 +layout(location = 0) in vec4 position; +layout(location = 1) in vec3 color; +layout(location = 0) out vec3 v_color; +layout(std140, binding = 0) uniform buf { + mat4 mvp; +}; + +void main() +{ + v_color = color; + gl_Position = mvp * position; +} +//![0] diff --git a/src/widgets/doc/snippets/splitter/splitter.cpp b/src/widgets/doc/snippets/splitter/splitter.cpp index c3a36ba4c0..662ac30eda 100644 --- a/src/widgets/doc/snippets/splitter/splitter.cpp +++ b/src/widgets/doc/snippets/splitter/splitter.cpp @@ -37,11 +37,5 @@ int main() //! [2] } -//! [3] - QListIterator<int> it(splitter->sizes()); - while (it.hasNext()) - processSize(it.next()); -//! [3] - return 0; } diff --git a/src/widgets/doc/snippets/styles/qcustompixmapstyle.cpp b/src/widgets/doc/snippets/styles/qcustompixmapstyle.cpp index 8a3a8555eb..67dedb147c 100644 --- a/src/widgets/doc/snippets/styles/qcustompixmapstyle.cpp +++ b/src/widgets/doc/snippets/styles/qcustompixmapstyle.cpp @@ -1,5 +1,5 @@ // Copyright (C) 2016 The Qt Company Ltd. -// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause #include "qcustompixmapstyle.h" diff --git a/src/widgets/doc/snippets/tooltips/main.cpp b/src/widgets/doc/snippets/tooltips/main.cpp new file mode 100644 index 0000000000..94cc71f711 --- /dev/null +++ b/src/widgets/doc/snippets/tooltips/main.cpp @@ -0,0 +1,74 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#include <QtWidgets> + +using SearchBar = QWidget; +using Element = QWidget; + +class Window : public QMainWindow +{ +public: + Window(QWidget *parent = nullptr); + +protected: + bool event(QEvent *event) override; + +private: + Element *elementAt(QPoint pos) const { + return nullptr; + } + + QToolBar *fileToolBar; + QMenu *fileMenu; + + SearchBar *searchBar; +}; + + +Window::Window(QWidget *parent) + : QMainWindow(parent) +{ +//! [action_tooltip] + QAction *openAction = new QAction(tr("&Open...")); + openAction->setToolTip(tr("Open an existing file")); + + fileMenu = menuBar()->addMenu(tr("&File")); + fileToolBar = addToolBar(tr("&File")); + + fileMenu->addAction(openAction); + fileToolBar->addAction(openAction); +//! [action_tooltip] + +//! [static_tooltip] + searchBar = new SearchBar; + searchBar->setToolTip(tr("Search in the current document")); +//! [static_tooltip] + + fileToolBar->addWidget(searchBar); +} + +//! [dynamic_tooltip] +bool Window::event(QEvent *event) +{ + if (event->type() == QEvent::ToolTip) { + QHelpEvent *helpEvent = static_cast<QHelpEvent *>(event); + if (Element *element = elementAt(helpEvent->pos())) { + QToolTip::showText(helpEvent->globalPos(), element->toolTip()); + } else { + QToolTip::hideText(); + event->ignore(); + } + + return true; + } + return QWidget::event(event); +} +//! [dynamic_tooltip] + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + Window w; + return 0; +} diff --git a/src/widgets/doc/snippets/updating-selections/window.cpp b/src/widgets/doc/snippets/updating-selections/window.cpp index b47e15e084..b965b81008 100644 --- a/src/widgets/doc/snippets/updating-selections/window.cpp +++ b/src/widgets/doc/snippets/updating-selections/window.cpp @@ -42,7 +42,7 @@ void MainWindow::updateSelection(const QItemSelection &selected, { QModelIndexList items = selected.indexes(); - for (const QModelIndex &index : qAsConst(items)) { + for (const QModelIndex &index : std::as_const(items)) { QString text = QString("(%1,%2)").arg(index.row()).arg(index.column()); model->setData(index, text); //! [0] //! [1] @@ -52,7 +52,7 @@ void MainWindow::updateSelection(const QItemSelection &selected, //! [2] items = deselected.indexes(); - for (const QModelIndex &index : qAsConst(items)) { + for (const QModelIndex &index : std::as_const(items)) { model->setData(index, QString()); } //! [2] diff --git a/src/widgets/doc/src/cmake-macros.qdoc b/src/widgets/doc/src/cmake-macros.qdoc index 4e947694f8..13bdcca67b 100644 --- a/src/widgets/doc/src/cmake-macros.qdoc +++ b/src/widgets/doc/src/cmake-macros.qdoc @@ -2,11 +2,11 @@ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! -\page qt_wrap_ui.html +\page qt-wrap-ui.html \ingroup cmake-macros-qtwidgets \title qt_wrap_ui -\target qt6_wrap_ui +\keyword qt6_wrap_ui \summary {Creates sources for .ui files.} diff --git a/src/widgets/doc/src/model-view-programming.qdoc b/src/widgets/doc/src/model-view-programming.qdoc index 5c09fd0445..5461619a4d 100644 --- a/src/widgets/doc/src/model-view-programming.qdoc +++ b/src/widgets/doc/src/model-view-programming.qdoc @@ -686,12 +686,8 @@ implementations of these functions. Editors for delegates can be implemented either by using widgets to manage - the editing process or by handling events directly. - The first approach is covered later in this section, and it is also - shown in the \l{Spin Box Delegate Example}{Spin Box Delegate} example. - - The \l{Pixelator Example}{Pixelator} example shows how to create a - custom delegate that performs specialized rendering for a table view. + the editing process or by handling events directly. The first approach is + covered later in this section. \section2 Using an existing delegate @@ -721,13 +717,15 @@ data entry. We construct a table view to display the contents of the model, and this will use the custom delegate for editing. - \image spinboxdelegate-example.png + \image spinboxdelegate-example.webp We subclass the delegate from \l QStyledItemDelegate because we do not want to write custom display functions. However, we must still provide functions to manage the editor widget: - \snippet itemviews/spinboxdelegate/delegate.h 0 + \snippet qitemdelegate/spinbox-delegate.cpp declaration + \codeline + \snippet qitemdelegate/spinbox-delegate.cpp constructor Note that no editor widgets are set up when the delegate is constructed. We only construct an editor widget when it is needed. @@ -741,7 +739,7 @@ supplied with everything that the delegate needs to be able to set up a suitable widget: - \snippet itemviews/spinboxdelegate/delegate.cpp 1 + \snippet qitemdelegate/spinbox-delegate.cpp createEditor Note that we do not need to keep a pointer to the editor widget because the view takes responsibility for destroying it when it is no longer @@ -765,7 +763,7 @@ \l{Qt::ItemDataRole}{display role}, and set the value in the spin box accordingly. - \snippet itemviews/spinboxdelegate/delegate.cpp 2 + \snippet qitemdelegate/spinbox-delegate.cpp setEditorData In this example, we know that the editor widget is a spin box, but we could have provided different editors for different types of data in @@ -778,7 +776,7 @@ asks the delegate to store the edited value in the model by calling the \l{QAbstractItemDelegate::setModelData()}{setModelData()} function. - \snippet itemviews/spinboxdelegate/delegate.cpp 3 + \snippet qitemdelegate/spinbox-delegate.cpp setModelData Since the view manages the editor widgets for the delegate, we only need to update the model with the contents of the editor supplied. @@ -789,8 +787,8 @@ finished editing by emitting the \l{QAbstractItemDelegate::closeEditor()}{closeEditor()} signal. The view ensures that the editor widget is closed and destroyed. In - this example, we only provide simple editing facilities, so we need - never emit this signal. + this example, we only provide simple editing facilities, so we never + need to emit this signal. All the operations on data are performed through the interface provided by \l QAbstractItemModel. This makes the delegate mostly @@ -809,7 +807,7 @@ the view provides all the necessary geometry information inside a \l{QStyleOptionViewItem}{view option} object. - \snippet itemviews/spinboxdelegate/delegate.cpp 4 + \snippet qitemdelegate/spinbox-delegate.cpp updateEditorGeometry In this case, we just use the geometry information provided by the view option in the item rectangle. A delegate that renders items with @@ -1818,8 +1816,6 @@ Note that the model will typically need to provide implementations of the QAbstractItemModel::insertRows() and QAbstractItemModel::setData() functions. - \sa {itemviews/puzzle}{Item Views Puzzle Example} - \section1 Proxy Models In the model/view framework, items of data supplied by a single model can be shared @@ -2313,10 +2309,6 @@ \section1 Related Examples \list - \li \l{itemviews/dirview}{Dir View} - \li \l{itemviews/spinboxdelegate}{Spin Box Delegate} - \li \l{itemviews/pixelator}{Pixelator} \li \l{itemviews/simpletreemodel}{Simple Tree Model} - \li \l{itemviews/chart}{Chart} \endlist */ diff --git a/src/widgets/doc/src/modelview.qdoc b/src/widgets/doc/src/modelview.qdoc index 6ae62ce7cd..7dd7503d29 100644 --- a/src/widgets/doc/src/modelview.qdoc +++ b/src/widgets/doc/src/modelview.qdoc @@ -534,7 +534,7 @@ Other references to delegates in Qt Documentation: \list - \li \l{Spin Box Delegate Example} + \li \l{Delegate Classes} \li \l{QAbstractItemDelegate}{QAbstractItemDelegate Class Reference} \li \l{QSqlRelationalDelegate}{QSqlRelationalDelegate Class Reference} \li \l{QStyledItemDelegate}{QStyledItemDelegate Class Reference} @@ -827,11 +827,6 @@ \li QStandardItemModel \li Basic QDataWidgetMapper usage \row - \li Spin Box Delegate - \li QTableView - \li QStandardItemModel - \li Custom delegate that uses a spin box as a cell editor - \row \li Spreadsheet \li {2, 1} QTableView \li Custom delegates diff --git a/src/widgets/doc/src/qt6-changes.qdoc b/src/widgets/doc/src/qt6-changes.qdoc index a334fd948c..c4d757fe6d 100644 --- a/src/widgets/doc/src/qt6-changes.qdoc +++ b/src/widgets/doc/src/qt6-changes.qdoc @@ -5,7 +5,7 @@ \page widgets-changes-qt6.html \title Changes to Qt Widgets \ingroup changes-qt-5-to-6 - \brief Migrate Qt Widgets to Qt 6. + \brief Changes in Kernel classes, Widgets, ItemViews, and Utility Classes. Qt 6 is a result of the conscious effort to make the framework more efficient and easy to use. diff --git a/src/widgets/doc/src/qtwidgets-index.qdoc b/src/widgets/doc/src/qtwidgets-index.qdoc index cbdd4b2a44..3894467ccf 100644 --- a/src/widgets/doc/src/qtwidgets-index.qdoc +++ b/src/widgets/doc/src/qtwidgets-index.qdoc @@ -22,11 +22,10 @@ interfaces \image parent-child-widgets.png A parent widget containing various child widgets. The QWidget class provides the basic capability to render to the - screen, and to handle user input events. All UI elements that Qt - provides are either subclasses of QWidget, or are used in connection - with a QWidget subclass. Creating custom widgets is done by - subclassing QWidget or a suitable subclass and reimplementing the - virtual event handlers. + screen and to handle user input events. All UI elements that Qt + provides are either subclasses of QWidget or are used in connection + with a QWidget subclass. To create custom widgets, subclass QWidget or a + suitable subclass and reimplement the virtual event handlers. \list \li \l{Window and Dialog Widgets} @@ -49,8 +48,9 @@ interfaces \li \image macos-tabwidget.png \endtable - \l{Qt Style Sheets} are a powerful mechanism that allows you to customize the - appearance of widgets, in addition to what is already possible by subclassing QStyle. + \l{Qt Style Sheets} are a powerful mechanism that lets you customize + the appearance of widgets, in addition to what is already possible by + subclassing QStyle. \section1 Layouts @@ -67,7 +67,7 @@ interfaces \li \image qformlayout-with-6-children.png \endtable - \l {Qt Designer} is a powerful tool for interactively creating and + \l {Qt Widgets Designer} is a powerful tool for interactively creating and arranging widgets in layouts. @@ -115,6 +115,7 @@ interfaces \list \li \l{Qt Widgets Examples} \li \l{Layout Examples} + \li \l{Tools Examples} \endlist \section1 API Reference diff --git a/src/widgets/doc/src/widgets-and-layouts/focus.qdoc b/src/widgets/doc/src/widgets-and-layouts/focus.qdoc index 4214f025f1..b49fc89993 100644 --- a/src/widgets/doc/src/widgets-and-layouts/focus.qdoc +++ b/src/widgets/doc/src/widgets-and-layouts/focus.qdoc @@ -9,7 +9,7 @@ \keyword keyboard focus - Qt's widgets handle keyboard focus in the ways that have become + Qt's widgets handle keyboard focus in ways that have become customary in GUIs. The basic issue is that the user's key strokes can be directed at any @@ -22,7 +22,7 @@ \section1 Focus Motion - The customs which have evolved for directing keyboard focus to a + The customs that have evolved for directing keyboard focus to a particular widget are these: \list 1 @@ -54,7 +54,7 @@ You can customize the tab order using QWidget::setTabOrder(). (If you don't, \uicontrol Tab generally moves focus in the order of widget - construction.) Qt Designer provides a means of visually + construction.) \QD provides a means of visually changing the tab order. Since pressing \uicontrol Tab is so common, most widgets that can have focus @@ -63,7 +63,7 @@ handler that moves the focus. For example, in a data entry dialog, there might be a field that - is only necessary in one per cent of all cases. In such a dialog, + is only necessary in one percent of all cases. In such a dialog, \uicontrol Tab could skip this field, and the dialog could use one of these mechanisms: @@ -126,14 +126,17 @@ explicitly using focus accelerators such as those provided by QLabel::setBuddy(), QGroupBox, and QTabBar. - We advise supporting shortcut focus for all widgets that the user + Your application can support shortcut focus for all widgets that the user may want to jump to. For example, a tab dialog can have keyboard shortcuts for each of its pages, so the user can press e.g. \uicontrol - Alt+P to step to the \underline{P}rinting page. It is easy to - overdo this: there are only a few keys, and it's also important - to provide keyboard shortcuts for commands. \uicontrol Alt+P is also - used for Paste, Play, Print, and Print Here in the \l{Standard - Accelerator Keys} list, for example. + Alt+P to step to the \underline{P}rinting page. Keep in mind that it's easy + to overdo this, as there are only a few keys, and also important to provide + keyboard shortcuts for commands. Refer to the design guidelines for the + platform you target, for example Microsoft's \l + {https://learn.microsoft.com/en-us/previous-versions/windows/desktop/dnacc/guidelines-for-keyboard-user-interface-design} + {guidelines for keyboard user interface design} or Apple's \l + {https://developer.apple.com/design/human-interface-guidelines/inputs/focus-and-selection/} + {focus and selection} guidelines. \section2 The User Rotates the Mouse Wheel diff --git a/src/widgets/doc/src/widgets-and-layouts/gallery.qdoc b/src/widgets/doc/src/widgets-and-layouts/gallery.qdoc index 851461af1f..822cf1efff 100644 --- a/src/widgets/doc/src/widgets-and-layouts/gallery.qdoc +++ b/src/widgets/doc/src/widgets-and-layouts/gallery.qdoc @@ -15,21 +15,18 @@ integrating to the platform theme. Thus, the final appearance varies depending on the active theme. - \table - \row - \li The Windows style ("windows") is provided by QWindowsStyle. - \li \image windows-style.png Windows Style - \row - \li \image windows-vista-style.png Windows Vista Style - \li The Windows Vista style ("windowsvista") is provided by - QWindowsVistaStyle. - \row - \li The macOS style ("macOS") is provided by QMacStyle. - \li \image macos-style.png \macos Style - \row - \li \image fusion-style.png Fusion Style - \li The Fusion style ("fusion") is provided by QFusionStyle. - \endtable + \image windows-style.png Windows Style + \caption The Windows style ("windows") is provided by QWindowsStyle. + + \image windows-vista-style.png Windows Vista Style + \caption The Windows Vista style ("windowsvista") is provided by + QWindowsVistaStyle. + + \image macos-style.png \macos Style + \caption The macOS style ("macOS") is provided by QMacStyle. + + \image fusion-style.png Fusion Style + \caption The Fusion style ("fusion") is provided by QFusionStyle. The Styles example displays the following widgets: diff --git a/src/widgets/doc/src/widgets-and-layouts/layout.qdoc b/src/widgets/doc/src/widgets-and-layouts/layout.qdoc index 4a3ded1cb8..5f1d5a7ea9 100644 --- a/src/widgets/doc/src/widgets-and-layouts/layout.qdoc +++ b/src/widgets/doc/src/widgets-and-layouts/layout.qdoc @@ -48,8 +48,8 @@ Qt's layout classes were designed for hand-written C++ code, allowing measurements to be specified in pixels for simplicity, so they are easy to - understand and use. The code generated for forms created using Qt Designer also - uses the layout classes. Qt Designer is useful to use when experimenting with the + understand and use. The code generated for forms created using \QD also + uses the layout classes. \QD is useful to use when experimenting with the design of a form since it avoids the compile, link and run cycle usually involved in user interface development. @@ -263,8 +263,8 @@ \section1 How to Write A Custom Layout Manager An alternative to manual layout is to write your own layout manager by - subclassing QLayout. The \l{layouts/borderlayout}{Border Layout} and - \l{layouts/flowlayout}{Flow Layout} examples show how to do this. + subclassing QLayout. The + \l{layouts/flowlayout}{Flow Layout} example shows how to do this. Here we present an example in detail. The \c CardLayout class is inspired by the Java layout manager of the same name. It lays out the items (widgets diff --git a/src/widgets/doc/src/widgets-and-layouts/stylesheet.qdoc b/src/widgets/doc/src/widgets-and-layouts/stylesheet.qdoc index 9c5d8d5fe2..05000024e1 100644 --- a/src/widgets/doc/src/widgets-and-layouts/stylesheet.qdoc +++ b/src/widgets/doc/src/widgets-and-layouts/stylesheet.qdoc @@ -28,7 +28,7 @@ \list \li \l{Overview} \li \l{The Style Sheet Syntax} - \li \l{Qt Designer Integration} + \li \l{Qt Widgets Designer Integration} \li \l{Customizing Qt Widgets Using Style Sheets} \li \l{Qt Style Sheets Reference} \li \l{Qt Style Sheets Examples} @@ -75,7 +75,7 @@ consideration. Unlike palette fiddling, style sheets offer guarantees: If you set the background color of a QPushButton to be red, you can be assured that the button will have a red background - in all styles, on all platforms. In addition, Qt Designer + in all styles, on all platforms. In addition, \QD provides style sheet integration, making it easy to view the effects of a style sheet in different \l{QStyle}{widget styles}. @@ -85,22 +85,7 @@ buttons and check boxes to make them stand out. Using this technique, you can also achieve minor customizations that would normally require subclassing several style classes, such as - specifying a \l{QStyle::styleHint()}{style hint}. The - \l{widgets/stylesheet}{Style Sheet} example depicted below defines - two distinctive style sheets that you can try out and modify at - will. - - \table - \row \li \inlineimage stylesheet-pagefold.png - \row \li Pagefold theme running on Windows - \endtable - - \table - \row \li \inlineimage stylesheet-coffee-cleanlooks.png - \li \inlineimage stylesheet-pagefold-mac.png - \row \li Coffee theme running on Ubuntu Linux - \li Pagefold theme running on \macos - \endtable + specifying a \l{QStyle::styleHint()}{style hint}. When a style sheet is active, the QStyle returned by QWidget::style() is a wrapper "style sheet" style, \e not the platform-specific style. The @@ -115,7 +100,7 @@ /*! \page stylesheet-syntax.html \previouspage Qt Style Sheets - \nextpage Qt Designer Integration + \nextpage Qt Widgets Designer Integration \title The Style Sheet Syntax Qt Style Sheet terminology and syntactic rules are almost @@ -495,11 +480,20 @@ \snippet code/doc_src_stylesheet.cpp 96 When the widget-style font and palette propagation is enabled, font and - palette changes made through Qt Style Sheets will behave as though the - user had manually called the corresponding QWidget::setPalette() and + palette changes made through Qt Style Sheets will behave as if the user + had manually called the corresponding QWidget::setPalette() and QWidget::setFont() methods on all of the QWidgets targeted by the style - sheet. If this would have caused propagation in C++, it will cause - propagation in style sheets and vice versa. + sheet. + + \list + \li Changes made by a style sheet are propagated. + They are pushed to all widgets matching the style sheet once, at the time + the change is made. + \li Changes made by calling QWidget::setPalette() or QWidget::setFont() are + inherited. + They are inherited by all existing and future children, where the respective + brush or font hasn't been explicitly set. + \endlist \section1 Widgets Inside C++ Namespaces @@ -513,7 +507,7 @@ the QObject::className() returns <namespace>::<classname>. This conflicts with the syntax for \l{Sub-Controls}. To overcome this problem, when using the Type Selector for widgets inside namespaces, we must - replace the "::" with "--". For example, + replace the \c{::} with \c{--}. For example, \snippet code/doc_src_stylesheet.cpp 27 @@ -525,8 +519,8 @@ For example, \snippet code/doc_src_stylesheet.qdoc 28 - If the property references an enum declared with Q_ENUMS, you should - reference its constants by name, i.e., not their numeric value. + If the property references an enum declared with Q_ENUM, you should + reference its constants by name, not their numeric value. \note Use the qproperty syntax with care, as it modifies the widget that is being painted. Also, the qproperty syntax is evaluated only @@ -538,22 +532,22 @@ \page stylesheet-designer.html \previouspage The Style Sheet Syntax \nextpage Customizing Qt Widgets Using Style Sheets - \title Qt Designer Integration + \title Qt Widgets Designer Integration - Qt Designer{Qt Designer} is an excellent tool + \l{Qt Widgets Designer Manual}{\QD} is an excellent tool to preview style sheets. You can right-click on any widget in Designer and select \uicontrol{Change styleSheet...} to set the style sheet. \image designer-stylesheet-options.png - In Qt 4.2 and later, Qt Designer also includes a + In Qt 4.2 and later, \QD also includes a style sheet syntax highlighter and validator. The validator indicates if the syntax is valid or invalid, at the bottom left of the \uicontrol{Edit Style Sheet} dialog. \image designer-validator-highlighter.png - When you click \uicontrol{OK} or \uicontrol{Apply}, Qt Designer will automatically display + When you click \uicontrol{OK} or \uicontrol{Apply}, \QD will automatically display the widget with its new stylesheet. \image designer-stylesheet-usage.png @@ -561,7 +555,7 @@ /*! \page stylesheet-customizing.html - \previouspage Qt Designer Integration + \previouspage Qt Widgets Designer Integration \nextpage Qt Style Sheets Reference \title Customizing Qt Widgets Using Style Sheets @@ -687,7 +681,8 @@ \row \li QAbstractScrollArea \target qabstractscrollarea-widget \li Supports the \l{box model}. - + \br + \br All derivatives of QAbstractScrollArea, including QTextEdit, and QAbstractItemView (all item view classes), support scrollable backgrounds using @@ -696,7 +691,8 @@ \c{fixed} provides a background-image that does not scroll with the viewport. Setting the background-attachment to \c{scroll}, scrolls the background-image when the scroll bars move. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QAbstractScrollArea} {Customizing QAbstractScrollArea} for an example. @@ -706,17 +702,21 @@ styled using the \l{#indicator-sub}{::indicator} subcontrol. By default, the indicator is placed in the Top Left corner of the Contents rectangle of the widget. - + \br + \br The \l{#spacing-prop}{spacing} property specifies the spacing between the check indicator and the text. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QCheckBox} {Customizing QCheckBox} for an example. \row \li QColumnView \target qcolumnview-widget - \li The grip can be styled be using the \l{image-prop}{image} property. + \li The grip can be styled by using the \l{image-prop}{image} property. + \br + \br The arrow indicators can by styled using the \l{left-arrow-sub}{::left-arrow} subcontrol and the \l{right-arrow-sub}{::right-arrow} subcontrol. @@ -724,14 +724,25 @@ \row \li QComboBox \target qcombobox-widget \li The frame around the combobox can be styled using the - \l{box model}. The drop-down button can be styled using + \l{box model}. + \br + \br + The drop-down button can be styled using the \l{#drop-down-sub}{::drop-down} subcontrol. By default, the drop-down button is placed in the top right corner of the padding - rectangle of the widget. The arrow mark inside the drop-down button + rectangle of the widget. + \br + \br + The arrow mark inside the drop-down button can be styled using the \l{#down-arrow-sub}{::down-arrow} subcontrol. By default, the arrow is placed in the center of the contents rectangle of the drop-down subcontrol. - + \br + \br + The color of the placeholder text can be set using the + \l{#placeholder-text-color-prop}{placeholder-text-color} property. + \br + \br See \l{Qt Style Sheets Examples#Customizing QComboBox}{Customizing QComboBox} for an example. @@ -760,14 +771,16 @@ \row \li QDockWidget \target qdockwidget-widget \li Supports styling of the title bar and the title bar buttons when docked. - + \br + \br The dock widget border can be styled using the \l{#border-prop}{border} property. The \l{#title-sub}{::title} subcontrol can be used to customize the title bar. The close and float buttons are positioned with respect to the \l{title-sub}{::title} subcontrol using the \l{#close-button-sub}{::close-button} and \l{#float-button-sub}{::float-button} respectively. - + \br + \br When the title bar is vertical, the \l{#vertical-ps}{:vertical} pseudo class is set. In addition, depending on QDockWidget::DockWidgetFeature, the \l{#closable-ps}{:closable}, \l{#floatable-ps}{:floatable} and @@ -788,31 +801,41 @@ \row \li QFrame \target qframe-widget \li Supports the \l{box model}. - + \br + \br Since 4.3, setting a stylesheet on a QLabel automatically sets the QFrame::frameStyle property to QFrame::StyledPanel. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame} for an example. \row \li QGroupBox \target qgroupbox-widget - \li Supports the \l{box model}. The title can be styled using the + \li Supports the \l{box model}. + \br + \br + The title can be styled using the \l{#title-sub}{::title} subcontrol. By default, the title is placed depending on QGroupBox::textAlignment. - + \br + \br In the case of a checkable QGroupBox, the title includes the check indicator. The indicator is styled using the \l{#indicator-sub}{::indicator} subcontrol. The \l{#spacing-prop}{spacing} property can be used to control the spacing between the text and indicator. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QGroupBox}{Customizing QGroupBox} for an example. \row \li QHeaderView \target qheaderview-widget - \li Supports the \l{box model}. The sections of the header view are + \li Supports the \l{box model}. + \br + \br + The sections of the header view are styled using the \l{#section-sub}{::section} sub control. The \c{section} Sub-control supports the \l{#middle-ps}{:middle}, \l{#first-ps}{:first}, \l{#last-ps}{:last}, @@ -820,11 +843,13 @@ \l{#previous-selected-ps}{:previous-selected}, \l{#selected-ps}{:selected}, and \l{#checked-ps}{:checked} pseudo states. - + \br + \br The sort indicator can be styled using the \l{#up-arrow-sub}{::up-arrow} and the \l{#down-arrow-sub}{::down-arrow} Sub-control. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QHeaderView}{Customizing QHeaderView} for an example. @@ -832,54 +857,72 @@ \li QLabel \target qlabel-widget \li Supports the \l{box model}. Does not support the \l{#hover-ps}{:hover} pseudo-state. - + \br + \br Since 4.3, setting a stylesheet on a QLabel automatically sets the QFrame::frameStyle property to QFrame::StyledPanel. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame} for an example (a QLabel derives from QFrame). \row \li QLineEdit \target qlineedit-widget - \li Support the \l{box model}. - + \li Supports the \l{box model}. + \br + \br The color and background of the selected item is styled using \l{#selection-color-prop}{selection-color} and \l{#selection-background-color-prop}{selection-background-color} respectively. - + \br + \br + The color of the placeholder text can be set using the + \l{#placeholder-text-color-prop}{placeholder-text-color} property. + \br + \br The password character can be styled using the \l{#lineedit-password-character-prop}{lineedit-password-character} property. - + \br + \br The password mask delay can be changed using the \l{#lineedit-password-mask-delay-prop}{lineedit-password-mask-delay} - + \br + \br See \l{Qt Style Sheets Examples#Customizing QLineEdit}{Customizing QLineEdit} for an example. \row \li QListView \target qlistview-widget - \li Supports the \l{box model}. When + \li Supports the \l{box model}. + \br + \br + When \l{QAbstractItemView::alternatingRowColors}{alternating row colors} is enabled, the alternating colors can be styled using the \l{#alternate-background-color-prop}{alternate-background-color} property. - + \br + \br The color and background of the selected item is styled using \l{#selection-color-prop}{selection-color} and \l{#selection-background-color-prop}{selection-background-color} respectively. - + \br + \br The selection behavior is controlled by the \l{#show-decoration-selected-prop}{show-decoration-selected} property. - + \br + \br Use the \l{#item-sub}{::item} subcontrol for more fine grained control over the items in the QListView. - + \br + \br See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to style scrollable backgrounds. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QListView} {Customzing QListView} for an example. @@ -889,45 +932,57 @@ \row \li QMainWindow \target qmainwindow-widget - \li Supports styling of the separator - + \li Supports styling of the separator. + \br + \br The separator in a QMainWindow when using QDockWidget is styled using the \l{#separator-sub}{::separator} subcontrol. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QMainWindow}{Customizing QMainWindow} for an example. \row \li QMenu \target qmenu-widget \li Supports the \l{box model}. - + \br + \br Individual items are styled using the \l{#item-sub}{::item} subcontrol. In addition to the usually supported pseudo states, \c{item} subcontrol supports the \l{#selected-ps}{:selected}, \l{#default-ps}{:default}, \l{#exclusive-ps}{:exclusive} and the \l{#non-exclusive-ps}{non-exclusive} pseudo states. - + \br + \br The indicator of checkable menu items is styled using the \l{#indicator-sub}{::indicator} subcontrol. - + \br + \br The separator is styled using the \l{#separator-sub}{::separator} subcontrol. - + \br + \br For items with a sub menu, the arrow marks are styled using the \l{right-arrow-sub}{right-arrow} and \l{left-arrow-sub}{left-arrow}. - + \br + \br The scroller is styled using the \l{#scroller-sub}{::scroller}. - + \br + \br The tear-off is styled using the \l{#tearoff-sub}{::tearoff}. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QMenu}{Customizing QMenu} for an example. \row \li QMenuBar \target qmenubar-widget - \li Supports the \l{box model}. The \l{#spacing-prop}{spacing} + \li Supports the \l{box model}. + \br + \br + The \l{#spacing-prop}{spacing} property specifies the spacing between menu items. Individual items are styled using the \l{#item-sub}{::item} subcontrol. @@ -946,27 +1001,38 @@ \row \li QProgressBar \target qprogressbar-widget - \li Supports the \l{box model}. The chunks of the progress bar + \li Supports the \l{box model}. + \br + \br + The chunks of the progress bar can be styled using the \l{#chunk-sub}{::chunk} subcontrol. The chunk is displayed on the Contents rectangle of the widget. - + \br + \br If the progress bar displays text, use the \l{text-align-prop}{text-align} property to position the text. - + \br + \br Indeterminate progress bars have the \l{#indeterminate-ps}{:indeterminate} pseudo state set. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QProgressBar}{Customizing QProgressBar} for an example. \row \li QPushButton \target qpushbutton-widget - \li Supports the \l{box model}. Supports the \l{#default-ps}{:default}, + \li Supports the \l{box model}. + \br + \br + Supports the \l{#default-ps}{:default}, \l{#flat-ps}{:flat}, \l{#checked-ps}{:checked} pseudo states. - + \br + \br Since 5.15, the \l{#icon-prop}{icon} property can be set to override the button icon. - + \br + \br For QPushButton with a menu, the menu indicator is styled using the \l{#menu-indicator-sub}{::menu-indicator} subcontrol. Appearance of checkable push buttons can be @@ -985,50 +1051,63 @@ \row \li QRadioButton \target qradiobutton-widget - \li Supports the \l{box model}. The check indicator can be + \li Supports the \l{box model}. + \br + \br + The check indicator can be styled using the \l{#indicator-sub}{::indicator} subcontrol. By default, the indicator is placed in the Top Left corner of the Contents rectangle of the widget. - + \br + \br The \l{#spacing-prop}{spacing} property specifies the spacing between the check indicator and the text. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QRadioButton} {Customizing QRadioButton} for an example. \row \li QScrollBar \target qscrollbar-widget - \li Supports the \l{box model}. The Contents rectangle of the widget + \li Supports the \l{box model}. + \br + \br + The Contents rectangle of the widget is considered to be the groove over which the slider moves. The extent of the QScrollBar (i.e the width or the height depending on the orientation) is set using the \l{#width-prop}{width} or \l{#height-prop}{height} property respectively. To determine the orientation, use the \l{#horizontal-ps}{:horizontal} and the \l{vertical-ps}{:vertical} pseudo states. - + \br + \br The slider can be styled using the \l{#handle-sub}{::handle} subcontrol. Setting the \l{#min-width-prop}{min-width} or \l{#min-height-prop}{min-height} provides size constraints for the slider depending on the orientation. - + \br + \br The \l{add-line-sub}{::add-line} subcontrol can be used to style the button to add a line. By default, the add-line subcontrol is placed in top right corner of the Border rectangle of the widget. Depending on the orientation the \l{#right-arrow-sub}{::right-arrow} or \l{#down-arrow-sub}{::down-arrow}. By default, the arrows are placed in the center of the Contents rectangle of the add-line subcontrol. - + \br + \br The \l{sub-line-sub}{::sub-line} subcontrol can be used to style the button to subtract a line. By default, the sub-line subcontrol is placed in bottom right corner of the Border rectangle of the widget. Depending on the orientation the \l{#left-arrow-sub}{::left-arrow} or \l{#up-arrow-sub}{::up-arrow}. By default, the arrows are placed in the center of the Contents rectangle of the sub-line subcontrol. - + \br + \br The \l{sub-page-sub}{::sub-page} subcontrol can be used to style the region of the slider that subtracts a page. The \l{add-page-sub}{::add-page} subcontrol can be used to style the region of the slider that adds a page. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QScrollBar}{Customizing QScrollBar} for an example. @@ -1037,25 +1116,31 @@ \li Supports the \l{#width-prop}{width}, \l{#height-prop}{height}, and \l{#image-prop}{image} properties. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QSizeGrip}{Customizing QSizeGrip} for an example. \row \li QSlider \target qslider-widget - \li Supports the \l{box model}. For horizontal slides, the + \li Supports the \l{box model}. + \br + \br + For horizontal slides, the \l{min-width-prop}{min-width} and \l{height-prop}{height} properties must be provided. For vertical sliders, the \l{min-height-prop}{min-height} and \l{width-prop}{width} properties must be provided. - + \br + \br The groove of the slider is styled using the \l{#groove-sub}{::groove}. The groove is positioned by default in the Contents rectangle of the widget. The thumb of the slider is styled using \l{#handle-sub}{::handle} subcontrol. The subcontrol moves in the Contents rectangle of the groove subcontrol. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QSlider}{Customizing QSlider} for an example. @@ -1063,7 +1148,8 @@ \li QSpinBox \target qspinbox-widget \li The frame of the spin box can be styled using the \l{box model}. - + \br + \br The up button and arrow can be styled using the \l{#up-button-sub}{::up-button} and \l{#up-arrow-sub}{::up-arrow} subcontrols. By default, @@ -1072,7 +1158,8 @@ it occupies half the height of its reference rectangle. The up-arrow is placed in the center of the Contents rectangle of the up-button. - + \br + \br The down button and arrow can be styled using the \l{#down-button-sub}{::down-button} and \l{#down-arrow-sub}{::down-arrow} subcontrols. By default, @@ -1081,7 +1168,8 @@ it occupies half the height of its reference rectangle. The bottom-arrow is placed in the center of the Contents rectangle of the bottom-button. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QSpinBox}{Customizing QSpinBox} for an example. @@ -1089,7 +1177,8 @@ \li QSplitter \target qsplitter-widget \li Supports the \l{box model}. The handle of the splitter is styled using the \l{#handle-sub}{::handle} subcontrol. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QSplitter}{Customizing QSplitter} for an example. @@ -1099,39 +1188,46 @@ {background} property. The frame for individual items can be style using the \l{#item-sub}{::item} subcontrol. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QStatusBar}{Customizing QStatusBar} for an example. \row \li QTabBar \target qtabbar-widget \li Individual tabs may be styled using the \l{#tab-sub}{::tab} subcontrol. - Close buttons using the \l{#close-button-sub}{::close-button} + Close buttons using the \l{#close-button-sub}{::close-button}. The tabs support the \l{#only-one-ps}{:only-one}, \l{#first-ps}{:first}, \l{#last-ps}{:last}, \l{#middle-ps}{:middle}, \l{#previous-selected-ps}{:previous--selected}, \l{#next-selected-ps}{:next-selected}, \l{#selected-ps}{:selected} pseudo states. - + \br + \br The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right}, \l{#bottom-ps}{:bottom} pseudo states depending on the orientation of the tabs. - + \br + \br Overlapping tabs for the selected state are created by using negative margins or using the \c{absolute} position scheme. - + \br + \br The tear indicator of the QTabBar is styled using the \l{#tear-sub}{::tear} subcontrol. - + \br + \br QTabBar used two QToolButtons for its scrollers that can be styled using the \c{QTabBar QToolButton} selector. To specify the width of the scroll button use the \l{#scroller-sub}{::scroller} subcontrol. - + \br + \br The alignment of the tabs within the QTabBar is styled - using the \l{#Alignment}{alignment} property. \warning - + using the \l{#Alignment}{alignment} property. + \br + \warning To change the position of the QTabBar within a QTabWidget, use the \l{#tab-bar-sub}{tab-bar} subcontrol (and set subcontrol-position). @@ -1146,15 +1242,18 @@ and \l{#right-corner-sub}{::right-corner} respectively. The position of the tab bar is controlled using the \l{#tab-bar-sub}{::tab-bar} subcontrol. - + \br + \br By default, the subcontrols have positions of a QTabWidget in the QWindowsStyle. To place the QTabBar in the center, set the subcontrol-position of the tab-bar subcontrol. - + \br + \br The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right}, \l{#bottom-ps}{:bottom} pseudo states depending on the orientation of the tabs. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QTabWidget and QTabBar} {Customizing QTabWidget} for an example. @@ -1165,27 +1264,32 @@ is enabled, the alternating colors can be styled using the \l{#alternate-background-color-prop}{alternate-background-color} property. - + \br + \br The color and background of the selected item is styled using \l{#selection-color-prop}{selection-color} and \l{#selection-background-color-prop}{selection-background-color} respectively. - + \br + \br The corner widget in a QTableView is implemented as a QAbstractButton and can be styled using the "QTableView QTableCornerButton::section" selector. - + \br \warning If you only set a background-color on a QTableCornerButton, the background may not appear unless you set the border property to some value. This is because, by default, the QTableCornerButton draws a native border which completely overlaps the background-color. + \br The color of the grid can be specified using the \l{#gridline-color-prop}{gridline-color} property. - + \br + \br See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to style scrollable backgrounds. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QTableView} {Customzing QTableView} for an example. @@ -1196,12 +1300,18 @@ \row \li QTextEdit \target qtextedit-widget \li Supports the \l{box model}. - + \br + \br The color and background of selected text is styled using \l{#selection-color-prop}{selection-color} and \l{#selection-background-color-prop}{selection-background-color} respectively. - + \br + \br + The color of the placeholder text can be set using the + \l{#placeholder-text-color-prop}{placeholder-text-color} property. + \br + \br See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to style scrollable backgrounds. @@ -1212,45 +1322,53 @@ \row \li QToolBar \target qtoolbar-widget \li Supports the \l{box model}. - + \br + \br The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right}, \l{#bottom-ps}{:bottom} pseudo states depending on the area in which the tool bar is grouped. - + \br + \br The \l{#first-ps}{:first}, \l{#last-ps}{:last}, \l{#middle-ps}{:middle}, \l{#only-one-ps}{:only-one} pseudo states indicator the position of the tool bar within a line group (See QStyleOptionToolBar::positionWithinLine). - + \br + \br The separator of a QToolBar is styled using the \l{#separator-sub}{::separator} subcontrol. - + \br + \br The handle (to move the toolbar) is styled using the \l{#handle-sub}{::handle} subcontrol. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QToolBar}{Customizing QToolBar} for an example. \row \li QToolButton \target qtoolbutton-widget \li Supports the \l{box model}. - + \br + \br If the QToolButton has a menu, is \l{#menu-indicator-sub}{::menu-indicator} subcontrol can be used to style the indicator. By default, the menu-indicator is positioned at the bottom right of the Padding rectangle of the widget. - + \br + \br If the QToolButton is in QToolButton::MenuButtonPopup mode, the \l{#menu-button-sub}{::menu-button} subcontrol is used to draw the menu button. \l{#menu-arrow-sub}{::menu-arrow} subcontrol is used to draw the menu arrow inside the menu-button. By default, it is positioned in the center of the Contents rectangle of the menu-button subcontrol. - + \br + \br When the QToolButton displays arrows, the \l{#up-arrow-sub}{::up-arrow}, \l{#down-arrow-sub}{::down-arrow}, \l{#left-arrow-sub}{::left-arrow} and \l{#right-arrow-sub}{::right-arrow} subcontrols are used. - + \br \warning If you only set a background-color on a QToolButton, the background will not appear unless you set the border property to some value. This is because, by default, the QToolButton draws a native border which completely @@ -1264,7 +1382,8 @@ \row \li QToolBox \target qtoolbox-widget \li Supports the \l{box model}. - + \br + \br The individual tabs can by styled using the \l{#tab-sub}{::tab} subcontrol. The tabs support the \l{#only-one-ps}{:only-one}, \l{#first-ps}{:first}, @@ -1277,7 +1396,8 @@ \li QToolTip \target qtooltip-widget \li Supports the \l{box model}. The \l{#opacity-prop}{opacity} property controls the opacity of the tooltip. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame} for an example (a QToolTip is a QFrame). @@ -1288,27 +1408,33 @@ is enabled, the alternating colors can be styled using the \l{#alternate-background-color-prop}{alternate-background-color} property. - + \br + \br The color and background of the selected item is styled using \l{#selection-color-prop}{selection-color} and \l{#selection-background-color-prop}{selection-background-color} respectively. - + \br + \br The selection behavior is controlled by the \l{#show-decoration-selected-prop}{show-decoration-selected} property. - + \br + \br The branches of the tree view can be styled using the \l{#branch-sub}{::branch} subcontrol. The ::branch Sub-control supports the \l{open-ps}{:open}, \l{closed-ps}{:closed}, \l{has-siblings-ps}{:has-sibling} and \l{has-children-ps}{:has-children} pseudo states. - + \br + \br Use the \l{#item-sub}{::item} subcontrol for more fine grained control over the items in the QTreeView. - + \br + \br See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to style scrollable backgrounds. - + \br + \br See \l{Qt Style Sheets Examples#Customizing QTreeView}{Customizing QTreeView} for an example to style the branches. @@ -1321,7 +1447,8 @@ \li Supports only the \l{Qt Style Sheets Reference#background-prop}{background}, \l{#background-clip-prop}{background-clip} and \l{#background-origin-prop}{background-origin} properties. - + \br + \br If you subclass from QWidget, you need to provide a paintEvent for your custom QWidget as below: \snippet code/doc_src_stylesheet.cpp 32 @@ -1335,23 +1462,44 @@ \section1 List of Properties - The table below lists all the properties supported by Qt Style - Sheets. Which values can be given to an property depend on the + This section lists all the properties supported by Qt Style + Sheets. Which values can be given to a property depend on the \l{List of Property Types}{property's type}. Unless otherwise - specified, properties below apply to all widgets. Properties + specified, the following properties apply to all widgets. Properties marked with an asterisk * are specific to Qt and have no equivalent - in CSS2 or CSS3. + in CSS2 or CSS3. The Qt-specific properties are the following: + \list + \li \l{#gridline-color*}{gridline-color*} + \li \l{#image*}{image*} + \li \l{#lineedit-password-character*}{lineedit-password-character*} + \li \l{#lineedit-password-mask-delay*}{lineedit-password-mask-delay*} + \li \l{#messagebox-text-interaction-flags*}{messagebox-text-interaction-flags*} + \li \l{#opacity*}{opacity*} + \li \l{#placeholder-text-color*}{placeholder-text-color*} + \li \l{#selection-background-color*}{selection-background-color*} + \li \l{#selection-color*}{selection-color*} + \li \l{#show-decoration-selected*}{show-decoration-selected*} + \li \l{#spacing*}{spacing*} + \li \l{#subcontrol-origin*}{subcontrol-origin*} + \li \l{#subcontrol-position*}{subcontrol-position*} + \li \l{#widget-animation-duration*}{widget-animation-duration*} + \endlist - \table 100% - \header - \li Property - \li Type - \li Description + \section2 accent-color - \row - \li \b{\c alternate-background-color} \target alternate-background-color-prop - \li \l{#Brush}{Brush} \br - \li The \l{QAbstractItemView::alternatingRowColors} + \table + \row \li \b Type \li \l{#Brush}{Brush} + \endtable + + The property sets the \c Accent, which is used to emphasize + interactive UI elements. If this property is not set, it defaults to the \c highlight color. + + \section2 alternate-background-color + \target alternate-background-color-prop + \table + \row \li \b Type \li \l{#Brush}{Brush} + \endtable + The \l{QAbstractItemView::alternatingRowColors} {alternate background color} used in QAbstractItemView subclasses. If this property is not set, the default value is @@ -1365,10 +1513,12 @@ See also \l{Qt Style Sheets Reference#background-prop}{background} and \l{#selection-background-color-prop}{selection-background-color}. - \row - \li \b{\c background} \target background-prop - \li \l{#Background}{Background} - \li Shorthand notation for setting the background. Equivalent + \section2 background + \target background-prop + \table + \row \li \b Type \li \l{#Background}{Background} + \endtable + Shorthand notation for setting the background. Equivalent to specifying \c background-color, \c background-image, \c background-repeat, and/or \c background-position. @@ -1399,19 +1549,23 @@ \l{#background-attachment-prop}{background-attachment} and \l{#alternate-background-color-prop}{alternate-background-color}. - \row - \li \c background-color \target background-color-prop - \li \l{#Brush}{Brush} \br - \li The background color used for the widget. + \section2 background-color + \target background-color-prop + \table + \row \li \b Type \li \l{#Brush}{Brush} + \endtable + The background color used for the widget. Examples: \snippet code/doc_src_stylesheet.qdoc 36 - \row - \li \c background-image \target background-image-prop - \li \l{#Url}{Url} - \li The background image used for the widget. Semi-transparent + \section2 background-image + \target background-image-prop + \table + \row \li \b Type \li \l{#Url}{Url} + \endtable + The background image used for the widget. Semi-transparent parts of the image let the \c background-color shine through. @@ -1419,10 +1573,13 @@ \snippet code/doc_src_stylesheet.qdoc 37 - \row - \li \c background-repeat \target background-repeat-prop - \li \l{#Repeat}{Repeat} - \li Whether and how the background image is repeated to fill + + \section2 background-repeat + \target background-repeat-prop + \table + \row \li \b Type \li \l{#Repeat}{Repeat} + \endtable + Whether and how the background image is repeated to fill the \c background-origin rectangle. If this property is not specified, the background image @@ -1432,10 +1589,11 @@ \snippet code/doc_src_stylesheet.qdoc 38 - \row - \li \c background-position - \li \l{#Alignment}{Alignment} - \li The alignment of the background image within the \c + \section2 background-position + \table + \row \li \b Type \li \l{#Alignment}{Alignment} + \endtable + The alignment of the background image within the \c background-origin rectangle. If this property is not specified, the alignment is \c @@ -1445,10 +1603,12 @@ \snippet code/doc_src_stylesheet.qdoc 39 - \row - \li \b{\c background-attachment} \target background-attachment-prop - \li \l{#Attachment}{Attachment} - \li Determines whether the background-image in a QAbstractScrollArea + \section2 background-attachment + \target background-attachment-prop + \table + \row \li \b Type \li \l{#Attachment}{Attachment} + \endtable + Determines whether the background-image in a QAbstractScrollArea is scrolled or fixed with respect to the viewport. By default, the background-image scrolls with the viewport. @@ -1458,10 +1618,12 @@ See also \l{Qt Style Sheets Reference#background-prop}{background} - \row - \li \b{\c background-clip} \target background-clip-prop - \li \l{#Origin}{Origin} - \li The widget's rectangle, in which the \c background is drawn. + \section2 background-clip + \target background-clip-prop + \table + \row \li \b Type \li \l{#Origin}{Origin} + \endtable + The widget's rectangle, in which the \c background is drawn. This property specifies the rectangle to which the \c background-color and \c background-image are clipped. @@ -1482,10 +1644,13 @@ See also \l{Qt Style Sheets Reference#background-prop}{background}, \l{#background-origin-prop}{background-origin} and \l{The Box Model}. - \row - \li \b{\c background-origin} \target background-origin-prop - \li \l{#Origin}{Origin} - \li The widget's background rectangle, to use in conjunction + \section2 background-origin + \target background-origin-prop + \table + \row \li \b Type \li \l{#Origin}{Origin} + \endtable + + The widget's background rectangle, to use in conjunction with \c background-position and \c background-image. This property is supported by QAbstractItemView @@ -1504,10 +1669,13 @@ See also \l{Qt Style Sheets Reference#background-prop}{background} and \l{The Box Model}. - \row - \li \b{\c border} \target border-prop - \li \l{#Border}{Border} - \li Shorthand notation for setting the widget's border. Equivalent + \section2 border + \target border-prop + \table + \row \li \b Type \li \l{#Border}{Border} + \endtable + + Shorthand notation for setting the widget's border. Equivalent to specifying \c border-color, \c border-style, and/or \c border-width. @@ -1521,39 +1689,52 @@ \snippet code/doc_src_stylesheet.qdoc 43 - \row - \li \c border-top - \li \l{#Border}{Border} - \li Shorthand notation for setting the widget's top border. + \section2 border-top + + \table + \row \li \b Type \li \l{#Border}{Border} + \endtable + + Shorthand notation for setting the widget's top border. Equivalent to specifying \c border-top-color, \c border-top-style, and/or \c border-top-width. - \row - \li \c border-right - \li \l{#Border}{Border} - \li Shorthand notation for setting the widget's right border. + \section2 border-right + \table + \row \li \b Type \li \l{#Border}{Border} + \endtable + + Shorthand notation for setting the widget's right border. Equivalent to specifying \c border-right-color, \c border-right-style, and/or \c border-right-width. - \row - \li \c border-bottom - \li \l{#Border}{Border} - \li Shorthand notation for setting the widget's bottom border. + \section2 border-bottom + \table + \row \li \b Type \li \l{#Border}{Border} + \endtable + + Shorthand notation for setting the widget's bottom border. Equivalent to specifying \c border-bottom-color, \c border-bottom-style, and/or \c border-bottom-width. - \row - \li \c border-left - \li \l{#Border}{Border} - \li Shorthand notation for setting the widget's left border. + \section2 border-left + \table + \row \li \b Type \li \l{#Border}{Border} + \endtable + + Shorthand notation for setting the widget's left border. Equivalent to specifying \c border-left-color, \c border-left-style, and/or \c border-left-width. - \row - \li \b{\c border-color} \target border-attrs - \target border-color-prop - \li \l{#Box Colors}{Box Colors} - \li The color of all the border's edges. Equivalent to + + \section2 border-color + \target border-attrs + \target border-color-prop + \table + \row \li \b Type \li \l{#Box Colors}{Box Colors} + \endtable + + The color of all the border's edges. Equivalent to specifying \c border-top-color, \c border-right-color, \c border-bottom-color, and \c border-left-color. @@ -1575,30 +1756,41 @@ \l{Qt Style Sheets Reference#border-width-prop}{border-width}, \l{#border-image-prop}{border-image}, and \l{The Box Model}. - \row - \li \c border-top-color - \li \l{#Brush}{Brush} \br - \li The color of the border's top edge. + \section2 border-top-color + \table + \row \li \b Type \li \l{#Brush}{Brush} + \endtable - \row - \li \c border-right-color - \li \l{#Brush}{Brush} \br - \li The color of the border's right edge. + The color of the border's top edge. - \row - \li \c border-bottom-color - \li \l{#Brush}{Brush} \br - \li The color of the border's bottom edge. + \section2 border-right-color + \table + \row \li \b Type \li \l{#Brush}{Brush} + \endtable - \row - \li \c border-left-color - \li \l{#Brush}{Brush} \br - \li The color of the border's left edge. + The color of the border's right edge. - \row - \li \b{\c border-image} \target border-image-prop - \li \l{#Border Image}{Border Image} - \li The image used to fill the border. The image is cut into + \section2 border-bottom-color + \table + \row \li \b Type \li \l{#Brush}{Brush} + \endtable + + The color of the border's bottom edge. + + \section2 border-left-color + \table + \row \li \b Type \li \l{#Brush}{Brush} + \endtable + + The color of the border's left edge. + + \section2 border-image + \target border-image-prop + \table + \row \li \b Type \li \l{#Border Image}{Border Image} + \endtable + + The image used to fill the border. The image is cut into nine parts and stretched appropriately if necessary. See \l{#Border Image}{Border Image} for details. @@ -1613,10 +1805,13 @@ \l{Qt Style Sheets Reference#border-width-prop}{border-width}, and \l{The Box Model}. - \row - \li \b{\c border-radius} \target border-radius-prop - \li \l{#Radius}{Radius} - \li The radius of the border's corners. Equivalent to + \section2 border-radius + \target border-radius-prop + \table + \row \li \b Type \li \l{#Radius}{Radius} + \endtable + + The radius of the border's corners. Equivalent to specifying \c border-top-left-radius, \c border-top-right-radius, \c border-bottom-right-radius, and \c border-bottom-left-radius. @@ -1639,33 +1834,44 @@ See also \l{Qt Style Sheets Reference#border-width-prop}{border-width} and \l{The Box Model}. - \row - \li \c border-top-left-radius - \li \l{#Radius}{Radius} - \li The radius of the border's top-left corner. + \section2 border-top-left-radius + \table + \row \li \b Type \li \l{#Radius}{Radius} + \endtable - \row - \li \c border-top-right-radius - \li \l{#Radius}{Radius} - \li The radius of the border's top-right corner. + The radius of the border's top-left corner. - \row - \li \c border-bottom-right-radius - \li \l{#Radius}{Radius} - \li The radius of the border's bottom-right corner. Setting + \section2 border-top-right-radius + \table + \row \li \b Type \li \l{#Radius}{Radius} + \endtable + + The radius of the border's top-right corner. + + \section2 border-bottom-right-radius + \table + \row \li \b Type \li \l{#Radius}{Radius} + \endtable + + The radius of the border's bottom-right corner. Setting this property to a positive value results in a rounded corner. - \row - \li \c border-bottom-left-radius - \li \l{#Radius}{Radius} - \li The radius of the border's bottom-left corner. Setting this + \section2 border-bottom-left-radius + \table + \row \li \b Type \li \l{#Radius}{Radius} + \endtable + + The radius of the border's bottom-left corner. Setting this property to a positive value results in a rounded corner. - \row - \li \b{\c border-style} \target border-style-prop - \li \l {Border Style} - \li The style of all the border's edges. + \section2 border-style + \target border-style-prop + \table + \row \li \b Type \li \l{#Border Style}{Border Style} + \endtable + + The style of all the border's edges. This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, @@ -1683,30 +1889,41 @@ \l{Qt Style Sheets Reference#border-style-prop}{border-style}, \l{#border-image-prop}{border-image}, and \l{The Box Model}. - \row - \li \c border-top-style - \li \l{#Border Style}{Border Style} - \li The style of the border's top edge. + \section2 border-top-style + \table + \row \li \b Type \li \l{#Border Style}{Border Style}} + \endtable - \row - \li \c border-right-style - \li \l{#Border Style}{Border Style} - \li The style of the border's right edge/ + The style of the border's top edge. - \row - \li \c border-bottom-style - \li \l{#Border Style}{Border Style} - \li The style of the border's bottom edge. + \section2 border-right-style + \table + \row \li \b Type \li \l{#Border Style}{Border Style} + \endtable - \row - \li \c border-left-style - \li \l{#Border Style}{Border Style} - \li The style of the border's left edge. + The style of the border's right edge. - \row - \li \b{\c border-width} \target border-width-prop - \li \l{#Box Lengths}{Box Lengths} - \li The width of the border. Equivalent to setting \c + \section2 border-bottom-style + \table + \row \li \b Type \li \l{#Border Style}{Border Style} + \endtable + + The style of the border's bottom edge. + + \section2 border-left-style + \table + \row \li \b Type \li \l{#Border Style}{Border Style} + \endtable + + The style of the border's left edge. + + \section2 border-width + \target border-width-prop + \table + \row \li \b Type \li \l{#Box Lengths}{Box Lengths} + \endtable + + The width of the border. Equivalent to setting \c border-top-width, \c border-right-width, \c border-bottom-width, and \c border-left-width. @@ -1726,30 +1943,41 @@ \l{#border-image-prop}{border-image}, and \l{The Box Model}. - \row - \li \c border-top-width - \li \l{#Length}{Length} - \li The width of the border's top edge. + \section2 border-top-width + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable - \row - \li \c border-right-width - \li \l{#Length}{Length} - \li The width of the border's right edge. + The width of the border's top edge. - \row - \li \c border-bottom-width - \li \l{#Length}{Length} - \li The width of the border's bottom edge. + \section2 border-right-width + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable - \row - \li \c border-left-width - \li \l{#Length}{Length} - \li The width of the border's left edge. + The width of the border's right edge. - \row - \li \b{\c bottom} \target bottom-prop - \li \l{#Length}{Length} - \li If \l{#position-prop}{position} is \c relative (the + \section2 border-bottom-width + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + The width of the border's bottom edge. + + \section2 border-left-width + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + The width of the border's left edge. + + \section2 bottom + \target bottom-prop + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + If \l{#position-prop}{position} is \c relative (the default), moves a subcontrol by a certain offset up; specifying \tt{bottom: \e{y}} is then equivalent to specifying \tt{\l{Qt Style Sheets Reference#top-prop}{top}: -\e{y}}. @@ -1767,10 +1995,14 @@ See also \l{Qt Style Sheets Reference#left-prop}{left}, \l{#right-prop}{right}, and \l{Qt Style Sheets Reference#top-prop}{top}. - \row - \li \b{\c button-layout} \target button-layout-prop - \li \l{#Number}{Number} - \li The layout of buttons in a QDialogButtonBox or + + \section2 button-layout + \target button-layout-prop + \table + \row \li \b Type \li \l{#Number}{Number} + \endtable + + The layout of buttons in a QDialogButtonBox or a QMessageBox. The possible values are 0 (\l{QDialogButtonBox::}{WinLayout}), 1 (\l{QDialogButtonBox::}{MacLayout}), 2 @@ -1786,10 +2018,14 @@ \snippet code/doc_src_stylesheet.qdoc 49 - \row - \li \b{\c color} \target color-prop - \li \l{#Brush}{Brush} \br - \li The color used to render text. + + \section2 color + \target color-prop + \table + \row \li \b Type \li \l{#Brush}{Brush} \br + \endtable + + The color used to render text. This property is supported by all widgets that respect the \l QWidget::palette. @@ -1805,10 +2041,12 @@ See also \l{Qt Style Sheets Reference#background-prop}{background} and \l{#selection-color-prop}{selection-color}. - \row - \li \b{\c dialogbuttonbox-buttons-have-icons} - \li \l{#Boolean}{Boolean} - \li Whether the buttons in a QDialogButtonBox show icons + \section2 dialogbuttonbox-buttons-have-icons + \table + \row \li \b Type \li \l{#Boolean}{Boolean} + \endtable + + Whether the buttons in a QDialogButtonBox show icons If this property is set to 1, the buttons of a QDialogButtonBox show icons; if it is set to 0, the icons are not shown. @@ -1837,10 +2075,13 @@ \snippet code/doc_src_stylesheet.qdoc 52 \endomit - \row - \li \b{\c font} \target font-prop - \li \l{#Font}{Font} - \li Shorthand notation for setting the text's font. Equivalent + \section2 font + \target font-prop + \table + \row \li \b Type \li \l{#Font}{Font} + \endtable + + Shorthand notation for setting the text's font. Equivalent to specifying \c font-family, \c font-size, \c font-style, and/or \c font-weight. @@ -1854,43 +2095,54 @@ \snippet code/doc_src_stylesheet.qdoc 53 - \row - \li \c font-family - \li String - \li The font family. + \section2 font-family + \table + \row \li \b Type \li String + \endtable + + The font family. Example: \snippet code/doc_src_stylesheet.qdoc 54 - \row - \li \c font-size - \li \l{#Font Size}{Font Size} - \li The font size. In this version of Qt, only pt and px metrics are + \section2 font-size + \table + \row \li \b Type \li \l{#Font Size}{Font Size} + \endtable + + The font size. In this version of Qt, only pt and px metrics are supported. Example: \snippet code/doc_src_stylesheet.qdoc 55 - \row - \li \c font-style - \li \l {Font Style} - \li The font style. + \section2 font-style + \table + \row \li \b Type \li \l {#Font Style} {Font Style} + \endtable + + The font style. Example: \snippet code/doc_src_stylesheet.qdoc 56 - \row - \li \c font-weight - \li \l{#Font Weight}{Font Weight} - \li The weight of the font. + \section2 font-weight + \table + \row \li \b Type \li \l{#Font Weight}{Font Weight} + \endtable - \row - \li \b{\c gridline-color}* \target gridline-color-prop - \li \l{#Color}{Color} \br - \li The color of the grid line in a QTableView. + The weight of the font. + + \section2 gridline-color* + \target gridline-color-prop + \table + \row \li \b Type \li \l{#Color}{Color} + \endtable + + The color of the grid line in a QTableView. If this property is not specified, it defaults to the value specified by the current style for the @@ -1900,10 +2152,14 @@ \snippet code/doc_src_stylesheet.qdoc 57 - \row - \li \b{\c height} \target height-prop - \li \l{#Length}{Length} - \li The height of a subcontrol (or in some case, a widget). + + \section2 height + \target height-prop + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + The height of a subcontrol (or in some case, a widget). If this property is not specified, it defaults to a value that depends on the subcontrol/widget and on the current style. @@ -1919,10 +2175,13 @@ See also \l{#width-prop}{width}. - \row - \li \b{\c icon} \target icon-prop - \li \l{#Url}{Url}+ - \li The icon that is used, for widgets that have an icon. + \section2 icon + \target icon-prop + \table + \row \li \b Type \li \l{#Url}{Url}+ + \endtable + + The icon that is used, for widgets that have an icon. The only widget currently supporting this property is QPushButton. @@ -1933,10 +2192,13 @@ Available since 5.15. - \row - \li \b{\c icon-size} \target icon-size-prop - \li \l{#Length}{Length} - \li The width and height of the icon in a widget. + \section2 icon-size + \target icon-size-prop + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + The width and height of the icon in a widget. The icon size of the following widgets can be set using this property. @@ -1951,10 +2213,13 @@ \li QTreeView \endlist - \row - \li \b{\c image}* \target image-prop - \li \l{#Url}{Url}+ - \li The image that is drawn in the contents rectangle of a + \section2 image* + \target image-prop + \table + \row \li \b Type \li \l{#Url}{Url}+ + \endtable + + The image that is drawn in the contents rectangle of a subcontrol. The image property accepts a list of \l{#Url}{Url}s or @@ -1979,16 +2244,23 @@ \snippet code/doc_src_stylesheet.qdoc 59 - \row - \li \b{\c image-position} \target image-position-prop - \li \l{#Alignment}{alignment} - \li In Qt 4.3 and later, the alignment of the image image's position can be specified + + \section2 image-position + \target image-position-prop + \table + \row \li \b Type \li \l{#Alignment}{alignment} + \endtable + + In Qt 4.3 and later, the alignment of the image image's position can be specified using relative or absolute position. - \row - \li \b{\c left} \target left-prop - \li \l{#Length}{Length} - \li If \l{#position-prop}{position} is \c relative (the + \section2 left + \target left-prop + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + If \l{#position-prop}{position} is \c relative (the default), moves a subcontrol by a certain offset to the right. @@ -2006,10 +2278,13 @@ See also \l{#right-prop}{right}, \l{Qt Style Sheets Reference#top-prop}{top}, and \l{#bottom-prop}{bottom}. - \row - \li \b{\c lineedit-password-character*} \target lineedit-password-character-prop - \li \l{#Number}{Number} - \li The QLineEdit password character as a Unicode number. + \section2 lineedit-password-character* + \target lineedit-password-character-prop + \table + \row \li \b Type \li \l{#Number}{Number} + \endtable + + The QLineEdit password character as a Unicode number. If this property is not specified, it defaults to the value specified by the current style for the @@ -2019,27 +2294,33 @@ \snippet code/doc_src_stylesheet.qdoc 61 - \row - \li \b{\c lineedit-password-mask-delay*} \target lineedit-password-mask-delay-prop - \li \l{#Number}{Number} - \li The QLineEdit password mask delay in milliseconds before + + \section2 lineedit-password-mask-delay* + \target lineedit-password-mask-delay-prop + \table + \row \li \b Type \li \l{#Number}{Number} + \endtable + + The QLineEdit password mask delay in milliseconds before \l{#lineedit-password-character-prop}{lineedit-password-character} is applied to visible character. If this property is not specified, it defaults to the value specified by the current style for the \l{QStyle::}{SH_LineEdit_PasswordMaskDelay} style hint. - \b{This property was added in Qt 5.4.} + Available since Qt 5.4. Example: \snippet code/doc_src_stylesheet.qdoc 160 + \section2 margin + \target margin-prop + \table + \row \li \b Type \li \l {#Box Lengths}{Box Lengths} + \endtable - \row - \li \b{\c margin} \target margin-prop - \li \l {Box Lengths} - \li The widget's margins. Equivalent to specifying \c + The widget's margins. Equivalent to specifying \c margin-top, \c margin-right, \c margin-bottom, and \c margin-left. @@ -2058,30 +2339,37 @@ See also \l{Qt Style Sheets Reference#padding-prop}{padding}, \l{#spacing-prop}{spacing}, and \l{The Box Model}. - \row - \li \c margin-top - \li \l{#Length}{Length} - \li The widget's top margin. + \section2 margin-top + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + The widget's top margin. - \row - \li \c margin-right - \li \l{#Length}{Length} - \li The widget's right margin. + \section2 margin-right + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + The widget's right margin. - \row - \li \c margin-bottom - \li \l{#Length}{Length} - \li The widget's bottom margin. + \section2 margin-bottom + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + The widget's bottom margin. - \row - \li \c margin-left - \li \l{#Length}{Length} - \li The widget's left margin. + \section2 margin-left + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + The widget's left margin. - \row - \li \b{\c max-height} \target max-height-prop - \li \l{#Length}{Length} - \li The widget's or a subcontrol's maximum height. + \section2 max-height + \target max-height-prop + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + The widget's or a subcontrol's maximum height. This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, @@ -2098,10 +2386,13 @@ See also \l{#max-width-prop}{max-width}. - \row - \li \b{\c max-width} \target max-width-prop - \li \l{#Length}{Length} - \li The widget's or a subcontrol's maximum width. + \section2 max-width + \target max-width-prop + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + The widget's or a subcontrol's maximum width. This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, @@ -2118,11 +2409,13 @@ See also \l{#max-height-prop}{max-height}. + \section2 messagebox-text-interaction-flags* + \target messagebox-text-interaction-flags-prop + \table + \row \li \b Type \li \l{#Number}{Number} + \endtable - \row - \li \b{\c messagebox-text-interaction-flags*} \target messagebox-text-interaction-flags-prop - \li \l{#Number}{Number} - \li The interaction behavior for text in a message box. + The interaction behavior for text in a message box. Possible values are based on Qt::TextInteractionFlags. If this property is not specified, it defaults to the @@ -2134,10 +2427,13 @@ \snippet code/doc_src_stylesheet.qdoc 65 - \row - \li \b{\c min-height} \target min-height-prop - \li \l{#Length}{Length} - \li The widget's or a subcontrol's minimum height. + \section2 min-height + \target min-height-prop + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + The widget's or a subcontrol's minimum height. This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, @@ -2160,10 +2456,13 @@ See also \l{#min-width-prop}{min-width}. - \row - \li \b{\c min-width} \target min-width-prop - \li \l{#Length}{Length} - \li The widget's or a subcontrol's minimum width. + \section2 min-width + \target min-width-prop + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + The widget's or a subcontrol's minimum width. This property is supported by QAbstractItemView subclasses, QAbstractSpinBox subclasses, QCheckBox, @@ -2186,10 +2485,13 @@ See also \l{#min-height-prop}{min-height}. - \row - \li \b{\c opacity*} \target opacity-prop - \li \l{#Number}{Number} - \li The opacity for a widget. Possible values are from 0 + \section2 opacity* + \target opacity-prop + \table + \row \li \b Type \li \l{#Number}{Number} + \endtable + + The opacity for a widget. Possible values are from 0 (transparent) to 255 (opaque). For the moment, this is only supported for \l{QToolTip}{tooltips}. @@ -2201,58 +2503,69 @@ \snippet code/doc_src_stylesheet.qdoc 68 - \row - \li \b outline - \li - \li The outline drawn around the object's border. + \section2 outline - \row - \li \b outline-color - \li \l{#Color}{Color} - \li The color of the outline. + The outline drawn around the object's border. + + \section2 outline-color + \table + \row \li \b Type \li \l{#Color}{Color} + \endtable + + The color of the outline. See also \l{Qt Style Sheets Reference#border-color-prop}{border-color} - \row - \li \b outline-offset - \li \l{#Length}{Length} - \li The outline's offset from the border of the widget. + \section2 outline-offset + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable - \row - \li \b outline-style - \li - \li Specifies the pattern used to draw the outline. - See also \l{Qt Style Sheets Reference#border-style-prop}{border-style} + The outline's offset from the border of the widget. - \row - \li \b outline-radius - \li - \li Adds rounded corners to the outline + \section2 outline-style - \row - \li \b outline-bottom-left-radius - \li \l{#Radius}{Radius} - \li The radius for the bottom-left rounded corner of the outline. + Specifies the pattern used to draw the outline. + See also \l{Qt Style Sheets Reference#border-style-prop}{border-style} - \row - \li \b outline-bottom-right-radius - \li \l{#Radius}{Radius} - \li The radius for the bottom-right rounded corner of the outline. + \section2 outline-radius - \row - \li \b outline-top-left-radius - \li \l{#Radius}{Radius} - \li The radius for the top-left corner of the outline. + Adds rounded corners to the outline. - \row - \li \b outline-top-right-radius - \li \l{#Radius}{Radius} - \li The radius for the top-right rounded corner of the outline. + \section2 outline-bottom-left-radius + \table + \row \li \b Type \li \l{#Radius}{Radius} + \endtable + The radius for the bottom-left rounded corner of the outline. - \row - \li \b{\c padding} \target padding-prop - \li \l{#Box Lengths}{Box Lengths} - \li The widget's padding. Equivalent to specifying \c + \section2 outline-bottom-right-radius + \table + \row \li \b Type \li \l{#Radius}{Radius} + \endtable + + The radius for the bottom-right rounded corner of the outline. + + \section2 outline-top-left-radius + \table + \row \li \b Type \li \l{#Radius}{Radius} + \endtable + + The radius for the top-left corner of the outline. + + \section2 outline-top-right-radius + \table + \row \li \b Type \li \l{#Radius}{Radius} + \endtable + + The radius for the top-right rounded corner of the outline. + + \section2 padding + \target padding-prop + \table + \row \li \b Type \li \l{#Box Lengths}{Box Lengths} + \endtable + + The widget's padding. Equivalent to specifying \c padding-top, \c padding-right, \c padding-bottom, and \c padding-left. @@ -2271,38 +2584,69 @@ See also \l{#margin-prop}{margin}, \l{#spacing-prop}{spacing}, and \l{The Box Model}. - \row - \li \c padding-top - \li \l{#Length}{Length} - \li The widget's top padding. + \section2 padding-top + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable - \row - \li \c padding-right - \li \l{#Length}{Length} - \li The widget's right padding. + The widget's top padding. - \row - \li \c padding-bottom - \li \l{#Length}{Length} - \li The widget's bottom padding. + \section2 padding-right + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable - \row - \li \c padding-left - \li \l{#Length}{Length} - \li The widget's left padding. + The widget's right padding. - \row - \li \b{\c paint-alternating-row-colors-for-empty-area} - \target paint-alternating-row-colors-for-empty-area-prop - \li \c bool - \li Whether the QTreeView paints alternating row colors for the empty + \section2 padding-bottom + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + The widget's bottom padding. + + \section2 padding-left + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + The widget's left padding. + + \section2 paint-alternating-row-colors-for-empty-area + \target paint-alternating-row-colors-for-empty-area-prop + \table + \row \li \b Type \li \c bool + \endtable + + Whether the QTreeView paints alternating row colors for the empty area (i.e the area where there are no items) - \row - \li \b{\c position} \target position-prop - \li \c relative \br - | \c absolute - \li Whether offsets specified using \l{Qt Style Sheets Reference#left-prop}{left}, + \section2 placeholder-text-color* + \target placeholder-text-color-prop + \table + \row \li \b Type \li \l{#Brush}{Brush} \br + \endtable + + The color used for the placeholder text of text editing widgets. + + If this property is not set, the default value is whatever + is set for the palette's \l{QPalette::}{PlaceholderText} + role. + + Example: + + \snippet code/doc_src_stylesheet.qdoc 163 + + Available since 6.5. + + \section2 position + \target position-prop + \table + \row \li \b Type \li \c relative \br + | \c absolute + \endtable + + Whether offsets specified using \l{Qt Style Sheets Reference#left-prop}{left}, \l{#right-prop}{right}, \l{Qt Style Sheets Reference#top-prop}{top}, and \l{#bottom-prop}{bottom} are relative or absolute coordinates. @@ -2310,10 +2654,13 @@ If this property is not specified, it defaults to \c relative. - \row - \li \b{\c right} \target right-prop - \li \l{#Length}{Length} - \li If \l{#position-prop}{position} is \c relative (the + \section2 right + \target right-prop + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + If \l{#position-prop}{position} is \c relative (the default), moves a subcontrol by a certain offset to the left; specifying \tt{right: \e{x}} is then equivalent to specifying \tt{\l{Qt Style Sheets Reference#left-prop}{left}: -\e{x}}. @@ -2330,10 +2677,13 @@ See also \l{Qt Style Sheets Reference#left-prop}{left}, \l{Qt Style Sheets Reference#top-prop}{top}, and \l{#bottom-prop}{bottom}. - \row - \li \b{\c selection-background-color*} \target selection-background-color-prop - \li \l{#Brush}{Brush} \br - \li The background of selected text or items. + \section2 selection-background-color* + \target selection-background-color-prop + \table + \row \li \b Type \li \l{#Brush}{Brush} + \endtable + + The background of selected text or items. This property is supported by all widgets that respect the \l QWidget::palette and that show selection text. @@ -2349,10 +2699,14 @@ See also \l{#selection-color-prop}{selection-color} and \l{Qt Style Sheets Reference#background-prop}{background}. - \row - \li \b{\c selection-color*} \target selection-color-prop - \li \l{#Brush}{Brush} \br - \li The foreground of selected text or items. + + \section2 selection-color* + \target selection-color-prop + \table + \row \li \b Type \li \l{#Brush}{Brush} \br + \endtable + + The foreground of selected text or items. This property is supported by all widgets that respect the \l QWidget::palette and that show selection text. @@ -2369,10 +2723,14 @@ \l{#selection-background-color-prop}{selection-background-color} and \l{#color-prop}{color}. - \row - \li \b{\c show-decoration-selected*} \target show-decoration-selected-prop - \li \l{#Boolean}{Boolean} - \li Controls whether selections in a QListView cover the + + \section2 show-decoration-selected* + \target show-decoration-selected-prop + \table + \row \li \b Type \li \l{#Boolean}{Boolean} + \endtable + + Controls whether selections in a QListView cover the entire row or just the extent of the text. If this property is not specified, it defaults to the @@ -2384,10 +2742,13 @@ \snippet code/doc_src_stylesheet.qdoc 73 - \row - \li \b{\c spacing*} \target spacing-prop - \li \l{#Length}{Length} - \li Internal spacing in the widget. + \section2 spacing* + \target spacing-prop + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + Internal spacing in the widget. This property is supported by QCheckBox, checkable \l{QGroupBox}es, QMenuBar, and QRadioButton. @@ -2402,10 +2763,14 @@ See also \l{Qt Style Sheets Reference#padding-prop}{padding} and \l{#margin-prop}{margin}. - \row - \li \b{\c subcontrol-origin*} \target subcontrol-origin-prop - \li \l{#Origin}{Origin} - \li The origin rectangle of the subcontrol within the + + \section2 subcontrol-origin* + \target subcontrol-origin-prop + \table + \row \li \b Type \li \l{#Origin}{Origin} + \endtable + + The origin rectangle of the subcontrol within the parent element. If this property is not specified, the default is \c @@ -2418,10 +2783,13 @@ See also \l{Qt Style Sheets Reference#subcontrol-position-prop}{subcontrol-position}. - \row - \li \b{\c subcontrol-position*} \target subcontrol-position-prop - \li \l{#Alignment}{Alignment} - \li The alignment of the subcontrol within the origin + \section2 subcontrol-position* + \target subcontrol-position-prop + \table + \row \li \b Type \li \l{#Alignment}{Alignment} + \endtable + + The alignment of the subcontrol within the origin rectangle specified by \l{Qt Style Sheets Reference#subcontrol-origin-prop} {subcontrol-origin}. @@ -2435,32 +2803,41 @@ See also \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}. - \row - \li \b{\c titlebar-show-tooltips-on-buttons}} - \target titlebar-show-tooltips-on-buttons-prop - \li \c bool - \li Whether tool tips are shown on window title bar buttons. + \section2 titlebar-show-tooltips-on-buttons + \target titlebar-show-tooltips-on-buttons-prop + \table + \row \li \b Type \li \c bool + \endtable - \row - \li \b{\c widget-animation-duration*} \target widget-animation-duration - \li \l{#Number}{Number} - \li How much an animation should last (in milliseconds). + Whether tool tips are shown on window title bar buttons. + + + \section2 widget-animation-duration* + \target widget-animation-duration + \table + \row \li \b Type \li \l{#Number}{Number} + \endtable + + How much an animation should last (in milliseconds). A value equal to zero means that the animations will be disabled. If this property is not specified, it defaults to the value specified by the current style for the \l{QStyle::}{SH_Widget_Animation_Duration} style hint. - \b{This property was added in Qt 5.10.} + Available since Qt 5.10. Example: \snippet code/doc_src_stylesheet.qdoc 162 - \row - \li \b{\c text-align} \target text-align-prop - \li \l{#Alignment}{Alignment} - \li The alignment of text and icon within the contents of the widget. + \section2 text-align + \target text-align-prop + \table + \row \li \b Type \li \l{#Alignment}{Alignment} + \endtable + + The alignment of text and icon within the contents of the widget. If this value is not specified, it defaults to the value that depends on the native style. @@ -2472,18 +2849,25 @@ This property is currently supported only by QPushButton and QProgressBar. - \row - \li \b{\c text-decoration} - \li \c none \br + \section2 text-decoration + \table + \row \li \b Type + \li \c none \br \c underline \br \c overline \br \c line-through - \li Additional text effects + \endtable - \row - \li \b{\c top} \target top-prop - \li \l{#Length}{Length} - \li If \l{#position-prop}{position} is \c relative (the + Additional text effects. + + + \section2 top + \target top-prop + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + If \l{#position-prop}{position} is \c relative (the default), moves a subcontrol by a certain offset down. @@ -2501,10 +2885,13 @@ See also \l{Qt Style Sheets Reference#left-prop}{left}, \l{#right-prop}{right}, and \l{#bottom-prop}{bottom}. - \row - \li \b{\c width} \target width-prop - \li \l{#Length}{Length} - \li The width of a subcontrol (or a widget in some cases). + \section2 width + \target width-prop + \table + \row \li \b Type \li \l{#Length}{Length} + \endtable + + The width of a subcontrol (or a widget in some cases). If this property is not specified, it defaults to a value that depends on the subcontrol/widget and on the current style. @@ -2520,19 +2907,24 @@ See also \l{#height-prop}{height}. - \row - \li \b -qt-background-role - \li \l{#paletterole}{PaletteRole} - \li The \c{background-color} for the subcontrol or widget based on the + + \section2 -qt-background-role + \table + \row \li \b Type \li \l{#paletterole}{PaletteRole} + \endtable + + The \c{background-color} for the subcontrol or widget based on the chosen role. - \row - \li \b -qt-style-features - \li \c list - \li The list of CSS properties that you want to apply Qt-specific styles on. + \section2 -qt-style-features + \table + \row \li \b Type \li \c list + \endtable + + The list of CSS properties that you want to apply Qt-specific styles on. \note The \c list can only include properties that are not pixmap-based. - \endtable + \target list of icons \section1 List of Icons @@ -3040,6 +3432,7 @@ \row \li \b{PaletteRole} \target PaletteRole \li \c alternate-base \br + | \c accent \br | \c base \br | \c bright-text \br | \c button \br @@ -4041,7 +4434,7 @@ \image stylesheet-treeview.png - \sa {Style Sheet Example}, {Supported HTML Subset}, QStyle + \sa {Supported HTML Subset}, QStyle \section1 Common Mistakes diff --git a/src/widgets/doc/src/widgets-tutorial.qdoc b/src/widgets/doc/src/widgets-tutorial.qdoc index c223340079..e0ad4d850c 100644 --- a/src/widgets/doc/src/widgets-tutorial.qdoc +++ b/src/widgets/doc/src/widgets-tutorial.qdoc @@ -101,6 +101,7 @@ /*! \example tutorials/widgets/toplevel \title Widgets Tutorial - Creating a Window + \examplecategory {User Interface Components} If a widget is created without a parent, it is treated as a window, or \e{top-level widget}, when it is shown. Since it has no parent object to @@ -127,6 +128,7 @@ /*! \example tutorials/widgets/childwidget \title Widgets Tutorial - Child Widgets + \examplecategory {User Interface Components} We can add a child widget to the window created in the previous example by passing \c window as the parent to its constructor. In this case, we add a @@ -149,6 +151,7 @@ /*! \example tutorials/widgets/windowlayout \title Widgets Tutorial - Using Layouts + \examplecategory {User Interface Components} Usually, child widgets are arranged inside a window using layout objects rather than by specifying positions and sizes explicitly. Here, we @@ -183,6 +186,7 @@ /*! \example tutorials/widgets/nestedlayouts \title Widgets Tutorial - Nested Layouts + \examplecategory {User Interface Components} Just as widgets can contain other widgets, layouts can be used to provide different levels of grouping for widgets. Here, we want to display a @@ -211,7 +215,7 @@ As well as QHBoxLayout and QVBoxLayout, Qt also provides QGridLayout and QFormLayout classes to help with more complex user interfaces. - These can be seen if you run Qt Designer. + These can be seen if you run \QD. \section1 Setting up the Model diff --git a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc index 192d05aff7..6b0315f10a 100644 --- a/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc +++ b/src/widgets/doc/src/windows-and-dialogs/mainwindow.qdoc @@ -6,18 +6,20 @@ \brief Windows and Dialogs in Qt. \ingroup qt-gui-concepts - A \l{Widgets Tutorial}{widget} that is not embedded in a parent widget is called a window. - (Usually, windows have a frame and a title bar, although it is also possible to create - windows without such decoration using suitable window flags). In Qt, QMainWindow - and the various subclasses of QDialog are the most common window types. + A \l{Widgets Tutorial}{widget} that is not embedded in a parent widget is + called a window. Usually, windows have a frame and a title bar, although it + is also possible to create windows without such decoration using suitable + window flags. In Qt, QMainWindow and the various subclasses of QDialog are + the most common window types. In applications, windows provide the screen space upon which the user interface is built. Windows separate applications visually from each other - and usually provide a window decoration that allows the user to resize and - position the applications according to his preferences. Windows are typically - integrated into the desktop environment and to some degree managed by the - window management system that the desktop environment provides. For instance, - selected windows of an application are represented in the task bar. + and usually provide a window decoration that allows you to resize and + position the applications according to your preferences. Windows are + typically integrated into the desktop environment and to some degree managed + by the window management system that the desktop environment provides. For + instance, selected windows of an application are represented in the task + bar. \section1 Primary and Secondary Windows @@ -27,8 +29,8 @@ In addition, a QWidget that has a parent can become a window by setting the Qt::Window flag. Depending on the window management system - such \e{secondary windows} are usually stacked on top of their respective parent - window, and not have a task bar entry of their own. + such \e{secondary windows} are usually stacked on top of their respective + parent window and do not have a task bar entry of their own. The QMainWindow class sets the Qt::Window flag in its constructor, as it is designed to be used as a window and provides facilities that are @@ -37,20 +39,21 @@ \section1 Main Windows and Dialogs The \l{Application Main Window} provides the framework for building the - application's main user interface, and are created by subclassing QMainWindow. + application's main user interface and are created by subclassing + QMainWindow. QMainWindow has its own layout to which you can add a \l{QMenuBar}{menu bar}, \l{QToolBar}{tool bars}, \l{QDockWidget}{dockable widgets} and a \l{QStatusBar}{status bar}. The center area can be occupied by any kind of QWidget. - \l{Dialog Windows} are used as secondary windows that present the user with + \l{Dialog Windows} are used as secondary windows that present you with options and choices. Dialogs are created by subclassing QDialog and using \l{Widgets and Layouts}{widgets and layouts} to implement the user interface. In addition, Qt provides a number of ready-made standard dialogs that can be used for standard tasks like file or font selection. - Both main windows and dialogs can be created with Qt Designer, Qt's visual design tool. - Using Qt Designer is a lot faster than hand-coding, and makes it easy to test different + Both main windows and dialogs can be created with \QD, Qt's visual design tool. + Using \QD is a lot faster than hand-coding, and makes it easy to test different design ideas. Creating designs visually and reading the code generated by \l{uic} is a great way to learn Qt! @@ -59,8 +62,8 @@ QWidget provides several functions that deal with a widget's geometry. Some of these functions operate on the pure client area - (i.e. the window excluding the window frame), others include the - window frame. The differentiation is done in a way that covers the + (that is, the window excluding the window frame), others include the + window frame. QWidget differentiates in a way that covers the most common usage transparently. \list @@ -99,9 +102,9 @@ Furthermore, a toolkit cannot simply place windows on the screen. All Qt can do is to send certain hints to the window manager. The window - manager, a separate process, may either obey, ignore or misunderstand + manager, a separate process, may either obey, ignore, or misunderstand them. Due to the partially unclear Inter-Client Communication - Conventions Manual (ICCCM), window placement is handled quite + Conventions Manual (ICCCM), window placement is handled differently in existing window managers. X11 provides no standard or easy way to get the frame geometry @@ -115,6 +118,15 @@ depends on the result of QWidget::frameGeometry() and the capability of the window manager to do proper window placement, neither of which can be guaranteed. + + \section2 Wayland Peculiarities + + On Wayland, programmatically setting or getting the position of a top-level window from the + client-side is typically not supported. Technically speaking, it depends on the shell + interface. For typical desktop compositors, however, the default shell interface will be + \c{XDG Shell}, which does not support manual positioning of windows. In such cases, Qt will + ignore calls to set the top-level position of a window, and, when queried, the window position + will always be returned as QPoint(0, 0). */ /*! @@ -128,8 +140,8 @@ \section1 Overview of the Main Window Classes These classes provide everything you need for a typical modern main - application window, like the main window itself, menu and tool bars, - a status bar, etc. + application window, such as the main window itself, menu and tool bars, + and a status bar. \annotatedlist mainwindow-classes @@ -139,8 +151,8 @@ associated user interface components: \list - \li QMainWindow is the central class around which applications - can be built. Along with the companion QDockWidget and QToolBar + \li QMainWindow is the central class around which applications can be + built. Along with the companion QDockWidget and QToolBar classes, it represents the top-level user interface of the application. \li QDockWidget provides a widget that can be used to create @@ -157,11 +169,11 @@ \section1 Example Code - Using QMainWindow is straightforward. Generally, we subclass + Using QMainWindow is straightforward. Generally, you subclass QMainWindow and set up menus, toolbars, and dock widgets inside the QMainWindow constructor. - To add a menu bar to the main window, we simply create the menus, and + To add a menu bar to the main window, create the menus, and add them to the main window's menu bar. Note that the QMainWindow::menuBar() function will automatically create the menu bar the first time it is called. You can also call @@ -172,8 +184,8 @@ \snippet mainwindows/menus/mainwindow.cpp 5 \dots - Once actions have been created, we can add them to the main window - components. To begin with, we add them to the pop-up menus: + Once actions have been created, you can add them to the main window + components. To begin with, add them to the pop-up menus: \snippet mainwindows/menus/mainwindow.cpp 10 \dots @@ -186,7 +198,7 @@ provides this function, making it easy to reuse actions in different parts of the main window. This avoids unnecessary duplication of work. - We create a toolbar as a child of the main window, and add the desired + Create a toolbar as a child of the main window, and add the desired actions to it: \code @@ -203,7 +215,7 @@ newAct and \c openAct will be displayed both on the toolbar and in the file menu. - QDockWidget is used in a similar way to QToolBar. We create a + QDockWidget is used in a similar way to QToolBar. You create a dock widget as a child of the main window, and add widgets as children of the dock widget: @@ -212,7 +224,7 @@ In this example, the dock widget can only be placed in the left and right dock areas, and it is initially placed in the left dock area. - The QMainWindow API allows the programmer to customize which dock + The QMainWindow API lets you customize which dock widget areas occupy the four corners of the dock widget area. If required, the default can be changed with the QMainWindow::setCorner() function: @@ -225,7 +237,7 @@ \image mainwindow-docks-example.png - Once all of the main window components have been set up, the central widget + Once all the main window components have been set up, the central widget is created and installed by using code similar to the following: \snippet code/doc_src_qt4-mainwindow.cpp 3 |
