/usr/share/qt5/doc/qtdesigner/designer-creating-custom-widgets-extensions.html is in qttools5-doc-html 5.2.1-8build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- designer-manual.qdoc -->
<title>Creating Custom Widget Extensions | QtDesigner </title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.2</li>
<li><a href="qtdesigner-manual.html">Qt Designer Manual</a></li>
<li>Creating Custom Widget Extensions</li>
<li id="buildversion">
Qt 5.2.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<link rel="prev" href="designer-creating-custom-widgets.html" />
<link rel="next" href="designer-ui-file-format.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="designer-creating-custom-widgets.html">Creating Custom Widgets for Qt Designer</a>
<a class="nextPage" href="designer-ui-file-format.html">Qt Designer's UI File Format</a>
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#extension-types">Extension Types</a></li>
<li class="level1"><a href="#creating-an-extension">Creating an Extension</a></li>
<li class="level1"><a href="#exposing-an-extension-to-qt-designer">Exposing an Extension to Qt Designer</a></li>
<li class="level2"><a href="#creating-an-extension-factory">Creating an Extension Factory</a></li>
<li class="level2"><a href="#accessing-qt-designer-s-extension-manager">Accessing Qt Designer's Extension Manager</a></li>
<li class="level1"><a href="#related-examples">Related Examples</a></li>
</ul>
</div>
<h1 class="title">Creating Custom Widget Extensions</h1>
<span class="subtitle"></span>
<!-- $$$designer-creating-custom-widgets-extensions.html-description -->
<div class="descr"> <a name="details"></a>
<p>Once you have a custom widget plugin for <i>Qt Designer</i>, you can provide it with the expected behavior and functionality within <i>Qt Designer</i>'s workspace, using custom widget extensions.</p>
<a name="extension-types"></a>
<h2>Extension Types</h2>
<p>There are several available types of extensions in <i>Qt Designer</i>. You can use all of these extensions in the same pattern, only replacing the respective extension base class.</p>
<p><a href="qdesignercontainerextension.html">QDesignerContainerExtension</a> is necessary when implementing a custom multi-page container.</p>
<table class="generic">
<tr valign="top" class="odd"><td ><img src="images/designer-manual-taskmenuextension.png" alt="" /></td><td ><b><a href="qdesignertaskmenuextension.html">QDesignerTaskMenuExtension</a></b><p><a href="qdesignertaskmenuextension.html">QDesignerTaskMenuExtension</a> is useful for custom widgets. It provides an extension that allows you to add custom menu entries to <i>Qt Designer</i>'s task menu.</p>
<p>The <a href="qtdesigner-taskmenuextension-example.html">Task Menu Extension</a> example illustrates how to use this class.</p>
</td></tr>
<tr valign="top" class="even"><td ><img src="images/designer-manual-containerextension.png" alt="" /></td><td ><b><a href="qdesignercontainerextension.html">QDesignerContainerExtension</a></b><p><a href="qdesignercontainerextension.html">QDesignerContainerExtension</a> is necessary when implementing a custom multi-page container. It provides an extension that allows you to add and delete pages for a multi-page container plugin in <i>Qt Designer</i>.</p>
<p>The <a href="qtdesigner-containerextension-example.html">Container Extension</a> example further explains how to use this class.</p>
<p><b>Note: </b>It is not possible to add custom per-page properties for some widgets (e.g., <a href="../qtwidgets/qtabwidget.html">QTabWidget</a>) due to the way they are implemented.</p></td></tr>
</table>
<table class="generic">
<tr valign="top" class="odd"><td ><img src="images/designer-manual-membersheetextension.png" alt="" /></td><td ><b><a href="qdesignermembersheetextension.html">QDesignerMemberSheetExtension</a></b><p>The <a href="qdesignermembersheetextension.html">QDesignerMemberSheetExtension</a> class allows you to manipulate a widget's member functions displayed when connecting signals and slots.</p>
</td></tr>
<tr valign="top" class="even"><td ><img src="images/designer-manual-propertysheetextension.png" alt="" /></td><td ><b><a href="qdesignerpropertysheetextension.html">QDesignerPropertySheetExtension</a>, <a href="qdesignerdynamicpropertysheetextension.html">QDesignerDynamicPropertySheetExtension</a></b><p>These extension classes allow you to control how a widget's properties are displayed in <i>Qt Designer</i>'s property editor.</p>
</td></tr>
</table>
<p><i>Qt Designer</i> uses the <a href="qdesignerpropertysheetextension.html">QDesignerPropertySheetExtension</a> and the <a href="qdesignermembersheetextension.html">QDesignerMemberSheetExtension</a> classes to feed its property and signal and slot editors. Whenever a widget is selected in its workspace, <i>Qt Designer</i> will query for the widget's property sheet extension; likewise, whenever a connection between two widgets is requested, <i>Qt Designer</i> will query for the widgets' member sheet extensions.</p>
<p><b>Warning:</b> All widgets have default property and member sheets. If you implement custom property sheet or member sheet extensions, your custom extensions will override the default sheets.</p>
<a name="creating-an-extension"></a>
<h2>Creating an Extension</h2>
<p>To create an extension you must inherit both <a href="../qtcore/qobject.html">QObject</a> and the appropriate base class, and reimplement its functions. Since we are implementing an interface, we must ensure that it is made known to the meta object system using the <a href="../qtcore/qobject.html#Q_INTERFACES">Q_INTERFACES</a>() macro in the extension class's definition. For example:</p>
<pre class="cpp"><span class="keyword">class</span> MyExtension: <span class="keyword">public</span> <span class="type"><a href="../qtcore/qobject.html">QObject</a></span><span class="operator">,</span>
<span class="keyword">public</span> QdesignerContainerExtension
{
Q_OBJECT
Q_INTERFACE(<span class="type"><a href="qdesignercontainerextension.html">QDesignerContainerExtension</a></span>)
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
}</pre>
<p>This enables <i>Qt Designer</i> to use the <a href="../qtcore/qobject.html#qobject_cast">qobject_cast</a>() function to query for supported interfaces using a <a href="../qtcore/qobject.html">QObject</a> pointer only.</p>
<a name="exposing-an-extension-to-qt-designer"></a>
<h2>Exposing an Extension to Qt Designer</h2>
<p>In <i>Qt Designer</i> the extensions are not created until they are required. For this reason, when implementing extensions, you must subclass <a href="qextensionfactory.html">QExtensionFactory</a> to create a class that is able to make instances of your extensions. Also, you must register your factory with <i>Qt Designer</i>'s extension manager; the extension manager handles the construction of extensions.</p>
<p>When an extension is requested, <i>Qt Designer</i>'s extension manager will run through its registered factories calling <a href="qextensionfactory.html#createExtension">QExtensionFactory::createExtension</a>() for each of them until it finds one that is able to create the requested extension for the selected widget. This factory will then make an instance of the extension.</p>
<p class="centerAlign"><img src="images/qtdesignerextensions.png" alt="" /></p><a name="creating-an-extension-factory"></a>
<h3>Creating an Extension Factory</h3>
<p>The <a href="qextensionfactory.html">QExtensionFactory</a> class provides a standard extension factory, but it can also be used as an interface for custom extension factories.</p>
<p>The purpose is to reimplement the <a href="qextensionfactory.html#createExtension">QExtensionFactory::createExtension</a>() function, making it able to create your extension, such as a <a href="qtdesigner-containerextension-example.html">MultiPageWidget</a> container extension.</p>
<p>You can either create a new <a href="qextensionfactory.html">QExtensionFactory</a> and reimplement the <a href="qextensionfactory.html#createExtension">QExtensionFactory::createExtension</a>() function:</p>
<pre class="cpp"><span class="type"><a href="../qtcore/qobject.html">QObject</a></span> <span class="operator">*</span>ANewExtensionFactory<span class="operator">::</span>createExtension(<span class="type"><a href="../qtcore/qobject.html">QObject</a></span> <span class="operator">*</span>object<span class="operator">,</span>
<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>iid<span class="operator">,</span> <span class="type"><a href="../qtcore/qobject.html">QObject</a></span> <span class="operator">*</span>parent) <span class="keyword">const</span>
{
<span class="keyword">if</span> (iid <span class="operator">!</span><span class="operator">=</span> Q_TYPEID(<span class="type"><a href="qdesignercontainerextension.html">QDesignerContainerExtension</a></span>))
<span class="keyword">return</span> <span class="number">0</span>;
<span class="keyword">if</span> (MyCustomWidget <span class="operator">*</span>widget <span class="operator">=</span> qobject_cast<span class="operator"><</span>MyCustomWidget<span class="operator">*</span><span class="operator">></span>
(object))
<span class="keyword">return</span> <span class="keyword">new</span> MyContainerExtension(widget<span class="operator">,</span> parent);
<span class="keyword">return</span> <span class="number">0</span>;
}</pre>
<p>or you can use an existing factory, expanding the <a href="qextensionfactory.html#createExtension">QExtensionFactory::createExtension</a>() function to enable the factory to create your custom extension as well:</p>
<pre class="cpp"><span class="type"><a href="../qtcore/qobject.html">QObject</a></span> <span class="operator">*</span>AGeneralExtensionFactory<span class="operator">::</span>createExtension(<span class="type"><a href="../qtcore/qobject.html">QObject</a></span> <span class="operator">*</span>object<span class="operator">,</span>
<span class="keyword">const</span> <span class="type"><a href="../qtcore/qstring.html">QString</a></span> <span class="operator">&</span>iid<span class="operator">,</span> <span class="type"><a href="../qtcore/qobject.html">QObject</a></span> <span class="operator">*</span>parent) <span class="keyword">const</span>
{
MyCustomWidget <span class="operator">*</span>widget <span class="operator">=</span> qobject_cast<span class="operator"><</span>MyCustomWidget<span class="operator">*</span><span class="operator">></span>(object);
<span class="keyword">if</span> (widget <span class="operator">&</span><span class="operator">&</span> (iid <span class="operator">=</span><span class="operator">=</span> Q_TYPEID(<span class="type"><a href="qdesignertaskmenuextension.html">QDesignerTaskMenuExtension</a></span>))) {
<span class="keyword">return</span> <span class="keyword">new</span> MyTaskMenuExtension(widget<span class="operator">,</span> parent);
} <span class="keyword">else</span> <span class="keyword">if</span> (widget <span class="operator">&</span><span class="operator">&</span> (iid <span class="operator">=</span><span class="operator">=</span> Q_TYPEID(<span class="type"><a href="qdesignercontainerextension.html">QDesignerContainerExtension</a></span>))) {
<span class="keyword">return</span> <span class="keyword">new</span> MyContainerExtension(widget<span class="operator">,</span> parent);
} <span class="keyword">else</span> {
<span class="keyword">return</span> <span class="number">0</span>;
}
}</pre>
<a name="accessing-qt-designer-s-extension-manager"></a>
<h3>Accessing Qt Designer's Extension Manager</h3>
<p>When implementing a custom widget plugin, you must subclass the <a href="qdesignercustomwidgetinterface.html">QDesignerCustomWidgetInterface</a> to expose your plugin to <i>Qt Designer</i>. This is covered in more detail in the <a href="designer-creating-custom-widgets.html">Creating Custom Widgets for Qt Designer</a> section. The registration of an extension factory is typically made in the <a href="qdesignercustomwidgetinterface.html#initialize">QDesignerCustomWidgetInterface::initialize</a>() function:</p>
<pre class="cpp"><span class="type">void</span> MyPlugin<span class="operator">::</span>initialize(<span class="type"><a href="qdesignerformeditorinterface.html">QDesignerFormEditorInterface</a></span> <span class="operator">*</span>formEditor)
{
<span class="keyword">if</span> (initialized)
<span class="keyword">return</span>;
<span class="type"><a href="qextensionmanager.html">QExtensionManager</a></span> <span class="operator">*</span>manager <span class="operator">=</span> formEditor<span class="operator">-</span><span class="operator">></span>extensionManager();
Q_ASSERT(manager <span class="operator">!</span><span class="operator">=</span> <span class="number">0</span>);
manager<span class="operator">-</span><span class="operator">></span>registerExtensions(<span class="keyword">new</span> MyExtensionFactory(manager)<span class="operator">,</span>
Q_TYPEID(<span class="type"><a href="qdesignertaskmenuextension.html">QDesignerTaskMenuExtension</a></span>));
initialized <span class="operator">=</span> <span class="keyword">true</span>;
}</pre>
<p>The <tt>formEditor</tt> parameter in the <a href="qdesignercustomwidgetinterface.html#initialize">QDesignerCustomWidgetInterface::initialize</a>() function is a pointer to <i>Qt Designer</i>'s current <a href="qdesignerformeditorinterface.html">QDesignerFormEditorInterface</a> object. You must use the <a href="qdesignerformeditorinterface.html#extensionManager">QDesignerFormEditorInterface::extensionManager</a>() function to retrieve an interface to <i>Qt Designer</i>'s extension manager. Then you use the <a href="qextensionmanager.html#registerExtensions">QExtensionManager::registerExtensions</a>() function to register your custom extension factory.</p>
<a name="related-examples"></a>
<h2>Related Examples</h2>
<p>For more information on creating custom widget extensions in <i>Qt Designer</i>, refer to the <a href="qtdesigner-taskmenuextension-example.html">Task Menu Extension</a> and <a href="qtdesigner-containerextension-example.html">Container Extension</a> examples.</p>
</div>
<!-- @@@designer-creating-custom-widgets-extensions.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="designer-creating-custom-widgets.html">Creating Custom Widgets for Qt Designer</a>
<a class="nextPage" href="designer-ui-file-format.html">Qt Designer's UI File Format</a>
</p>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Digia, Qt and their respective logos are trademarks of Digia Plc in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|