summaryrefslogtreecommitdiffstats
path: root/examples/widgets/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'examples/widgets/doc/src')
-rw-r--r--examples/widgets/doc/src/addressbook-tutorial.qdoc972
-rw-r--r--examples/widgets/doc/src/addressbook.qdoc47
-rw-r--r--examples/widgets/doc/src/affine.qdoc31
-rw-r--r--examples/widgets/doc/src/analogclock.qdoc113
-rw-r--r--examples/widgets/doc/src/application.qdoc395
-rw-r--r--examples/widgets/doc/src/basicdrawing.qdoc29
-rw-r--r--examples/widgets/doc/src/basicgraphicslayouts.qdoc29
-rw-r--r--examples/widgets/doc/src/basiclayouts.qdoc29
-rw-r--r--examples/widgets/doc/src/basicsortfiltermodel.qdoc29
-rw-r--r--examples/widgets/doc/src/blurpicker.qdoc44
-rw-r--r--examples/widgets/doc/src/borderlayout.qdoc70
-rw-r--r--examples/widgets/doc/src/calculator.qdoc29
-rw-r--r--examples/widgets/doc/src/calendar.qdoc226
-rw-r--r--examples/widgets/doc/src/calendarwidget.qdoc29
-rw-r--r--examples/widgets/doc/src/charactermap.qdoc275
-rw-r--r--examples/widgets/doc/src/chart.qdoc82
-rw-r--r--examples/widgets/doc/src/chip.qdoc29
-rw-r--r--examples/widgets/doc/src/classwizard.qdoc191
-rw-r--r--examples/widgets/doc/src/codeeditor.qdoc197
-rw-r--r--examples/widgets/doc/src/collidingmice-example.qdoc31
-rw-r--r--examples/widgets/doc/src/coloreditorfactory.qdoc41
-rw-r--r--examples/widgets/doc/src/combowidgetmapper.qdoc49
-rw-r--r--examples/widgets/doc/src/completer.qdoc33
-rw-r--r--examples/widgets/doc/src/composition.qdoc31
-rw-r--r--examples/widgets/doc/src/concentriccircles.qdoc233
-rw-r--r--examples/widgets/doc/src/cuberhiwidget.qdoc170
-rw-r--r--examples/widgets/doc/src/customsortfiltermodel.qdoc29
-rw-r--r--examples/widgets/doc/src/deform.qdoc29
-rw-r--r--examples/widgets/doc/src/diagramscene.qdoc37
-rw-r--r--examples/widgets/doc/src/digitalclock.qdoc75
-rw-r--r--examples/widgets/doc/src/dirview.qdoc73
-rw-r--r--examples/widgets/doc/src/dockwidgets.qdoc164
-rw-r--r--examples/widgets/doc/src/draganddroppuzzle.qdoc42
-rw-r--r--examples/widgets/doc/src/dragdroprobot.qdoc31
-rw-r--r--examples/widgets/doc/src/draggableicons.qdoc29
-rw-r--r--examples/widgets/doc/src/draggabletext.qdoc29
-rw-r--r--examples/widgets/doc/src/dynamiclayouts.qdoc115
-rw-r--r--examples/widgets/doc/src/easing.qdoc29
-rw-r--r--examples/widgets/doc/src/echoplugin.qdoc205
-rw-r--r--examples/widgets/doc/src/editabletreemodel.qdoc82
-rw-r--r--examples/widgets/doc/src/elasticnodes.qdoc33
-rw-r--r--examples/widgets/doc/src/elidedlabel.qdoc155
-rw-r--r--examples/widgets/doc/src/embeddeddialogs.qdoc39
-rw-r--r--examples/widgets/doc/src/extension.qdoc145
-rw-r--r--examples/widgets/doc/src/fademessage.qdoc39
-rw-r--r--examples/widgets/doc/src/fetchmore.qdoc46
-rw-r--r--examples/widgets/doc/src/findfiles.qdoc293
-rw-r--r--examples/widgets/doc/src/flowlayout.qdoc29
-rw-r--r--examples/widgets/doc/src/fontsampler.qdoc37
-rw-r--r--examples/widgets/doc/src/fridgemagnets.qdoc362
-rw-r--r--examples/widgets/doc/src/frozencolumn.qdoc31
-rw-r--r--examples/widgets/doc/src/gallery.qdoc29
-rw-r--r--examples/widgets/doc/src/gradients.qdoc29
-rw-r--r--examples/widgets/doc/src/graphicsview-anchorlayout.qdoc81
-rw-r--r--examples/widgets/doc/src/graphicsview-flowlayout.qdoc52
-rw-r--r--examples/widgets/doc/src/graphicsview-simpleanchorlayout.qdoc31
-rw-r--r--examples/widgets/doc/src/graphicsview-weatheranchorlayout.qdoc38
-rw-r--r--examples/widgets/doc/src/groupbox.qdoc29
-rw-r--r--examples/widgets/doc/src/i18n.qdoc40
-rw-r--r--examples/widgets/doc/src/icons.qdoc829
-rw-r--r--examples/widgets/doc/src/imagecomposition.qdoc29
-rw-r--r--examples/widgets/doc/src/imageviewer.qdoc344
-rw-r--r--examples/widgets/doc/src/interview.qdoc39
-rw-r--r--examples/widgets/doc/src/itemviewspuzzle.qdoc43
-rw-r--r--examples/widgets/doc/src/licensewizard.qdoc33
-rw-r--r--examples/widgets/doc/src/lineedits.qdoc29
-rw-r--r--examples/widgets/doc/src/mainwindow.qdoc37
-rw-r--r--examples/widgets/doc/src/mdi.qdoc38
-rw-r--r--examples/widgets/doc/src/menus.qdoc32
-rw-r--r--examples/widgets/doc/src/movie.qdoc40
-rw-r--r--examples/widgets/doc/src/orderform.qdoc29
-rw-r--r--examples/widgets/doc/src/painterpaths.qdoc40
-rw-r--r--examples/widgets/doc/src/pathstroke.qdoc29
-rw-r--r--examples/widgets/doc/src/pixelator.qdoc255
-rw-r--r--examples/widgets/doc/src/plugandpaint.qdoc551
-rw-r--r--examples/widgets/doc/src/regularexpression.qdoc29
-rw-r--r--examples/widgets/doc/src/screenshot.qdoc31
-rw-r--r--examples/widgets/doc/src/scribble.qdoc29
-rw-r--r--examples/widgets/doc/src/sdi.qdoc37
-rw-r--r--examples/widgets/doc/src/settingseditor.qdoc38
-rw-r--r--examples/widgets/doc/src/shapedclock.qdoc104
-rw-r--r--examples/widgets/doc/src/shortcuteditor.qdoc231
-rw-r--r--examples/widgets/doc/src/simpledommodel.qdoc280
-rw-r--r--examples/widgets/doc/src/simplerhiwidget.qdoc204
-rw-r--r--examples/widgets/doc/src/simpletreemodel.qdoc79
-rw-r--r--examples/widgets/doc/src/simplewidgetmapper.qdoc125
-rw-r--r--examples/widgets/doc/src/sliders.qdoc117
-rw-r--r--examples/widgets/doc/src/spinboxdelegate.qdoc141
-rw-r--r--examples/widgets/doc/src/spinboxes.qdoc29
-rw-r--r--examples/widgets/doc/src/spreadsheet.qdoc29
-rw-r--r--examples/widgets/doc/src/standarddialogs.qdoc29
-rw-r--r--examples/widgets/doc/src/stardelegate.qdoc29
-rw-r--r--examples/widgets/doc/src/styleplugin.qdoc138
-rw-r--r--examples/widgets/doc/src/styles.qdoc472
-rw-r--r--examples/widgets/doc/src/stylesheet.qdoc88
-rw-r--r--examples/widgets/doc/src/syntaxhighlighter.qdoc35
-rw-r--r--examples/widgets/doc/src/tabdialog.qdoc29
-rw-r--r--examples/widgets/doc/src/tablet.qdoc37
-rw-r--r--examples/widgets/doc/src/tetrix.qdoc431
-rw-r--r--examples/widgets/doc/src/textedit.qdoc39
-rw-r--r--examples/widgets/doc/src/tooltips.qdoc394
-rw-r--r--examples/widgets/doc/src/transformations.qdoc43
-rw-r--r--examples/widgets/doc/src/treemodelcompleter.qdoc29
-rw-r--r--examples/widgets/doc/src/trivialwizard.qdoc31
-rw-r--r--examples/widgets/doc/src/undo.qdoc44
-rw-r--r--examples/widgets/doc/src/undoframework.qdoc70
-rw-r--r--examples/widgets/doc/src/validators.qdoc35
-rw-r--r--examples/widgets/doc/src/wiggly.qdoc168
-rw-r--r--examples/widgets/doc/src/windowflags.qdoc29
109 files changed, 1031 insertions, 10980 deletions
diff --git a/examples/widgets/doc/src/addressbook-tutorial.qdoc b/examples/widgets/doc/src/addressbook-tutorial.qdoc
deleted file mode 100644
index 563b6a2be9..0000000000
--- a/examples/widgets/doc/src/addressbook-tutorial.qdoc
+++ /dev/null
@@ -1,972 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
-
-/*!
- \page tutorials-addressbook.html
-
- \title Address Book Tutorial
- \ingroup examples-layout
- \brief An introduction to GUI programming, showing how to put together a
- simple yet fully-functioning application.
-
- This tutorial is an introduction to GUI programming with the Qt
- cross-platform framework.
-
- \image addressbook-tutorial-screenshot.png
-
- \omit
- It doesn't cover everything; the emphasis is on teaching the programming
- philosophy of GUI programming, and Qt's features are introduced as needed.
- Some commonly used features are never used in this tutorial.
- \endomit
-
- In this tutorial, you will learn about some of the basic
- components of Qt, including:
-
- \list
- \li Widgets and layout managers
- \li Container classes
- \li Signals and slots
- \li Input and output devices
- \endlist
-
- Tutorial contents:
-
- \list 1
- \li \l{tutorials/addressbook/part1}{Designing the User Interface}
- \li \l{tutorials/addressbook/part2}{Adding Addresses}
- \li \l{tutorials/addressbook/part3}{Navigating between Entries}
- \li \l{tutorials/addressbook/part4}{Editing and Removing Addresses}
- \li \l{tutorials/addressbook/part5}{Adding a Find Function}
- \li \l{tutorials/addressbook/part6}{Loading and Saving}
- \li \l{tutorials/addressbook/part7}{Additional Features}
- \endlist
-
- The tutorial source code is located in \c{tutorials/addressbook}.
-
- Although this little application does not look much like a
- fully-fledged modern GUI application, it uses many of the basic
- elements that are used in more complex applications. After you
- have worked through this tutorial, we recommend reading the
- \l{mainwindows/application}{Application} example, which presents a
- small GUI application, with menus, toolbars, a status bar, and so
- on.
-*/
-
-/*!
- \example tutorials/addressbook/part1
- \title Part 1 - Designing the User Interface
- \brief Describes how to code the user interface of the Address Book Example.
- This first part covers the design of the basic graphical user
- interface (GUI) for our address book application.
-
- The first step in creating a GUI program is to design the user
- interface. Here the our goal is to set up the labels and input
- fields to implement a basic address book. The figure below is a
- screenshot of the expected output.
-
- \image addressbook-tutorial-part1-screenshot.png
-
- We require two QLabel objects, \c nameLabel and \c addressLabel, as well
- as two input fields, a QLineEdit object, \c nameLine, and a QTextEdit
- object, \c addressText, to enable the user to enter a contact's name and
- address. The widgets used and their positions are shown in the figure
- below.
-
- \image addressbook-tutorial-part1-labeled-screenshot.png
-
- There are three files used to implement this address book:
-
- \list
- \li \c{addressbook.h} - the definition file for the \c AddressBook
- class,
- \li \c{addressbook.cpp} - the implementation file for the
- \c AddressBook class, and
- \li \c{main.cpp} - the file containing a \c main() function, with
- an instance of \c AddressBook.
- \endlist
-
- \section1 Qt Programming - Subclassing
-
- When writing Qt programs, we usually subclass Qt objects to add
- functionality. This is one of the essential concepts behind creating
- custom widgets or collections of standard widgets. Subclassing to
- extend or change the behavior of a widget has the following advantages:
-
- \list
- \li We can write implementations of virtual or pure virtual functions to
- obtain exactly what we need, falling back on the base class's implementation
- when necessary.
- \li It allows us to encapsulate parts of the user interface within a class,
- so that the other parts of the application don't need to know about the
- individual widgets in the user interface.
- \li The subclass can be used to create multiple custom widgets in the same
- application or library, and the code for the subclass can be reused in other
- projects.
- \endlist
-
- Since Qt does not provide a specific address book widget, we subclass a
- standard Qt widget class and add features to it. The \c AddressBook class
- we create in this tutorial can be reused in situations where a basic address
- book widget is needed.
-
- \section1 Defining the AddressBook Class
-
- 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
- a constructor. We also use the Q_OBJECT macro to indicate that the class
- uses internationalization and Qt's signals and slots features, even
- if we do not use all of these features at this stage.
-
- \snippet tutorials/addressbook/part1/addressbook.h class definition
-
- The class holds declarations of \c nameLine and \c addressText,
- the private instances of QLineEdit and QTextEdit mentioned
- earlier. The data stored in \c nameLine and \c addressText will
- be needed for many of the address book functions.
-
- We don't include declarations of the QLabel objects we will use
- because we will not need to reference them once they have been
- created. The way Qt tracks the ownership of objects is explained
- in the next section.
-
- The Q_OBJECT macro itself implements some of the more advanced features of Qt.
- For now, it is useful to think of the Q_OBJECT macro as a shortcut which allows
- us to use the \l{QObject::}{tr()} and \l{QObject::}{connect()} functions.
-
- We have now completed the \c addressbook.h file and we move on to
- implement the corresponding \c addressbook.cpp file.
-
- \section1 Implementing the AddressBook Class
-
- The constructor of \c AddressBook accepts a QWidget parameter, \a parent.
- By convention, we pass this parameter to the base class's constructor.
- This concept of ownership, where a parent can have one or more children,
- is useful for grouping widgets in Qt. For example, if you delete a parent,
- all of its children will be deleted as well.
-
- \snippet tutorials/addressbook/part1/addressbook.cpp constructor and input fields
-
- In this constructor, the QLabel objects \c nameLabel and \c
- addressLabel are instantiated, as well as \c nameLine and \c
- addressText. The \l{QObject::tr()}{tr()} function returns a
- translated version of the string, if there is one
- available. Otherwise it returns the string itself. This function
- marks its QString parameter as one that should be translated into
- other languages. It should be used wherever a translatable string
- appears.
-
- When programming with Qt, it is useful to know how layouts work.
- Qt provides three main layout classes: QHBoxLayout, QVBoxLayout
- and QGridLayout to handle the positioning of widgets.
-
- \image addressbook-tutorial-part1-labeled-layout.png
-
- We use a QGridLayout to position our labels and input fields in a
- structured manner. QGridLayout divides the available space into a grid and
- places widgets in the cells we specify with row and column numbers. The
- diagram above shows the layout cells and the position of our widgets, and
- we specify this arrangement using the following code:
-
- \snippet tutorials/addressbook/part1/addressbook.cpp layout
-
- Notice that \c addressLabel is positioned using Qt::AlignTop as an
- additional argument. This is to make sure it is not vertically centered in
- cell (1,0). For a basic overview on Qt Layouts, refer to the
- \l{Layout Management} documentation.
-
- In order to install the layout object onto the widget, we have to invoke
- the widget's \l{QWidget::setLayout()}{setLayout()} function:
-
- \snippet tutorials/addressbook/part1/addressbook.cpp setting the layout
-
- Lastly, we set the widget's title to "Simple Address Book".
-
- \section1 Running the Application
-
- A separate file, \c main.cpp, is used for the \c main() function. Within
- this function, we instantiate a QApplication object, \c app. QApplication
- is responsible for various application-wide resources, such as the default
- font and cursor, and for running an event loop. Hence, there is always one
- QApplication object in every GUI application using Qt.
-
- \snippet tutorials/addressbook/part1/main.cpp main function
-
- We construct a new \c AddressBook widget on the stack and invoke
- its \l{QWidget::show()}{show()} function to display it.
- However, the widget will not be shown until the application's event loop
- is started. We start the event loop by calling the application's
- \l{QApplication::}{exec()} function; the result returned by this function
- is used as the return value from the \c main() function. At this point,
- it becomes apparent why we instanciated \c AddressBook on the stack: It
- will now go out of scope. Therefore, \c AddressBook and all its child widgets
- will be deleted, thus preventing memory leaks.
-*/
-
-/*!
- \example tutorials/addressbook/part2
- \title Part 2 - Adding Addresses
- \brief Describes the code for inserting records in the Address Book Example.
-
- The next step in creating the address book is to implement some
- user interactions.
-
- \image addressbook-tutorial-part2-add-contact.png
-
- We will provide a push button that the user can click to add a new contact.
- Also, some form of data structure is needed to store these contacts in an
- organized way.
-
- \section1 Defining the AddressBook Class
-
- Now that we have the labels and input fields set up, we add push buttons to
- complete the process of adding a contact. This means that our
- \c addressbook.h file now has three QPushButton objects declared and three
- corresponding public slots.
-
- \snippet tutorials/addressbook/part2/addressbook.h slots
-
- A slot is a function that responds to a particular signal. We will discuss
- this concept in further detail when implementing the \c AddressBook class.
- However, for an overview of Qt's signals and slots concept, you can refer
- to the \l{Signals and Slots} document.
-
- Three QPushButton objects (\c addButton, \c submitButton, and
- \c cancelButton) are now included in our private variable declarations,
- along with \c nameLine and \c addressText.
-
- \snippet tutorials/addressbook/part2/addressbook.h pushbutton declaration
-
- We need a container to store our address book contacts, so that we can
- traverse and display them. A QMap object, \c contacts, is used for this
- purpose as it holds a key-value pair: the contact's name as the \e key,
- and the contact's address as the \e{value}.
-
- \snippet tutorials/addressbook/part2/addressbook.h remaining private variables
-
- We also declare two private QString objects, \c oldName and \c oldAddress.
- These objects are needed to hold the name and address of the contact that
- was last displayed, before the user clicked \uicontrol Add. So, when the user clicks
- \uicontrol Cancel, we can revert to displaying the details of the last contact.
-
- \section1 Implementing the AddressBook Class
-
- Within the constructor of \c AddressBook, we set the \c nameLine and
- \c addressText to read-only, so that we can only display but not edit
- existing contact details.
-
- \dots
- \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 1
- \dots
- \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 2
-
- Then, we instantiate our push buttons: \c addButton, \c submitButton, and
- \c cancelButton.
-
- \snippet tutorials/addressbook/part2/addressbook.cpp pushbutton declaration
-
- The \c addButton is displayed by invoking the \l{QPushButton::show()}
- {show()} function, while the \c submitButton and \c cancelButton are
- hidden by invoking \l{QPushButton::hide()}{hide()}. These two push
- buttons will only be displayed when the user clicks \uicontrol Add and this is
- handled by the \c addContact() function discussed below.
-
- \snippet tutorials/addressbook/part2/addressbook.cpp connecting signals and slots
-
- We connect the push buttons' \l{QPushButton::clicked()}{clicked()} signal
- to their respective slots. The figure below illustrates this.
-
- \image addressbook-tutorial-part2-signals-and-slots.png
-
- Next, we arrange our push buttons neatly to the right of our address book
- widget, using a QVBoxLayout to line them up vertically.
-
- \snippet tutorials/addressbook/part2/addressbook.cpp vertical layout
-
- The \l{QBoxLayout::addStretch()}{addStretch()} function is used to ensure
- the push buttons are not evenly spaced, but arranged closer to the top of
- the widget. The figure below shows the difference between using
- \l{QBoxLayout::addStretch()}{addStretch()} and not using it.
-
- \image addressbook-tutorial-part2-stretch-effects.png
-
- We then add \c buttonLayout1 to \c mainLayout, using
- \l{QGridLayout::addLayout()}{addLayout()}. This gives us nested layouts
- as \c buttonLayout1 is now a child of \c mainLayout.
-
- \snippet tutorials/addressbook/part2/addressbook.cpp grid layout
-
- Our layout coordinates now look like this:
-
- \image addressbook-tutorial-part2-labeled-layout.png
-
- In the \c addContact() function, we store the last displayed contact
- details in \c oldName and \c oldAddress. Then we clear these input
- fields and turn off the read-only mode. The focus is set on \c nameLine
- and we display \c submitButton and \c cancelButton.
-
- \snippet tutorials/addressbook/part2/addressbook.cpp addContact
-
- The \c submitContact() function can be divided into three parts:
-
- \list 1
- \li We extract the contact's details from \c nameLine and \c addressText
- and store them in QString objects. We also validate to make sure that the
- user did not click \uicontrol Submit with empty input fields; otherwise, a
- QMessageBox is displayed to remind the user for a name and address.
-
- \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part1
-
- \li We then proceed to check if the contact already exists. If it does not
- exist, we add the contact to \c contacts and we display a QMessageBox to
- inform the user that the contact has been added.
-
- \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part2
-
- If the contact already exists, again, we display a QMessageBox to inform
- the user about this, preventing the user from adding duplicate contacts.
- Our \c contacts object is based on key-value pairs of name and address,
- hence, we want to ensure that \e key is unique.
-
- \li Once we have handled both cases mentioned above, we restore the push
- buttons to their normal state with the following code:
-
- \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part3
-
- \endlist
-
- The screenshot below shows the QMessageBox object we use to display
- information messages to the user.
-
- \image addressbook-tutorial-part2-add-successful.png
-
- The \c cancel() function restores the last displayed contact details and
- enables \c addButton, as well as hides \c submitButton and
- \c cancelButton.
-
- \snippet tutorials/addressbook/part2/addressbook.cpp cancel
-
- The general idea behind adding a contact is to give the user the
- flexibility to click \uicontrol Submit or \uicontrol Cancel at any time. The flowchart below
- further explains this concept:
-
- \image addressbook-tutorial-part2-add-flowchart.png
-*/
-
-/*!
- \example tutorials/addressbook/part3
- \title Part 3 - Navigating between Entries
- \brief Explains the code that enables navigating the contacts.
-
- The address book is now about half complete. We should add the
- capability to navigate the contacts, but first we must
- decide what sort of a data structure we need for containing these
- contacts.
-
- In the previous section, we used a QMap of key-value pairs with
- the contact's name as the \e key, and the contact's address as the
- \e value. This works well for our case. However, in order to
- navigate and display each entry, a little bit of enhancement is
- needed.
-
- We enhance the QMap by making it replicate a data structure similar to a
- circularly-linked list, where all elements are connected, including the
- first element and the last element. The figure below illustrates this data
- structure.
-
- \image addressbook-tutorial-part3-linkedlist.png
-
- \section1 Defining the AddressBook Class
-
- To add navigation functions to the address book, we must add two
- more slots to the \c AddressBook class: \c next() and \c
- previous() to the \c addressbook.h file:
-
- \snippet tutorials/addressbook/part3/addressbook.h navigation functions
-
- We also require another two QPushButton objects, so we declare \c nextButton
- and \c previousButton as private variables:
-
- \snippet tutorials/addressbook/part3/addressbook.h navigation pushbuttons
-
- \section1 Implementing the AddressBook Class
-
- In the \c AddressBook constructor in \c addressbook.cpp, we instantiate
- \c nextButton and \c previousButton and disable them by default. This is
- because navigation is only enabled when there is more than one contact
- in the address book.
-
- \snippet tutorials/addressbook/part3/addressbook.cpp navigation pushbuttons
-
- We then connect these push buttons to their respective slots:
-
- \snippet tutorials/addressbook/part3/addressbook.cpp connecting navigation signals
-
- The image below is the expected graphical user interface.
-
- \image addressbook-tutorial-part3-screenshot.png
-
- We follow basic conventions for \c next() and \c previous() functions by
- placing the \c nextButton on the right and the \c previousButton on the
- left. In order to achieve this intuitive layout, we use QHBoxLayout to
- place the widgets side-by-side:
-
- \snippet tutorials/addressbook/part3/addressbook.cpp navigation layout
-
- The QHBoxLayout object, \c buttonLayout2, is then added to \c mainLayout.
-
- \snippet tutorials/addressbook/part3/addressbook.cpp adding navigation layout
-
- The figure below shows the coordinates of the widgets in \c mainLayout.
- \image addressbook-tutorial-part3-labeled-layout.png
-
- Within our \c addContact() function, we have to disable these buttons so
- that the user does not attempt to navigate while adding a contact.
-
- \snippet tutorials/addressbook/part3/addressbook.cpp disabling navigation
-
- Also, in our \c submitContact() function, we enable the navigation
- buttons, \c nextButton and \c previousButton, depending on the size
- of \c contacts. As mentioned earlier, navigation is only enabled when
- there is more than one contact in the address book. The following lines
- of code demonstrates how to do this:
-
- \snippet tutorials/addressbook/part3/addressbook.cpp enabling navigation
-
- We also include these lines of code in the \c cancel() function.
-
- Recall that we intend to emulate a circularly-linked list with our QMap
- object, \c contacts. So, in the \c next() function, we obtain an iterator
- for \c contacts and then:
-
- \list
- \li If the iterator is not at the end of \c contacts, we increment it
- by one.
- \li If the iterator is at the end of \c contacts, we move it to the
- beginning of \c contacts. This gives us the illusion that our QMap is
- working like a circularly-linked list.
- \endlist
-
- \snippet tutorials/addressbook/part3/addressbook.cpp next() function
-
- Once we have iterated to the correct object in \c contacts, we display
- its contents on \c nameLine and \c addressText.
-
- Similarly, for the \c previous() function, we obtain an iterator for
- \c contacts and then:
-
- \list
- \li If the iterator is at the end of \c contacts, we clear the
- display and return.
- \li If the iterator is at the beginning of \c contacts, we move it to
- the end.
- \li We then decrement the iterator by one.
- \endlist
-
- \snippet tutorials/addressbook/part3/addressbook.cpp previous() function
-
- Again, we display the contents of the current object in \c contacts.
-
-*/
-
-/*!
- \example tutorials/addressbook/part4
- \title Part 4 - Editing and Removing Addresses
- \brief Explains how to add edit and remove functionality.
-
- Now we look at ways to modify the contents of contacts stored in
- the address book.
-
- \image addressbook-tutorial-screenshot.png
-
- We now have an address book that not only holds contacts in an
- organized manner, but also allows navigation. It would be
- convenient to include edit and remove functions so that a
- contact's details can be changed when needed. However, this
- requires a little improvement, in the form of enums. We defined
- two modes: \c{AddingMode} and \c{NavigationMode}, but they were
- not defined as enum values. Instead, we enabled and disabled the
- corresponding buttons manually, resulting in multiple lines of
- repeated code.
-
- Here we define the \c Mode enum with three different values:
-
- \list
- \li \c{NavigationMode},
- \li \c{AddingMode}, and
- \li \c{EditingMode}.
- \endlist
-
- \section1 Defining the AddressBook Class
-
- The \c addressbook.h file is updated to contain the \c Mode enum:
-
- \snippet tutorials/addressbook/part4/addressbook.h Mode enum
-
- We also add two new slots, \c editContact() and \c removeContact(), to
- our current list of public slots.
-
- \snippet tutorials/addressbook/part4/addressbook.h edit and remove slots
-
- In order to switch between modes, we introduce the \c updateInterface() function
- to control the enabling and disabling of all QPushButton objects. We also
- add two new push buttons, \c editButton and \c removeButton, for the edit
- and remove functions mentioned earlier.
-
- \snippet tutorials/addressbook/part4/addressbook.h updateInterface() declaration
- \dots
- \snippet tutorials/addressbook/part4/addressbook.h buttons declaration
- \dots
- \snippet tutorials/addressbook/part4/addressbook.h mode declaration
-
- Lastly, we declare \c currentMode to keep track of the enum's current mode.
-
- \section1 Implementing the AddressBook Class
-
- We now implement the mode-changing features of the address
- book. The \c editButton and \c removeButton are instantiated and
- disabled by default. The address book starts with zero contacts
- in memory.
-
- \snippet tutorials/addressbook/part4/addressbook.cpp edit and remove buttons
-
- These buttons are then connected to their respective slots, \c editContact()
- and \c removeContact(), and we add them to \c buttonLayout1.
-
- \snippet tutorials/addressbook/part4/addressbook.cpp connecting edit and remove
- \dots
- \snippet tutorials/addressbook/part4/addressbook.cpp adding edit and remove to the layout
-
- The \c editContact() function stores the contact's old details in
- \c oldName and \c oldAddress, before switching the mode to \c EditingMode.
- In this mode, the \c submitButton and \c cancelButton are both enabled,
- hence, the user can change the contact's details and click either button.
-
- \snippet tutorials/addressbook/part4/addressbook.cpp editContact() function
-
- The \c submitContact() function has been divided in two with an \c{if-else}
- statement. We check \c currentMode to see if it's in \c AddingMode. If it is,
- we proceed with our adding process.
-
- \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function beginning
- \dots
- \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part1
-
- Otherwise, we check to see if \c currentMode is in \c EditingMode. If it
- is, we compare \c oldName with \c name. If the name has changed, we remove
- the old contact from \c contacts and insert the newly updated contact.
-
- \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part2
-
- If only the address has changed (i.e., \c oldAddress is not the same as \c address),
- we update the contact's address. Lastly, we set \c currentMode to
- \c NavigationMode. This is an important step as it re-enables all the
- disabled push buttons.
-
- To remove a contact from the address book, we implement the
- \c removeContact() function. This function checks to see if the contact
- exists in \c contacts.
-
- \snippet tutorials/addressbook/part4/addressbook.cpp removeContact() function
-
- If it does, we display a QMessageBox, to confirm the removal with the
- user. Once the user has confirmed, we call \c previous() to ensure that the
- user interface shows another contact, and we remove the contact using \l{QMap}'s
- \l{QMap::remove()}{remove()} function. As a courtesy, we display a QMessageBox
- to inform the user. Both the message boxes used in this function are shown below:
-
- \image addressbook-tutorial-part4-remove.png
-
- \section2 Updating the User Interface
-
- We mentioned the \c updateInterface() function earlier as a means to
- enable and disable the push buttons depending on the current mode.
- The function updates the current mode according to the \c mode argument
- passed to it, assigning it to \c currentMode before checking its value.
-
- Each of the push buttons is then enabled or disabled, depending on the
- current mode. The code for \c AddingMode and \c EditingMode is shown below:
-
- \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 1
-
- For \c NavigationMode, however, we include conditions within the parameters
- of the QPushButton::setEnabled() function. This is to ensure that
- \c editButton and \c removeButton are enabled when there is at least one
- contact in the address book; \c nextButton and \c previousButton are only
- enabled when there is more than one contact in the address book.
-
- \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 2
-
- By setting the mode and updating the user interface in the same
- function, we avoid the possibility of the user interface getting
- out of sync with the internal state of the application.
- */
-
-/*!
- \example tutorials/addressbook/part5
- \title Part 5 - Adding a Find Function
- \brief Describes how to add a find function.
-
- Here we look at ways to locate contacts and addresses in the
- address book.
-
- \image addressbook-tutorial-part5-screenshot.png
-
- As we add contacts to our address book, it becomes tedious to
- navigate the list with the \e Next and \e Previous buttons. A \e
- Find function would be more efficient. The screenshot above shows
- the \e Find button and its position on the panel of buttons.
-
- When the user clicks on the \e Find button, it is useful to
- display a dialog that prompts for a contact's name. Qt provides
- QDialog, which we subclass here to implement a \c FindDialog
- class.
-
- \section1 Defining the FindDialog Class
-
- \image addressbook-tutorial-part5-finddialog.png
-
- In order to subclass QDialog, we first include the header for QDialog in
- the \c finddialog.h file. Also, we use forward declaration to declare
- QLineEdit and QPushButton since we will be using those widgets in our
- dialog class.
-
- As in our \c AddressBook class, the \c FindDialog class includes
- the Q_OBJECT macro and its constructor is defined to accept a parent
- QWidget, even though the dialog will be opened as a separate window.
-
- \snippet tutorials/addressbook/part5/finddialog.h FindDialog header
-
- We define a public function, \c getFindText(), to be used by classes that
- instantiate \c FindDialog. This function allows these classes to obtain the
- search string entered by the user. A public slot, \c findClicked(), is also
- defined to handle the search string when the user clicks the \uicontrol Find
- button.
-
- Lastly, we define the private variables, \c findButton, \c lineEdit
- and \c findText, corresponding to the \uicontrol Find button, the line edit
- into which the user types the search string, and an internal string
- used to store the search string for later use.
-
- \section1 Implementing the FindDialog Class
-
- Within the constructor of \c FindDialog, we set up the private variables,
- \c lineEdit, \c findButton and \c findText. We use a QHBoxLayout to
- position the widgets.
-
- \snippet tutorials/addressbook/part5/finddialog.cpp constructor
-
- We set the layout and window title, as well as connect the signals to their
- respective slots. Notice that \c{findButton}'s \l{QPushButton::clicked()}
- {clicked()} signal is connected to \c findClicked() and
- \l{QDialog::accept()}{accept()}. The \l{QDialog::accept()}{accept()} slot
- provided by QDialog hides the dialog and sets the result code to
- \l{QDialog::}{Accepted}. We use this function to help \c{AddressBook}'s
- \c findContact() function know when the \c FindDialog object has been
- closed. We will explain this logic in further detail when discussing the
- \c findContact() function.
-
- \image addressbook-tutorial-part5-signals-and-slots.png
-
- In \c findClicked(), we validate \c lineEdit to ensure that the user
- did not click the \uicontrol Find button without entering a contact's name. Then, we set
- \c findText to the search string, extracted from \c lineEdit. After that,
- we clear the contents of \c lineEdit and hide the dialog.
-
- \snippet tutorials/addressbook/part5/finddialog.cpp findClicked() function
-
- The \c findText variable has a public getter function, \c getFindText(),
- associated with it. Since we only ever set \c findText directly in both the
- constructor and in the \c findClicked() function, we do not create a
- setter function to accompany \c getFindText().
- Because \c getFindText() is public, classes instantiating and using
- \c FindDialog can always access the search string that the user has
- entered and accepted.
-
- \snippet tutorials/addressbook/part5/finddialog.cpp getFindText() function
-
- \section1 Defining the AddressBook Class
-
- To ensure we can use \c FindDialog from within our \c AddressBook class, we
- include \c finddialog.h in the \c addressbook.h file.
-
- \snippet tutorials/addressbook/part5/addressbook.h include finddialog's header
-
- So far, all our address book features have a QPushButton and a
- corresponding slot. Similarly, for the \uicontrol Find feature we have
- \c findButton and \c findContact().
-
- The \c findButton is declared as a private variable and the
- \c findContact() function is declared as a public slot.
-
- \snippet tutorials/addressbook/part5/addressbook.h findContact() declaration
- \dots
- \snippet tutorials/addressbook/part5/addressbook.h findButton declaration
-
- Lastly, we declare the private variable, \c dialog, which we will use to
- refer to an instance of \c FindDialog.
-
- \snippet tutorials/addressbook/part5/addressbook.h FindDialog declaration
-
- Once we have instantiated a dialog, we will want to use it more than once;
- using a private variable allows us to refer to it from more than one place
- in the class.
-
- \section1 Implementing the AddressBook Class
-
- Within the \c AddressBook class's constructor, we instantiate our private
- objects, \c findButton and \c findDialog:
-
- \snippet tutorials/addressbook/part5/addressbook.cpp instantiating findButton
- \dots
- \snippet tutorials/addressbook/part5/addressbook.cpp instantiating FindDialog
-
- Next, we connect the \c{findButton}'s
- \l{QPushButton::clicked()}{clicked()} signal to \c findContact().
-
- \snippet tutorials/addressbook/part5/addressbook.cpp signals and slots for find
-
- Now all that is left is the code for our \c findContact() function:
-
- \snippet tutorials/addressbook/part5/addressbook.cpp findContact() function
-
- We start out by displaying the \c FindDialog instance, \c dialog. This is
- when the user enters a contact name to look up. Once the user clicks
- the dialog's \c findButton, the dialog is hidden and the result code is
- set to QDialog::Accepted. This ensures that
- our \c if statement is always true.
-
- We then proceed to extract the search string, which in this case is
- \c contactName, using \c{FindDialog}'s \c getFindText() function. If the
- contact exists in our address book, we display it immediately. Otherwise,
- we display the QMessageBox shown below to indicate that their search
- failed.
-
- \image addressbook-tutorial-part5-notfound.png
-*/
-
-/*!
- \example tutorials/addressbook/part6
- \title Part 6 - Loading and Saving
- \brief Describes how to add save and load functionality.
-
- This part covers the Qt file handling features we use to write
- loading and saving routines for the address book.
-
- \image addressbook-tutorial-part6-screenshot.png
-
- Although browsing and searching the contact list are useful
- features, our address book is not complete until we can save
- existing contacts and load them again at a later time.
-
- Qt provides a number of classes for \l{Input/Output and Networking}
- {input and output}, but we have chosen to use two which are simple to use
- in combination: QFile and QDataStream.
-
- A QFile object represents a file on disk that can be read from and written
- to. QFile is a subclass of the more general QIODevice class which
- represents many different kinds of devices.
-
- A QDataStream object is used to serialize binary data so that it can be
- stored in a QIODevice and retrieved again later. Reading from a QIODevice
- and writing to it is as simple as opening the stream - with the respective
- device as a parameter - and reading from or writing to it.
-
-
- \section1 Defining the AddressBook Class
-
- We declare two public slots, \c saveToFile() and \c loadFromFile(), as well
- as two QPushButton objects, \c loadButton and \c saveButton.
-
- \snippet tutorials/addressbook/part6/addressbook.h save and load functions declaration
- \dots
- \snippet tutorials/addressbook/part6/addressbook.h save and load buttons declaration
-
- \section1 Implementing the AddressBook Class
-
- In our constructor, we instantiate \c loadButton and \c saveButton.
- Ideally, it would be more user-friendly to set the push buttons' labels
- to "Load contacts from a file" and "Save contacts to a file". However, due
- to the size of our other push buttons, we set the labels to \uicontrol{Load...}
- and \uicontrol{Save...}. Fortunately, Qt provides a simple way to set tooltips with
- \l{QWidget::setToolTip()}{setToolTip()} and we use it in the following way
- for our push buttons:
-
- \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 1
- \dots
- \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 2
-
- Although it is not shown here, just like the other features we implemented,
- we add the push buttons to the layout panel on the right, \c buttonLayout1,
- and we connect the push buttons' \l{QPushButton::clicked()}{clicked()}
- signals to their respective slots.
-
- For the saving feature, we first obtain \c fileName using
- QFileDialog::getSaveFileName(). This is a convenience function provided
- by QFileDialog, which pops up a modal file dialog and allows the user to
- enter a file name or select any existing \c{.abk} file. The \c{.abk} file
- is our Address Book extension that we create when we save contacts.
-
- \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part1
-
- The file dialog that pops up is displayed in the screenshot below:
-
- \image addressbook-tutorial-part6-save.png
-
- If \c fileName is not empty, we create a QFile object, \c file, with
- \c fileName. QFile works with QDataStream as QFile is a QIODevice.
-
- Next, we attempt to open the file in \l{QIODevice::}{WriteOnly} mode.
- If this is unsuccessful, we display a QMessageBox to inform the user.
-
- \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part2
-
- Otherwise, we instantiate a QDataStream object, \c out, to write the open
- file. QDataStream requires that the same version of the stream is used
- for reading and writing. We ensure that this is the case by setting the
- version used to the \l{QDataStream::Qt_4_5}{version introduced with Qt 4.5}
- before serializing the data to \c file.
-
- \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part3
-
- For the loading feature, we also obtain \c fileName using
- QFileDialog::getOpenFileName(). This function, the counterpart to
- QFileDialog::getSaveFileName(), also pops up the modal file dialog and
- allows the user to enter a file name or select any existing \c{.abk} file
- to load it into the address book.
-
- \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part1
-
- On Windows, for example, this function pops up a native file dialog, as
- shown in the following screenshot.
-
- \image addressbook-tutorial-part6-load.png
-
- If \c fileName is not empty, again, we use a QFile object, \c file, and
- attempt to open it in \l{QIODevice::}{ReadOnly} mode. Similar to our
- implementation of \c saveToFile(), if this attempt is unsuccessful, we
- display a QMessageBox to inform the user.
-
- \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part2
-
- Otherwise, we instantiate a QDataStream object, \c in, set its version as
- above and read the serialized data into the \c contacts data structure.
- The \c contacts object is emptied before data is read into it to simplify
- the file reading process. A more advanced method would be to read the
- contacts into a temporary QMap object, and copy over non-duplicate contacts
- into \c contacts.
-
- \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part3
-
- To display the contacts that have been read from the file, we must first
- validate the data obtained to ensure that the file we read from actually
- contains address book contacts. If it does, we display the first contact;
- otherwise, we display a QMessageBox to inform the user about the problem.
- Lastly, we update the interface to enable and disable the push buttons
- accordingly.
-*/
-
-/*!
- \example tutorials/addressbook/part7
- \title Part 7 - Additional Features
- \brief Describes how to export data in VCard format.
-
- This part covers some additional features that make the address
- book more convenient for the frequent user.
-
- \image addressbook-tutorial-part7-screenshot.png
-
- Although our address book is useful in isolation, it would be
- better if we could exchange contact data with other applications.
- The vCard format is a popular file format that can be used for
- this purpose. Here we extend our address book client to allow
- contacts to be exported to vCard \c{.vcf} files.
-
- \section1 Defining the AddressBook Class
-
- We add a QPushButton object, \c exportButton, and a corresponding public
- slot, \c exportAsVCard() to our \c AddressBook class in the
- \c addressbook.h file.
-
- \snippet tutorials/addressbook/part7/addressbook.h exportAsVCard() declaration
- \dots
- \snippet tutorials/addressbook/part7/addressbook.h exportButton declaration
-
- \section1 Implementing the AddressBook Class
-
- Within the \c AddressBook constructor, we connect \c{exportButton}'s
- \l{QPushButton::clicked()}{clicked()} signal to \c exportAsVCard().
- We also add this button to our \c buttonLayout1, the layout responsible
- for our panel of buttons on the right.
-
- In our \c exportAsVCard() function, we start by extracting the contact's
- name into \c name. We declare \c firstName, \c lastName and \c nameList.
- Next, we look for the index of the first white space in \c name. If there
- is a white space, we split the contact's name into \c firstName and
- \c lastName. Then, we replace the space with an underscore ("_").
- Alternately, if there is no white space, we assume that the contact only
- has a first name.
-
- \snippet tutorials/addressbook/part7/addressbook.cpp export function part1
-
- As with the \c saveToFile() function, we open a file dialog to let the user
- choose a location for the file. Using the file name chosen, we create an
- instance of QFile to write to.
-
- We attempt to open the file in \l{QIODevice::}{WriteOnly} mode. If this
- process fails, we display a QMessageBox to inform the user about the
- problem and return. Otherwise, we pass the file as a parameter to a
- QTextStream object, \c out. Like QDataStream, the QTextStream class
- provides functionality to read and write plain text to files. As a result,
- the \c{.vcf} file generated can be opened for editing in a text editor.
-
- \snippet tutorials/addressbook/part7/addressbook.cpp export function part2
-
- We then write out a vCard file with the \c{BEGIN:VCARD} tag, followed by
- the \c{VERSION:2.1} tag. The contact's name is written with the \c{N:}
- tag. For the \c{FN:} tag, which fills in the "File as" property of a vCard,
- we have to check whether the contact has a last name or not. If the contact
- does, we use the details in \c nameList to fill it. Otherwise, we write
- \c firstName only.
-
- \snippet tutorials/addressbook/part7/addressbook.cpp export function part3
-
- We proceed to write the contact's address. The semicolons in the address
- are escaped with "\\", the newlines are replaced with semicolons, and the
- commas are replaced with spaces. Lastly, we write the \c{ADR;HOME:;}
- tag, followed by \c address and then the \c{END:VCARD} tag.
-
- \snippet tutorials/addressbook/part7/addressbook.cpp export function part4
-
- In the end, a QMessageBox is displayed to inform the user that the vCard
- has been successfully exported.
-
- \e{vCard is a trademark of the \l{http://www.imc.org}
- {Internet Mail Consortium}}.
-*/
diff --git a/examples/widgets/doc/src/addressbook.qdoc b/examples/widgets/doc/src/addressbook.qdoc
index 22769cb270..8f2512298b 100644
--- a/examples/widgets/doc/src/addressbook.qdoc
+++ b/examples/widgets/doc/src/addressbook.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example itemviews/addressbook
- \title Address Book Example
+ \title Address Book
+ \examplecategory {User Interface Components}
\ingroup examples-itemviews
\brief The address book example shows how to use proxy models to display
different views onto data from a single model.
@@ -48,7 +25,7 @@
\c AddDialog. The \c MainWindow class uses \c AddressWidget as
its central widget and provides \uicontrol File and \uicontrol Tools menus.
- \image addressbook-classes.png Diagram for Address Book Example
+ \image addressbook-classes.png Diagram for Address Book example
The \c AddressWidget class is a QTabWidget subclass that is used
to manipulate the 10 tabs displayed in the example: the 9
@@ -405,17 +382,15 @@
respective slots, we also connect \c AddressWidget's
\c selectionChanged() signal to its \c updateActions() slot.
- The \c openFile() function allows the user to choose a file with
- the \l{QFileDialog::getOpenFileName()}{open file dialog}. The chosen
- file has to be a custom \c{.dat} file that contains address book
- contacts. This function is a slot connected to \c openAct in the
- \uicontrol File menu.
+ The \c openFile() function opens a custom \c{addressbook.dat} file that
+ contains address book contacts. This function is a slot connected to
+ \c openAct in the \uicontrol File menu.
\snippet itemviews/addressbook/mainwindow.cpp 2
- The \c saveFile() function allows the user to save a file with
- the \l{QFileDialog::getSaveFileName()}{save file dialog}. This function
- is a slot connected to \c saveAct in the \uicontrol File menu.
+ The \c saveFile() function saves a custom \c{addressbook.dat} file that
+ will contain the address book contacts. This function is a slot connected
+ to \c saveAct in the \uicontrol File menu.
\snippet itemviews/addressbook/mainwindow.cpp 3
diff --git a/examples/widgets/doc/src/affine.qdoc b/examples/widgets/doc/src/affine.qdoc
index 601a707eb9..2ec3a4fc4d 100644
--- a/examples/widgets/doc/src/affine.qdoc
+++ b/examples/widgets/doc/src/affine.qdoc
@@ -1,35 +1,12 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example painting/affine
\title Affine Transformations
+ \examplecategory {Graphics}
\ingroup examples-painting
- \brief Demonstrates how affine transformations in QPainter works.
+ \brief Demonstrates how affine transformations in QPainter work.
\brief In this example we show Qt's ability to perform affine transformations
on painting operations.
diff --git a/examples/widgets/doc/src/analogclock.qdoc b/examples/widgets/doc/src/analogclock.qdoc
index ff65f97730..8f98f4b7b0 100644
--- a/examples/widgets/doc/src/analogclock.qdoc
+++ b/examples/widgets/doc/src/analogclock.qdoc
@@ -1,33 +1,12 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example widgets/analogclock
- \title Analog Clock Example
+ \examplecategory {Graphics}
+ \meta tags {widgets}
+
+ \title Analog Clock
\ingroup examples-widgets
\brief The Analog Clock example shows how to draw the contents of a
custom widget.
@@ -41,8 +20,8 @@
\section1 AnalogClock Class Definition
- The \c AnalogClock class provides a clock widget with hour and minute
- hands that is automatically updated every few seconds.
+ The \c AnalogClock class provides a clock widget with hour, minute and
+ second hands that is automatically updated every second.
We subclass \l QWidget and reimplement the standard
\l{QWidget::paintEvent()}{paintEvent()} function to draw the clock face:
@@ -50,19 +29,14 @@
\section1 AnalogClock Class Implementation
- \snippet widgets/analogclock/analogclock.cpp 1
-
When the widget is constructed, we set up a one-second timer to
keep track of the current time, and we connect it to the standard
\l{QWidget::update()}{update()} slot so that the clock face is
updated when the timer emits the \l{QTimer::timeout()}{timeout()}
- signal.
-
- Finally, we resize the widget so that it is displayed at a
+ signal. Finally, we resize the widget so that it is displayed at a
reasonable size.
- \snippet widgets/analogclock/analogclock.cpp 8
- \snippet widgets/analogclock/analogclock.cpp 10
+ \snippet widgets/analogclock/analogclock.cpp 1
The \c paintEvent() function is called whenever the widget's
contents need to be updated. This happens when the widget is
@@ -70,31 +44,37 @@
executed when the widget's \l{QWidget::update()}{update()} slot
is called. Since we connected the timer's
\l{QTimer::timeout()}{timeout()} signal to this slot, it will be
- called at least once every five seconds.
+ called at least once per second.
Before we set up the painter and draw the clock, we first define
- two lists of \l {QPoint}s and two \l{QColor}s that will be used
- for the hour and minute hands. The minute hand's color has an
- alpha component of 191, meaning that it's 75% opaque.
+ three lists of \l {QPoint}s and three \l{QColor}s that will be used
+ for the hour, minute and second hands. We use the
+ \l{QWidget::palette()}{palette()} function to get appropriate colors
+ that fit into the rest of the window, both in light and dark mode.
+ The hour and minute hands are drawn in the foreground color, the
+ second hand is drawn in the accent color.
We also determine the length of the widget's shortest side so that we
can fit the clock face inside the widget. It is also useful to determine
the current time before we start drawing.
- \snippet widgets/analogclock/analogclock.cpp 11
- \snippet widgets/analogclock/analogclock.cpp 12
- \snippet widgets/analogclock/analogclock.cpp 13
- \snippet widgets/analogclock/analogclock.cpp 14
+ \snippet widgets/analogclock/analogclock.cpp 8
+ \snippet widgets/analogclock/analogclock.cpp 10
The contents of custom widgets are drawn with a QPainter.
Painters can be used to draw on any QPaintDevice, but they are
usually used with widgets, so we pass the widget instance to the
painter's constructor.
+ \snippet widgets/analogclock/analogclock.cpp 11
+ \snippet widgets/analogclock/analogclock.cpp 14
+
We call QPainter::setRenderHint() with QPainter::Antialiasing to
turn on antialiasing. This makes drawing of diagonal lines much
smoother.
+ \snippet widgets/analogclock/analogclock.cpp 12
+
The translation moves the origin to the center of the widget, and
the scale operation ensures that the following drawing operations
are scaled to fit within the widget. We use a scale factor that
@@ -102,6 +82,8 @@
ensures that these lie within the length of the widget's shortest
side.
+ \snippet widgets/analogclock/analogclock.cpp 13
+
To make our code simpler, we will draw a fixed size clock face that will
be positioned and scaled so that it lies in the center of the widget.
@@ -112,44 +94,47 @@
\image analogclock-viewport.png
- We draw the hour hand first, using a formula that rotates the coordinate
- system counterclockwise by a number of degrees determined by the current
- hour and minute. This means that the hand will be shown rotated clockwise
- by the required amount.
-
- \snippet widgets/analogclock/analogclock.cpp 15
- \snippet widgets/analogclock/analogclock.cpp 16
-
We set the pen to be Qt::NoPen because we don't want any outline,
and we use a solid brush with the color appropriate for
displaying hours. Brushes are used when filling in polygons and
other geometric shapes.
- \snippet widgets/analogclock/analogclock.cpp 17
- \snippet widgets/analogclock/analogclock.cpp 19
+ \snippet widgets/analogclock/analogclock.cpp 15
+ \snippet widgets/analogclock/analogclock.cpp 16
+ We draw the hour hand first, using a formula that rotates the coordinate
+ system counterclockwise by a number of degrees determined by the current
+ hour and minute. This means that the hand will be shown rotated clockwise
+ by the required amount.
We save and restore the transformation matrix before and after the
rotation because we want to place the minute hand without having to
take into account any previous rotations.
+ \snippet widgets/analogclock/analogclock.cpp 17
+ \snippet widgets/analogclock/analogclock.cpp 19
+
+ We draw markers around the edge of the clock for each hour in the same
+ color as the hour hand. We draw each marker then rotate the coordinate
+ system so that the painter is ready for the next one.
+
\snippet widgets/analogclock/analogclock.cpp 20
- \codeline
+
+ The minute hand is rotated and painted in a similar way to the hour hand.
+
\snippet widgets/analogclock/analogclock.cpp 21
- We draw markers around the edge of the clock for each hour. We
- draw each marker then rotate the coordinate system so that the
- painter is ready for the next one.
+ For the seconds hand we do the same and add two cicles as a visual highlight.
- \snippet widgets/analogclock/analogclock.cpp 22
\snippet widgets/analogclock/analogclock.cpp 23
+ \codeline
+ \snippet widgets/analogclock/analogclock.cpp 24
- The minute hand is rotated in a similar way to the hour hand.
+ Finally, we draw markers around the edge of the clock, indicating
+ minutes and seconds. This time we draw them as lines and therefore
+ set the pen to the respective color.
\snippet widgets/analogclock/analogclock.cpp 25
\codeline
- \snippet widgets/analogclock/analogclock.cpp 26
+ \snippet widgets/analogclock/analogclock.cpp 27
- Again, we draw markers around the edge of the clock, but this
- time to indicate minutes. We skip multiples of 5 to avoid drawing
- minute markers on top of hour markers.
*/
diff --git a/examples/widgets/doc/src/application.qdoc b/examples/widgets/doc/src/application.qdoc
deleted file mode 100644
index 334c8cb9f0..0000000000
--- a/examples/widgets/doc/src/application.qdoc
+++ /dev/null
@@ -1,395 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 mainwindows/application
- \title Qt Widgets - Application Example
- \ingroup examples-mainwindow
-
- \brief The Application example shows how to implement a standard
- widget application with menus, toolbars, and a status bar. The example
- itself is a simple text editor program built around QPlainTextEdit.
-
- \image application.png Screenshot of the Application example
-
- Nearly all of the code for the Application example is in the \c
- MainWindow class, which inherits QMainWindow. QMainWindow
- provides the framework for windows that have menus, toolbars,
- dock windows, and a status bar. The application provides
- \uicontrol{File}, \uicontrol{Edit}, and \uicontrol{Help} entries in the menu
- bar, with the following popup menus:
-
- \image application-menus.png The Application example's menu system
-
- The status bar at the bottom of the main window shows a
- description of the menu item or toolbar button under the cursor.
-
- To keep the example simple, recently opened files aren't shown in
- the \uicontrol{File} menu, even though this feature is desired in 90%
- of applications. Furthermore, this example can only load one file at a
- time. The \l{mainwindows/sdi}{SDI} and \l{mainwindows/mdi}{MDI} examples
- show how to lift these restrictions and how to implement recently opened files
- handling.
-
- \section1 MainWindow Class Definition
-
- Here's the class definition:
-
- \snippet mainwindows/application/mainwindow.h 0
-
- The public API is restricted to the constructor. In the \c
- protected section, we reimplement QWidget::closeEvent() to detect
- when the user attempts to close the window, and warn the user
- about unsaved changes. In the \c{private slots} section, we
- declare slots that correspond to menu entries, as well as a
- mysterious \c documentWasModified() slot. Finally, in the \c
- private section of the class, we have various members that will
- be explained in due time.
-
- \section1 MainWindow Class Implementation
-
- \snippet mainwindows/application/mainwindow.cpp 0
-
- We start by including \c <QtWidgets>, a header file that contains the
- definition of all classes in the Qt Core, Qt GUI and Qt Widgets
- modules. This saves us from the trouble of having to include
- every class individually. We also include \c mainwindow.h.
-
- You might wonder why we don't include \c <QtWidgets> in \c
- mainwindow.h and be done with it. The reason is that including
- such a large header from another header file can rapidly degrade
- performances. Here, it wouldn't do any harm, but it's still
- generally a good idea to include only the header files that are
- strictly necessary from another header file.
-
- \snippet mainwindows/application/mainwindow.cpp 1
- \snippet mainwindows/application/mainwindow.cpp 2
-
- In the constructor, we start by creating a QPlainTextEdit widget as a
- child of the main window (the \c this object). Then we call
- QMainWindow::setCentralWidget() to tell that this is going to be
- the widget that occupies the central area of the main window,
- between the toolbars and the status bar.
-
- Then we call \c createActions() and \c createStatusBar(), two private
- functions that set up the user interface. After that, we call \c
- readSettings() to restore the user's preferences.
-
- We establish a signal-slot connection between the QPlainTextEdit's
- document object and our \c documentWasModified() slot. Whenever
- the user modifies the text in the QPlainTextEdit, we want to update
- the title bar to show that the file was modified.
-
- At the end, we set the window title using the private
- \c setCurrentFile() function. We'll come back to this later.
-
- \target close event handler
- \snippet mainwindows/application/mainwindow.cpp 3
- \snippet mainwindows/application/mainwindow.cpp 4
-
- When the user attempts to close the window, we call the private
- function \c maybeSave() to give the user the possibility to save
- pending changes. The function returns true if the user wants the
- application to close; otherwise, it returns false. In the first
- case, we save the user's preferences to disk and accept the close
- event; in the second case, we ignore the close event, meaning
- that the application will stay up and running as if nothing
- happened.
-
- \snippet mainwindows/application/mainwindow.cpp 5
- \snippet mainwindows/application/mainwindow.cpp 6
-
- The \c newFile() slot is invoked when the user selects
- \uicontrol{File|New} from the menu. We call \c maybeSave() to save any
- pending changes and if the user accepts to go on, we clear the
- QPlainTextEdit and call the private function \c setCurrentFile() to
- update the window title and clear the
- \l{QWidget::windowModified}{windowModified} flag.
-
- \snippet mainwindows/application/mainwindow.cpp 7
- \snippet mainwindows/application/mainwindow.cpp 8
-
- The \c open() slot is invoked when the user clicks
- \uicontrol{File|Open}. We pop up a QFileDialog asking the user to
- choose a file. If the user chooses a file (i.e., \c fileName is
- not an empty string), we call the private function \c loadFile()
- to actually load the file.
-
- \snippet mainwindows/application/mainwindow.cpp 9
- \snippet mainwindows/application/mainwindow.cpp 10
-
- The \c save() slot is invoked when the user clicks
- \uicontrol{File|Save}. If the user hasn't provided a name for the file
- yet, we call \c saveAs(); otherwise, we call the private function
- \c saveFile() to actually save the file.
-
- \snippet mainwindows/application/mainwindow.cpp 11
- \snippet mainwindows/application/mainwindow.cpp 12
-
- In \c saveAs(), we start by popping up a QFileDialog asking the
- user to provide a name. If the user clicks \uicontrol{Cancel}, the
- returned file name is empty, and we do nothing.
-
- \snippet mainwindows/application/mainwindow.cpp 13
- \snippet mainwindows/application/mainwindow.cpp 14
-
- The application's About box is done using one statement, using
- the QMessageBox::about() static function and relying on its
- support for an HTML subset.
-
- The \l{QObject::tr()}{tr()} call around the literal string marks
- the string for translation. It is a good habit to call
- \l{QObject::tr()}{tr()} on all user-visible strings, in case you
- later decide to translate your application to other languages.
- The \l{Internationalization with Qt} overview covers
- \l{QObject::tr()}{tr()} in more detail.
-
- \snippet mainwindows/application/mainwindow.cpp 15
- \snippet mainwindows/application/mainwindow.cpp 16
-
- The \c documentWasModified() slot is invoked each time the text
- in the QPlainTextEdit changes because of user edits. We call
- QWidget::setWindowModified() to make the title bar show that the
- file was modified. How this is done varies on each platform.
-
- \snippet mainwindows/application/mainwindow.cpp 17
- \snippet mainwindows/application/mainwindow.cpp 18
- \dots
- \snippet mainwindows/application/mainwindow.cpp 22
-
- The \c createActions() private function, which is called from the
- \c MainWindow constructor, creates \l{QAction}s and populates
- the menus and two toolbars. The code is very
- repetitive, so we show only the actions corresponding to
- \uicontrol{File|New}, \uicontrol{File|Open}, and \uicontrol{Help|About Qt}.
-
- A QAction is an object that represents one user action, such as
- saving a file or invoking a dialog. An action can be put in a
- QMenu or a QToolBar, or both, or in any other widget that
- reimplements QWidget::actionEvent().
-
- An action has a text that is shown in the menu, an icon, a
- shortcut key, a tooltip, a status tip (shown in the status bar),
- a "What's This?" text, and more. It emits a
- \l{QAction::triggered()}{triggered()} signal whenever the user
- invokes the action (e.g., by clicking the associated menu item or
- toolbar button).
-
- Instances of QAction can be created by passing a parent QObject or
- by using one of the convenience functions of QMenu, QMenuBar or QToolBar.
- We create the actions that are in a menu as well as in a toolbar
- parented on the window to prevent ownership issues. For actions
- that are only in the menu, we use the convenience function
- QMenu::addAction(), which allows us to pass text, icon and the
- target object and its slot member function.
-
- Creating toolbars is very similar to creating menus. The same
- actions that we put in the menus can be reused in the toolbars.
- After creating the action, we add it to the toolbar using
- QToolBar::addAction().
-
- The code above contains one more idiom that must be explained.
- For some of the actions, we specify an icon as a QIcon to the
- QAction constructor. We use QIcon::fromTheme() to obtain
- the correct standard icon from the underlying window system.
- If that fails due to the platform not supporting it, we
- pass a file name as fallback. Here, the file name starts
- with \c{:}. Such file names aren't ordinary file names, but
- rather path in the executable's stored resources. We'll come back
- to this when we review the \c application.qrc file that's part of
- the project.
-
- \snippet mainwindows/application/mainwindow.cpp 23
- \snippet mainwindows/application/mainwindow.cpp 24
-
- The \uicontrol{Edit|Cut} and \uicontrol{Edit|Copy} actions must be available
- only when the QPlainTextEdit contains selected text. We disable them
- by default and connect the QPlainTextEdit::copyAvailable() signal to
- the QAction::setEnabled() slot, ensuring that the actions are
- disabled when the text editor has no selection.
-
- Just before we create the \uicontrol{Help} menu, we call
- QMenuBar::addSeparator(). This has no effect for most widget
- styles (e.g., Windows and \macos styles), but for some
- styles this makes sure that \uicontrol{Help} is pushed to the right
- side of the menu bar.
-
- \snippet mainwindows/application/mainwindow.cpp 32
- \snippet mainwindows/application/mainwindow.cpp 33
-
- QMainWindow::statusBar() returns a pointer to the main window's
- QStatusBar widget. Like with \l{QMainWindow::menuBar()}, the
- widget is automatically created the first time the function is
- called.
-
- \snippet mainwindows/application/mainwindow.cpp 34
- \snippet mainwindows/application/mainwindow.cpp 36
-
- The \c readSettings() function is called from the constructor to
- load the user's preferences and other application settings. The
- QSettings class provides a high-level interface for storing
- settings permanently on disk. On Windows, it uses the (in)famous
- Windows registry; on \macos, it uses the native XML-based
- CFPreferences API; on Unix/X11, it uses text files.
-
- The QSettings constructor takes arguments that identify your
- company and the name of the product. This ensures that the
- settings for different applications are kept separately.
-
- We use QSettings::value() to extract the value of the geometry setting.
- The second argument to QSettings::value() is
- optional and specifies a default value for the setting if there
- exists none. This value is used the first time the application is
- run.
-
- We use QWidget::saveGeometry() and Widget::restoreGeometry() to
- save the position. They use an opaque QByteArray to store
- screen number, geometry and window state.
-
- \snippet mainwindows/application/mainwindow.cpp 37
- \snippet mainwindows/application/mainwindow.cpp 39
-
- The \c writeSettings() function is called from \c closeEvent().
- Writing settings is similar to reading them, except simpler. The
- arguments to the QSettings constructor must be the same as in \c
- readSettings().
-
- \snippet mainwindows/application/mainwindow.cpp 40
- \snippet mainwindows/application/mainwindow.cpp 41
-
- The \c maybeSave() function is called to save pending changes. If
- there are pending changes, it pops up a QMessageBox giving the
- user to save the document. The options are QMessageBox::Yes,
- QMessageBox::No, and QMessageBox::Cancel. The \uicontrol{Yes} button is
- made the default button (the button that is invoked when the user
- presses \uicontrol{Return}) using the QMessageBox::Default flag; the
- \uicontrol{Cancel} button is made the escape button (the button that is
- invoked when the user presses \uicontrol{Esc}) using the
- QMessageBox::Escape flag.
-
- The \c maybeSave() function returns \c true in all cases, except
- when the user clicks \uicontrol{Cancel} or saving the file fails.
- The caller must check the return value and stop whatever it was
- doing if the return value is \c false.
-
- \snippet mainwindows/application/mainwindow.cpp 42
- \snippet mainwindows/application/mainwindow.cpp 43
-
- In \c loadFile(), we use QFile and QTextStream to read in the
- data. The QFile object provides access to the bytes stored in a
- file.
-
- We start by opening the file in read-only mode. The QFile::Text
- flag indicates that the file is a text file, not a binary file.
- On Unix and \macos, this makes no difference, but on Windows,
- it ensures that the "\\r\\n" end-of-line sequence is converted to
- "\\n" when reading.
-
- If we successfully opened the file, we use a QTextStream object
- to read in the data. QTextStream automatically converts the 8-bit
- data into a Unicode QString and supports various encodings. If no
- encoding is specified, QTextStream assumes the file is encoded in
- UTF-8.
-
- Since the call to QTextStream::readAll() might take some time, we
- set the cursor to be Qt::WaitCursor for the entire application
- while it goes on.
-
- At the end, we call the private \c setCurrentFile() function,
- which we'll cover in a moment, and we display the string "File
- loaded" in the status bar for 2 seconds (2000 milliseconds).
-
- \snippet mainwindows/application/mainwindow.cpp 44
- \snippet mainwindows/application/mainwindow.cpp 45
-
- Saving a file is similar to loading one. We use QSaveFile to ensure
- all data are safely written and existing files are not damaged
- should writing fail.
- We use the QFile::Text flag to make sure that on Windows, "\\n"
- is converted into "\\r\\n" to conform to the Windows convention.
-
-
- \snippet mainwindows/application/mainwindow.cpp 46
- \snippet mainwindows/application/mainwindow.cpp 47
-
- The \c setCurrentFile() function is called to reset the state of
- a few variables when a file is loaded or saved, or when the user
- starts editing a new file (in which case \c fileName is empty).
- We update the \c curFile variable, clear the
- QTextDocument::modified flag and the associated \c
- QWidget:windowModified flag, and update the window title to
- contain the new file name (or \c untitled.txt).
-
- The \c strippedName() function call around \c curFile in the
- QWidget::setWindowTitle() call shortens the file name to exclude
- the path. Here's the function:
-
- \snippet mainwindows/application/mainwindow.cpp 48
- \snippet mainwindows/application/mainwindow.cpp 49
-
- \section1 The main() Function
-
- The \c main() function for this application is typical of
- applications that contain one main window:
-
- \snippet mainwindows/application/main.cpp 0
-
- The main function uses QCommandLineParser to check whether some file
- argument was passed to the application and loads it via
- MainWindow::loadFile().
-
- \section1 The Resource File
-
- As you will probably recall, for some of the actions, we
- specified icons with file names starting with \c{:} and mentioned
- that such file names aren't ordinary file names, but path in the
- executable's stored resources. These resources are compiled
-
- The resources associated with an application are specified in a
- \c .qrc file, an XML-based file format that lists files on the
- disk. Here's the \c application.qrc file that's used by the
- Application example:
-
- \quotefile mainwindows/application/application.qrc
-
- The \c .png files listed in the \c application.qrc file are files
- that are part of the Application example's source tree. Paths are
- relative to the directory where the \c application.qrc file is
- located (the \c mainwindows/application directory).
-
- The resource file must be mentioned in the \c application.pro
- file so that \c qmake knows about it:
-
- \snippet mainwindows/application/application.pro 0
-
- \c qmake will produce make rules to generate a file called \c
- qrc_application.cpp that is linked into the application. This
- file contains all the data for the images and other resources as
- static C++ arrays of compressed binary data. See
- \l{resources.html}{The Qt Resource System} for more information
- about resources.
-*/
diff --git a/examples/widgets/doc/src/basicdrawing.qdoc b/examples/widgets/doc/src/basicdrawing.qdoc
index 3eda3ffed2..0882c0f32f 100644
--- a/examples/widgets/doc/src/basicdrawing.qdoc
+++ b/examples/widgets/doc/src/basicdrawing.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example painting/basicdrawing
\title Basic Drawing Example
+ \examplecategory {Graphics}
\ingroup examples-painting
\brief The Basic Drawing example shows how to display basic
graphics primitives in a variety of styles using the QPainter
diff --git a/examples/widgets/doc/src/basicgraphicslayouts.qdoc b/examples/widgets/doc/src/basicgraphicslayouts.qdoc
index 23661d0558..1add587464 100644
--- a/examples/widgets/doc/src/basicgraphicslayouts.qdoc
+++ b/examples/widgets/doc/src/basicgraphicslayouts.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example graphicsview/basicgraphicslayouts
\title Basic Graphics Layouts Example
+ \examplecategory {Graphics}
\ingroup examples-graphicsview-layout
\brief Demonstrates how to create basic graphics layout.
diff --git a/examples/widgets/doc/src/basiclayouts.qdoc b/examples/widgets/doc/src/basiclayouts.qdoc
index e9d7cea21b..e6f1cab4d9 100644
--- a/examples/widgets/doc/src/basiclayouts.qdoc
+++ b/examples/widgets/doc/src/basiclayouts.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example layouts/basiclayouts
\title Basic Layouts Example
+ \examplecategory {User Interface Components}
\brief Shows how to use the standard layout managers.
\e{Basic Layouts} shows how to use the standard layout managers that are
diff --git a/examples/widgets/doc/src/basicsortfiltermodel.qdoc b/examples/widgets/doc/src/basicsortfiltermodel.qdoc
index d598ab1e24..c0b8a5f426 100644
--- a/examples/widgets/doc/src/basicsortfiltermodel.qdoc
+++ b/examples/widgets/doc/src/basicsortfiltermodel.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example itemviews/basicsortfiltermodel
\title Basic Sort/Filter Model Example
+ \examplecategory {User Interface Components}
\ingroup examples-itemviews
\brief The Basic Sort/Filter Model example illustrates how to use
QSortFilterProxyModel to perform basic sorting and filtering.
diff --git a/examples/widgets/doc/src/blurpicker.qdoc b/examples/widgets/doc/src/blurpicker.qdoc
deleted file mode 100644
index d4d84f7248..0000000000
--- a/examples/widgets/doc/src/blurpicker.qdoc
+++ /dev/null
@@ -1,44 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 effects/blurpicker
- \title Blur Picker Effect Example
- \ingroup examples-graphicsview-graphicseffects
- \brief Demonstrates how to apply graphical effects on items in the view.
-
- \image blurpickereffect-example.png
-
- The Blur Picker example displays a circle of application icons.
- All icons are blurred, except the one on the bottom left side of
- the screen, which is the one in focus.
- Clicking anywhere on the left side of the screen moves the icon
- circle clockwise to the next icon
- Clicking on the right side advances the circle counterclockwise.
-
- \sa QGraphicsBlurEffect
-*/
diff --git a/examples/widgets/doc/src/borderlayout.qdoc b/examples/widgets/doc/src/borderlayout.qdoc
deleted file mode 100644
index 6572bfe578..0000000000
--- a/examples/widgets/doc/src/borderlayout.qdoc
+++ /dev/null
@@ -1,70 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 layouts/borderlayout
- \title Border Layout Example
- \ingroup examples-layout
- \brief Shows how to arrange child widgets along a border.
-
- \e{Border Layout} implements a layout that arranges child widgets to
- surround the main area.
-
- \image borderlayout-example.png
-
- The constructor of the Window class creates a QTextBrowser object,
- to which a BorderLayout named \c layout is added. The declaration
- of the BorderLayout class is quoted at the end of this document.
-
- \quotefromfile layouts/borderlayout/window.cpp
- \skipto Window::Window()
- \printuntil BorderLayout
-
- Several labeled widgets are added to \c layout with the orientation
- \c {Center}, \c {North}, \c {West}, \c {East 1}, \c {East 2}, and
- \c {South}.
-
- \skipto layout->addWidget
- \printuntil setWindowTitle
-
- createLabel() in class \c Window sets the text of the labeled widgets
- and the style.
-
- \skipto QLabel *Window::createLabel
- \printuntil /^\}/
-
- Class BorderLayout contains all the utilitarian functions for formatting
- the widgets it contains.
-
- \quotefromfile layouts/borderlayout/borderlayout.h
- \skipto class
- \printuntil /^\}/
-
- For more information, visit the \l{Layout Management} page.
-
- \include examples-run.qdocinc
-*/
diff --git a/examples/widgets/doc/src/calculator.qdoc b/examples/widgets/doc/src/calculator.qdoc
index 7d34a86c19..c59d3cd161 100644
--- a/examples/widgets/doc/src/calculator.qdoc
+++ b/examples/widgets/doc/src/calculator.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example widgets/calculator
\title Calculator Example
+ \examplecategory {User Interface Components}
\ingroup examples-widgets
\ingroup examples-layout
\brief The example shows how to use signals and slots to implement the
diff --git a/examples/widgets/doc/src/calendar.qdoc b/examples/widgets/doc/src/calendar.qdoc
deleted file mode 100644
index 4a6a482ff2..0000000000
--- a/examples/widgets/doc/src/calendar.qdoc
+++ /dev/null
@@ -1,226 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 richtext/calendar
- \title Calendar Example
- \ingroup examples-richtext
- \brief The Calendar example shows how to create rich text content
- and display it using a rich text editor.
-
- \brief The Calendar example shows how to create rich text content and display it using
- a rich text editor.
-
- \image calendar-example.png
-
- Specifically, the example demonstrates the following:
-
- \list
- \li Use of a text editor with a text document
- \li Insertion of tables and frames into a document
- \li Navigation within a table
- \li Insert text in different styles
- \endlist
-
- The rich text editor used to display the document is used within a main window
- application.
-
- \section1 MainWindow Class Definition
-
- The \c MainWindow class provides a text editor widget and some controls to
- allow the user to change the month and year shown. The font size used for the
- text can also be adjusted.
-
- \snippet richtext/calendar/mainwindow.h 0
-
- The private \c insertCalendar() function performs most of the work, relying on
- the \c fontSize and \c selectedDate variables to write useful information to
- the \c editor.
-
- \section1 MainWindow Class Implementation
-
- The \c MainWindow constructor sets up the user interface and initializes
- variables used to generate a calendar for each month.
-
- \snippet richtext/calendar/mainwindow.cpp 0
-
- We begin by setting default values for the selected date that will be highlighted
- in the calendar and the font size to be used. Since we are using a QMainWindow
- for the user interface, we construct a widget for use as the central widget.
-
- The user interface will include a line of controls above the generated calendar;
- we construct a label and a combobox to allow the month to be selected, and a
- spin box for the year. These widgets are configured to provide a reasonable range
- of values for the user to try:
-
- \snippet richtext/calendar/mainwindow.cpp 1
-
- We use the \c selectedDate object to obtain the current month and year, and we
- set these in the combobox and spin box:
-
- The font size is displayed in a spin box which we restrict to a sensible range
- of values:
-
- \snippet richtext/calendar/mainwindow.cpp 2
-
- We construct an editor and use the \c insertCalendar() function to create
- a calendar for it. Each calendar is displayed in the same text editor; in
- this example we use a QTextBrowser since we do not allow the calendar to be
- edited.
-
- The controls used to set the month, year, and font size will not have any
- effect on the appearance of the calendar unless we make some signal-slot
- connections:
-
- \snippet richtext/calendar/mainwindow.cpp 3
-
- The signals are connected to some simple slots in the \c MainWindow class
- which we will describe later.
-
- We create layouts to manage the widgets we constructed:
-
- \snippet richtext/calendar/mainwindow.cpp 4
-
- Finally, the central widget is set for the window.
-
- Each calendar is created for the editor by the \c insertCalendar() function
- which uses the date and font size, defined by the private \a selectedDate
- and \c fontSize variables, to produce a suitable plan for the specified
- month and year.
-
- \snippet richtext/calendar/mainwindow.cpp 5
-
- We begin by clearing the editor's rich text document, and obtain a text
- cursor from the editor that we will use to add content. We also create a
- QDate object based on the currently selected date.
-
- The calendar is made up of a table with a gray background color that contains
- seven columns: one for each day of the week. It is placed in the center of the
- page with equal space to the left and right of it. All of these properties are
- set in a QTextTableFormat object:
-
- \snippet richtext/calendar/mainwindow.cpp 6
-
- Each cell in the table will be padded and spaced to make the text easier to
- read.
-
- We want the columns to have equal widths, so we provide a list containing
- percentage widths for each of them and set the constraints in the
- QTextTableFormat:
-
- \snippet richtext/calendar/mainwindow.cpp 7
-
- The constraints used for the column widths are only useful if the table has
- an appropriate number of columns. With the format for the table defined, we
- construct a new table with one row and seven columns at the current cursor
- position:
-
- \snippet richtext/calendar/mainwindow.cpp 8
-
- We only need one row to start with; more can be added as we need them. Using
- this approach means that we do not need to perform any date calculations
- until we add cells to the table.
-
- When inserting objects into a document with the cursor's insertion functions,
- the cursor is automatically moved inside the newly inserted object. This means
- that we can immediately start modifying the table from within:
-
- \snippet richtext/calendar/mainwindow.cpp 9
-
- Since the table has an outer frame, we obtain the frame and its format so that
- we can customize it. After making the changes we want, we set the frame's format
- using the modified format object. We have given the table an outer border one
- pixel wide.
-
- \snippet richtext/calendar/mainwindow.cpp 10
-
- In a similar way, we obtain the cursor's current character format and
- create customized formats based on it.
-
- We do not set the format on the cursor because this would change the default
- character format; instead, we use the customized formats explicitly when we
- insert text. The following loop inserts the days of the week into the table
- as bold text:
-
- \snippet richtext/calendar/mainwindow.cpp 11
-
- For each day of the week, we obtain an existing table cell in the first row
- (row 0) using the table's \l{QTextTable::cellAt()}{cellAt()} function. Since
- we start counting the days of the week at day 1 (Monday), we subtract 1 from
- \c weekDay to ensure that we obtain the cell for the correct column of the
- table.
-
- Before text can be inserted into a cell, we must obtain a cursor with the
- correct position in the document. The cell provides a function for this
- purpose, and we use this cursor to insert text using the \c boldFormat
- character format that we created earlier:
-
- \snippet richtext/calendar/mainwindow.cpp 12
-
- Inserting text into document objects usually follows the same pattern.
- Each object can provide a new cursor that corresponds to the first valid
- position within itself, and this can be used to insert new content. We
- continue to use this pattern as we insert the days of the month into the
- table.
-
- Since every month has more than seven days, we insert a single row to begin
- and add days until we reach the end of the month. If the current date is
- encountered, it is inserted with a special format (created earlier) that
- makes it stand out:
-
- \snippet richtext/calendar/mainwindow.cpp 13
-
- We add a new row to the table at the end of each week only if the next week
- falls within the currently selected month.
-
- For each calendar that we create, we change the window title to reflect the
- currently selected month and year:
-
- \snippet richtext/calendar/mainwindow.cpp 14
-
- The \c insertCalendar() function relies on up-to-date values for the month,
- year, and font size. These are set in the following slots:
-
- \snippet richtext/calendar/mainwindow.cpp 15
-
- The \c setFontSize() function simply changes the private \c fontSize variable
- before updating the calendar.
-
- \snippet richtext/calendar/mainwindow.cpp 16
-
- The \c setMonth slot is called when the QComboBox used to select the month is
- updated. The value supplied is the currently selected row in the combobox.
- We add 1 to this value to obtain a valid month number, and create a new QDate
- based on the existing one. The calendar is then updated to use this new date.
-
- \snippet richtext/calendar/mainwindow.cpp 17
-
- The \c setYear() slot is called when the QDateTimeEdit used to select the
- year is updated. The value supplied is a QDate object; this makes
- the construction of a new value for \c selectedDate simple. We update the
- calendar afterwards to use this new date.
-*/
diff --git a/examples/widgets/doc/src/calendarwidget.qdoc b/examples/widgets/doc/src/calendarwidget.qdoc
index c04fab1fc7..01c6df6926 100644
--- a/examples/widgets/doc/src/calendarwidget.qdoc
+++ b/examples/widgets/doc/src/calendarwidget.qdoc
@@ -1,32 +1,9 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\title Calendar Widget Example
+ \examplecategory {User Interface Components}
\example widgets/calendarwidget
\ingroup examples-widgets
\ingroup examples-layout
diff --git a/examples/widgets/doc/src/charactermap.qdoc b/examples/widgets/doc/src/charactermap.qdoc
deleted file mode 100644
index 3cf4a1210b..0000000000
--- a/examples/widgets/doc/src/charactermap.qdoc
+++ /dev/null
@@ -1,275 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/charactermap
-\title Character Map Example
-\ingroup examples-widgets
-\brief The Character Map example shows how to create a custom widget that can
-both display its own content and respond to user input.
-
-The example displays an array of characters which the user can click on
-to enter text in a line edit. The contents of the line edit can then be
-copied into the clipboard, and pasted into other applications. The
-purpose behind this sort of tool is to allow users to enter characters
-that may be unavailable or difficult to locate on their keyboards.
-
-\borderedimage charactermap-example.png
-\caption Screenshot of the Character Map example
-
-The example consists of the following classes:
-
-\list
-\li \c CharacterWidget displays the available characters in the current
- font and style.
-\li \c MainWindow provides a standard main window that contains font and
- style information, a view onto the characters, a line edit, and a push
- button for submitting text to the clipboard.
-\endlist
-
-\section1 CharacterWidget Class Definition
-
-The \c CharacterWidget class is used to display an array of characters in
-a user-specified font and style. For flexibility, we subclass QWidget and
-reimplement only the functions that we need to provide basic rendering
-and interaction features.
-
-The class definition looks like this:
-
-\snippet widgets/charactermap/characterwidget.h 0
-
-The widget does not contain any other widgets, so it must provide its own
-size hint to allow its contents to be displayed correctly.
-We reimplement \l{QWidget::paintEvent()} to draw custom content. We also
-reimplement \l{QWidget::mousePressEvent()} to allow the user to interact
-with the widget.
-
-The updateFont() and updateStyle() slots are used to update the font and
-style of the characters in the widget whenever the user changes the
-settings in the application.
-The class defines the characterSelected() signal so that other parts
-of the application are informed whenever the user selects a character in
-the widget.
-As a courtesy, the widget provides a tooltip that shows the current
-character value. We reimplement the \l{QWidget::mouseMoveEvent()} event
-handler and define showToolTip() to enable this feature.
-
-The \c columns, \c displayFont and \c currentKey private data members
-are used to record the number of columns to be shown, the current font,
-and the currently highlighted character in the widget.
-
-\section1 CharacterWidget Class Implementation
-
-Since the widget is to be used as a simple canvas, the constructor just
-calls the base class constructor and defines some default values for
-private data members.
-
-\snippet widgets/charactermap/characterwidget.cpp 0
-
-We initialize \c currentKey with a value of -1 to indicate
-that no character is initially selected. We enable mouse tracking to
-allow us to follow the movement of the cursor across the widget.
-
-The class provides two functions to allow the font and style to be set up.
-Each of these modify the widget's display font and call update():
-
-\snippet widgets/charactermap/characterwidget.cpp 1
-\codeline
-\snippet widgets/charactermap/characterwidget.cpp 2
-
-We use a fixed size font for the display. Similarly, a fixed size hint is
-provided by the sizeHint() function:
-
-\snippet widgets/charactermap/characterwidget.cpp 3
-
-Three standard event functions are implemented so that the widget
-can respond to clicks, provide tooltips, and render the available
-characters. The paintEvent() shows how the contents of the widget are
-arranged and displayed:
-
-\snippet widgets/charactermap/characterwidget.cpp 6
-
-A QPainter is created for the widget and, in all cases, we ensure that the
-widget's background is painted. The painter's font is set to the
-user-specified display font.
-
-The area of the widget that needs to be redrawn is used to determine which
-characters need to be displayed:
-
-\snippet widgets/charactermap/characterwidget.cpp 7
-
-Using integer division, we obtain the row and column numbers of each
-characters that should be displayed, and we draw a square on the widget
-for each character displayed.
-
-\snippet widgets/charactermap/characterwidget.cpp 8
-\snippet widgets/charactermap/characterwidget.cpp 9
-
-The symbols for each character in the array are drawn within each square,
-with the symbol for the most recently selected character displayed in red:
-
-\snippet widgets/charactermap/characterwidget.cpp 10
-
-We do not need to take into account the difference between the area
-displayed in the viewport and the area we are drawing on because
-everything outside the visible area will be clipped.
-
-The mousePressEvent() defines how the widget responds to mouse clicks.
-
-\snippet widgets/charactermap/characterwidget.cpp 5
-
-We are only interested when the user clicks with the left mouse button
-over the widget. When this happens, we calculate which character was
-selected and emit the characterSelected() signal.
-The character's number is found by dividing the x and y-coordinates of
-the click by the size of each character's grid square. Since the number
-of columns in the widget is defined by the \c columns variable, we
-simply multiply the row index by that value and add the column number
-to obtain the character number.
-
-If any other mouse button is pressed, the event is passed on to the
-QWidget base class. This ensures that the event can be handled properly
-by any other interested widgets.
-
-The mouseMoveEvent() maps the mouse cursor's position in global
-coordinates to widget coordinates, and determines the character that
-was clicked by performing the calculation
-
-\snippet widgets/charactermap/characterwidget.cpp 4
-
-The tooltip is given a position defined in global coordinates.
-
-\section1 MainWindow Class Definition
-
-The \c MainWindow class provides a minimal user interface for the example,
-with only a constructor, slots that respond to signals emitted by standard
-widgets, and some convenience functions that are used to set up the user
-interface.
-
-The class definition looks like this:
-
-\snippet widgets/charactermap/mainwindow.h 0
-
-The main window contains various widgets that are used to control how
-the characters will be displayed, and defines the findFonts() function
-for clarity and convenience. The findStyles() slot is used by the widgets
-to determine the styles that are available, insertCharacter() inserts
-a user-selected character into the window's line edit, and
-updateClipboard() synchronizes the clipboard with the contents of the
-line edit.
-
-\section1 MainWindow Class Implementation
-
-In the constructor, we set up the window's central widget and fill it with
-some standard widgets (two comboboxes, a line edit, and a push button).
-We also construct a CharacterWidget custom widget, and add a QScrollArea
-so that we can view its contents:
-
-\snippet widgets/charactermap/mainwindow.cpp 0
-
-QScrollArea provides a viewport onto the \c CharacterWidget when we set
-its widget and handles much of the work needed to provide a scrolling
-viewport.
-
-The font combo box is automatically popuplated with a list of available
-fonts. We list the available styles for the current font in the style
-combobox using the following function:
-
-\snippet widgets/charactermap/mainwindow.cpp 1
-
-The line edit and push button are used to supply text to the clipboard:
-
-\snippet widgets/charactermap/mainwindow.cpp 2
-
-We also obtain a clipboard object so that we can send text entered by the
-user to other applications.
-
-Most of the signals emitted in the example come from standard widgets.
-We connect these signals to slots in this class, and to the slots provided
-by other widgets.
-
-\snippet widgets/charactermap/mainwindow.cpp 4
-
-The font combobox's
-\l{QFontComboBox::currentFontChanged()}{currentFontChanged()} signal is
-connected to the findStyles() function so that the list of available styles
-can be shown for each font that is used. Since both the font and the style
-can be changed by the user, the font combobox's currentFontChanged() signal
-and the style combobox's
-\l{QComboBox::currentIndexChanged()}{currentIndexChanged()} are connected
-directly to the character widget.
-
-The final two connections allow characters to be selected in the character
-widget, and text to be inserted into the clipboard:
-
-\snippet widgets/charactermap/mainwindow.cpp 5
-
-The character widget emits the characterSelected() custom signal when
-the user clicks on a character, and this is handled by the insertCharacter()
-function in this class. The clipboard is changed when the push button emits
-the clicked() signal, and we handle this with the updateClipboard() function.
-
-The remaining code in the constructor sets up the layout of the central widget,
-and provides a window title:
-
-\snippet widgets/charactermap/mainwindow.cpp 6
-
-The font combobox is automatically populated with a list of available font
-families. The styles that can be used with each font are found by the
-findStyles() function. This function is called whenever the user selects a
-different font in the font combobox.
-
-\snippet widgets/charactermap/mainwindow.cpp 7
-
-We begin by recording the currently selected style, and we clear the
-style combobox so that we can insert the styles associated with the
-current font family.
-
-\snippet widgets/charactermap/mainwindow.cpp 8
-
-We use the font database to collect the styles that are available for the
-current font, and insert them into the style combobox. The current item is
-reset if the original style is not available for this font.
-
-The last two functions are slots that respond to signals from the character
-widget and the main window's push button. The insertCharacter() function is
-used to insert characters from the character widget when the user clicks a
-character:
-
-\snippet widgets/charactermap/mainwindow.cpp 9
-
-The character is inserted into the line edit at the current cursor position.
-
-The main window's "To clipboard" push button is connected to the
-updateClipboard() function so that, when it is clicked, the clipboard is
-updated to contain the contents of the line edit:
-
-\snippet widgets/charactermap/mainwindow.cpp 10
-
-We copy all the text from the line edit to the clipboard, but we do not clear
-the line edit.
-*/
diff --git a/examples/widgets/doc/src/chart.qdoc b/examples/widgets/doc/src/chart.qdoc
deleted file mode 100644
index e721832c5b..0000000000
--- a/examples/widgets/doc/src/chart.qdoc
+++ /dev/null
@@ -1,82 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 itemviews/chart
- \title Chart Example
- \ingroup examples-itemviews
- \brief The Chart example shows how to create a custom view for the model/view framework.
-
- \image chart-example.png
-
- In this example, the items in a table model are represented as slices in a pie chart,
- relying on the flexibility of the model/view architecture to handle custom editing
- and selection features.
-
- \b{Note that you only need to create a new view class if your data requires a
- specialized representation.} You should first consider using a standard QListView,
- QTableView, or QTreeView with a custom QItemDelegate subclass if you need to
- represent data in a special way.
-
- \omit
- \section1 PieView Class Definition
-
- The \c PieView class is a subclass of QAbstractItemView. The base class provides
- much of the functionality required by view classes, so we only need to provide
- implementations for three public functions: visualRect(), scrollTo(), and
- indexAt(). However, the view needs to maintain strict control over its look and
- feel, so we also provide implementations for a number of other functions:
-
- \snippet itemviews/chart/pieview.h 0
-
-
-
- \section1 PieView Class Implementation
-
- The paint event renders the data from the standard item model as a pie chart.
- We interpret the data in the following way:
-
- \list
- \li Column 0 contains data in two different roles:
- The \l{Qt::ItemDataRole}{DisplayRole} contains a label, and the
- \l{Qt::ItemDataRole}{DecorationRole} contains the color of the pie slice.
- \li Column 1 contains a quantity which we will convert to the angular extent of
- the slice.
- \endlist
-
- The figure is always drawn with the chart on the left and the key on
- the right. This means that we must try and obtain an area that is wider
- than it is tall. We do this by imposing a particular aspect ratio on
- the chart and applying it to the available vertical space. This ensures
- that we always obtain the maximum horizontal space for the aspect ratio
- used.
- We also apply fixed size margin around the figure.
-
- We use logical coordinates to draw the chart and key, and position them
- on the view using viewports.
- \endomit
-*/
diff --git a/examples/widgets/doc/src/chip.qdoc b/examples/widgets/doc/src/chip.qdoc
index 758b692f0e..2c69c10f39 100644
--- a/examples/widgets/doc/src/chip.qdoc
+++ b/examples/widgets/doc/src/chip.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example graphicsview/chip
\title 40000 Chips
+ \examplecategory {Graphics}
\ingroup examples-graphicsview
\brief Visualizes a huge graphic view scene with 40000 chip items.
diff --git a/examples/widgets/doc/src/classwizard.qdoc b/examples/widgets/doc/src/classwizard.qdoc
deleted file mode 100644
index 7f3693b65e..0000000000
--- a/examples/widgets/doc/src/classwizard.qdoc
+++ /dev/null
@@ -1,191 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 dialogs/classwizard
- \title Class Wizard Example
- \ingroup examples-dialogs
-
- \brief The Class Wizard example shows how to implement linear
- wizards using QWizard.
-
- \image classwizard.png Screenshot of the Class Wizard example
-
- Most wizards have a linear structure, with page 1 followed by
- page 2 and so on until the last page. Some wizards are more
- complex in that they allow different traversal paths based on the
- information provided by the user. The
- \l{dialogs/licensewizard}{License Wizard} example shows how to
- create such wizards.
-
- The Class Wizard example consists of the following classes:
-
- \list
- \li \c ClassWizard inherits QWizard and provides a
- three-step wizard that generates the skeleton of a C++ class
- based on the user's input.
- \li \c IntroPage, \c ClassInfoPage, \c CodeStylePage, \c
- OutputFilesPage, and \c ConclusionPage are QWizardPage
- subclasses that implement the wizard pages.
- \endlist
-
- \section1 ClassWizard Class Definition
-
- \image classwizard-flow.png The Class Wizard pages
-
- We will see how to subclass QWizard to implement our own wizard.
- The concrete wizard class is called \c ClassWizard and provides
- five pages:
-
- \list
- \li The first page is an introduction page, telling the user what
- the wizard is going to do.
- \li The second page asks for a class name and a base class, and
- allows the user to specify whether the class should have a \c
- Q_OBJECT macro and what constructors it should provide.
- \li The third page allows the user to set some options related to the code
- style, such as the macro used to protect the header file from
- multiple inclusion (e.g., \c MYDIALOG_H).
- \li The fourth page allows the user to specify the names of the
- output files.
- \li The fifth page is a conclusion page.
- \endlist
-
- Although the program is just an example, if you press \uicontrol Finish
- (\uicontrol Done on \macos), actual C++ source files will actually be
- generated.
-
- \section1 The ClassWizard Class
-
- Here's the \c ClassWizard definition:
-
- \snippet dialogs/classwizard/classwizard.h 0
-
- The class reimplements QDialog's \l{QDialog::}{accept()} slot.
- This slot is called when the user clicks \uicontrol{Finish}.
-
- Here's the constructor:
-
- \snippet dialogs/classwizard/classwizard.cpp 1
-
- We instantiate the five pages and insert them into the wizard
- using QWizard::addPage(). The order in which they are inserted
- is also the order in which they will be shown later on.
-
- We call QWizard::setPixmap() to set the banner and the
- background pixmaps for all pages. The banner is used as a
- background for the page header when the wizard's style is
- \l{QWizard::}{ModernStyle}; the background is used as the
- dialog's background in \l{QWizard::}{MacStyle}. (See \l{Elements
- of a Wizard Page} for more information.)
-
- \snippet dialogs/classwizard/classwizard.cpp 3
- \snippet dialogs/classwizard/classwizard.cpp 4
- \dots
- \snippet dialogs/classwizard/classwizard.cpp 5
- \snippet dialogs/classwizard/classwizard.cpp 6
-
- If the user clicks \uicontrol Finish, we extract the information from
- the various pages using QWizard::field() and generate the files.
- The code is long and tedious (and has barely anything to do with
- noble art of designing wizards), so most of it is skipped here.
- See the actual example in the Qt distribution for the details if
- you're curious.
-
- \section1 The IntroPage Class
-
- The pages are defined in \c classwizard.h and implemented in \c
- classwizard.cpp, together with \c ClassWizard. We will start with
- the easiest page:
-
- \snippet dialogs/classwizard/classwizard.h 1
- \codeline
- \snippet dialogs/classwizard/classwizard.cpp 7
-
- A page inherits from QWizardPage. We set a
- \l{QWizardPage::}{title} and a
- \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting
- any \l{QWizardPage::}{subTitle}, we ensure that no header is
- displayed for this page. (On Windows, it is customary for wizards
- to display a watermark pixmap on the first and last pages, and to
- have a header on the other pages.)
-
- Then we create a QLabel and add it to a layout.
-
- \section1 The ClassInfoPage Class
-
- The second page is defined and implemented as follows:
-
- \snippet dialogs/classwizard/classwizard.h 2
- \codeline
- \snippet dialogs/classwizard/classwizard.cpp 9
- \dots
- \snippet dialogs/classwizard/classwizard.cpp 12
- \dots
- \snippet dialogs/classwizard/classwizard.cpp 13
-
- First, we set the page's \l{QWizardPage::}{title},
- \l{QWizardPage::}{subTitle}, and \l{QWizard::LogoPixmap}{logo
- pixmap}. The logo pixmap is displayed in the page's header in
- \l{QWizard::}{ClassicStyle} and \l{QWizard::}{ModernStyle}.
-
- Then we create the child widgets, create \l{Registering and Using
- Fields}{wizard fields} associated with them, and put them into
- layouts. The \c className field is created with an asterisk (\c
- *) next to its name. This makes it a \l{mandatory fields}{mandatory field}, that
- is, a field that must be filled before the user can press the
- \uicontrol Next button (\uicontrol Continue on \macos). The fields' values
- can be accessed from any other page using QWizardPage::field(),
- or from the wizard code using QWizard::field().
-
- \section1 The CodeStylePage Class
-
- The third page is defined and implemented as follows:
-
- \snippet dialogs/classwizard/classwizard.h 3
- \codeline
- \snippet dialogs/classwizard/classwizard.cpp 14
- \dots
- \snippet dialogs/classwizard/classwizard.cpp 15
- \codeline
- \snippet dialogs/classwizard/classwizard.cpp 16
-
- The code in the constructor is very similar to what we did for \c
- ClassInfoPage, so we skipped most of it.
-
- The \c initializePage() function is what makes this class
- interesting. It is reimplemented from QWizardPage and is used to
- initialize some of the page's fields with values from the
- previous page (namely, \c className and \c baseClass). For
- example, if the class name on page 2 is \c SuperDuperWidget, the
- default macro name on page 3 is \c SUPERDUPERWIDGET_H.
-
- The \c OutputFilesPage and \c ConclusionPage classes are very
- similar to \c CodeStylePage, so we won't review them here.
-
- \sa QWizard, {License Wizard Example}, {Trivial Wizard Example}
-*/
diff --git a/examples/widgets/doc/src/codeeditor.qdoc b/examples/widgets/doc/src/codeeditor.qdoc
deleted file mode 100644
index 7f09f4bba0..0000000000
--- a/examples/widgets/doc/src/codeeditor.qdoc
+++ /dev/null
@@ -1,197 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/codeeditor
- \title Code Editor Example
- \ingroup examples-widgets
- \brief The Code Editor example shows how to create a simple editor that
- has line numbers and that highlights the current line.
-
- \borderedimage codeeditor-example.png
-
- As can be seen from the image, the editor displays the line
- numbers in an area to the left of the area for editing. The editor
- will highlight the line containing the cursor.
-
- We implement the editor in \c CodeEditor, which is a widget that
- inherits QPlainTextEdit. We keep a separate widget in \c
- CodeEditor (\c LineNumberArea) onto which we draw the line
- numbers.
-
- QPlainTextEdit inherits from QAbstractScrollArea, and editing
- takes place within its \l{QAbstractScrollArea::}{viewport()}'s
- margins. We make room for our line number area by setting the left
- margin of the viewport to the size we need to draw the line
- numbers.
-
- When it comes to editing code, we prefer QPlainTextEdit over
- QTextEdit because it is optimized for handling plain text. See
- the QPlainTextEdit class description for details.
-
- QPlainTextEdit lets us add selections in addition to the
- selection the user can make with the mouse or keyboard. We use
- this functionality to highlight the current line. More on this
- later.
-
- We will now move on to the definitions and implementations of \c
- CodeEditor and \c LineNumberArea. Let's start with the \c
- LineNumberArea class.
-
- \section1 The LineNumberArea Class
-
- We paint the line numbers on this widget, and place it over the \c
- CodeEditor's \l{QAbstractScrollArea::}{viewport()}'s left margin
- area.
-
- We need to use protected functions in QPlainTextEdit while
- painting the area. So to keep things simple, we paint the area in
- the \c CodeEditor class. The area also asks the editor to
- calculate its size hint.
-
- Note that we could simply paint the line numbers directly on the
- code editor, and drop the LineNumberArea class. However, the
- QWidget class helps us to \l{QWidget::}{scroll()} its contents.
- Also, having a separate widget is the right choice if we wish to
- extend the editor with breakpoints or other code editor features.
- The widget would then help in the handling of mouse events.
-
- \snippet widgets/codeeditor/codeeditor.h extraarea
-
- \section1 CodeEditor Class Definition
-
- Here is the code editor's class definition:
-
- \snippet widgets/codeeditor/codeeditor.h codeeditordefinition
-
- In the editor we resize and draw the line numbers on the \c
- LineNumberArea. We need to do this when the number of lines in the
- editor changes, and when the editor's viewport() is scrolled. Of
- course, it is also done when the editor's size changes. We do
- this in \c updateLineNumberWidth() and \c updateLineNumberArea().
-
- Whenever, the cursor's position changes, we highlight the current
- line in \c highlightCurrentLine().
-
- \section1 CodeEditor Class Implementation
-
- We will now go through the code editors implementation, starting
- off with the constructor.
-
- \snippet widgets/codeeditor/codeeditor.cpp constructor
-
- In the constructor we connect our slots to signals in
- QPlainTextEdit. It is necessary to calculate the line number area
- width and highlight the first line when the editor is created.
-
- \snippet widgets/codeeditor/codeeditor.cpp extraAreaWidth
-
- The \c lineNumberAreaWidth() function calculates the width of the
- \c LineNumberArea widget. We take the number of digits in the last
- line of the editor and multiply that with the maximum width of a
- digit.
-
- \snippet widgets/codeeditor/codeeditor.cpp slotUpdateExtraAreaWidth
-
- When we update the width of the line number area, we simply call
- QAbstractScrollArea::setViewportMargins().
-
- \snippet widgets/codeeditor/codeeditor.cpp slotUpdateRequest
-
- This slot is invoked when the editors viewport has been scrolled.
- The QRect given as argument is the part of the editing area that
- is do be updated (redrawn). \c dy holds the number of pixels the
- view has been scrolled vertically.
-
- \snippet widgets/codeeditor/codeeditor.cpp resizeEvent
-
- When the size of the editor changes, we also need to resize the
- line number area.
-
- \snippet widgets/codeeditor/codeeditor.cpp cursorPositionChanged
-
- When the cursor position changes, we highlight the current line,
- i.e., the line containing the cursor.
-
- QPlainTextEdit gives the possibility to have more than one
- selection at the same time. we can set the character format
- (QTextCharFormat) of these selections. We clear the cursors
- selection before setting the new new
- QPlainTextEdit::ExtraSelection, else several lines would get
- highlighted when the user selects multiple lines with the mouse.
- \omit ask someone how this works \endomit
-
- One sets the selection with a text cursor. When using the
- FullWidthSelection property, the current cursor text block (line)
- will be selected. If you want to select just a portion of the text
- block, the cursor should be moved with QTextCursor::movePosition()
- from a position set with \l{QTextCursor::}{setPosition()}.
-
- \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_0
-
- The \c lineNumberAreaPaintEvent() is called from \c LineNumberArea
- whenever it receives a paint event. We start off by painting the
- widget's background.
-
- \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_1
-
- We will now loop through all visible lines and paint the line
- numbers in the extra area for each line. Notice that in a plain
- text edit each line will consist of one QTextBlock; though, if
- line wrapping is enabled, a line may span several rows in the text
- edit's viewport.
-
- We get the top and bottom y-coordinate of the first text block,
- and adjust these values by the height of the current text block in
- each iteration in the loop.
-
- \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_2
-
- Notice that we check if the block is visible in addition to check
- if it is in the areas viewport - a block can, for example, be
- hidden by a window placed over the text edit.
-
- \section1 Suggestions for Extending the Code Editor
-
- No self-respecting code editor is without a syntax
- highligther; the \l{Syntax Highlighter Example} shows how to
- create one.
-
- In addition to line numbers, you can add more to the extra area,
- for instance, break points.
-
- QSyntaxHighlighter gives the possibility to add user data to each
- text block with
- \l{QSyntaxHighlighter::}{setCurrentBlockUserData()}. This can be
- used to implement parenthesis matching. In the \c
- highlightCurrentLine(), the data of the currentBlock() can be
- fetched with QTextBlock::userData(). Matching parentheses can be
- highlighted with an extra selection. The "Matching Parentheses
- with QSyntaxHighlighter" article in Qt Quarterly 31 implements
- this. You find it here: \l{http://doc.qt.io/archives/qq/}.
-
-*/
diff --git a/examples/widgets/doc/src/collidingmice-example.qdoc b/examples/widgets/doc/src/collidingmice-example.qdoc
index 984d3244f9..a1b8e0e141 100644
--- a/examples/widgets/doc/src/collidingmice-example.qdoc
+++ b/examples/widgets/doc/src/collidingmice-example.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example graphicsview/collidingmice
\title Colliding Mice Example
+ \examplecategory {Graphics}
\brief Demonstrates how to animate items on a graphics view.
\ingroup examples-graphicsview
@@ -161,7 +138,7 @@
Because the complexity of arbitrary shape-shape intersection grows
with an order of magnitude when the shapes are complex, this
- operation can be noticably time consuming. An alternative approach
+ operation can be noticeably time consuming. An alternative approach
is to reimplement the \l
{QGraphicsItem::collidesWithItem()}{collidesWithItem()} function
to provide your own custom item and shape collision algorithm.
diff --git a/examples/widgets/doc/src/coloreditorfactory.qdoc b/examples/widgets/doc/src/coloreditorfactory.qdoc
index 1471f75e78..f43a7eb95c 100644
--- a/examples/widgets/doc/src/coloreditorfactory.qdoc
+++ b/examples/widgets/doc/src/coloreditorfactory.qdoc
@@ -1,42 +1,19 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example itemviews/coloreditorfactory
\title Color Editor Factory Example
+ \examplecategory {User Interface Components}
\ingroup examples-itemviews
\brief This example shows how to create an editor that can be used by
- a QItemDelegate.
+ a QStyledItemDelegate.
\image coloreditorfactoryimage.png
When editing data in a QListView, QTableView, or QTreeView,
editors are created and displayed by a \l{Delegate
- Classes}{delegate}. QItemDelegate, which is the default delegate
+ Classes}{delegate}. QStyledItemDelegate, which is the default delegate
used by Qt's \l{View Classes}{item views}, uses a
QItemEditorFactory to create editors for it. A unique instance
provided by QItemEditorFactory is by default installed on all
@@ -50,7 +27,7 @@
In this example, we will create an editor (implemented in the \c
ColorListEditor class) that can edit the QColor data type and be
- used by \l{QItemDelegate}s. We do this by creating a new
+ used by \l{QStyledItemDelegate}s. We do this by creating a new
QItemEditorCreatorBase that produces \c ColorListEditors and
register it with a new factory, which we set as the default editor
item factory (the unique factory instance). To test our editor, we
@@ -90,7 +67,7 @@
\snippet itemviews/coloreditorfactory/colorlisteditor.h 0
- QItemDelegate manages the interaction between the editor and
+ QStyledItemDelegate manages the interaction between the editor and
the model, i.e., it retrieves data to edit from the model and
store data from the editor in the model. The data that is edited
by an editor is stored in the editor's user data property, and the
@@ -129,7 +106,7 @@
usually sufficient to provide custom editors. Further
customization is achieved by subclassing QItemEditorFactory
and QItemEditorCreatorBase. It is also possible to subclass
- QItemDelegate if you don't wish to use a factory at all.
+ QStyledItemDelegate if you don't wish to use a factory at all.
Possible suggestions are:
@@ -151,5 +128,5 @@
In this example, we use a standard QVariant data type. You can
also use custom types. In the \l{Star Delegate Example}, we
show how to store a custom data type in a QVariant and paint
- and edit it in a class that inherits QItemDelegate.
+ and edit it in a class that inherits QStyledItemDelegate.
*/
diff --git a/examples/widgets/doc/src/combowidgetmapper.qdoc b/examples/widgets/doc/src/combowidgetmapper.qdoc
index d1b8948b6d..aae546005c 100644
--- a/examples/widgets/doc/src/combowidgetmapper.qdoc
+++ b/examples/widgets/doc/src/combowidgetmapper.qdoc
@@ -1,47 +1,17 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example itemviews/combowidgetmapper
\title Combo Widget Mapper Example
+ \examplecategory {User Interface Components}
\ingroup examples-itemviews
\brief The Combo Widget Mapper example shows how to use a custom delegate to
map information from a model to specific widgets on a form.
\image combowidgetmapper-example.png
- In the \l{Simple Widget Mapper Example}, we showed the basic use of a
- widget mapper to relate data exposed by a model to simple input widgets
- in a user interface. However, sometimes we want to use input widgets that
- expose data as choices to the user, such as QComboBox, and we need a way
- to relate their input to the values stored in the model.
-
- This example is very similar to the \l{Simple Widget Mapper Example}.
- Again, we create a \c Window class with an almost identical user interface,
+ We create a \c Window class with an almost identical user interface,
except that, instead of providing a spin box so that each person's age
can be entered, we provide a combo box to allow their addresses to be
classified as "Home", "Work" or "Other".
@@ -89,8 +59,7 @@
interfering with the other input widgets. The implementation is shown later.
\endomit
- The rest of the constructor is very similar to that of the
- \l{Simple Widget Mapper Example}:
+ The rest of the constructor sets up connections and layouts:
\snippet itemviews/combowidgetmapper/window.cpp Set up connections and layouts
@@ -119,7 +88,7 @@
\section1 Delegate Class Definition and Implementation
The delegate we use to mediate interaction between the widget mapper and
- the input widgets is a small QItemDelegate subclass:
+ the input widgets is a small QStyledItemDelegate subclass:
\snippet itemviews/combowidgetmapper/delegate.h Delegate class definition
@@ -130,7 +99,7 @@
Since we only provide an empty implementation of the constructor, we
concentrate on the other two functions.
- The \l{QItemDelegate::}{setEditorData()} implementation takes the data
+ The \l{QStyledItemDelegate::}{setEditorData()} implementation takes the data
referred to by the model index supplied and processes it according to
the presence of a \c currentIndex property in the editor widget:
@@ -142,10 +111,10 @@
values needed for the \c currentIndex property.
As a result, instead of showing "0", "1" or "2" in the combo box, one of
- its predefined set of items is shown. We call QItemDelegate::setEditorData()
+ its predefined set of items is shown. We call QStyledItemDelegate::setEditorData()
for widgets without the \c currentIndex property.
- The \l{QItemDelegate::}{setModelData()} implementation performs the reverse
+ The \l{QStyledItemDelegate::}{setModelData()} implementation performs the reverse
process, taking the value stored in the widget's \c currentIndex property
and storing it back in the model:
diff --git a/examples/widgets/doc/src/completer.qdoc b/examples/widgets/doc/src/completer.qdoc
index 8c6b0246ea..f3e4fe8f0e 100644
--- a/examples/widgets/doc/src/completer.qdoc
+++ b/examples/widgets/doc/src/completer.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example tools/completer
\title Completer Example
+ \examplecategory {User Interface Components}
\ingroup examples-widgets-tools
\brief The Completer example shows how to provide string-completion facilities
@@ -69,7 +46,7 @@
\snippet tools/completer/fsmodel.cpp 0
As mentioned earlier, the \c data() function is reimplemented in order to
- get it to return the entire file parth for the display role. For example,
+ get it to return the entire file path for the display role. For example,
with a QFileSystemModel, you will see "Program Files" in the view. However, with
\c FileSystemModel, you will see "C:\\Program Files".
@@ -225,7 +202,7 @@
\snippet tools/completer/mainwindow.cpp 14
- The \c changeMaxVisible() update the maximum number of visible items in
+ The \c changeMaxVisible() updates the maximum number of visible items in
the completer.
\snippet tools/completer/mainwindow.cpp 15
diff --git a/examples/widgets/doc/src/composition.qdoc b/examples/widgets/doc/src/composition.qdoc
index 89669e7daa..a8adcd2549 100644
--- a/examples/widgets/doc/src/composition.qdoc
+++ b/examples/widgets/doc/src/composition.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example painting/composition
\title Composition Modes
+ \examplecategory {Graphics}
\ingroup examples-painting
\brief Demonstrates how Composition Modes work in QPainter.
@@ -42,5 +19,5 @@
drawn on top of the destination.
In addition to these standard modes, Qt defines the complete set of composition modes
- as defined by X. Porter and Y. Duff. See the QPainter documentation for details.
+ as defined by T. Porter and T. Duff. See the QPainter documentation for details.
*/
diff --git a/examples/widgets/doc/src/concentriccircles.qdoc b/examples/widgets/doc/src/concentriccircles.qdoc
deleted file mode 100644
index fdf1f88142..0000000000
--- a/examples/widgets/doc/src/concentriccircles.qdoc
+++ /dev/null
@@ -1,233 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 painting/concentriccircles
- \title Concentric Circles Example
- \ingroup examples-painting
- \brief Demonstrates the improved quality that antialiasing and floating point precision gives.
-
- \brief The Concentric Circles example shows the improved rendering
- quality that can be obtained using floating point precision and
- anti-aliasing when drawing custom widgets. The example also shows
- how to do simple animations.
-
- The application's main window displays several widgets which are
- drawn using the various combinations of precision and
- anti-aliasing.
-
- \image concentriccircles-example.png
-
- Anti-aliasing is one of QPainter's render hints. The
- QPainter::RenderHints are used to specify flags to QPainter that
- may, or may not, be respected by any given
- engine. QPainter::Antialiasing indicates that the engine should
- anti-alias the edges of primitives if possible, i.e. put
- additional pixels around the original ones to smooth the edges.
-
- The difference between floating point precision and integer
- precision is a matter of accuracy, and is visible in the
- application's main window: Even though the logic that is
- calculating the circles' geometry is the same, floating points
- ensure that the white spaces between each circle are of the same
- size, while integers make two and two circles appear as if they
- belong together. The reason is that the integer based precision
- rely on rounding off non-integer calculations.
-
- The example consists of two classes:
-
- \list
- \li \c CircleWidget is a custom widget which renders several animated
- concentric circles.
- \li \c Window is the application's main window displaying four \c
- {CircleWidget}s drawn using different combinations of precision
- and aliasing.
- \endlist
-
- First we will review the CircleWidget class, then we will take a
- look at the Window class.
-
- \section1 CircleWidget Class Definition
-
- The CircleWidget class inherits QWidget, and is a custom widget
- which renders several animated concentric circles.
-
- \snippet painting/concentriccircles/circlewidget.h 0
-
- We declare the \c floatBased and \c antialiased variables to hold
- whether an instance of the class should be rendered with integer
- or float based precision, and whether the rendering should be
- anti-aliased or not. We also declare functions setting each of
- these variables.
-
- In addition we reimplement the QWidget::paintEvent() function to
- apply the various combinations of precision and anti-aliasing when
- rendering, and to support the animation. We reimplement the
- QWidget::minimumSizeHint() and QWidget::sizeHint() functions to
- give the widget a reasonable size within our application.
-
- We declare the private \c nextAnimationFrame() slot, and the
- associated \c frameNo variable holding the number of "animation
- frames" for the widget, to facilitate the animation.
-
- \section1 CircleWidget Class Implementation
-
- In the constructor we make the widget's rendering integer based
- and aliased by default:
-
- \snippet painting/concentriccircles/circlewidget.cpp 0
-
- We initialize the widget's \c frameNo variable, and set the
- widget's background color using the QWidget::setBackgroundColor()
- function which takes a \l {QPalette::ColorRole}{color role} as
- argument; the QPalette::Base color role is typically white.
-
- Then we set the widgets size policy using the
- QWidget::setSizePolicy() function. QSizePolicy::Expanding means
- that the widget's \l {QWidget::sizeHint()}{sizeHint()} is a
- sensible size, but that the widget can be shrunk and still be
- useful. The widget can also make use of extra space, so it should
- get as much space as possible.
-
- \snippet painting/concentriccircles/circlewidget.cpp 1
- \codeline
- \snippet painting/concentriccircles/circlewidget.cpp 2
-
- The public \c setFloatBased() and \c setAntialiased() functions
- update the widget's rendering preferences, i.e. whether the widget
- should be rendered with integer or float based precision, and
- whether the rendering should be anti-aliased or not.
-
- The functions also generate a paint event by calling the
- QWidget::update() function, forcing a repaint of the widget with
- the new rendering preferences.
-
- \snippet painting/concentriccircles/circlewidget.cpp 3
- \codeline
- \snippet painting/concentriccircles/circlewidget.cpp 4
-
- The default implementations of the QWidget::minimumSizeHint() and
- QWidget::sizeHint() functions return invalid sizes if there is no
- layout for the widget, otherwise they return the layout's minimum and
- preferred size, respectively.
-
- We reimplement the functions to give the widget minimum and
- preferred sizes which are reasonable within our application.
-
- \snippet painting/concentriccircles/circlewidget.cpp 5
-
- The nextAnimationFrame() slot simply increments the \c frameNo
- variable's value, and calls the QWidget::update() function which
- schedules a paint event for processing when Qt returns to the main
- event loop.
-
- \snippet painting/concentriccircles/circlewidget.cpp 6
-
- A paint event is a request to repaint all or part of the
- widget. The \c paintEvent() function is an event handler that can
- be reimplemented to receive the widget's paint events. We
- reimplement the event handler to apply the various combinations of
- precision and anti-aliasing when rendering the widget, and to
- support the animation.
-
- First, we create a QPainter for the widget, and set its
- antialiased flag to the widget's preferred aliasing. We also
- translate the painters coordinate system, preparing to draw the
- widget's cocentric circles. The translation ensures that the
- center of the circles will be equivalent to the widget's center.
-
- \snippet painting/concentriccircles/circlewidget.cpp 7
-
- When painting a circle, we use the number of "animation frames" to
- determine the alpha channel of the circle's color. The alpha
- channel specifies the color's transparency effect, 0 represents a
- fully transparent color, while 255 represents a fully opaque
- color.
-
- \snippet painting/concentriccircles/circlewidget.cpp 8
-
- If the calculated alpha channel is fully transparent, we don't
- draw anything since that would be equivalent to drawing a white
- circle on a white background. Instead we skip to the next circle
- still creating a white space. If the calculated alpha channel is
- fully opaque, we set the pen (the QColor passed to the QPen
- constructor is converted into the required QBrush by default) and
- draw the circle. If the widget's preferred precision is float
- based, we specify the circle's bounding rectangle using QRectF and
- double values, otherwise we use QRect and integers.
-
- The animation is controlled by the public \c nextAnimationFrame()
- slot: Whenever the \c nextAnimationFrame() slot is called the
- number of frames is incremented and a paint event is
- scheduled. Then, when the widget is repainted, the alpha-blending
- of the circles' colors change and the circles appear as animated.
-
- \section1 Window Class Definition
-
- The Window class inherits QWidget, and is the application's main
- window rendering four \c {CircleWidget}s using different
- combinations of precision and aliasing.
-
- \snippet painting/concentriccircles/window.h 0
-
- We declare the various components of the main window, i.e., the text
- labels and a double array that will hold reference to the four \c
- {CircleWidget}s. In addition we declare the private \c
- createLabel() function to simplify the constructor.
-
- \section1 Window Class Implementation
-
- \snippet painting/concentriccircles/window.cpp 0
-
- In the constructor, we first create the various labels and put
- them in a QGridLayout.
-
- \snippet painting/concentriccircles/window.cpp 1
-
- Then we create a QTimer. The QTimer class is a high-level
- programming interface for timers, and provides repetitive and
- single-shot timers.
-
- We create a timer to facilitate the animation of our concentric
- circles; when we create the four CircleWidget instances (and add
- them to the layout), we connect the QTimer::timeout() signal to
- each of the widgets' \c nextAnimationFrame() slots.
-
- \snippet painting/concentriccircles/window.cpp 2
-
- Before we set the layout and window title for our main window, we
- make the timer start with a timeout interval of 100 milliseconds,
- using the QTimer::start() function. That means that the
- QTimer::timeout() signal will be emitted, forcing a repaint of the
- four \c {CircleWidget}s, every 100 millisecond which is the reason
- the circles appear as animated.
-
- \snippet painting/concentriccircles/window.cpp 3
-
- The private \c createLabel() function is implemented to simlify
- the constructor.
-*/
diff --git a/examples/widgets/doc/src/cuberhiwidget.qdoc b/examples/widgets/doc/src/cuberhiwidget.qdoc
new file mode 100644
index 0000000000..d40459ecf1
--- /dev/null
+++ b/examples/widgets/doc/src/cuberhiwidget.qdoc
@@ -0,0 +1,170 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+ \example rhi/cuberhiwidget
+ \title Cube RHI Widget Example
+ \examplecategory {Graphics}
+ \ingroup examples-widgets
+ \brief Shows how to render a textured cube and integrate with QPainter and widgets, using QRhi Qt's 3D API and shading language abstraction layer.
+
+ \image cuberhiwidget-example.jpg
+ \caption Screenshot of the Cube RHI Widget example
+
+ This example builds on the \l{Simple RHI Widget Example}. While the simple
+ example is intentionally minimal and as compact as possible, rendering only
+ a single triangle with no additional widgets in the window, this
+ application demonstrates:
+
+ \list
+
+ \li Having various widgets in the window, some of them controlling data
+ that is consumed by the QRhiWidget subclass.
+
+ \li Instead of continuously requesting updates, the QRhiWidget here only
+ updates the content in its backing texture when some related data changes.
+
+ \li The cube is textured using a \l QRhiTexture that sources its content
+ from a \l QImage that contains software-based rendering performed with
+ \l QPainter.
+
+ \li The contents of the QRhiWidget \l{QRhiWidget::grab()}{can be
+ read back} and saved to an image file (e.g. a PNG file).
+
+ \li 4x multisample antialiasing \l{QRhiWidget::sampleCount()}{can be toggled}
+ at run time. The QRhiWidget subclass is prepared to handle the changing
+ sample count correctly.
+
+ \li Forcing an \l{QRhiWidget::explicitSize}{explicitly specified backing
+ texture size} can be toggled dynamically and controlled with a slider
+ between 16x16 up to 512x512 pixels.
+
+ \li The QRhiWidget subclass deals with a changing \l QRhi correctly. This
+ can be seen in action when making the widget top-level (no parent; becomes
+ a separate window) and then reparenting it again into the main window's
+ child hierarchy.
+
+ \li Most importantly, some widgets, with semi-transparency even, can be
+ placed on top of the QRhiWidget, proving that correct stacking and blending
+ is feasible. This is a case where QRhiWidget is superior to embedding a
+ native window, i.e. a QRhi-based QWindow using
+ QWidget::createWindowContainer(), because it allows stacking and clipping
+ the same way as any ordinary, software-rendered QWidget, whereas native
+ window embedding may, depending on the platform, have various limitations,
+ e.g. often it can be difficult or inefficient to place additional controls
+ on top.
+
+ \endlist
+
+ In the reimplementation of \l{QRhiWidget::initialize()}{initialize()}, the
+ first thing to do is to check if the QRhi we last worked with is still
+ up-to-date, and if the sample count (for multisample antialiasing) has
+ changed. The former is important because all graphics resources must be
+ released when the QRhi changes, whereas with a dynamically changing sample
+ count a similar problem arises specifically for QRhiGraphicsPipeline
+ objects as those bake the sample count in. For simplicity, the application
+ handles all such changes the same way, by resetting its \c scene struct to
+ a default constructed one, which conveniently drops all graphics resources.
+ All resources are then recreated.
+
+ When the backing texture size (so the render target size) changes, no
+ special action is needed, but a signal is emitted for convenience, just so
+ that main() can reposition the overlay label. The 3D API name is also
+ exposed via a signal by querying \l QRhi::backendName() whenever the QRhi
+ changes.
+
+ The implementation has to be aware that multisample antialiasing implies
+ that \l{QRhiWidget::colorTexture()}{colorTexture()} is \nullptr, while
+ \l{QRhiWidget::msaaColorBuffer()}{msaaColorBuffer()} is valid. This is
+ the opposite of when MSAA is not in use. The reason for differentiating
+ and using different types (QRhiTexture, QRhiRenderBuffer) is to allow
+ using MSAA with 3D graphics APIs that do not have support for
+ multisample textures, but have support for multisample renderbuffers.
+ An example of this is OpenGL ES 3.0.
+
+ When checking the up-to-date pixel size and sample count, a convenient and
+ compact solution is to query via the QRhiRenderTarget, because this way one
+ does not need to check which of colorTexture() and msaaColorBuffer() are
+ valid.
+
+ \snippet rhi/cuberhiwidget/examplewidget.cpp init-1
+
+ The rest is quite self-explanatory. The buffers and pipelines are
+ (re)created, if necessary. The contents of the texture that is used to
+ texture the cube mesh is updated. The scene is rendered using a perspective
+ projection. The view is just a simple translation for now.
+
+ \snippet rhi/cuberhiwidget/examplewidget.cpp init-2
+
+ The function that performs the actual enqueuing of the uniform buffer write
+ is also taking the user-provided rotation into account, thus generating the
+ final modelview-projection matrix.
+
+ \snippet rhi/cuberhiwidget/examplewidget.cpp rotation-update
+
+ Updating the \l QRhiTexture that is sampled in the fragment shader when
+ rendering the cube, is quite simple, even though a lot is happening in
+ there: first a QPainter-based drawing is generated within a QImage. This
+ uses the user-provided text. Then the CPU-side pixel data is uploaded to a
+ texture (more precisely, the upload operation is recorded on a \l
+ QRhiResourceUpdateBatch, which is then submitted later in render()).
+
+ \snippet rhi/cuberhiwidget/examplewidget.cpp texture-update
+
+ The graphics resource initialization is simple. There is only a vertex
+ buffer, no index buffer, and a uniform buffer with only a 4x4 matrix in it
+ (16 floats).
+
+ The texture that contains the QPainter-generated drawing has a size of
+ 512x512. Note that all sizes (texture sizes, viewports, scissors, texture
+ upload regions, etc.) are always in pixels when working with QRhi. To
+ sample this texture in the shader, a \l{QRhiSampler}{sampler object} is
+ needed (irrespective of the fact that QRhi-based applications will
+ typically use combined image samplers in the GLSL shader code, which then
+ may be transpiled to separate texture and sampler objects with some shading
+ languages, or may stay a combined texture-sampler object with others,
+ meaning there may not actually be a native sampler object under the hood at
+ run time, depending on the 3D API, but this is all transparent to the
+ application)
+
+ The vertex shader reads from the uniform buffer at binding point 0,
+ therefore
+ \c{scene.ubuf} is exposed at that binding location. The fragment shader
+ samples a texture provided at binding point 1,
+ therefore a combined texture-sampler pair is specified for that binding location.
+
+ The QRhiGraphicsPipeline enables depth test/write, and culls backfaces. It
+ also relies on a number of defaults, e.g. the depth comparison function
+ defaults to \c Less, which is fine for us, and the front face mode is
+ counter-clockwise, which is also good as-is so does not need to be set
+ again.
+
+ \snippet rhi/cuberhiwidget/examplewidget.cpp setup-scene
+
+ In the reimplementation of \l{QRhiWidget::render()}{render()}, first the
+ user-provided data is checked. If the \l QSlider controlling the rotation
+ has provided a new value, or the \l QTextEdit with the cube text has
+ changed its text, the graphics resources the contents of which depend on
+ such data get updated.
+
+ Then, a single render pass with a single draw call is recorded. The cube
+ mesh data is provided in a non-interleaved format, hence the need for two
+ vertex input bindings, one is the positions (x, y, z) the other is the UVs
+ (u, v), with a start offset that corresponds to 36 x-y-z float pairs.
+
+ \snippet rhi/cuberhiwidget/examplewidget.cpp render
+
+ How is the user-provided data sent? Take the rotation for example. main()
+ connects to the QSlider's \l{QSlider::valueChanged}{valueChanged} signal.
+ When emitted, the connected lamda calls setCubeRotation() on the
+ ExampleRhiWidget. Here, if the value is different from before, it is
+ stored, and a dirty flag is set. Then, most importantly,
+ \l{QWidget::update()}{update()} is called on the ExampleRhiWidget. This is
+ what triggers rendering a new frame into the QRhiWidget's backing texture.
+ Without this the content of the ExampleRhiWidget would not update when
+ dragging the slider.
+
+ \snippet rhi/cuberhiwidget/examplewidget.h data-setters
+
+ \sa QRhi, {Simple RHI Widget Example}, {RHI Window Example}
+*/
diff --git a/examples/widgets/doc/src/customsortfiltermodel.qdoc b/examples/widgets/doc/src/customsortfiltermodel.qdoc
index ebbd29a921..b6ff8e7b48 100644
--- a/examples/widgets/doc/src/customsortfiltermodel.qdoc
+++ b/examples/widgets/doc/src/customsortfiltermodel.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example itemviews/customsortfiltermodel
\title Custom Sort/Filter Model Example
+ \examplecategory {User Interface Components}
\ingroup examples-itemviews
\brief The Custom Sort/Filter Model example illustrates how to subclass
QSortFilterProxyModel to perform advanced sorting and filtering.
diff --git a/examples/widgets/doc/src/deform.qdoc b/examples/widgets/doc/src/deform.qdoc
index db7d7a82c9..f33522fa3b 100644
--- a/examples/widgets/doc/src/deform.qdoc
+++ b/examples/widgets/doc/src/deform.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example painting/deform
\title Vector Deformation
+ \examplecategory {Graphics}
\ingroup examples-painting
\brief Demonstrates how to manipulate the elements of a QPainterPath.
diff --git a/examples/widgets/doc/src/diagramscene.qdoc b/examples/widgets/doc/src/diagramscene.qdoc
index 6a38ebd2c5..6f307ef97c 100644
--- a/examples/widgets/doc/src/diagramscene.qdoc
+++ b/examples/widgets/doc/src/diagramscene.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example graphicsview/diagramscene
\title Diagram Scene Example
+ \examplecategory {Graphics}
\ingroup examples-graphicsview
\brief Demonstrate how to use the Graphics View framework.
@@ -36,7 +13,7 @@
The Diagram Scene example is an application in which you can
create a flowchart diagram. It is possible to add flowchart shapes
and text and connect the shapes by arrows as shown in the image
- above. The shapes, arrows, and text can be given different
+ above. The shapes, arrows, and text can be given different
colors, and it is possible to change the font, style, and
underline of the text.
@@ -145,9 +122,7 @@
We show an example of the creation of an action. The
functionality the actions trigger is discussed in the slots we
- connect the actions to. You can see the \l{Qt Widgets - Application
- Example}{application example} if you need a high-level
- introduction to actions.
+ connect the actions to.
The is the \c createMenus() function:
@@ -313,7 +288,7 @@
added to the scene. We set the mode of the scene back to the mode
before the item was inserted, which is ItemMove or InsertText
depending on which button is checked in the \c pointerTypeGroup.
- We must also uncheck the button in the in the \c buttonGroup.
+ We must also uncheck the button in the \c buttonGroup.
Here is the implementation of \c textInserted():
diff --git a/examples/widgets/doc/src/digitalclock.qdoc b/examples/widgets/doc/src/digitalclock.qdoc
deleted file mode 100644
index aff349adb8..0000000000
--- a/examples/widgets/doc/src/digitalclock.qdoc
+++ /dev/null
@@ -1,75 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/digitalclock
- \title Digital Clock Example
- \ingroup examples-widgets
- \brief The Digital Clock example shows how to use QLCDNumber to display a
- number with LCD-like digits.
-
- \borderedimage digitalclock-example.png
- \caption Screenshot of the Digital Clock example
-
- This example also demonstrates how QTimer can be used to update a widget
- at regular intervals.
-
- \section1 DigitalClock Class Definition
-
- The \c DigitalClock class provides a clock widget showing the time with
- hours and minutes separated by a blinking colon. We subclass QLCDNumber
- and implement a private slot called \c showTime() to update the clock
- display:
-
- \snippet widgets/digitalclock/digitalclock.h 0
-
- \section1 DigitalClock Class Implementation
-
- \snippet widgets/digitalclock/digitalclock.cpp 0
-
- In the constructor, we first change the look of the LCD numbers. The
- QLCDNumber::Filled style produces raised segments filled with the
- foreground color (typically black). We also set up a one-second timer
- to keep track of the current time, and we connect
- its \l{QTimer::timeout()}{timeout()} signal to the private \c showTime() slot
- so that the display is updated every second. Then, we
- call the \c showTime() slot; without this call, there would be a one-second
- delay at startup before the time is shown.
-
- \snippet widgets/digitalclock/digitalclock.cpp 1
- \snippet widgets/digitalclock/digitalclock.cpp 2
-
- The \c showTime() slot is called whenever the clock display needs
- to be updated.
-
- The current time is converted into a string with the format "hh:mm".
- When QTime::second() is a even number, the colon in the string is
- replaced with a space. This makes the colon appear and vanish every
- other second.
-
- Finally, we call QLCDNumber::display() to update the widget.
-*/
diff --git a/examples/widgets/doc/src/dirview.qdoc b/examples/widgets/doc/src/dirview.qdoc
deleted file mode 100644
index d8c68bf41e..0000000000
--- a/examples/widgets/doc/src/dirview.qdoc
+++ /dev/null
@@ -1,73 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 itemviews/dirview
- \title Dir View Example
- \ingroup examples-itemviews
- \brief This example demonstrates the usage of a tree view, and smooth flicking on a touchscreen.
-
- The Dir View example shows a tree view of the local file
- system. It uses the QFileSystemModel class to provide file
- and directory information.
-
- \borderedimage dirview-example.png
-
- \quotefromfile itemviews/dirview/main.cpp
- \skipto QCommandLineParser parser
- \printuntil parser.positionalArguments
-
- The example supports a number of command line options.
- These options include:
- \list
- \li Application description
- \li -help option
- \li -version option
- \li if the optionc {-c} is specified, the application will not
- use custom directory options
- \endlist
-
- \skipto QFileSystemModel
- \printuntil tree.setModel
-
- Declares \c model as data model for reading the local filesystem.
- \c model.setRootPath("") sets the current folder as the folder from
- which \c model will start reading.
- QTreeView object \c tree visualizes the filesystem in a tree structure.
-
- \skipto tree.setAnimated(false)
- \printuntil tree.setColumnWidth
-
- Sets layout options for animation, indentation, sorting, and sizing of the
- filesystem tree.
-
- \skipto QScroller::grabGesture
- \printuntil QScroller::grabGesture
-
- Creates a \l QScroller instance to recognize gestures on touchscreens,
- so that you can flick the tree view with your finger.
-*/
diff --git a/examples/widgets/doc/src/dockwidgets.qdoc b/examples/widgets/doc/src/dockwidgets.qdoc
deleted file mode 100644
index 34190f6d2e..0000000000
--- a/examples/widgets/doc/src/dockwidgets.qdoc
+++ /dev/null
@@ -1,164 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 mainwindows/dockwidgets
- \title Dock Widgets Example
- \ingroup examples-mainwindow
-
- \brief The Dock Widgets example shows how to add dock windows to an
- application. It also shows how to use Qt's rich text engine.
-
- \image dockwidgets-example.png Screenshot of the Dock Widgets example
-
- The application presents a simple business letter template, and has
- a list of customer names and addresses and a list of standard
- phrases in two dock windows. The user can click a customer to have
- their name and address inserted into the template, and click one or
- more of the standard phrases. Errors can be corrected by clicking
- the Undo button. Once the letter has been prepared it can be printed
- or saved as HTML.
-
- \section1 MainWindow Class Definition
-
- Here's the class definition:
-
- \snippet mainwindows/dockwidgets/mainwindow.h 0
-
- We will now review each function in turn.
-
- \section1 MainWindow Class Implementation
-
- \snippet mainwindows/dockwidgets/mainwindow.cpp 0
-
- We start by including \c <QtWidgets>, a header file that contains the
- definition of all classes in the Qt Core, Qt GUI and Qt Widgets
- modules. This saves us from having to include
- every class individually and is especially convenient if we add new
- widgets. We also include \c mainwindow.h.
-
- \snippet mainwindows/dockwidgets/mainwindow.cpp 1
-
- In the constructor, we start by creating a QTextEdit widget. Then we call
- QMainWindow::setCentralWidget(). This function passes ownership of
- the QTextEdit to the \c MainWindow and tells the \c MainWindow that
- the QTextEdit will occupy the \c MainWindow's central area.
-
- Then we call \c createActions(), \c createMenus(), \c
- createToolBars(), \c createStatusBar(), and \c createDockWindows()
- to set up the user interface. Finally we call \c setWindowTitle() to
- give the application a title, and \c newLetter() to create a new
- letter template.
-
- We won't quote the \c createActions(), \c createMenus(), \c
- createToolBars(), and \c createStatusBar() functions since they
- follow the same pattern as all the other Qt examples.
-
- \snippet mainwindows/dockwidgets/mainwindow.cpp 9
-
- We create the customers dock window first, and in addition to a
- window title, we also pass it a \c this pointer so that it becomes a
- child of \c MainWindow. Normally we don't have to pass a parent
- because widgets are parented automatically when they are laid out:
- but dock windows aren't laid out using layouts.
-
- We've chosen to restrict the customers dock window to the left and
- right dock areas. (So the user cannot drag the dock window to the
- top or bottom dock areas.) The user can drag the dock window out of
- the dock areas entirely so that it becomes a free floating window.
- We can change this (and whether the dock window is moveable or
- closable) using QDockWidget::setFeatures().
-
- Once we've created the dock window we create a list widget with the
- dock window as parent, then we populate the list and make it the
- dock window's widget. Finally we add the dock widget to the \c
- MainWindow using \c addDockWidget(), choosing to put it in the right
- dock area.
-
- We undertake a similar process for the paragraphs dock window,
- except that we don't restrict which dock areas it can be dragged to.
-
- Finally we set up the signal-slot connections. If the user clicks a
- customer or a paragraph their \c currentTextChanged() signal will be
- emitted and we connect these to \c insertCustomer() and
- addParagraph() passing the text that was clicked.
-
- We briefly discuss the rest of the implementation, but have now
- covered everything relating to dock windows.
-
- \snippet mainwindows/dockwidgets/mainwindow.cpp 2
-
- In this function we clear the QTextEdit so that it is empty. Next we
- create a QTextCursor on the QTextEdit. We move the cursor to the
- start of the document and create and format a frame. We then create
- some character formats and a table format. We insert a table into
- the document and insert the company's name and address into a table
- using the table and character formats we created earlier. Then we
- insert the skeleton of the letter including two markers \c NAME and
- \c ADDRESS. We will also use the \c{Yours sincerely,} text as a marker.
-
- \snippet mainwindows/dockwidgets/mainwindow.cpp 6
-
- If the user clicks a customer we split the customer details into
- pieces. We then look for the \c NAME marker using the \c find()
- function. This function selects the text it finds, so when we call
- \c insertText() with the customer's name the name replaces the marker.
- We then look for the \c ADDRESS marker and replace it with each line
- of the customer's address. Notice that we wrapped all the insertions
- between a \c beginEditBlock() and \c endEditBlock() pair. This means
- that the entire name and address insertion is treated as a single
- operation by the QTextEdit, so a single undo will revert all the
- insertions.
-
- \snippet mainwindows/dockwidgets/mainwindow.cpp 7
-
- This function works in a similar way to \c insertCustomer(). First
- we look for the marker, in this case, \c {Yours sincerely,}, and then
- replace it with the standard paragraph that the user clicked. Again
- we use a \c beginEditBlock() ... \c endEditBlock() pair so that the
- insertion can be undone as a single operation.
-
- \snippet mainwindows/dockwidgets/mainwindow.cpp 3
-
- Qt's QTextDocument class makes printing documents easy. We simply
- take the QTextEdit's QTextDocument, set up the printer and print the
- document.
-
- \snippet mainwindows/dockwidgets/mainwindow.cpp 4
-
- QTextEdit can output its contents in HTML format, so we prompt the
- user for the name of an HTML file and if they provide one we simply
- write the QTextEdit's contents in HTML format to the file.
-
- \snippet mainwindows/dockwidgets/mainwindow.cpp 5
-
- If the focus is in the QTextEdit, pressing \uicontrol Ctrl+Z undoes as
- expected. But for the user's convenience we provide an
- application-wide undo function that simply calls the QTextEdit's
- undo: this means that the user can undo regardless of where the
- focus is in the application.
-*/
diff --git a/examples/widgets/doc/src/draganddroppuzzle.qdoc b/examples/widgets/doc/src/draganddroppuzzle.qdoc
deleted file mode 100644
index b318cc2fb9..0000000000
--- a/examples/widgets/doc/src/draganddroppuzzle.qdoc
+++ /dev/null
@@ -1,42 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 draganddrop/puzzle
- \title Drag and Drop Puzzle Example
-
- \brief The Drag and Drop Puzzle example demonstrates a way of using the drag and drop system with
- item view widgets.
-
- \image draganddroppuzzle-example.png
-
- This example is an implementation of a simple jigsaw puzzle game using Qt's
- drag and drop API.
- The \l{Item Views Puzzle Example}{Item View Puzzle} example shows
- many of the same features, but takes an alternative approach that uses Qt's
- model/view framework to manage drag and drop operations.
-*/
diff --git a/examples/widgets/doc/src/dragdroprobot.qdoc b/examples/widgets/doc/src/dragdroprobot.qdoc
index ac138072c9..c9ff04574b 100644
--- a/examples/widgets/doc/src/dragdroprobot.qdoc
+++ b/examples/widgets/doc/src/dragdroprobot.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example graphicsview/dragdroprobot
\title Drag and Drop Robot Example
+ \examplecategory {Graphics}
\ingroup examples-graphicsview
\brief Demonstrates how to drag and drop items in a graphics view.
@@ -319,7 +296,7 @@
This snippet has a somewhat random outcome: once in a while, a special
image is assigned to the drag object's mime data. The pixmap is also
- assiged as the drag object's pixmap. This will ensure that you can see the
+ assigned as the drag object's pixmap. This will ensure that you can see the
image that is being dragged as a pixmap under the mouse cursor.
\snippet graphicsview/dragdroprobot/coloritem.cpp 7
diff --git a/examples/widgets/doc/src/draggableicons.qdoc b/examples/widgets/doc/src/draggableicons.qdoc
index 7c5b5dc574..fd4f9e69e3 100644
--- a/examples/widgets/doc/src/draggableicons.qdoc
+++ b/examples/widgets/doc/src/draggableicons.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example draganddrop/draggableicons
\title Draggable Icons Example
+ \examplecategory {User Interface Components}
\brief The Draggable Icons example shows how to drag and drop image data between widgets
in the same application, and between different applications.
diff --git a/examples/widgets/doc/src/draggabletext.qdoc b/examples/widgets/doc/src/draggabletext.qdoc
index e934119e7a..6e15e7f946 100644
--- a/examples/widgets/doc/src/draggabletext.qdoc
+++ b/examples/widgets/doc/src/draggabletext.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example draganddrop/draggabletext
\title Draggable Text Example
+ \examplecategory {User Interface Components}
\brief Illustrates how to drag and drop text between widgets.
\brief The Draggable Text example shows how to drag and drop textual data between widgets
diff --git a/examples/widgets/doc/src/dynamiclayouts.qdoc b/examples/widgets/doc/src/dynamiclayouts.qdoc
deleted file mode 100644
index 0b9d43c98e..0000000000
--- a/examples/widgets/doc/src/dynamiclayouts.qdoc
+++ /dev/null
@@ -1,115 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 layouts/dynamiclayouts
- \title Dynamic Layouts Example
- \brief Shows how to re-orient widgets in running applications.
-
- \e{Dynamic Layouts} implements dynamically placed widgets within running
- applications. The widget placement depends on whether \c Horizontal or \c
- Vertical is chosen.
-
- \borderedimage dynamiclayouts-example.png
- For more information, visit the \l{Layout Management} page.
-
- \section1 Dialog Constructor
-
- To begin with, the application creates the UI components by calling the
- following methods:
-
- \list
- \li createRotatableGroupBox()
- \li createOptionsGroupBox()
- \li createButtonBox()
- \endlist
-
- It then adds the UI components to a GridLayout (\c mainLayout).
-
- Finally, \c Dialog::rotateWidgets() is called.
-
- \quotefromfile layouts/dynamiclayouts/dialog.cpp
- \skipuntil createRotatableGroupBox
- \printuntil setWindowTitle
-
- \section1 Creating the Main Widgets
-
- The \c createRotatableGroupBox() method creates a rotatable group box,
- then adds a series of widgets:
-
- \list
- \li QSpinBox
- \li QSlider
- \li QDial
- \li QProgressBar
- \endlist
-
- It goes on to add signals and slots to each widget, and assigns
- a QGridLayout called \a rotatableLayout.
-
- \skipto Dialog::createRotatableGroupBox
- \printuntil /^\}/
-
- \section1 Adding Options
-
- \c createOptionsGroupBox() creates the following widgets:
- \list
- \li \c optionsGroupBox
- \li \c buttonsOrientationLabel
- \li \c buttonsOrientationComboBox. The orientation of the ComboBox is either
- \c horizontal (default value) or \c vertical. These two values
- are added during the startup of the application. It is not possible
- to leave the option empty.
- \endlist
-
- \skipto Dialog::createOptionsGroupBox()
- \printuntil /^\}/
-
- \section1 Adding Buttons
-
- createButtonBox() constructs a QDialogButtonBox called \c buttonBox
- to which are added a \c closeButton, a \c helpButton and a
- \c rotateWidgetsButton.
- It then assigns a signal and a slot to each button in \c buttonBox.
-
- \skipto Dialog::createButtonBox()
- \printuntil /^\}/
-
-
- \section1 Rotating the Widgets
-
- Removes the current widgets and activates the next widget.
-
- \quotefromfile layouts/dynamiclayouts/dialog.cpp
- \skipto Dialog::rotateWidgets()
- \printuntil rotatableLayout->addWidget(rotatableWidgets[i]
- \printuntil }
- \printuntil }
-
- \include examples-run.qdocinc
-*/
-
diff --git a/examples/widgets/doc/src/easing.qdoc b/examples/widgets/doc/src/easing.qdoc
index 807dd72e93..79c985392c 100644
--- a/examples/widgets/doc/src/easing.qdoc
+++ b/examples/widgets/doc/src/easing.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example animation/easing
\title Easing Curves Example
+ \examplecategory {Multimedia}
\brief The Easing Curves example shows how to use easing curves to
control the speed of an animation.
diff --git a/examples/widgets/doc/src/echoplugin.qdoc b/examples/widgets/doc/src/echoplugin.qdoc
deleted file mode 100644
index 28be789c5c..0000000000
--- a/examples/widgets/doc/src/echoplugin.qdoc
+++ /dev/null
@@ -1,205 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 tools/echoplugin
- \title Echo Plugin Example
- \ingroup examples-widgets-tools
- \ingroup examples-layout
-
- \brief This example shows how to create a Qt plugin.
-
- \image echopluginexample.png
-
- There are two kinds of plugins in Qt: plugins that extend Qt
- itself and plugins that extend applications written in Qt. In this
- example, we show the procedure of implementing plugins that extend
- applications. When you create a plugin you declare an interface,
- which is a class with only pure virtual functions. This interface
- is inherited by the class that implements the plugin. The class is
- stored in a shared library and can therefore be loaded by
- applications at run-time. When loaded, the plugin is dynamically
- cast to the interface using Qt's \l{Meta-Object
- System}{meta-object system}. The plugin \l{How to Create Qt
- Plugins}{overview document} gives a high-level introduction to
- plugins.
-
- We have implemented a plugin, the \c EchoPlugin, which implements
- the \c EchoInterface. The interface consists of \c echo(), which
- takes a QString as argument. The \c EchoPlugin returns the string
- unaltered (i.e., it works as the familiar echo command found in
- both Unix and Windows).
-
- We test the plugin in \c EchoWindow: when you push the QPushButton
- (as seen in the image above), the application sends the text in
- the QLineEdit to the plugin, which echoes it back to the
- application. The answer from the plugin is displayed in the
- QLabel.
-
-
- \section1 EchoWindow Class Definition
-
- The \c EchoWindow class lets us test the \c EchoPlugin through a
- GUI.
-
- \snippet tools/echoplugin/echowindow/echowindow.h 0
-
- We load the plugin in \c loadPlugin() and cast it to \c
- EchoInterface. When the user clicks the \c button we take the
- text in \c lineEdit and call the interface's \c echo() with it.
-
-
- \section1 EchoWindow Class Implementation
-
- We start with a look at the constructor:
-
- \snippet tools/echoplugin/echowindow/echowindow.cpp 0
-
- We create the widgets and set a title for the window. We then load
- the plugin. \c loadPlugin() returns false if the plugin could not
- be loaded, in which case we disable the widgets. If you wish a
- more detailed error message, you can use
- \l{QPluginLoader::}{errorString()}; we will look more closely at
- QPluginLoader later.
-
- Here is the implementation of \c sendEcho():
-
- \snippet tools/echoplugin/echowindow/echowindow.cpp 1
-
- This slot is called when the user pushes \c button or presses
- enter in \c lineEdit. We call \c echo() of the echo interface. In
- our example this is the \c EchoPlugin, but it could be any plugin
- that inherit the \c EchoInterface. We take the QString returned
- from \c echo() and display it in the \c label.
-
- Here is the implementation of \c createGUI():
-
- \snippet tools/echoplugin/echowindow/echowindow.cpp 2
-
- We create the widgets and lay them out in a grid layout. We
- connect the label and line edit to our \c sendEcho() slot.
-
- Here is the \c loadPlugin() function:
-
- \snippet tools/echoplugin/echowindow/echowindow.cpp 3
-
- Access to plugins at run-time is provided by QPluginLoader. You
- supply it with the filename of the shared library the plugin is
- stored in and call \l{QPluginLoader::}{instance()}, which loads
- and returns the root component of the plugin (i.e., it resolves
- the type of the plugin and creates a QObject instance of it). If
- the plugin was not successfully loaded, it will be null, so we
- return false. If it was loaded correctly, we can cast the plugin
- to our \c EchoInterface and return true. In the case that the
- plugin loaded does not implement the \c EchoInterface, \c
- instance() will return null, but this cannot happen in our
- example. Notice that the location of the plugin is not the same
- for all platforms.
-
-
- \section1 EchoInterface Class Definition
-
- The \c EchoInterface defines the functions that the plugin will
- provide. An interface is a class that only consists of pure
- virtual functions. If non virtual functions were present in the
- class you would get misleading compile errors in the moc files.
-
- \snippet tools/echoplugin/echowindow/echointerface.h 0
-
- We declare \c echo(). In our \c EchoPlugin we use this method to
- return, or echo, \a message.
-
- We use the Q_DECLARE_INTERFACE macro to let \l{Meta-Object
- System}{Qt's meta object system} aware of the interface. We do
- this so that it will be possible to identify plugins that
- implements the interface at run-time. The second argument is a
- string that must identify the interface in a unique way.
-
-
- \section1 EchoPlugin Class Definition
-
- We inherit both QObject and \c EchoInterface to make this class a
- plugin. The Q_INTERFACES macro tells Qt which interfaces the class
- implements. In our case we only implement the \c EchoInterface.
- If a class implements more than one interface, they are given as
- a space separated list. The Q_PLUGIN_METADATA macro is included next
- to the Q_OBJECT macro. It contains the plugins IID and a filename
- pointing to a json file containing the metadata for the plugin.
- The json file is compiled into the plugin and does not need to be installed.
-
- \snippet tools/echoplugin/plugin/echoplugin.h 0
-
- \section1 EchoPlugin Class Implementation
-
- Here is the implementation of \c echo():
-
- \snippet tools/echoplugin/plugin/echoplugin.cpp 0
-
- We simply return the functions parameter.
-
- \section1 The \c main() function
-
- \snippet tools/echoplugin/echowindow/main.cpp 0
-
- We create an \c EchoWindow and display it as a top-level window.
-
- \section1 The Profiles
-
- When creating plugins the profiles need to be adjusted.
- We show here what changes need to be done.
-
- The profile in the echoplugin directory uses the \c subdirs
- template and simply includes includes to directories in which
- the echo window and echo plugin lives:
-
- \snippet tools/echoplugin/echoplugin.pro 0
-
- The profile for the echo window does not need any plugin specific
- settings. We move on to the plugin profile:
-
- \snippet tools/echoplugin/plugin/plugin.pro 0
-
- We need to set the TEMPLATE as we now want to make a library
- instead of an executable. We also need to tell qmake that we are
- creating a plugin. The \c EchoInterface that the plugin implements
- lives in the \c echowindow directory, so we need to add that
- directory to the include path. We set the TARGET of the project,
- which is the name of the library file in which the plugin will be
- stored; qmake appends the appropriate file extension depending on
- the platform. By convention the target should have the same name
- as the plugin (set with Q_EXPORT_PLUGIN2)
-
- \section1 Further Reading and Examples
-
- The \l {qtplugin-defining-plugins}{Defining Plugins} page presents an overview of the macros needed to
- create plugins.
-
- We give an example of a plugin that extends Qt in the \l{Style
- Plugin Example}{style plugin} example. The \l{Plug & Paint
- Example}{plug and paint} example shows how to create static
- plugins.
-*/
diff --git a/examples/widgets/doc/src/editabletreemodel.qdoc b/examples/widgets/doc/src/editabletreemodel.qdoc
index 68e10e3e78..15df678c87 100644
--- a/examples/widgets/doc/src/editabletreemodel.qdoc
+++ b/examples/widgets/doc/src/editabletreemodel.qdoc
@@ -1,36 +1,13 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example itemviews/editabletreemodel
\title Editable Tree Model Example
+ \examplecategory {User Interface Components}
\ingroup examples-itemviews
\brief This example shows how to implement a simple item-based tree model that can
- be used with other classes the model/view framework.
+ be used with other classes in the model/view framework.
\image itemviews-editabletreemodel.png
@@ -108,7 +85,7 @@
\l{TreeItem::data}{data()} function to read entries in the \c itemData
list and a \l{TreeItem::setData}{setData()} function to allow them to
be modified.
- As with other functions in the item, this simplifies the implemention
+ As with other functions in the item, this simplifies the implementation
of the model's \l{QAbstractItemModel::}{data()} and
\l{QAbstractItemModel::}{setData()} functions.
@@ -253,32 +230,30 @@
internal \c childItems member using the \c insertChildren() function
described later.
- The destructor ensures that each child added to the item is deleted
- when the item itself is deleted:
-
- \snippet itemviews/editabletreemodel/treeitem.cpp 1
+ The children are stored in std::unique_ptr to ensures that each child
+ added to the item is deleted when the item itself is deleted.
\target TreeItem::parent
Since each item stores a pointer to its parent, the \c parent() function
is trivial:
- \snippet itemviews/editabletreemodel/treeitem.cpp 9
+ \snippet itemviews/editabletreemodel/treeitem.cpp 8
\target TreeItem::child
Three functions provide information about the children of an item.
\c child() returns a specific child from the internal list of children:
- \snippet itemviews/editabletreemodel/treeitem.cpp 2
+ \snippet itemviews/editabletreemodel/treeitem.cpp 1
The \c childCount() function returns the total number of children:
- \snippet itemviews/editabletreemodel/treeitem.cpp 3
+ \snippet itemviews/editabletreemodel/treeitem.cpp 2
The \c childNumber() function is used to determine the index of the child
in its parent's list of children. It accesses the parent's \c childItems
member directly to obtain this information:
- \snippet itemviews/editabletreemodel/treeitem.cpp 4
+ \snippet itemviews/editabletreemodel/treeitem.cpp 3
The root item has no parent item; for this item, we return zero to be
consistent with the other items.
@@ -286,20 +261,20 @@
The \c columnCount() function simply returns the number of elements in
the internal \c itemData list of QVariant objects:
- \snippet itemviews/editabletreemodel/treeitem.cpp 5
+ \snippet itemviews/editabletreemodel/treeitem.cpp 4
\target TreeItem::data
Data is retrieved using the \c data() function, which accesses the
appropriate element in the \c itemData list:
- \snippet itemviews/editabletreemodel/treeitem.cpp 6
+ \snippet itemviews/editabletreemodel/treeitem.cpp 5
\target TreeItem::setData
Data is set using the \c setData() function, which only stores values
in the \c itemData list for valid list indexes, corresponding to column
values in the model:
- \snippet itemviews/editabletreemodel/treeitem.cpp 11
+ \snippet itemviews/editabletreemodel/treeitem.cpp 10
To make implementation of the model easier, we return true to indicate
that the data was set successfully.
@@ -309,20 +284,20 @@
in the model leads to the insertion of new child items in the corresponding
item, handled by the \c insertChildren() function:
- \snippet itemviews/editabletreemodel/treeitem.cpp 7
+ \snippet itemviews/editabletreemodel/treeitem.cpp 6
This ensures that new items are created with the required number of columns
and inserted at a valid position in the internal \c childItems list.
Items are removed with the \c removeChildren() function:
- \snippet itemviews/editabletreemodel/treeitem.cpp 10
+ \snippet itemviews/editabletreemodel/treeitem.cpp 9
As discussed above, the functions for inserting and removing columns are
used differently to those for inserting and removing child items because
they are expected to be called on every item in the tree. We do this by
recursively calling this function on each child of the item:
- \snippet itemviews/editabletreemodel/treeitem.cpp 8
+ \snippet itemviews/editabletreemodel/treeitem.cpp 7
\section1 TreeModel Class Definition
@@ -358,11 +333,12 @@
use with the model. Other models may be initialized with a ready-made
data structure, or use an API from a library that maintains its own data.
- The destructor only has to delete the root item, which will cause all child
- items to be recursively deleted.
-
\snippet itemviews/editabletreemodel/treemodel.cpp 1
+ The destructor only has to delete the root item, which will cause all child
+ items to be recursively deleted. This is done automatically by the default
+ destructor since the root item is stored inside an unique_ptr.
+
\target TreeModel::getItem
Since the model's interface to the other model/view components is based
on model indexes, and since the internal data structure is item-based,
@@ -443,4 +419,20 @@
\target TreeModel::data
\target TreeModel::setupModelData
+ \section1 Testing the model
+
+ Correctly implementing an item model can be challenging. The class
+ \l [QtTest] QAbstractItemModelTester from the \l [QtTest]{Qt Test} module
+ checks for model consistency, like the model index creation and
+ parent-child relationships.
+
+ You can test your model by just passing a model instance to the class
+ constructor, for instance as part of a Qt unit test:
+
+ \snippet itemviews/editabletreemodel/test.cpp 1
+
+ To create a test which can be run using the \c ctest executable,
+ \c add_test() is used:
+
+ \snippet itemviews/editabletreemodel/CMakeLists.txt 1
*/
diff --git a/examples/widgets/doc/src/elasticnodes.qdoc b/examples/widgets/doc/src/elasticnodes.qdoc
index e78db67be2..c25fd68009 100644
--- a/examples/widgets/doc/src/elasticnodes.qdoc
+++ b/examples/widgets/doc/src/elasticnodes.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example graphicsview/elasticnodes
\title Elastic Nodes Example
+ \examplecategory {Graphics}
\ingroup examples-graphicsview
\brief Demonstrates how to interact with graphical items in a scene.
@@ -259,7 +236,7 @@
This ensures that the edge items are not considered for mouse input at all
(i.e., you cannot click the edges). Then, the source and destination
pointers are updated, this edge is registered with each node, and we call
- \c adjust() to update this edge's start end end position.
+ \c adjust() to update this edge's start and end position.
\snippet graphicsview/elasticnodes/edge.cpp 1
@@ -355,7 +332,7 @@
collection of small items that all move around, it's unnecessary for
Graphics View to waste time finding accurate update regions, so we set the
QGraphicsView::BoundingRectViewportUpdate viewport update mode. The default
- would work fine, but this mode is noticably faster for this example.
+ would work fine, but this mode is noticeably faster for this example.
To improve rendering quality, we set QPainter::Antialiasing.
diff --git a/examples/widgets/doc/src/elidedlabel.qdoc b/examples/widgets/doc/src/elidedlabel.qdoc
deleted file mode 100644
index b731b60e83..0000000000
--- a/examples/widgets/doc/src/elidedlabel.qdoc
+++ /dev/null
@@ -1,155 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/elidedlabel
- \title Elided Label Example
-
- \brief This example creates a widget similar to QLabel, that elides the last
- visible line, if the text is too long to fit the widget's geometry.
-
- \image elidedlabel-example.png Elided Label example on XPressMusic 5800
-
- When text of varying length has to be displayed in a uniformly sized
- area, for instance within a list or grid view where all list items have the
- same size, it can be useful to give the user a visual clue when not all
- text is visible. QLabel can elide text that doesn't fit within it, but only
- in one line. The \c ElidedLabel widget shown in this example word wraps its
- text by its width, and elides the last visible line if some text is left
- out. \c TestWidget gives control to the features of \c ElidedWidget and
- forms the example application.
-
-
- \section1 ElidedLabel Class Definition
-
- Like QLabel, \c ElidedLabel inherits from QFrame. Here's the definition of
- the \c ElidedLabel class:
-
-
- \snippet widgets/elidedlabel/elidedlabel.h 0
-
- The \c isElided property depends the font, text content and geometry of the
- widget. Whenever any of these change, the \c elisionChanged() signal might
- trigger. We cache the current elision value in \c elided, so that it
- doesn't have to be recomputed every time it's asked for.
-
-
- \section1 ElidedLabel Class Implementation
-
- Except for initializing the member variables, the constructor sets the size
- policy to be horizontally expanding, since it's meant to fill the width of
- its container and grow vertically.
-
- \snippet widgets/elidedlabel/elidedlabel.cpp 0
-
- Changing the \c content require a repaint of the widget.
-
- \snippet widgets/elidedlabel/elidedlabel.cpp 1
-
- QTextLayout is used in the \c paintEvent() to divide the \c content into
- lines, that wrap on word boundaries. Each line, except the last visible
- one, is drawn \c lineSpacing pixels below the previous one. The \c draw()
- method of QTextLine will draw the line using the coordinate point as the
- top left corner.
-
- \snippet widgets/elidedlabel/elidedlabel.cpp 2
-
- Unfortunately, QTextLayout does not elide text, so the last visible line
- has to be treated differently. This last line is elided if it is too wide.
- The \c drawText() method of QPainter draws the text starting from the base
- line, which is \c ascecnt() pixels below the last drawn line.
-
- Finally, one more line is created to see if everything fit on this line.
-
- \snippet widgets/elidedlabel/elidedlabel.cpp 3
-
- If the text was elided and wasn't before or vice versa, cache it in
- \c elided and emit the change.
-
- \snippet widgets/elidedlabel/elidedlabel.cpp 4
-
-
- \section1 TestWidget Class Definition
-
- \c TestWidget is a QWidget and is the main window of the example. It
- contains an \c ElidedLabel which can be resized with two QSlider widgets.
-
- \snippet widgets/elidedlabel/testwidget.h 0
-
- \section1 TestWidget Class Implementation
-
- The constructor initializes the whole widget. Strings of different length
- are stored in \c textSamples. The user is able to switch between these.
-
- \snippet widgets/elidedlabel/testwidget.cpp 0
-
- An \c ElidedLabel is created to contain the first of the sample strings.
- The frame is made visible to make it easier to see the actual size of the
- widget.
-
- \snippet widgets/elidedlabel/testwidget.cpp 1
-
- The buttons and the elision label are created. By connecting the
- \c elisionChanged() signal to the \c setVisible() slot of the \c label,
- it will act as an indicator to when the text is elided or not. This signal
- could, for instance, be used to make a "More" button visible, or similar.
-
- \snippet widgets/elidedlabel/testwidget.cpp 2
-
- The \c widthSlider and \c heightSlider specify the size of the
- \c elidedText. Since the y-axis is inverted, the \c heightSlider has to be
- inverted to act appropriately.
-
- \snippet widgets/elidedlabel/testwidget.cpp 3
-
- The components are all stored in a QGridLayout, which is made the layout of
- the \c TestWidget.
-
- \snippet widgets/elidedlabel/testwidget.cpp 4
-
- The \c widthSlider and \c heightSlider have the exact same length as the
- dimensions of the \c elidedText. The maximum value for both of them is
- thus their lengths, and each tick indicates one pixel.
-
- \snippet widgets/elidedlabel/testwidget.cpp 6
-
- The \c switchText() slot simply cycles through all the available sample
- texts.
-
- \snippet widgets/elidedlabel/testwidget.cpp 7
-
- These slots set the width and height of the \c elided text, in response to
- changes in the sliders.
-
- \section1 The \c main() Function
-
- The \c main() function creates an instance of \c TestWidget fullscreen and
- enters the message loop.
-
- \snippet widgets/elidedlabel/main.cpp 0
-*/
-
diff --git a/examples/widgets/doc/src/embeddeddialogs.qdoc b/examples/widgets/doc/src/embeddeddialogs.qdoc
deleted file mode 100644
index 0b31e01e0c..0000000000
--- a/examples/widgets/doc/src/embeddeddialogs.qdoc
+++ /dev/null
@@ -1,39 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 graphicsview/embeddeddialogs
- \title Embedded Dialogs
- \ingroup examples-graphicsview-layout
- \brief Demonstrates how to embed dialogs into a graphics view.
-
- This example shows how to embed standard dialogs into
- Graphics View. It also shows how you can customize the
- proxy class and add window shadows.
-
- \image embeddeddialogs-demo.png
-*/
diff --git a/examples/widgets/doc/src/extension.qdoc b/examples/widgets/doc/src/extension.qdoc
deleted file mode 100644
index c895258acf..0000000000
--- a/examples/widgets/doc/src/extension.qdoc
+++ /dev/null
@@ -1,145 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 dialogs/extension
- \title Extension Example
- \ingroup examples-dialogs
-
- \brief The Extension example shows how to add an extension to a QDialog
- using the QAbstractButton::toggled() signal and the
- QWidget::setVisible() slot.
-
- \image extension-example.png Screenshot of the Extension example
-
- The Extension application lets the user add search parameters in
- a dialog and launch a simple or advanced search.
-
- The simple search has two options: \uicontrol {Match case} and \uicontrol
- {Search from start}. The advanced search offers search for \uicontrol {Whole words},
- \uicontrol {Search backward}, and \uicontrol {Search selection}. The
- application starts with simple search as the default. Click the \uicontrol More button
- to show the advanced search options:
-
- \image extension_more.png Screenshot of the Extension example
-
- \section1 FindDialog Class Definition
-
- The \c FindDialog class inherits QDialog. QDialog is the
- base class for dialog windows. A dialog window is a top-level
- window mostly used for short-term tasks and brief communications
- with the user.
-
- \snippet dialogs/extension/finddialog.h 0
-
- The \c FindDialog widget is the main application widget, and
- displays the application's search options and controlling
- buttons.
-
- In addition to the constructor, there are several child widgets:
-
- \list
- \li A QLineEdit with an associated QLabel to let the
- user type a word to search for.
- \li Several \l {QCheckBox}{QCheckBox}es to facilitate the search options.
- \li Three \l {QPushButton}{QPushButton}s:
- \list
- \li the \uicontrol Find button to start a search
- \li the \uicontrol More button to enable an advanced search
- \li a QWidget representing the application's extension part
- \endlist
- \endlist
-
- \section1 FindDialog Class Implementation
-
- Create the standard child widgets for the simple search in the constructor:
- the QLineEdit with the associated QLabel, two {QCheckBox}es and all the
- \l {QPushButton}{QPushButton}s.
-
- \snippet dialogs/extension/finddialog.cpp 0
-
- This snippet illustrates how you can define a shortcut key
- for a widget. A shortcut should be defined by putting the ampersand
- character (\c &) in front of the letter that should
- become the shortcut.
- For example, for \uicontrol {Find what}, pressing \uicontrol Alt
- and \uicontrol w transfers focus to the QLineEdit widget.
- Shortcuts can also be used for checking on or off a checkmark.
- For example, pressing \uicontrol Alt and \uicontrol c puts the check mark
- on \uicontrol {Match Case} if it was unchecked and vice versa.
- It is the QLabel::setBuddy() method that links a widget to the shortcut
- character if it has been defined.
-
- Set the \uicontrol Find button's default property to true, using the
- QPushButton::setDefault() function. Then the push button will be
- pressed if the user presses the Enter (or Return) key. Note that a
- QDialog can only have one default button.
-
- \snippet dialogs/extension/finddialog.cpp 2
-
- Create the extension widget, and the \l {QCheckBox}{QCheckBox}es associated
- with the advanced search options.
-
- \snippet dialogs/extension/finddialog.cpp 3
-
- Now that the extension widget is created, connect the \uicontrol
- More button's \l{QAbstractButton::toggled()}{toggled()} signal to
- the extension widget's \l{QWidget::setVisible()}{setVisible()} slot.
-
- The QAbstractButton::toggled() signal is emitted whenever a
- checkable button changes its state. The signal's argument is true
- if the button is checked, or false if the button is unchecked. The
- QWidget::setVisible() slot sets the widget's visible status. If
- the status is true the widget is shown, otherwise the widget is
- hidden.
-
- Since the \uicontrol More button is checkable, the connection makes
- sure that the extension widget is shown depending on the state of
- the \uicontrol More button.
-
- Create checkboxes associated with the advanced search options in
- a layout installed on the extension widget.
-
- \snippet dialogs/extension/finddialog.cpp 4
-
- Before creating the main layout, create several child layouts
- for the widgets. First align the QLabel and its buddy, the
- QLineEdit, using a QHBoxLayout. Then align the QLabel and the QLineEdit
- vertically with the checkboxes associated with the simple search,
- using a QVBoxLayout. Create also a QVBoxLayout for the buttons.
- Finally, lay out the two latter layouts and the extension widget
- using a QGridLayout.
-
- \snippet dialogs/extension/finddialog.cpp 5
-
- Hide the extension widget using the QWidget::hide()
- function, making the application only show the simple search
- options when it starts. When the user wants to access the advanced
- search options, the dialog only needs to change the visibility of
- the extension widget. Qt's layout management takes care of the
- dialog's appearance.
-*/
diff --git a/examples/widgets/doc/src/fademessage.qdoc b/examples/widgets/doc/src/fademessage.qdoc
deleted file mode 100644
index 2035922067..0000000000
--- a/examples/widgets/doc/src/fademessage.qdoc
+++ /dev/null
@@ -1,39 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 effects/fademessage
- \title Fade Message Effect Example
- \ingroup examples-graphicsview-graphicseffects
- \brief Demonstrates how to apply effects on items in the view.
-
- \div { style="text-align: left"}
- \inlineimage fademessageeffect-example.png
- \inlineimage fademessageeffect-example-faded.png
- \enddiv
-
-*/
diff --git a/examples/widgets/doc/src/fetchmore.qdoc b/examples/widgets/doc/src/fetchmore.qdoc
index a27efaf071..d8dae18f33 100644
--- a/examples/widgets/doc/src/fetchmore.qdoc
+++ b/examples/widgets/doc/src/fetchmore.qdoc
@@ -1,48 +1,19 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example itemviews/fetchmore
\title Fetch More Example
+ \examplecategory {User Interface Components}
\ingroup examples-itemviews
\brief The Fetch More example shows how to add items to an item view
model on demand.
\image fetchmore-example.png
-
- This example consists of a dialog where you can enter a directory
- name in the \uicontrol Directory edit field. The application loads and
- visualizes all files it finds as you are typing. It is not required
- to press [Enter] to launch the search.
-
When you have large - or perhaps even infinite - data sets, you
will need to add items to the model in batches, and preferably only
- when the items are needed by the view (i.e., when they are visible
+ when the items are needed by the view (i.e., when they become visible
in the view).
In this example, we implement \c FileListModel - an item view
@@ -50,6 +21,15 @@
Window, which sets up the GUI and feeds the model with
directories.
+ The UI consists of a dialog with a list showing the contents
+ of the root directory. Directories can be navigated by double-clicking.
+
+ At the bottom, there is a log window displaying messages when the view
+ asks the model for more data.
+
+ To exercise it, navigate to a large directory (say \c /bin), and scroll
+ to the bottom. Log messages appear showing the data being retrieved.
+
Let's take a tour of \c {FileListModel}'s code.
\section1 FileListModel Class Definition
diff --git a/examples/widgets/doc/src/findfiles.qdoc b/examples/widgets/doc/src/findfiles.qdoc
deleted file mode 100644
index d7428e7d16..0000000000
--- a/examples/widgets/doc/src/findfiles.qdoc
+++ /dev/null
@@ -1,293 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 dialogs/findfiles
- \title Find Files Example
- \ingroup examples-dialogs
-
- \brief A dialog for finding files in a specified folder.
-
- The Find Files application allows the user to search for files in a
- specified directory, matching a given file name or wildcard,
- and containing a specified string (if filled in). The search
- result is displayed in a table containing the names of the files
- and their sizes. The application also shows the number of files found.
-
- The Find Files example illustrates the use of several classes:
-
- \table
- \row
- \li QProgressDialog
- \li Provide feedback on the progress of a search operation
- \row
- \li QFileDialog
- \li Browse through a file list
- \row
- \li QTextStream
- \li Use stream operators to read a file
- \row
- \li QTableWidget
- \li Browse through the search results in a table
- \row
- \li QDesktopServices
- \li Open files in the result list in a suitable application
- \endtable
-
- \image findfiles-example.png Screenshot of the Find Files example
-
-
- \section1 Window Class Definition
-
- The \c Window class inherits QWidget, and is the main application
- widget. It shows the search options and displays the search
- results.
-
- \snippet dialogs/findfiles/window.h 0
-
- The application has two private slots:
- \table
- \row
- \li The \c browse() slot
- \li Called whenever the user wants to browse for a directory to search in
- \row
- \li The \c find() slot
- \li Called whenever the user launches a search with the \uicontrol Find button
- \endtable
-
- In addition we declare several private functions:
-
- \table
- \row
- \li findFiles()
- \li Search for files matching the search parameters
- \row
- \li showFiles()
- \li Display the search result
- \row
- \li ceateButton()
- \li Construct the widget
- \row
- \li createComboBox()
- \li Construct the widget
- \row
- \li createFilesTable()
- \li Construct the widget
- \endtable
-
- \section1 Window Class Implementation
-
- In the constructor we first create the application's widgets.
-
- \snippet dialogs/findfiles/window.cpp 0
-
- We create the widgets to build up the UI, and we add them to a main layout
- using QGridLayout. We have, however, put the \c Find and \c Quit buttons
- and a stretchable space in a separate \l QHBoxLayout first, to make the
- buttons appear in the \c Window widget's bottom right corner.
-
- Alternatively, we could have used Qt Designer to construct a UI file,
- and \l {uic} to generate this code.
-
- \snippet dialogs/findfiles/window.cpp 1
-
- We did not create a \l QMenuBar with a \uicontrol Quit menu item; but we
- would still like to have a keyboard shortcut for quitting. Since we
- construct a \l QShortcut with \l QKeySequence::Quit, and connect it to
- \l QApplication::quit(), on most platforms it will be possible to press
- Control-Q to quit (or whichever standard Quit key is configured on that platform).
- (On \macos, this is redundant, because every application gets a
- \uicontrol Quit menu item automatically; but it helps to make the application portable.)
-
- \snippet dialogs/findfiles/window.cpp 2
-
- The \c browse() slot presents a file dialog to the user, using the
- QFileDialog class. QFileDialog enables a user to traverse the file
- system in order to select one or many files or a directory. The
- easiest way to create a QFileDialog is to use the convenience
- static functions.
-
- Here we use the static QFileDialog::getExistingDirectory()
- function which returns an existing directory selected by the
- user. Then we display the directory in the directory combobox
- using the QComboBox::addItem() function and update the current
- index.
-
- QComboBox::addItem() adds an item to the combobox with the given
- text (if not already present in the list), and containing
- the specified userData. The item is appended to the list of
- existing items.
-
- \snippet dialogs/findfiles/window.cpp 3
-
- The \c find() slot is called whenever the user requests a new
- search by pressing the \uicontrol Find button.
-
- First we eliminate any previous search results by setting the
- table widgets row count to zero. Then we retrieve the
- specified file name, text, and directory path from the respective
- comboboxes.
-
- \snippet dialogs/findfiles/window.cpp 4
-
- We use the directory's path to create a QDir; the QDir class
- provides access to the directory structure and its contents.
-
- We use QDirIterator to iterate over the files that match the
- specified file name and build a QStringList of paths.
-
- Then we search through all the files in the list, using the private
- \c findFiles() function, eliminating the ones that don't contain the
- specified text. We sort them (because QDirIterator did not). And finally,
- we display the results using the private \c showFiles() function.
-
- If the user didn't specify any text, there is no reason to search
- through the files, so we sort and display the results immediately.
-
- \image findfiles_progress_dialog.png Screenshot of the Progress Dialog
-
- \snippet dialogs/findfiles/window.cpp 5
-
- In the private \c findFiles() function we search through a list of
- files, looking for the ones that contain a specified text. This
- can be a very slow operation depending on the number of files as
- well as their sizes. QProgressDialog displays a progress dialog
- if the application has to search through a large number of files,
- or if some of the files have a large size. QProgressDialog can
- also allow the user to abort the operation if it takes too much
- time.
-
- \snippet dialogs/findfiles/window.cpp 6
-
- We run through the files, one at a time, and for each file we
- update the QProgressDialog value. This property holds the current
- amount of progress made. We also update the progress dialog's
- label.
-
- Then we call the QCoreApplication::processEvents() function using
- the QApplication object. In this way we interleave the display of
- the progress made with the process of searching through the files
- so the application doesn't appear to be frozen.
-
- The QApplication class manages the GUI application's control flow
- and main settings. It contains the main event loop, where all
- events from the window system and other sources are processed and
- dispatched. QApplication inherits QCoreApplication. The
- QCoreApplication::processEvents() function processes all pending
- events according to the specified QEventLoop::ProcessEventFlags
- until there are no more events to process. The default flags are
- QEventLoop::AllEvents.
-
- \snippet dialogs/findfiles/window.cpp 7
-
- After updating the QProgressDialog, we open the file in read-only
- mode, and read one line at a time using QTextStream.
-
- The QTextStream class provides a convenient interface for reading
- and writing text. Using QTextStream's streaming operators, you can
- conveniently read and write words, lines and numbers.
-
- For each line we read we check if the QProgressDialog has been
- canceled. If it has, we abort the operation, otherwise we check if
- the line contains the specified text. When we find the text within
- one of the files, we add the file's name to a list of found files
- that contain the specified text, and start searching a new file.
-
- Finally, we return the list of the files found.
-
- \snippet dialogs/findfiles/window.cpp 8
-
- Both the \c findFiles() and \c showFiles() functions are called from
- the \c find() slot. In the \c showFiles() function we run through
- the provided list of file names, adding each relative file name to the
- first column in the table widget and retrieving the file's size using
- QFileInfo for the second column. We use \l QLocale::formattedDataSize()
- to format the file size in a human-readable form. For later use, we set
- the absolute path as a data on the QTableWidget using the
- the role absoluteFileNameRole defined to be Qt::UserRole + 1.
-
- \snippet dialogs/findfiles/window.cpp 17
-
- This allows for retrieving the name of an item using a
- convenience function:
-
- \snippet dialogs/findfiles/window.cpp 18
-
- We also update the total number of files found.
-
- \snippet dialogs/findfiles/window.cpp 10
-
- The private \c createComboBox() function is also called from the
- contructor. We create a QComboBox with the given text, and make it
- editable.
-
- When the user enters a new string in an editable combobox, the
- widget may or may not insert it, and it can insert it in several
- locations, depending on the QComboBox::InsertPolicy. The default
- policy is is QComboBox::InsertAtBottom.
-
- Then we add the provided text to the combobox, and specify the
- widget's size policies, before we return a pointer to the
- combobox.
-
- \snippet dialogs/findfiles/window.cpp 11
-
- The private \c createFilesTable() function is called from the
- constructor. In this function we create the QTableWidget that
- will display the search results. We set its horizontal headers and
- their resize mode.
-
- QTableWidget inherits QTableView which provides a default
- model/view implementation of a table view. The
- QTableView::horizontalHeader() function returns the table view's
- horizontal header as a QHeaderView. The QHeaderView class provides
- a header row or header column for item views, and the
- QHeaderView::setResizeMode() function sets the constraints on how
- the section in the header can be resized.
-
- Finally, we hide the QTableWidget's vertical headers using the
- QWidget::hide() function, and remove the default grid drawn for
- the table using the QTableView::setShowGrid() function.
-
- \snippet dialogs/findfiles/window.cpp 12
-
- \snippet dialogs/findfiles/window.cpp 14
-
- The \c openFileOfItem() slot is invoked when the user double
- clicks on a cell in the table. The QDesktopServices::openUrl()
- knows how to open a file given the file name.
-
- \snippet dialogs/findfiles/window.cpp 15
- \snippet dialogs/findfiles/window.cpp 16
-
- We set the context menu policy to of the table view to Qt::CustomContextMenu
- and connect a slot contextMenu() to its signal
- customContextMenuRequested(). We retrieve the absolute file name
- from the data of the QTableWidgetItem and populate the context menu
- with actions offering to copy the file name and to open the file.
-*/
-
diff --git a/examples/widgets/doc/src/flowlayout.qdoc b/examples/widgets/doc/src/flowlayout.qdoc
index c907cb3af7..03dfc164d7 100644
--- a/examples/widgets/doc/src/flowlayout.qdoc
+++ b/examples/widgets/doc/src/flowlayout.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example layouts/flowlayout
\title Flow Layout Example
+ \examplecategory {User Interface Components}
\ingroup examples-layout
\brief Shows how to arrange widgets for different window sizes.
diff --git a/examples/widgets/doc/src/fontsampler.qdoc b/examples/widgets/doc/src/fontsampler.qdoc
deleted file mode 100644
index 2e206c7769..0000000000
--- a/examples/widgets/doc/src/fontsampler.qdoc
+++ /dev/null
@@ -1,37 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 painting/fontsampler
- \title Font Sampler Example
- \ingroup examples-painting
- \brief The Font Sampler example shows how to preview and print multi-page documents.
-
- The Font Sampler example shows how to preview and print multi-page documents.
-
- \image fontsampler-example.png
-*/
diff --git a/examples/widgets/doc/src/fridgemagnets.qdoc b/examples/widgets/doc/src/fridgemagnets.qdoc
deleted file mode 100644
index 101d0fd390..0000000000
--- a/examples/widgets/doc/src/fridgemagnets.qdoc
+++ /dev/null
@@ -1,362 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 draganddrop/fridgemagnets
- \title Fridge Magnets Example
- \brief The Fridge Magnets example illustrates how to move around several types of
- MIME-encoded data with drag and drop.
-
- The Fridge Magnets example shows how to supply more than one type
- of MIME-encoded data with a drag and drop operation.
-
- \image fridgemagnets-example.png
-
- With this application the user can play around with a collection
- of fridge magnets, using drag and drop to form new sentences from
- the words on the magnets. The example consists of two classes:
-
- \list
- \li \c DragLabel is a custom widget representing one
- single fridge magnet.
- \li \c DragWidget provides the main application window.
- \endlist
-
- We will first take a look at the \c DragLabel class, then we will
- examine the \c DragWidget class.
-
- \section1 DragLabel Class Definition
-
- Each fridge magnet is represented by an instance of the \c
- DragLabel class:
-
- \snippet draganddrop/fridgemagnets/draglabel.h 0
-
- Each instance of this QLabel subclass will be used to display an
- pixmap generated from a text string. Since we cannot store both
- text and a pixmap in a standard label, we declare a private variable
- to hold the original text, and we define an additional member
- function to allow it to be accessed.
-
- \section1 DragLabel Class Implementation
-
- In the \c DragLabel constructor, we first create a QImage object
- on which we will draw the fridge magnet's text and frame:
-
- \snippet draganddrop/fridgemagnets/draglabel.cpp 0
-
- Its size depends on the current font size, and its format is
- QImage::Format_ARGB32_Premultiplied; i.e., the image is stored
- using a premultiplied 32-bit ARGB format (0xAARRGGBB).
-
- We then construct a font object that uses the application's
- default font, and set its style strategy. The style strategy tells
- the font matching algorithm what type of fonts should be used to
- find an appropriate default family. The QFont::ForceOutline forces
- the use of outline fonts.
-
- To draw the text and frame onto the image, we use the QPainter
- class. QPainter provides highly optimized methods to do most of
- the drawing GUI programs require. It can draw everything from
- simple lines to complex shapes like pies and chords. It can also
- draw aligned text and pixmaps.
-
- \snippet draganddrop/fridgemagnets/draglabel.cpp 1
-
- A painter can be activated by passing a paint device to the
- constructor, or by using the \l{QPainter::}{begin()} method as we
- do in this example. The \l{QPainter::}{end()} method deactivates
- it. Note that the latter function is called automatically upon
- destruction when the painter is actived by its constructor. The
- QPainter::Antialiasing render hint ensures that the paint engine
- will antialias the edges of primitives if possible.
-
- When the painting is done, we convert our image to a pixmap using
- QPixmap's \l {QPixmap::}{fromImage()} method. This method also
- takes an optional flags argument, and converts the given image to
- a pixmap using the specified flags to control the conversion (the
- flags argument is a bitwise-OR of the Qt::ImageConversionFlags;
- passing 0 for flags sets all the default options).
-
- \snippet draganddrop/fridgemagnets/draglabel.cpp 2
-
- Finally, we set the label's \l{QLabel::pixmap}{pixmap property}
- and store the label's text for later use.
-
- \e{Note that setting the pixmap clears any previous content, including
- any text previously set using QLabel::setText(), and disables
- the label widget's buddy shortcut, if any.}
-
- \section1 DragWidget Class Definition
-
- The \c DragWidget class inherits QWidget, providing support for
- drag and drop operations:
-
- \snippet draganddrop/fridgemagnets/dragwidget.h 0
-
- To make the widget responsive to drag and drop operations, we simply
- reimplement the \l{QWidget::}{dragEnterEvent()},
- \l{QWidget::}{dragMoveEvent()} and \l{QWidget::}{dropEvent()} event
- handlers inherited from QWidget.
-
- We also reimplement \l{QWidget::}{mousePressEvent()} to make the
- widget responsive to mouse clicks. This is where we will write code
- to start drag and drop operations.
-
- \section1 DragWidget Class Implementation
-
- In the constructor, we first open the file containing the words on
- our fridge magnets:
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 0
-
- QFile is an I/O device for reading and writing text and binary
- files and resources, and may be used by itself or in combination
- with QTextStream or QDataStream. We have chosen to read the
- contents of the file using the QTextStream class that provides a
- convenient interface for reading and writing text.
-
- We then create the fridge magnets. As long as there is data (the
- QTextStream::atEnd() method returns true if there is no more data
- to be read from the stream), we read one line at a time using
- QTextStream's \l {QTextStream::}{readLine()} method.
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 1
-
- For each line, we create a \c DragLabel object using the read line
- as text, we calculate its position and ensure that it is visible by
- calling the QWidget::show() method. We set the Qt::WA_DeleteOnClose
- attribute on each label to ensure that any unused labels will be
- deleted; we will need to create new labels and delete old ones when
- they are dragged around, and this ensures that the example does not
- leak memory.
-
- We also set the \c FridgeMagnets widget's palette, minimum size
- and window title.
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 2
-
- Finally, to enable our user to move the fridge magnets around, we
- must also set the \c FridgeMagnets widget's
- \l{QWidget::acceptDrops}{acceptDrops} property.
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 3
-
- Setting this property to true announces to the system that this
- widget \e may be able to accept drop events (events that are sent
- when drag and drop actions are completed). Later, we will
- implement the functions that ensure that the widget accepts the
- drop events it is interested in.
-
- \section2 Dragging
-
- Let's take a look at the \l{QWidget::}{mousePressEvent()} event
- handler, where drag and drop operations begin:
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 13
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 14
-
- Mouse events occur when a mouse button is pressed or released
- inside a widget, or when the mouse cursor is moved. By
- reimplementing the \l{QWidget::}{mousePressEvent()} method we
- ensure that we will receive mouse press events for the widget
- containing the fridge magnets.
-
- Whenever we receive such an event, we first check to see if the
- position of the click coincides with one of the labels. If not,
- we simply return.
-
- If the user clicked a label, we determine the position of the
- \e{hot spot} (the position of the click relative to the top-left
- corner of the label). We create a byte array to store the label's
- text and the hot spot, and we use a QDataStream object to stream
- the data into the byte array.
-
- With all the information in place, we create a new QMimeData object.
- As mentioned above, QMimeData objects associate the data that they
- hold with the corresponding MIME types to ensure that information
- can be safely transferred between applications. The
- \l{QMimeData::}{setData()} method sets the data associated with a
- given MIME type. In our case, we associate our item data with the
- custom \c application/x-fridgemagnet type.
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 15
-
- Note that we also associate the magnet's text with the
- \c text/plain MIME type using QMimeData's \l{QMimeData::}{setText()}
- method. Below, we will see how our widget detects both these MIME
- types with its event handlers.
-
- Finally, we create a QDrag object. It is the QDrag class that
- handles most of the details of a drag and drop operation,
- providing support for MIME-based drag and drop data transfer. The
- data to be transferred by the drag and drop operation is contained
- in a QMimeData object. When we call QDrag's
- \l{QDrag::}{setMimeData()} method the ownership of our item data is
- transferred to the QDrag object.
-
- We call the \l{QDrag::}{setPixmap()} function to set the pixmap used
- to represent the data during the drag and drop operation.
- Typically, this pixmap shows an icon that represents the MIME type
- of the data being transferred, but any pixmap can be used. In this
- example, we simply use the pixmap used by the label itself to make
- it look like the fridge magnet itself is being moved.
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 16
-
- We also specify the cursor's hot spot, its position relative to the
- top-level corner of the drag pixmap, to be the point we calculated
- above. This makes the process of dragging the label feel more natural
- because the cursor always points to the same place on the label
- during the drag operation.
-
- We start the drag operation using QDrag's \l{QDrag::}{exec()} function,
- requesting that the magnet is copied when the drag is completed.
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 17
-
- The function returns the drop action actually performed by the user
- (this can be either a copy or a move action in this case); if this
- action is equal to Qt::MoveAction we will close the activated
- fridge magnet widget because we will create a new one to replace it
- (see the \l{drop}{dropEvent()} implementation). Otherwise, if
- the drop is outside our main widget, we simply show the widget in
- its original position.
-
- \section2 Dropping
-
- When a a drag and drop action enters our widget, we will receive a
- drag enter \e event. QDragEnterEvent inherits most of its
- functionality from QDragMoveEvent, which in turn inherits most of
- its functionality from QDropEvent. Note that we must accept this
- event in order to receive the drag move events that are sent while
- the drag and drop action is in progress. The drag enter event is
- always immediately followed by a drag move event.
-
- In our \c dragEnterEvent() implementation, we first determine
- whether we support the event's MIME type or not:
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 4
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 5
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 6
-
- If the type is \c application/x-fridgemagnet and the event
- origins from any of this application's fridge magnet widgets, we
- first set the event's drop action using the
- QDropEvent::setDropAction() method. An event's drop action is the
- action to be performed on the data by the target. Qt::MoveAction
- indicates that the data is moved from the source to the target.
-
- Then we call the event's \l {QDragMoveEvent::}{accept()} method to
- indicate that we have handled the event. In general, unaccepted
- events might be propagated to the parent widget. If the event
- origins from any other widget, we simply accept the proposed
- action.
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 7
-
- We also accept the proposed action if the event's MIME type is \c
- text/plain, i.e., if QMimeData::hasText() returns true. If the
- event has any other type, on the other hand, we call the event's
- \l {QDragMoveEvent::}{ignore()} method allowing the event to be
- propagated further.
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 8
-
- Drag move events occur when the cursor enters a widget, when it
- moves within the widget, and when a modifier key is pressed on the
- keyboard while the widget has focus. Our widget will receive drag
- move events repeatedly while a drag is within its boundaries. We
- reimplement the \l {QWidget::}{dragMoveEvent()} method, and
- examine the event in the exact same way as we did with drag enter
- events.
-
- Note that the \l{QWidget::}{dropEvent()} event handler behaves
- slightly differently: We first get hold of the event's MIME
- data.
-
- \target drop
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 9
-
- The QMimeData class provides a container for data that
- records information about its MIME type. QMimeData objects
- associate the data that they hold with the corresponding MIME
- types to ensure that information can be safely transferred between
- applications, and copied around within the same application.
-
- We retrieve the data associated with the \c application/x-fridgemagnet
- MIME type using a data stream in order to create a new \c DragLabel
- object.
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 10
-
- The QDataStream class provides serialization of binary data to a
- QIODevice (a data stream is a binary stream of encoded information
- which is completely independent of the host computer's operating
- system, CPU or byte order).
-
- Finally, we create a label and move it to the event's position:
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 11
-
- If the source of the event is also the widget receiving the
- drop event, we set the event's drop action to Qt::MoveAction and
- call the event's \l{QDragMoveEvent::}{accept()}
- method. Otherwise, we simply accept the proposed action. This
- means that labels are moved rather than copied in the same
- window. However, if we drag a label to a second instance of the
- Fridge Magnets example, the default action is to copy it, leaving
- the original in the first instance.
-
- If the event's MIME type is \c text/plain (i.e., if
- QMimeData::hasText() returns true) we retrieve its text and split
- it into words. For each word we create a new \c DragLabel action,
- and show it at the event's position plus an offset depending on
- the number of words in the text. In the end we accept the proposed
- action. This lets the user drop selected text from a text editor or
- Web browser onto the widget to add more fridge magnets.
-
- \snippet draganddrop/fridgemagnets/dragwidget.cpp 12
-
- If the event has any other type, we call the event's
- \l{QDragMoveEvent::}{ignore()} method allowing the event to be
- propagated further.
-
- \section1 Summary
-
- We set our main widget's \l{QWidget::}{acceptDrops} property
- and reimplemented QWidget's \l{QWidget::}{dragEnterEvent()},
- \l{QWidget::}{dragMoveEvent()} and \l{QWidget::}{dropEvent()} event
- handlers to support content dropped on our widget.
-
- In addition, we reimplemented the \l{QWidget::}{mousePressEvent()}
- function to let the user pick up fridge magnets in the first place.
-
- Because data is communicated using drag and drop operations and
- encoded using MIME types, you can run more than one instance of this
- example, and transfer magnets between them.
-*/
diff --git a/examples/widgets/doc/src/frozencolumn.qdoc b/examples/widgets/doc/src/frozencolumn.qdoc
index 705d190582..c213ba1779 100644
--- a/examples/widgets/doc/src/frozencolumn.qdoc
+++ b/examples/widgets/doc/src/frozencolumn.qdoc
@@ -1,40 +1,17 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example itemviews/frozencolumn
\title Frozen Column Example
+ \examplecategory {User Interface Components}
\ingroup examples-itemviews
\brief This example demonstrates how to freeze a column within a QTableView.
\image frozencolumn-example.png "Screenshot of the example"
We use Qt's model/view framework to implement a table with its first
- column frozen. This technique can be aplied to several columns or rows,
+ column frozen. This technique can be applied to several columns or rows,
as long as they are on the edge of the table.
The model/view framework allows for one model to be displayed in different
diff --git a/examples/widgets/doc/src/gallery.qdoc b/examples/widgets/doc/src/gallery.qdoc
index 3f2cb4bbcc..36b76d8f63 100644
--- a/examples/widgets/doc/src/gallery.qdoc
+++ b/examples/widgets/doc/src/gallery.qdoc
@@ -1,34 +1,11 @@
-/****************************************************************************
-**
-** 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$
-**
-****************************************************************************/
+// Copyright (C) 2020 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example gallery
\meta {tag} {gallery}
\title Widgets Gallery Example
+ \examplecategory {User Interface Components}
\ingroup examples-widgets
\brief The Widgets Gallery example shows widgets relevant for designing UIs.
diff --git a/examples/widgets/doc/src/gradients.qdoc b/examples/widgets/doc/src/gradients.qdoc
index 457e6f837a..e2ad68db1a 100644
--- a/examples/widgets/doc/src/gradients.qdoc
+++ b/examples/widgets/doc/src/gradients.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example painting/gradients
\title Gradients
+ \examplecategory {Graphics}
\ingroup examples-painting
\brief Shows how gradients can be used with QPainter.
diff --git a/examples/widgets/doc/src/graphicsview-anchorlayout.qdoc b/examples/widgets/doc/src/graphicsview-anchorlayout.qdoc
deleted file mode 100644
index 7933e3c956..0000000000
--- a/examples/widgets/doc/src/graphicsview-anchorlayout.qdoc
+++ /dev/null
@@ -1,81 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 graphicsview/anchorlayout
- \title Anchor Layout Example
- \ingroup examples-graphicsview-layout
- \brief Demonstrates anchor layout in a graphics view scene.
-
- The Anchor Layout example demonstrates the use of the QGraphicsAnchorLayout
- class.
-
- \image graphicsanchorlayout-example.png
-
- The basic steps of this example are:
- \list
- \li Create a QGraphicsScene
- \li Create widgets
- \li Create a QGraphicsAnchorLayout
- \li Create a QGraphicsWidget
- \li Add vertical and horizontal anchors between the widgets
- \li View the scene with a QGraphicsView object
- \endlist
-
- \section1 Creating a QGraphicsScene
-
- \quotefromfile graphicsview/anchorlayout/main.cpp
- \skipto QGraphicsScene
- \printuntil setSceneRect
-
- \section1 Creating Widgets
-
- \skipto QGraphicsProxyWidget
- \printuntil *g
-
- \section1 Creating a Layout
-
- \skipto QGraphicsAnchorLayout
- \printuntil l->setSpacing
-
- \section1 Creating a QGraphicsWidget
-
- \skipto QGraphicsWidget
- \printuntil setLayout(l)
-
- \section1 Adding Anchors
-
- \skipto vertical
- \printuntil l->addAnchor(f, Qt::AnchorRight
-
- \section1 Viewing the Scene with QGraphicsView
-
- \skipto scene.addItem
- \printuntil view.show
-
- \sa {Simple Anchor Layout Example}
-*/
diff --git a/examples/widgets/doc/src/graphicsview-flowlayout.qdoc b/examples/widgets/doc/src/graphicsview-flowlayout.qdoc
deleted file mode 100644
index 13819f5499..0000000000
--- a/examples/widgets/doc/src/graphicsview-flowlayout.qdoc
+++ /dev/null
@@ -1,52 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 graphicsview/flowlayout
- \title Graphics View Flow Layout Example
- \ingroup examples-graphicsview-layout
- \brief Demonstrates flow layout on a graphics view scene.
-
- The Graphics View Flow Layout example shows the use of a flow layout
- in a Graphics View widget.
-
- \image graphicsflowlayout-example.png
-
- This example uses a Graphics View to display the widget, which is a more
- customizable approach than displaying the flow layout in the application
- window (See \l {Flow Layout Example}).
-
- Graphics View Flow Layout snippet:
-
- \snippet graphicsview/flowlayout/main.cpp 1
-
- Flow Layout Example snippet:
-
- \snippet layouts/flowlayout/main.cpp 1
-
-
-*/
diff --git a/examples/widgets/doc/src/graphicsview-simpleanchorlayout.qdoc b/examples/widgets/doc/src/graphicsview-simpleanchorlayout.qdoc
index 27b3f86156..ce5fe8934a 100644
--- a/examples/widgets/doc/src/graphicsview-simpleanchorlayout.qdoc
+++ b/examples/widgets/doc/src/graphicsview-simpleanchorlayout.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example graphicsview/simpleanchorlayout
\title Simple Anchor Layout Example
+ \examplecategory {Graphics}
\ingroup examples-graphicsview-layout
\brief Demonstrates anchor layout on a graphics view scene.
@@ -79,6 +56,4 @@
\skipto QGraphicsWidget
\printuntil app.exec()
-
- \sa {Anchor Layout Example}
*/
diff --git a/examples/widgets/doc/src/graphicsview-weatheranchorlayout.qdoc b/examples/widgets/doc/src/graphicsview-weatheranchorlayout.qdoc
deleted file mode 100644
index 71ace60355..0000000000
--- a/examples/widgets/doc/src/graphicsview-weatheranchorlayout.qdoc
+++ /dev/null
@@ -1,38 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 graphicsview/weatheranchorlayout
- \title Weather Anchor Layout Example
- \ingroup examples-graphicsview-layout
- \brief Demonstrates anchor layout on a graphics view scene.
-
- The Weather Anchor Layout example shows more complex use of the
- QGraphicsAnchorLayout class to create a real-world window layout.
-
- \image weatheranchorlayout-example.png
-*/
diff --git a/examples/widgets/doc/src/groupbox.qdoc b/examples/widgets/doc/src/groupbox.qdoc
index b9da2f05f4..aa339098ab 100644
--- a/examples/widgets/doc/src/groupbox.qdoc
+++ b/examples/widgets/doc/src/groupbox.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example widgets/groupbox
\title Group Box Example
+ \examplecategory {User Interface Components}
\ingroup examples-widgets
\brief The Group Box example shows how to use the different kinds of group
boxes in Qt.
diff --git a/examples/widgets/doc/src/i18n.qdoc b/examples/widgets/doc/src/i18n.qdoc
deleted file mode 100644
index e13a315a80..0000000000
--- a/examples/widgets/doc/src/i18n.qdoc
+++ /dev/null
@@ -1,40 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 tools/i18n
- \title I18N Example
- \ingroup examples-widgets-tools
-
- \brief The Internationalization (I18N) example demonstrates Qt's support for translated
- text. Developers can write the initial application text in one language, and
- translations can be provided later without any modifications to the code. It also
- demonstrates how to detect the system language settings and show the UI in the appropriate
- language.
-
- \image i18n-example.png
-*/
diff --git a/examples/widgets/doc/src/icons.qdoc b/examples/widgets/doc/src/icons.qdoc
deleted file mode 100644
index 5dca44a887..0000000000
--- a/examples/widgets/doc/src/icons.qdoc
+++ /dev/null
@@ -1,829 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/icons
- \title Icons Example
- \ingroup examples-widgets
- \brief The Icons example shows how QIcon can generate pixmaps reflecting
- an icon's state, mode and size.
-
- These pixmaps are generated from the set of pixmaps made available to the
- icon, and are used by Qt widgets to show an icon representing a particular
- action.
-
- \image icons-example.png Screenshot of the Icons example
-
- Contents:
-
- \tableofcontents
-
- \section1 QIcon Overview
-
- The QIcon class provides scalable icons in different modes and
- states. An icon's state and mode are depending on the intended use
- of the icon. Qt currently defines four modes:
-
- \table
- \header \li Mode \li Description
- \row
- \li QIcon::Normal
- \li Display the pixmap when the user is not interacting with the
- icon, but the functionality represented by the icon is
- available.
- \row
- \li QIcon::Active
- \li Display the pixmap when the functionality represented by the
- icon is available and the user is interacting with the icon,
- for example, moving the mouse over it or clicking it.
- \row
- \li QIcon::Disabled
- \li Display the pixmap when the functionality represented by
- the icon is not available.
- \row
- \li QIcon::Selected
- \li Display the pixmap when the icon is selected.
- \endtable
-
- QIcon's states are QIcon::On and QIcon::Off, which will display
- the pixmap when the widget is in the respective state. The most
- common usage of QIcon's states are when displaying checkable tool
- buttons or menu entries (see QAbstractButton::setCheckable() and
- QAction::setCheckable()). When a tool button or menu entry is
- checked, the QIcon's state is \l{QIcon::}{On}, otherwise it's
- \l{QIcon::}{Off}. You can, for example, use the QIcon's states to
- display differing pixmaps depending on whether the tool button or
- menu entry is checked or not.
-
- A QIcon can generate smaller, larger, active, disabled, and
- selected pixmaps from the set of pixmaps it is given. Such
- pixmaps are used by Qt widgets to show an icon representing a
- particular action.
-
- \section1 Overview of the Icons Application
-
- With the Icons application you get a preview of an icon's
- generated pixmaps reflecting its different states, modes and size.
-
- When an image is loaded into the application, it is converted into
- a pixmap and becomes a part of the set of pixmaps available to the
- icon. An image can be excluded from this set by checking off the
- related checkbox. The application provides a sub directory
- containing sets of images explicitly designed to illustrate how Qt
- renders an icon in different modes and states.
-
- The application allows you to manipulate the icon size with some
- predefined sizes and a spin box. The predefined sizes are style
- dependent, but most of the styles have the same values. Only the
- \macos style differs by using 32 pixels instead of 16 pixels
- for toolbar buttons. You can navigate between the available styles
- using the \uicontrol View menu.
-
- \image icons-view-menu.png Screenshot of the View menu
-
- The \uicontrol View menu also provide the option to make the application
- guess the icon state and mode from an image's file name. The \uicontrol
- File menu provide the options of adding an image and removing all
- images. These last options are also available through a context
- menu that appears if you press the right mouse button within the
- table of image files. In addition, the \uicontrol File menu provide an
- \uicontrol Exit option, and the \uicontrol Help menu provide information about
- the example and about Qt.
-
- \image icons_find_normal.png Screenshot of the Find Files
-
- The screenshot above shows the application with one image file
- loaded. The \uicontrol {Guess Image Mode/State} is enabled and the
- style is Plastique.
-
- When QIcon is provided with only one available pixmap, that
- pixmap is used for all the states and modes. In this case the
- pixmap's icon mode is set to normal, and the generated pixmaps
- for the normal and active modes will look the same. But in
- disabled and selected mode, Qt will generate a slightly different
- pixmap.
-
- The next screenshot shows the application with an additional file
- loaded, providing QIcon with two available pixmaps. Note that the
- new image file's mode is set to disabled. When rendering the \uicontrol
- Disabled mode pixmaps, Qt will now use the new image. We can see
- the difference: The generated disabled pixmap in the first
- screenshot is slightly darker than the pixmap with the originally
- set disabled mode in the second screenshot.
-
- \image icons_find_normal_disabled.png Screenshot of the Find Files
-
- When Qt renders the icon's pixmaps it searches through the set of
- available pixmaps following a particular algorithm. The algorithm
- is documented in QIcon, but we will describe some particular cases
- below.
-
- \image icons_monkey_active.png Screenshot of the Find Files
-
- In the screenshot above, we have set \c monkey_on_32x32 to be an
- Active/On pixmap and \c monkey_off_64x64 to be Normal/Off. To
- render the other six mode/state combinations, QIcon uses the
- search algorithm described in the table below:
-
- \table 100%
- \header \li{2,1} Requested Pixmap \li {8,1} Preferred Alternatives (mode/state)
- \header \li Mode \li State \li 1 \li 2 \li 3 \li 4 \li 5 \li 6 \li 7 \li 8
- \row \li{1,2} Normal \li Off \li \b N0 \li A0 \li N1 \li A1 \li D0 \li S0 \li D1 \li S1
- \row \li On \li N1 \li \b A1 \li N0 \li A0 \li D1 \li S1 \li D0 \li S0
- \row \li{1,2} Active \li Off \li A0 \li \b N0 \li A1 \li N1 \li D0 \li S0 \li D1 \li S1
- \row \li On \li \b A1 \li N1 \li A0 \li N0 \li D1 \li S1 \li D0 \li S0
- \row \li{1,2} Disabled \li Off \li D0 \li \b {N0'} \li A0' \li D1 \li N1' \li A1' \li S0' \li S1'
- \row \li On \li D1 \li N1' \li \b {A1'} \li D0 \li N0' \li A0' \li S1' \li S0'
- \row \li{1,2} Selected \li Off \li S0 \li \b {N0''} \li A0'' \li S1 \li N1'' \li A1'' \li D0'' \li D1''
- \row \li On \li S1 \li N1'' \li \b {A1''} \li S0 \li N0'' \li A0'' \li D1'' \li D0''
- \endtable
-
- In the table, "0" and "1" stand for "Off" and "On", respectively.
- Single quotes indicates that QIcon generates a disabled ("grayed
- out") version of the pixmap; similarly, double quuote indicate
- that QIcon generates a selected ("blued out") version of the
- pixmap.
-
- The alternatives used in the screenshot above are shown in bold.
- For example, the Disabled/Off pixmap is derived by graying out
- the Normal/Off pixmap (\c monkey_off_64x64).
-
- In the next screenshots, we loaded the whole set of monkey
- images. By checking or unchecking file names from the image list,
- we get different results:
-
- \table
- \row
- \li \inlineimage icons_monkey.png Screenshot of the Monkey Files
- \li \inlineimage icons_monkey_mess.png Screenshot of the Monkey Files
- \endtable
-
- For any given mode/state combination, it is possible to specify
- several images at different resolutions. When rendering an
- icon, QIcon will automatically pick the most suitable image
- and scale it down if necessary. (QIcon never scales up images,
- because this rarely looks good.)
-
- The screenshots below shows what happens when we provide QIcon
- with three images (\c qt_extended_16x16.png, \c qt_extended_32x32.png, \c
- qt_extended_48x48.png) and try to render the QIcon at various
- resolutions:
-
- \table
- \row
- \li
- \li \inlineimage icons_qt_extended_8x8.png Qt Extended icon at 8 x 8
- \li \inlineimage icons_qt_extended_16x16.png Qt Extended icon at 16 x 16
- \li \inlineimage icons_qt_extended_17x17.png Qt Extended icon at 17 x 17
- \row
- \li
- \li 8 x 8
- \li \b {16 x 16}
- \li 17 x 17
- \row
- \li \inlineimage icons_qt_extended_32x32.png Qt Extended icon at 32 x 32
- \li \inlineimage icons_qt_extended_33x33.png Qt Extended icon at 33 x 33
- \li \inlineimage icons_qt_extended_48x48.png Qt Extended icon at 48 x 48
- \li \inlineimage icons_qt_extended_64x64.png Qt Extended icon at 64 x 64
- \row
- \li \b {32 x 32}
- \li 33 x 33
- \li \b {48 x 48}
- \li 64 x 64
- \endtable
-
- For sizes up to 16 x 16, QIcon uses \c qt_extended_16x16.png and
- scales it down if necessary. For sizes between 17 x 17 and 32 x
- 32, it uses \c qt_extended_32x32.png. For sizes above 32 x 32, it uses
- \c qt_extended_48x48.png.
-
- \section1 Line-by-Line Walkthrough
-
- The Icons example consists of four classes:
-
- \list
- \li \c MainWindow inherits QMainWindow and is the main application
- window.
- \li \c IconPreviewArea is a custom widget that displays all
- 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 QStyledItemDelegate that
- provides comboboxes for letting the user set the mode and state
- associated with an image.
- \endlist
-
- We will start by reviewing the \c IconPreviewArea class before we
- take a look at the \c MainWindow class. Finally, we will review the
- \c IconSizeSpinBox and \c ImageDelegate classes.
-
- \section2 IconPreviewArea Class Definition
-
- An \c IconPreviewArea widget consists of a group box containing a grid of
- QLabel widgets displaying headers and pixmaps.
-
- \image icons_preview_area.png Screenshot of IconPreviewArea.
-
- \snippet widgets/icons/iconpreviewarea.h 0
-
- The \c IconPreviewArea class inherits QWidget. It displays the
- generated pixmaps corresponding to an icon's possible states and
- modes at a given size.
-
- \snippet widgets/icons/iconpreviewarea.cpp 42
-
- We would like the table columns to be in the order QIcon::Normal,
- QIcon::Active, QIcon::Disabled, QIcon::Selected and the rows in the order
- QIcon::Off, QIcon::On, which does not match the enumeration. The above code
- provides arrays allowing to map from enumeration value to row/column
- (by using QList::indexOf()) and back by using the array index and lists
- of the matching strings. Qt's containers can be easily populated by
- using C++ 11 initializer lists.
-
- We need two public functions to set the current icon and the
- icon's size. In addition the class has three private functions: We
- use the \c createHeaderLabel() and \c createPixmapLabel()
- functions when constructing the preview area, and we need the \c
- updatePixmapLabels() function to update the preview area when
- the icon or the icon's size has changed.
-
- The \c NumModes and \c NumStates constants reflect \l{QIcon}'s
- number of currently defined modes and states.
-
- \section2 IconPreviewArea Class Implementation
-
- \snippet widgets/icons/iconpreviewarea.cpp 0
-
- In the constructor we create the labels displaying the headers and
- the icon's generated pixmaps, and add them to a grid layout.
-
- When creating the header labels, we make sure the enums \c
- NumModes and \c NumStates defined in the \c .h file, correspond
- with the number of labels that we create. Then if the enums at
- some point are changed, the \c Q_ASSERT() macro will alert that this
- part of the \c .cpp file needs to be updated as well.
-
- If the application is built in debug mode, the \c Q_ASSERT()
- macro will expand to
-
- \code
- if (!condition)
- qFatal("ASSERT: "condition" in file ...");
- \endcode
-
- In release mode, the macro simply disappear. The mode can be set
- in the application's \c .pro file. One way to do so is to add an
- option to \c qmake when building the application:
-
- \code
- qmake "CONFIG += debug" icons.pro
- \endcode
-
- or
-
- \code
- qmake "CONFIG += release" icons.pro
- \endcode
-
- Another approach is to add this line directly to the \c .pro
- file.
-
- \snippet widgets/icons/iconpreviewarea.cpp 1
- \codeline
- \snippet widgets/icons/iconpreviewarea.cpp 2
-
- The public \c setIcon() and \c setSize() functions change the icon
- or the icon size, and make sure that the generated pixmaps are
- updated.
-
- \snippet widgets/icons/iconpreviewarea.cpp 3
- \codeline
- \snippet widgets/icons/iconpreviewarea.cpp 4
-
- We use the \c createHeaderLabel() and \c createPixmapLabel()
- functions to create the preview area's labels displaying the
- headers and the icon's generated pixmaps. Both functions return
- the QLabel that is created.
-
- \snippet widgets/icons/iconpreviewarea.cpp 5
-
- We use the private \c updatePixmapLabel() function to update the
- generated pixmaps displayed in the preview area.
-
- For each mode, and for each state, we retrieve a pixmap using the
- QIcon::pixmap() function, which generates a pixmap corresponding
- to the given state, mode and size. We pass the QWindows instance
- obtained by calling QWidget::windowHandle() on the top level
- widget (QWidget::nativeParentWidget()) in order to retrieve
- the pixmap that matches best.
- We format a tooltip displaying size, actual size and device pixel
- ratio.
-
- \section2 MainWindow Class Definition
-
- The \c MainWindow widget consists of three main elements: an
- images group box, an icon size group box and a preview area.
-
- \image icons-example.png Screenshot of the Icons example
-
- \snippet widgets/icons/mainwindow.h 0
-
- The MainWindow class inherits from QMainWindow. We reimplement the
- constructor, and declare several private slots:
-
- \list
- \li The \c about() slot simply provides information about the example.
- \li The \c changeStyle() slot changes the application's GUI style and
- adjust the style dependent size options.
- \li The \c changeSize() slot changes the size of the preview area's icon.
- \li The \c changeIcon() slot updates the set of pixmaps available to the
- icon displayed in the preview area.
- \li The \c addSampleImages() slot allows the user to load a new image
- from the samples provided into the application.
- \li The \c addOtherImages() slot allows the user to load a new image from
- the directory obtained by calling
- QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).
- \li The \c screenChanged() updates the display in the \uicontrol{High DPI}
- group box to correctly display the parameters of the current screen
- the window is located on.
- \endlist
-
- In addition we declare several private functions to simplify the
- constructor.
-
- \section2 MainWindow Class Implementation
-
- \snippet widgets/icons/mainwindow.cpp 0
-
- In the constructor we first create the main window's central
- widget and its child widgets, and put them in a grid layout. Then
- we create the menus with their associated entries and actions.
-
- We set the window title and determine the current style for the
- application. We also enable the icon size spin box by clicking the
- associated radio button, making the current value of the spin box
- the icon's initial size.
-
- \snippet widgets/icons/mainwindow.cpp 1
-
- The \c about() slot displays a message box using the static
- QMessageBox::about() function. In this example it displays a
- simple box with information about the example.
-
- The \c about() function looks for a suitable icon in four
- locations: It prefers its parent's icon if that exists. If it
- doesn't, the function tries the top-level widget containing
- parent, and if that fails, it tries the active window. As a last
- resort it uses the QMessageBox's Information icon.
-
- \snippet widgets/icons/mainwindow.cpp 2
-
- In the \c changeStyle() slot we first check the slot's
- parameter. If it is false we immediately return, otherwise we find
- out which style to change to, i.e. which action that triggered the
- slot, using the QObject::sender() function.
-
- This function returns the sender as a QObject pointer. Since we
- know that the sender is a QAction object, we can safely cast the
- QObject. We could have used a C-style cast or a C++ \c
- static_cast(), but as a defensive programming technique we use a
- \l qobject_cast(). The advantage is that if the object has the
- wrong type, a null pointer is returned. Crashes due to null
- pointers are much easier to diagnose than crashes due to unsafe
- casts.
-
- \snippet widgets/icons/mainwindow.cpp 3
- \snippet widgets/icons/mainwindow.cpp 4
-
- Once we have the action, we extract the style name using
- QAction::data(). Then we create a QStyle object using the static
- QStyleFactory::create() function.
-
- Although we can assume that the style is supported by the
- QStyleFactory: To be on the safe side, we use the \c Q_ASSERT()
- macro to check if the created style is valid before we use the
- QApplication::setStyle() function to set the application's GUI
- style to the new style. QApplication will automatically delete
- the style object when a new style is set or when the application
- exits.
-
- The predefined icon size options provided in the application are
- style dependent, so we need to update the labels in the icon size
- group box and in the end call the \c changeSize() slot to update
- the icon's size.
-
- \snippet widgets/icons/mainwindow.cpp 5
-
- The \c changeSize() slot sets the size for the preview area's
- icon.
-
- It is invoked by the QButtonGroup whose members are radio buttons for
- controlling the icon size. In \c createIconSizeGroupBox(), each button is
- assigned a QStyle::PixelMetric value as an id, which is passed as a
- parameter to the slot.
-
- The special value \c OtherSize indicates that the spin box is
- enabled. If it is, we extract the extent of the new size from the
- box. If it's not, we query the style for the metric. Then we create
- a QSize object based on the extent, and use that object to set the
- size of the preview area's icon.
-
- \snippet widgets/icons/mainwindow.cpp 12
-
- The function \c addImages() is called by the slot addSampleImages()
- passing the samples directory, or by the slot addOtherImages()
- passing the directory obtained by querying
- QStandardPaths::standardLocations().
-
- The first thing we do is to show a file dialog to the user.
- We initialize it to show the filters returned by
- QImageReader::supportedMimeTypes().
-
- For each of the files the file dialog returns, we add a row to the
- table widget. The table widget is listing the images the user has
- loaded into the application.
-
- \snippet widgets/icons/mainwindow.cpp 13
-
- We retrieve the image name using the QFileInfo::baseName()
- function that returns the base name of the file without the path,
- and create the first table widget item in the row.
- We check if a high resolution version of the image exists (identified by
- the suffix \c @2x on the base name) and display that along with the size
- in the tooltip.
-
- We add the file's complete name to the item's data. Since an item can
- hold several information pieces, we need to assign the file name a role
- that will distinguish it from other data. This role can be Qt::UserRole
- or any value above it.
-
- We also make sure that the item is not editable by removing the
- Qt::ItemIsEditable flag. Table items are editable by default.
-
- \snippet widgets/icons/mainwindow.cpp 15
-
- 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
- {Guess Image Mode/State} option is checked, and the file name
- contains "_act", "_dis", or "_sel", the modes are changed to
- Active, Disabled, or Selected. And if the file name contains
- "_on", the state is changed to On. The sample files in the
- example's \c images subdirectory respect this naming convention.
-
- \snippet widgets/icons/mainwindow.cpp 18
-
- In the end we add the items to the associated row, and use the
- QTableWidget::openPersistentEditor() function to create
- comboboxes for the mode and state columns of the items.
-
- Due to the connection between the table widget's \l
- {QTableWidget::itemChanged()}{itemChanged()} signal and the \c
- changeIcon() slot, the new image is automatically converted into a
- pixmap and made part of the set of pixmaps available to the icon
- in the preview area. So, corresponding to this fact, we need to
- make sure that the new image's check box is enabled.
-
- \snippet widgets/icons/mainwindow.cpp 6
-
- The \c changeIcon() slot is called when the user alters the set
- of images listed in the QTableWidget, to update the QIcon object
- rendered by the \c IconPreviewArea.
-
- We first create a QIcon object, and then we run through the
- QTableWidget, which lists the images the user has loaded into the
- application.
-
- \snippet widgets/icons/mainwindow.cpp 8
-
- We also extract the image file's name using the
- QTableWidgetItem::data() function. This function takes a
- Qt::DataItemRole as an argument to retrieve the right data
- (remember that an item can hold several pieces of information)
- and returns it as a QVariant. Then we use the
- QVariant::toString() function to get the file name as a QString.
-
- To create a pixmap from the file, we need to first create an
- image and then convert this image into a pixmap using
- QPixmap::fromImage(). Once we have the final pixmap, we add it,
- with its associated mode and state, to the QIcon's set of
- available pixmaps.
-
- \snippet widgets/icons/mainwindow.cpp 11
-
- After running through the entire list of images, we change the
- icon of the preview area to the one we just created.
-
- \snippet widgets/icons/mainwindow.cpp 20
-
- In the \c removeAllImages() slot, we simply set the table widget's
- row count to zero, automatically removing all the images the user
- has loaded into the application. Then we update the set of pixmaps
- available to the preview area's icon using the \c changeIcon()
- slot.
-
- \image icons_images_groupbox.png Screenshot of the images group box
-
- The \c createImagesGroupBox() function is implemented to simplify
- the constructor. The main purpose of the function is to create a
- QTableWidget that will keep track of the images the user has
- loaded into the application.
-
- \snippet widgets/icons/mainwindow.cpp 21
-
- First we create a group box that will contain the table widget.
- Then we create a QTableWidget and customize it to suit our
- purposes.
-
- We call QAbstractItemView::setSelectionMode() to prevent the user
- from selecting items.
-
- The QAbstractItemView::setItemDelegate() call sets the item
- delegate for the table widget. We create a \c ImageDelegate that
- we make the item delegate for our 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 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
-
- Then we customize the QTableWidget's horizontal header, and hide
- the vertical header.
-
- \snippet widgets/icons/mainwindow.cpp 24
-
- At the end, we connect the QTableWidget::itemChanged() signal to
- the \c changeIcon() slot to ensure that the preview area is in
- sync with the image table.
-
- \image icons_size_groupbox.png Screenshot of the icon size group box
-
- The \c createIconSizeGroupBox() function is called from the
- constructor. It creates the widgets controlling the size of the
- preview area's icon.
-
- \snippet widgets/icons/mainwindow.cpp 26
-
- First we create a group box that will contain all the widgets;
- then we create the radio buttons and the spin box. We add the
- radio buttons to an instance of QButtonGroup, using the value
- of the QStyle::PixelMetric they represent as an integer id.
-
- \snippet widgets/icons/mainwindow.cpp 40
-
- We introduce an enumeration constant \c OtherSize to represent
- a custom size.
-
- The spin box is not a regular QSpinBox but an \c IconSizeSpinBox.
- The \c IconSizeSpinBox class inherits QSpinBox and reimplements
- two functions: QSpinBox::textFromValue() and
- QSpinBox::valueFromText(). The \c IconSizeSpinBox is designed to
- handle icon sizes, e.g., "32 x 32", instead of plain integer
- values.
-
- \snippet widgets/icons/mainwindow.cpp 27
-
- Then we connect all of the radio buttons
- \l{QRadioButton::toggled()}{toggled()} signals and the spin box's
- \l {QSpinBox::valueChanged()}{valueChanged()} signal to the \c
- changeSize() slot to make sure that the size of the preview
- area's icon is updated whenever the user changes the icon size.
- In the end we put the widgets in a layout that we install on the
- group box.
-
- \snippet widgets/icons/mainwindow.cpp 28
-
- In the \c createActions() function we create and customize all the
- actions needed to implement the functionality associated with the
- menu entries in the application.
-
- In particular we create the \c styleActionGroup based on the
- currently available GUI styles using
- QStyleFactory. QStyleFactory::keys() returns a list of valid keys,
- typically including "windows" and "fusion". Depending on the platform,
- "windowsvista" and "macos" may be available.
-
- We create one action for each key, and adds the action to the
- action group. Also, for each action, we call QAction::setData()
- with the style name. We will retrieve it later using
- QAction::data().
-
- As we go along, we create the \uicontrol File, \uicontrol View and
- \uicontrol Help menus and add the actions to them.
-
- The QMenu class provides a menu widget for use in menu bars,
- context menus, and other popup menus. We put each menu in the
- application's menu bar, which we retrieve using
- QMainWindow::menuBar().
-
- \snippet widgets/icons/mainwindow.cpp 30
-
- QWidgets have a \l{QWidget::contextMenuPolicy}{contextMenuPolicy}
- property that controls how the widget should behave when the user
- requests a context menu (e.g., by right-clicking). We set the
- QTableWidget's context menu policy to Qt::ActionsContextMenu,
- meaning that the \l{QAction}s associated with the widget should
- appear in its context menu.
-
- Then we add the \uicontrol{Add Image} and \uicontrol{Remove All Images}
- actions to the table widget. They will then appear in the table
- widget's context menu.
-
- \snippet widgets/icons/mainwindow.cpp 31
-
- In the \c checkCurrentStyle() function we go through the group of
- style actions, looking for the current GUI style.
-
- For each action, we first extract the style name using
- QAction::data(). Since this is only a QStyleFactory key (e.g.,
- "macos"), we cannot compare it directly to the current
- style's class name. We need to create a QStyle object using the
- static QStyleFactory::create() function and compare the class
- name of the created QStyle object with that of the current style.
- As soon as we are done with a QStyle candidate, we delete it.
-
- For all QObject subclasses that use the \c Q_OBJECT macro, the
- class name of an object is available through its
- \l{QObject::metaObject()}{meta-object}.
-
- We can assume that the style is supported by
- QStyleFactory, but to be on the safe side we use the \c
- Q_ASSERT() macro to make sure that QStyleFactory::create()
- returned a valid pointer.
-
- \snippet widgets/icons/mainwindow.cpp 44
-
- We overload the show() function to set up the updating of the
- current screen in \c screenChanged(). After calling QWidget::show(),
- the QWindow associated with the QWidget is created and we can
- connect to its QWindow::screenChanged() signal.
-
- \section2 IconSizeSpinBox Class Definition
-
- \snippet widgets/icons/iconsizespinbox.h 0
-
- The \c IconSizeSpinBox class is a subclass of QSpinBox. A plain
- QSpinBox can only handle integers. But since we want to display
- the spin box's values in a more sophisticated way, we need to
- subclass QSpinBox and reimplement the QSpinBox::textFromValue()
- and QSpinBox::valueFromText() functions.
-
- \image icons_size_spinbox.png Screenshot of the icon size spinbox
-
- \section2 IconSizeSpinBox Class Implementation
-
- \snippet widgets/icons/iconsizespinbox.cpp 0
-
- The constructor is trivial.
-
- \snippet widgets/icons/iconsizespinbox.cpp 2
-
- QSpinBox::textFromValue() is used by the spin box whenever it
- needs to display a value. The default implementation returns a
- base 10 representation of the \c value parameter.
-
- Our reimplementation returns a QString of the form "32 x 32".
-
- \snippet widgets/icons/iconsizespinbox.cpp 1
-
- The QSpinBox::valueFromText() function is used by the spin box
- whenever it needs to interpret text typed in by the user. Since
- we reimplement the \c textFromValue() function we also need to
- reimplement the \c valueFromText() function to interpret the
- parameter text and return the associated int value.
-
- We parse the text using a regular expression (a QRegularExpression). We
- define an expression that matches one or several digits,
- optionally followed by whitespace, an "x" or the times symbol,
- whitespace and one or several digits again.
-
- The first digits of the regular expression are captured using
- parentheses. This enables us to use the QRegularExpressionMatch::captured()
- or QRegularExpressionMatch::capturedTexts() functions to extract the matched
- characters. If the first and second numbers of the spin box value
- differ (e.g., "16 x 24"), we use the first number.
-
- When the user presses \uicontrol Enter, QSpinBox first calls
- QSpinBox::valueFromText() to interpret the text typed by the
- user, then QSpinBox::textFromValue() to present it in a canonical
- format (e.g., "16 x 16").
-
- \section2 ImageDelegate Class Definition
-
- \snippet widgets/icons/imagedelegate.h 0
-
- 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 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 QStyledItemDelegate creates a QLineEdit.
- Since we want the editor to be a QComboBox, we need to subclass
- QStyledItemDelegate and reimplement the QStyledItemDelegate::createEditor(),
- QStyledItemDelegate::setEditorData() and QStyledItemDelegate::setModelData()
- functions.
-
- \snippet widgets/icons/imagedelegate.h 2
-
- The \c emitCommitData() slot is used to emit the
- QImageDelegate::commitData() signal with the appropriate
- argument.
-
- \section2 ImageDelegate Class Implementation
-
- \snippet widgets/icons/imagedelegate.cpp 0
-
- The constructor is trivial.
-
- \snippet widgets/icons/imagedelegate.cpp 1
-
- 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.
-
- Our reimplementation creates and populates a combobox instead of
- the default line edit. The contents of the combobox depends on
- the column in the table for which the editor is requested. Column
- 1 contains the QIcon modes, whereas column 2 contains the QIcon
- states.
-
- In addition, we connect the combobox's \l
- {QComboBox::activated()}{activated()} signal to the \c
- emitCommitData() slot to emit the
- QAbstractItemDelegate::commitData() signal whenever the user
- chooses an item using the combobox. This ensures that the rest of
- the application notices the change and updates itself.
-
- \snippet widgets/icons/imagedelegate.cpp 2
-
- 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.
-
- Delegates work in terms of models, not items. This makes it
- possible to use them with any item view class (e.g., QListView,
- QListWidget, QTreeView, etc.). The transition between model and
- items is done implicitly by QTableWidget; we don't need to worry
- about it.
-
- \snippet widgets/icons/imagedelegate.cpp 3
-
- 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
-
- The \c emitCommitData() slot simply emit the
- QAbstractItemDelegate::commitData() signal for the editor that
- triggered the slot. This signal must be emitted when the editor
- widget has completed editing the data, and wants to write it back
- into the model.
-
- \section2 The Implementation of the Function main()
-
- \snippet widgets/icons/main.cpp 45
-
- We use QCommandLineParser to handle any command line options or parameters
- passed to the application. Then, we resize the main window according
- to the available screen geometry and show it.
-*/
diff --git a/examples/widgets/doc/src/imagecomposition.qdoc b/examples/widgets/doc/src/imagecomposition.qdoc
index 97f3a78264..9eec57ca88 100644
--- a/examples/widgets/doc/src/imagecomposition.qdoc
+++ b/examples/widgets/doc/src/imagecomposition.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example painting/imagecomposition
\title Image Composition Example
+ \examplecategory {Graphics}
\ingroup examples-painting
\ingroup examples-layout
\brief Shows how composition modes work in QPainter.
diff --git a/examples/widgets/doc/src/imageviewer.qdoc b/examples/widgets/doc/src/imageviewer.qdoc
deleted file mode 100644
index 8cf8c2489e..0000000000
--- a/examples/widgets/doc/src/imageviewer.qdoc
+++ /dev/null
@@ -1,344 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/imageviewer
- \title Image Viewer Example
- \ingroup examples-widgets
- \brief The example shows how to combine QLabel and QScrollArea to
- display an image.
-
- QLabel is typically used for displaying text,
- but it can also display an image. QScrollArea provides a
- scrolling view around another widget. If the child widget exceeds
- the size of the frame, QScrollArea automatically provides scroll
- bars.
-
- The example demonstrates how QLabel's ability to scale its
- contents (QLabel::scaledContents), and QScrollArea's ability to
- automatically resize its contents (QScrollArea::widgetResizable),
- can be used to implement zooming and scaling features. In
- addition the example shows how to use QPainter to print an image.
-
- \borderedimage imageviewer-example.png
- \caption Screenshot of the Image Viewer example
-
- With the Image Viewer application, the users can view an image of
- their choice. The \uicontrol File menu gives the user the possibility
- to:
-
- \list
- \li \uicontrol{Open...} - Open an image file
- \li \uicontrol{Print...} - Print an image
- \li \uicontrol{Exit} - Exit the application
- \endlist
-
- Once an image is loaded, the \uicontrol View menu allows the users to:
-
- \list
- \li \uicontrol{Zoom In} - Scale the image up by 25%
- \li \uicontrol{Zoom Out} - Scale the image down by 25%
- \li \uicontrol{Normal Size} - Show the image at its original size
- \li \uicontrol{Fit to Window} - Stretch the image to occupy the entire window
- \endlist
-
- In addition the \uicontrol Help menu provides the users with information
- about the Image Viewer example in particular, and about Qt in
- general.
-
- \section1 ImageViewer Class Definition
-
- \snippet widgets/imageviewer/imageviewer.h 0
-
- The \c ImageViewer class inherits from QMainWindow. We reimplement
- the constructor, and create several private slots to facilitate
- the menu entries. In addition we create four private functions.
-
- We use \c createActions() and \c createMenus() when constructing
- the \c ImageViewer widget. We use the \c updateActions() function
- to update the menu entries when a new image is loaded, or when
- the \uicontrol {Fit to Window} option is toggled. The zoom slots use \c
- scaleImage() to perform the zooming. In turn, \c
- scaleImage() uses \c adjustScrollBar() to preserve the focal point after
- scaling an image.
-
- \section1 ImageViewer Class Implementation
-
- \snippet widgets/imageviewer/imageviewer.cpp 0
-
- In the constructor we first create the label and the scroll area.
-
- We set \c {imageLabel}'s size policy to \l
- {QSizePolicy::Ignored}{ignored}, making the users able to scale
- the image to whatever size they want when the \uicontrol {Fit to Window}
- option is turned on. Otherwise, the default size polizy (\l
- {QSizePolicy::Preferred}{preferred}) will make scroll bars appear
- when the scroll area becomes smaller than the label's minimum size
- hint.
-
- We ensure that the label will scale its contents to fill all
- available space, to enable the image to scale properly when
- zooming. If we omitted to set the \c {imageLabel}'s \l
- {QLabel::scaledContents}{scaledContents} property, zooming in
- would enlarge the QLabel, but leave the pixmap at
- its original size, exposing the QLabel's background.
-
- We make \c imageLabel the scroll area's child widget, and we make
- \c scrollArea the central widget of the QMainWindow. At the end
- we create the associated actions and menus, and customize the \c
- {ImageViewer}'s appearance.
-
- \snippet widgets/imageviewer/imageviewer.cpp 1
-
- In the \c open() slot, we show a file dialog to the user. We compile
- a list of mime types for use as a filter by querying QImageReader
- for the available mime type names.
-
- We show the file dialog until a valid file name is entered or
- the user cancels.
-
- The function \c loadFile() is used to load the image.
-
- \snippet widgets/imageviewer/imageviewer.cpp 2
-
- In the \c loadFile() function, we instantiate a QImageReader
- and enable automatic transformations by calling
- QImageReader::setAutoTransform(). For files in JPEG format,
- this ensures that portrait mode images of digital cameras are shown
- correctly by applying the appropriate orientation read from the
- EXIF meta data stored in the image file.
-
- We then load the image using QImageReader::read(). If this returns
- a null image, indicating that the file is not an image file,
- we use a QMessageBox to alert the user.
-
- The QMessageBox class provides a modal dialog with a short
- message, an icon, and some buttons. As with QFileDialog the
- easiest way to create a QMessageBox is to use its static
- convenience functions. QMessageBox provides a range of different
- messages arranged along two axes: severity (question,
- information, warning and critical) and complexity (the number of
- necessary response buttons). In this particular example an
- information message with an \uicontrol OK button (the default) is
- sufficient, since the message is part of a normal operation.
-
- \snippet widgets/imageviewer/imageviewer.cpp 4
-
- If the format is supported, we display the image in \c imageLabel
- by setting the label's \l {QLabel::pixmap}{pixmap}. Then we enable
- the \uicontrol Print and \uicontrol {Fit to Window} menu entries and update
- the rest of the view menu entries. The \uicontrol Open and \uicontrol Exit
- entries are enabled by default.
-
- If the \uicontrol {Fit to Window} option is turned off, the
- QScrollArea::widgetResizable property is \c false and it is
- our responsibility (not QScrollArea's) to give the QLabel a
- reasonable size based on its contents. We call
- \{QWidget::adjustSize()}{adjustSize()} to achieve this, which is
- essentially the same as
-
- \code
- imageLabel->resize(imageLabel->pixmap()->size());
- \endcode
-
- In the \c print() slot, we first make sure that an image has been
- loaded into the application:
-
- \snippet widgets/imageviewer/imageviewer.cpp 5
- \snippet widgets/imageviewer/imageviewer.cpp 6
-
- If the application is built in debug mode, the \c Q_ASSERT() macro
- will expand to
-
- \code
- if (imageLabel->pixmap(Qt::ReturnByValue).isNull())
- qFatal("ASSERT: "imageLabel->pixmap(Qt::ReturnByValue).isNull()" in file ...");
- \endcode
-
- In release mode, the macro simply disappear. The mode can be set
- in the application's \c .pro file. One way to do so is to add an
- option to \uicontrol qmake when building the application:
-
- \code
- qmake "CONFIG += debug" foo.pro
- \endcode
-
- or
-
- \code
- qmake "CONFIG += release" foo.pro
- \endcode
-
- Another approach is to add this line directly to the \c .pro
- file.
-
- \snippet widgets/imageviewer/imageviewer.cpp 7
- \snippet widgets/imageviewer/imageviewer.cpp 8
-
- Then we present a print dialog allowing the user to choose a
- printer and to set a few options. We construct a painter with a
- QPrinter as the paint device. We set the painter's window
- and viewport in such a way that the image is as large as possible
- on the paper, but without altering its
- \l{Qt::KeepAspectRatio}{aspect ratio}.
-
- In the end we draw the pixmap at position (0, 0).
-
- \snippet widgets/imageviewer/imageviewer.cpp 9
- \snippet widgets/imageviewer/imageviewer.cpp 10
-
- We implement the zooming slots using the private \c scaleImage()
- function. We set the scaling factors to 1.25 and 0.8,
- respectively. These factor values ensure that a \uicontrol {Zoom In}
- action and a \uicontrol {Zoom Out} action will cancel each other (since
- 1.25 * 0.8 == 1), and in that way the normal image size can be
- restored using the zooming features.
-
- The screenshots below show an image in its normal size, and the
- same image after zooming in:
-
- \table
- \row
- \li \inlineimage imageviewer-original_size.png
- \li \inlineimage imageviewer-zoom_in_1.png
- \li \inlineimage imageviewer-zoom_in_2.png
- \endtable
-
- \snippet widgets/imageviewer/imageviewer.cpp 11
- \snippet widgets/imageviewer/imageviewer.cpp 12
-
- When zooming, we use the QLabel's ability to scale its contents.
- Such scaling doesn't change the actual size hint of the contents.
- And since the \l {QLabel::adjustSize()}{adjustSize()} function
- use those size hint, the only thing we need to do to restore the
- normal size of the currently displayed image is to call \c
- adjustSize() and reset the scale factor to 1.0.
-
- \snippet widgets/imageviewer/imageviewer.cpp 13
- \snippet widgets/imageviewer/imageviewer.cpp 14
-
- The \c fitToWindow() slot is called each time the user toggled
- the \uicontrol {Fit to Window} option. If the slot is called to turn on
- the option, we tell the scroll area to resize its child widget
- with the QScrollArea::setWidgetResizable() function. Then we
- disable the \uicontrol {Zoom In}, \uicontrol {Zoom Out} and \uicontrol {Normal
- Size} menu entries using the private \c updateActions() function.
-
- If the \l {QScrollArea::widgetResizable} property is set to \c
- false (the default), the scroll area honors the size of its child
- widget. If this property is set to \c true, the scroll area will
- automatically resize the widget in order to avoid scroll bars
- where they can be avoided, or to take advantage of extra space.
- But the scroll area will honor the minimum size hint of its child
- widget independent of the widget resizable property. So in this
- example we set \c {imageLabel}'s size policy to \l
- {QSizePolicy::Ignored}{ignored} in the constructor, to avoid that
- scroll bars appear when the scroll area becomes smaller than the
- label's minimum size hint.
-
- The screenshots below shows an image in its normal size, and the
- same image with the \uicontrol {Fit to window} option turned on.
- Enlarging the window will stretch the image further, as shown in
- the third screenshot.
-
- \table
- \row
- \li \inlineimage imageviewer-original_size.png
- \li \inlineimage imageviewer-fit_to_window_1.png
- \li \inlineimage imageviewer-fit_to_window_2.png
- \endtable
-
- If the slot is called to turn off the option, the
- {QScrollArea::setWidgetResizable} property is set to \c false. We
- also restore the image pixmap to its normal size by adjusting the
- label's size to its content. And in the end we update the view
- menu entries.
-
- \snippet widgets/imageviewer/imageviewer.cpp 15
- \snippet widgets/imageviewer/imageviewer.cpp 16
-
- We implement the \c about() slot to create a message box
- describing what the example is designed to show.
-
- \snippet widgets/imageviewer/imageviewer.cpp 17
- \snippet widgets/imageviewer/imageviewer.cpp 18
-
- In the private \c createAction() function, we create the
- actions providing the application features and populate
- a menu with them.
-
- We assign a short-cut key to each action and connect them to the
- appropriate slots. We only enable the \c openAct and \c exitAct at
- the time of creation, the others are updated once an image has
- been loaded into the application. In addition we make the \c
- fitToWindowAct \l {QAction::checkable}{checkable}.
-
- The QMenu class provides a menu widget for use in menu bars,
- context menus, and other popup menus. The QMenuBar class provides
- a horizontal menu bar that consists of a list of pull-down menu
- items. So we put the menus in the \c {ImageViewer}'s
- menu bar which we retrieve with the QMainWindow::menuBar()
- function.
-
- \snippet widgets/imageviewer/imageviewer.cpp 21
- \snippet widgets/imageviewer/imageviewer.cpp 22
-
- The private \c updateActions() function enables or disables the
- \uicontrol {Zoom In}, \uicontrol {Zoom Out} and \uicontrol {Normal Size} menu
- entries depending on whether the \uicontrol {Fit to Window} option is
- turned on or off.
-
- \snippet widgets/imageviewer/imageviewer.cpp 23
- \snippet widgets/imageviewer/imageviewer.cpp 24
-
- In \c scaleImage(), we use the \c factor parameter to calculate
- the new scaling factor for the displayed image, and resize \c
- imageLabel. Since we set the
- \l{QLabel::scaledContents}{scaledContents} property to \c true in
- the constructor, the call to QWidget::resize() will scale the
- image displayed in the label. We also adjust the scroll bars to
- preserve the focal point of the image.
-
- At the end, if the scale factor is less than 33.3% or greater
- than 300%, we disable the respective menu entry to prevent the
- image pixmap from becoming too large, consuming too much
- resources in the window system.
-
- \snippet widgets/imageviewer/imageviewer.cpp 25
- \snippet widgets/imageviewer/imageviewer.cpp 26
-
- Whenever we zoom in or out, we need to adjust the scroll bars in
- consequence. It would have been tempting to simply call
-
- \code
- scrollBar->setValue(int(factor * scrollBar->value()));
- \endcode
-
- but this would make the top-left corner the focal point, not the
- center. Therefore we need to take into account the scroll bar
- handle's size (the \l{QScrollBar::pageStep}{page step}).
-*/
diff --git a/examples/widgets/doc/src/interview.qdoc b/examples/widgets/doc/src/interview.qdoc
deleted file mode 100644
index 072d755e37..0000000000
--- a/examples/widgets/doc/src/interview.qdoc
+++ /dev/null
@@ -1,39 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 itemviews/interview
- \title Interview
- \ingroup examples-itemviews
- \brief This example demonstrates the usage of the model/view framework.
-
- \brief The Interview example explores the flexibility and scalability of the
- model/view framework by presenting an infinitely deep data structure using a model
- and three different types of view.
-
- \image interview-demo.png
-*/
diff --git a/examples/widgets/doc/src/itemviewspuzzle.qdoc b/examples/widgets/doc/src/itemviewspuzzle.qdoc
deleted file mode 100644
index 4789ce717c..0000000000
--- a/examples/widgets/doc/src/itemviewspuzzle.qdoc
+++ /dev/null
@@ -1,43 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 itemviews/puzzle
- \title Item Views Puzzle Example
- \ingroup examples-itemviews
- \brief The Puzzle example shows how to enable drag and drop with a custom model
- to allow items to be transferred between a view and another widget.
-
- \image itemviewspuzzle-example.png
-
- This example is an implementation of a simple jigsaw puzzle game using the
- built-in support for drag and drop provided by Qt's model/view framework.
- The \l{Drag and Drop Puzzle Example}{Drag and Drop Puzzle} example shows
- many of the same features, but takes an alternative approach that uses Qt's
- drag and drop API at the application level to handle drag and drop
- operations.
-*/
diff --git a/examples/widgets/doc/src/licensewizard.qdoc b/examples/widgets/doc/src/licensewizard.qdoc
index 30f1a876d2..66c822e421 100644
--- a/examples/widgets/doc/src/licensewizard.qdoc
+++ b/examples/widgets/doc/src/licensewizard.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example dialogs/licensewizard
\title License Wizard Example
+ \examplecategory {User Interface Components}
\ingroup examples-dialogs
\brief The License Wizard example shows how to implement complex wizards in
@@ -37,7 +14,7 @@
Most wizards have a linear structure, with page 1 followed by
page 2 and so on until the last page. The
- \l{dialogs/classwizard}{Class Wizard} example shows how to create
+ \l{dialogs/trivialwizard}{Trivial Wizard} example shows how to create
such wizards.
Some wizards are more complex in that they allow different
@@ -215,5 +192,5 @@
option and disconnect the \c printButtonClicked() slot.
\endlist
- \sa QWizard, {Class Wizard Example}, {Trivial Wizard Example}
+ \sa QWizard, {Trivial Wizard Example}
*/
diff --git a/examples/widgets/doc/src/lineedits.qdoc b/examples/widgets/doc/src/lineedits.qdoc
index 08de3c08dd..7065a5f425 100644
--- a/examples/widgets/doc/src/lineedits.qdoc
+++ b/examples/widgets/doc/src/lineedits.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example widgets/lineedits
\title Line Edits Example
+ \examplecategory {User Interface Components}
\ingroup examples-widgets
\brief The Line Edits example demonstrates the many ways that QLineEdit
can be used, and shows the effects of various properties and validators
diff --git a/examples/widgets/doc/src/mainwindow.qdoc b/examples/widgets/doc/src/mainwindow.qdoc
deleted file mode 100644
index b2f397dfc7..0000000000
--- a/examples/widgets/doc/src/mainwindow.qdoc
+++ /dev/null
@@ -1,37 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 mainwindows/mainwindow
- \title Main Window
- \ingroup examples-mainwindow
-
- \brief The Main Window example shows Qt's extensive support for tool bars,
- dock windows, menus, and other standard application features.
-
- \image mainwindow-demo.png
-*/
diff --git a/examples/widgets/doc/src/mdi.qdoc b/examples/widgets/doc/src/mdi.qdoc
deleted file mode 100644
index f54d8f8f4a..0000000000
--- a/examples/widgets/doc/src/mdi.qdoc
+++ /dev/null
@@ -1,38 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 mainwindows/mdi
- \title MDI Example
- \ingroup examples-mainwindow
-
- \brief The MDI example shows how to implement a Multiple Document Interface using Qt's
- QMdiArea class.
-
- \image mdi-example.png
-
-*/
diff --git a/examples/widgets/doc/src/menus.qdoc b/examples/widgets/doc/src/menus.qdoc
index 0cf74a7dac..b78d394691 100644
--- a/examples/widgets/doc/src/menus.qdoc
+++ b/examples/widgets/doc/src/menus.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example mainwindows/menus
\title Menus Example
+ \examplecategory {User Interface Components}
\ingroup examples-mainwindow
\ingroup examples-layout
@@ -143,7 +120,8 @@
using the provided convenience functions.
In the \c createActions() function, we first create a \c newAct
- action. We make \uicontrol Ctrl+N its shortcut using the
+ action, passing the text and and an icon using one of the theme
+ icon constants. We make \uicontrol Ctrl+N its shortcut using the
QAction::setShortcut() function, and we set its status tip using the
QAction::setStatusTip() function (the status tip is displayed on all
status bars provided by the action's top-level parent widget). We
diff --git a/examples/widgets/doc/src/movie.qdoc b/examples/widgets/doc/src/movie.qdoc
deleted file mode 100644
index 2363383ffe..0000000000
--- a/examples/widgets/doc/src/movie.qdoc
+++ /dev/null
@@ -1,40 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/movie
- \title Movie Example
- \ingroup examples-widgets
- \brief The Movie example demonstrates how to use QMovie and QLabel to
- display animations.
-
- QMovie is mostly useful if one wants to play
- a simple animation without the added complexity of a multimedia
- framework to install and deploy.
-
- \borderedimage movie-example.png
-*/
diff --git a/examples/widgets/doc/src/orderform.qdoc b/examples/widgets/doc/src/orderform.qdoc
index 5c63081a77..7ae89dfda8 100644
--- a/examples/widgets/doc/src/orderform.qdoc
+++ b/examples/widgets/doc/src/orderform.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example richtext/orderform
\title Order Form Example
+ \examplecategory {User Interface Components}
\ingroup examples-richtext
\brief The Order Form example shows how to generate rich text
documents by combining a simple template with data input by the
diff --git a/examples/widgets/doc/src/painterpaths.qdoc b/examples/widgets/doc/src/painterpaths.qdoc
index bd821ac1bf..305a7608e5 100644
--- a/examples/widgets/doc/src/painterpaths.qdoc
+++ b/examples/widgets/doc/src/painterpaths.qdoc
@@ -1,39 +1,13 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example painting/painterpaths
\title Painter Paths Example
+ \examplecategory {Graphics}
\ingroup examples-painting
- \brief The Painter Paths example shows how painter paths can be
- used to beuild complex shapes for rendering.
-
- \brief The Painter Paths example shows how painter paths can be used to
- build complex shapes for rendering.
+ \brief The Painter Paths example shows how to use painter paths
+ to build complex shapes for rendering.
\image painterpaths-example.png
@@ -127,7 +101,7 @@
explicitly start a new subpath using the QPainterPath::moveTo()
function.
- QPainterPath also provide the QPainterPath::addRect() convenience
+ QPainterPath also provides the QPainterPath::addRect() convenience
function, which adds a given rectangle to the path as a closed
subpath. The rectangle is added as a clockwise set of lines. The
painter path's current position after the rect has been added is
@@ -175,7 +149,7 @@
Constructing a polygon is equivalent to constructing a rectangle.
- QPainterPath also provide the QPainterPath::addPolygon()
+ QPainterPath also provides the QPainterPath::addPolygon()
convenience function which adds the given polygon to the path as a
new subpath. Current position after the polygon has been added is
the last point in polygon.
diff --git a/examples/widgets/doc/src/pathstroke.qdoc b/examples/widgets/doc/src/pathstroke.qdoc
index 83f25113dd..bc4001ebb5 100644
--- a/examples/widgets/doc/src/pathstroke.qdoc
+++ b/examples/widgets/doc/src/pathstroke.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example painting/pathstroke
\title Path Stroking
+ \examplecategory {Graphics}
\ingroup examples-painting
\brief The Path Stroking example shows various types of pens that
can be used with QPainter.
diff --git a/examples/widgets/doc/src/pixelator.qdoc b/examples/widgets/doc/src/pixelator.qdoc
deleted file mode 100644
index 5ad2158e7e..0000000000
--- a/examples/widgets/doc/src/pixelator.qdoc
+++ /dev/null
@@ -1,255 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 itemviews/pixelator
- \title Pixelator Example
- \ingroup examples-itemviews
- \brief The Pixelator example shows how delegates can be used to customize the way that
- items are rendered in standard item views.
-
- \image pixelator-example.png
-
- By default, QTreeView, QTableView, and QListView use a standard item delegate
- to display and edit a set of common data types that are sufficient for many
- applications. However, an application may need to represent items of data in a
- particular way, or provide support for rendering more specialized data types,
- and this often requires the use of a custom delegate.
-
- In this example, we show how to use custom delegates to modify the appearance
- of standard views. To do this, we implement the following components:
-
- \list
- \li A model which represents each pixel in an image as an item of data, where each
- item contains a value for the brightness of the corresponding pixel.
- \li A custom delegate that uses the information supplied by the model to represent
- each pixel as a black circle on a white background, where the radius of the
- circle corresponds to the darkness of the pixel.
- \endlist
-
- This example may be useful for developers who want to implement their own table
- models or custom delegates. The process of creating custom delegates for editing
- item data is covered in the \l{Spin Box Delegate Example}{Spin Box Delegate}
- example.
-
- \section1 ImageModel Class Definition
-
- The \c ImageModel class is defined as follows:
-
- \snippet itemviews/pixelator/imagemodel.h 0
-
- Since we only require a simple, read-only table model, we only need to implement
- functions to indicate the dimensions of the image and supply data to other
- components.
-
- \section1 ImageModel Class Implementation
-
- The constructor is trivial:
-
- \snippet itemviews/pixelator/imagemodel.cpp 0
-
- The \c setImage() function sets the image that will be used by the model:
-
- \snippet itemviews/pixelator/imagemodel.cpp 1
-
- The QAbstractItemModel::reset() call tells the view(s) that the model
- has changed.
-
- The \c rowCount() and \c columnCount() functions return the height and width of
- the image respectively:
-
- \snippet itemviews/pixelator/imagemodel.cpp 2
- \snippet itemviews/pixelator/imagemodel.cpp 3
-
- Since the image is a simple two-dimensional structure, the \c parent arguments
- to these functions are unused. They both simply return the relevant size from
- the underlying image object.
-
- The \c data() function returns data for the item that corresponds to a given
- model index in a format that is suitable for a particular role:
-
- \snippet itemviews/pixelator/imagemodel.cpp 4
-
- In this implementation, we only check that the model index is valid, and that
- the role requested is the \l{Qt::ItemDataRole}{DisplayRole}. If so, the function
- returns the grayscale value of the relevant pixel in the image; otherwise, a null
- model index is returned.
-
- This model can be used with QTableView to display the integer brightness values
- for the pixels in the image. However, we will implement a custom delegate to
- display this information in a more artistic way.
-
- The \c headerData() function is also reimplemented:
-
- \snippet itemviews/pixelator/imagemodel.cpp 5
-
- We return (1, 1) as the size hint for a header item. If we
- didn't, the headers would default to a larger size, preventing
- us from displaying really small items (which can be specified
- using the \uicontrol{Pixel size} combobox).
-
- \section1 PixelDelegate Class Definition
-
- The \c PixelDelegate class is defined as follows:
-
- \snippet itemviews/pixelator/pixeldelegate.h 0
-
- This class provides only basic features for a delegate so, unlike the
- \l{Spin Box Delegate Example}{Spin Box Delegate} example, we subclass
- QAbstractItemDelegate instead of QItemDelegate.
-
- We only need to reimplement \l{QAbstractItemDelegate::paint()}{paint()} and
- \l{QAbstractItemDelegate::sizeHint()}{sizeHint()} in this class.
- However, we also provide a delegate-specific \c setPixelSize() function so
- that we can change the delegate's behavior via the signals and slots mechanism.
-
- \section1 PixelDelegate Class Implementation
-
- The \c PixelDelegate constructor is used to set up a default value for
- the size of each "pixel" that it renders. The base class constructor is
- also called to ensure that the delegate is set up with a parent object,
- if one is supplied:
-
- \snippet itemviews/pixelator/pixeldelegate.cpp 0
-
- Each item is rendered by the delegate's
- \l{QAbstractItemDelegate::paint()}{paint()} function. The view calls this
- function with a ready-to-use QPainter object, style information that the
- delegate should use to correctly draw the item, and an index to the item in
- the model:
-
- \snippet itemviews/pixelator/pixeldelegate.cpp 1
-
- The first task the delegate has to perform is to draw the item's background
- correctly. Usually, selected items appear differently to non-selected items,
- so we begin by testing the state passed in the style option and filling the
- background if necessary.
-
- The radius of each circle is calculated in the following lines of code:
-
- \snippet itemviews/pixelator/pixeldelegate.cpp 3
- \snippet itemviews/pixelator/pixeldelegate.cpp 4
-
- First, the largest possible radius of the circle is determined by taking the
- smallest dimension of the style option's \c rect attribute.
- Using the model index supplied, we obtain a value for the brightness of the
- relevant pixel in the image. The radius of the circle is calculated by
- scaling the brightness to fit within the item and subtracting it from the
- largest possible radius.
-
- \snippet itemviews/pixelator/pixeldelegate.cpp 5
- \snippet itemviews/pixelator/pixeldelegate.cpp 6
- \snippet itemviews/pixelator/pixeldelegate.cpp 7
-
- We save the painter's state, turn on antialiasing (to obtain smoother
- curves), and turn off the pen.
-
- \snippet itemviews/pixelator/pixeldelegate.cpp 8
- \snippet itemviews/pixelator/pixeldelegate.cpp 9
-
- The foreground of the item (the circle representing a pixel) must be
- rendered using an appropriate brush. For unselected items, we will use a
- solid black brush; selected items are drawn using a predefined brush from
- the style option's palette.
-
- \snippet itemviews/pixelator/pixeldelegate.cpp 10
-
- Finally, we paint the circle within the rectangle specified by the style
- option and we call \l{QPainter::}{restore()} on the painter.
-
- The \c paint() function does not have to be particularly complicated; it is
- only necessary to ensure that the state of the painter when the function
- returns is the same as it was when it was called. This usually
- means that any transformations applied to the painter must be preceded by
- a call to QPainter::save() and followed by a call to QPainter::restore().
-
- The delegate's \l{QAbstractItemDelegate::}{sizeHint()} function
- returns a size for the item based on the predefined pixel size, initially set
- up in the constructor:
-
- \snippet itemviews/pixelator/pixeldelegate.cpp 11
-
- The delegate's size is updated whenever the pixel size is changed.
- We provide a custom slot to do this:
-
- \snippet itemviews/pixelator/pixeldelegate.cpp 12
-
- \section1 Using The Custom Delegate
-
- In this example, we use a main window to display a table of data, using the
- custom delegate to render each cell in a particular way. Much of the
- \c MainWindow class performs tasks that are not related to item views. Here,
- we only quote the parts that are relevant. You can look at the rest of the
- implementation by following the links to the code at the top of this
- document.
-
- In the constructor, we set up a table view, turn off its grid, and hide its
- headers:
-
- \snippet itemviews/pixelator/mainwindow.cpp 0
- \dots
- \snippet itemviews/pixelator/mainwindow.cpp 1
-
- This enables the items to be drawn without any gaps between them. Removing
- the headers also prevents the user from adjusting the sizes of individual
- rows and columns.
-
- We also set the minimum section size to 1 on the headers. If we
- didn't, the headers would default to a larger size, preventing
- us from displaying really small items (which can be specified
- using the \uicontrol{Pixel size} combobox).
-
- The custom delegate is constructed with the main window as its parent, so
- that it will be deleted correctly later, and we set it on the table view.
-
- \snippet itemviews/pixelator/mainwindow.cpp 2
-
- Each item in the table view will be rendered by the \c PixelDelegate
- instance.
-
- We construct a spin box to allow the user to change the size of each "pixel"
- drawn by the delegate:
-
- \snippet itemviews/pixelator/mainwindow.cpp 3
-
- This spin box is connected to the custom slot we implemented in the
- \c PixelDelegate class. This ensures that the delegate always draws each
- pixel at the currently specified size:
-
- \snippet itemviews/pixelator/mainwindow.cpp 4
- \dots
- \snippet itemviews/pixelator/mainwindow.cpp 5
-
- We also connect the spin box to a slot in the \c MainWindow class. This
- forces the view to take into account the new size hints for each item;
- these are provided by the delegate in its \c sizeHint() function.
-
- \snippet itemviews/pixelator/mainwindow.cpp 6
-
- We explicitly resize the columns and rows to match the
- \uicontrol{Pixel size} combobox.
-*/
diff --git a/examples/widgets/doc/src/plugandpaint.qdoc b/examples/widgets/doc/src/plugandpaint.qdoc
deleted file mode 100644
index b37176da0e..0000000000
--- a/examples/widgets/doc/src/plugandpaint.qdoc
+++ /dev/null
@@ -1,551 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 tools/plugandpaint/app
- \title Plug & Paint Example
- \ingroup examples-widgets-tools
-
- \brief Demonstrates how to extend Qt applications using plugins.
-
- \image plugandpaint.png Screenshot of the Plug & Paint example
-
- A plugin is a dynamic library that can be loaded at run-time to
- extend an application. Qt makes it possible to create custom
- plugins and to load them using QPluginLoader. To ensure that
- plugins don't get lost, it is also possible to link them
- statically to the executable. The Plug & Paint example uses
- plugins to support custom brushes, shapes, and image filters. A
- single plugin can provide multiple brushes, shapes, and/or
- filters.
-
- If you want to learn how to make your own application extensible
- through plugins, we recommend that you start by reading this
- overview, which explains how to make an application use plugins.
- Afterwards, you can read the
- \l{tools/plugandpaint/plugins/basictools}{Basic Tools} and
- \l{tools/plugandpaint/plugins/extrafilters}{Extra Filters}
- overviews, which show how to implement static and dynamic
- plugins, respectively.
-
- Plug & Paint consists of the following classes:
-
- \list
- \li \c MainWindow is a QMainWindow subclass that provides the menu
- system and that contains a \c PaintArea as the central widget.
- \li \c PaintArea is a QWidget that allows the user to draw using a
- brush and to insert shapes.
- \li \c PluginDialog is a dialog that shows information about the
- plugins detected by the application.
- \li \c BrushInterface, \c ShapeInterface, and \c FilterInterface are
- abstract base classes that can be implemented by plugins to
- provide custom brushes, shapes, and image filters.
- \endlist
-
- \section1 The Plugin Interfaces
-
- We will start by reviewing the interfaces defined in \c
- interfaces.h. These interfaces are used by the Plug & Paint
- application to access extra functionality. They are implemented
- in the plugins.
-
-
- \snippet tools/plugandpaint/app/interfaces.h 0
-
- The \c BrushInterface class declares four pure virtual functions.
- The first pure virtual function, \c brushes(), returns a list of
- strings that identify the brushes provided by the plugin. By
- returning a QStringList instead of a QString, we make it possible
- for a single plugin to provide multiple brushes. The other
- functions have a \c brush parameter to identify which brush
- (among those returned by \c brushes()) is used.
-
- \c mousePress(), \c mouseMove(), and \c mouseRelease() take a
- QPainter and one or two \l{QPoint}s, and return a QRect
- identifying which portion of the image was altered by the brush.
-
- The class also has a virtual destructor. Interface classes
- usually don't need such a destructor (because it would make
- little sense to \c delete the object that implements the
- interface through a pointer to the interface), but some compilers
- emit a warning for classes that declare virtual functions but no
- virtual destructor. We provide the destructor to keep these
- compilers happy.
-
- \snippet tools/plugandpaint/app/interfaces.h 1
-
- The \c ShapeInterface class declares a \c shapes() function that
- works the same as \c{BrushInterface}'s \c brushes() function, and
- a \c generateShape() function that has a \c shape parameter.
- Shapes are represented by a QPainterPath, a data type that can
- represent arbitrary 2D shapes or combinations of shapes. The \c
- parent parameter can be used by the plugin to pop up a dialog
- asking the user to specify more information.
-
- \snippet tools/plugandpaint/app/interfaces.h 2
-
- The \c FilterInterface class declares a \c filters() function
- that returns a list of filter names, and a \c filterImage()
- function that applies a filter to an image.
-
- \snippet tools/plugandpaint/app/interfaces.h 4
-
- To make it possible to query at run-time whether a plugin
- implements a given interface, we must use the \c
- Q_DECLARE_INTERFACE() macro. The first argument is the name of
- the interface. The second argument is a string identifying the
- interface in a unique way. By convention, we use a "Java package
- name" syntax to identify interfaces. If we later change the
- interfaces, we must use a different string to identify the new
- interface; otherwise, the application might crash. It is therefore
- a good idea to include a version number in the string, as we did
- above.
-
- The \l{tools/plugandpaint/plugins/basictools}{Basic Tools} plugin
- and the \l{tools/plugandpaint/plugins/extrafilters}{Extra Filters}
- plugin shows how to derive from \c BrushInterface, \c
- ShapeInterface, and \c FilterInterface.
-
- A note on naming: It might have been tempting to give the \c
- brushes(), \c shapes(), and \c filters() functions a more generic
- name, such as \c keys() or \c features(). However, that would
- have made multiple inheritance impractical. When creating
- interfaces, we should always try to give unique names to the pure
- virtual functions.
-
- \section1 The MainWindow Class
-
- The \c MainWindow class is a standard QMainWindow subclass, as
- found in many of the other examples (e.g.,
- \l{mainwindows/application}{Application}). Here, we'll
- concentrate on the parts of the code that are related to plugins.
-
- \snippet tools/plugandpaint/app/mainwindow.cpp 4
-
- The \c loadPlugins() function is called from the \c MainWindow
- constructor to detect plugins and update the \uicontrol{Brush},
- \uicontrol{Shapes}, and \uicontrol{Filters} menus. We start by handling static
- plugins (available through QPluginLoader::staticInstances())
-
- To the application that uses the plugin, a Qt plugin is simply a
- QObject. That QObject implements plugin interfaces using multiple
- inheritance.
-
- \snippet tools/plugandpaint/app/mainwindow.cpp 5
-
- The next step is to load dynamic plugins. We initialize the \c
- pluginsDir member variable to refer to the \c plugins
- subdirectory of the Plug & Paint example. On Unix, this is just a
- matter of initializing the QDir variable with
- QApplication::applicationDirPath(), the path of the executable
- file, and to do a \l{QDir::cd()}{cd()}. On Windows and \macos,
- this file is usually located in a subdirectory, so we need to
- take this into account.
-
- \snippet tools/plugandpaint/app/mainwindow.cpp 6
- \snippet tools/plugandpaint/app/mainwindow.cpp 7
- \snippet tools/plugandpaint/app/mainwindow.cpp 8
-
- We use QDir::entryList() to get a list of all files in that
- directory. Then we iterate over the result using a range-based for loop
- and try to load the plugin using QPluginLoader.
-
- The QObject provided by the plugin is accessible through
- QPluginLoader::instance(). If the dynamic library isn't a Qt
- plugin, or if it was compiled against an incompatible version of
- the Qt library, QPluginLoader::instance() returns a null pointer.
-
- If QPluginLoader::instance() is non-null, we add it to the menus.
-
- \snippet tools/plugandpaint/app/mainwindow.cpp 9
-
- At the end, we enable or disable the \uicontrol{Brush}, \uicontrol{Shapes},
- and \uicontrol{Filters} menus based on whether they contain any items.
-
- \snippet tools/plugandpaint/app/mainwindow.cpp 10
-
- For each plugin (static or dynamic), we check which interfaces it
- implements using \l qobject_cast(). First, we try to cast the
- plugin instance to a \c BrushInterface; if it works, we call the
- private function \c addToMenu() with the list of brushes returned
- by \c brushes(). Then we do the same with the \c ShapeInterface
- and the \c FilterInterface.
-
- \snippet tools/plugandpaint/app/mainwindow.cpp 3
-
- The \c aboutPlugins() slot is called on startup and can be
- invoked at any time through the \uicontrol{About Plugins} action. It
- pops up a \c PluginDialog, providing information about the loaded
- plugins.
-
- \image plugandpaint-plugindialog.png Screenshot of the Plugin dialog
-
-
- The \c addToMenu() function is called from \c loadPlugin() to
- create \l{QAction}s for custom brushes, shapes, or filters and
- add them to the relevant menu. The QAction is created with the
- plugin from which it comes from as the parent; this makes it
- convenient to get access to the plugin later.
-
- \snippet tools/plugandpaint/app/mainwindow.cpp 0
-
- The \c changeBrush() slot is invoked when the user chooses one of
- the brushes from the \uicontrol{Brush} menu. We start by finding out
- which action invoked the slot using QObject::sender(). Then we
- get the \c BrushInterface out of the plugin (which we
- conveniently passed as the QAction's parent) and we call \c
- PaintArea::setBrush() with the \c BrushInterface and the string
- identifying the brush. Next time the user draws on the paint
- area, \c PaintArea will use this brush.
-
- \snippet tools/plugandpaint/app/mainwindow.cpp 1
-
- The \c insertShape() is invoked when the use chooses one of the
- shapes from the \uicontrol{Shapes} menu. We retrieve the QAction that
- invoked the slot, then the \c ShapeInterface associated with that
- QAction, and finally we call \c ShapeInterface::generateShape()
- to obtain a QPainterPath.
-
- \snippet tools/plugandpaint/app/mainwindow.cpp 2
-
- The \c applyFilter() slot is similar: We retrieve the QAction
- that invoked the slot, then the \c FilterInterface associated to
- that QAction, and finally we call \c
- FilterInterface::filterImage() to apply the filter onto the
- current image.
-
- \section1 The PaintArea Class
-
- The \c PaintArea class contains some code that deals with \c
- BrushInterface, so we'll review it briefly.
-
- \snippet tools/plugandpaint/app/paintarea.cpp 0
-
- In \c setBrush(), we simply store the \c BrushInterface and the
- brush that are given to us by \c MainWindow.
-
- \snippet tools/plugandpaint/app/paintarea.cpp 1
-
- In the \l{QWidget::mouseMoveEvent()}{mouse move event handler},
- we call the \c BrushInterface::mouseMove() function on the
- current \c BrushInterface, with the current brush. The mouse
- press and mouse release handlers are very similar.
-
- \section1 The PluginDialog Class
-
- The \c PluginDialog class provides information about the loaded
- plugins to the user. Its constructor takes a path to the plugins
- and a list of plugin file names. It calls \c findPlugins()
- to fill the QTreeWdiget with information about the plugins:
-
- \snippet tools/plugandpaint/app/plugindialog.cpp 0
-
- The \c findPlugins() is very similar to \c
- MainWindow::loadPlugins(). It uses QPluginLoader to access the
- static and dynamic plugins. Its helper function \c
- populateTreeWidget() uses \l qobject_cast() to find out which
- interfaces are implemented by the plugins:
-
- \snippet tools/plugandpaint/app/plugindialog.cpp 1
-
- \section1 Importing Static Plugins
-
- The \l{tools/plugandpaint/plugins/basictools}{Basic Tools} plugin
- is built as a static plugin, to ensure that it is always
- available to the application. This requires using the
- Q_IMPORT_PLUGIN() macro somewhere in the application (in a \c
- .cpp file) and specifying the plugin in the \c .pro file.
-
- For Plug & Paint, we have chosen to put Q_IMPORT_PLUGIN() in \c
- main.cpp:
-
- \snippet tools/plugandpaint/app/main.cpp 0
-
- The argument to Q_IMPORT_PLUGIN() is the plugin name, which corresponds
- with the name of the class that declares metadata for the plugin with
- Q_PLUGIN_METADATA().
-
- In the \c .pro file, we need to specify the static library.
- Here's the project file for building Plug & Paint:
-
- \snippet tools/plugandpaint/app/app.pro 0
-
- The \c LIBS line variable specifies the library \c pnp_basictools
- located in the \c ../plugandpaint/plugins/basictools directory.
- (Although the \c LIBS syntax has a distinct Unix flavor, \c qmake
- supports it on all platforms.)
-
- The \c CONFIG() code at the end is necessary for this example
- because the example is part of the Qt distribution and Qt can be
- configured to be built simultaneously in debug and in release
- modes. You don't need to for your own plugin applications.
-
- This completes our review of the Plug & Paint application. At
- this point, you might want to take a look at the
- \l{tools/plugandpaint/plugins/basictools}{Basic Tools} example
- plugin.
-*/
-
-/*!
- \example tools/plugandpaint/plugins/basictools
- \title Plug & Paint Basic Tools Example
- \brief A plugin providing the basic tools for painting functionality.
-
- \image plugandpaint.png Screenshot of the Plug & Paint example
-
- The Basic Tools example is a static plugin for the
- \l{tools/plugandpaint/app}{Plug & Paint} example. It provides a set
- of basic brushes, shapes, and filters. Through the Basic Tools
- example, we will review the four steps involved in writing a Qt
- plugin:
-
- \list 1
- \li Declare a plugin class.
- \li Implement the interfaces provided by the plugin.
- \li Export the plugin using the Q_PLUGIN_METADATA() macro.
- \li Build the plugin using an adequate \c .pro file.
- \endlist
-
- \section1 Declaration of the Plugin Class
-
- \snippet tools/plugandpaint/plugins/basictools/basictoolsplugin.h 0
-
- We start by including \c interfaces.h, which defines the plugin
- interfaces for the \l{tools/plugandpaint/app}{Plug & Paint}
- application. For the \c #include to work, we need to add an \c
- INCLUDEPATH entry to the \c .pro file with the path to the
- header file.
-
- The \c BasicToolsPlugin class is a QObject subclass that
- implements the \c BrushInterface, the \c ShapeInterface, and the
- \c FilterInterface. This is done through multiple inheritance.
- The \c Q_INTERFACES() macro is necessary to tell \l{moc}, Qt's
- meta-object compiler, that the base classes are plugin
- interfaces. Without the \c Q_INTERFACES() macro, we couldn't use
- \l qobject_cast() in the \l{tools/plugandpaint/app}{Plug & Paint}
- application to detect interfaces.
- For an explanation for the \c Q_PLUGIN_METADATA() macro see
- \l {Exporting the Plugin}.
-
- \snippet tools/plugandpaint/plugins/basictools/basictoolsplugin.h 2
-
- In the \c public section of the class, we declare all the
- functions from the three interfaces.
-
- \section1 Implementation of the Brush Interface
-
- Let's now review the implementation of the \c BasicToolsPlugin
- member functions inherited from \c BrushInterface.
-
- \snippet tools/plugandpaint/plugins/basictools/basictoolsplugin.cpp 0
-
- The \c brushes() function returns a list of brushes provided by
- this plugin. We provide three brushes: \uicontrol{Pencil}, \uicontrol{Air
- Brush}, and \uicontrol{Random Letters}.
-
- \snippet tools/plugandpaint/plugins/basictools/basictoolsplugin.cpp 1
-
- On a mouse press event, we just call \c mouseMove() to draw the
- spot where the event occurred.
-
- \snippet tools/plugandpaint/plugins/basictools/basictoolsplugin.cpp 2
-
- In \c mouseMove(), we start by saving the state of the QPainter
- and we compute a few variables that we'll need later.
-
- \snippet tools/plugandpaint/plugins/basictools/basictoolsplugin.cpp 3
-
- Then comes the brush-dependent part of the code:
-
- \list
- \li If the brush is \uicontrol{Pencil}, we just call
- QPainter::drawLine() with the current QPen.
-
- \li If the brush is \uicontrol{Air Brush}, we start by setting the
- painter's QBrush to Qt::Dense6Pattern to obtain a dotted
- pattern. Then we draw a circle filled with that QBrush several
- times, resulting in a thick line.
-
- \li If the brush is \uicontrol{Random Letters}, we draw a random letter
- at the new cursor position. Most of the code is for setting
- the font to be bold and larger than the default font and for
- computing an appropriate bounding rect.
- \endlist
-
- At the end, we restore the painter state to what it was upon
- entering the function and we return the bounding rectangle.
-
- \snippet tools/plugandpaint/plugins/basictools/basictoolsplugin.cpp 4
-
- When the user releases the mouse, we do nothing and return an
- empty QRect.
-
- \section1 Implementation of the Shape Interface
-
- \snippet tools/plugandpaint/plugins/basictools/basictoolsplugin.cpp 5
-
- The plugin provides three shapes: \uicontrol{Circle}, \uicontrol{Star}, and
- \uicontrol{Text...}. The three dots after \uicontrol{Text} are there because
- the shape pops up a dialog asking for more information. We know
- that the shape names will end up in a menu, so we include the
- three dots in the shape name.
-
- A cleaner but more complicated design would have been to
- distinguish between the internal shape name and the name used in
- the user interface.
-
- \snippet tools/plugandpaint/plugins/basictools/basictoolsplugin.cpp 6
-
- The \c generateShape() creates a QPainterPath for the specified
- shape. If the shape is \uicontrol{Text}, we pop up a QInputDialog to
- let the user enter some text.
-
- \section1 Implementation of the Filter Interface
-
- \snippet tools/plugandpaint/plugins/basictools/basictoolsplugin.cpp 7
-
- The plugin provides three filters: \uicontrol{Invert Pixels}, \uicontrol{Swap
- RGB}, and \uicontrol{Grayscale}.
-
- \snippet tools/plugandpaint/plugins/basictools/basictoolsplugin.cpp 8
-
- The \c filterImage() function takes a filter name and a QImage as
- parameters and returns an altered QImage. The first thing we do
- is to convert the image to a 32-bit RGB format, to ensure that
- the algorithms will work as expected. For example,
- QImage::invertPixels(), which is used to implement the
- \uicontrol{Invert Pixels} filter, gives counterintuitive results for
- 8-bit images, because they invert the indices into the color
- table instead of inverting the color table's entries.
-
- \section1 Exporting the Plugin
-
- To finally export your plugin you just have to add the
- \c Q_PLUGIN_METADATA() macro right next to the \c Q_OBJECT() macro
- into the header file of the plugin.
- It must contain the plugins IID and optionally a filename pointing
- to a json file containing the metadata for the plugin.
-
- \snippet tools/plugandpaint/plugins/basictools/basictoolsplugin.h 4
-
- Within this example the json file does not need to export any metadata,
- so it just contains an empty json object.
-
- \code
- {}
- \endcode
-
- \section1 The .pro File
-
- Here's the project file for building the Basic Tools plugin:
-
- \snippet tools/plugandpaint/plugins/basictools/basictools.pro 0
-
- The \c .pro file differs from typical \c .pro files in many
- respects. First, it starts with a \c TEMPLATE entry specifying \c
- lib. (The default template is \c app.) It also adds \c plugin to
- the \c CONFIG variable. This is necessary on some platforms to
- avoid generating symbolic links with version numbers in the file
- name, which is appropriate for most dynamic libraries but not for
- plugins.
-
- To make the plugin a static plugin, all that is required is to
- specify \c static in addition to \c plugin. The
- \l{tools/plugandpaint/plugins/extrafilters}{Extra Filters} plugin,
- which is compiled as a dynamic plugin, doesn't specify \c static
- in its \c .pro file.
-
- The \c INCLUDEPATH variable sets the search paths for global
- headers (i.e., header files included using \c{#include <...>}).
- We add \c ../../app to the list, so that we can include
- \c <interfaces.h>.
-
- The \c TARGET variable specifies which name we want to give the
- target library. We use \c pnp_ as the prefix to show that the
- plugin is designed to work with Plug & Paint. On Unix, \c lib is
- also prepended to that name. On all platforms, a
- platform-specific suffix is appended (e.g., \c .dll on Windows,
- \c .a on Linux).
-
- The \c CONFIG() code at the end is necessary for this example
- because the example is part of the Qt distribution and Qt can be
- configured to be built simultaneously in debug and in release
- modes. You don't need to for your own plugins.
-*/
-
-/*!
- \example tools/plugandpaint/plugins/extrafilters
- \title Plug & Paint Extra Filters Example
- \brief A plugin providing the extra filters.
-
- \image plugandpaint.png Screenshot of the Plug & Paint example
-
- The Extra Filters example is a plugin for the
- \l{tools/plugandpaint/app}{Plug & Paint} example. It provides a set
- of filters in addition to those provided by the
- \l{tools/plugandpaint/plugins/basictools}{Basic Tools} plugin.
-
- Since the approach is identical to
- \l{tools/plugandpaint/plugins/basictools}{Basic Tools}, we won't
- review the code here. The only part of interest is the
- \c .pro file, since Extra Filters is a dynamic plugin
- (\l{tools/plugandpaint/plugins/basictools}{Basic Tools} is
- linked statically into the Plug & Paint executable).
-
- Here's the project file for building the Extra Filters plugin:
-
- \snippet tools/plugandpaint/plugins/extrafilters/extrafilters.pro 0
-
- The \c .pro file differs from typical \c .pro files in many
- respects. First, it starts with a \c TEMPLATE entry specifying \c
- lib. (The default template is \c app.) It also adds \c plugin to
- the \c CONFIG variable. This is necessary on some platforms to
- avoid generating symbolic links with version numbers in the file
- name, which is appropriate for most dynamic libraries but not for
- plugins.
-
- The \c INCLUDEPATH variable sets the search paths for global
- headers (i.e., header files included using \c{#include <...>}).
- We add \c ../../app to the list, so that we can include
- \c <interfaces.h>.
-
- The \c TARGET variable specifies which name we want to give the
- target library. We use \c pnp_ as the prefix to show that the
- plugin is designed to work with Plug & Paint. On Unix, \c lib is
- also prepended to that name. On all platforms, a
- platform-specific suffix is appended (e.g., \c .dll on Windows,
- \c .so on Linux).
-
- The \c DESTDIR variable specifies where we want to install the
- plugin. We put it in Plug & Paint's \c plugins subdirectory,
- since that's where the application looks for dynamic plugins.
-
- The \c CONFIG() code at the end is necessary for this example
- because the example is part of the Qt distribution and Qt can be
- configured to be built simultaneously in debug and in release
- modes. You don't need to for your own plugins.
-*/
diff --git a/examples/widgets/doc/src/regularexpression.qdoc b/examples/widgets/doc/src/regularexpression.qdoc
index f11679cf6c..f6f1e87689 100644
--- a/examples/widgets/doc/src/regularexpression.qdoc
+++ b/examples/widgets/doc/src/regularexpression.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example tools/regularexpression
\title QRegularExpression Example
+ \examplecategory {User Interface Components}
\ingroup examples-widgets-tools
\brief The QRegularExpression example shows how regular expressions in Qt are
diff --git a/examples/widgets/doc/src/screenshot.qdoc b/examples/widgets/doc/src/screenshot.qdoc
index 7274a8f37c..2e2b3123ef 100644
--- a/examples/widgets/doc/src/screenshot.qdoc
+++ b/examples/widgets/doc/src/screenshot.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example desktop/screenshot
- \title Screenshot Example
+ \title Taking a Screenshot
+ \examplecategory {Desktop}
\ingroup examples-desktop
\brief The Screenshot example shows how to take a screenshot of the
desktop.
diff --git a/examples/widgets/doc/src/scribble.qdoc b/examples/widgets/doc/src/scribble.qdoc
index ca79431334..3cd7205397 100644
--- a/examples/widgets/doc/src/scribble.qdoc
+++ b/examples/widgets/doc/src/scribble.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example widgets/scribble
\title Scribble Example
+ \examplecategory {User Interface Components}
\ingroup examples-widgets
\brief The Scribble example shows how to reimplement some of QWidget's
event handlers to receive the events generated for the
diff --git a/examples/widgets/doc/src/sdi.qdoc b/examples/widgets/doc/src/sdi.qdoc
deleted file mode 100644
index 3aa96ff598..0000000000
--- a/examples/widgets/doc/src/sdi.qdoc
+++ /dev/null
@@ -1,37 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 mainwindows/sdi
- \title SDI Example
- \ingroup examples-mainwindow
-
- \brief The SDI example shows how to create a Single Document Interface. It uses a number of
- top-level windows to display the contents of different text files.
-
- \image sdi-example.png
-*/
diff --git a/examples/widgets/doc/src/settingseditor.qdoc b/examples/widgets/doc/src/settingseditor.qdoc
deleted file mode 100644
index 4abf23cf14..0000000000
--- a/examples/widgets/doc/src/settingseditor.qdoc
+++ /dev/null
@@ -1,38 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 tools/settingseditor
- \title Settings Editor Example
- \ingroup examples-widgets-tools
-
- \brief The Settings Editor example shows how Qt's standard settings support is used in an
- application by providing an editor that enables the user to view the settings for
- installed applications, and modify those that can be edited.
-
- \image settingseditor-example.png
-*/
diff --git a/examples/widgets/doc/src/shapedclock.qdoc b/examples/widgets/doc/src/shapedclock.qdoc
index 732820cdc8..4bcd04683c 100644
--- a/examples/widgets/doc/src/shapedclock.qdoc
+++ b/examples/widgets/doc/src/shapedclock.qdoc
@@ -1,43 +1,21 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example widgets/shapedclock
- \title Shaped Clock Example
+ \title Translucent Background
+ \examplecategory {User Interface Components}
\ingroup examples-widgets
- \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.
+ \brief The example shows how to make a round window with a translucent
+ background.
\borderedimage shapedclock-example.png
- 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
+ Widgets that set their background to be translucent will be transparent for all
+ unpainted pixels, and the background will shine through pixels painted with an
+ opacity of less than 100%. Pixels that are not painted at all will also not
+ receive any mouse input. This can be used to customize the shapes of top-level
+ widgets. 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.
@@ -49,17 +27,15 @@
\section1 ShapedClock Class Definition
The \c ShapedClock class is based on the \c AnalogClock class defined in the
- \l{Analog Clock Example}{Analog Clock} example. The whole class definition is
+ \l{Analog Clock} example. The whole class definition is
presented below:
\snippet widgets/shapedclock/shapedclock.h 0
- 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.
+ The \l{QWidget::paintEvent()}{paintEvent()} implementation draws an analog clock
+ on a semi-transparent background (the clock face). In addition, we implement
+ \l{QWidget::sizeHint()}{sizeHint()} so that we don't have to resize the widget
+ explicitly.
Since the window containing the clock widget will have no title bar, we provide
implementations for \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} and
@@ -69,8 +45,9 @@
\section1 ShapedClock Class Implementation
- The \c ShapedClock constructor performs many of the same tasks as the \c AnalogClock
- constructor. We set up a timer and connect it to the widget's update() slot:
+ The \c ShapedClock constructor sets up a timer and connect it to the widget's
+ update() slot. In addition, we add an action to the widget, which will automatically
+ become available through a context menu when right-clicking on the widget.
\snippet widgets/shapedclock/shapedclock.cpp 0
@@ -101,49 +78,14 @@
cursor position in global coordinates. If we drag the widget, we also accept the event.
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.
+ \l{Analog Clock} example. The one addition is that we use QPainter::drawEllipse() to
+ draw a round clock face. We reduce the painter's opacity to 90%, and use the palette's
+ default background color.
\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. 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
-
- Since the clock face is a circle drawn in the center of the widget, this is the region
- we use as the mask.
-
- Although the lack of a window frame may make it difficult for the user to resize the
- widget on some platforms, it will not necessarily be impossible. The \c resizeEvent()
- function ensures that the widget mask will always be updated if the widget's dimensions
- change, and additionally ensures that it will be set up correctly when the widget is
- first displayed.
-
Finally, we implement the \c sizeHint() for the widget so that it is given a reasonable
default size when it is first shown:
- \snippet widgets/shapedclock/shapedclock.cpp 5
-
- \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.
-
- Widget masks can also be constructed by using the contents of pixmap to define the
- opaque part of the widget. For a pixmap with an alpha channel, a suitable mask can be
- obtained with QPixmap::mask().
+ \snippet widgets/shapedclock/shapedclock.cpp 4
*/
diff --git a/examples/widgets/doc/src/shortcuteditor.qdoc b/examples/widgets/doc/src/shortcuteditor.qdoc
new file mode 100644
index 0000000000..9999a18421
--- /dev/null
+++ b/examples/widgets/doc/src/shortcuteditor.qdoc
@@ -0,0 +1,231 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+ \example widgets/shortcuteditor
+ \title Shortcut Editor Example
+ \examplecategory {User Interface Components}
+ \ingroup examples-widgets
+ \brief The Shortcut Editor example shows how to create a basic, read-write
+ hierarchical model to use with Qt's standard view and QKeySequenceEdit
+ classes. For a description of Model/View Programming, see the \l{Model/View
+ Programming} overview.
+
+ \image shortcuteditor-example.png
+
+ Qt's model/view architecture provides a standard way for views to
+ manipulate information in a data source, using an abstract model
+ of the data to simplify and standardize the way it is accessed.
+ The shortcut editor model represents the actions as a tree of items, and
+ allow views to access this data via an
+ \l{Model/View Programming#Models}{index-based} system. More generally,
+ models can be used to represent data in the form of a tree structure
+ by allowing each item to act as a parent to a table of child items.
+
+ \section1 Design and Concepts
+
+ The data structure that we use to represent the structure of the data takes
+ the form of a tree built from ShortcutEditorModelItem objects. Each
+ ShortcutEditorModelItem represents an item in a tree view, and contains
+ two columns of data.
+
+ \table
+ \row \li \inlineimage treemodel-structure.png
+ \li \b{Shortcut Editor Structure}
+
+ The data is stored internally in the model using ShortcutEditorModelItem
+ objects that are linked together in a pointer-based tree structure.
+ Generally, each ShortcutEditorModelItem has a parent item, and can have a
+ number of child items. However, the root item in the tree structure has no
+ parent item and it is never referenced outside the model.
+
+ Each ShortcutEditorModelItem contains information about its place in the
+ tree structure; it can return its parent item and its row number. Having
+ this information readily available makes implementing the model easier.
+
+ Since each item in a tree view usually contains several columns of data
+ (a name and a shortcut in this example), it is natural to store this
+ information in each item. For simplicity, we will use a list of QVariant
+ objects to store the data for each column in the item.
+ \endtable
+
+ The use of a pointer-based tree structure means that, when passing a
+ model index to a view, we can record the address of the corresponding
+ item in the index (see QAbstractItemModel::createIndex()) and retrieve
+ it later with QModelIndex::internalPointer(). This makes writing the
+ model easier and ensures that all model indexes that refer to the same
+ item have the same internal data pointer.
+
+ With the appropriate data structure in place, we can create a tree model
+ with a minimal amount of extra code to supply model indexes and data to
+ other components.
+
+ \section1 ShortcutEditorModelItem Class Definition
+
+ The ShortcutEditorModelItem class is defined as follows:
+
+ The class is a basic C++ class. It does not inherit from QObject or
+ provide signals and slots. It is used to hold a list of QVariants,
+ containing column data, and information about its position in the tree
+ structure. The functions provide the following features:
+
+ \list
+ \li The \c appendChildItem() is used to add data when the model is first
+ constructed and is not used during normal use.
+ \li The \c child() and \c childCount() functions allow the model to obtain
+ information about any child items.
+ \li Information about the number of columns associated with the item is
+ provided by \c columnCount(), and the data in each column can be
+ obtained with the data() function.
+ \li The \c row() and \c parent() functions are used to obtain the item's
+ row number and parent item.
+ \endlist
+
+ The parent item and column data are stored in the \c parentItem and
+ \c itemData private member variables. The \c childItems variable contains
+ a list of pointers to the item's own child items.
+
+ \section1 ShortcutEditorModel Class Definition
+
+ The \c ShortcutEditorModel class is defined as follows:
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.h 0
+
+ This class is similar to most other subclasses of QAbstractItemModel that
+ provide read-write models. Only the form of the constructor and the
+ \c setupModelData() function are specific to this model. In addition, we
+ provide a destructor to clean up when the model is destroyed.
+
+ \section1 ShortcutEditorModel Class Implementation
+
+ The constructor takes an argument containing the data that the model will
+ share with views and delegates:
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.cpp 0
+
+ It is up to the constructor to create a root item for the model. This
+ item only contains vertical header data for convenience. We also use it
+ to reference the internal data structure that contains the model data,
+ and it is used to represent an imaginary parent of top-level items in
+ the model.
+
+ The model's internal data structure is populated with items by the
+ \c setupModelData() function. We will examine this function separately
+ at the end of this document.
+
+ The destructor ensures that the root item and all of its descendants
+ are deleted when the model is destroyed:
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.cpp 1
+
+ Since we cannot add data to the model after it is constructed and set
+ up, this simplifies the way that the internal tree of items is managed.
+
+ Models must implement an \c index() function to provide indexes for
+ views and delegates to use when accessing data. Indexes are created
+ for other components when they are referenced by their row and column
+ numbers, and their parent model index. If an invalid model
+ index is specified as the parent, it is up to the model to return an
+ index that corresponds to a top-level item in the model.
+
+ When supplied with a model index, we first check whether it is valid.
+ If it is not, we assume that a top-level item is being referred to;
+ otherwise, we obtain the data pointer from the model index with its
+ \l{QModelIndex::internalPointer()}{internalPointer()} function and use
+ it to reference a \c TreeItem object. Note that all the model indexes
+ that we construct will contain a pointer to an existing \c TreeItem,
+ so we can guarantee that any valid model indexes that we receive will
+ contain a valid data pointer.
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.cpp 2
+
+ Since the row and column arguments to this function refer to a
+ child item of the corresponding parent item, we obtain the item using
+ the \c TreeItem::child() function. The
+ \l{QAbstractItemModel::createIndex()}{createIndex()} function is used
+ to create a model index to be returned. We specify the row and column
+ numbers, and a pointer to the item itself. The model index can be used
+ later to obtain the item's data.
+
+ The way that the \c TreeItem objects are defined makes writing the
+ \c parent() function easy:
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.cpp 3
+
+ We only need to ensure that we never return a model index corresponding
+ to the root item. To be consistent with the way that the \c index()
+ function is implemented, we return an invalid model index for the
+ parent of any top-level items in the model.
+
+ When creating a model index to return, we must specify the row and
+ column numbers of the parent item within its own parent. We can
+ easily discover the row number with the \c TreeItem::row() function,
+ but we follow a convention of specifying 0 as the column number of
+ the parent. The model index is created with
+ \l{QAbstractItemModel::createIndex()}{createIndex()} in the same way
+ as in the \c index() function.
+
+ The \c rowCount() function simply returns the number of child items
+ for the \c TreeItem that corresponds to a given model index, or the
+ number of top-level items if an invalid index is specified:
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.cpp 4
+
+ Since each item manages its own column data, the \c columnCount()
+ function has to call the item's own \c columnCount() function to
+ determine how many columns are present for a given model index.
+ As with the \c rowCount() function, if an invalid model index is
+ specified, the number of columns returned is determined from the
+ root item:
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.cpp 5
+
+ Data is obtained from the model via \c data(). Since the item manages
+ its own columns, we need to use the column number to retrieve the data
+ with the \c TreeItem::data() function:
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.cpp 6
+
+ Note that we only support the \l{Qt::ItemDataRole}{DisplayRole}
+ in this implementation, and we also return invalid QVariant objects for
+ invalid model indexes.
+
+ We use the \c flags() function to ensure that views know that the
+ model is read-only:
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.cpp 7
+
+ The \c headerData() function returns data that we conveniently stored
+ in the root item:
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.cpp 8
+
+ This information could have been supplied in a different way: either
+ specified in the constructor, or hard coded into the \c headerData()
+ function.
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.cpp 9
+
+ TODO
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.cpp 10
+
+ TODO
+
+ \snippet widgets/shortcuteditor/shortcuteditormodel.cpp 11
+
+ TODO
+
+ \section1 Setting Up the Data in the Model
+
+ We use the \c setupModelData() function to set up the initial data in
+ the model. This function retrieves the registered actions text and creates
+ item objects that record both the data and the overall model structure.
+ Naturally, this function works in a way that is very specific to
+ this model. We provide the following description of its behavior,
+ and refer the reader to the example code itself for more information.
+
+ To ensure that the model works correctly, it is only necessary to
+ create instances of ShortcutEditorModelItem with the correct data and
+ parent item.
+*/
diff --git a/examples/widgets/doc/src/simpledommodel.qdoc b/examples/widgets/doc/src/simpledommodel.qdoc
deleted file mode 100644
index 314e0fe9d4..0000000000
--- a/examples/widgets/doc/src/simpledommodel.qdoc
+++ /dev/null
@@ -1,280 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 itemviews/simpledommodel
- \title Simple DOM Model Example
- \ingroup examples-itemviews
- \brief The Simple DOM Model example shows how an existing class can be adapted for use with
- the model/view framework.
-
- \image simpledommodel-example.png
-
- Qt provides two complementary sets of classes for reading XML files: The classes based
- around QXmlReader provide a SAX-style API for incremental reading of large files, and
- the classes based around QDomDocument enable developers to access the contents of XML
- files using a Document Object Model (DOM) API.
-
- In this example, we create a model that uses the DOM API to expose the structure and
- contents of XML documents to views via the standard QAbstractModel interface.
-
- \section1 Design and Concepts
-
- Reading an XML document with Qt's DOM classes is a straightforward process. Typically,
- the contents of a file are supplied to QDomDocument, and nodes are accessed using the
- functions provided by QDomNode and its subclasses.
-
- \omit
- For example, the following code
- snippet reads the contents of a file into a QDomDocument object and traverses the
- document, reading all the plain text that can be found:
-
- \snippet doc/src/snippets/code/doc_src_examples_simpledommodel.cpp 0
-
- In principle, the functions provided by QDomNode can be used to navigate from any
- given starting point in a document to the piece of data requested by another component.
- Since QDomDocument maintains information about the structure of a document, we can
- use this to implement the required virtual functions in a QAbstractItemModel subclass.
- \endomit
-
- The aim is to use the structure provided by QDomDocument by wrapping QDomNode objects
- in item objects similar to the \c TreeItem objects used in the
- \l{Simple Tree Model Example}{Simple Tree Model} example.
-
- \section1 DomModel Class Definition
-
- Let us begin by examining the \c DomModel class:
-
- \snippet itemviews/simpledommodel/dommodel.h 0
-
- The class definition contains all the basic functions that are needed for a
- read-only model. Only the constructor and \c document() function are specific to
- this model. The private \c domDocument variable is used to hold the document
- that is exposed by the model; the \c rootItem variable contains a pointer to
- the root item in the model.
-
- \section1 DomItem Class Definition
-
- The \c DomItem class is used to hold information about a specific QDomNode in
- the document:
-
- \snippet itemviews/simpledommodel/domitem.h 0
-
- Each \c DomItem provides a wrapper for a QDomNode obtained from the underlying
- document which contains a reference to the node, it's location in the parent node's
- list of child nodes, and a pointer to a parent wrapper item.
-
- The \c parent(), \c child(), and \c row() functions are convenience functions for
- the \c DomModel to use that provide basic information about the item to be discovered
- quickly. The node() function provides access to the underlying QDomNode object.
-
- As well as the information supplied in the constructor, the class maintains a cache
- of information about any child items. This is used to provide a collection of
- persistent item objects that the model can identify consistently and improve the
- performance of the model when accessing child items.
-
- \section1 DomItem Class Implementation
-
- Since the \c DomItem class is only a thin wrapper around QDomNode objects, with a
- few additional features to help improve performance and memory usage, we can provide
- a brief outline of the class before discussing the model itself.
-
- The constructor simply records details of the QDomNode that needs to be wrapped:
-
- \snippet itemviews/simpledommodel/domitem.cpp 0
- \snippet itemviews/simpledommodel/domitem.cpp 1
-
- As a result, functions to provide the parent wrapper, the row number occupied by
- the item in its parent's list of children, and the underlying QDomNode for each item
- are straightforward to write:
-
- \snippet itemviews/simpledommodel/domitem.cpp 4
- \codeline
- \snippet itemviews/simpledommodel/domitem.cpp 6
- \codeline
- \snippet itemviews/simpledommodel/domitem.cpp 3
-
- It is necessary to maintain a collection of items which can be consistently identified
- by the model. For that reason, we maintain a hash of child wrapper items that, to
- minimize memory usage, is initially empty. The model uses the item's \c child()
- function to help create model indexes, and this constructs wrappers for the children
- of the item's QDomNode, relating the row number of each child to the newly-constructed
- wrapper:
-
- \snippet itemviews/simpledommodel/domitem.cpp 5
-
- If a QDomNode was previously wrapped, the cached wrapper is returned; otherwise, a
- new wrapper is constructed and stored for valid children, and zero is returned for
- invalid ones.
-
- The class's destructor deletes all the child items of the wrapper:
-
- \snippet itemviews/simpledommodel/domitem.cpp 2
-
- These, in turn, will delete their children and free any QDomNode objects in use.
-
- \section1 DomModel Class Implementation
-
- The structure provided by the \c DomItem class makes the implementation of \c DomModel
- similar to the \c TreeModel shown in the
- \l{Simple Tree Model Example}{Simple Tree Model} example.
-
- The constructor accepts an existing document and a parent object for the model:
-
- \snippet itemviews/simpledommodel/dommodel.cpp 0
-
- A shallow copy of the document is stored for future reference, and a root item is
- created to provide a wrapper around the document. We assign the root item a row
- number of zero only to be consistent since the root item will have no siblings.
-
- Since the model only contains information about the root item, the destructor only
- needs to delete this one item:
-
- \snippet itemviews/simpledommodel/dommodel.cpp 1
-
- All of the child items in the tree will be deleted by the \c DomItem destructor as
- their parent items are deleted.
-
- \section2 Basic Properties of The Model
-
- Some aspects of the model do not depend on the structure of the underlying document,
- and these are simple to implement.
-
- The number of columns exposed by the model is returned by the \c columnCount()
- function:
-
- \snippet itemviews/simpledommodel/dommodel.cpp 2
-
- This value is fixed, and does not depend on the location or type of the underlying
- node in the document. We will use these three columns to display different kinds of
- data from the underlying document.
-
- Since we only implement a read-only model, the \c flags() function is straightforward
- to write:
-
- \snippet itemviews/simpledommodel/dommodel.cpp 5
-
- Since the model is intended for use in a tree view, the \c headerData() function only
- provides a horizontal header:
-
- \snippet itemviews/simpledommodel/dommodel.cpp 6
-
- The model presents the names of nodes in the first column, element attributes in the
- second, and any node values in the third.
-
- \section2 Navigating The Document
-
- The index() function creates a model index for the item with the given row, column,
- and parent in the model:
-
- \snippet itemviews/simpledommodel/dommodel.cpp 7
-
- The function first has to relate the parent index to an item that contains a node
- from the underlying document. If the parent index is invalid, it refers to the root
- node in the document, so we retrieve the root item that wraps it; otherwise, we
- obtain a pointer to the relevant item using the QModelIndex::internalPointer()
- function. We are able to extract a pointer in this way because any valid model index
- will have been created by this function, and we store pointers to item objects in
- any new indexes that we create with QAbstractItemModel::createIndex():
-
- \snippet itemviews/simpledommodel/dommodel.cpp 8
-
- A child item for the given row is provided by the parent item's \c child() function.
- If a suitable child item was found then we call
- \l{QAbstractItemModel::createIndex()}{createIndex()} to produce a model index for the
- requested row and column, passing a pointer to the child item for it to store
- internally. If no suitable child item is found, an invalid model index is returned.
-
- Note that the items themselves maintain ownership of their child items. This means
- that the model does not need to keep track of the child items that have been created,
- and can let the items themselves tidy up when they are deleted.
-
- The number of rows beneath a given item in the model is returned by the \c rowCount()
- function, and is the number of child nodes contained by the node that corresponds to
- the specified model index:
-
- \snippet itemviews/simpledommodel/dommodel.cpp 10
-
- To obtain the relevant node in the underlying document, we access the item via the
- internal pointer stored in the model index. If an invalid index is supplied, the
- root item is used instead. We use the item's \c node() function to access the node
- itself, and simply count the number of child nodes it contains.
-
- Since the model is used to represent a hierarchical data structure, it needs to
- provide an implementation for the \c parent() function. This returns a model index
- that corresponds to the parent of a child model index supplied as its argument:
-
- \snippet itemviews/simpledommodel/dommodel.cpp 9
-
- For valid indexes other than the index corresponding to the root item, we obtain
- a pointer to the relevant item using the method described in the \c index() function,
- and use the item's \c parent() function to obtain a pointer to the parent item.
-
- If no valid parent item exists, or if the parent item is the root item, we can simply
- follow convention and return an invalid model index. For all other parent items, we
- create a model index containing the appropriate row and column numbers, and a pointer
- to the parent item we just obtained.
-
- Data is provided by the \c data() function. For simplicity, we only provide data for
- the \l{Qt::DisplayRole}{display role}, returning an invalid variant for all other
- requests:
-
- \snippet itemviews/simpledommodel/dommodel.cpp 3
-
- As before, we obtain an item pointer for the index supplied, and use it to obtain
- the underlying document node. Depending on the column specified, the data we return
- is obtained in different ways:
-
- \snippet itemviews/simpledommodel/dommodel.cpp 4
-
- For the first column, we return the node's name. For the second column, we read any
- attributes that the node may have, and return a string that contains a space-separated
- list of attribute-value assignments. For the third column, we return any value that
- the node may have; this allows the contents of text nodes to be displayed in a view.
-
- If data from any other column is requested, an invalid variant is returned.
-
- \section1 Implementation Notes
-
- Ideally, we would rely on the structure provided by QDomDocument to help us write
- the \l{QAbstractItemModel::parent()}{parent()} and
- \l{QAbstractItemModel::index()}{index()} functions that are required when subclassing
- QAbstractItemModel. However, since Qt's DOM classes use their own system for
- dynamically allocating memory for DOM nodes, we cannot guarantee that the QDomNode
- objects returned for a given piece of information will be the same for subsequent
- accesses to the document.
-
- We use item wrappers for each QDomNode to provide consistent pointers that the model
- can use to navigate the document structure.
- \omit
- Since these items contain value references to the QDomNode objects themselves, this
- has the side effect that the DOM nodes themselves can be used to reliably navigate
- the document [not sure about this - QDom* may return different QDomNode objects for
- the same piece of information]. However, this advantage is redundant since we need to
- use wrapper items to obtain it. [Possible use of QDomNode cache in the model itself.]
- \endomit
-*/
diff --git a/examples/widgets/doc/src/simplerhiwidget.qdoc b/examples/widgets/doc/src/simplerhiwidget.qdoc
new file mode 100644
index 0000000000..e53302218e
--- /dev/null
+++ b/examples/widgets/doc/src/simplerhiwidget.qdoc
@@ -0,0 +1,204 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+ \example rhi/simplerhiwidget
+ \title Simple RHI Widget Example
+ \examplecategory {Graphics}
+ \ingroup examples-widgets
+ \brief Shows how to render a triangle using QRhi, Qt's 3D API and shading language abstraction layer.
+
+ \image simplerhiwidget-example.jpg
+ \caption Screenshot of the Simple RHI Widget example
+
+ This example is, in many ways, the counterpart of the \l{RHI Window
+ Example} in the \l QWidget world. The \l QRhiWidget subclass in this
+ applications renders a single triangle, using a simple graphics pipeline
+ with basic vertex and fragment shaders. Unlike the plain QWindow-based
+ application, this example does not need to worry about lower level details,
+ such as setting up the window and the QRhi, or dealing with swapchain and
+ window events, as that is taken care of by the QWidget framework here. The
+ instance of the \l QRhiWidget subclass is added to a QVBoxLayout. To keep
+ the example minimal and compact, there are no further widgets or 3D content
+ introduced.
+
+ Once an instance of \c ExampleRhiWidget, a \l QRhiWidget subclass, is added
+ to a top-level widget's child hierarchy, the corresponding window
+ automatically becomes a Direct 3D, Vulkan, Metal, or OpenGL-rendered
+ window. The QPainter-rendered widget content, i.e. everything that is not a
+ QRhiWidget, QOpenGLWidget, or QQuickWidget, is then uploaded to a texture,
+ whereas the mentioned special widgets each render to a texture. The
+ resulting set of \l{QRhiTexture}{textures} is composited together by the
+ top-level widget's backingstore.
+
+ \section1 Structure and main()
+
+ The \c{main()} function is quite simple. The top-level widget defaults to a
+ size of 720p (this size is in logical units, the actual pixel size may be
+ different, depending on the \l{QWidget::devicePixelRatio()}{scale factor}.
+ The window is resizable. QRhiWidget makes it simple to implement subclasses
+ that correctly deal with the resizing of the widget due to window size or
+ layout changes.
+
+ \snippet rhi/simplerhiwidget/main.cpp 0
+
+ The QRhiWidget subclass reimplements the two virtuals:
+ \l{QRhiWidget::initialize()}{initialize()} and
+ \l{QRhiWidget::render()}{render()}.
+ initialize() is called at least once before render(),
+ but is also invoked upon a number of important changes, such as when the
+ widget's backing texture is recreated due to a changing widget size, when
+ render target parameters change, or when the widget changes to a new QRhi
+ due to moving to a new top-level window.
+
+ \note Unlike QOpenGLWidget's legacy \c initializeGL - \c resizeGL - \c
+ paintGL model, there are only two virtuals in QRhiWidget. This is because
+ there are more special events that possible need taking care of than just
+ resizing, e.g. when reparenting to a different top-level window. (robust
+ QOpenGLWidget implementations had to deal with this by performing
+ additional bookkeeping, e.g. by tracking the associated QOpenGLContext
+ lifetime, meaning the three virtuals were not actually sufficient) A
+ simpler pair of \c initialize - \c render, where \c initialize is
+ re-invoked upon important changes is better suited for this.
+
+ The \l QRhi instance is not owned by the widget. It is going to be queried
+ in \c initialize() \l{QRhiWidget::rhi()}{from the base class}. Storing it
+ as a member allows recognizing changes when \c initialize() is invoked
+ again. Graphics resources, such as the vertex and uniform buffers, or the
+ graphics pipeline are however under the control of \c ExampleRhiWidget.
+
+ \snippet rhi/simplerhiwidget/examplewidget.h 0
+
+ For the \c{#include <rhi/qrhi.h>} statement to work, the application must
+ link to \c GuiPrivate (or \c{gui-private} with qmake). See \l QRhi for more
+ details about the compatibility promise of the QRhi family of APIs.
+
+ \c CMakeLists.txt
+
+ \badcode
+ target_link_libraries(simplerhiwidget PRIVATE
+ Qt6::Core
+ Qt6::Gui
+ Qt6::GuiPrivate
+ Qt6::Widgets
+ )
+ \endcode
+
+ \section1 Rendering Setup
+
+ In \c examplewidget.cpp the widget implementation uses a helper function to
+ load up a \l QShader object from a \c{.qsb} file. This application ships
+ pre-conditioned \c{.qsb} files embedded in to the executable via the Qt
+ Resource System. Due to module dependencies (and due to still supporting
+ qmake), this example does not use the convenient CMake function
+ \c{qt_add_shaders()}, but rather comes with the \c{.qsb} files as part of
+ the source tree. Real world applications are encouraged to avoid this and
+ rather use the Qt Shader Tools module's CMake integration features (\c
+ qt_add_shaders). Regardless of the approach, in the C++ code the loading
+ of the bundled/generated \c{.qsb} files is the same.
+
+ \snippet rhi/simplerhiwidget/examplewidget.cpp get-shader
+
+ Let's look at the initialize() implementation. First, the \l QRhi object is
+ queried and stored for later use, and also to allow comparison in future
+ invocations of the function. When there is a mismatch (e.g. when the widget
+ is moved between windows), recreation of graphics resources need to be
+ recreated is triggered by destroying and nulling out a suitable object, in
+ this case the \c m_pipeline. The example does not actively demonstrate
+ reparenting between windows, but it is prepared to handle it. It is also
+ prepared to handle a changing widget size that can happen when resizing the
+ window. That needs no special handling since \c{initialize()} is invoked
+ every time that happens, and so querying
+ \c{renderTarget()->pixelSize()} or \c{colorTexture()->pixelSize()}
+ always gives the latest, up-to-date size in pixels. What this example is
+ not prepared for is changing
+ \l{QRhiWidget::textureFormat}{texture formats} and
+ \l{QRhiWidget::sampleCount}{multisample settings}
+ since it only ever uses the defaults (RGBA8 and no multisample antialiasing).
+
+ \snippet rhi/simplerhiwidget/examplewidget.cpp init-1
+
+ When the graphics resources need to be (re)created, \c{initialize()} does
+ this using quite typical QRhi-based code. A single vertex buffer with the
+ interleaved position - color vertex data is sufficient, whereas the
+ modelview-projection matrix is exposed via a uniform buffer of 64 bytes (16
+ floats). The uniform buffer is the only shader visible resource, and it is
+ only used in the vertex shader. The graphics pipeline relies on a lot of
+ defaults (for example, depth test off, blending disabled, color write
+ enabled, face culling disabled, the default topology of triangles, etc.)
+ The vertex data layout is \c x, \c y, \c r, \c g, \c b, hence the stride is
+ 5 floats, whereas the second vertex input attribute (the color) has an
+ offset of 2 floats (skipping \c x and \c y). Each graphics pipeline has to
+ be associated with a \l QRhiRenderPassDescriptor. This can be retrieved
+ from the \l QRhiRenderTarget managed by the base class.
+
+ \note This example relies on the QRhiWidget's default of
+ \l{QRhiWidget::autoRenderTarget}{autoRenderTarget} set to \c true.
+ That is why it does not need to manage the render target, but can just
+ query the existing one by calling
+ \l{QRhiWidget::renderTarget()}{renderTarget()}.
+
+ \snippet rhi/simplerhiwidget/examplewidget.cpp init-pipeline
+
+ Finally, the projection matrix is calculated. This depends on the widget
+ size and is thus done unconditionally in every invocation of the functions.
+
+ \note Any size and viewport calculations should only ever rely on the pixel
+ size queried from the resource serving as the color buffer since that is
+ the actual render target. Avoid manually calculating sizes, viewports,
+ scissors, etc. based on the QWidget-reported size or device pixel ratio.
+
+ \note The projection matrix includes the
+ \l{QRhi::clipSpaceCorrMatrix()}{correction matrix} from QRhi in order to
+ cater for 3D API differences in normalized device coordinates.
+ (for example, Y down vs. Y up)
+
+ A translation of \c{-4} is applied just to make sure the triangle with \c z
+ values of 0 will be visible.
+
+ \snippet rhi/simplerhiwidget/examplewidget.cpp init-matrix
+
+ \section1 Rendering
+
+ The widget records a single render pass, which contains a single draw call.
+
+ The view-projection matrix calculated in the initialize step gets combined
+ with the model matrix, which in this case happens to be a simple rotation.
+ The resulting matrix is then written to the uniform buffer. Note how
+ \c resourceUpdates is passed to
+ \l{QRhiCommandBuffer::beginPass()}{beginPass()}, which is a shortcut to not
+ having to invoke \l{QRhiCommandBuffer::resourceUpdate()}{resourceUpdate()}
+ manually.
+
+ \snippet rhi/simplerhiwidget/examplewidget.cpp render-1
+
+ In the render pass, a single draw call with 3 vertices is recorded. The
+ graphics pipeline created in the initialize step is bound on the command
+ buffer, and the viewport is set to cover the entire widget. To make the
+ uniform buffer visible to the (vertex) shader,
+ \l{QRhiCommandBuffer::setShaderResources()}{setShaderResources()} is called
+ with no argument, which means using the \c m_srb since that was associated
+ with the pipeline at pipeline creation time. In more complex renderers it
+ is not unusual to pass in a different \l QRhiShaderResourceBindings object,
+ as long as that is
+ \l{QRhiShaderResourceBindings::isLayoutCompatible()}{layout-compatible}
+ with the one given at pipeline creation time.
+ There is no index buffer, and there is a single vertex buffer binding (the
+ single element in \c vbufBinding refers to the single entry in the binding
+ list of the \l QRhiVertexInputLayout that was specified when creating
+ pipeline).
+
+ \snippet rhi/simplerhiwidget/examplewidget.cpp render-pass
+
+ Once the render pass is recorded, \l{QWidget::update()}{update()} is
+ called. This requests a new frame, and is used to ensure the widget
+ continuously updates, and the triangle appears rotating. The rendering
+ thread (the main thread in this case) is throttled by the presentation rate
+ by default. There is no proper animation system in this example, and so the
+ rotation will increase in every frame, meaning the triangle will rotate at
+ different speeds on displays with different refresh rates.
+
+ \snippet rhi/simplerhiwidget/examplewidget.cpp render-2
+
+ \sa QRhi, {Cube RHI Widget Example}, {RHI Window Example}
+*/
diff --git a/examples/widgets/doc/src/simpletreemodel.qdoc b/examples/widgets/doc/src/simpletreemodel.qdoc
index f5fe93897c..aa12a9585f 100644
--- a/examples/widgets/doc/src/simpletreemodel.qdoc
+++ b/examples/widgets/doc/src/simpletreemodel.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example itemviews/simpletreemodel
\title Simple Tree Model Example
+ \examplecategory {User Interface Components}
\ingroup examples-itemviews
\ingroup examples-layout
\brief The Simple Tree Model example shows how to use a hierarchical model
@@ -128,16 +105,14 @@
\snippet itemviews/simpletreemodel/treeitem.cpp 0
A pointer to each of the child items belonging to this item will be
- stored in the \c childItems private member variable. When the class's
- destructor is called, it must delete each of these to ensure that
- their memory is reused:
-
- \snippet itemviews/simpletreemodel/treeitem.cpp 1
+ stored in the \c childItems private member variable as an std::unique_ptr.
+ When the class's destructor is called, the child items will be automatically
+ deleted to ensure that their memory is reused:
Since each of the child items are constructed when the model is initially
populated with data, the function to add child items is straightforward:
- \snippet itemviews/simpletreemodel/treeitem.cpp 2
+ \snippet itemviews/simpletreemodel/treeitem.cpp 1
Each item is able to return any of its child items when given a suitable
row number. For example, in the \l{#SimpleTreeModelStructure}{above diagram},
@@ -148,11 +123,11 @@
The \c child() function returns the child that corresponds to
the specified row number in the item's list of child items:
- \snippet itemviews/simpletreemodel/treeitem.cpp 3
+ \snippet itemviews/simpletreemodel/treeitem.cpp 2
The number of child items held can be found with \c childCount():
- \snippet itemviews/simpletreemodel/treeitem.cpp 4
+ \snippet itemviews/simpletreemodel/treeitem.cpp 3
The \c TreeModel uses this function to determine the number of rows that
exist for a given parent item.
@@ -160,7 +135,7 @@
The \c row() function reports the item's location within its parent's
list of items:
- \snippet itemviews/simpletreemodel/treeitem.cpp 8
+ \snippet itemviews/simpletreemodel/treeitem.cpp 7
Note that, although the root item (with no parent item) is automatically
assigned a row number of 0, this information is never used by the model.
@@ -168,16 +143,17 @@
The number of columns of data in the item is trivially returned by the
\c columnCount() function.
- \snippet itemviews/simpletreemodel/treeitem.cpp 5
+ \snippet itemviews/simpletreemodel/treeitem.cpp 4
- Column data is returned by the \c data() function. The bounds are checked
- before accessing the container with the data:
+ Column data is returned by the \c data() function. We use
+ the QList::value() convenience function which checks the bounds
+ and returns a default-constructed QVariant in case they are violated:
- \snippet itemviews/simpletreemodel/treeitem.cpp 6
+ \snippet itemviews/simpletreemodel/treeitem.cpp 5
The item's parent is found with \c parent():
- \snippet itemviews/simpletreemodel/treeitem.cpp 7
+ \snippet itemviews/simpletreemodel/treeitem.cpp 6
Note that, since the root item in the model will not have a parent, this
function will return zero in that case. We need to ensure that the model
@@ -207,14 +183,16 @@
item only contains vertical header data for convenience. We also use it
to reference the internal data structure that contains the model data,
and it is used to represent an imaginary parent of top-level items in
- the model.
+ the model. The root item is managed with a std::unique_ptr to ensure the
+ entire tree of item is deleted when the model is deleted.
The model's internal data structure is populated with items by the
\c setupModelData() function. We will examine this function separately
at the end of this document.
The destructor ensures that the root item and all of its descendants
- are deleted when the model is destroyed:
+ are deleted when the model is destroyed. This is done automatically
+ since the root item is stored in a unique_ptr.
\snippet itemviews/simpletreemodel/treemodel.cpp 1
@@ -341,4 +319,21 @@
To ensure that the model works correctly, it is only necessary to
create instances of \c TreeItem with the correct data and parent item.
+
+ \section1 Testing the model
+
+ Correctly implementing an item model can be challenging. The class
+ \l [QtTest] QAbstractItemModelTester from the \l [QtTest] {Qt Test} module
+ checks for model consistency, like the model index creation and
+ parent-child relationships.
+
+ You can test your model by just passing a model instance to the class
+ constructor, for instance as part of a Qt unit test:
+
+ \snippet itemviews/simpletreemodel/test.cpp 1
+
+ To create a test which can be run using the \c ctest executable,
+ \c add_test() is used:
+
+ \snippet itemviews/simpletreemodel/CMakeLists.txt 1
*/
diff --git a/examples/widgets/doc/src/simplewidgetmapper.qdoc b/examples/widgets/doc/src/simplewidgetmapper.qdoc
deleted file mode 100644
index c427dc6542..0000000000
--- a/examples/widgets/doc/src/simplewidgetmapper.qdoc
+++ /dev/null
@@ -1,125 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 itemviews/simplewidgetmapper
- \title Simple Widget Mapper Example
- \ingroup examples-itemviews
- \brief The Simple Widget Mapper example shows how to use a widget mapper to display
- data from a model in a collection of widgets.
-
- \image simplewidgetmapper-example.png
-
- The QDataWidgetMapper class allows information obtained from a
- \l{Model Classes}{model} to be viewed and edited in a collection of
- widgets instead of in an \l{View Classes}{item view}.
- Any model derived from QAbstractItemModel can be used as the source of
- data and almost any input widget can be used to display it.
-
- The example itself is very simple: we create \c Window, a QWidget subclass
- that we use to hold the widgets used to present the data, and show it. The
- \c Window class will provide buttons that the user can click to show
- different records from the model.
-
- \section1 Window Class Definition
-
- The class provides a constructor, a slot to keep the buttons up to date,
- and a private function to set up the model:
-
- \snippet itemviews/simplewidgetmapper/window.h Window definition
-
- In addition to the QDataWidgetMapper object and the controls used to make
- up the user interface, we use a QStandardItemModel to hold our data.
- We could use a custom model, but this standard implementation is sufficient
- for our purposes.
-
- \section1 Window Class Implementation
-
- The constructor of the \c Window class can be explained in three parts.
- In the first part, we set up the widgets used for the user interface:
-
- \snippet itemviews/simplewidgetmapper/window.cpp Set up widgets
-
- We also set up the buddy relationships between various labels and the
- corresponding input widgets.
-
- Next, we set up the widget mapper, relating each input widget to a column
- in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}:
-
- \snippet itemviews/simplewidgetmapper/window.cpp Set up the mapper
-
- We also connect the mapper to the \uicontrol{Next} and \uicontrol{Previous} buttons
- via its \l{QDataWidgetMapper::}{toNext()} and
- \l{QDataWidgetMapper::}{toPrevious()} slots. The mapper's
- \l{QDataWidgetMapper::}{currentIndexChanged()} signal is connected to the
- \c{updateButtons()} slot in the window which we'll show later.
-
- In the final part of the constructor, we set up the layout, placing each
- of the widgets in a grid (we could also use a QFormLayout for this):
-
- \snippet itemviews/simplewidgetmapper/window.cpp Set up the layout
-
- Lastly, we set the window title and initialize the mapper by setting it to
- refer to the first row in the model.
-
- The model is initialized in the window's \c{setupModel()} function. Here,
- we create a standard model with 5 rows and 3 columns, and we insert some
- sample names, addresses and ages into each row:
-
- \snippet itemviews/simplewidgetmapper/window.cpp Set up the model
-
- As a result, each row can be treated like a record in a database, and the
- widget mapper will read the data from each row, using the column numbers
- specified earlier to access the correct data for each widget. This is
- shown in the following diagram:
-
- \image widgetmapper-simple-mapping.png
-
- Since the user can navigate using the buttons in the user interface, the
- example is fully-functional at this point, but to make it a bit more
- user-friendly, we implement the \c{updateButtons()} slot to show when the
- user is viewing the first or last records:
-
- \snippet itemviews/simplewidgetmapper/window.cpp Slot for updating the buttons
-
- If the mapper is referring to the first row in the model, the \uicontrol{Previous}
- button is disabled. Similarly, the \uicontrol{Next} button is disabled if the
- mapper reaches the last row in the model.
-
- \section1 More Complex Mappings
-
- The QDataWidgetMapper class makes it easy to relate information from a
- model to widgets in a user interface. However, it is sometimes necessary
- to use input widgets which offer choices to the user, such as QComboBox,
- in conjunction with a widget mapper.
-
- In these situations, although the mapping to input widgets remains simple,
- more work needs to be done to expose additional data to the widget mapper.
- This is covered by the \l{Combo Widget Mapper Example}{Combo Widget Mapper}
- and \l{SQL Widget Mapper Example}{SQL Widget Mapper}
- examples.
-*/
diff --git a/examples/widgets/doc/src/sliders.qdoc b/examples/widgets/doc/src/sliders.qdoc
index eb9a932c76..9bfb4abdc4 100644
--- a/examples/widgets/doc/src/sliders.qdoc
+++ b/examples/widgets/doc/src/sliders.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example widgets/sliders
\title Sliders Example
+ \examplecategory {User Interface Components}
\ingroup examples-widgets
\brief The Sliders example shows how to use the different types of sliders
available in Qt: QSlider, QScrollBar and QDial.
@@ -41,7 +18,8 @@
manipulated through their properties.
The example also demonstrates how signals and slots can be used to
- synchronize the behavior of two or more widgets.
+ synchronize the behavior of two or more widgets, and how to override
+ \l{QWidget::}{resizeEvent()} to implement a responsive layout.
\borderedimage sliders-example.png
\caption Screenshot of the Sliders example
@@ -54,10 +32,8 @@
QScrollBar and a QDial.
\li \c Window is the main widget combining a QGroupBox and a
- QStackedWidget. In this example, the QStackedWidget provides a
- stack of two \c SlidersGroup widgets. The QGroupBox contain
- several widgets that control the behavior of the slider-like
- widgets.
+ SlidersGroup. The QGroupBox contains several widgets that control
+ the behavior of the slider-like widgets.
\endlist
@@ -79,28 +55,14 @@
\snippet widgets/sliders/window.cpp 0
- In the constructor we first create the two \c SlidersGroup
- widgets that display the slider widgets horizontally and
- vertically, and add them to the QStackedWidget. QStackedWidget
- provides a stack of widgets where only the top widget is visible.
- With \c createControls() we create a connection from a
- controlling widget to the QStackedWidget, making the user able to
- choose between horizontal and vertical orientation of the slider
- widgets. The rest of the controlling mechanisms is implemented by
- the same function call.
+ In the constructor we first create the \c SlidersGroup widget
+ that displays the slider widgets. With \c createControls() we
+ create the controlling widgets, and connect those to to the
+ sliders.
\snippet widgets/sliders/window.cpp 1
- \snippet widgets/sliders/window.cpp 2
-
- Then we connect the \c horizontalSliders, \c verticalSliders and
- \c valueSpinBox to each other, so that the slider widgets and the
- control widget will behave synchronized when the current value of
- one of them changes. The \c valueChanged() signal is emitted with
- the new value as argument. The \c setValue() slot sets the
- current value of the widget to the new value, and emits \c
- valueChanged() if the new value is different from the old one.
- We put the group of control widgets and the stacked widget in a
+ We put the groups of control widgets and the sliders in a
horizontal layout before we initialize the minimum, maximum and
current values. The initialization of the current value will
propagate to the slider widgets through the connection we made
@@ -108,15 +70,14 @@
minimum and maximum values propagate through the connections we
created with \c createControls().
+ \snippet widgets/sliders/window.cpp 2
\snippet widgets/sliders/window.cpp 3
- \snippet widgets/sliders/window.cpp 4
In the private \c createControls() function, we let a QGroupBox
(\c controlsGroup) display the control widgets. A group box can
provide a frame, a title and a keyboard shortcut, and displays
various other widgets inside itself. The group of control widgets
- is composed by two checkboxes, three spin boxes (with labels) and
- one combobox.
+ is composed by two checkboxes, and three spin boxes with labels.
After creating the labels, we create the two checkboxes.
Checkboxes are typically used to represent features in an
@@ -154,8 +115,8 @@
bindings are inverted by default: \uicontrol PageDown increases the
current value, and \uicontrol PageUp decreases it.
+ \snippet widgets/sliders/window.cpp 4
\snippet widgets/sliders/window.cpp 5
- \snippet widgets/sliders/window.cpp 6
Then we create the spin boxes. QSpinBox allows the user to choose
a value by clicking the up and down buttons or pressing the \uicontrol
@@ -164,14 +125,15 @@
manually. The spin boxes control the minimum, maximum and current
values for the QSlider, QScrollBar, and QDial widgets.
- We create a QComboBox that allows the user to choose the
- orientation of the slider widgets. The QComboBox widget is a
- combined button and popup list. It provides a means of presenting
- a list of options to the user in a way that takes up the minimum
- amount of screen space.
+ \snippet widgets/sliders/window.cpp 6
- \snippet widgets/sliders/window.cpp 7
- \snippet widgets/sliders/window.cpp 8
+ Then we connect the \c slidersGroup and the \c valueSpinBox to each
+ other, so that the slider widgets and the control widget will behave
+ synchronized when the current value of one of them changes.
+ The \c valueChanged() signal is emitted with the new value as
+ argument. The \c setValue() slot sets the current value of the
+ widget to the new value, and emits \c valueChanged() if the new
+ value is different from the old one.
We synchronize the behavior of the control widgets and the slider
widgets through their signals and slots. We connect each control
@@ -181,6 +143,17 @@
lay out the control widgets in a QGridLayout within the \c
controlsGroup group box.
+ \snippet widgets/sliders/window.cpp 7
+
+ Lastly, we override resizeEvent() from QWidget. We guard against
+ dividing by zero, and otherwise compute the aspect ratio of the
+ widget. If the window has a portrait format, then we set the
+ layout to organize the groups of control widgets and sliders
+ vertically, and we give the sliders a horizontal orientation.
+ If the window has a landscape format, then we change the layout
+ to show the sliders and controlling widgets side by side, and
+ give the sliders a vertical orientation.
+
\section1 SlidersGroup Class Definition
\snippet widgets/sliders/slidersgroup.h 0
@@ -193,7 +166,8 @@
slot with equivalent functionality to the ones in QAbstractSlider
and QSpinBox. In addition, we implement several other public
slots to set the minimum and maximum value, and invert the slider
- widgets' appearance as well as key bindings.
+ widgets' appearance as well as key bindings, and set the
+ orientation.
\section1 SlidersGroup Class Implementation
@@ -206,24 +180,21 @@
focus. The Qt::StrongFocus policy means that the widget accepts
focus by both tabbing and clicking.
+ \snippet widgets/sliders/slidersgroup.cpp 1
+
Then we connect the widgets with each other, so that they will
stay synchronized when the current value of one of them changes.
- \snippet widgets/sliders/slidersgroup.cpp 1
- \snippet widgets/sliders/slidersgroup.cpp 2
-
We connect \c {dial}'s \c valueChanged() signal to the
\c{SlidersGroup}'s \c valueChanged() signal, to notify the other
widgets in the application (i.e., the control widgets) of the
changed value.
- \snippet widgets/sliders/slidersgroup.cpp 3
\codeline
\snippet widgets/sliders/slidersgroup.cpp 4
- Finally, depending on the \l {Qt::Orientation}{orientation} given
- at the time of construction, we choose and create the layout for
- the slider widgets within the group box.
+ Finally, we create the layout for the slider widgets within the
+ group box. We start with a horizontal arrangement of the sliders.
\snippet widgets/sliders/slidersgroup.cpp 5
\snippet widgets/sliders/slidersgroup.cpp 6
@@ -256,4 +227,12 @@
\l{QAbstractSlider::invertedAppearance}{invertedAppearance} and
\l{QAbstractSlider::invertedControls}{invertedControls}
properties.
+
+ \snippet widgets/sliders/slidersgroup.cpp 15
+
+ The setOrientation() slot controls the direction of the layout
+ and the orientation of the sliders. In a horizontal group, the
+ sliders have a horizontal orientation, and are laid out on top
+ of each other. In a vertical group, the sliders have a vertical
+ orientation, and are laid out next to each other.
*/
diff --git a/examples/widgets/doc/src/spinboxdelegate.qdoc b/examples/widgets/doc/src/spinboxdelegate.qdoc
deleted file mode 100644
index c234673eb7..0000000000
--- a/examples/widgets/doc/src/spinboxdelegate.qdoc
+++ /dev/null
@@ -1,141 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 itemviews/spinboxdelegate
- \title Spin Box Delegate Example
- \ingroup examples-itemviews
- \brief The Spin Box Delegate example shows how to create an editor for a custom delegate in
- the model/view framework by reusing a standard Qt editor widget.
-
- The model/view framework provides a standard delegate that is used by default
- with the standard view classes. For most purposes, the selection of editor
- widgets available through this delegate is sufficient for editing text, boolean
- values, and other simple data types. However, for specific data types, it is
- sometimes necessary to use a custom delegate to either display the data in a
- specific way, or allow the user to edit it with a custom control.
-
- \image spinboxdelegate-example.png
-
- This concepts behind this example are covered in the
- \l{Model/View Programming#Delegate Classes}{Delegate Classes} chapter
- of the \l{Model/View Programming} overview.
-
- \section1 SpinBoxDelegate Class Definition
-
- The definition of the delegate is as follows:
-
- \snippet itemviews/spinboxdelegate/delegate.h 0
-
- The delegate class declares only those functions that are needed to
- create an editor widget, display it at the correct location in a view,
- and communicate with a model. Custom delegates can also provide their
- own painting code by reimplementing the \c paintEvent() function.
- Furthermore it is also possible to reuse (and avoid deleting) the editor
- widget by reimplementing the \a destroyEditor() function. A reused widget
- could be a mutable member created in the constructor and deleted in
- the destructor.
-
- \section1 SpinBoxDelegate Class Implementation
-
- Delegates are often stateless. The constructor only needs to
- call the base class's constructor with the parent QObject as its
- argument:
-
- \snippet itemviews/spinboxdelegate/delegate.cpp 0
-
- Since the delegate is a subclass of QStyledItemDelegate, the data it retrieves
- from the model is displayed in a default style, and we do not need to
- provide a custom \c paintEvent().
-
- The \c createEditor() function returns an editor widget, in this case a
- spin box that restricts values from the model to integers from 0 to 100
- inclusive.
-
- \snippet itemviews/spinboxdelegate/delegate.cpp 1
-
- We install an event filter on the spin box to ensure that it behaves in
- a way that is consistent with other delegates. The implementation for
- the event filter is provided by the base class.
-
- The \c setEditorData() function reads data from the model, converts it
- to an integer value, and writes it to the editor widget.
-
- \snippet itemviews/spinboxdelegate/delegate.cpp 2
-
- Since the view treats delegates as ordinary QWidget instances, we have
- to use a static cast before we can set the value in the spin box.
-
- The \c setModelData() function reads the contents of the spin box, and
- writes it to the model.
-
- \snippet itemviews/spinboxdelegate/delegate.cpp 3
-
- We call \l{QSpinBox::interpretText()}{interpretText()} to make sure that
- we obtain the most up-to-date value in the spin box.
-
- The \c updateEditorGeometry() function updates the editor widget's
- geometry using the information supplied in the style option. This is the
- minimum that the delegate must do in this case.
-
- \snippet itemviews/spinboxdelegate/delegate.cpp 4
-
- More complex editor widgets may divide the rectangle available in
- \c{option.rect} between different child widgets if required.
-
- \section1 The Main Function
-
- This example is written in a slightly different way to many of the
- other examples supplied with Qt. To demonstrate the use of a custom
- editor widget in a standard view, it is necessary to set up a model
- containing some arbitrary data and a view to display it.
-
- We set up the application in the normal way, construct a standard item
- model to hold some data, set up a table view to use the data in the
- model, and construct a custom delegate to use for editing:
-
- \snippet itemviews/spinboxdelegate/main.cpp 0
-
- The table view is informed about the delegate, and will use it to
- display each of the items. Since the delegate is a subclass of
- QStyledItemDelegate, each cell in the table will be rendered using standard
- painting operations.
-
- We insert some arbitrary data into the model for demonstration purposes:
-
- \snippet itemviews/spinboxdelegate/main.cpp 1
- \snippet itemviews/spinboxdelegate/main.cpp 2
-
- Finally, the table view is displayed with a window title, and we start
- the application's event loop:
-
- \snippet itemviews/spinboxdelegate/main.cpp 3
-
- Each of the cells in the table can now be edited in the usual way, but
- the spin box ensures that the data returned to the model is always
- constrained by the values allowed by the spin box delegate.
-*/
diff --git a/examples/widgets/doc/src/spinboxes.qdoc b/examples/widgets/doc/src/spinboxes.qdoc
index 4478ce12d2..eb42696c48 100644
--- a/examples/widgets/doc/src/spinboxes.qdoc
+++ b/examples/widgets/doc/src/spinboxes.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example widgets/spinboxes
\title Spin Boxes Example
+ \examplecategory {User Interface Components}
\ingroup examples-widgets
\brief The Spin Boxes example shows how to use the many different types of
spin boxes available in Qt, from a simple QSpinBox widget to more complex
diff --git a/examples/widgets/doc/src/spreadsheet.qdoc b/examples/widgets/doc/src/spreadsheet.qdoc
index 392fbd0a16..02d5e0a957 100644
--- a/examples/widgets/doc/src/spreadsheet.qdoc
+++ b/examples/widgets/doc/src/spreadsheet.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example itemviews/spreadsheet
\title Spreadsheet
+ \examplecategory {User Interface Components}
\ingroup examples-itemviews
\brief The Spreadsheet example shows how to create a simple spreadsheet application.
diff --git a/examples/widgets/doc/src/standarddialogs.qdoc b/examples/widgets/doc/src/standarddialogs.qdoc
index 0a41f61c00..396f1d1044 100644
--- a/examples/widgets/doc/src/standarddialogs.qdoc
+++ b/examples/widgets/doc/src/standarddialogs.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example dialogs/standarddialogs
\title Standard Dialogs Example
+ \examplecategory {User Interface Components}
\ingroup examples-dialogs
\brief The Standard Dialogs example shows the standard dialogs that are provided by Qt.
diff --git a/examples/widgets/doc/src/stardelegate.qdoc b/examples/widgets/doc/src/stardelegate.qdoc
index f26424abaf..44d75e64f4 100644
--- a/examples/widgets/doc/src/stardelegate.qdoc
+++ b/examples/widgets/doc/src/stardelegate.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example itemviews/stardelegate
\title Star Delegate Example
+ \examplecategory {User Interface Components}
\ingroup examples-itemviews
\brief The Star Delegate example shows how to create a delegate that
can paint itself and that supports editing.
diff --git a/examples/widgets/doc/src/styleplugin.qdoc b/examples/widgets/doc/src/styleplugin.qdoc
deleted file mode 100644
index 5977633428..0000000000
--- a/examples/widgets/doc/src/styleplugin.qdoc
+++ /dev/null
@@ -1,138 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 tools/styleplugin
- \title Style Plugin Example
- \ingroup examples-widgets-tools
-
- \brief This example shows how to create a plugin that extends Qt with a new
- GUI look and feel.
-
- \image stylepluginexample.png
-
- A plugin in Qt is a class stored in a shared library that can be
- loaded by a QPluginLoader at run-time. When you create plugins in
- Qt, they either extend a Qt application or Qt itself. Writing a
- plugin that extends Qt itself is achieved by inheriting one of the
- plugin \l{Plugin Classes}{base classes}, reimplementing functions
- from that class, and adding a macro. In this example we extend Qt
- by adding a new GUI look and feel (i.e., making a new QStyle
- available). A high-level introduction to plugins is given in the
- plugin \l{How to Create Qt Plugins}{overview document}.
-
- Plugins that provide new styles inherit the QStylePlugin base
- class. Style plugins are loaded by Qt and made available through
- QStyleFactory; we will look at this later. We have implemented \c
- SimpleStylePlugin, which provides \c SimpleStyle. The new style
- contributes to widget styling by drawing button backgrounds in
- red - not a major contribution, but it still makes a new style.
-
- The new style is platform agnostic in the sense that it is not
- based on any specific style implementation, but uses QProxyStyle
- to merely tweak the looks in the current application style that
- defaults to the native system style.
-
- \note On some platforms, the native style will prevent the button
- from having a red background. In this case, try to run the example
- in another style (e.g., fusion).
-
- We test the plugin with \c StyleWindow, in which we display a
- QPushButton. The \c SimpleStyle and \c StyleWindow classes do not
- contain any plugin specific functionality and their implementations
- are trivial; we will therefore leap past them and head on to the \c
- SimpleStylePlugin and the \c main() function. After we have looked
- at that, we examine the plugin's profile.
-
-
- \section1 SimpleStylePlugin Class Definition
-
- \c SimpleStylePlugin inherits QStylePlugin and is the plugin
- class.
-
- \snippet tools/styleplugin/plugin/simplestyleplugin.h 0
-
- \c keys() returns a list of style names that this plugin can
- create, while \c create() takes such a string and returns the
- QStyle corresponding to the key. Both functions are pure virtual
- functions reimplemented from QStylePlugin. When an application
- requests an instance of the \c SimpleStyle style, which this
- plugin creates, Qt will create it with this plugin.
-
-
- \section1 SimpleStylePlugin Class Implementation
-
- Here is the implementation of \c keys():
-
- \snippet tools/styleplugin/plugin/simplestyleplugin.cpp 0
-
- Since this plugin only supports one style, we return a QStringList
- with the class name of that style.
-
- Here is the \c create() function:
-
- \snippet tools/styleplugin/plugin/simplestyleplugin.cpp 1
-
- Note that the key for style plugins are case insensitive.
- The case sensitivity varies from plugin to plugin, so you need to
- check this when implementing new plugins.
-
- \section1 The \c main() function
-
- \snippet tools/styleplugin/stylewindow/main.cpp 0
-
- Qt loads the available style plugins when the QApplication object
- is initialized. The QStyleFactory class knows about all styles and
- produces them with \l{QStyleFactory::}{create()} (it is a
- wrapper around all the style plugins).
-
- \section1 The Simple Style Plugin Profile
-
- The \c SimpleStylePlugin lives in its own directory and have
- its own profile:
-
- \snippet tools/styleplugin/plugin/plugin.pro 0
-
- In the plugin profile we need to set the lib template as we are
- building a shared library instead of an executable. We must also
- set the config to plugin. We set the library to be stored in the
- styles folder under stylewindow because this is a path in which Qt
- will search for style plugins.
-
- \section1 Related Articles and Examples
-
- In addition to the plugin \l{How to Create Qt Plugins}{overview
- document}, we have other examples and articles that concern
- plugins.
-
- In the \l{Echo Plugin Example}{echo plugin example} we show how to
- implement plugins that extends Qt applications rather than Qt
- itself, which is the case with the style plugin of this example.
- The \l{Plug & Paint Example}{plug & paint} example shows how to
- implement a static plugin as well as being a more involved example
- on plugins that extend applications.
-*/
diff --git a/examples/widgets/doc/src/styles.qdoc b/examples/widgets/doc/src/styles.qdoc
deleted file mode 100644
index 99575a84da..0000000000
--- a/examples/widgets/doc/src/styles.qdoc
+++ /dev/null
@@ -1,472 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/styles
- \title Styles Example
- \ingroup examples-widgets
- \brief The Styles example illustrates how to create custom widget
- drawing styles using Qt, and demonstrates Qt's predefined styles.
-
- \borderedimage styles-enabledwood.png
- \caption Screenshot of the Styles example
-
- A style in Qt is a subclass of QStyle or of one of its
- subclasses. Styles perform drawing on behalf of widgets. Qt
- provides a whole range of predefined styles, either built into
- the Qt Widgets module or found in plugins. Styles are usually
- customized by subclassing QProxyStyle and reimplementing a few
- virtual functions. While QProxyStyle provides a transparent way
- to customize either a specific style or the appropriate platform's
- default style, Qt also provides QCommonStyle as a convenient base
- for full custom style implementations.
-
- In this example, the custom style is called \c NorwegianWoodStyle
- and derives from QProxyStyle. Its main features are the wooden
- textures used for filling most of the widgets and its round
- buttons and comboboxes.
-
- To implement the style, we use some advanced features provided by
- QPainter, such as \l{QPainter::Antialiasing}{antialiasing} (to
- obtain smoother button edges), \l{QColor::alpha()}{alpha blending}
- (to make the buttons appeared raised or sunken), and
- \l{QPainterPath}{painter paths} (to fill the buttons and draw the
- outline). We also use many features of QBrush and QPalette.
-
- The example consists of the following classes:
-
- \list
- \li \c NorwegianWoodStyle inherits from QProxyStyle and implements
- the Norwegian Wood style.
- \li \c WidgetGallery is a \c QDialog subclass that shows the most
- common widgets and allows the user to switch style
- dynamically.
- \endlist
-
- \section1 NorwegianWoodStyle Class Definition
-
- Here's the definition of the \c NorwegianWoodStyle class:
-
- \snippet widgets/styles/norwegianwoodstyle.h 0
-
- The public functions are all declared in QStyle (QProxyStyle's
- grandparent class) and reimplemented here to override the Windows
- look and feel. The private functions are helper functions.
-
- \section1 NorwegianWoodStyle Class Implementation
-
- We will now review the implementation of the \c
- NorwegianWoodStyle class.
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 0
-
- 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.
-
- We start by defining a few \l{QColor}s that we'll need. Then we
- load two PNG images. The \c : prefix in the file path indicates
- that the PNG files are \l{The Qt Resource System}{embedded
- resources}.
-
- \table
- \row \li \inlineimage widgets/styles/images/woodbackground.png
-
- \li \b{woodbackground.png}
-
- This texture is used as the background of most widgets.
- The wood pattern is horizontal.
-
- \row \li \inlineimage widgets/styles/images/woodbutton.png
-
- \li \b{woodbutton.png}
-
- This texture is used for filling push buttons and
- comboboxes. The wood pattern is vertical and more reddish
- than the texture used for the background.
- \endtable
-
- The \c midImage variable is initialized to be the same as \c
- buttonImage, but then we use a QPainter and fill it with a 25%
- opaque black color (a black with an \l{QColor::alpha()}{alpha
- channel} of 63). The result is a somewhat darker image than \c
- buttonImage. This image will be used for filling buttons that the
- user is holding down.
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 1
-
- We initialize the palette. Palettes have various
- \l{QPalette::ColorRole}{color roles}, such as QPalette::Base
- (used for filling text editors, item views, etc.), QPalette::Text
- (used for foreground text), and QPalette::Window (used for
- the background of most widgets). Each role has its own QBrush,
- which usually is a plain color but can also be a brush pattern or
- even a texture (a QPixmap).
-
- In addition to the roles, palettes have several
- \l{QPalette::ColorGroup}{color groups}: active, disabled, and
- inactive. The active color group is used for painting widgets in
- the active window. The disabled group is used for disabled
- widgets. The inactive group is used for all other widgets. Most
- palettes have identical active and inactive groups, while the
- disabled group uses darker shades.
-
- We initialize the QPalette object with a brown color. Qt
- automatically derivates all color roles for all color groups from
- that single color. We then override some of the default values. For
- example, we use Qt::darkGreen instead of the default
- (Qt::darkBlue) for the QPalette::Highlight role. The
- QPalette::setBrush() overload that we use here sets the same
- color or brush for all three color groups.
-
- The \c setTexture() function is a private function that sets the
- texture for a certain color role, while preserving the existing
- color in the QBrush. A QBrush can hold both a solid color and a
- texture at the same time. The solid color is used for drawing
- text and other graphical elements where textures don't look good.
-
- At the end, we set the brush for the disabled color group of the
- palette. We use \c woodbackground.png as the texture for all
- disabled widgets, including buttons, and use a darker color to
- accompany the texture.
-
- \image styles-disabledwood.png The Norwegian Wood style with disabled widgets
-
- Let's move on to the other functions reimplemented from
- QProxyStyle:
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 3
- \snippet widgets/styles/norwegianwoodstyle.cpp 4
-
- This QStyle::polish() overload is called once on every widget
- drawn using the style. We reimplement it to set the Qt::WA_Hover
- attribute on \l{QPushButton}s and \l{QComboBox}es. When this
- attribute is set, Qt generates paint events when the mouse
- pointer enters or leaves the widget. This makes it possible to
- render push buttons and comboboxes differently when the mouse
- pointer is over them.
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 5
- \snippet widgets/styles/norwegianwoodstyle.cpp 6
-
- This QStyle::unpolish() overload is called to undo any
- modification done to the widget in \c polish(). For simplicity,
- we assume that the flag wasn't set before \c polish() was called.
- In an ideal world, we would remember the original state for each
- widgets (e.g., using a QMap<QWidget *, bool>) and restore it in
- \c unpolish().
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 7
- \snippet widgets/styles/norwegianwoodstyle.cpp 8
-
- The \l{QStyle::pixelMetric()}{pixelMetric()} function returns the
- size in pixels for a certain user interface element. By
- reimplementing this function, we can affect the way certain
- widgets are drawn and their size hint. Here, we return 8 as the
- width around a shown in a QComboBox, ensuring that there is
- enough place around the text and the arrow for the Norwegian Wood
- round corners. The default value for this setting in the Windows
- style is 2.
-
- We also change the extent of \l{QScrollBar}s, i.e., the height
- for a horizontal scroll bar and the width for a vertical scroll
- bar, to be 4 pixels more than in the Windows style. This makes the
- style a bit more distinctive.
-
- For all other QStyle::PixelMetric elements, we use the Windows
- settings.
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 9
- \snippet widgets/styles/norwegianwoodstyle.cpp 10
-
- The \l{QStyle::styleHint()}{styleHint()} function returns some
- hints to widgets or to the base style (in our case QProxyStyle)
- about how to draw the widgets. The Windows style returns \c true
- for the QStyle::SH_DitherDisabledText hint, resulting in a most
- unpleasing visual effect. We override this behavior and return \c
- false instead. We also return \c true for the
- QStyle::SH_EtchDisabledText hint, meaning that disabled text is
- rendered with an embossed look.
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 11
- \snippet widgets/styles/norwegianwoodstyle.cpp 12
-
- The \l{QStyle::drawPrimitive()}{drawPrimitive()} function is
- called by Qt widgets to draw various fundamental graphical
- elements. Here we reimplement it to draw QPushButton and
- QComboBox with round corners. The button part of these widgets is
- drawn using the QStyle::PE_PanelButtonCommand primitive element.
-
- The \c option parameter, of type QStyleOption, contains
- everything we need to know about the widget we want to draw on.
- In particular, \c option->rect gives the rectangle within which
- to draw the primitive element. The \c painter parameter is a
- QPainter object that we can use to draw on the widget.
-
- The \c widget parameter is the widget itself. Normally, all the
- information we need is available in \c option and \c painter, so
- we don't need \c widget. We can use it to perform special
- effects; for example, QMacStyle uses it to animate default
- buttons. If you use it, be aware that the caller is allowed to
- pass a null pointer.
-
- We start by defining three \l{QColor}s that we'll need later on.
- We also put the x, y, width, and height components of the
- widget's rectangle in local variables. The value used for the \c
- semiTransparentWhite and for the \c semiTransparentBlack color's
- alpha channel depends on whether the mouse cursor is over the
- widget or not. Since we set the Qt::WA_Hover attribute on
- \l{QPushButton}s and \l{QComboBox}es, we can rely on the
- QStyle::State_MouseOver flag to be set when the mouse is over the
- widget.
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 13
- \snippet widgets/styles/norwegianwoodstyle.cpp 14
-
- The \c roundRect variable is a QPainterPath. A QPainterPath is is
- a vectorial specification of a shape. Any shape (rectangle,
- ellipse, spline, etc.) or combination of shapes can be expressed
- as a path. We will use \c roundRect both for filling the button
- background with a wooden texture and for drawing the outline. The
- \c roundRectPath() function is a private function; we will come
- back to it later.
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 15
- \snippet widgets/styles/norwegianwoodstyle.cpp 16
- \snippet widgets/styles/norwegianwoodstyle.cpp 17
- \snippet widgets/styles/norwegianwoodstyle.cpp 18
-
- We define two variables, \c brush and \c darker, and initialize
- them based on the state of the button:
-
- \list
- \li If the button is a \l{QPushButton::flat}{flat button}, we use
- the \l{QPalette::Window}{Window} brush. We set \c
- darker to \c true if the button is
- \l{QAbstractButton::down}{down} or
- \l{QAbstractButton::checked}{checked}.
- \li If the button is currently held down by the user or in the
- \l{QAbstractButton::checked}{checked} state, we use the
- \l{QPalette::Mid}{Mid} component of the palette. We set
- \c darker to \c true if the button is
- \l{QAbstractButton::checked}{checked}.
- \li Otherwise, we use the \l{QPalette::Button}{Button} component
- of the palette.
- \endlist
-
- The screenshot below illustrates how \l{QPushButton}s are
- rendered based on their state:
-
- \image styles-woodbuttons.png Norwegian Wood buttons in different states
-
- To discover whether the button is flat or not, we need to cast
- the \c option parameter to QStyleOptionButton and check if the
- \l{QStyleOptionButton::features}{features} member specifies the
- QStyleOptionButton::Flat flag. The qstyleoption_cast() function
- performs a dynamic cast; if \c option is not a
- QStyleOptionButton, qstyleoption_cast() returns a null pointer.
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 19
- \snippet widgets/styles/norwegianwoodstyle.cpp 20
- \snippet widgets/styles/norwegianwoodstyle.cpp 21
- \snippet widgets/styles/norwegianwoodstyle.cpp 22
- \snippet widgets/styles/norwegianwoodstyle.cpp 23
-
- We turn on antialiasing on QPainter. Antialiasing is a technique
- that reduces the visual distortion that occurs when the edges of
- a shape are converted into pixels. For the Norwegian Wood style,
- we use it to obtain smoother edges for the round buttons.
-
- \image styles-aliasing.png Norwegian wood buttons with and without antialiasing
-
- The first call to QPainter::fillPath() draws the background of
- the button with a wooden texture. The second call to
- \l{QPainter::fillPath()}{fillPath()} paints the same area with a
- semi-transparent black color (a black color with an alpha channel
- of 63) to make the area darker if \c darker is true.
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 24
- \snippet widgets/styles/norwegianwoodstyle.cpp 25
-
- Next, we draw the outline. The top-left half of the outline and
- the bottom-right half of the outline are drawn using different
- \l{QPen}s to produce a 3D effect. Normally, the top-left half of
- the outline is drawn lighter whereas the bottom-right half is
- drawn darker, but if the button is
- \l{QAbstractButton::down}{down} or
- \l{QAbstractButton::checked}{checked}, we invert the two
- \l{QPen}s to give a sunken look to the button.
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 26
-
- We draw the top-left part of the outline by calling
- QPainter::drawPath() with an appropriate
- \l{QPainter::setClipRegion()}{clip region}. If the
- \l{QStyleOption::direction}{layout direction} is right-to-left
- instead of left-to-right, we swap the \c x1, \c x2, \c x3, and \c
- x4 variables to obtain correct results. On right-to-left desktop,
- the "light" comes from the top-right corner of the screen instead
- of the top-left corner; raised and sunken widgets must be drawn
- accordingly.
-
- The diagram below illustrates how 3D effects are drawn according
- to the layout direction. The area in red on the diagram
- corresponds to the \c topHalf polygon:
-
- \image styles-3d.png
-
- An easy way to test how a style looks in right-to-left mode is to
- pass the \c -reverse command-line option to the application. This
- option is recognized by the QApplication constructor.
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 32
- \snippet widgets/styles/norwegianwoodstyle.cpp 33
- \snippet widgets/styles/norwegianwoodstyle.cpp 34
-
- The bottom-right part of the outline is drawn in a similar
- fashion. Then we draw a one-pixel wide outline around the entire
- button, using the \l{QPalette::WindowText}{WindowText} component
- of the QPalette.
-
- This completes the QStyle::PE_PanelButtonCommand case of the \c
- switch statement. Other primitive elements are handled by the
- base style. Let's now turn to the other \c NorwegianWoodStyle
- member functions:
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 35
- \snippet widgets/styles/norwegianwoodstyle.cpp 36
-
- We reimplement QStyle::drawControl() to draw the text on a
- QPushButton in a bright color when the button is
- \l{QAbstractButton::down}{down} or
- \l{QAbstractButton::checked}{checked}.
-
- If the \c option parameter points to a QStyleOptionButton object
- (it normally should), we take a copy of the object and modify its
- \l{QStyleOption::palette}{palette} member to make the
- QPalette::ButtonText be the same as the QPalette::BrightText
- component (unless the widget is disabled).
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 37
- \snippet widgets/styles/norwegianwoodstyle.cpp 38
-
- The \c setTexture() function is a private function that sets the
- \l{QBrush::texture()}{texture} component of the \l{QBrush}es for
- 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 standardPalette.
-
- \snippet widgets/styles/norwegianwoodstyle.cpp 39
- \snippet widgets/styles/norwegianwoodstyle.cpp 40
-
- The \c roundRectPath() function is a private function that
- constructs a QPainterPath object for round buttons. The path
- consists of eight segments: four arc segments for the corners and
- four lines for the sides.
-
- With around 250 lines of code, we have a fully functional custom
- style based on one of the predefined styles. Custom styles can be
- used to provide a distinct look to an application or family of
- applications.
-
- \section1 WidgetGallery Class
-
- For completeness, we will quickly review the \c WidgetGallery
- class, which contains the most common Qt widgets and allows the
- user to change style dynamically. Here's the class definition:
-
- \snippet widgets/styles/widgetgallery.h 0
- \dots
- \snippet widgets/styles/widgetgallery.h 1
-
- Here's the \c WidgetGallery constructor:
-
- \snippet widgets/styles/widgetgallery.cpp 0
-
- We start by creating child widgets. The \uicontrol Style combobox is
- initialized with all the styles known to QStyleFactory, in
- addition to \c NorwegianWood. The \c create...() functions are
- private functions that set up the various parts of the \c
- WidgetGallery.
-
- \snippet widgets/styles/widgetgallery.cpp 1
- \snippet widgets/styles/widgetgallery.cpp 2
-
- We connect the \uicontrol Style combobox to the \c changeStyle()
- private slot, the \uicontrol{Use style's standard palette} check box to
- the \c changePalette() slot, and the \uicontrol{Disable widgets} check
- box to the child widgets'
- \l{QWidget::setDisabled()}{setDisabled()} slot.
-
- \snippet widgets/styles/widgetgallery.cpp 3
- \snippet widgets/styles/widgetgallery.cpp 4
-
- Finally, we put the child widgets in layouts.
-
- \snippet widgets/styles/widgetgallery.cpp 5
- \snippet widgets/styles/widgetgallery.cpp 6
-
- When the user changes the style in the combobox, we call
- QApplication::setStyle() to dynamically change the style of the
- application.
-
- \snippet widgets/styles/widgetgallery.cpp 7
- \snippet widgets/styles/widgetgallery.cpp 8
-
- If the user turns the \uicontrol{Use style's standard palette} on, the
- current style's \l{QStyle::standardPalette()}{standard palette}
- is used; otherwise, the system's default palette is honored.
-
- \snippet widgets/styles/widgetgallery.cpp 9
- \snippet widgets/styles/widgetgallery.cpp 10
-
- The \c advanceProgressBar() slot is called at regular intervals
- to advance the progress bar. Since we don't know how long the
- user will keep the Styles application running, we use a
- logarithmic formula: The closer the progress bar gets to 100%,
- the slower it advances.
-
- We will review \c createProgressBar() in a moment.
-
- \snippet widgets/styles/widgetgallery.cpp 11
- \snippet widgets/styles/widgetgallery.cpp 12
-
- The \c createTopLeftGroupBox() function creates the QGroupBox
- that occupies the top-left corner of the \c WidgetGallery. We
- skip the \c createTopRightGroupBox(), \c
- createBottomLeftTabWidget(), and \c createBottomRightGroupBox()
- functions, which are very similar.
-
- \snippet widgets/styles/widgetgallery.cpp 13
-
- In \c createProgressBar(), we create a QProgressBar at the bottom
- of the \c WidgetGallery and connect its
- \l{QTimer::timeout()}{timeout()} signal to the \c
- advanceProgressBar() slot.
-*/
diff --git a/examples/widgets/doc/src/stylesheet.qdoc b/examples/widgets/doc/src/stylesheet.qdoc
deleted file mode 100644
index b51f1bed41..0000000000
--- a/examples/widgets/doc/src/stylesheet.qdoc
+++ /dev/null
@@ -1,88 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/stylesheet
- \title Style Sheet Example
- \ingroup examples-widgets
- \brief The Style Sheet Example shows how to use style sheets.
-
- \borderedimage stylesheet-pagefold.png
- \caption Screen Shot of the Pagefold style sheet
-
- The Style Sheet example shows how widgets can be styled using Qt Style Sheets.
- You can open the style editor by selecting \uicontrol File > \uicontrol Edit Style Sheet,
- to select an existing style sheet or design your own style and load it.
-
- The Style Sheet example consists of 2 classes:
- \list
- \li \c MainWindow
- \li \c StyleSheetEditor
- \endlist
-
-
- \section1 MainWindow Class
-
- \c MainWindow inherits QWidget, and is the application's main window defined in
- \c mainwindow.ui. The style of \c MainWindow can be modified with \c StyleSheetEditor.
-
-
- \section1 StyleSheetEditor Class
-
- \c StyleSheetEditor enables you to open an editor where you can load an existing style sheet.
- It is also possible to define a new stylesheet and load it. Its layout is defined in
- \c stylesheeteditor.ui.
-
- \quotefromfile widgets/stylesheet/stylesheeteditor.cpp
- \skipto setStyleName
- \printline setStyleName
-
- Sets the specified \a styleName and grays the \c applyButton.
-
- \skipto setStyleSheetName
- \printline setStyleSheetName
-
- Loads the stylesheet from \c styleSheetName.
-
- \skipto setModified()
- \printline setModified()
-
- Enables the \c applyButton when the text in the buffer has changed.
-
- \skipto apply()
- \printline apply()
-
- Sets the stylesheet properties in \l qApp and disables the \c applyButton.
-
- \skipto loadStyleSheet(const QString &sheetName)
- \printline loadStyleSheet(const QString &sheetName)
-
- Loads the specified \a sheetName, and sets its properties in
- \l qApp.
-
-*/
-
diff --git a/examples/widgets/doc/src/syntaxhighlighter.qdoc b/examples/widgets/doc/src/syntaxhighlighter.qdoc
index 30dc685843..17bcc1fa06 100644
--- a/examples/widgets/doc/src/syntaxhighlighter.qdoc
+++ b/examples/widgets/doc/src/syntaxhighlighter.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example richtext/syntaxhighlighter
\title Syntax Highlighter Example
+ \examplecategory {User Interface Components}
\ingroup examples-richtext
\brief The Syntax Highlighter example shows how to perform
simple syntax highlighting.
@@ -243,10 +220,4 @@
function. The QSyntaxHighlighter class also provides the \l
{QSyntaxHighlighter::document()}{document()} function which
returns the currently set document.
-
- \section1 Other Code Editor Features
-
- The \l{Code Editor Example} shows how to implement line
- numbers and how to highlight the current line.
-
*/
diff --git a/examples/widgets/doc/src/tabdialog.qdoc b/examples/widgets/doc/src/tabdialog.qdoc
index 4a30f51e73..fb45bbae04 100644
--- a/examples/widgets/doc/src/tabdialog.qdoc
+++ b/examples/widgets/doc/src/tabdialog.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example dialogs/tabdialog
\title Tab Dialog Example
+ \examplecategory {User Interface Components}
\ingroup examples-dialogs
\brief The Tab Dialog example shows how to construct a tab dialog using the
diff --git a/examples/widgets/doc/src/tablet.qdoc b/examples/widgets/doc/src/tablet.qdoc
index a10846fed4..9d49d8dec8 100644
--- a/examples/widgets/doc/src/tablet.qdoc
+++ b/examples/widgets/doc/src/tablet.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example widgets/tablet
\title Tablet Example
+ \examplecategory {User Interface Components}
\ingroup examples-widgets
\brief This example shows how to use a Wacom tablet in Qt applications.
@@ -37,7 +14,7 @@
generated. You need to reimplement the \l{QWidget::}{tabletEvent()} event
handler if you want to handle tablet events. Events are generated when the
tool (stylus) used for drawing enters and leaves the proximity of the
- tablet (i.e., when it is close but not pressed down on it), when the tool
+ tablet (i.e., when it is closed but not pressed down on it), when the tool
is pressed down and released from it, when the tool is moved across the
tablet, and when one of the buttons on the tool is pressed or released.
@@ -55,7 +32,7 @@
draw on the tablet as you use a pencil on paper. When you draw with the
airbrush you get a spray of virtual paint; the finger wheel is used to
change the density of the spray. When you draw with the art pen, you get a
- a line whose width and endpoint angle depend on the rotation of the pen.
+ line whose width and endpoint angle depend on the rotation of the pen.
The pressure and tilt can also be assigned to change the alpha and
saturation values of the color and the width of the stroke.
@@ -112,8 +89,6 @@
in a submenu of the \b Tablet menu, for selecting which property of each
QTabletEvent will be used to vary the translucency (alpha channel) of the
line being drawn or color being airbrushed.
- (See the \l{Qt Widgets - Application Example}{application example} if you want
- a high-level introduction to QActions.)
\snippet widgets/tablet/mainwindow.cpp 9
@@ -329,7 +304,7 @@
receive tablet proximity events and forward them to \c TabletCanvas.
The \c TabletEnterProximity and \c TabletLeaveProximity events are sent to
the QApplication object, while other tablet events are sent to the QWidget's
- \c event() hander, which sends them on to \l{QWidget::}{tabletEvent()}.
+ \c event() handler, which sends them on to \l{QWidget::}{tabletEvent()}.
\section1 TabletApplication Class Implementation
diff --git a/examples/widgets/doc/src/tetrix.qdoc b/examples/widgets/doc/src/tetrix.qdoc
deleted file mode 100644
index ddcf95013b..0000000000
--- a/examples/widgets/doc/src/tetrix.qdoc
+++ /dev/null
@@ -1,431 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/tetrix
- \title Tetrix Example
- \ingroup examples-widgets
- \brief The Tetrix example is a Qt version of the classic Tetrix game.
-
- \borderedimage tetrix-example.png
-
- The object of the game is to stack pieces dropped from the top of the
- playing area so that they fill entire rows at the bottom of the playing area.
-
- When a row is filled, all the blocks on that row are removed, the player earns
- a number of points, and the pieces above are moved down to occupy that row.
- If more than one row is filled, the blocks on each row are removed, and the
- player earns extra points.
-
- The \uicontrol{Left} cursor key moves the current piece one space to the left, the
- \uicontrol{Right} cursor key moves it one space to the right, the \uicontrol{Up} cursor
- key rotates the piece counter-clockwise by 90 degrees, and the \uicontrol{Down}
- cursor key rotates the piece clockwise by 90 degrees.
-
- To avoid waiting for a piece to fall to the bottom of the board, press \uicontrol{D}
- to immediately move the piece down by one row, or press the \uicontrol{Space} key to
- drop it as close to the bottom of the board as possible.
-
- This example shows how a simple game can be created using only three classes:
-
- \list
- \li The \c TetrixWindow class is used to display the player's score, number of
- lives, and information about the next piece to appear.
- \li The \c TetrixBoard class contains the game logic, handles keyboard input, and
- displays the pieces on the playing area.
- \li The \c TetrixPiece class contains information about each piece.
- \endlist
-
- In this approach, the \c TetrixBoard class is the most complex class, since it
- handles the game logic and rendering. One benefit of this is that the
- \c TetrixWindow and \c TetrixPiece classes are very simple and contain only a
- minimum of code.
-
- \section1 TetrixWindow Class Definition
-
- The \c TetrixWindow class is used to display the game information and contains
- the playing area:
-
- \snippet widgets/tetrix/tetrixwindow.h 0
-
- We use private member variables for the board, various display widgets, and
- buttons to allow the user to start a new game, pause the current game, and quit.
-
- Although the window inherits QWidget, the constructor does not provide an
- argument to allow a parent widget to be specified. This is because the window
- will always be used as a top-level widget.
-
- \section1 TetrixWindow Class Implementation
-
- The constructor sets up the user interface elements for the game:
-
- \snippet widgets/tetrix/tetrixwindow.cpp 0
-
- We begin by constructing a \c TetrixBoard instance for the playing area and a
- label that shows the next piece to be dropped into the playing area; the label
- is initially empty.
-
- Three QLCDNumber objects are used to display the score, number of lives, and
- lines removed. These initially show default values, and will be filled in
- when a game begins:
-
- \snippet widgets/tetrix/tetrixwindow.cpp 1
-
- Three buttons with shortcuts are constructed so that the user can start a
- new game, pause the current game, and quit the application:
-
- \snippet widgets/tetrix/tetrixwindow.cpp 2
- \snippet widgets/tetrix/tetrixwindow.cpp 3
-
- These buttons are configured so that they never receive the keyboard focus;
- we want the keyboard focus to remain with the \c TetrixBoard instance so that
- it receives all the keyboard events. Nonetheless, the buttons will still respond
- to \uicontrol{Alt} key shortcuts.
-
- We connect \l{QAbstractButton::}{clicked()} signals from the \uicontrol{Start}
- and \uicontrol{Pause} buttons to the board, and from the \uicontrol{Quit} button to the
- application's \l{QCoreApplication::quit()} slot.
-
- \snippet widgets/tetrix/tetrixwindow.cpp 4
- \snippet widgets/tetrix/tetrixwindow.cpp 5
-
- Signals from the board are also connected to the LCD widgets for the purpose of
- updating the score, number of lives, and lines removed from the playing area.
-
- We place the label, LCD widgets, and the board into a QGridLayout
- along with some labels that we create with the \c createLabel() convenience
- function:
-
- \snippet widgets/tetrix/tetrixwindow.cpp 6
-
- Finally, we set the grid layout on the widget, give the window a title, and
- resize it to an appropriate size.
-
- The \c createLabel() convenience function simply creates a new label on the
- heap, gives it an appropriate alignment, and returns it to the caller:
-
- \snippet widgets/tetrix/tetrixwindow.cpp 7
-
- Since each label will be used in the widget's layout, it will become a child
- of the \c TetrixWindow widget and, as a result, it will be deleted when the
- window is deleted.
-
- \section1 TetrixPiece Class Definition
-
- The \c TetrixPiece class holds information about a piece in the game's
- playing area, including its shape, position, and the range of positions it can
- occupy on the board:
-
- \snippet widgets/tetrix/tetrixpiece.h 0
-
- Each shape contains four blocks, and these are defined by the \c coords private
- member variable. Additionally, each piece has a high-level description that is
- stored internally in the \c pieceShape variable.
-
- The constructor is written inline in the definition, and simply ensures that
- each piece is initially created with no shape. The \c shape() function simply
- returns the contents of the \c pieceShape variable, and the \c x() and \c y()
- functions return the x and y-coordinates of any given block in the shape.
-
- \section1 TetrixPiece Class Implementation
-
- The \c setRandomShape() function is used to select a random shape for a piece:
-
- \snippet widgets/tetrix/tetrixpiece.cpp 0
-
- For convenience, it simply chooses a random shape from the \c TetrixShape enum
- and calls the \c setShape() function to perform the task of positioning the
- blocks.
-
- The \c setShape() function uses a look-up table of pieces to associate each
- shape with an array of block positions:
-
- \snippet widgets/tetrix/tetrixpiece.cpp 1
- \snippet widgets/tetrix/tetrixpiece.cpp 2
-
- These positions are read from the table into the piece's own array of positions,
- and the piece's internal shape information is updated to use the new shape.
-
- The \c x() and \c y() functions are implemented inline in the class definition,
- returning positions defined on a grid that extends horizontally and vertically
- with coordinates from -2 to 2. Although the predefined coordinates for each
- piece only vary horizontally from -1 to 1 and vertically from -1 to 2, each
- piece can be rotated by 90, 180, and 270 degrees.
-
- The \c minX() and \c maxX() functions return the minimum and maximum horizontal
- coordinates occupied by the blocks that make up the piece:
-
- \snippet widgets/tetrix/tetrixpiece.cpp 3
- \snippet widgets/tetrix/tetrixpiece.cpp 4
-
- Similarly, the \c minY() and \c maxY() functions return the minimum and maximum
- vertical coordinates occupied by the blocks:
-
- \snippet widgets/tetrix/tetrixpiece.cpp 5
- \snippet widgets/tetrix/tetrixpiece.cpp 6
-
- The \c rotatedLeft() function returns a new piece with the same shape as an
- existing piece, but rotated counter-clockwise by 90 degrees:
-
- \snippet widgets/tetrix/tetrixpiece.cpp 7
-
- Similarly, the \c rotatedRight() function returns a new piece with the same
- shape as an existing piece, but rotated clockwise by 90 degrees:
-
- \snippet widgets/tetrix/tetrixpiece.cpp 9
-
- These last two functions enable each piece to create rotated copies of itself.
-
- \section1 TetrixBoard Class Definition
-
- The \c TetrixBoard class inherits from QFrame and contains the game logic and display features:
-
- \snippet widgets/tetrix/tetrixboard.h 0
-
- Apart from the \c setNextPieceLabel() function and the \c start() and \c pause()
- public slots, we only provide public functions to reimplement QWidget::sizeHint()
- and QWidget::minimumSizeHint(). The signals are used to communicate changes to
- the player's information to the \c TetrixWindow instance.
-
- The rest of the functionality is provided by reimplementations of protected event
- handlers and private functions:
-
- \snippet widgets/tetrix/tetrixboard.h 1
-
- The board is composed of a fixed-size array whose elements correspond to
- spaces for individual blocks. Each element in the array contains a \c TetrixShape
- value corresponding to the type of shape that occupies that element.
-
- Each shape on the board will occupy four elements in the array, and these will
- all contain the enum value that corresponds to the type of the shape.
-
- We use a QBasicTimer to control the rate at which pieces fall toward the bottom
- of the playing area. This allows us to provide an implementation of
- \l{QObject::}{timerEvent()} that we can use to update the widget.
-
- \section1 TetrixBoard Class Implementation
-
- In the constructor, we customize the frame style of the widget, ensure that
- keyboard input will be received by the widget by using Qt::StrongFocus for the
- focus policy, and initialize the game state:
-
- \snippet widgets/tetrix/tetrixboard.cpp 0
-
- The first (next) piece is also set up with a random shape.
-
- The \c setNextPieceLabel() function is used to pass in an externally-constructed
- label to the board, so that it can be shown alongside the playing area:
-
- \snippet widgets/tetrix/tetrixboard.cpp 1
-
- We provide a reasonable size hint and minimum size hint for the board, based on
- the size of the space for each block in the playing area:
-
- \snippet widgets/tetrix/tetrixboard.cpp 2
- \snippet widgets/tetrix/tetrixboard.cpp 3
-
- By using a minimum size hint, we indicate to the layout in the parent widget
- that the board should not shrink below a minimum size.
-
- A new game is started when the \c start() slot is called. This resets the
- game's state, the player's score and level, and the contents of the board:
-
- \snippet widgets/tetrix/tetrixboard.cpp 4
-
- We also emit signals to inform other components of these changes before creating
- a new piece that is ready to be dropped into the playing area. We start the
- timer that determines how often the piece drops down one row on the board.
-
- The \c pause() slot is used to temporarily stop the current game by stopping the
- internal timer:
-
- \snippet widgets/tetrix/tetrixboard.cpp 5
- \snippet widgets/tetrix/tetrixboard.cpp 6
-
- We perform checks to ensure that the game can only be paused if it is already
- running and not already paused.
-
- The \c paintEvent() function is straightforward to implement. We begin by
- calling the base class's implementation of \l{QWidget::}{paintEvent()} before
- constructing a QPainter for use on the board:
-
- \snippet widgets/tetrix/tetrixboard.cpp 7
-
- Since the board is a subclass of QFrame, we obtain a QRect that covers the area
- \e inside the frame decoration before drawing our own content.
-
- If the game is paused, we want to hide the existing state of the board and
- show some text. We achieve this by painting text onto the widget and returning
- early from the function. The rest of the painting is performed after this point.
-
- The position of the top of the board is found by subtracting the total height
- of each space on the board from the bottom of the frame's internal rectangle.
- For each space on the board that is occupied by a piece, we call the
- \c drawSquare() function to draw a block at that position.
-
- \snippet widgets/tetrix/tetrixboard.cpp 8
- \snippet widgets/tetrix/tetrixboard.cpp 9
-
- Spaces that are not occupied by blocks are left blank.
-
- Unlike the existing pieces on the board, the current piece is drawn
- block-by-block at its current position:
-
- \snippet widgets/tetrix/tetrixboard.cpp 10
- \snippet widgets/tetrix/tetrixboard.cpp 11
- \snippet widgets/tetrix/tetrixboard.cpp 12
-
- The \c keyPressEvent() handler is called whenever the player presses a key while
- the \c TetrixBoard widget has the keyboard focus.
-
- \snippet widgets/tetrix/tetrixboard.cpp 13
-
- If there is no current game, the game is running but paused, or if there is no
- current shape to control, we simply pass on the event to the base class.
-
- We check whether the event is about any of the keys that the player uses to
- control the current piece and, if so, we call the relevant function to handle
- the input:
-
- \snippet widgets/tetrix/tetrixboard.cpp 14
-
- In the case where the player presses a key that we are not interested in, we
- again pass on the event to the base class's implementation of
- \l{QWidget::}{keyPressEvent()}.
-
- The \c timerEvent() handler is called every time the class's QBasicTimer
- instance times out. We need to check that the event we receive corresponds to
- our timer. If it does, we can update the board:
-
- \snippet widgets/tetrix/tetrixboard.cpp 15
- \snippet widgets/tetrix/tetrixboard.cpp 16
- \snippet widgets/tetrix/tetrixboard.cpp 17
-
- If a row (or line) has just been filled, we create a new piece and reset the
- timer; otherwise we move the current piece down by one row. We let the base
- class handle other timer events that we receive.
-
- The \c clearBoard() function simply fills the board with the
- \c TetrixShape::NoShape value:
-
- \snippet widgets/tetrix/tetrixboard.cpp 18
-
- The \c dropDown() function moves the current piece down as far as possible on
- the board, either until it is touching the bottom of the playing area or it is
- stacked on top of another piece:
-
- \snippet widgets/tetrix/tetrixboard.cpp 19
- \snippet widgets/tetrix/tetrixboard.cpp 20
-
- The number of rows the piece has dropped is recorded and passed to the
- \c pieceDropped() function so that the player's score can be updated.
-
- The \c oneLineDown() function is used to move the current piece down by one row
- (line), either when the user presses the \uicontrol{D} key or when the piece is
- scheduled to move:
-
- \snippet widgets/tetrix/tetrixboard.cpp 21
-
- If the piece cannot drop down by one line, we call the \c pieceDropped() function
- with zero as the argument to indicate that it cannot fall any further, and that
- the player should receive no extra points for the fall.
-
- The \c pieceDropped() function itself is responsible for awarding points to the
- player for positioning the current piece, checking for full rows on the board
- and, if no lines have been removed, creating a new piece to replace the current
- one:
-
- \snippet widgets/tetrix/tetrixboard.cpp 22
- \snippet widgets/tetrix/tetrixboard.cpp 23
-
- We call \c removeFullLines() each time a piece has been dropped. This scans
- the board from bottom to top, looking for blank spaces on each row.
-
- \snippet widgets/tetrix/tetrixboard.cpp 24
- \snippet widgets/tetrix/tetrixboard.cpp 25
- \snippet widgets/tetrix/tetrixboard.cpp 26
- \snippet widgets/tetrix/tetrixboard.cpp 27
-
- If a row contains no blank spaces, the rows above it are copied down by one row
- to compress the stack of pieces, the top row on the board is cleared, and the
- number of full lines found is incremented.
-
- \snippet widgets/tetrix/tetrixboard.cpp 28
- \snippet widgets/tetrix/tetrixboard.cpp 29
-
- If some lines have been removed, the player's score and the total number of lines
- removed are updated. The \c linesRemoved() and \c scoreChanged() signals are
- emitted to send these new values to other widgets in the window.
-
- Additionally, we set the timer to elapse after half a second, set the
- \c isWaitingAfterLine flag to indicate that lines have been removed, unset
- the piece's shape to ensure that it is not drawn, and update the widget.
- The next time that the \c timerEvent() handler is called, a new piece will be
- created and the game will continue.
-
- The \c newPiece() function places the next available piece at the top of the
- board, and creates a new piece with a random shape:
-
- \snippet widgets/tetrix/tetrixboard.cpp 30
- \snippet widgets/tetrix/tetrixboard.cpp 31
-
- We place a new piece in the middle of the board at the top. The game is over if
- the piece can't move, so we unset its shape to prevent it from being drawn, stop
- the timer, and unset the \c isStarted flag.
-
- The \c showNextPiece() function updates the label that shows the next piece to
- be dropped:
-
- \snippet widgets/tetrix/tetrixboard.cpp 32
- \snippet widgets/tetrix/tetrixboard.cpp 33
-
- We draw the piece's component blocks onto a pixmap that is then set on the label.
-
- The \c tryMove() function is used to determine whether a piece can be positioned
- at the specified coordinates:
-
- \snippet widgets/tetrix/tetrixboard.cpp 34
-
- We examine the spaces on the board that the piece needs to occupy and, if they
- are already occupied by other pieces, we return \c false to indicate that the
- move has failed.
-
- \snippet widgets/tetrix/tetrixboard.cpp 35
-
- If the piece could be placed on the board at the desired location, we update the
- current piece and its position, update the widget, and return \c true to indicate
- success.
-
- The \c drawSquare() function draws the blocks (normally squares) that make up
- each piece using different colors for pieces with different shapes:
-
- \snippet widgets/tetrix/tetrixboard.cpp 36
-
- We obtain the color to use from a look-up table that relates each shape to an
- RGB value, and use the painter provided to draw the block at the specified
- coordinates.
-*/
diff --git a/examples/widgets/doc/src/textedit.qdoc b/examples/widgets/doc/src/textedit.qdoc
deleted file mode 100644
index 8f4f8a5ac4..0000000000
--- a/examples/widgets/doc/src/textedit.qdoc
+++ /dev/null
@@ -1,39 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 richtext/textedit
- \title Text Edit
- \ingroup examples-richtext
- \brief The Text Edit example shows Qt's rich text editing facilities
- in action.
-
- \brief The Text Edit example shows Qt's rich text editing facilities in action,
- providing an example document for you to experiment with.
-
- \image textedit-demo.png
-*/
diff --git a/examples/widgets/doc/src/tooltips.qdoc b/examples/widgets/doc/src/tooltips.qdoc
deleted file mode 100644
index a278215503..0000000000
--- a/examples/widgets/doc/src/tooltips.qdoc
+++ /dev/null
@@ -1,394 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/tooltips
- \title Tool Tips Example
- \ingroup examples-widgets
- \brief The Tool Tips example shows how to provide static and dynamic tool
- tips for an application's widgets.
-
- The simplest and most common way to set a widget's tool tip is by
- calling its QWidget::setToolTip() function (static tool
- tips). Then the tool tip is shown whenever the cursor points at
- the widget. We show how to do this with our application's tool
- buttons. But it is also possible to show different tool tips
- depending on the cursor's position (dynamic tooltips). This
- approach uses mouse tracking and event handling to determine what
- widgets are located under the cursor at any point in time, and
- displays their tool tips. The tool tips for the shape items in our
- application are implemented using the latter approach.
-
- \image tooltips-example.png
-
- With the \c Tooltips application the user can create new shape
- items with the provided tool buttons, and move the items around
- using the mouse. Tooltips are provided whenever the cursor is
- pointing to a shape item or one of the buttons.
-
- The Tooltips example consists of two classes:
-
- \list
- \li \c ShapeItem is a custom widget representing one single shape item.
- \li \c SortingBox inherits from QWidget and is the application's main
- widget.
- \endlist
-
- First we will review the \c SortingBox class, then we will take a
- look at the \c ShapeItem class.
-
- \section1 SortingBox Class Definition
-
- \snippet widgets/tooltips/sortingbox.h 0
-
- The \c SortingBox class inherits QWidget, and it is the Tooltips
- application's main widget. We reimplement several of the event
- handlers.
-
- The \c event() function provides tooltips, the \c resize()
- function makes sure the application appears consistently when the
- user resizes the main widget, and the \c paintEvent() function
- displays the shape items within the \c SortingBox widget. The
- mouse event handlers are reimplemented to make the user able to
- move the items around.
-
- In addition we need three private slots to make the user able to
- create new shape items.
-
- \snippet widgets/tooltips/sortingbox.h 1
-
- We also create several private functions: We use the \c
- initialItemPosition(), \c initialItemColor() and \c
- createToolButton() functions when we are constructing the widget,
- and we use the \c updateButtonGeometry() function whenever the
- user is resizing the application's main widget.
-
- The \c itemAt() function determines if there is a shape item at a
- particular position, and the \c moveItemTo() function moves an
- item to a new position. We use the \c createShapeItem(), \c
- randomItemPosition() and \c randomItemColor() functions to create
- new shape items.
-
- \snippet widgets/tooltips/sortingbox.h 2
-
- We keep all the shape items in a QList, and we keep three
- QPainterPath objects holding the shapes of a circle, a square and
- a triangle. We also need to have a pointer to an item when it is
- moving, and we need to know its previous position.
-
- \section1 SortingBox Class Implementation
-
- \snippet widgets/tooltips/sortingbox.cpp 0
-
- In the constructor, we first set the Qt::WA_StaticContents
- attribute on the widget. This attribute indicates that the widget
- contents are north-west aligned and static. On resize, such a
- widget will receive paint events only for the newly visible part
- of itself.
-
- \snippet widgets/tooltips/sortingbox.cpp 1
-
- To be able to show the appropriate tooltips while the user is
- moving the cursor around, we need to enable mouse tracking for the
- widget.
-
- If mouse tracking is disabled (the default), the widget only
- receives mouse move events when at least one mouse button is
- pressed while the mouse is being moved. If mouse tracking is
- enabled, the widget receives mouse move events even if no buttons
- are pressed.
-
- \snippet widgets/tooltips/sortingbox.cpp 2
-
- A widget's background role defines the brush from the widget's
- palette that is used to render the background, and QPalette::Base
- is typically white.
-
- \snippet widgets/tooltips/sortingbox.cpp 3
-
- After creating the application's tool buttons using the private \c
- createToolButton() function, we construct the shapes of a circle,
- a square and a triangle using QPainterPath.
-
- The QPainterPath class provides a container for painting
- operations, enabling graphical shapes to be constructed and
- reused. The main advantage of painter paths over normal drawing
- operations is that complex shapes only need to be created once,
- but they can be drawn many times using only calls to
- QPainter::drawPath().
-
- \snippet widgets/tooltips/sortingbox.cpp 4
-
- Then we set the window title, resize the widget to a suitable
- size, and finally create three initial shape items using the
- private \c createShapeItem(), \c initialItemPosition() and \c
- initialItemColor() functions.
-
- \snippet widgets/tooltips/sortingbox.cpp 5
-
- QWidget::event() is the main event handler and receives all the
- widget's events. Normally, we recommend reimplementing one of the
- specialized event handlers instead of this function. But here we
- want to catch the QEvent::ToolTip events, and since these are
- rather rare, there exists no specific event handler. For that
- reason we reimplement the main event handler, and the first thing
- we need to do is to determine the event's type:
-
- \snippet widgets/tooltips/sortingbox.cpp 6
-
- If the type is QEvent::ToolTip, we cast the event to a QHelpEvent,
- otherwise we propagate the event using the QWidget::event()
- function.
-
- The QHelpEvent class provides an event that is used to request
- helpful information about a particular point in a widget.
-
- For example, the QHelpEvent::pos() function returns the event's
- position relative to the widget to which the event is dispatched.
- Here we use this information to determine if the position of the
- event is contained within the area of any of the shape items. If
- it is, we display the shape item's tooltip at the position of the
- event. If not, we hide the tooltip and explicitly ignore the event.
- This makes sure that the calling code does not start any tooltip
- specific modes as a result of the event. Note that the
- QToolTip::showText() function needs the event's position in global
- coordinates provided by QHelpEvent::globalPos().
-
- \snippet widgets/tooltips/sortingbox.cpp 7
-
- The \c resizeEvent() function is reimplemented to receive the
- resize events dispatched to the widget. It makes sure that the
- tool buttons keep their position relative to the main widget when
- the widget is resized. We want the buttons to always be vertically
- aligned in the application's bottom right corner, so each time the
- main widget is resized we update the buttons geometry.
-
- \snippet widgets/tooltips/sortingbox.cpp 8
-
- The \c paintEvent() function is reimplemented to receive paint
- events for the widget. We create a QPainter for the \c SortingBox
- widget, and run through the list of created shape items, drawing
- each item at its defined position.
-
- \snippet widgets/tooltips/sortingbox.cpp 9
-
- The painter will by default draw all the shape items at position
- (0,0) in the \c SortingBox widget. The QPainter::translate()
- function translates the coordinate system by the given offset,
- making each shape item appear at its defined position. But
- remember to translate the coordinate system back when the item is
- drawn, otherwise the next shape item will appear at a position
- relative to the item we drawed last.
-
- \snippet widgets/tooltips/sortingbox.cpp 10
-
- The QPainter::setBrush() function sets the current brush used by
- the painter. When the provided argument is a QColor, the function
- calls the appropriate QBrush constructor which creates a brush with
- the specified color and Qt::SolidPattern style. The
- QPainter::drawPath() function draws the given path using the
- current pen for outline and the current brush for filling.
-
- \snippet widgets/tooltips/sortingbox.cpp 11
-
- The \c mousePressEvent() function is reimplemented to receive the
- mouse press events dispatched to the widget. It determines if an
- event's position is contained within the area of any of the shape
- items, using the private \c itemAt() function.
-
- If an item covers the position, we store a pointer to that item
- and the event's position. If several of the shape items cover the
- position, we store the pointer to the uppermost item. Finally, we
- move the shape item to the end of the list, and make a call to the
- QWidget::update() function to make the item appear on top.
-
- The QWidget::update() function does not cause an immediate
- repaint; instead it schedules a paint event for processing when Qt
- returns to the main event loop.
-
- \snippet widgets/tooltips/sortingbox.cpp 12
-
- The \c mouseMoveEvent() function is reimplemented to receive mouse
- move events for the widget. If the left mouse button is pressed
- and there exists a shape item in motion, we use the private \c
- moveItemTo() function to move the item with an offset
- corresponding to the offset between the positions of the current
- mouse event and the previous one.
-
- \snippet widgets/tooltips/sortingbox.cpp 13
-
- The \c mouseReleaseEvent() function is reimplemented to receive
- the mouse release events dispatched to the widget. If the left
- mouse button is pressed and there exists a shape item in motion,
- we use the private \c moveItemTo() function to move the item like
- we did in \c mouseMoveEvent(). But then we remove the pointer to
- the item in motion, making the shape item's position final for
- now. To move the item further, the user will need to press the
- left mouse button again.
-
- \snippet widgets/tooltips/sortingbox.cpp 14
- \codeline
- \snippet widgets/tooltips/sortingbox.cpp 15
- \codeline
- \snippet widgets/tooltips/sortingbox.cpp 16
-
- The \c createNewCircle(), \c createNewSquare() and \c
- createNewTriangle() slots simply create new shape items, using the
- private \c createShapeItem(), \c randomItemPosition() and \c
- randomItemColor() functions.
-
- \snippet widgets/tooltips/sortingbox.cpp 17
-
- In the \c itemAt() function, we run through the list of created
- shape items to check if the given position is contained within the
- area of any of the shape items.
-
- For each shape item we use the QPainterPath::contains() function
- to find out if the item's painter path contains the position. If
- it does we return the index of the item, otherwise we return
- -1. We run through the list backwards to get the index of the
- uppermost shape item in case several items cover the position.
-
- \snippet widgets/tooltips/sortingbox.cpp 18
-
- The \c moveItemTo() function moves the shape item in motion, and
- the parameter \c pos is the position of a mouse event. First we
- calculate the offset between the parameter \c pos and the previous
- mouse event position. Then we add the offset to the current
- position of the item in motion.
-
- It is tempting to simply set the position of the item to be the
- parameter \c pos. But an item's position defines the top left
- corner of the item's bounding rectangle, and the parameter \c pos
- can be any point; The suggested shortcut would cause the item to
- jump to a position where the cursor is pointing to the bounding
- rectangle's top left corner, regardless of the item's previous
- position.
-
- \snippet widgets/tooltips/sortingbox.cpp 19
-
- Finally, we update the previous mouse event position, and make a
- call to the QWidget::update() function to make the item appear at
- its new position.
-
- \snippet widgets/tooltips/sortingbox.cpp 20
-
- In the \c updateButtonGeometry() function we set the geometry for
- the given button. The parameter coordinates define the bottom
- right corner of the button. We use these coordinates and the
- button's size hint to determine the position of the upper left
- corner. This position, and the button's width and height, are the
- arguments required by the QWidget::setGeometry() function.
-
- In the end, we calculate and return the y-coordinate of the bottom
- right corner of the next button. We use the QWidget::style()
- function to retrieve the widget's GUI style, and then
- QStyle::pixelMetric() to determine the widget's preferred default
- spacing between its child widgets.
-
- \snippet widgets/tooltips/sortingbox.cpp 21
-
- The \c createShapeItem() function creates a single shape item. It
- sets the path, tooltip, position and color, using the item's own
- functions. In the end, the function appends the new item to the
- list of shape items, and calls the QWidget::update() function to
- make it appear with the other items within the \c SortingBox
- widget.
-
- \snippet widgets/tooltips/sortingbox.cpp 22
-
- The \c createToolButton() function is called from the \c
- SortingBox constructor. We create a tool button with the given
- tooltip and icon. The button's parent is the \c SortingBox widget,
- and its size is 32 x 32 pixels. Before we return the button, we
- connect it to the given slot.
-
- \snippet widgets/tooltips/sortingbox.cpp 23
-
- The \c initialItemPosition() function is also called from the
- constructor. We want the three first items to initially be
- centered in the middle of the \c SortingBox widget, and we use
- this function to calculate their positions.
-
- \snippet widgets/tooltips/sortingbox.cpp 24
-
- Whenever the user creates a new shape item, we want the new item
- to appear at a random position, and we use the \c
- randomItemPosition() function to calculate such a position. We
- make sure that the item appears within the visible area of the
- \c SortingBox widget, using the widget's current width and height
- when calculating the random coordinates.
-
- \snippet widgets/tooltips/sortingbox.cpp 25
-
- As with \c initialItemPosition(), the \c initialItemColor()
- function is called from the constructor. The purposes of both
- functions are purely cosmetic: We want to control the initial
- position and color of the three first items.
-
- \snippet widgets/tooltips/sortingbox.cpp 26
-
- Finally the \c randomItemColor() function is implemented to give
- the shape items the user creates, a random color.
-
- \section1 ShapeItem Class Definition
-
- \snippet widgets/tooltips/shapeitem.h 0
-
- The \c ShapeItem class is a custom widget representing one single
- shape item. The widget has a path, a position, a color and a
- tooltip. We need functions to set or modify these objects, as well
- as functions that return them. We make the latter functions \c
- const to prohibit any modifications of the objects,
- i.e. prohibiting unauthorized manipulation of the shape items
- appearance.
-
- \section1 ShapeItem Class Implementation
-
- \snippet widgets/tooltips/shapeitem.cpp 0
- \codeline
- \snippet widgets/tooltips/shapeitem.cpp 1
- \codeline
- \snippet widgets/tooltips/shapeitem.cpp 2
- \codeline
- \snippet widgets/tooltips/shapeitem.cpp 3
-
- This first group of functions simply return the objects that are
- requested. The objects are returned as constants, i.e. they cannot
- be modified.
-
- \snippet widgets/tooltips/shapeitem.cpp 4
- \codeline
- \snippet widgets/tooltips/shapeitem.cpp 5
- \codeline
- \snippet widgets/tooltips/shapeitem.cpp 6
- \codeline
- \snippet widgets/tooltips/shapeitem.cpp 7
-
- The last group of functions set or modify the shape item's path,
- position, color and tooltip, respectively.
-*/
diff --git a/examples/widgets/doc/src/transformations.qdoc b/examples/widgets/doc/src/transformations.qdoc
index 17b540b6cc..d90708340c 100644
--- a/examples/widgets/doc/src/transformations.qdoc
+++ b/examples/widgets/doc/src/transformations.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example painting/transformations
\title Transformations Example
+ \examplecategory {Graphics}
\ingroup examples-painting
\brief The Transformations example shows how transformations
influence the way that QPainter renders graphics primitives.
@@ -72,8 +49,8 @@
coordinate system around the origin (called shearing) using the
QPainter::shear() function.
- All the tranformation operations operate on QPainter's
- tranformation matrix that you can retrieve using the
+ All the transformation operations operate on QPainter's
+ transformation matrix that you can retrieve using the
QPainter::worldTransform() function. A matrix transforms a point in the
plane to another point. For more information about the
transformation matrix, see the \l {Coordinate System} and
@@ -289,11 +266,11 @@
\snippet painting/transformations/window.cpp 1
Then we create the \c RenderArea widgets that will render their
- shapes with coordinate tranformations. By default the applied
+ shapes with coordinate transformations. By default the applied
operation is \uicontrol {No Transformation}, i.e. the shapes are
rendered within the default coordinate system. We create and
initialize the associated \l {QComboBox}es with items
- corresponding to the various transformation operations decribed by
+ corresponding to the various transformation operations described by
the global \c Operation enum.
We also connect the \l {QComboBox}es' \l
@@ -359,10 +336,10 @@
also has good support for coordinate transformations. With the
Transformations application you can scale, rotate and translate
QPainter's coordinate system. The order in which these
- tranformations are applied is essential for the result.
+ transformations are applied is essential for the result.
- All the tranformation operations operate on QPainter's
- tranformation matrix. For more information about the
+ All the transformation operations operate on QPainter's
+ transformation matrix. For more information about the
transformation matrix, see the \l {Coordinate System} and
QTransform documentation.
diff --git a/examples/widgets/doc/src/treemodelcompleter.qdoc b/examples/widgets/doc/src/treemodelcompleter.qdoc
index d3b435976c..ae7c18f442 100644
--- a/examples/widgets/doc/src/treemodelcompleter.qdoc
+++ b/examples/widgets/doc/src/treemodelcompleter.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example tools/treemodelcompleter
\title Tree Model Completer Example
+ \examplecategory {User Interface Components}
\ingroup examples-widgets-tools
\brief The Tree Model Completer example shows how to provide completion
diff --git a/examples/widgets/doc/src/trivialwizard.qdoc b/examples/widgets/doc/src/trivialwizard.qdoc
index 783cc07028..75d007f388 100644
--- a/examples/widgets/doc/src/trivialwizard.qdoc
+++ b/examples/widgets/doc/src/trivialwizard.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example dialogs/trivialwizard
\title Trivial Wizard Example
+ \examplecategory {User Interface Components}
\ingroup examples-dialogs
\brief The Trivial Wizard example illustrates how to create a linear three-page
@@ -79,5 +56,5 @@
\snippet dialogs/trivialwizard/trivialwizard.cpp 10
- \sa QWizard, {Class Wizard Example}, {License Wizard Example}
+ \sa QWizard, {License Wizard Example}
*/
diff --git a/examples/widgets/doc/src/undo.qdoc b/examples/widgets/doc/src/undo.qdoc
deleted file mode 100644
index 321ae159a3..0000000000
--- a/examples/widgets/doc/src/undo.qdoc
+++ /dev/null
@@ -1,44 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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 tools/undo
- \title Undo Framework
- \ingroup examples-widgets-tools
-
- \brief This example shows Qt's undo framework in action.
-
- \image undodemo.png
-
- Qt's undo framework is an implementation of the Command
- pattern, which provides advanced undo/redo functionality.
-
- To show the abilities of the framework, we have implemented a
- small diagram application in which the diagram items are geometric
- primitives. You can edit the diagram in the following ways: add,
- move, change the color of, and delete the items.
-*/
diff --git a/examples/widgets/doc/src/undoframework.qdoc b/examples/widgets/doc/src/undoframework.qdoc
index b4e6f3685d..e8d895b7f0 100644
--- a/examples/widgets/doc/src/undoframework.qdoc
+++ b/examples/widgets/doc/src/undoframework.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example tools/undoframework
\title Undo Framework Example
+ \examplecategory {Data Processing & I/O}
\ingroup examples-widgets-tools
\brief This example shows how to implement undo/redo functionality
@@ -93,6 +70,9 @@
\snippet tools/undoframework/mainwindow.cpp 0
In the constructor, we set up the DiagramScene and QGraphicsView.
+ We only want \c deleteAction to be enabled when we have selected an
+ item, so we connect to the \c selectionChanged() signal of the scene
+ to \c updateActions() slot.
Here is the \c createUndoView() function:
@@ -100,13 +80,11 @@
The QUndoView is a widget that display the text, which is set with
the \l{QUndoCommand::}{setText()} function, for each QUndoCommand
- in the undo stack in a list.
+ in the undo stack in a list. We put it into a docking widget.
Here is the \c createActions() function:
\snippet tools/undoframework/mainwindow.cpp 2
- \codeline
- \snippet tools/undoframework/mainwindow.cpp 3
\dots
\snippet tools/undoframework/mainwindow.cpp 5
@@ -119,46 +97,38 @@
\l{QUndoCommand::}{text()} of the undo commands. For the other
actions we have implemented slots in the \c MainWindow class.
- Here is the \c createMenus() function:
-
+ \dots
\snippet tools/undoframework/mainwindow.cpp 6
- \dots
+ Once all actions are created we update their state by calling the
+ same function that is connected to the \c selectionChanged signal of
+ the scene.
+
+ The \c createMenus() and \c createToolBars() functions add the
+ actions to menus and toolbars:
+
\snippet tools/undoframework/mainwindow.cpp 7
\dots
\snippet tools/undoframework/mainwindow.cpp 8
-
- We have to use the QMenu \c aboutToShow() and \c aboutToHide()
- signals since we only want \c deleteAction to be enabled when we
- have selected an item.
+ \dots
+ \snippet tools/undoframework/mainwindow.cpp 9
Here is the \c itemMoved() slot:
- \snippet tools/undoframework/mainwindow.cpp 9
+ \snippet tools/undoframework/mainwindow.cpp 11
We simply push a MoveCommand on the stack, which calls \c redo()
on it.
Here is the \c deleteItem() slot:
- \snippet tools/undoframework/mainwindow.cpp 10
+ \snippet tools/undoframework/mainwindow.cpp 12
- An item must be selected to be deleted. We need to check if it is
+ An item must be selected to be deleted. We need to check if it is
selected as the \c deleteAction may be enabled even if an item is
not selected. This can happen as we do not catch a signal or event
when an item is selected.
- Here is the \c itemMenuAboutToShow() and itemMenuAboutToHide() slots:
-
- \snippet tools/undoframework/mainwindow.cpp 11
- \codeline
- \snippet tools/undoframework/mainwindow.cpp 12
-
- We implement \c itemMenuAboutToShow() and \c itemMenuAboutToHide()
- to get a dynamic item menu. These slots are connected to the
- \l{QMenu::}{aboutToShow()} and \l{QMenu::}{aboutToHide()} signals.
- We need this to disable or enable the \c deleteAction.
-
Here is the \c addBox() slot:
\snippet tools/undoframework/mainwindow.cpp 13
diff --git a/examples/widgets/doc/src/validators.qdoc b/examples/widgets/doc/src/validators.qdoc
deleted file mode 100644
index 9d82f3f575..0000000000
--- a/examples/widgets/doc/src/validators.qdoc
+++ /dev/null
@@ -1,35 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/validators
- \title Validators Example
- \brief The Validators example shows the signal emission behavior of input
- validators.
-
- \borderedimage validators.png
-*/
diff --git a/examples/widgets/doc/src/wiggly.qdoc b/examples/widgets/doc/src/wiggly.qdoc
deleted file mode 100644
index d70d609e2b..0000000000
--- a/examples/widgets/doc/src/wiggly.qdoc
+++ /dev/null
@@ -1,168 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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/wiggly
- \title Wiggly Example
- \ingroup examples-widgets
- \brief The Wiggly example shows how to animate a widget using
- QBasicTimer and \l{QObject::timerEvent()}{timerEvent()}. In
- addition, the example demonstrates how to use QFontMetrics to
- determine the size of text on screen.
-
- \borderedimage wiggly-example.png
- \caption Screenshot of the Wiggly example
-
- QBasicTimer is a low-level class for timers. Unlike QTimer,
- QBasicTimer doesn't inherit from QObject; instead of emitting a
- \l{QTimer::timeout()}{timeout()} signal when a certain amount of
- time has passed, it sends a QTimerEvent to a QObject of our
- choice. This makes QBasicTimer a more lightweight alternative to
- QTimer. Qt's built-in widgets use it internally, and it is
- provided in Qt's API for highly-optimized applications (such as
- embedded applications).
-
- The example consists of two classes:
-
- \list
- \li \c WigglyWidget is the custom widget displaying the text
- in a wiggly line.
-
- \li \c Dialog is the dialog widget allowing the user to enter a
- text. It combines a \c WigglyWidget and a \c QLineEdit.
- \endlist
-
- We will first take a quick look at the \c Dialog class, then we
- will review the \c WigglyWidget class.
-
- \section1 Dialog Class Definition
-
- \snippet widgets/wiggly/dialog.h 0
-
- The \c Dialog class provides a dialog widget that allows the user
- to enter a text. The text is then rendered by \c WigglyWidget.
-
- \section1 Dialog Class Implementation
-
- \snippet widgets/wiggly/dialog.cpp 0
-
- In the constructor we create a wiggly widget along with a
- \l{QLineEdit}{line edit}, and we put the two widgets in a
- vertical layout. We connect the line edit's \l
- {QLineEdit::textChanged()}{textChanged()} signal to the wiggly
- widget's \c setText() slot to obtain the real time interaction
- with the wiggly widget. The widget's default text is "Hello
- world!".
-
- \section1 WigglyWidget Class Definition
-
- \snippet widgets/wiggly/wigglywidget.h 0
-
- The \c WigglyWidget class provides the wiggly line displaying the
- text. We subclass QWidget and reimplement the standard \l
- {QWidget::paintEvent()}{paintEvent()} and \l
- {QObject::timerEvent()}{timerEvent()} functions to draw and update
- the widget. In addition we implement a public \c setText() slot
- that sets the widget's text.
-
- The \c timer variable, of type QBasicTimer, is used to update the
- widget at regular intervals, making the widget move. The \c text
- variable is used to store the currently displayed text, and \c
- step to calculate position and color for each character on the
- wiggly line.
-
- \section1 WigglyWidget Class Implementation
-
- \snippet widgets/wiggly/wigglywidget.cpp 0
-
- In the constructor, we make the widget's background slightly
- lighter than the usual background using the QPalette::Midlight
- color role. The background role defines the brush from the
- widget's palette that Qt uses to paint the background. Then we
- enlarge the widget's font with 20 points.
-
- Finally we start the timer; the call to QBasicTimer::start()
- makes sure that \e this particular wiggly widget will receive the
- timer events generated when the timer times out (every 60
- milliseconds).
-
- \snippet widgets/wiggly/wigglywidget.cpp 1
- \snippet widgets/wiggly/wigglywidget.cpp 2
-
- The \c paintEvent() function is called whenever a QPaintEvent is
- sent to the widget. Paint events are sent to widgets that need to
- update themselves, for instance when part of a widget is exposed
- because a covering widget was moved. For the wiggly widget, a
- paint event will also be generated every 60 milliseconds from
- the \c timerEvent() slot.
-
- The \c sineTable represents y-values of the sine curve,
- multiplied by 100. It is used to make the wiggly widget move
- along the sine curve.
-
- The QFontMetrics object provides information about the widget's
- font. The \c x variable is the horizontal position where we start
- drawing the text. The \c y variable is the vertical position of
- the text's base line. Both variables are computed so that the
- text is horizontally and vertically centered. To compute the base
- line, we take into account the font's ascent (the height of the
- font above the base line) and font's descent (the height of the
- font below the base line). If the descent equals the ascent, they
- cancel out each other and the base line is at \c height() / 2.
-
- \snippet widgets/wiggly/wigglywidget.cpp 3
- \snippet widgets/wiggly/wigglywidget.cpp 4
-
- Each time the \c paintEvent() function is called, we create a
- QPainter object \c painter to draw the contents of the widget.
- For each character in \c text, we determine the color and the
- position on the wiggly line based on \c step. In addition, \c x
- is incremented by the character's width.
-
- For simplicity, we assume that QFontMetrics::horizontalAdvance(\c text)
- returns the sum of the individual character advances
- (QFontMetrics::horizontalAdvance(\c text[i])). In practice, this is not
- always the case because QFontMetrics::horizontalAdvance(\c text) also takes
- into account the kerning between certain letters (e.g., 'A' and
- 'V'). The result is that the text isn't perfectly centered. You
- can verify this by typing "AVAVAVAVAVAV" in the line edit.
-
- \snippet widgets/wiggly/wigglywidget.cpp 5
- \snippet widgets/wiggly/wigglywidget.cpp 6
-
- The \c timerEvent() function receives all the timer events that
- are generated for this widget. If a timer event is sent from the
- widget's QBasicTimer, we increment \c step to make the text move,
- and call QWidget::update() to refresh the display. Any other
- timer event is passed on to the base class's implementation of
- the \l{QWidget::timerEvent()}{timerEvent()} function.
-
- The QWidget::update() slot does not cause an immediate repaint;
- instead the slot schedules a paint event for processing when Qt
- returns to the main event loop. The paint events are then handled
- by \c{WigglyWidget}'s \c paintEvent() function.
-*/
diff --git a/examples/widgets/doc/src/windowflags.qdoc b/examples/widgets/doc/src/windowflags.qdoc
index 3fe00cd266..10b0496728 100644
--- a/examples/widgets/doc/src/windowflags.qdoc
+++ b/examples/widgets/doc/src/windowflags.qdoc
@@ -1,33 +1,10 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 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$
-**
-****************************************************************************/
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example widgets/windowflags
\title Window Flags Example
+ \examplecategory {User Interface Components}
\ingroup examples-widgets
\brief The Window Flags example shows how to use the window flags
available in Qt.