<tdalign="right"valign="center"><imgsrc="logo32.png"align="right"width="64"height="32"border="0"></td></tr></table><palign="right">[<ahref="designer-manual-1.html">Prev: Preface</a>] [<ahref="designer-manual.html">Home</a>] [<ahref="designer-manual-3.html">Next: Creating a Main Window Application</a>]</p>
<p>This chapter provides a quick start for users of <em>TQt Designer</em>. The chapter takes you step-by-step through the creation of a small dialog-style metric conversion application. It introduces many of the common tasks users perform when creating an application: adding widgets to a form, setting widget properties, making connections between signals and slots, laying out widgets, and adding custom code. This chapter only covers a portion of <em>TQt Designer</em>'s functionality; explanations and details are mostly left for the more detailed <tt>colortool</tt> tutorial presented in chapters two and three.</p>
<h3><aname="1"></a>Starting and Exiting <em>TQt Designer</em></h3>
<h4><aname="1-1"></a>Starting <em>TQt Designer</em> under Windows</h4>
<p>To start <em>TQt Designer</em> under Windows, click the <b>Start</b> button then select <b>Programs|TQt X.x.x|Designer</b>. (X.x.x is the TQt version number, e.g. 3.3.1.)</p>
<h4><aname="1-2"></a>Starting <em>TQt Designer</em> under Unix or Linux</h4>
<p><em>TQt Designer</em> may be started in a number of ways, depending on the desktop environment you are using:</p>
<ul><li><p>If there is a <em>TQt Designer</em> icon on the desktop background, you may double click this to start <em>TQt Designer</em>.</p>
<li><p>For desktop environments which feature a <b>Start</b> menu, there may be a <em>TQt Designer</em> item in the relevant submenu; try looking for a <em>TQt Designer</em> entry in the "Programming" or "Development" submenus, and select this.</p>
<li><p>Entering <tt>designer</tt> in a terminal window will also start <em>TQt Designer</em>.</p>
</ul><h4><aname="1-3"></a>Starting <em>TQt Designer</em> under Mac OS X</h4>
<p>Double click on <em>TQt Designer</em> in the Finder.</p>
<h4><aname="1-4"></a>Exiting</h4>
<p>When you have finished using <em>TQt Designer</em>, just click <b>File|Exit</b>. If you have unsaved work, <em>TQt Designer</em> will ask you whether you wish to save or discard any changes.</p>
<h3><aname="2"></a>Creating the Project</h3>
<p>Start <em>TQt Designer</em> now. When <em>TQt Designer</em> starts, it shows the <em>New/Open</em> dialog. We will open this dialog ourselves, so click <b>Cancel</b> to close it.</p>
<p>Our metric conversion application is a standard C++ application, so we must create a C++ project, and add our files and code to this project.</p>
<p>Create the new project as follows:</p>
<ul><li><p>Click <b>File|New</b> to invoke the <em>New File</em> dialog.</p>
<li><p>Click "C++ Project" to create a C++ project then click <b>OK</b> to pop up the <em>Project Settings</em> dialog.</p>
<li><p>Click the <b>ellipsis (...)</b> button next to the Project File line edit to invoke the <em>Save As</em> dialog. Use this dialog to navigate to where you want to create the new project, creating a new folder for it (called "metric") using the <b>Create New Folder</b> toolbar button.</p>
<li><p>Enter a filename of "metric.pro" then click <b>Save</b>; the project's name will now be "metric".</p>
<li><p>Click <b>OK</b> to close the <em>Project Settings</em> dialog.</p>
<li><p>Click <b>File|Save</b> to save the project.</p>
<p>See also <ahref="designer-manual-3.html#creating-the-project">Creating the Project</a>.</p>
<h3><aname="3"></a>Creating the Dialog</h3>
<ul><li><p>Click <b>File|New</b> to invoke the <em>New File</em> dialog.</p>
<li><p>Click "Dialog" then click <b>OK</b>.</p>
<li><p>Drag a corner of the new form to make it a lot smaller.</p>
<li><p>Change the form's name (in the <ahref="designer-manual-3.html#using-the-property-editor-sidebar">Property Editor</a>) to "ConversionForm", and change its caption to "Metric Conversion".</p>
<li><p>Click <b>File|Save</b>, accept the default form name, and click <b>Save</b> to save it.</p>
<p>See also <ahref="designer-manual-4.html">Creating Dialogs</a> and <ahref="designer-manual-4.html#layouts-subsection">Layouts</a>.</p>
<h4><aname="3-1"></a>Adding Widgets to the Dialog</h4>
<h5><aname="3-1-1"></a>Adding Text Labels</h5>
<ul><li><p>Click the <b>Common Widgets</b> button listed in the Toolbox toolbar at the left of <em>TQt Designer</em>'s main window.</p>
<li><p>Double click the <b>TextLabel</b> button then click inside the dialog near the top left corner.</p>
<li><p>Click four more times below the top text label until you have five labels from top to bottom. Don't worry about exact placement of the labels since the layout tools will handle this automatically.</p>
<li><p>Click the <b>Pointer</b> toolbar button to deselect the text label.</p>
</ul><p>See also <ahref="designer-manual-4.html#adding-the-widgets-subsection">Adding the Widgets</a>.</p>
<p>We will change the properties of the text labels to suit the application. This will make them easier to refer to later.</p>
<ul><li><p>Click on the text label that is closest to the top of the dialog. Go to the <em>Property Editor</em> window, and change the label's <em>text</em> property to "Enter &Number:". The & (ampersand) makes the following letter an Alt key accelerator (keyboard shortcuts).</p>
<li><p>Click the second label. Change the label's <em>text</em> property to "Convert &From:".</p>
<li><p>Click the third label. Change the label's <em>text</em> property to "Convert &To:".</p>
<li><p>Click the fourth label. Change the label's <em>text</em> property to "Result:".</p>
<li><p>Click the fifth label. Change the label's <em>text</em> property to "&Decimals:".</p>
<p>See also <ahref="designer-manual-3.html#using-the-property-editor-sidebar">Using the Property Editor</a>.</p>
<h5><aname="3-1-2"></a>Adding Line Edits, Comboboxes, and Spinboxes</h5>
<ul><li><p>Click the <b>Common Widgets</b> button listed in the Toolbox toolbar at the left of <em>TQt Designer</em>'s main window.</p>
<li><p>Click the <b>LineEdit</b> button and then click to the right of the Enter Number label. Change its <em>name</em> property to "numberLineEdit". Change the <em>hAlign</em> property to AlignRight and change <em>vAlign</em> to AlignTop. Change the <em>font</em> property to use a bold variant by expanding it and adjusting the value in its <em>bold</em> subsection. Finally, change <em>wordwrap</em> to False. Note that whenever you click a widget, its properties appear in the <em>Property Editor</em>.</p>
<li><p>Double click the <b>ComboBox</b> button, and click to the right of the Convert From label. Now click to the right of the "Convert To" label. Click the <b>Pointer</b> toolbar button to deselect the ComboBox. Change the <em>name</em> property of the first combobox to "fromComboBox". Change the <em>name</em> property of the second to "toComboBox".</p>
<li><p>Click the <b>LineEdit</b> button then click to the right of the "Result" label. Change its <em>name</em> property to "resultLineEdit". Change the <em>paletteBackgroundColor</em> property to a shade of yellow and modify the <em>font</em> property to use a bold variant (just to make the result stand out). Change <em>hAlign</em> to AlignRight, <em>vAlign</em> to AlignVCenter, and <em>wordwrap</em> to False. Now change the <em>readOnly</em> property to "True".</p>
<li><p>Click the <b>SpinBox</b> button then click to the right of the Decimals label. Place the SpinBox below the right side of the resultLineEdit. Change the spinbox's <em>name</em> property to "decimalsSpinBox". Change its <em>max value</em> property to "6", and the <em>value</em> to "3".</p>
<p>A widget that does not accept focus itself, e.g. a <ahref="ntqlabel.html">TQLabel</a>, can have an accelerator that will pass the focus to its "buddy", e.g. a <ahref="ntqlineedit.html">TQLineEdit</a>. In <em>TQt Designer</em>, we enable this by setting the first widget's <em>buddy</em> property to the name of the buddy widget.</p>
<ul><li><p>Click the <b>Set Buddy</b> toolbar button (or press <b>F12</b>). Click the Enter Number label, drag the line to the numberLineEdit, then release.</p>
<li><p>Click the <b>Set Buddy</b> toolbar button. Click the Convert From label, drag the line to the fromComboBox, then release.</p>
<li><p>Click the <b>Set Buddy</b> toolbar button. Click the Convert To label, drag the line to the toComboBox, then release.</p>
<li><p>Click the <b>Set Buddy</b> toolbar button. Click the Decimals label, drag the line to the decimalsSpinBox, then release.</p>
<p>We need to add spacers to absorb redundant space in our dialog, so that it will lay out nicely at any size. Usually spacers are added as you experiment with the layout but, since this is a quick guide to <em>TQt Designer</em>, and we already know that they will be needed, we will add the spacers now.</p>
<ul><li><p>Click the <b>Common Widgets</b> button in the Toolbox.</p>
<li><p>Click the <b>Spacer</b> button. Click to the right of the "Decimal" label, drag right towards the spinbox, then release. A horizontal spacer will appear.</p>
<li><p>Click the <b>Spacer</b> button again. Click to the right of the Calculate push button, drag right towards the Quit push button, then release.</p>
<li><p>Click the <b>Spacer</b> button. Click just below the spin box, drag vertically towards the buttons, then release. This time, a vertical spacer will appear.</p>
<ul><li><p>Right click the toComboBox then click <b>Edit</b> from the context menu.</p>
<li><p>Delete the "New Item" text, and type "Miles".</p>
<li><p>Click <b>New Item</b>, and change the text to "Yards".</p>
<li><p>Click <b>New Item</b>, and change the text to "Feet".</p>
<li><p>Click <b>New Item</b>, and change the text to "Inches".</p>
<li><p>Click <b>OK</b> to close the Edit Listbox dialog.</p>
</ul><h4><aname="3-2"></a>Laying Out the Dialog</h4>
<p>We will lay out the text labels with their corresponding widgets first, and lay out the push buttons last.</p>
<ul><li><p>Click the decimalsSpinBox, and press <b>Shift+Click</b> on the spacer next to it.</p>
<li><p>Click the <b>Lay Out Horizontally</b> (<b>Ctrl+H</b>) toolbar button.</p>
<li><p>Click the form to deselect anything that's selected.</p>
<li><p>Click the form to the left of the Decimals text label, drag the rubber band so that all the widgets above the vertical spacer are selected, then release.</p>
<li><p>Click the <b>Lay Out in a Grid</b> (<b>Ctrl+G</b>) toolbar button.</p>
<li><p>Click the Clear push button in the <em>Object Explorer</em> window (Objects tab) then <b>Shift+Click</b> the Calculate push button, the Quit push button, and the Spacer between the push buttons.</p>
<li><p>Click the <b>Lay Out Horizontally</b> toolbar button.</p>
<p>See also <ahref="designer-manual-4.html#laying-out-the-widgets-subsection">Laying Out the Widgets</a>.</p>
<h5><aname="3-2-1"></a>Tab Order</h5>
<p>We should make sure that our dialog's tab order is set correctly.</p>
<ul><li><p>Click the <b>Tab Order</b> toolbar button. A number in a blue circle will appear next to every widget that can accept the keyboard focus.</p>
<li><p>Click every widget in turn in the order you want them to accept the keyboard focus.</p>
<li><p>Press <b>Esc</b> to leave tab order mode.</p>
<p>See also <ahref="designer-manual-4.html#changing-the-tab-order-sidebar">Changing the Tab Order</a>.</p>
<h4><aname="3-3"></a>Previewing the Dialog</h4>
<p>To preview the dialog, press <b>Ctrl+T</b> or click <b>Preview|Preview Form</b> from the menubar. Try dragging the corner of the dialog to adjust the size. Note that the the widgets always stay in proportion no matter what size you make the dialog. Check the tab order of the widgets by pressing the <b>Tab</b> key.</p>
<h4><aname="3-4"></a>Connecting the Widgets</h4>
<p>We need to connect three buttons: the Clear button, the Calculate button, and the Quit button. We also need to connect some of the other widgets. For convenience, we can make all of our connections at once using the <em>View and Edit Connections</em> dialog.</p>
<p>We will now connect our clearButton:</p>
<ul><li><p>Click <b>Edit|Connections</b> to invoke the <em>View and Edit Connections</em> dialog.</p>
<li><p>Click <b>New</b> to enter a new connection.</p>
<li><p>For the first connection, select clearPushButton for the Sender, clicked() for the Signal, numberLineEdit for the Receiver, and clear() for the Slot.</p>
<li><p>Click <b>New</b> again.</p>
<li><p>Select clearPushButton for the Sender, clicked() for the Signal, resultLineEdit for the Receiver, and clear() for the Slot.</p>
<li><p>Click <b>New</b> again.</p>
<li><p>Select clearPushButton for the Sender, clicked() for the Signal, numberLineEdit for the Receiver, and setFocus() for the Slot.</p>
</ul><p>We want to connect the calculate button and the other widgets, but the slot we want to use is not listed in the combobox. We will need to create a new slot so that we can select it from the list to complete our connections.</p>
<ul><li><p>Click <b>New</b>.</p>
<li><p>Select calculatePushButton for the Sender, clicked() for the Signal, and ConversionForm for the Receiver.</p>
<li><p>Click <b>Edit Slots</b> to invoke the <em>Edit Functions</em> dialog.</p>
<li><p>Click <b>New Function</b>.</p>
<li><p>Type over the Function name with the name of our new function: convert().</p>
<li><p>Click <b>OK</b>.</p>
<li><p>Select convert() from the Slot combobox to complete our connection.</p>
<p>Click <b>OK</b> to exit the View and Edit Connections dialog.</p>
<p>Click <b>Save</b> to save the project.</p>
<h3><aname="4"></a>Coding the Dialog</h3>
<p>Click "conversionform.ui.h" in the <em>Project Overview</em> window to invoke the code editor. We will implement the <tt>convert()</tt> and <tt>init()</tt> functions. For faster implementation, copy the code from this section and then follow the brief explanations below:</p>
<p>First, we define some enums for the input and output units. Then we retrieve the input from the numberLineEdit. We convert the input to millimeters because this is the most precise metric unit we support. Then we convert it to inches which is the most precise output unit we support. We then scale it to the selected output unit. Finally, we put the result in the resultLineEdit.</p>
<p>Next, we will implement the <tt>init()</tt> function which is called when the dialog is created.</p>
<pre> void ConversionForm::init()
{
numberLineEdit->setValidator( new <ahref="qdoublevalidator.html">TQDoubleValidator</a>( numberLineEdit ) );
<p>For this function, we set a validator on the numberLineEdit so that the user can only input numbers. To be able to do this, we also need to add <tt>#include <ntqvalidator.h></tt> at the top of the "conversionform.ui.h" file, before the <tt>init()</tt> function. Lastly, we set the initial input.</p>
<p>We are almost ready to run the application. Before we compile the application, we need a <tt>main.cpp</tt> file.</p>
<ul><li><p>Click <b>File|New</b> to open the New File dialog.</p>
<li><p>Click C++ Main File (<tt>main.cpp</tt>) then click <b>OK</b>.</p>
<li><p>Accept the default selections for the Configure Main-File dialog.</p>
<li><p>Click <b>Save</b> to save the project.</p>
</ul><p>Compiling and Running the Application</p>
<ul><li><p>Start or switch to a console, and navigate to the directory where the project is saved.</p>
<li><p>Run <em>qmake</em> on the project file (<tt>metric.pro</tt>) by typing <tt>qmake -o Makefile metric.pro</tt>.</p>
<li><p>Run <em>make</em> (or <em>nmake</em> depending on your system).</p>
<li><p>After the project has compiled, run the application.</p>
</ul><h3><aname="5"></a>Wrapping Up</h3>
<p>In this brief introduction to <em>TQt Designer</em>, we have covered the basic tasks involved in creating a simple dialog-style application. The user should now be able to add widgets to a form, set widget properties, connect signals and slots, lay out the form, and add custom code. We have ignored many of the details, and deferred some explanations until later chapters. The next two chapters provide a tutorial that covers the development of a small but complete application, and the reference chapters complete the detailed coverage.</p>
<!-- eof -->
<palign="right">[<ahref="designer-manual-1.html">Prev: Preface</a>] [<ahref="designer-manual.html">Home</a>] [<ahref="designer-manual-3.html">Next: Creating a Main Window Application</a>]</p>
