path: root/examples/designer/doc/src/taskmenuextension.qdoc

// 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

    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

    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

    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.
*/