diff options
Diffstat (limited to 'examples/widgets/doc')
| -rw-r--r-- | examples/widgets/doc/src/addressbook-tutorial.qdoc | 2 | ||||
| -rw-r--r-- | examples/widgets/doc/src/customsortfiltermodel.qdoc | 4 | ||||
| -rw-r--r-- | examples/widgets/doc/src/gallery.qdoc | 36 | ||||
| -rw-r--r-- | examples/widgets/doc/src/icons.qdoc | 38 | ||||
| -rw-r--r-- | examples/widgets/doc/src/padnavigator.qdoc | 21 | ||||
| -rw-r--r-- | examples/widgets/doc/src/shapedclock.qdoc | 52 | ||||
| -rw-r--r-- | examples/widgets/doc/src/styles.qdoc | 10 | ||||
| -rw-r--r-- | examples/widgets/doc/src/transformations.qdoc | 4 |
8 files changed, 105 insertions, 62 deletions
diff --git a/examples/widgets/doc/src/addressbook-tutorial.qdoc b/examples/widgets/doc/src/addressbook-tutorial.qdoc index 1f6966e8ae..563b6a2be9 100644 --- a/examples/widgets/doc/src/addressbook-tutorial.qdoc +++ b/examples/widgets/doc/src/addressbook-tutorial.qdoc @@ -136,7 +136,7 @@ \section1 Defining the AddressBook Class - The \l{tutorials/addressbook/part1/addressbook.h}{\c addressbook.h} file is + The \c{tutorials/addressbook/part1/addressbook.h} file is used to define the \c AddressBook class. We start by defining \c AddressBook as a QWidget subclass and declaring diff --git a/examples/widgets/doc/src/customsortfiltermodel.qdoc b/examples/widgets/doc/src/customsortfiltermodel.qdoc index 9f0d13dd83..97725ead04 100644 --- a/examples/widgets/doc/src/customsortfiltermodel.qdoc +++ b/examples/widgets/doc/src/customsortfiltermodel.qdoc @@ -284,6 +284,6 @@ instance of the QStandardItemModel class, i.e., a generic model for storing custom data typically used as a repository for standard Qt data types. Each mail description is added to the - model using \c addMail(), another convenience function. See \l - {itemviews/customsortfiltermodel/main.cpp}{main.cpp} for details. + model using \c addMail(), another convenience function. See \c + {itemviews/customsortfiltermodel/main.cpp} for details. */ diff --git a/examples/widgets/doc/src/gallery.qdoc b/examples/widgets/doc/src/gallery.qdoc new file mode 100644 index 0000000000..a262374ce6 --- /dev/null +++ b/examples/widgets/doc/src/gallery.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2020 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/gallery + \title Widgets Gallery Example + \ingroup examples-widgets + \brief The Widgets Gallery example shows widgets relevant for designing UIs. + + This example demonstrates widgets typically used in dialogs and forms. + It also allows for changing the style. +*/ diff --git a/examples/widgets/doc/src/icons.qdoc b/examples/widgets/doc/src/icons.qdoc index 7aae0491d6..24be09a7a9 100644 --- a/examples/widgets/doc/src/icons.qdoc +++ b/examples/widgets/doc/src/icons.qdoc @@ -232,8 +232,8 @@ combinations of states and modes for a given icon. \li \c IconSizeSpinBox is a subclass of QSpinBox that lets the user enter icon sizes (e.g., "48 x 48"). - \li \c ImageDelegate is a subclass of QItemDelegate that provides - comboboxes for letting the user set the mode and state + \li \c ImageDelegate is a subclass of QStyledItemDelegate that + provides comboboxes for letting the user set the mode and state associated with an image. \endlist @@ -468,7 +468,6 @@ loaded into the application. \snippet widgets/icons/mainwindow.cpp 13 - \snippet widgets/icons/mainwindow.cpp 14 We retrieve the image name using the QFileInfo::baseName() function that returns the base name of the file without the path, @@ -486,8 +485,6 @@ Qt::ItemIsEditable flag. Table items are editable by default. \snippet widgets/icons/mainwindow.cpp 15 - \snippet widgets/icons/mainwindow.cpp 16 - \snippet widgets/icons/mainwindow.cpp 17 Then we create the second and third items in the row making the default mode Normal and the default state Off. But if the \uicontrol @@ -498,7 +495,6 @@ example's \c images subdirectory respect this naming convention. \snippet widgets/icons/mainwindow.cpp 18 - \snippet widgets/icons/mainwindow.cpp 19 In the end we add the items to the associated row, and use the QTableWidget::openPersistentEditor() function to create @@ -522,8 +518,6 @@ application. \snippet widgets/icons/mainwindow.cpp 8 - \snippet widgets/icons/mainwindow.cpp 9 - \snippet widgets/icons/mainwindow.cpp 10 We also extract the image file's name using the QTableWidgetItem::data() function. This function takes a @@ -571,24 +565,22 @@ delegate for the table widget. We create a \c ImageDelegate that we make the item delegate for our view. - The QItemDelegate class can be used to provide an editor for an item view + The QStyledItemDelegate class can be used to provide an editor for an item view class that is subclassed from QAbstractItemView. Using a delegate for this purpose allows the editing mechanism to be customized and developed independently from the model and view. - In this example we derive \c ImageDelegate from QItemDelegate. - QItemDelegate usually provides line editors, while our subclass + In this example we derive \c ImageDelegate from QStyledItemDelegate. + QStyledItemDelegate usually provides line editors, while our subclass \c ImageDelegate, provides comboboxes for the mode and state fields. \snippet widgets/icons/mainwindow.cpp 22 - \snippet widgets/icons/mainwindow.cpp 23 Then we customize the QTableWidget's horizontal header, and hide the vertical header. \snippet widgets/icons/mainwindow.cpp 24 - \snippet widgets/icons/mainwindow.cpp 25 At the end, we connect the QTableWidget::itemChanged() signal to the \c changeIcon() slot to ensure that the preview area is in @@ -750,23 +742,23 @@ \snippet widgets/icons/imagedelegate.h 0 - The \c ImageDelegate class is a subclass of QItemDelegate. The - QItemDelegate class provides display and editing facilities for - data items from a model. A single QItemDelegate object is + The \c ImageDelegate class is a subclass of QStyledItemDelegate. The + QStyledItemDelegate class provides display and editing facilities for + data items from a model. A single QStyledItemDelegate object is responsible for all items displayed in a item view (in our case, a QTableWidget). - A QItemDelegate can be used to provide an editor for an item view + A QStyledItemDelegate can be used to provide an editor for an item view class that is subclassed from QAbstractItemView. Using a delegate for this purpose allows the editing mechanism to be customized and developed independently from the model and view. \snippet widgets/icons/imagedelegate.h 1 - The default implementation of QItemDelegate creates a QLineEdit. + The default implementation of QStyledItemDelegate creates a QLineEdit. Since we want the editor to be a QComboBox, we need to subclass - QItemDelegate and reimplement the QItemDelegate::createEditor(), - QItemDelegate::setEditorData() and QItemDelegate::setModelData() + QStyledItemDelegate and reimplement the QStyledItemDelegate::createEditor(), + QStyledItemDelegate::setEditorData() and QStyledItemDelegate::setModelData() functions. \snippet widgets/icons/imagedelegate.h 2 @@ -783,7 +775,7 @@ \snippet widgets/icons/imagedelegate.cpp 1 - The default QItemDelegate::createEditor() implementation returns + The default QStyledItemDelegate::createEditor() implementation returns the widget used to edit the item specified by the model and item index for editing. The parent widget and style option are used to control the appearance of the editor widget. @@ -803,7 +795,7 @@ \snippet widgets/icons/imagedelegate.cpp 2 - The QItemDelegate::setEditorData() function is used by + The QStyledItemDelegate::setEditorData() function is used by QTableWidget to transfer data from a QTableWidgetItem to the editor. The data is stored as a string; we use QComboBox::findText() to locate it in the combobox. @@ -816,7 +808,7 @@ \snippet widgets/icons/imagedelegate.cpp 3 - The QItemDelegate::setEditorData() function is used by QTableWidget + The QStyledItemDelegate::setEditorData() function is used by QTableWidget to transfer data back from the editor to the \l{QTableWidgetItem}. \snippet widgets/icons/imagedelegate.cpp 4 diff --git a/examples/widgets/doc/src/padnavigator.qdoc b/examples/widgets/doc/src/padnavigator.qdoc index e59fa3cdbe..d8e83978cf 100644 --- a/examples/widgets/doc/src/padnavigator.qdoc +++ b/examples/widgets/doc/src/padnavigator.qdoc @@ -387,17 +387,12 @@ \snippet graphicsview/padnavigator/padnavigator.cpp 7 We now create the animations that control the flip-effect when you press - the enter key. The main goal is to rotate the pad by 180 degrees or back, - but we also need to make sure the selection item's tilt rotations are reset - back to 0 when the pad is flipped, and restored back to their original - values when flipped back: + the enter key. The main goal is to rotate the pad by 180 degrees or back. \list \li \c smoothFlipRotation: Animates the main 180 degree rotation of the pad. \li \c smoothFlipScale: Scales the pad out and then in again while the pad is rotating. - \li \c smoothFlipXRotation: Animates the selection item's X-tilt to 0 and back. - \li \c smoothFlipYRotation: Animates the selection item's Y-tilt to 0 and back. - \li \c flipAnimation: A parallel animation group that ensures all the above animations are run in parallel. + \li \c flipAnimation: A parallel animation group that ensures the above animations are run in parallel. \endlist All animations are given a 500 millisecond duration and an @@ -447,11 +442,17 @@ Each state assigns specific properties to objects on entry. Most interesting perhaps is the assignment of the value 0.0 to the pad's \c flipRotation angle property when in \c frontState, and 180.0 when in \c - backState. At the end of this section we register default animations with - the state engine; these animations will apply to their respective objects - and properties for any state transition. Otherwise it's common to assign + backState. + + At the end of this section we register default animations with the state + engine; these animations will apply to their respective objects and + properties for any state transition. Otherwise it's common to assign animations to specific transitions. + Specifically, we use default animations to control the selection item's + movement and tilt rotations. The tilt rotations are set to 0 when the pad + is flipped, and restored back to their original values when flipped back. + The \c splashState state is set as the initial state. This is required before we start the state engine. We proceed with creating some transitions. diff --git a/examples/widgets/doc/src/shapedclock.qdoc b/examples/widgets/doc/src/shapedclock.qdoc index 2e5d8b1496..732820cdc8 100644 --- a/examples/widgets/doc/src/shapedclock.qdoc +++ b/examples/widgets/doc/src/shapedclock.qdoc @@ -29,16 +29,18 @@ \example widgets/shapedclock \title Shaped Clock Example \ingroup examples-widgets - \brief The Shaped Clock example shows how to apply a widget mask to a top-level - widget to produce a shaped window. + \brief The Shaped Clock example shows how to apply a translucent background + and a widget mask to a top-level widget to produce a shaped window. \borderedimage shapedclock-example.png - Widget masks are used to customize the shapes of top-level widgets by restricting - the available area for painting. On some window systems, setting certain window flags - will cause the window decoration (title bar, window frame, buttons) to be disabled, - allowing specially-shaped windows to be created. In this example, we use this feature - to create a circular window containing an analog clock. + Widget masks are used to customize the shapes of top-level widgets by + restricting the area available for painting and mouse input. Using a + translucent background facilitates partially transparent windows and smooth + edges. On most window systems, setting certain window flags will cause the + window decoration (title bar, window frame, buttons) to be disabled, + allowing specially-shaped windows to be created. In this example, we use + this feature to create a circular window containing an analog clock. Since this example's window does not provide a \uicontrol File menu or a close button, we provide a context menu with an \uicontrol Exit entry so that the example @@ -52,8 +54,10 @@ \snippet widgets/shapedclock/shapedclock.h 0 - The \l{QWidget::paintEvent()}{paintEvent()} implementation is the same as that found - in the \c AnalogClock class. We implement \l{QWidget::sizeHint()}{sizeHint()} + The \l{QWidget::paintEvent()}{paintEvent()} implementation is the same as + that found in the \c AnalogClock class, with one important exception: we + now must also draw background (the clock face) ourselves, since the widget + background is just transparent. We implement \l{QWidget::sizeHint()}{sizeHint()} so that we don't have to resize the widget explicitly. We also provide an event handler for resize events. This allows us to update the mask if the clock is resized. @@ -70,9 +74,11 @@ \snippet widgets/shapedclock/shapedclock.cpp 0 - We inform the window manager that the widget is not to be decorated with a window - frame by setting the Qt::FramelessWindowHint flag on the widget. As a result, we need - to provide a way for the user to move the clock around the screen. + We request a transparent window by setting the Qt::WA_TranslucentBackground + widget attribute. We inform the window manager that the widget is not to be + decorated with a window frame by setting the Qt::FramelessWindowHint flag + on the widget. As a result, we need to provide a way for the user to move + the clock around the screen. Mouse button events are delivered to the \c mousePressEvent() handler: @@ -94,14 +100,20 @@ widget is moved to the point given by subtracting the \c dragPosition from the current cursor position in global coordinates. If we drag the widget, we also accept the event. - The \c paintEvent() function is given for completeness. See the - \l{Analog Clock Example}{Analog Clock} example for a description of the process used - to render the clock. + The \c paintEvent() function is mainly the same as described in the + \l{Analog Clock Example}{Analog Clock} example. The one addition is that we + use QPainter::drawEllipse() to draw a round clock face with the current + palette's default background color. We make the clock face a bit smaller + than the widget mask, so that the anti-aliased, semi-transparent pixels on + the edge are not clipped away by the widget mask. This gives the shaped + window smooth edges on the screen. \snippet widgets/shapedclock/shapedclock.cpp 3 - In the \c resizeEvent() handler, we re-use some of the code from the \c paintEvent() - to determine the region of the widget that is visible to the user: + In the \c resizeEvent() handler, we re-use some of the code from the \c + paintEvent() to determine the region of the widget that is visible to the + user. This tells the system the area where mouse clicks should go to us, + and not to whatever window is behind us: \snippet widgets/shapedclock/shapedclock.cpp 4 @@ -121,6 +133,12 @@ \section1 Notes on Widget Masks + Widget masks are used to hint to the window system that the application + does not want mouse events for areas outside the mask. On most systems, + they also result in coarse visual clipping. To get smooth window edges, one + should use translucent background and anti-aliased painting, as shown in + this example. + Since QRegion allows arbitrarily complex regions to be created, widget masks can be made to suit the most unconventionally-shaped windows, and even allow widgets to be displayed with holes in them. diff --git a/examples/widgets/doc/src/styles.qdoc b/examples/widgets/doc/src/styles.qdoc index 4fea8f3bfc..014541a330 100644 --- a/examples/widgets/doc/src/styles.qdoc +++ b/examples/widgets/doc/src/styles.qdoc @@ -84,8 +84,8 @@ \snippet widgets/styles/norwegianwoodstyle.cpp 0 - The \c polish() function is reimplemented from QStyle. It takes a - QPalette as a reference and adapts the palette to fit the style. + The \c standardPalette() function is reimplemented from QStyle. + It returns a QPalette with the style's preferred colors and textures. Most styles don't need to reimplement that function. The Norwegian Wood style reimplements it to set a "wooden" palette. @@ -380,7 +380,7 @@ a certain \l{QPalette::ColorRole}{color role}, for all three \l{QPalette::ColorGroup}{color groups} (active, disabled, inactive). We used it to initialize the Norwegian Wood palette in - \c polish(QPalette &). + \c standardPalette. \snippet widgets/styles/norwegianwoodstyle.cpp 39 \snippet widgets/styles/norwegianwoodstyle.cpp 40 @@ -443,10 +443,6 @@ current style's \l{QStyle::standardPalette()}{standard palette} is used; otherwise, the system's default palette is honored. - For the Norwegian Wood style, this makes no difference because we - always override the palette with our own palette in \c - NorwegianWoodStyle::polish(). - \snippet widgets/styles/widgetgallery.cpp 9 \snippet widgets/styles/widgetgallery.cpp 10 diff --git a/examples/widgets/doc/src/transformations.qdoc b/examples/widgets/doc/src/transformations.qdoc index d67e315848..17b540b6cc 100644 --- a/examples/widgets/doc/src/transformations.qdoc +++ b/examples/widgets/doc/src/transformations.qdoc @@ -320,8 +320,8 @@ The \c setupShapes() function is called from the constructor and create the QPainterPath objects representing the shapes that are - used in the application. For construction details, see the \l - {painting/transformations/window.cpp}{window.cpp} example + used in the application. For construction details, see the \c + {painting/transformations/window.cpp} example file. The shapes are stored in a QList. The QList::append() function inserts the given shape at the end of the list. |