1/****************************************************************************
2**
3** Copyright (C) 2015 The Qt Company Ltd.
4** Contact: http://www.qt.io/licensing/
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:FDL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see http://www.qt.io/terms-conditions. For further
15** information use the contact form at http://www.qt.io/contact-us.
16**
17** GNU Free Documentation License Usage
18** Alternatively, this file may be used under the terms of the GNU Free
19** Documentation License version 1.3 as published by the Free Software
20** Foundation and appearing in the file included in the packaging of
21** this file.  Please review the following information to ensure
22** the GNU Free Documentation License version 1.3 requirements
23** will be met: http://www.gnu.org/copyleft/fdl.html.
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29    \class QDesignerTaskMenuExtension
30    \brief The QDesignerTaskMenuExtension class allows you to add custom
31    menu entries to Qt Designer's task menu.
32    \inmodule QtDesigner
33
34    QDesignerTaskMenuExtension provides an interface for creating
35    custom task menu extensions. It is typically used to create task
36    menu entries that are specific to a plugin in \QD.
37
38    \QD uses the QDesignerTaskMenuExtension to feed its task
39    menu. Whenever a task menu is requested, \QD will query
40    for the selected widget's task menu extension.
41
42    \image taskmenuextension-example-faded.png
43
44    A task menu extension is a collection of QActions. The actions
45    appear as entries in the task menu when the plugin with the
46    specified extension is selected. The image above shows the custom
47    \gui {Edit State...} action which appears in addition to \QD's
48    default task menu entries: \gui Cut, \gui Copy, \gui Paste etc.
49
50    To create a custom task menu extension, your extension class must
51    inherit from both QObject and QDesignerTaskMenuExtension. For
52    example:
53
54    \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 9
55
56    Since we are implementing an interface, we must ensure that it
57    is made known to the meta-object system using the Q_INTERFACES()
58    macro. This enables \QD to use the qobject_cast() function to
59    query for supported interfaces using nothing but a QObject
60    pointer.
61
62    You must reimplement the taskActions() function to return a list
63    of actions that will be included in \QD task menu. Optionally, you
64    can reimplement the preferredEditAction() function to set the
65    action that is invoked when selecting your plugin and pressing
66    \key F2. The preferred edit action must be one of the actions
67    returned by taskActions() and, if it's not defined, pressing the
68    \key F2 key will simply be ignored.
69
70    In \QD, extensions are not created until they are required. A
71    task menu extension, for example, is created when you click the
72    right mouse button over a widget in \QD's workspace. For that
73    reason you must also construct an extension factory, using either
74    QExtensionFactory or a subclass, and register it using \QD's
75    \l {QExtensionManager}{extension manager}.
76
77    When a task menu extension is required, \QD's \l
78    {QExtensionManager}{extension manager} will run through all its
79    registered factories calling QExtensionFactory::createExtension()
80    for each until it finds one that is able to create a task menu
81    extension for the selected widget. This factory will then make an
82    instance of the extension.
83
84    There are four available types of extensions in \QD:
85    QDesignerContainerExtension, QDesignerMemberSheetExtension,
86    QDesignerPropertySheetExtension, and QDesignerTaskMenuExtension.
87    \QD's behavior is the same whether the requested extension is
88    associated with a container, a member sheet, a property sheet or a
89    task menu.
90
91    The QExtensionFactory class provides a standard extension factory,
92    and can also be used as an interface for custom extension
93    factories. You can either create a new QExtensionFactory and
94    reimplement the QExtensionFactory::createExtension() function. For
95    example:
96
97    \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 10
98
99    Or you can use an existing factory, expanding the
100    QExtensionFactory::createExtension() function to make the factory
101    able to create a task menu extension as well. For example:
102
103    \snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 11
104
105    For a complete example using the QDesignerTaskMenuExtension class,
106    see the \l {designer/taskmenuextension}{Task Menu Extension
107    example}. The example shows how to create a custom widget plugin
108    for \QD, and how to to use the QDesignerTaskMenuExtension
109    class to add custom items to \QD's task menu.
110
111    \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget
112    Extensions}
113*/
114
115/*!
116    \fn QDesignerTaskMenuExtension::~QDesignerTaskMenuExtension()
117
118    Destroys the task menu extension.
119*/
120
121/*!
122    \fn QAction *QDesignerTaskMenuExtension::preferredEditAction() const
123
124    Returns the action that is invoked when selecting a plugin with
125    the specified extension and pressing \key F2.
126
127    The action must be one of the actions returned by taskActions().
128*/
129
130/*!
131    \fn QList<QAction*> QDesignerTaskMenuExtension::taskActions() const
132
133    Returns the task menu extension as a list of actions which will be
134    included in \QD's task menu when a plugin with the specified
135    extension is selected.
136
137    The function must be reimplemented to add actions to the list.
138*/
139