To get us started doing something useful with Qt Designer, we are going to build a simple program that will show you the power of Qt Designer and KDevelop. I hope that this will help you to create your first "real" KDE application.
KDevelop will help you to build a complete KDE application. The KDE project uses the autoconf and automake tools for KDE 3.x, and KDevelop will provide you with all the necessary files (admin directory, Makefile.cvs, Makefile.am,...).
Qt Designer is part of the qt-3.2.x package and above. If you have an older Qt on your system, you should get at least this version. At the time of writing, Qt latest version is 3.3.2.
Please remember to check if you have all the qt-related packages installed. You need the qt headers in order to compile this tutorial application. These headers usually come in the devel package. You also need to be sure you have designer. In some distributions, it comes in a separate package.
To check if you have everything, do a:
If you get something like /usr/lib/qt3/include/qstring.h then you can set your QTDIR variable to /usr/lib/qt3/. In bash environment, this is done by typing:
export QTDIR= /usr/lib/qt3
For an explanation for how to use anonymous SVN, get the qt-copy and kde modules and compile them, please see a great documentation at Using Subversion with KDE.
You must then set the QTDIR environment variable. This should point to the directory into which you installed Qt. In bash, for example, you would type:
export QTDIR= /usr/local/qt
provided that /usr/local/qt is the directory into which you installed Qt. Please read the INSTALL file for more details.
You then compile by issuing the following commands, here is the recommended compile line:
./configure -system-zlib -qt-gif -system-libpng -system-libjpeg \
-plugin-imgfmt-mng -thread -no-exceptions -debug -fast
The command make install is not needed.
Qt Designer is located in the bin directory of your Qt installation directory. You can run it by typing:
in a console.
KDevelop 3 should be part of your distribution. Pre 3 versions of KDevelop were nicknamed Gideon, but they are obsolete now.
KDevelop can be downloaded from the KDevelop website, under the Quick download heading.
To compile KDevelop 3, you need qt-3.1.0 or higher and kdelibs-3.1.0 or higher. The environment variables QTDIR and KDEDIR should point to those directories.
Don't forget to set up the KDE and Qt paths. The most common errors while using KDevelop come from the environment variables not set up properly. Check in a console by issuing the command set to see all your environment variables. You should set your PATH variable as follow as well as your LD_LIBRARY_PATH:
If you have any problem getting KDevelop running, please refer to the KDevelop Forum to find the answer to your problem.
If you never used KDevelop before, try to create a new project and to compile it to get used to the interface and the icons.
The framework in which our program will sit in (i.e. the main window) can be done easily and quickly by using KDevelop. Start KDevelop and select New Project in the Project menu. The Application Wizard appears then. Choose a C++ -> KDE -> Simple KDE Application. Fill in the blank lines with the project name SigCreate, your name as author, and your email. Refer to this screen shot as a reference.
Click on Next. Have a look to the CVS option and the header templates. Then click on Finish on the last screen. KDevelop creates all the files that you need to compile your project. You can use the file selector to view the code of the 3 files which are main.cpp, sigcreate.cpp and sigcreate.h, as shown here.
Once the Application Wizard has created your application, compile it to ensure that everything is fine. To do that, select Build -> Run automake & friends then Build -> Run configure. The Messages output window should say
" Good - your configure finished. Start make now
so you can run make with Build -> Build Project (or using the F8 shortcut). Then Build -> Install. Then Build -> Execute program (or F9). The result is shown here.
Qt Designer is a tool for designing and implementing user interfaces. It helps you arranging your widgets on a form and adding a proper layout so your interface can be resized properly. I recommend that you read the Qt Designer manual to know everything about Qt Designer. Qt Designer includes a code editor but we'll use KDevelop to edit and modify all code.
We will now create the interface of our application using Qt Designer. A form from Qt Designer is saved with a .ui extension because it is then processed by the uic program to generate a .h and .cpp files. KDevelop takes care of that, the only thing we need to do is to create the form.
In KDevelop, click on File -> New and fill the dialog window that appears. First write the file name: sigcreatedlg and select what new file you want in the combobox: here we want a Widget (.ui). Please be sure that Add to project is checked, this ensures that the Makefile.am is updated. Refer to this screen shot.
Click the OK button. The Automake manager dialog then pops up. Click the OK button for this dialog as well.
If the new file sigcreatedlg.ui is not open in Qt Designer, open the Automake Manager, right-click on the file and select Open With, then Qt Designer. Qt Designer will open.
The Qt Designer interface is essentially split into three areas. On the left is the toolbox, where you can select your widgets. On the right, several dialogs can be selected. I'll keep only the Property Editor dialog (I close the 2 others). Your widgets can be fine tuned to behave how you want them to. You can choose the size of the widget, its background color (palette), and so on. Between those 2 windows is the Form, your program window, within which you will design your user interface.
Each time you want to use Qt Designer, you should have a precise visual idea of the design of your interface. You can see in this picture what the program will be like. It is a window with a number of different items (or widgets) on it, designed so that the user puts the right information in the right boxes. You should always design your program from the user's point of view, as it must be easy to use.
This application creates an email signature, which is then displayed on the screen. The user should enter her/his name, email address, and then select one of three comments. When you click the Create! button, the generated signature is shown in a MultiLineEdit. When you click Cancel, the program quits.
Go back to the Qt Designer window with the new dialog open. You will see that the property editor has been filled with details about the form you have created. The first line in the Property Editor shows the name of the form which is Form1. Click on the field with this name to change it and type SigCreateDlg. This will form the class name of the dialog so you should name it something useful.
To change properties, select the property you wish to change, then alter its setting on the right. Change the Caption property to "SigCreateDlg v.01". We will now begin to add widgets on our dialog.
To start, we will insert the text at the top of the program window, which can be seen here. This text tells the user how to operate the program. This type of widget is called a Label and you can put one on your program like this:
You follow pretty much the same procedure for embedding any type of widget that is supported by Qt Designer; select it, drag it, and finally, change its properties and size.
An interesting concept in Qt Designer is that widgets can act as containers for other widgets. This will be demonstrated in our next task, which is to create the input fields inside the frame. You can see that in Picture 8 we have a bunch of labels and text boxes inside a frame. This frame is called a Group Box and acts as a container for the labels and text boxes inside it. Let's first create the frame by selecting the GroupBox in the Toolbox dialog->Containers or Tools->Containers->GroupBox from the menubar. You can drag the mouse to create the box just below the Label you put before. In the Property Editor you can change the title property to alter the text in the frame. Put Details in the title text field. You may notice a + symbol in this entry in the Property Editor. This indicates that the property has subproperties that can also be changed.
Once you have created the frame (i.e the GroupBox), create three more labels as before but when you draw them, draw them inside the GroupBox frame. You can then see in the Object Explorer box (Windows menu -> Views -> Object Explorer) to the right that the labels have become children of the GroupBox frame. See this image.
Change the text of labels by double-clicking on it.
Once you have done this you can then create the text boxes. They will allow the user to type in text like his(her) name and email address. We use the simplest type of text boxes: a widget called QLineEdit which allows the user to enter one line of text only. You have to create two QLineEdit widgets for the name and the email address. You choose the menu Tools then the entry Input then LineEdit and you draw it beside the 'Your Name' Label. Do the same below for the address.
The witty comment will be selected by the user. We use a ComboBox which will present the user with three comments. Click on the ComboBox icon or select it via the Tools-> Input-> ComboBox menu. Draw it beside the Witty Comment label. Then double-click on it. You will be presented with a box into which you can add the contents of the combo box. Click on the 'New Item' button and type in your comment in the text box at the right. Then click again on 'New Item' for the second and third comments. Click on OK when you have finished.
Adjust the size of the different widgets so they are nicely placed.
Up to now, we have not named any of the widgets that are being placed in our program. It is useful to set an internal name for widgets so we can call them after in the program. Labels don't perform any action so they don't need to be named but other widgets do. It is the case now for our text boxes. We'll need to manipulate the data from the three input widgets (i.e. read the text) so we should give them a name. Names should be easily recognized later and they should make sense. The names are assigned via the name property on the top of the Property Editor. We name the top LineEdit nameBox and the second one mailBox. We name the ComboBox commBox. This will allow us to access the comments. So click on each LineEdit and then besides Name in the Property Editor write nameBox and mailBox. Then click on the ComboBox and name it commBox.
We finish the graphical design by adding a label with 'Generated Signature' as text. Below it, we put a TextEdit (Tools->Input->TextEdit') where the generated signature will be displayed. We name it 'sigBox'. And then we add two PushButtons at the bottom ('Create!' and 'Cancel'). They don't need names but you can give them some if you want.
Save your form. You can now have a quick preview by selecting the menu Preview-> Preview Form. This is the form before layout management.