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