<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /home/reggie/tmp/qt-3.1-reggie-23625/qt-x11-free-3.1.1/tools/designer/book/chap-quickstart2.leaf:3 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Quick Start</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-1.html">Prev: Preface</a>] [<a href="designer-manual.html">Home</a>] [<a href="designer-manual-3.html">Next: Creating a Main Window Application</a>]</p>
<h2 align="center">Quick Start</h2>
<p>This chapter provides a quick start for users of <em>Qt Designer</em>. The chapter takes you step-by-step through the creation of a small dialog-style metric conversion application. It introduces adding widgets to a form, setting widget properties, making signals and slots connections, laying out and adding custom code. This chapter only covers a proportion of <em>Qt Designer</em>'s functionality and explanations and details are mostly left for the more detailed <tt>colortool</tt> tutorial presented in chapters two and three.</p>
<p align="center"><img align="middle" src="qs-metric.png">
</p>
<blockquote><p align="center"><em>The Metric Conversion Dialog</em></p></blockquote>
<h3><a name="1"></a>Starting and Exiting <em>Qt Designer</em></h3>
<h4><a name="1-1"></a>Starting</h4>
<ul><li><p>To start <em>Qt Designer</em> under Windows click the <b>Start</b> button and click <b>Programs|Qt X.x.x|Designer</b>. (X.x.x is the Qt version number, e.g. 3.1.0.)</p>
<li><p>If you're running a Unix or Linux operating system you can either double click the <em>Qt Designer</em> icon or enter <tt>designer &</tt> in an xterm.</p>
<li><p>Start <em>Qt Designer</em> now. When <em>Qt Designer</em> starts, it shows the <em>New/Open</em> dialog. We'll just click <b>Cancel</b> to skip it.</p>
</ul><h4><a name="1-2"></a>Exiting</h4>
<p>When you've finished using <em>Qt Designer</em> click <b>File|Exit</b>; you will be prompted to save any unsaved changes.</p>
<h3><a name="2"></a>Creating the Project</h3>
<p>The 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, ideally creating a new folder for it (e.g. 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"; 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>
</ul><p align="center"><img align="middle" src="qs-projset.png">
</p>
<p>See also Creating the Project.</p>
<h3><a name="3"></a>Creating the Dialog</h3>
<ul><li><p>Click <b>File|New</b> to invoke the <em>New File</em> dialog, then click "Dialog", then click <b>OK</b>.</p>
<li><p>Drag a corner of the new form to make it a lot smaller. Change the form's name (in the Property Editor) to "ConversionForm", and change its caption to "Metric Conversion".</p>
<li><p>Click <b>File|Save</b>, accept the default form name, and then click <b>Save</b> to save it.</p>
</ul><p align="center"><img align="middle" src="qs-newdlg.png">
</p>
<p>See also <a href="designer-manual-4.html">Creating Dialogs</a> and Layouts.</p>
<h4><a name="3-1"></a>Adding Widgets to the Dialog</h4>
<h5><a name="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>Qt Designer</em>'s main window.</p>
<li><p>Double click the <b>TextLabel</b> button and click towards the top left of the dialog.</p>
<li><p>Click four more times below the top text label until you have 5 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 Adding the Widgets.</p>
<p>Now we will change the properties of the text labels to suit the application.</p>
<ul><li><p>Click on the top text label. Go to the <em>Property Editor</em> window and change the label's <em>text</em> property to "Enter &Number:".</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>
</ul><p align="center"><img align="middle" src="qs-txtlbl.png">
</p>
<p>See also Using the Property Editor.</p>
<h5><a name="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>Qt 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. 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 and then click to the right of the "Result" label. Change its <em>name</em> property to "resultLineEdit". Change the <em>paletteBackground</em> property to a shade of yellow (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 "False", if it isn't already.</p>
<li><p>Click the <b>SpinBox</b> button and 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>
<li><p>Click <b>File|Save</b>.</p>
</ul><p align="center"><img align="middle" src="qs-addwidg.png">
</p>
<p>Now we need to relate each of the text labels to the corresponding widget. We do this by creating "buddies".</p>
<p>A widget that does not accept focus itself, e.g. a QLabel, can have an accelerator that will pass the focus to its "buddy", e.g. a QLineEdit, 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> button (<b>F5</b>). Click the Enter Number label and drag the rubber band to the numberLineEdit; then release.</p>
<li><p>Click the <b>Set Buddy</b> button. Click the Convert From label and drag the rubber band to the fromComboBox; then release.</p>
<li><p>Click the <b>Set Buddy</b> button. Click the Convert To label and drag the rubber band to the toComboBox; then release.</p>
<li><p>Click the <b>Set Buddy</b> button. Click the Decimals label and drag the rubber band to the decimalsSpinBox; then release.</p>
</ul><h5><a name="3-1-3"></a>Adding Push Buttons</h5>
<ul><li><p>Click the <b>Common Widgets</b> button in the Toolbox.</p>
<li><p>Double click the <b>Pushbutton</b> button and click towards the bottom left of the dialog, below the Decimals label.</p>
<li><p>Click to the right of the new push button two more times so that you have three push buttons horizontally in a row at the bottom of the dialog.</p>
<li><p>Click the <b>Pointer</b> toolbar button to deselect the push button.</p>
</ul><p>We will change a few properties for each of the push buttons in the <em>Property Editor</em> window.</p>
<ul><li><p>Click the first push button starting from the left of the dialog. Change its name to "clearPushButton" and its text to "&Clear".</p>
<li><p>Click the second push button and change its name to "calculatePushButton", its text to "Calculate" and its default property to "True".</p>
<li><p>Click the third push button and change its name to "quitPushButton" and its text to "&Quit".</p>
</ul><p align="center"><img align="middle" src="qs-pushbutt.png">
</p>
<h5><a name="3-1-4"></a>Adding Spacers</h5>
<p>We need to add spacers to absorb redundant space in our dialog so that it will lay out nicely at whatever size the user resizes it to. Usually spacers are added as you experiment with the layout, but since this is a quick guide to <em>Qt Designer</em>, we will add the spacers now since we already know that they will be needed.</p>
<ul><li><p>Click the <b>Common Widgets</b> button in the Toolbox.</p>
<li><p>Click the <b>Spacer</b> button and click to the right of the Decimal label and drag right towards the spinbox; then release. A horizontal spacer will appear.</p>
<li><p>Click the <b>Spacer</b> button again and click to the right of the Calculate push button and drag right towards the Quit push button; then release.</p>
<li><p>Click the <b>Spacer</b> button and click just below the spin box and drag vertically towards the buttons; then release. A vertical spacer will appear.</p>
</ul><p align="center"><img align="middle" src="qs-spacers.png">
</p>
<p>Click <b>File|Save</b> to save the dialog.</p>
<h5><a name="3-1-5"></a>Editing Widgets</h5>
<p>We'll now edit some of the widgets to contain the values needed for the conversions.</p>
<p>The fromComboBox:</p>
<ul><li><p>Right click the fromComboBox and then click <b>Edit</b> from the context menu.</p>
<li><p>Click <b>New Item</b> and then delete the "New Item" text and type "Kilometers". Click <b>New Item</b> and change the text to "Meters". Repeat this two more times, changing the text to "Centimeters" and to "Millimeters" respectively.</p>
<li><p>Click <b>OK</b> to close the Edit Listbox dialog.</p>
</ul><p align="center"><img align="middle" src="qs-editlistbox1.png">
</p>
<p>The toComboBox:</p>
<ul><li><p>Right click the toComboBox and then click <b>Edit</b> from the context menu.</p>
<li><p>Delete the "New Item" text and type "Miles". Click <b>New Item</b> and change the text to "Yards". Repeat this two more times, changing the text to "Feet" and to "Inches".</p>
<li><p>Click <b>OK</b> to close the Edit Listbox dialog.</p>
</ul><h4><a name="3-2"></a>Laying Out the Dialog</h4>
<p>We'll lay out the text labels and their corresponding widgets first and we'll do the push buttons last.</p>
<ul><li><p>Click the decimalsSpinBox and press <b>Shift+Click</b> on the spacer next to it. Click the <b>Lay Out Horizontally</b> (<b>Ctrl+H</b>) toolbar button.</p>
<li><p>Click and hold on the form to the left of the text labels and then drag the rubber band so that it touches every label and widget and spacer except for the push buttons and the spacer between the push buttons and the spacer below the spin box. Release the rubberband and notice that the desired widgets are selected. Click the <b>Lay Out in a Grid</b> (<b>Ctrl+G</b>) toolbar button.</p>
<p align="center"><img align="middle" src="qs-laygrid.png">
</p>
<li><p>Click the Clear push button in the <em>Object Explorer</em> window (Objects tab) and then <b>Shift+Click</b> the Calculate push button, the Quit push button and the Spacer between the push buttons. Click the <b>Lay Out Horizontally</b> toolbar button.</p>
<p align="center"><img align="middle" src="qs-layhoriz.png">
</p>
<li><p>Click the form to deselect all widgets and layouts and then click the <b>Lay Out Vertically</b> (<b>Ctrl+L</b>) toolbar button.</p>
<li><p>Finally, click the dialog and then click the <b>Adjust Size</b> (<b>Ctrl+J</b>) toolbar button.</p>
</ul><p align="center"><img align="middle" src="qslayvert.png">
</p>
<p>Click <b>File|Save</b> to save the dialog.</p>
<p>See also Laying Out the Widgets.</p>
<h5><a name="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 focus.</p>
<li><p>Click every widget in turn in the order you want them to accept focus.</p>
<li><p>Press <b>Esc</b> to leave tab order mode.</p>
</ul><p align="center"><img align="middle" src="qstaborder.png">
</p>
<p>See also Changing the Tab Order.</p>
<h4><a name="3-3"></a>Previewing the Dialog</h4>
<p>To preview the dialog, press <b>Ctrl+T</b>. 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><a name="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 do all of our connections in one go 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 align="center"><img align="middle" src="qs-editconn1.png">
</p>
<p>We also need to connect the quit button to the form:</p>
<ul><li><p>Click <b>New</b>.</p>
<li><p>Select quitPushButton for Sender, clicked() for Signal, ConversionForm for Receiver, and close() for 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. Click <b>New Function</b>. Type over the Function name with the name of our new function: convert(), then click <b>OK</b>.</p>
<li><p>Select convert() from the Slot combobox to complete our connection.</p>
</ul><p align="center"><img align="middle" src="qs-editfunc.png">
</p>
<p>We will now connect the last few widgets:</p>
<ul><li><p>Click <b>New</b>.</p>
<li><p>Select decimalsSpinBox as the Sender, valueChanged(int) as the Signal, ConversionForm as the Receiver, and convert() as the Slot.</p>
<li><p>Click <b>New</b>.</p>
<li><p>Select fromComboBox as the Sender, activated(int) as the Signal, ConversionForm as the Receiver, and convert() as the Slot.</p>
<li><p>Click <b>New</b>.</p>
<li><p>Select toComboBox as the Sender, activated(int) as the Signal, ConversionForm as the Receiver, and convert() as the Slot.</p>
</ul><p align="center"><img align="middle" src="qs-editconn2.png">
</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><a name="4"></a>Coding the Dialog</h3>
<p>Click "conversionform.ui.h" in the <em>Project Overview</em> window to invoke the code editor. We'll implement the <tt>convert()</tt> function and also the <tt>init()</tt> function. For faster implementation, copy the code from this section and then follow the brief explanations below:</p>
<pre> void ConversionForm::convert()
{
enum MetricUnits {
Kilometers,
Meters,
Centimeters,
Millimeters
};
enum OldUnits {
Miles,
Yards,
Feet,
Inches
};
// Retrieve the input
double input = numberLineEdit->text().toDouble();
double scaledInput = input;
// internally convert the input to millimeters
switch ( fromComboBox->currentItem() ) {
case Kilometers:
scaledInput *= 1000000;
break;
case Meters:
scaledInput *= 1000;
break;
case Centimeters:
scaledInput *= 10;
break;
}
//convert to inches
double result = scaledInput * 0.0393701;
switch ( toComboBox->currentItem() ) {
case Miles:
result /= 63360;
break;
case Yards:
result /= 36;
break;
case Feet:
result /= 12;
break;
}
// set the result
int decimals = decimalsSpinBox->value();
resultLineEdit->setText( QString::<a href="qstring.html#number">number</a>( result, 'f', decimals ) );
numberLineEdit->setText( QString::<a href="qstring.html#number">number</a>( input, 'f', decimals ) );
}
</pre>
<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 <a href="qdoublevalidator.html">QDoubleValidator</a>( numberLineEdit ) );
numberLineEdit->setText( "10" );
convert();
numberLineEdit->selectAll();
}
</pre>
<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 <qvalidator.h></tt> at the top of the form, right above the <tt>init()</tt>. 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> and click <tt>main.cpp</tt>.</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 you saved your project.</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><a name="5"></a>Wrapping Up</h3>
<p>This application has given a very quick introduction to <em>Qt Designer</em>. It has introduced adding widgets to a form, setting widget properties, making signals and slots connections, laying out and adding custom code. Much of the detail and explanations have been deferred. 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 -->
<p align="right">[<a href="designer-manual-1.html">Prev: Preface</a>] [<a href="designer-manual.html">Home</a>] [<a href="designer-manual-3.html">Next: Creating a Main Window Application</a>]</p>
<p><address><hr><div align=center>
<table width=100% cellspacing=0 border=0><tr>
<td>Copyright © 2002
<a href="http://www.trolltech.com">Trolltech</a><td><a href="http://www.trolltech.com/trademarks.html">Trademarks</a>
<td align=right><div align=right>Qt version 3.1.1</div>
</table></div></address></body>
</html>
