📄 designer-manual-6.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><!-- /home/reggie/tmp/qt-3.0-reggie-5401/qt-x11-commercial-3.0.5/tools/designer/book/chap-custom-controls.leaf:3 --><html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Creating Custom Widgets</title><style type="text/css"><!--h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm; }a:link { color: #004faf; text-decoration: none }a:visited { color: #672967; text-decoration: none }body { background: #ffffff; color: black; }--></style></head><body><table border="0" cellpadding="0" cellspacing="0" width="100%"><tr bgcolor="#E5E5E5"><td 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="mainclasses.html"><font color="#004faf">Main Classes</font></a> | <a href="annotated.html"><font color="#004faf">Annotated</font></a> | <a href="groups.html"><font color="#004faf">Grouped Classes</font></a> | <a href="functions.html"><font color="#004faf">Functions</font></a></td><td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><p align="right">[<a href="designer-manual-5.html">Prev: Subclassing and Dynamic Dialogs</a>] [<a href="designer-manual.html">Home</a>] [<a href="designer-manual-7.html">Next: Creating Database Applications</a>]</p><h2 align="center">Creating Custom Widgets</h2><!-- index Custom Widgets --><!-- index Widgets!Custom --><p>Custom widgets are created in code. They may comprise a combination of existing widgets but with additional functionality, slots and signals, or they may be written from scratch, or a mixture of both.</p><!-- index Previewing!Custom Widgets --><!-- index Custom Widgets!Previewing --><p><em>Qt Designer</em> provides two mechanisms for incorporating custom widgets:</p><ol type=1><li><p>The original method involves little more than completing a dialog box. Widgets incorporated this way appear as flat pixmaps when added to a form in <em>Qt Designer</em>, even in preview mode. They only appear in their true form at runtime. We'll explain how to create custom widgets using the original approach in "Simple Custom Widgets".</p><li><!-- index Plugins --><p>The new method involves embedding the widgets in a plugin. Widgets that are incorporated through plugins appear in their true form in <em>Qt Designer</em>, both when laying out the form and in preview mode. This approach provides more power and flexibility than the original method and is covered in <a href="designer-manual-6.html#2">Creating Custom Widgets with Plugins</a>.</p></ol><h3><a name="1"></a>Simple Custom Widgets</h3><!-- index Custom Widgets!Simple --><p>There are two stages to creating a custom widget. Firstly we must create a class that defines the widget, and secondly we must incorporate the widget into <em>Qt Designer</em>. Creating the widget has to be done whether we are creating a simple custom widget or a plugin, but for simple custom widgets the incorporation into <em>Qt Designer</em> is very easy.</p><p>We will create a VCR style widget comprising four buttons, rewind, play, next and stop. The widget will emit signals according to which button is clicked.</p><h4><a name="1-1"></a>Coding the Custom Widget</h4><p>A custom widget may consist of one or more standard widgets placed together in a particular combination, or may be written from scratch. We will combine some <b>QPushButton</b> widgets to form the basis of our custom widget.</p><p>We'll look at the header file, <tt>qt/tools/designer/examples/vcr/vcr.h</tt> first.</p><pre> #include <<a href="qwidget-h.html">qwidget.h</a>> class Vcr : public <a href="qwidget.html">QWidget</a> { Q_OBJECT public: Vcr( <a href="qwidget.html">QWidget</a> *parent = 0, const char *name = 0 ); ~Vcr() {} signals: void rewind(); void play(); void next(); void stop(); };</pre><!-- index Macros!Q_OBJECT --><!-- index Q_OBJECT --> <p>We include <tt>qwidget.h</tt> since we'll be deriving our custom widget from <b>QWidget</b>. We declare a constructor where the widget will be created and the four signals we want our widget to emit. Since we're using signals we must also include the <tt>Q_OBJECT</tt> macro.</p><p>The implementation is straightforward. The only function we implement is the constructor. The rest of the file consists of include statements and embedded<!-- index .xpm --> <tt>.xpm</tt> images.</p><pre> Vcr::Vcr( <a href="qwidget.html">QWidget</a> *parent, const char *name ) : <a href="qwidget.html">QWidget</a>( parent, name ) { <a href="qhboxlayout.html">QHBoxLayout</a> *layout = new <a href="qhboxlayout.html">QHBoxLayout</a>( this ); layout-><a href="qlayout.html#setMargin">setMargin</a>( 0 ); <a href="qpushbutton.html">QPushButton</a> *rewind = new <a href="qpushbutton.html">QPushButton</a>( QPixmap( rewind_xpm ), 0, this, "vcr_rewind" ); layout-><a href="qboxlayout.html#addWidget">addWidget</a>( rewind );</pre> <p>We create a <b>QHBoxLayout</b> in which we'll place the buttons. We've only shown the rewind button in the code above since all the others are identical except for the names of the buttons, pixmaps and signals. For each of the buttons we require we call the <b>QPushButton</b> constructor passing it the appropriate embedded pixmap. We then add it to the layout. Finally we connect the button's<!-- index clicked() --> <tt>clicked()</tt> signal to the appropriate <em>signal</em>. Since the<!-- index clicked() --> <tt>clicked()</tt> signals aren't specific to our widget we want to emit signals that reflect the widget's use. The <tt>rewind()</tt>, <tt>play()</tt>, etc. signals are meaningful in the context of our widget so we propagate each button's<!-- index clicked() --> <tt>clicked()</tt> signal to the appropriate widget-specific signal.</p><!-- index Forms!Creating Test Harnesses --><p>The implementation is complete, but to make sure that our widget compiles and runs we'll create a tiny test harness. The test harness will require two files, a<!-- index .pro --> <tt>.pro</tt> project file and a<!-- index main.cpp --> <tt>main.cpp</tt>. The <tt>qt/tools/designer/examples/vcr/vcr.pro</tt> project file:</p><pre>SOURCES += vcr.cpp main.cppHEADERS += vcr.hTARGET = vcrTEMPLATE =appCONFIG += qt warn_on releaseDBFILE = vcr.dbLANGUAGE = C++</pre><p>The <tt>qt/tools/designer/examples/vcr/main.cpp</tt> file is also brief:</p><pre> #include <<a href="qapplication-h.html">qapplication.h</a>> #include "vcr.h" int main( int argc, char ** argv ) { <a href="qapplication.html">QApplication</a> app( argc, argv ); Vcr *vcr = new Vcr; vcr-><a href="qwidget.html#show">show</a>(); return app.<a href="qapplication.html#exec">exec</a>(); }</pre> <p>Once we're satisfied that the custom widget compiles and runs we are ready to incorporate it into <em>Qt Designer</em>.</p><p>In <a href="designer-manual-8.html#2-2">Base-class Templates</a> the creation of a container custom widget is described.</p><h4><a name="1-2"></a>Adding the Custom Widget to Qt Designer</h4><!-- index Custom Widgets!Adding to Qt Designer --><!-- index Adding!Custom Widgets to Qt Designer --><p>Click <b>Tools|Custom|Edit Custom Widgets</b> to invoke the <em>Edit Custom Widgets</em> dialog.</p><ol type=1><li><p>Click <b>New Widget</b> so that we are ready to add our new widget.</p><li><p>Change the Class name from 'MyCustomWidget' to 'Vcr'.</p><li><p>Click the ellipsis (<b>...</b>) button to the right of the Headerfile line edit to invoke the file Open dialog. Locate <tt>vcr.h</tt>, select it, and click <b>Open</b>. It will now appear as the header file.</p><li><p>If you have a pixmap that you want to use to identify your widget on the toolbar click the ellipsis button to the right of Pixmap property. (The ellipsis button appears when you click in the Value part of the Properties list by a <em>pixmap</em> or <em>iconSet</em> property.)</p><p>In our example we have the file <tt>qt/tools/designer/examples/vcr/play.xpm</tt> which we'll use for this purpose.</p><li><p>Since we know the minimum sensible size for our widget we'll put these values into the Size Hint spin boxes. Enter a width of 80 (in the left hand spin box), and a height of 20 (in the right hand spin box).</p></ol><p>The remaining items to be completed will depend on the characteristics of the widget you've created. If, for example, your widget can be used to contain other widgets you'd check the Container Widget checkbox. In the case of our Vcr example the only items we need to add are its signals.</p><p>Click the Signals tab. Click the <b>New Signal</b> button and type in the signal name 'rewind()'. Click <b>New Signal</b> again and this time type in 'play()'. Add the 'next()' and 'stop()' signals in the same way.</p><p>Since our example hasn't any slots or properties we've finished and can click <b>Close</b>. A new icon will appear in <em>Qt Designer</em>'s toolbars which represents the new widget. If you create a new form you can add Vcr widgets and connect the Vcr's signals to your slots.</p><p>Incorporating custom widgets that have their own slots and properties is achieved in a similar way to adding signals. All the required information is in our custom widget's header file.</p><a name="creatingplugins"></a><h3><a name="2"></a>Creating Custom Widgets with Plugins</h3><!-- index Custom Widgets!Plugins --><!-- index Plugins!Implementing Custom Widgets --><p>This section will show you how to write a custom widget and how to embed the custom widget into a plugin. There are no restrictions or special considerations that must be taken into account when creating a widget that is destined to become a plugin. If you are an experienced Qt programmer you can safely skip the section on creating a custom widget and go directly to <a href="designer-manual-6.html#2-2">Creating a Plugin</a>.</p><h4><a name="2-1"></a>Creating a Custom Widget</h4><!-- index Creating Custom Widgets --><!-- index Widgets!Creating a Custom Widget --><!-- index Subclassing!Widgets --><p>A custom widget is often a specialization (subclass) of another widget or a combination of widgets working together or a blend of both these approaches. If you simply want a collection of widgets in a particular configuration it is easiest to create them, select them as a group, and copy and paste them as required within <em>Qt Designer</em>. Custom widgets are generally created when you need to add new functionality to existing widgets or groups of widgets.</p><!-- index Properties!Creating Custom Properties --><p>We have two recommendations that you should consider when creating a custom widget for a plugin:</p><ol type=1><li><p>Using Qt's property system will provide <em>Qt Designer</em> users with a direct means of configuring the widget through the property editor. (See the <a href="http://doc.trolltech.com/properties.html">Qt Properties</a> documentation.)</p><li><p>Consider making your widget's public 'set' functions into public slots so that you can perform signal-slot connections with the widget in <em>Qt Designer</em>.</p></ol><p>In the course of this chapter we will create a simple but useful widget, 'FileChooser', which we'll later make available in <em>Qt Designer</em> as a plugin. In practice most custom widgets are created to add functionality rather than to compose widgets, so we will create our widget in code rather than using <em>Qt Designer</em> to reflect this approach. FileChooser consists of a <b>QLineEdit</b> and a <b>QPushButton</b>. The <b>QLineEdit</b> is used to hold a file or directory name, the <b>QPushButton</b> is used to launch a file dialog through which the user can choose a file or directory.</p><p align="center"><img align="middle" src="filechooser.png" width="169" height="34"></p><blockquote><p align="center"><em>The FileChooser Custom Widget</em></p></blockquote><p>If you've followed the manual up to this point you may well be able to create this custom widget yourself. If you're confident that you can make your own version of the widget, or have another widget that you want to turn into a plugin, skip ahead to <a href="designer-manual-6.html#2-2">Creating a Plugin</a>. If you prefer to read how we created the widget then read on.</p><h5><a name="2-1-1"></a>Coding the Widget's Interface</h5><p>We will work step-by-step through the widget's header file, <tt>qt/tools/designer/examples/filechooser/widget/filechooser.h</tt>.</p><pre> #include <<a href="qwidget-h.html">qwidget.h</a>> class QLineEdit; class QPushButton;</pre> <p>Our widget will be derived from <b>QWidget</b> so we include the <tt>qwidget.h</tt> header file. We also forward declare the two classes that our widget will be built from.</p><pre></pre><!-- index Macros!Q_OBJECT --><!-- index Q_OBJECT --><!-- index Macros!Q_ENUMS --><!-- index Q_ENUMS --> <p>We include the <tt>Q_OBJECT</tt> macro since this is required for classes that declare signals or slots. The <tt>Q_ENUMS</tt> declaration is used to register the Mode enumeration. Our widget has two properties, mode, to store whether the user should select a File or a Directory and fileName which stores the file or directory they chose.</p><pre> class FileChooser : public <a href="qwidget.html">QWidget</a> { Q_OBJECT Q_ENUMS( Mode )⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -