diff options
Diffstat (limited to 'doc/html/designer-manual-7.html')
| -rw-r--r-- | doc/html/designer-manual-7.html | 40 |
1 files changed, 20 insertions, 20 deletions
diff --git a/doc/html/designer-manual-7.html b/doc/html/designer-manual-7.html index 472878307..539028b38 100644 --- a/doc/html/designer-manual-7.html +++ b/doc/html/designer-manual-7.html @@ -39,7 +39,7 @@ body { background: #ffffff; color: black; } <!-- 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>TQt 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>TQt 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 <a href="ntqpushbutton.html">TQPushButton</a> widgets to form the basis of our custom widget.</p> +<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 <a href="tqpushbutton.html">TQPushButton</a> 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="tqwidget-h.html">tqwidget.h</a>> @@ -65,10 +65,10 @@ body { background: #ffffff; color: black; } <a href="qhboxlayout.html">TQHBoxLayout</a> *layout = new <a href="qhboxlayout.html">TQHBoxLayout</a>( this ); layout-><a href="ntqlayout.html#setMargin">setMargin</a>( 0 ); - <a href="ntqpushbutton.html">TQPushButton</a> *rewind = new <a href="ntqpushbutton.html">TQPushButton</a>( TQPixmap( rewind_xpm ), 0, this, "vcr_rewind" ); + <a href="tqpushbutton.html">TQPushButton</a> *rewind = new <a href="tqpushbutton.html">TQPushButton</a>( TQPixmap( rewind_xpm ), 0, this, "vcr_rewind" ); layout-><a href="qboxlayout.html#addWidget">addWidget</a>( rewind ); </pre> - <p>We create a <a href="qhboxlayout.html">TQHBoxLayout</a> 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 <a href="ntqpushbutton.html">TQPushButton</a> 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> + <p>We create a <a href="qhboxlayout.html">TQHBoxLayout</a> 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 <a href="tqpushbutton.html">TQPushButton</a> 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>TEMPLATE = app LANGUAGE = C++ @@ -113,7 +113,7 @@ DBFILE = vcr.db <!-- 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 TQt's property system will provide <em>TQt 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">TQt 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>TQt 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>TQt 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>TQt Designer</em> to reflect this approach. FileChooser consists of a <a href="ntqlineedit.html">TQLineEdit</a> and a <a href="ntqpushbutton.html">TQPushButton</a>. The <a href="ntqlineedit.html">TQLineEdit</a> is used to hold a file or directory name, the <a href="ntqpushbutton.html">TQPushButton</a> is used to launch a file dialog through which the user can choose a file or directory.</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>TQt 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>TQt Designer</em> to reflect this approach. FileChooser consists of a <a href="tqlineedit.html">TQLineEdit</a> and a <a href="tqpushbutton.html">TQPushButton</a>. The <a href="tqlineedit.html">TQLineEdit</a> is used to hold a file or directory name, the <a href="tqpushbutton.html">TQPushButton</a> 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> @@ -158,13 +158,13 @@ DBFILE = vcr.db </pre> <p>The two 'set' functions are declared as public slots. <tt>setFileName()</tt> and <tt>setMode()</tt> set the filename and mode respectively. We declare a single signal, <tt>fileNameChanged()</tt>. The private slot, <tt>chooseFile()</tt> is called by the widget itself when its button is clicked.</p> <pre> private: - <a href="ntqlineedit.html">TQLineEdit</a> *lineEdit; - <a href="ntqpushbutton.html">TQPushButton</a> *button; + <a href="tqlineedit.html">TQLineEdit</a> *lineEdit; + <a href="tqpushbutton.html">TQPushButton</a> *button; Mode md; }; </pre> - <p>A pointer to <a href="ntqlineedit.html">TQLineEdit</a> and <a href="ntqpushbutton.html">TQPushButton</a>, as well as a Mode variable are held as private data.</p> + <p>A pointer to <a href="tqlineedit.html">TQLineEdit</a> and <a href="tqpushbutton.html">TQPushButton</a>, as well as a Mode variable are held as private data.</p> <h5><a name="2-1-2"></a>Coding the Implementation</h5> <p>We will work step-by-step through the implementation which is in <tt>qt/tools/designer/examples/filechooser/widget/filechooser.cpp</tt>.</p> <pre> FileChooser::FileChooser( <a href="tqwidget.html">TQWidget</a> *parent, const char *name ) @@ -175,51 +175,51 @@ DBFILE = vcr.db <pre> <a href="qhboxlayout.html">TQHBoxLayout</a> *layout = new <a href="qhboxlayout.html">TQHBoxLayout</a>( this ); layout-><a href="ntqlayout.html#setMargin">setMargin</a>( 0 ); - lineEdit = new <a href="ntqlineedit.html">TQLineEdit</a>( this, "filechooser_lineedit" ); + lineEdit = new <a href="tqlineedit.html">TQLineEdit</a>( this, "filechooser_lineedit" ); layout-><a href="qboxlayout.html#addWidget">addWidget</a>( lineEdit ); </pre> - <p>We begin by creating a horizontal box layout (<a href="qhboxlayout.html">TQHBoxLayout</a>) and add a <a href="ntqlineedit.html">TQLineEdit</a> and a <a href="ntqpushbutton.html">TQPushButton</a> to it.</p> -<pre> <a href="tqobject.html#connect">connect</a>( lineEdit, TQ_SIGNAL( <a href="ntqlineedit.html#textChanged">textChanged</a>( const <a href="tqstring.html">TQString</a> & ) ), + <p>We begin by creating a horizontal box layout (<a href="qhboxlayout.html">TQHBoxLayout</a>) and add a <a href="tqlineedit.html">TQLineEdit</a> and a <a href="tqpushbutton.html">TQPushButton</a> to it.</p> +<pre> <a href="tqobject.html#connect">connect</a>( lineEdit, TQ_SIGNAL( <a href="tqlineedit.html#textChanged">textChanged</a>( const <a href="tqstring.html">TQString</a> & ) ), this, TQ_SIGNAL( fileNameChanged( const <a href="tqstring.html">TQString</a> & ) ) ); - button = new <a href="ntqpushbutton.html">TQPushButton</a>( "...", this, "filechooser_button" ); + button = new <a href="tqpushbutton.html">TQPushButton</a>( "...", this, "filechooser_button" ); button-><a href="tqwidget.html#setFixedWidth">setFixedWidth</a>( button-><a href="tqwidget.html#fontMetrics">fontMetrics</a>().width( " ... " ) ); layout-><a href="qboxlayout.html#addWidget">addWidget</a>( button ); <a href="tqobject.html#connect">connect</a>( button, TQ_SIGNAL( <a href="ntqbutton.html#clicked">clicked</a>() ), this, TQ_SLOT( chooseFile() ) ); </pre> - <p>We connect the lineEdit's<!-- index textChanged() --> <tt>textChanged()</tt> signal to the custom widget's <tt>fileNameChanged()</tt> signal. This ensures that if the user changes the text in the <a href="ntqlineedit.html">TQLineEdit</a> this fact will be propagated via the custom widget's own signal. The button's<!-- index clicked() --> <tt>clicked()</tt> signal is connected to the custom widget's <tt>chooseFile()</tt> slot which invokes the appropriate dialog for the user to choose their file or directory.</p> + <p>We connect the lineEdit's<!-- index textChanged() --> <tt>textChanged()</tt> signal to the custom widget's <tt>fileNameChanged()</tt> signal. This ensures that if the user changes the text in the <a href="tqlineedit.html">TQLineEdit</a> this fact will be propagated via the custom widget's own signal. The button's<!-- index clicked() --> <tt>clicked()</tt> signal is connected to the custom widget's <tt>chooseFile()</tt> slot which invokes the appropriate dialog for the user to choose their file or directory.</p> <pre> <a href="tqwidget.html#setFocusProxy">setFocusProxy</a>( lineEdit ); } </pre> <p>We set the lineEdit as the focus proxy for our custom widget. This means that when the widget is given focus the focus actually goes to the lineEdit.</p> <pre> void FileChooser::setFileName( const <a href="tqstring.html">TQString</a> &fn ) { - lineEdit-><a href="ntqlineedit.html#setText">setText</a>( fn ); + lineEdit-><a href="tqlineedit.html#setText">setText</a>( fn ); } TQString FileChooser::fileName() const { - return lineEdit-><a href="ntqlineedit.html#text">text</a>(); + return lineEdit-><a href="tqlineedit.html#text">text</a>(); } </pre> - <p>The <tt>setFileName()</tt> function sets the filename in the <a href="ntqlineedit.html">TQLineEdit</a>, and the <tt>fileName()</tt> function returns the filename from the <a href="ntqlineedit.html">TQLineEdit</a>. The <tt>setMode()</tt> and <tt>mode()</tt> functions (not shown) are similarly set and return the given mode.</p> + <p>The <tt>setFileName()</tt> function sets the filename in the <a href="tqlineedit.html">TQLineEdit</a>, and the <tt>fileName()</tt> function returns the filename from the <a href="tqlineedit.html">TQLineEdit</a>. The <tt>setMode()</tt> and <tt>mode()</tt> functions (not shown) are similarly set and return the given mode.</p> <pre> void FileChooser::chooseFile() { <a href="tqstring.html">TQString</a> fn; if ( mode() == File ) - fn = TQFileDialog::<a href="tqfiledialog.html#getOpenFileName">getOpenFileName</a>( lineEdit-><a href="ntqlineedit.html#text">text</a>(), TQString::null, this ); + fn = TQFileDialog::<a href="tqfiledialog.html#getOpenFileName">getOpenFileName</a>( lineEdit-><a href="tqlineedit.html#text">text</a>(), TQString::null, this ); else - fn = TQFileDialog::<a href="tqfiledialog.html#getExistingDirectory">getExistingDirectory</a>( lineEdit-><a href="ntqlineedit.html#text">text</a>(),this ); + fn = TQFileDialog::<a href="tqfiledialog.html#getExistingDirectory">getExistingDirectory</a>( lineEdit-><a href="tqlineedit.html#text">text</a>(),this ); if ( !fn.<a href="tqstring.html#isEmpty">isEmpty</a>() ) { - lineEdit-><a href="ntqlineedit.html#setText">setText</a>( fn ); + lineEdit-><a href="tqlineedit.html#setText">setText</a>( fn ); emit fileNameChanged( fn ); } } </pre> - <p>When <tt>chooseFile()</tt> is called it presents the user with a file or directory dialog depending on the mode. If the user chooses a file or directory the <a href="ntqlineedit.html">TQLineEdit</a> is updated with the chosen file or directory and the <tt>fileNameChanged()</tt> signal is emitted.</p> + <p>When <tt>chooseFile()</tt> is called it presents the user with a file or directory dialog depending on the mode. If the user chooses a file or directory the <a href="tqlineedit.html">TQLineEdit</a> is updated with the chosen file or directory and the <tt>fileNameChanged()</tt> signal is emitted.</p> <p>Although these two files complete the implementation of the FileChooser widget it is good practice to write a test harness to check that the widget behaves as expected before attempting to put it into a plugin.</p> <h5><a name="2-1-3"></a>Testing the Implementation</h5> <!-- index main.cpp --><!-- index Forms!Creating Test Harnesses --><p>We present a rudimentary test harness which will allow us to run our custom widget. The test harness requires two files, a <tt>main.cpp</tt> to contain the FileChooser, and a <tt>.pro</tt> file to create the Makefile from. Here is <tt>qt/tools/designer/examples/filechooser/widget/main.cpp</tt>:</p> @@ -348,7 +348,7 @@ DEFINES += FILECHOOSER_IS_WIDGET return FALSE; } </pre> - <p>Copy this function changing the class name to suit your widget plugin implementation. It should return <tt>TRUE</tt> if your custom widget can contain other widgets, e.g. like <a href="ntqframe.html">TQFrame</a>, or <tt>FALSE</tt> if it must not contain other widgets, e.g. like <a href="ntqpushbutton.html">TQPushButton</a>.</p> + <p>Copy this function changing the class name to suit your widget plugin implementation. It should return <tt>TRUE</tt> if your custom widget can contain other widgets, e.g. like <a href="ntqframe.html">TQFrame</a>, or <tt>FALSE</tt> if it must not contain other widgets, e.g. like <a href="tqpushbutton.html">TQPushButton</a>.</p> <!-- index Macros!TQ_EXPORT_PLUGIN --><!-- index TQ_EXPORT_PLUGIN --><p>The <tt>TQ_EXPORT_PLUGIN</tt> macro.</p> <pre> TQ_EXPORT_PLUGIN( CustomWidgetPlugin ) </pre> |