Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example taskmenuextension
++ \examplecategory {Desktop}
++ \meta tags {widgets,designer}
++ \ingroup examples-designer
++ \title Task Menu Extension
++
++ \brief Creating a custom widget plugin for \QD and providing custom task
++ menu entries that are associated with the plugin.
++
++ The Task Menu Extension example shows how to create a custom
++ widget plugin for \l {Qt Widgets Designer Manual}{\QD}, and how to use
++ the QDesignerTaskMenuExtension class to provide custom task menu
++ entries associated with the plugin.
++
++ \image taskmenuextension-example.webp {Screenshot of a custom "Edit State..."
++ action in a context menu of \QD.}
++
++ To provide a custom widget that can be used with \QD, we need to
++ supply a self-contained implementation. In this example we use a
++ custom widget designed to show the task menu extension feature:
++ The TicTacToe widget.
++
++ An extension is an object which modifies the behavior of \QD. The
++ QDesignerTaskMenuExtension can provide custom task menu entries
++ when a widget with this extension is selected.
++
++ There are four available types of extensions in \QD:
++
++ \list
++ \li QDesignerContainerExtension provides an extension that allows
++ you to add (and delete) pages to a multi-page container plugin
++ in \QD.
++ \li QDesignerMemberSheetExtension provides an extension that allows
++ you to manipulate a widget's member functions which is displayed
++ when configuring connections using \QD's mode for editing
++ signals and slots.
++ \li QDesignerPropertySheetExtension provides an extension that
++ allows you to manipulate a widget's properties which is displayed
++ in \QD's property editor.
++ \li QDesignerTaskMenuExtension provides an extension that allows
++ you to add custom menu entries to \QD's task menu.
++ \endlist
++
++ You can use all the extensions following the same pattern as in
++ this example, only replacing the respective extension base
++ class. For more information, see the \l{Qt Widgets Designer C++ Classes}.
++
++ The Task Menu Extension example consists of five classes:
++
++ \list
++ \li \c TicTacToe is a custom widget that lets the user play
++ the Tic-Tac-Toe game.
++ \li \c TicTacToePlugin exposes the \c TicTacToe class to \QD.
++ \li \c TicTacToeTaskMenuFactory creates a \c TicTacToeTaskMenu object.
++ \li \c TicTacToeTaskMenu provides the task menu extension, i.e the
++ plugin's associated task menu entries.
++ \li \c TicTacToeDialog lets the user modify the state of a
++ Tic-Tac-Toe plugin loaded into \QD.
++ \endlist
++
++ The project file for custom widget plugins needs some additional
++ information to ensure that they will work within \QD. For example,
++ custom widget plugins rely on components supplied with \QD, and
++ this must be specified in the project file that we use. We will
++ first take a look at the plugin's project file.
++
++ Then we will continue by reviewing the \c TicTacToePlugin class,
++ and take a look at the \c TicTacToeTaskMenuFactory and \c
++ TicTacToeTaskMenu classes. Finally, we will review the \c
++ TicTacToeDialog class before we take a quick look at the \c
++ TicTacToe widget's class definition.
++
++ \section1 Project files
++
++ \section2 CMake
++
++ The project files need to state that a plugin linking
++ to the \QD libraries is to be built:
++
++ \snippet taskmenuextension/CMakeLists.txt 0
++ \codeline
++ \snippet taskmenuextension/CMakeLists.txt 2
++
++ The following example shows how to add the header and source files of the
++ widget:
++
++ \snippet taskmenuextension/CMakeLists.txt 1
++
++ We provide an implementation of the plugin interface so that \QD
++ can use the custom widget. In this particular example we also
++ provide implementations of the task menu extension and the
++ extension factory as well as a dialog implementation.
++
++ It is important to ensure that the plugin is installed in a
++ location that is searched by \QD. We do this by specifying a
++ target path for the project and adding it to the list of items to
++ install:
++
++ \snippet taskmenuextension/CMakeLists.txt 3
++ \snippet taskmenuextension/CMakeLists.txt 4
++
++ The task menu extension is created as a library. It will be
++ installed alongside the other \QD plugins when the project is
++ installed (using \c{ninja install} or an equivalent installation
++ procedure).
++
++ For more information about plugins, see the
++ \l {How to Create Qt Plugins} documentation.
++
++ \section2 qmake
++
++ The following example shows how to link a plugin to the \QD libraries:
++
++ \snippet taskmenuextension/taskmenuextension.pro 0
++ \codeline
++ \snippet taskmenuextension/taskmenuextension.pro 1
++
++ The following example shows how to add the header and source files of the
++ widget:
++
++ \snippet taskmenuextension/taskmenuextension.pro 2
++
++ The following example shows how to install a plugin to the \QD's plugin path:
++
++ \snippet taskmenuextension/taskmenuextension.pro 3
++
++ \section1 TicTacToePlugin Class Definition
++
++ The \c TicTacToePlugin class exposes \c the TicTacToe class to
++ \QD. Its definition is equivalent to the \l
++ {customwidgetplugin}{Custom Widget Plugin} example's
++ plugin class which is explained in detail. The only part of the
++ class definition that is specific to this particular custom widget
++ is the class name.
++
++ To ensure that Qt recognizes the widget as a plugin, export relevant
++ information about the widget by adding the \c Q_PLUGIN_METADATA() macro:
++
++ \snippet taskmenuextension/tictactoeplugin.h 0
++
++ The plugin class provides \QD with basic information about our
++ plugin, such as its class name and its include file. Furthermore
++ it knows how to create instances of the \c TicTacToe widget.
++ TicTacToePlugin also defines the \l
++ {QDesignerCustomWidgetInterface::initialize()}{initialize()}
++ function which is called after the plugin is loaded into \QD. The
++ function's QDesignerFormEditorInterface parameter provides the
++ plugin with a gateway to all of \QD's API's.
++
++ The \c TicTacToePlugin class inherits from both QObject and
++ QDesignerCustomWidgetInterface. It is important to remember, when
++ using multiple inheritance, to ensure that all the interfaces
++ (i.e. the classes that doesn't inherit Q_OBJECT) are made known to
++ the meta object system using the Q_INTERFACES() macro. This
++ enables \QD to use qobject_cast() to query for supported
++ interfaces using nothing but a QObject pointer.
++
++ \section1 TicTacToePlugin Class Implementation
++
++ The TicTacToePlugin class implementation is in most parts
++ equivalent to the \l {customwidgetplugin}{Custom Widget
++ Plugin} example's plugin class:
++
++ \snippet taskmenuextension/tictactoeplugin.cpp 0
++
++ The only function that differs significantly is the initialize()
++ function:
++
++ \snippet taskmenuextension/tictactoeplugin.cpp 1
++
++ The \c initialize() function takes a QDesignerFormEditorInterface
++ object as argument. The QDesignerFormEditorInterface class
++ provides access to \QD's components.
++
++ In \QD you can create two kinds of plugins: custom widget plugins
++ and tool plugins. QDesignerFormEditorInterface provides access to
++ all the \QD components that you normally need to create a tool
++ plugin: the extension manager, the object inspector, the property
++ editor and the widget box. Custom widget plugins have access to
++ the same components.
++
++ \snippet taskmenuextension/tictactoeplugin.cpp 2
++
++ When creating extensions associated with custom widget plugins, we
++ need to access \QD's current extension manager which we retrieve
++ from the QDesignerFormEditorInterface parameter.
++
++ \QD's QDesignerFormEditorInterface holds information about all Qt
++ Designer's components: The action editor, the object inspector,
++ the property editor, the widget box, and the extension and form
++ window managers.
++
++ The QExtensionManager class provides extension management
++ facilities for \QD. Using \QD's current extension manager you can
++ retrieve the extension for a given object. You can also register
++ and unregister an extension for a given object. Remember that an
++ extension is an object which modifies the behavior of \QD.
++
++ When registrering an extension, it is actually the associated
++ extension factory that is registered. In \QD, extension factories
++ are used to look up and create named extensions as they are
++ required. So, in this example, the task menu extension itself is
++ not created until a task menu is requested by the user.
++
++ \snippet taskmenuextension/tictactoeplugin.cpp 3
++
++ We create a \c TicTacToeTaskMenuFactory object that we register
++ using \QD's current \l {QExtensionManager}{extension manager}
++ retrieved from the QDesignerFormEditorInterface parameter. The
++ first argument is the newly created factory and the second
++ argument is an extension identifier which is a string. The \c
++ Q_TYPEID() macro simply converts the string into a QLatin1String.
++
++ The \c TicTacToeTaskMenuFactory class is a subclass of
++ QExtensionFactory. When the user request a task menu by clicking
++ the right mouse button over a widget with the specified task menu
++ extension, \QD's extension manager will run through all its
++ registered factories invoking the first one that is able to create
++ a task menu extension for the selected widget. This factory will
++ in turn create a \c TicTacToeTaskMenu object (the extension).
++
++ We omit to reimplement the
++ QDesignerCustomWidgetInterface::domXml() function (which include
++ default settings for the widget in the standard XML format used by
++ \QD), since no default values are necessary.
++
++ \snippet taskmenuextension/tictactoeplugin.h 1
++
++ Finally, we use the Q_PLUGIN_METADATA() macro to export the
++ TicTacToePlugin class for use with Qt's plugin handling classes:
++ This macro ensures that \QD can access and construct the custom
++ widget. Without this macro, there is no way for \QD to use the
++ widget.
++
++ \section1 TicTacToeTaskMenuFactory Class Definition
++
++ The \c TicTacToeTaskMenuFactory class inherits QExtensionFactory
++ which provides a standard extension factory for \QD.
++
++ \snippet taskmenuextension/tictactoetaskmenu.h 1
++
++ The subclass's purpose is to reimplement the
++ QExtensionFactory::createExtension() function, making it able to
++ create a \c TicTacToe task menu extension.
++
++ \section1 TicTacToeTaskMenuFactory Class Implementation
++
++ The class constructor simply calls the QExtensionFactory base
++ class constructor:
++
++ \snippet taskmenuextension/tictactoetaskmenu.cpp 4
++
++ As described above, the factory is invoked when the user request a
++ task menu by clicking the right mouse button over a widget with
++ the specified task menu extension in \QD.
++
++ \QD's behavior is the same whether the requested extension is
++ associated with a container, a member sheet, a property sheet or a
++ task menu: Its extension manager runs through all its registered
++ extension factories calling \c createExtension() for each until
++ one responds by creating the requested extension.
++
++ \snippet taskmenuextension/tictactoetaskmenu.cpp 5
++
++ So the first thing we do in \c
++ TicTacToeTaskMenuFactory::createExtension() is to check if the
++ requested extension is a task menu extension. If it is, and the
++ widget requesting it is a \c TicTacToe widget, we create and
++ return a \c TicTacToeTaskMenu object. Otherwise, we simply return
++ a null pointer, allowing \QD's extension manager to continue its
++ search through the registered factories.
++
++
++ \section1 TicTacToeTaskMenu Class Definition
++
++ \image taskmenuextension-menu.webp {Screenshot showing all options
++ to change a widget in the UI editor}
++
++ The \c TicTacToeTaskMenu class inherits QDesignerTaskMenuExtension
++ which allows you to add custom entries (in the form of QActions)
++ to the task menu in \QD.
++
++ \snippet taskmenuextension/tictactoetaskmenu.h 0
++
++ We reimplement the \c preferredEditAction() and \c taskActions()
++ functions. Note that we implement a constructor that takes \e two
++ arguments: the parent widget, and the \c TicTacToe widget for
++ which the task menu is requested.
++
++ In addition we declare the private \c editState() slot, our custom
++ \c editStateAction and a private pointer to the \c TicTacToe
++ widget which state we want to modify.
++
++ \section1 TicTacToeTaskMenu Class Implementation
++
++ \snippet taskmenuextension/tictactoetaskmenu.cpp 0
++
++ In the constructor we first save the reference to the \c TicTacToe
++ widget sent as parameter, i.e the widget which state we want to
++ modify. We will need this later when our custom action is
++ invoked. We also create our custom \c editStateAction and connect
++ it to the \c editState() slot.
++
++ \snippet taskmenuextension/tictactoetaskmenu.cpp 1
++
++ The \c editState() slot is called whenever the user chooses the
++ \gui {Edit State...} option in a \c TicTacToe widget's task menu. The
++ slot creates a \c TicTacToeDialog presenting the current state of
++ the widget, and allowing the user to edit its state by playing the
++ game.
++
++ \snippet taskmenuextension/tictactoetaskmenu.cpp 2
++
++ We reimplement the \c preferredEditAction() function to return our
++ custom \c editStateAction as the action that should be invoked
++ when selecting a \c TicTacToe widget and pressing \key F2 .
++
++ \snippet taskmenuextension/tictactoetaskmenu.cpp 3
++
++ We reimplement the \c taskActions() function to return a list of
++ our custom actions making these appear on top of the default menu
++ entries in a \c TicTacToe widget's task menu.
++
++ \section1 TicTacToeDialog Class Definition
++
++ \image taskmenuextension-dialog.webp {Screenshot showing the edit
++ state mode of a widget}
++
++ The \c TicTacToeDialog class inherits QDialog. The dialog lets the
++ user modify the state of the currently selected Tic-Tac-Toe
++ plugin.
++
++ \snippet taskmenuextension/tictactoedialog.h 0
++
++ We reimplement the \c sizeHint() function. We also declare two
++ private slots: \c resetState() and \c saveState(). In addition to
++ the dialog's buttons and layouts we declare two \c TicTacToe
++ pointers, one to the widget the user can interact with and the
++ other to the original custom widget plugin which state the user
++ wants to edit.
++
++ \section1 TicTacToeDialog Class Implementation
++
++ \snippet taskmenuextension/tictactoedialog.cpp 0
++
++ In the constructor we first save the reference to the TicTacToe
++ widget sent as parameter, i.e the widget which state the user want
++ to modify. Then we create a new \c TicTacToe widget, and set its
++ state to be equivalent to the parameter widget's state.
++
++ Finally, we create the dialog's buttons and layout.
++
++ \snippet taskmenuextension/tictactoedialog.cpp 1
++
++ We reimplement the \c sizeHint() function to ensure that the
++ dialog is given a reasonable size.
++
++ \snippet taskmenuextension/tictactoedialog.cpp 2
++
++ The \c resetState() slot is called whenever the user press the
++ \gui Reset button. The only thing we do is to call the \c
++ clearBoard() function for the editor widget, i.e. the \c TicTacToe
++ widget we created in the dialog's constructor.
++
++ \snippet taskmenuextension/tictactoedialog.cpp 3
++
++ The \c saveState() slot is called whenever the user press the \gui
++ OK button, and transfers the state of the editor widget to the
++ widget which state we want to modify. In order to make the change
++ of state visible to \QD we need to set the latter widget's state
++ property using the QDesignerFormWindowInterface class.
++
++ QDesignerFormWindowInterface provides you with information about
++ the associated form window as well as allowing you to alter its
++ properties. The interface is not intended to be instantiated
++ directly, but to provide access to \QD's current form
++ windows controlled by \QD's form window manager.
++
++ If you are looking for the form window containing a specific
++ widget, you can use the static
++ QDesignerFormWindowInterface::findFormWindow() function:
++
++ \snippet taskmenuextension/tictactoedialog.cpp 4
++
++ After retrieving the form window of the widget (which state we
++ want to modify), we use the QDesignerFormWindowInterface::cursor()
++ function to retrieve the form window's cursor.
++
++ The QDesignerFormWindowCursorInterface class provides an interface
++ to the form window's text cursor. Once we have cursor, we can
++ finally set the state property using the
++ QDesignerFormWindowCursorInterface::setProperty() function.
++
++ \snippet taskmenuextension/tictactoedialog.cpp 5
++
++ In the end we call the QEvent::accept() function which sets the
++ accept flag of the event object. Setting the \c accept parameter
++ indicates that the event receiver wants the event. Unwanted events
++ might be propagated to the parent widget.
++
++ \section1 TicTacToe Class Definition
++
++ The \c TicTacToe class is a custom widget that lets the user play
++ the Tic-Tac-Toe game.
++
++ \snippet taskmenuextension/tictactoe.h 0
++
++ The main details to observe in the \c TicTacToe class defintion is
++ the declaration of the \c state property and its \c state() and \c
++ setState() functions.
++
++ We need to declare the \c TicTacToe widget's state as a property
++ to make it visible to \QD; allowing \QD to manage it in the same
++ way it manages the properties the \c TicTacToe widget inherits
++ from QWidget and QObject, for example featuring the property
++ editor.
++ */