14
14
<table border="0" cellpadding="0" cellspacing="0" width="100%">
16
<td align="left" valign="top" width="32"><a href="http://qtsoftware.com/products/qt"><img src="images/qt-logo.png" align="left" border="0" /></a></td>
17
<td width="1"> </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="namespaces.html"><font color="#004faf">All Namespaces</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="mainclasses.html"><font color="#004faf">Main Classes</font></a> · <a href="groups.html"><font color="#004faf">Grouped Classes</font></a> · <a href="modules.html"><font color="#004faf">Modules</font></a> · <a href="functions.html"><font color="#004faf">Functions</font></a></td>
18
<td align="right" valign="top" width="230"></td></tr></table><p>
16
<td align="left" valign="top" width="32"><a href="http://qt.nokia.com/"><img src="images/qt-logo.png" align="left" border="0" /></a></td>
17
<td width="1"> </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="functions.html"><font color="#004faf">All Functions</font></a> · <a href="overviews.html"><font color="#004faf">Overviews</font></a></td><td class="searchBar" align="right" valign="center"><form action="http://www.google.com/cse" id="cse-search-box"><div><input type="hidden" name="cx" value="000136343326384750312:dhbxnqlakyu" /><input type="hidden" name="ie" value="UTF-8" /><input type="text" name="q" size="31" /><input type="submit" name="sa" value="Search" /></div></form></td>
19
19
[Previous: <a href="porting4-dnd.html">Porting to Qt 4 - Drag and Drop</a>]
20
20
[<a href="porting.html">Contents</a>]
21
21
[Next: <a href="graphicsview-porting.html">Porting to Graphics View</a>]
23
<h1 class="title">Porting .ui Files to Qt 4<br /><span class="subtitle"></span>
23
<h1 class="title">Porting UI Files to Qt 4<br /><span class="subtitle"></span>
25
<p>Qt Designer has changed significantly in the Qt 4 release. We have moved away from viewing Qt Designer as an IDE and concentrated on creating a robust form builder which can be extended and embedded in existing IDEs. Our efforts are ongoing and include the <a href="http://www.qtsoftware.com/products/qt/indepth/vs-integration">Visual Studio Integration</a>, as well as integrating Designer with KDevelop and possibly other IDEs.</p>
26
<p>The most important changes in Qt Designer 4 which affect porting for <tt>.ui</tt> files are summarized below:</p>
25
<p>Qt Designer has changed significantly in the Qt 4 release. We have moved away from viewing Qt Designer as an IDE and concentrated on creating a robust form builder which can be extended and embedded in existing IDEs. Our efforts are ongoing and include the <a href="http://qt.nokia.com/products/developer-tools">Visual Studio Integration</a>, as well as integrating Designer with KDevelop and possibly other IDEs.</p>
26
<p>The most important changes in Qt Designer 4 which affect porting for UI files are summarized below:</p>
28
<li><b>Removed project manager.</b> Qt Designer now only reads and edits <tt>.ui</tt> files. It has no notion of a project (<tt>.pro</tt> file).</li>
28
<li><b>Removed project manager.</b> Qt Designer now only reads and edits UI files. It has no notion of a project file (<tt>.pro</tt>).</li>
29
29
<li><b>Removed code editor.</b> Qt Designer can no longer be used to edit source files.</li>
30
<li><b>Changed format of <tt>.ui</tt> files.</b> Qt Designer 4 cannot read files created by Qt Designer 3 and vice versa. However, we provide the tool <tt>uic3</tt> to generate Qt 4 code out of Qt 3 <tt>.ui</tt> files, and to convert old <tt>.ui</tt> files into a format readable by Qt Designer 4.</li>
30
<li><b>Changed format of UI files.</b> Qt Designer 4 cannot read files created by Qt Designer 3 and vice versa. However, we provide the tool <tt>uic3</tt> to generate Qt 4 code out of Qt 3 UI files, and to convert old UI files into a format readable by Qt Designer 4.</li>
31
31
<li><b>Changed structure of the code generated by <tt>uic</tt>.</b> The <tt>myform.ui</tt> file containing the form <tt>MyForm</tt> is now converted into a single header file <tt>ui_myform.h</tt>, which contains the declaration and inline definition of a POD class <tt>Ui::MyForm</tt>.</li>
32
<li><b>New resource file system.</b> Icon data is no longer stored in the <tt>.ui</tt> file. Instead, icons are put into resource files (<tt>.qrc</tt>).</li>
32
<li><b>New resource file system.</b> Icon data is no longer stored in the UI file. Instead, icons are put into resource files (<tt>.qrc</tt>).</li>
34
34
<p>The rest of this document explains how to deal with the main differences between Qt Designer 3 and Qt Designer 4:</p>
35
35
<ul><li><a href="#uic-output">uic Output</a></li>
112
112
return app.exec();
114
114
<p>This second method is useful when porting Qt 3 forms to Qt 4. <tt>HelloWorldWidget</tt> is a class whose instance is the actual form and which contains public pointers to all the widgets in it. It therefore has an interface identical to that of a class generated by <tt>uic</tt> in Qt 3.</p>
115
<p>Creating POD classes from <tt>.ui</tt> files is more flexible and generic than the old approach of creating widgets. Qt Designer doesn't need to know anything about the main container apart from the base widget class it inherits. Indeed, <tt>Ui::HelloWorld</tt> can be used to populate any container that inherits <a href="qwidget.html">QWidget</a>. Conversely, all non-GUI aspects of the main container may be implemented by the programmer in the application's sources without reference to the form.</p>
115
<p>Creating POD classes from UI files is more flexible and generic than the old approach of creating widgets. Qt Designer does not need to know anything about the main container apart from the base widget class it inherits. Indeed, <tt>Ui::HelloWorld</tt> can be used to populate any container that inherits <a href="qwidget.html">QWidget</a>. Conversely, all non-GUI aspects of the main container may be implemented by the programmer in the application's sources without reference to the form.</p>
116
116
<a name="working-with-uic3"></a>
117
117
<h3>Working with uic3</h3>
118
118
<p>Qt 4 comes with the tool <tt>uic3</tt> for working with old <tt>.ui</tt> files. It can be used in two ways:</p>
120
120
<li>To generate headers and source code for a widget to implement any custom signals and slots added using Qt Designer 3.</li>
121
<li>To generate a new <tt>.ui</tt> file that can be used with Qt Designer 4.</li>
121
<li>To generate a new UI file that can be used with Qt Designer 4.</li>
123
<p>You can use both these methods in combination to obtain <tt>.ui</tt>, header and source files that you can use as a starting point when porting your user interface to Qt 4.</p>
123
<p>You can use both these methods in combination to obtain UI, header and source files that you can use as a starting point when porting your user interface to Qt 4.</p>
124
124
<p>The first method generates a Qt 3 style header and implementation which uses Qt 4 widgets (this includes the Qt 3 compatibility classes present in the <a href="qt3support.html">Qt3Support</a> library). This process should be familiar to anyone used to working with Qt Designer 3:</p>
125
125
<pre> uic3 myform.ui > myform.h
126
126
uic3 -impl myform.h myform.ui > myform.cpp</pre>
127
<p>The resulting files <tt>myform.h</tt> and <tt>myform.cpp</tt> implement the form in Qt 4 using a <a href="qwidget.html">QWidget</a> that will include custom signals, slots and connections specified in the <tt>.ui</tt> file. However, see below for the <a href="#limitations-of-uic3">limitations</a> of this method.</p>
127
<p>The resulting files <tt>myform.h</tt> and <tt>myform.cpp</tt> implement the form in Qt 4 using a <a href="qwidget.html">QWidget</a> that will include custom signals, slots and connections specified in the UI file. However, see below for the <a href="#limitations-of-uic3">limitations</a> of this method.</p>
128
128
<p>The second method is to use <tt>uic3</tt> to convert a Qt Designer 3 <tt>.ui</tt> file to the Qt Designer 4 format:</p>
129
129
<pre> uic3 -convert myform3.ui > myform4.ui</pre>
130
<p>The resulting file <tt>myform4.ui</tt> can be edited in Qt Designer 4. The header file for the form is generated by Qt 4's <tt>uic</tt>. See the <a href="designer-using-a-ui-file.html">Using a Designer .ui File in Your Application</a> chapter of the <a href="designer-manual.html">Qt Designer Manual</a> for information about the preferred ways to use forms created with Qt Designer 4.</p>
130
<p>The resulting file <tt>myform4.ui</tt> can be edited in Qt Designer 4. The header file for the form is generated by Qt 4's <tt>uic</tt>. See the <a href="designer-using-a-ui-file.html">Using a Designer UI File in Your Application</a> chapter of the <a href="designer-manual.html">Qt Designer Manual</a> for information about the preferred ways to use forms created with Qt Designer 4.</p>
131
131
<p><tt>uic3</tt> tries very hard to map Qt 3 classes and their properties to Qt 4. However, the behavior of some classes changed significantly in Qt 4. To keep the form working, some Qt 3 classes are mapped to classes in the <a href="qt3support.html">Qt3Support</a> library. Table 1 shows a list of classes this applies to.</p>
132
<p><table align="center" cellpadding="2" cellspacing="1" border="0">
132
<p><table class="generic" align="center" cellpadding="2" cellspacing="1" border="0">
133
133
<thead><tr valign="top" class="qt-style"><th>Qt 3 class</th><th>Qt 4 class</th></tr></thead>
134
<tr valign="top" class="odd"><td><tt>QButtonGroup</tt></td><td><a href="q3buttongroup.html">Q3ButtonGroup</a></td></tr>
135
<tr valign="top" class="even"><td><tt>QDateEdit</tt></td><td><a href="q3dateedit.html">Q3DateEdit</a></td></tr>
136
<tr valign="top" class="odd"><td><tt>QDateTimeEdit</tt></td><td><a href="q3datetimeedit.html">Q3DateTimeEdit</a></td></tr>
137
<tr valign="top" class="even"><td><tt>QGroupBox</tt></td><td><a href="q3groupbox.html">Q3GroupBox</a></td></tr>
138
<tr valign="top" class="odd"><td><tt>QListBox</tt></td><td><a href="q3listbox.html">Q3ListBox</a></td></tr>
139
<tr valign="top" class="even"><td><tt>QListView</tt></td><td><a href="q3listview.html">Q3ListView</a></td></tr>
140
<tr valign="top" class="odd"><td><tt>QMainWindow</tt></td><td><a href="q3mainwindow.html">Q3MainWindow</a></td></tr>
141
<tr valign="top" class="even"><td><tt>QTextEdit</tt></td><td><a href="q3textedit.html">Q3TextEdit</a></td></tr>
142
<tr valign="top" class="odd"><td><tt>QTextView</tt></td><td><a href="q3textview.html">Q3TextView</a></td></tr>
143
<tr valign="top" class="even"><td><tt>QTimeEdit</tt></td><td><a href="q3timeedit.html">Q3TimeEdit</a></td></tr>
144
<tr valign="top" class="odd"><td><tt>QWidgetStack</tt></td><td><a href="q3widgetstack.html">Q3WidgetStack</a></td></tr>
145
<tr valign="top" class="even"><td><tt>QWizard</tt></td><td><a href="q3wizard.html">Q3Wizard</a></td></tr>
134
<tr valign="top" class="odd"><td><tt>QButtonGroup</tt></td><td><a href="q3buttongroup.html" class="compat">Q3ButtonGroup</a></td></tr>
135
<tr valign="top" class="even"><td><tt>QDateEdit</tt></td><td><a href="q3dateedit.html" class="compat">Q3DateEdit</a></td></tr>
136
<tr valign="top" class="odd"><td><tt>QDateTimeEdit</tt></td><td><a href="q3datetimeedit.html" class="compat">Q3DateTimeEdit</a></td></tr>
137
<tr valign="top" class="even"><td><tt>QGroupBox</tt></td><td><a href="q3groupbox.html" class="compat">Q3GroupBox</a></td></tr>
138
<tr valign="top" class="odd"><td><tt>QListBox</tt></td><td><a href="q3listbox.html" class="compat">Q3ListBox</a></td></tr>
139
<tr valign="top" class="even"><td><tt>QListView</tt></td><td><a href="q3listview.html" class="compat">Q3ListView</a></td></tr>
140
<tr valign="top" class="odd"><td><tt>QMainWindow</tt></td><td><a href="q3mainwindow.html" class="compat">Q3MainWindow</a></td></tr>
141
<tr valign="top" class="even"><td><tt>QTextEdit</tt></td><td><a href="q3textedit.html" class="compat">Q3TextEdit</a></td></tr>
142
<tr valign="top" class="odd"><td><tt>QTextView</tt></td><td><a href="q3textview.html" class="compat">Q3TextView</a></td></tr>
143
<tr valign="top" class="even"><td><tt>QTimeEdit</tt></td><td><a href="q3timeedit.html" class="compat">Q3TimeEdit</a></td></tr>
144
<tr valign="top" class="odd"><td><tt>QWidgetStack</tt></td><td><a href="q3widgetstack.html" class="compat">Q3WidgetStack</a></td></tr>
145
<tr valign="top" class="even"><td><tt>QWizard</tt></td><td><a href="q3wizard.html" class="compat">Q3Wizard</a></td></tr>
147
147
<a name="limitations-of-uic3"></a>
148
148
<h3>Limitations of uic3</h3>
149
<p>Converting Qt 3 <tt>.ui</tt> files to Qt 4 has some limitations. The most noticeable limitation is the fact that since <tt>uic</tt> no longer generates a <a href="qobject.html">QObject</a>, it's not possible to define custom signals or slots for the form. Instead, the programmer must define these signals and slots in the main container and connect them to the widgets in the form after calling <tt>setupUi()</tt>. For example:</p>
149
<p>Converting Qt 3 UI files to Qt 4 has some limitations. The most noticeable limitation is the fact that since <tt>uic</tt> no longer generates a <a href="qobject.html">QObject</a>, it's not possible to define custom signals or slots for the form. Instead, the programmer must define these signals and slots in the main container and connect them to the widgets in the form after calling <tt>setupUi()</tt>. For example:</p>
150
150
<pre> class HelloWorldWidget : public QWidget, public Ui::HelloWorld
174
<p>A quick and dirty way to port forms containing custom signals and slots is to generate the code using <tt>uic3</tt>, rather than <tt>uic</tt>. Since <tt>uic3</tt> does generate a <a href="qwidget.html">QWidget</a>, it will populate it with custom signals, slots and connections specified in the <tt>.ui</tt> file. However, <tt>uic3</tt> can only generate code from Qt 3 <tt>.ui</tt> files, which implies that the <tt>.ui</tt> files never get translated and need to be edited using Qt Designer 3.</p>
175
<p>Note also that it is possible to create implicit connections between the widgets in a form and the main container. After <tt>setupUi()</tt> populates the main container with child widgets it scans the main container's list of slots for names with the form <tt>on_<i>objectName</i>_<i>signalName</i>().</tt></p>
174
<p>A quick and dirty way to port forms containing custom signals and slots is to generate the code using <tt>uic3</tt>, rather than <tt>uic</tt>. Since <tt>uic3</tt> does generate a <a href="qwidget.html">QWidget</a>, it will populate it with custom signals, slots and connections specified in the UI file. However, <tt>uic3</tt> can only generate code from Qt 3 UI files, which implies that the UI files never get translated and need to be edited using Qt Designer 3.</p>
175
<p>Note also that it is possible to create implicit connections between the widgets in a form and the main container. After <tt>setupUi()</tt> populates the main container with child widgets it scans the main container's list of slots for names with the form <tt>on_<i>objectName</i><a href="examples-overview.html">_</a><i>signalName</i>().</tt></p>
176
176
<p>If the form contains a widget whose object name is <tt><i>objectName</i></tt>, and if that widget has a signal called <tt><i>signalName</i></tt>, then this signal will be connected to the main container's slot. For example:</p>
177
177
<pre> class HelloWorldWidget : public QWidget, public Ui::HelloWorld