<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.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>Qt 4.8: Using Custom Widgets with Qt Designer</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>Using Custom Widgets with Qt Designer</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<link rel="prev" href="designer-customizing-forms.html" />
<link rel="next" href="designer-creating-custom-widgets.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="designer-customizing-forms.html">Customizing Qt Designer Forms</a>
<a class="nextPage" href="designer-creating-custom-widgets.html">Creating Custom Widgets for Qt Designer</a>
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#handling-custom-widgets">Handling Custom Widgets</a></li>
<li class="level2"><a href="#promoting-widgets">Promoting Widgets</a></li>
<li class="level2"><a href="#user-defined-custom-widgets">User Defined Custom Widgets</a></li>
</ul>
</div>
<h1 class="title">Using Custom Widgets with Qt Designer</h1>
<span class="subtitle"></span>
<!-- $$$designer-using-custom-widgets.html-description -->
<div class="descr"> <a name="details"></a>
<p><i>Qt Designer</i> can display custom widgets through its extensible plugin mechanism, allowing the range of designable widgets to be extended by the user and third parties. This feature also allows <i>Qt Designer</i> to optionally support <a href="qt3support.html">Qt 3 compatibility widgets</a>. Alternatively, it is possible to use existing widgets as placeholders for widget classes that provide similar APIs.</p>
<p>Widgets from the <a href="qt3support.html">Qt3Support</a> library are made available via in <i>Qt Designer</i>'s support for custom widgets.</p>
<a name="handling-custom-widgets"></a>
<h2>Handling Custom Widgets</h2>
<p>Although <i>Qt Designer</i> supports all of the standard Qt widgets, and can be configured to handle widgets supplied in the <a href="qt3support.html">Qt3Support</a> library, some specialized widgets may not be available as standard for a number of reasons:</p>
<ul>
<li>Custom widgets may not be available at the time the user interface is being designed.</li>
<li>Custom widgets may be platform-specific, and designers may be developing the user interface on a different platform to end users.</li>
<li>The source code for a custom widget is not available, or the user interface designers are unable to use the widget for non-technical reasons.</li>
</ul>
<p>In the above situations, it is still possible to design forms with the aim of using custom widgets in the application. To achieve this, we can use the widget promotion feature of <i>Qt Designer</i>.</p>
<p>In all other cases, where the source code to the custom widgets is available, we can adapt the custom widget for use with <i>Qt Designer</i>.</p>
<a name="promoting-widgets"></a>
<h3>Promoting Widgets</h3>
<p class="centerAlign"><img src="images/designer-promoting-widgets.png" alt="" /></p><p>If some forms must be designed, but certain custom widgets are unavailble to the designer, we can substitute similar widgets to represent the missing widgets. For example, we might represent instances of a custom push button class, <tt>MyPushButton</tt>, with instances of <a href="qpushbutton.html">QPushButton</a> and promote these to <tt>MyPushButton</tt> so that <a href="uic.html">uic</a> generates suitable code for this missing class.</p>
<p>When choosing a widget to use as a placeholder, it is useful to compare the API of the missing widget with those of standard Qt widgets. For specialized widgets that subclass standard classes, the obvious choice of placeholder is the base class of the custom widget; for example, <a href="qslider.html">QSlider</a> might be used for specialized <a href="qslider.html">QSlider</a> subclasses.</p>
<p>For specialized widgets that do not share a common API with standard Qt widgets, it is worth considering adapting a custom widget for use in <i>Qt Designer</i>. If this is not possible then <a href="qwidget.html">QWidget</a> is the obvious choice for a placeholder widget since it is the lowest common denominator for all widgets.</p>
<p>To add a placeholder, select an object of a suitable base class and choose <b>Promote to ...</b> from the form's context menu. After entering the class name and header file in the lower part of the dialog, choose <b>Add</b>. The placeholder class will now appear along with the base class in the upper list. Click the <b>Promote</b> button to accept this choice.</p>
<p>Now, when the form's context menu is opened over objects of the base class, the placeholder class will appear in the <b>Promote to</b> submenu, allowing for convenient promotion of objects to that class.</p>
<p>A promoted widget can be reverted to its base class by choosing <b>Demote to</b> from the form's context menu.</p>
<a name="user-defined-custom-widgets"></a>
<h3>User Defined Custom Widgets</h3>
<p class="centerAlign"><img src="images/worldtimeclockplugin-example.png" alt="" /></p><p>Custom widgets can be adapted for use with <i>Qt Designer</i>, giving designers the opportunity to configure the user interface using the actual widgets that will be used in an application rather than placeholder widgets. The process of creating a custom widget plugin is described in the <a href="designer-creating-custom-widgets.html">Creating Custom Widgets for Qt Designer</a> chapter of this manual.</p>
<p>To use a plugin created in this way, it is necessary to ensure that the plugin is located on a path that <i>Qt Designer</i> searches for plugins. Generally, plugins stored in <tt>$QTDIR/plugins/designer</tt> will be loaded when <i>Qt Designer</i> starts. Further information on building and installing plugins can be found <a href="designer-creating-custom-widgets.html#buildingandinstallingtheplugin">here</a>. You can also refer to the <a href="plugins-howto.html">Plugins HOWTO</a> document for information about creating plugins.</p>
</div>
<!-- @@@designer-using-custom-widgets.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="designer-customizing-forms.html">Customizing Qt Designer Forms</a>
<a class="nextPage" href="designer-creating-custom-widgets.html">Creating Custom Widgets for Qt Designer</a>
</p>
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
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.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Qt and respective logos are trademarks of The Qt Company Ltd
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
