|
Lines 1-1549
Link Here
|
| 1 |
<?xml version="1.0" ?> |
|
|
| 2 |
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ |
| 3 |
<!ENTITY tdevelop "<application>KDevelop</application>"> |
| 4 |
<!ENTITY kappname "&tdevelop;"> |
| 5 |
<!ENTITY % addindex "INCLUDE"> |
| 6 |
<!ENTITY % English "INCLUDE" > <!-- change language only here --> |
| 7 |
]> |
| 8 |
|
| 9 |
<book lang="&language;"> |
| 10 |
|
| 11 |
<bookinfo> |
| 12 |
<title>The &tdevelop; Programming Handbook</title> |
| 13 |
|
| 14 |
<date>2002-12-05</date> |
| 15 |
<releaseinfo>2.0</releaseinfo> |
| 16 |
|
| 17 |
<authorgroup> |
| 18 |
<author> |
| 19 |
<firstname>Ralf</firstname> |
| 20 |
<surname>Nolden</surname> |
| 21 |
<affiliation><address><email>Ralf.Nolden@post.rwth-aachen.de</email></address></affiliation> |
| 22 |
</author> |
| 23 |
<author> |
| 24 |
<firstname>Caleb</firstname> |
| 25 |
<surname>Tennis</surname> |
| 26 |
<affiliation><address><email>caleb@aei-tech.com</email></address></affiliation> |
| 27 |
</author> |
| 28 |
</authorgroup> |
| 29 |
|
| 30 |
<copyright> |
| 31 |
<year>1999</year> |
| 32 |
<holder>Ralf Nolden</holder> |
| 33 |
</copyright> |
| 34 |
<copyright> |
| 35 |
<year>2002</year> |
| 36 |
<holder>Caleb Tennis</holder> |
| 37 |
</copyright> |
| 38 |
|
| 39 |
<!-- ROLES_OF_TRANSLATORS --> |
| 40 |
|
| 41 |
<legalnotice>&FDLNotice;</legalnotice> |
| 42 |
|
| 43 |
<abstract> |
| 44 |
<para>The User Guide to C++ Application Design for the Trinity Desktop Environment (TDE) with |
| 45 |
the &tdevelop; IDE</para> |
| 46 |
</abstract> |
| 47 |
|
| 48 |
<keywordset> |
| 49 |
<keyword>KDE</keyword> |
| 50 |
<keyword>KDevelop</keyword> |
| 51 |
<keyword>IDE</keyword> |
| 52 |
<keyword>development</keyword> |
| 53 |
<keyword>programming</keyword> |
| 54 |
</keywordset> |
| 55 |
|
| 56 |
</bookinfo> |
| 57 |
|
| 58 |
<chapter id="chapter1"> |
| 59 |
<title>Introduction</title> |
| 60 |
<para> |
| 61 |
As Unix Systems are becoming more and more popular to even beginners working with computer machines |
| 62 |
due to its advantages in regards of stability and functionality, most are somehow disappointed, because |
| 63 |
those applications don't have a consistent look and each one behaves different from another. With KDE, |
| 64 |
developers have an almost perfect way to create first-class applications for Unix desktop systems to get |
| 65 |
a wider user community by the mere quality their applications have to offer. Therefore, KDE becomes more |
| 66 |
and more popular as a base for programming design, and developers want to take advantage of the |
| 67 |
possibilities that the system has to offer. |
| 68 |
</para> |
| 69 |
|
| 70 |
<sect1 id="c1s1"> |
| 71 |
<title>What you should know already</title> |
| 72 |
<para> |
| 73 |
For making the best use of this programming handbook, we assume that you already know about the |
| 74 |
C++ programming language; if not, you should make yourself familiar with that first. Information about |
| 75 |
C++ is available through various sources either in printed form at your local bookstore or by tutorials |
| 76 |
found on the Internet. Knowledge about the design of Graphical User Interfaces is not required, as this |
| 77 |
handbook tries to cover the application design for KDE programs, which also includes an introduction into |
| 78 |
the Qt toolkit as well as the KDE libraries and the design of User Interfaces. Also, you should have made |
| 79 |
yourself comfortable with &tdevelop; by reading The User Manual to &tdevelop;, which contains a descriptive |
| 80 |
review of the functionality provided by the IDE. |
| 81 |
</para> |
| 82 |
</sect1> |
| 83 |
|
| 84 |
<sect1 id="c1s2"> |
| 85 |
<title>About this Handbook</title> |
| 86 |
<para> |
| 87 |
This handbook has been written to give developers an introduction into KDE application development by |
| 88 |
using the KDevelop Integrated Development Environment. |
| 89 |
</para> |
| 90 |
<para> |
| 91 |
The following chapters therefore give an introduction on how to create projects, explains the sourcecode |
| 92 |
already generated and shows how to extend the given sources on various topics such as toolbars, menu bars |
| 93 |
and view areas. |
| 94 |
</para> |
| 95 |
<para> |
| 96 |
Then the dialogeditor is discussed in detail, explaining how widgets are created and covers widget |
| 97 |
properties settings in detail for all provided widgets. |
| 98 |
</para> |
| 99 |
<para> |
| 100 |
Finally, you will learn about several topics that will complete your knowledge in regards of project design |
| 101 |
and helps you work out additional issues besides coding such as adding API documentation and extending |
| 102 |
online-manuals. |
| 103 |
</para> |
| 104 |
<sect2 id="c1s2s1"> |
| 105 |
<title>In the next chapter</title> |
| 106 |
<para> |
| 107 |
We'll take a look at the Qt and KDE libraries, showing basic concepts and why things are the way they are. |
| 108 |
Also, we will discuss how to create the tutorial applications provided with the Qt toolkit by using |
| 109 |
tdevelop;, so beginners can already see first results with a few steps, and thereby will learn how to make |
| 110 |
use of some of &tdevelop;'s best features. |
| 111 |
</para> |
| 112 |
</sect2> |
| 113 |
|
| 114 |
<sect2 id="c1s2s2"> |
| 115 |
<title>In the following chapters</title> |
| 116 |
<para> |
| 117 |
You will learn how to: |
| 118 |
<itemizedlist> |
| 119 |
<listitem><para>create an application with the KAppWizard</para></listitem> |
| 120 |
<listitem><para>What the project skeleton already provides</para></listitem> |
| 121 |
<listitem><para>What the code already create means</para></listitem> |
| 122 |
<listitem><para>How to create your own views</para></listitem> |
| 123 |
<listitem><para>How to extend your application's functionality by dialog, menu bars, and toolbars</para></listitem> |
| 124 |
<listitem><para>How to make your application user friendly by providing help functions</para></listitem> |
| 125 |
<listitem><para>How to write online documentation</para></listitem> |
| 126 |
</itemizedlist> |
| 127 |
</para> |
| 128 |
</sect2> |
| 129 |
|
| 130 |
</sect1> |
| 131 |
|
| 132 |
<sect1 id="c1s3"> |
| 133 |
<title>Additional Information</title> |
| 134 |
<para> |
| 135 |
Additional information about Qt/KDE programming is available by various sources: |
| 136 |
<itemizedlist> |
| 137 |
<listitem><para>Programming with Qt by Matthias Kalle Dalheimer</para></listitem> |
| 138 |
<listitem><para><ulink url="www.kdevelop.org">The User Manual to KDevelop, provided with the TDevelop IDE</ulink></para></listitem> |
| 139 |
<listitem><para><ulink url="doc.trolltech.com">The Online Reference to the Qt library</ulink></para></listitem> |
| 140 |
<listitem><para><ulink url="developer.kde.org">The KDE Developer web site</ulink></para></listitem> |
| 141 |
</itemizedlist> |
| 142 |
</para> |
| 143 |
<para> |
| 144 |
Additionally, you should look for help by subscribing to the various mailing lists, whose addresses |
| 145 |
are available on the mentioned web sites, and on the Usenet newsgroups dedicated to users of KDE and |
| 146 |
Unix Systems as well as about the C and C++ programming language. |
| 147 |
</para> |
| 148 |
<para> |
| 149 |
For obtaining help about the TDevelop IDE, you should send requests to our mailinglist at |
| 150 |
<email>kdevelop@kdevelop.org</email>. Mind that the KDevelop team is dedicated to provide the means to enable you to |
| 151 |
program applications and therefore is not intended as a technical support team in cases where the |
| 152 |
applications you're developing don't work due to implementation errors or misconfigurations of your |
| 153 |
operating system. By this, we ask all users to take advantage of the mailinglist in any case you're running |
| 154 |
into problems with the use of the IDE itself, as well as for bug reports and suggestions for improving the |
| 155 |
functionality of the development environment. |
| 156 |
</para> |
| 157 |
</sect1> |
| 158 |
|
| 159 |
</chapter> |
| 160 |
|
| 161 |
<chapter id="chapter2"> |
| 162 |
<title>The KDE and Qt Libraries</title> |
| 163 |
<para> |
| 164 |
The Norwegian company TrollTech (<ulink url="http://www.trolltech.com">http://www.trolltech.com</ulink>) |
| 165 |
provides a so-called GUI toolkit, named Qt. GUI means "Graphical User Interface", and therefore, Qt-based |
| 166 |
applications represent themselves with buttons, windows etc, allowing user input by visualizing the functions |
| 167 |
an application provides. Such a toolkit is needed for developing graphical applications that run on the X-Window |
| 168 |
interface on Unix Systems, because X does not contain a pre-defined user interface itself. Although other |
| 169 |
toolkits are also available to create User Interfaces, Qt offers some technical advantages that make |
| 170 |
application design very easy. Additionally, the Qt toolkit is also available for Microsoft Windows systems, |
| 171 |
which allows developers to provide their applications for both platforms. |
| 172 |
</para> |
| 173 |
<para> |
| 174 |
The KDE Team (<ulink url="http://www.kde.org">http://www.kde.org</ulink>) joined together with the goal |
| 175 |
to make using Unix Systems more friendly, and decided to use the Qt toolkit for the development of a window |
| 176 |
manager on X-Windows, plus a variety of tools included with the KDE packages. The K Desktop Environment |
| 177 |
therefore contains the window manager kwm, the file manager kfm and the launch panel kpanel as the main |
| 178 |
components plus a variety of first-class utilities and applications. After KDE was out, a lot of developers |
| 179 |
turned their eyes towards the new environment and what it has to offer them. The KDE libraries are providing |
| 180 |
essential methods and classes that make all applications designed with them look similar and consistent, |
| 181 |
so the user has the great advantage that he only has to get accustomed with an application's specific |
| 182 |
usage, not with handling dialogs or buttons. Also, KDE programs integrate themselves into the desktop and |
| 183 |
are able to interact with the file manager via drag'n drop, offer session management and many more, if all |
| 184 |
features offered by the KDE libraries are used. Both, the Qt toolkit and the KDE libraries, are implemented |
| 185 |
in the C++ programming language; therefore applications that make use of these libraries are also mostly |
| 186 |
written in C++. In the following chapter, we'll make a short trip through the libraries to see what already |
| 187 |
is provided and how Qt and TDE applications are created in general. |
| 188 |
</para> |
| 189 |
<para> |
| 190 |
Both, the Qt toolkit and the KDE libraries, are implemented in the C++ programming language; |
| 191 |
therefore applications that make use of these libraries are also mostly written in C++. In the following |
| 192 |
chapter, we'll make a short trip through the libraries to see what already is provided and how Qt and KDE |
| 193 |
applications are created in general. |
| 194 |
</para> |
| 195 |
|
| 196 |
<sect1 id="c2s1"> |
| 197 |
<title>The Qt GUI Toolkit</title> |
| 198 |
<para> |
| 199 |
As said, the Qt library is a toolkit that offers graphical elements that are used for creating GUI |
| 200 |
applications and are needed for X-Window programming. Additionally, the toolkit offers: |
| 201 |
<itemizedlist> |
| 202 |
<listitem><para>A complete set of classes and methods ready to use even for non-graphical programming issues</para></listitem> |
| 203 |
<listitem><para>A good solution towards user interaction by virtual methods and the signal/slot mechanism</para></listitem> |
| 204 |
<listitem><para>A set of predefined GUI-elements, called "widgets", that can be used easily for creating the visible elements</para></listitem> |
| 205 |
<listitem><para>Additional completely pre-defined dialogs that are often used in applications such as progress and file dialogs</para></listitem> |
| 206 |
</itemizedlist> |
| 207 |
</para> |
| 208 |
<para> |
| 209 |
Therefore knowing the Qt classes is very essential, even if you only want to program KDE-applications. |
| 210 |
To have an impression on the basic concept how GUI-applications are constructed and compiled, we'll first |
| 211 |
have a look at a sample Qt-only program; then we'll extend it to a KDE program. |
| 212 |
</para> |
| 213 |
|
| 214 |
<sect2 id="c2s1s1"> |
| 215 |
<title>The first Qt Application</title> |
| 216 |
<para> |
| 217 |
As usual, programs in C++ have to contain a <function>main()</function> function, which is the starting point for application |
| 218 |
execution. As we want them to be graphically visible in windows and offering user interaction, |
| 219 |
we first have to know, how they can show themselves to the user. For an example, we'll have a look |
| 220 |
at the first tutorial included with the Qt Online Reference Documentation and explain the basic execution |
| 221 |
steps; also why and how the application window appears: |
| 222 |
<programlisting> |
| 223 |
#include <qapplication.h> |
| 224 |
#include <qpushbutton.h> |
| 225 |
|
| 226 |
int main( int argc, char **argv ) |
| 227 |
{ |
| 228 |
QApplication a( argc, argv ); |
| 229 |
|
| 230 |
QPushButton hello( "Hello world!", 0 ); |
| 231 |
hello.resize( 100, 30 ); |
| 232 |
|
| 233 |
a.setMainWidget( &hello ); |
| 234 |
hello.show(); |
| 235 |
return a.exec(); |
| 236 |
} |
| 237 |
</programlisting> |
| 238 |
</para> |
| 239 |
<para> |
| 240 |
This application merely paints a window containing a button with "Hello world" as its text. As for |
| 241 |
all Qt-based applications, you first have to create an instance of the class <classname>QApplication</classname>, represented by |
| 242 |
variable a. |
| 243 |
</para> |
| 244 |
<para> |
| 245 |
Next, the program creates an instance of the class <classname>QPushButton</classname> called hello, this will be the button. |
| 246 |
The constructor of hello gets a string as a parameter, which is the contents of the widget visible as |
| 247 |
the buttons text. |
| 248 |
</para> |
| 249 |
<para> |
| 250 |
Then the <methodname>resize()</methodname> method is called on the hello button. This changes the default size a widget |
| 251 |
(which is in this case the <classname>QPushButton</classname>) has when created to the length of 100 pixels and the height of |
| 252 |
30 pixels. Finally, the setMainWidget() method is called for a and the show() method for hello. The |
| 253 |
QApplication is finally executed by <methodname>a.exec()</methodname>, enters the main event loop and waits until it has to return |
| 254 |
an integer value to the overlaying Operating System signaling that the application is exited. |
| 255 |
</para> |
| 256 |
</sect2> |
| 257 |
|
| 258 |
<sect2 id="c2s1s2"> |
| 259 |
<title>The Reference Documentation for Qt</title> |
| 260 |
<para> |
| 261 |
Now, let's have a quick look at the reference documentation of the Qt library. To do this, start |
| 262 |
&tdevelop; and select "Qt" from the tree in the Documentation tab. The documentation browser opens |
| 263 |
and shows you the start page of the Qt reference. This will be your first place to get information |
| 264 |
about Qt, it's classes and the available functions they provide. Also, the above program is the first |
| 265 |
that is included in the tutorials section. To get to the classes we want to have a look at, |
| 266 |
<classname>QApplication</classname> and <classname>QPushButton</classname>, select "Alphabetical Class List" |
| 267 |
and search for the according names. Follow either of them to have a look at the class documentation. |
| 268 |
</para> |
| 269 |
<para> |
| 270 |
Alternatively, you can use the online documentation from Trolltech's <ulink url="doc.trolltech.com">Qt Documentation</ulink> |
| 271 |
</para> |
| 272 |
<para> |
| 273 |
For <classname>QApplication</classname>, you will see the constructor and all other methods that this |
| 274 |
class provides. If you follow a link, you will get more information about the usage and meaning of the |
| 275 |
methods, which is very useful when you sometimes can't detect the correct use or want to have an example. |
| 276 |
This also counts for the KDE library documentation, which uses a similar documentation type; therefore |
| 277 |
this is almost all you have to know about using the class-references with the documentation browser. |
| 278 |
</para> |
| 279 |
<sect3 id="c2s1s2s1"> |
| 280 |
<title>Interpretation of the Sample</title> |
| 281 |
<para> |
| 282 |
Starting with <classname>QApplication</classname>, you will find all the methods used in our first example: |
| 283 |
<itemizedlist> |
| 284 |
<listitem><para>the constructor <methodname>QApplication()</methodname></para></listitem> |
| 285 |
<listitem><para>the <methodname>setMainWidget()</methodname> method</para></listitem> |
| 286 |
<listitem><para>the <methodname>exec()</methodname> method</para></listitem> |
| 287 |
</itemizedlist> |
| 288 |
</para> |
| 289 |
<para> |
| 290 |
The interpretation why we use these methods is very simple: |
| 291 |
<orderedlist> |
| 292 |
<listitem><para>Create an instance of the class <classname>QApplication</classname> with the constructor, |
| 293 |
so we can make use of the GUI elements provided by Qt</para></listitem> |
| 294 |
<listitem><para>Create a widget which will be the contents of our program window</para></listitem> |
| 295 |
<listitem><para>Set the widget as the main widget for a</para></listitem> |
| 296 |
<listitem><para>Execute the a instance of <classname>QApplication</classname></para></listitem> |
| 297 |
</orderedlist> |
| 298 |
</para> |
| 299 |
<para> |
| 300 |
The second object of our program is the pushbutton, an instance of the class <classname>QPushButton</classname>. |
| 301 |
From the two constructors given to create an instance, we used the second: this accepts a text, |
| 302 |
which is the label contents of the button; here, it is the string "Hello world!". Then we called the |
| 303 |
<methodname>resize()</methodname> method to change the size of the button according to it's contents - |
| 304 |
the button has to be larger to make the string completely visible. |
| 305 |
</para> |
| 306 |
<para> |
| 307 |
But what about the <methodname>show()</methodname> method? Now, you see that like most other widgets, |
| 308 |
<classname>QPushButton</classname> is based on a single inheritance, the documentation says, Inherits |
| 309 |
<classname>QButton</classname>. Follow the link to the <classname>QButton</classname> class. |
| 310 |
This shows you a lot of other widgets that are inherited by <classname>QPushButton</classname>, |
| 311 |
which we'll use later to explain the signal/slot mechanism. Anyway, the <methodname>show()</methodname> |
| 312 |
method is not listed, therefore, it must be a method that is provided by inheritance as well. The class |
| 313 |
that <classname>QButton</classname> inherits is <classname>QWidget</classname>. Just follow the link |
| 314 |
again, and you will see a whole bunch of methods that the QWidget class provides; including |
| 315 |
the <methodname>show()</methodname> method. Now we understand what was done in the sample with the button: |
| 316 |
<orderedlist> |
| 317 |
<listitem><para>Create an instance of <classname>QPushButton</classname>, use the second constructor to set the button text</para></listitem> |
| 318 |
<listitem><para>Resize the widget to its contents</para></listitem> |
| 319 |
<listitem><para>Set the widget as the main widget of the <classname>QApplication</classname> instance a</para></listitem> |
| 320 |
<listitem><para>Tell the widget to display itself on the screen by calling <methodname>show()</methodname>, an inherited method from <classname>QWidget</classname></para></listitem> |
| 321 |
</orderedlist> |
| 322 |
</para> |
| 323 |
<para> |
| 324 |
After calling the <methodname>exec()</methodname> method, the application is visible to the user, |
| 325 |
showing a window with the button showing "Hello world!". Note: GUI programs behave somewhat differently |
| 326 |
than procedural applications. The main thing here is that the application enters a so-called |
| 327 |
"main event loop". This means that the program has to wait for user actions and then react to it, also |
| 328 |
that for a Qt application, the program has to be in the main event loop to start the event handling. |
| 329 |
The next section tells you in short what this means to the programmer and what Qt offers to process |
| 330 |
user events. |
| 331 |
</para> |
| 332 |
<note><para> |
| 333 |
For already advanced users: The button has no parent declared in the constructor, therefore it |
| 334 |
is a top-level widget alone and runs in a local event loop which doesn't need to wait for the main |
| 335 |
event loop. See the QWidget class documentation and The KDE Library Reference Guide</para> |
| 336 |
</note> |
| 337 |
|
| 338 |
</sect3> |
| 339 |
</sect2> |
| 340 |
|
| 341 |
<sect2 id="c2s1s3"> |
| 342 |
<title>User Interaction</title> |
| 343 |
<para> |
| 344 |
After reading the last sections, you should already know: |
| 345 |
<itemizedlist> |
| 346 |
<listitem><para>What the Qt-library provides in terms of GUI applications</para></listitem> |
| 347 |
<listitem><para>How a program using Qt is created and</para></listitem> |
| 348 |
<listitem><para>Where and how to find information about classes that you want to use with the documentation browser</para></listitem> |
| 349 |
</itemizedlist> |
| 350 |
</para> |
| 351 |
<para> |
| 352 |
Now we'll turn to give the application "life" by processing user events. Generally, the user has two ways |
| 353 |
to interact with a program: the mouse and the keyboard. For both ways, a graphical user interface has to |
| 354 |
provide methods that detect actions and methods that do something as a reaction to these actions. |
| 355 |
</para> |
| 356 |
<para> |
| 357 |
The Window system therefore sends all interaction events to the according application. The |
| 358 |
<classname>QApplication</classname> then sends them to the active window as a <classname>QEvent</classname> |
| 359 |
and the widgets themselves have to decide what to do with them. A widget receives the event and processes |
| 360 |
<methodname>QWidget::event(QEvent*)</methodname>, which then decides which event has been executed |
| 361 |
and how to react; <methodname>event()</methodname> is therefore the main event handler. Then, |
| 362 |
the <methodname>event()</methodname> method passes the event to so-called event filters |
| 363 |
that determine what happened and what to do with the event. If no filter signs responsible for the |
| 364 |
event, the specialized event handlers are called. Thereby we can decide between: |
| 365 |
<itemizedlist> |
| 366 |
<listitem><para> |
| 367 |
Keyboard events -- TAB and Shift-TAB keys:</para> |
| 368 |
<itemizedlist> |
| 369 |
<listitem><para><methodname>virtual void focusInEvent(QFocusEvent *)</methodname></para></listitem> |
| 370 |
<listitem><para><methodname>virtual void focusOutEvent(QFocusEvent *)</methodname></para></listitem> |
| 371 |
</itemizedlist> |
| 372 |
</listitem> |
| 373 |
|
| 374 |
<listitem><para> |
| 375 |
All other keyboard input:</para> |
| 376 |
<itemizedlist> |
| 377 |
<listitem><para><methodname>virtual void keyPressEvent(QKeyEvent *)</methodname></para></listitem> |
| 378 |
<listitem><para><methodname>virtual void keyReleaseEvent(QKeyEvent *)</methodname></para></listitem> |
| 379 |
</itemizedlist> |
| 380 |
</listitem> |
| 381 |
|
| 382 |
<listitem><para> |
| 383 |
Mouse movements:</para> |
| 384 |
<itemizedlist> |
| 385 |
<listitem><para><methodname>virtual void mouseMoveEvent(QMouseEvent *)</methodname></para></listitem> |
| 386 |
<listitem><para><methodname>virtual void enterEvent(QEvent *)</methodname></para></listitem> |
| 387 |
<listitem><para><methodname>virtual void leaveEvent(QEvent *)</methodname></para></listitem> |
| 388 |
</itemizedlist> |
| 389 |
</listitem> |
| 390 |
|
| 391 |
<listitem><para> |
| 392 |
Mouse button actions</para> |
| 393 |
<itemizedlist> |
| 394 |
<listitem><para><methodname>virtual void mousePressEvent(QMouseEvent *)</methodname></para></listitem> |
| 395 |
<listitem><para><methodname>virtual void mouseReleaseEvent(QMouseEvent *)</methodname></para></listitem> |
| 396 |
<listitem><para><methodname>virtual void mouseDoubleClickEvent(QMouseEvent *)</methodname></para></listitem> |
| 397 |
</itemizedlist> |
| 398 |
</listitem> |
| 399 |
|
| 400 |
<listitem><para> |
| 401 |
Window events containing the widget</para> |
| 402 |
<itemizedlist> |
| 403 |
<listitem><para><methodname>virtual void moveEvent(QMoveEvent *)</methodname></para></listitem> |
| 404 |
<listitem><para><methodname>virtual void resizeEvent(QResizeEvent *)</methodname></para></listitem> |
| 405 |
<listitem><para><methodname>virtual void closeEvent(QCloseEvent *)</methodname></para></listitem> |
| 406 |
</itemizedlist> |
| 407 |
</listitem> |
| 408 |
|
| 409 |
</itemizedlist> |
| 410 |
</para> |
| 411 |
<para> |
| 412 |
Note that all event functions are virtual and protected; therefore you can re-implement the events |
| 413 |
that you need in your own widgets and specify how your widget has to react. <classname>QWidget</classname> |
| 414 |
also contains some other virtual methods that can be useful in your programs; anyway, it is sufficient |
| 415 |
to know about <classname>QWidget</classname> very well. |
| 416 |
</para> |
| 417 |
</sect2> |
| 418 |
<sect2 id="c1s2s4"> |
| 419 |
<title>Object Interaction by Signals and Slots</title> |
| 420 |
<para> |
| 421 |
Now we're coming to the most obvious advantages of the Qt toolkit: the signal/slot mechanism. |
| 422 |
This offers a very handy and useful solution to object interaction, which usually is solved by |
| 423 |
callback functions for X-Window toolkits. As this communication requires a strict programming and |
| 424 |
sometimes makes user interface creation very difficult (as referred by the Qt documentation and explained |
| 425 |
in Programming with Qt by K.Dalheimer), Troll Tech invented a new system where objects can emit signals |
| 426 |
that can be connected to methods declared as slots. For the C++ part of the programmer, he only has to know |
| 427 |
some things about this mechanism: |
| 428 |
<itemizedlist> |
| 429 |
<listitem><para> |
| 430 |
the class declaration of a class using signals/slots has to contain the Q_OBJECT macro at the beginning |
| 431 |
(without a semicolon); and have to be derved from the <classname>QObject</classname> class |
| 432 |
</para></listitem> |
| 433 |
<listitem><para> |
| 434 |
a signal can be emitted by the keyword emit, e.g. emit signal(parameters); from within any member function |
| 435 |
of a class that allows signals/slots |
| 436 |
</para></listitem> |
| 437 |
|
| 438 |
<listitem><para> |
| 439 |
all signals used by the classes that are not inherited have to be added to the class declaration by a |
| 440 |
signals section |
| 441 |
</para></listitem> |
| 442 |
<listitem><para> |
| 443 |
all methods that can be connected with a signal are declared in sections with the additional keyword slot, |
| 444 |
e.g. public slots: within the class declaration |
| 445 |
</para></listitem> |
| 446 |
<listitem><para> |
| 447 |
the meta-object compiler moc has to run over the header file to expand the macros and to produce the |
| 448 |
implementation (which is not necessary to know). The output files of moc are compiled also by the C++ compiler. |
| 449 |
</para></listitem> |
| 450 |
</itemizedlist> |
| 451 |
</para> |
| 452 |
<para> |
| 453 |
Another way to use signals without deriving from <classname>QObject</classname> is to use the |
| 454 |
<classname>QSignal</classname> class- see the reference documentation for more information and example |
| 455 |
usage. In the following, we assume you're deriving from <classname>QObject</classname>. |
| 456 |
</para> |
| 457 |
<para> |
| 458 |
This way, your class is able to send signals anywhere and to provide slots that signals can connect |
| 459 |
to. By using the signals, you don't have to care about who's receiving it- you just have to emit the |
| 460 |
signal and whatever slot you want to connect to it can react to the emission. Also the slots can be used |
| 461 |
as normal methods during implementation. |
| 462 |
</para> |
| 463 |
<para> |
| 464 |
Now, to connect a signal to a slot, you have to use the <methodname>connect()</methodname> methods that |
| 465 |
are provided by <classname>QObject</classname> or, where available, special methods that objects provide |
| 466 |
to set the connection for a certain signal. |
| 467 |
</para> |
| 468 |
|
| 469 |
<sect3 id="c1s2s4s1"> |
| 470 |
<title>Sample Usage</title> |
| 471 |
<para> |
| 472 |
To explain the way how to set up object-interaction, we'll take our first example again and extend it by a |
| 473 |
simple connection: |
| 474 |
<programlisting> |
| 475 |
#include <qapplication.h> |
| 476 |
#include <qpushbutton.h> |
| 477 |
|
| 478 |
int main( int argc, char **argv ) |
| 479 |
{ |
| 480 |
QApplication a( argc, argv ); |
| 481 |
|
| 482 |
QPushButton hello( "Hello world!" , 0); |
| 483 |
hello.resize( 100, 30 ); |
| 484 |
|
| 485 |
a.setMainWidget( &hello ); |
| 486 |
|
| 487 |
QObject::connect(&hello, SIGNAL( clicked() ), &a, SLOT( quit() )); |
| 488 |
|
| 489 |
hello.show(); |
| 490 |
return a.exec(); |
| 491 |
} |
| 492 |
</programlisting> |
| 493 |
</para> |
| 494 |
<para> |
| 495 |
You see, the only addition to give the button more interaction is to use a <methodname>connect() |
| 496 |
</methodname> method: <methodname>connect(&hello, SIGNAL( clicked() ), &a, SLOT( quit() ))</methodname>; |
| 497 |
is all you have to add. What is the meaning now? The class declaration of QObject says about the |
| 498 |
<methodname>connect()</methodname> method: |
| 499 |
</para> |
| 500 |
<para><methodname> |
| 501 |
bool connect ( const QObject * sender, const char * signal, const QObject * receiver, const char * member ) |
| 502 |
</methodname></para> |
| 503 |
<para> |
| 504 |
This means you have to specify a <classname>QObject</classname> instance pointer that is the sender |
| 505 |
of the signal, meaning that it can emit this signal as first parameter; then you have to specify the signal |
| 506 |
that you want to connect to. The last two parameters are the receiver object that provides a slot, followed |
| 507 |
by the member function which actually is the slot that will be executed on signal emission. |
| 508 |
</para> |
| 509 |
<para> |
| 510 |
By using signals and slots, your program's objects can interact with each other easily without explicitly |
| 511 |
depending on the type of the receiver object. You will learn more about using this mechanism for productive |
| 512 |
usage later in this handbook. More information about the Signals/Slot mechanism can also be found in |
| 513 |
<ulink url="developer.kde.org/documentation/library/libraryref.html">The KDE Library Reference Guide</ulink> |
| 514 |
and the <ulink url="doc.trolltech.com">Qt online reference</ulink>. |
| 515 |
</para> |
| 516 |
</sect3> |
| 517 |
</sect2> |
| 518 |
</sect1> |
| 519 |
|
| 520 |
<sect1 id="c2s3"> |
| 521 |
<title>What KDE provides</title> |
| 522 |
<sect2 id="c2s3s1"> |
| 523 |
<title>The KDE 3.x libraries</title> |
| 524 |
<para> |
| 525 |
The main KDE libraries you'll be using for creating your own TDE applications are: |
| 526 |
<itemizedlist> |
| 527 |
<listitem><para> |
| 528 |
the tdecore library, containing all classes that are non-visible elements to provide application functionality |
| 529 |
</para></listitem> |
| 530 |
<listitem><para> |
| 531 |
the tdeui library, containing user interface elements like menubars, toolbars, etc. |
| 532 |
</para></listitem> |
| 533 |
<listitem><para> |
| 534 |
the tdefile library, containing the file selection dialogs |
| 535 |
</para></listitem> |
| 536 |
</itemizedlist> |
| 537 |
</para> |
| 538 |
<para> |
| 539 |
Additionally, for specific solutions KDE offers the following libraries: |
| 540 |
<itemizedlist> |
| 541 |
<listitem><para> |
| 542 |
the tdefx library, containing pixmaps, image effects the TDEStyle extension to QStyle |
| 543 |
</para></listitem> |
| 544 |
<listitem><para> |
| 545 |
the tdehtml library, containing KDE's html component |
| 546 |
</para></listitem> |
| 547 |
<listitem><para> |
| 548 |
the kjs library, containing KDE's Javascript support |
| 549 |
</para></listitem> |
| 550 |
<listitem><para> |
| 551 |
the tdeio library, containing low level access to network files |
| 552 |
</para></listitem> |
| 553 |
<listitem><para> |
| 554 |
the tdeparts library, containing support for re-usable embeddable extendable applications |
| 555 |
</para></listitem> |
| 556 |
</itemizedlist> |
| 557 |
</para> |
| 558 |
<para> |
| 559 |
Next we'll have a look at what is needed to turn out first Qt Application into a KDE one. |
| 560 |
</para> |
| 561 |
</sect2> |
| 562 |
<sect2 id="c2s3s2"> |
| 563 |
<title>Example KDE Application</title> |
| 564 |
<para> |
| 565 |
In the following, you will see that writing a KDE application is not much more difficult than a |
| 566 |
Qt application. For the use of KDE's features, you just have to use some other classes, and you're almost |
| 567 |
done. As an example, we'll discuss the changed version of the Qt example from above: |
| 568 |
<programlisting> |
| 569 |
#include <tdeapplication.h> |
| 570 |
#include <qpushbutton.h> |
| 571 |
|
| 572 |
int main( int argc, char **argv ) |
| 573 |
{ |
| 574 |
TDEApplication a( argc, argv ); |
| 575 |
|
| 576 |
QPushButton hello( "Hello world!", 0 ); |
| 577 |
hello.resize( 100, 30 ); |
| 578 |
|
| 579 |
a.setTopWidget( &hello ); |
| 580 |
|
| 581 |
QObject::connect(&hello, SIGNAL( clicked() ), &a, SLOT( quit() )); |
| 582 |
|
| 583 |
hello.show(); |
| 584 |
return a.exec(); |
| 585 |
} |
| 586 |
</programlisting> |
| 587 |
</para> |
| 588 |
<para> |
| 589 |
You see that first we have changed from <classname>QApplication</classname> to <classname>TDEApplication |
| 590 |
</classname>. Further, we had to change the previously used <methodname>setMainWidget()</methodname> method |
| 591 |
to <methodname>setTopWidget</methodname>, which <classname>TDEApplication</classname> uses to set the main |
| 592 |
widget. That's it! Your first KDE application is ready - you only have to tell the compiler the KDE |
| 593 |
include path and the linker to link in the tdecore library with -ltdecore. |
| 594 |
</para> |
| 595 |
<para> |
| 596 |
As you now know what at least the <function>main()</function> function provides generally and how an |
| 597 |
application gets visible and allows user and object interaction, we'll go on with the next chapter, |
| 598 |
where our first application is made with &tdevelop;. There you can also test everything which was |
| 599 |
mentioned before and see the effects. |
| 600 |
</para> |
| 601 |
<para> |
| 602 |
What you should have looked into additionally until now is the reference documentation for Qt, |
| 603 |
especially the <classname>QApplication</classname>, <classname>QWidget</classname> and <classname>QObject |
| 604 |
</classname> class and the tdecore library documentation for the <classname>TDEApplication</classname> class. |
| 605 |
The <ulink url="developer.kde.org/documentation/library/libraryref.html">KDE Library Reference handbook</ulink> |
| 606 |
also covers a complete description about the invocation of the <classname>QApplication</classname> and |
| 607 |
<classname>TDEApplication</classname> constructors including command-line argument processing. |
| 608 |
</para> |
| 609 |
</sect2> |
| 610 |
</sect1> |
| 611 |
|
| 612 |
</chapter> |
| 613 |
|
| 614 |
<chapter id="chapter3"> |
| 615 |
<title>Creating New Applications</title> |
| 616 |
|
| 617 |
<sect1 id="c3s1"> |
| 618 |
<title>The Application Wizard</title> |
| 619 |
<para> |
| 620 |
&tdevelop;'s Application Wizard is intended to let you start working on new project with &tdevelop;. Therefore |
| 621 |
all of your projects are first created by the wizard, and then you can start building them and extend what is |
| 622 |
already provided by the source skeleton. You can choose from several project types according to your project goals: |
| 623 |
<itemizedlist> |
| 624 |
<listitem><para> |
| 625 |
KDE Application Framework: includes source code for a complete frame structre of a standard KDE application |
| 626 |
</para></listitem> |
| 627 |
<listitem><para> |
| 628 |
QMake Project: Creates an application framework based around Trolltech's qmake configuration system |
| 629 |
</para></listitem> |
| 630 |
<listitem><para> |
| 631 |
Simple hello world program: Creates a C++ terminal based program with no GUI support |
| 632 |
</para></listitem> |
| 633 |
<listitem><para> |
| 634 |
A multitude of other program skeletons |
| 635 |
</para></listitem> |
| 636 |
</itemizedlist> |
| 637 |
</para> |
| 638 |
<para> |
| 639 |
In this chapter we'll see how the Application Wizard can be invoked and what has to be done to generate |
| 640 |
a KDE application project. This will also be the initial step of our coverage, where we will create the |
| 641 |
initial version of a sample project. For all other project types the steps are usualyl the same, but you |
| 642 |
may not have as many options available. |
| 643 |
</para> |
| 644 |
</sect1> |
| 645 |
|
| 646 |
<sect1 id="c3s2"> |
| 647 |
<title>Invoking the Application Wizard and Project Generation</title> |
| 648 |
<sect2 id="c3s2s1"> |
| 649 |
<title>Starting the Application Wizard and the First Page</title> |
| 650 |
<para> |
| 651 |
To start with your KDE application, open &tdevelop;. From the Project menu, selection New Project. The |
| 652 |
Application Wizard starts, and you'll see the selection tree on the first page containing available project |
| 653 |
types that can be created. Choose the C++ subtree, then KDE, then Application Framework. |
| 654 |
</para> |
| 655 |
<para> |
| 656 |
For our sample project, we are going to create the application KScribble. Enter this as the application |
| 657 |
name, and change any other information at the bottom of this screen that may need it. Then, select Next. |
| 658 |
<screenshot><mediaobject><imageobject> |
| 659 |
<imagedata fileref="appwizard.png" format="PNG"/> |
| 660 |
</imageobject><textobject><phrase>Application Wizard</phrase></textobject> |
| 661 |
</mediaobject></screenshot> |
| 662 |
</para> |
| 663 |
</sect2> |
| 664 |
<sect2 id="c3s2s2"> |
| 665 |
<title>Version control information</title> |
| 666 |
<para> |
| 667 |
On this screen you have the ability to decide if your project will use a version control system like |
| 668 |
CVS. For our sample project we will not use source control, so make sure the selection box reads None |
| 669 |
and select Next. |
| 670 |
</para> |
| 671 |
</sect2> |
| 672 |
<sect2 id="c3s2s3"> |
| 673 |
<title>Header and Source Templates</title> |
| 674 |
<para> |
| 675 |
The next two pages show example headers that will go at the top of each of the header and source files that |
| 676 |
you create using &tdevelop;. For now, just leave these as the default, and select Next, then Finish. If the |
| 677 |
Finish button is not activated, you haven't set all of the options correct. Use the Back button to return |
| 678 |
to earlier menus and correct any mistakes. |
| 679 |
</para> |
| 680 |
</sect2> |
| 681 |
<sect2 id="c3s2s4"> |
| 682 |
<title>Finishing Up</title> |
| 683 |
<para> |
| 684 |
Upon completion, the Application Wizard should close and the messages window should popup displaying |
| 685 |
information about the tasks that &tdevelop; is currently doing. At the end of all of the tasks, you |
| 686 |
should see **** Success *****. This means the application framework was successfully loaded. |
| 687 |
</para> |
| 688 |
</sect2> |
| 689 |
</sect1> |
| 690 |
|
| 691 |
<sect1 id="c3s3"> |
| 692 |
<title>The First Build</title> |
| 693 |
<para> |
| 694 |
After our project is generated, we'll first make a trip through the source code to get a general understanding |
| 695 |
of how the application framework looks. This won't only help us get started, but we'll know where to change |
| 696 |
what in later steps. |
| 697 |
</para> |
| 698 |
<para> |
| 699 |
This chapter makes the assumption that you understand the basic navigation of &tdevelop;. Consult the |
| 700 |
KDevelop User Manual for information if you need it. |
| 701 |
</para> |
| 702 |
<para> |
| 703 |
The Automake manager shows the project files as follows: |
| 704 |
<screenshot><mediaobject><imageobject> |
| 705 |
<imagedata fileref="kscribblefiles.png" format="PNG"/> |
| 706 |
</imageobject><textobject><phrase>Files in our project</phrase></textobject> |
| 707 |
</mediaobject></screenshot> |
| 708 |
</para> |
| 709 |
<para> |
| 710 |
Before diving into the sources, we'll let &tdevelop; build an run our new application. To do this, select |
| 711 |
Build Project from the Build menu, or press F8. The output window opens and displays output messages during |
| 712 |
the compilation phase. |
| 713 |
<programlisting> |
| 714 |
1 cd /home/caleb/kscribble && WANT_AUTOCONF_2_5=1 WANT_AUTOMAKE_1_6=1 gmake k |
| 715 |
2 gmake all-recursive |
| 716 |
3 gmake[1]: Entering directory `/home/caleb/kscribble' |
| 717 |
4 Making all in doc |
| 718 |
5 gmake[2]: Entering directory `/home/caleb/kscribble/doc' |
| 719 |
6 Making all in . |
| 720 |
7 gmake[3]: Entering directory `/home/caleb/kscribble/doc' |
| 721 |
8 gmake[3]: Nothing to be done for `all-am'. |
| 722 |
9 gmake[3]: Leaving directory `/home/caleb/kscribble/doc' |
| 723 |
10 Making all in en |
| 724 |
11 gmake[3]: Entering directory `/home/caleb/kscribble/doc/en' |
| 725 |
12 /usr/local/trinity/bin/meinproc --check --cache index.cache.bz2 /home/caleb/kscribble/doc/en/index.docbook |
| 726 |
13 gmake[3]: Leaving directory `/home/caleb/kscribble/doc/en' |
| 727 |
14 gmake[2]: Leaving directory `/home/caleb/kscribble/doc' |
| 728 |
15 Making all in po |
| 729 |
16 gmake[2]: Entering directory `/home/caleb/kscribble/po' |
| 730 |
17 gmake[2]: Nothing to be done for `all'. |
| 731 |
18 gmake[2]: Leaving directory `/home/caleb/kscribble/po' |
| 732 |
19 Making all in src |
| 733 |
20 gmake[2]: Entering directory `/home/caleb/kscribble/src' |
| 734 |
21 source='main.cpp' object='main.o' libtool=no \ |
| 735 |
22 depfile='.deps/main.Po' tmpdepfile='.deps/main.TPo' \ |
| 736 |
23 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ |
| 737 |
24 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include |
| 738 |
-I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor |
| 739 |
-Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings |
| 740 |
-ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new |
| 741 |
-c -o main.o `test -f 'main.cpp' || echo '/home/caleb/kscribble/src/'`main.cpp |
| 742 |
25 /usr/lib/qt/bin/moc /home/caleb/kscribble/src/kscribble.h -o kscribble.moc |
| 743 |
26 source='kscribble.cpp' object='kscribble.o' libtool=no \ |
| 744 |
27 depfile='.deps/kscribble.Po' tmpdepfile='.deps/kscribble.TPo' \ |
| 745 |
28 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ |
| 746 |
29 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include |
| 747 |
-I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor |
| 748 |
-Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings |
| 749 |
-ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new |
| 750 |
-c -o kscribble.o `test -f 'kscribble.cpp' || echo '/home/caleb/kscribble/src/'`kscribble.cpp |
| 751 |
30 kscribble.cpp: In member function `void KScribble::setupActions()' |
| 752 |
31 kscribble.cpp:107: warning: unused variable `TDEAction*custom' |
| 753 |
32 /usr/lib/qt/bin/moc /home/caleb/kscribble/src/kscribbleview.h -o kscribbleview.moc |
| 754 |
33 source='kscribbleview.cpp' object='kscribbleview.o' libtool=no \ |
| 755 |
34 depfile='.deps/kscribbleview.Po' tmpdepfile='.deps/kscribbleview.TPo' \ |
| 756 |
35 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ |
| 757 |
36 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include |
| 758 |
-I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor |
| 759 |
-Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings -ansi |
| 760 |
-D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new -c |
| 761 |
-o kscribbleview.o `test -f 'kscribbleview.cpp' || echo '/home/caleb/kscribble/src/'`kscribbleview.cpp |
| 762 |
37 kscribbleview.cpp: In member function `void KScribbleView::print(QPainter*, |
| 763 |
38 int, int)': |
| 764 |
39 kscribbleview.cpp:79: warning: unused parameter `QPainter*p' |
| 765 |
40 kscribbleview.cpp:79: warning: unused parameter `int height' |
| 766 |
41 kscribbleview.cpp:79: warning: unused parameter `int width' |
| 767 |
42 /usr/lib/qt/bin/moc /home/caleb/kscribble/src/pref.h -o pref.moc |
| 768 |
43 source='pref.cpp' object='pref.o' libtool=no \ |
| 769 |
44 depfile='.deps/pref.Po' tmpdepfile='.deps/pref.TPo' \ |
| 770 |
45 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ |
| 771 |
46 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include |
| 772 |
-I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor |
| 773 |
-Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings |
| 774 |
-ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new |
| 775 |
-c -o pref.o `test -f 'pref.cpp' || echo '/home/caleb/kscribble/src/'`pref.cpp |
| 776 |
47 /usr/local/trinity/bin/dcopidl /home/caleb/kscribble/src/kscribbleiface.h > kscribbleiface.kidl || |
| 777 |
( rm -f kscribbleiface.kidl ; /bin/false ) |
| 778 |
48 /usr/local/trinity/bin/dcopidl2cpp --c++-suffix cpp --no-signals --no-stub kscribbleiface.kidl |
| 779 |
49 source='kscribbleiface_skel.cpp' object='kscribbleiface_skel.o' libtool=no \ |
| 780 |
50 depfile='.deps/kscribbleiface_skel.Po' tmpdepfile='.deps/kscribbleiface_skel.TPo' \ |
| 781 |
51 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ |
| 782 |
52 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include |
| 783 |
-I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor |
| 784 |
-Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings |
| 785 |
-ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new |
| 786 |
-c -o kscribbleiface_skel.o `test -f 'kscribbleiface_skel.cpp' || |
| 787 |
echo '/home/caleb/kscribble/src/'`kscribbleiface_skel.cpp |
| 788 |
53 /bin/sh ../libtool --silent --mode=link --tag=CXX g++ -Wnon-virtual-dtor -Wno-long-long -Wundef -Wall |
| 789 |
-pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings -ansi -D_XOPEN_SOURCE=500 |
| 790 |
-D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new -o kscribble -R |
| 791 |
/usr/local/trinity/lib -R /usr/lib/qt/lib -R /usr/X11R6/lib -L/usr/X11R6/lib -L/usr/lib/qt/lib |
| 792 |
-L/usr/local/trinity/lib main.o kscribble.o kscribbleview.o pref.o kscribbleiface_skel.o -ltdeio |
| 793 |
54 source='kscribble_client.cpp' object='kscribble_client.o' libtool=no \ |
| 794 |
55 depfile='.deps/kscribble_client.Po' tmpdepfile='.deps/kscribble_client.TPo' \ |
| 795 |
56 depmode=gcc3 /bin/sh /home/caleb/kscribble/admin/depcomp \ |
| 796 |
57 g++ -DHAVE_CONFIG_H -I. -I/home/caleb/kscribble/src -I.. -I/usr/local/trinity/include |
| 797 |
-I/usr/lib/qt/include -I/usr/X11R6/include -DQT_THREAD_SUPPORT -D_REENTRANT -Wnon-virtual-dtor |
| 798 |
-Wno-long-long -Wundef -Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings |
| 799 |
-ansi -D_XOPEN_SOURCE=500 -D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new |
| 800 |
-c -o kscribble_client.o `test -f 'kscribble_client.cpp' || echo |
| 801 |
'/home/caleb/kscribble/src/'`kscribble_client.cpp |
| 802 |
58 /bin/sh ../libtool --silent --mode=link --tag=CXX g++ -Wnon-virtual-dtor -Wno-long-long -Wundef |
| 803 |
-Wall -pedantic -W -Wpointer-arith -Wmissing-prototypes -Wwrite-strings -ansi -D_XOPEN_SOURCE=500 |
| 804 |
-D_BSD_SOURCE -Wcast-align -Wconversion -O2 -fno-exceptions -fno-check-new -o kscribble_client -R |
| 805 |
/usr/local/trinity/lib -R /usr/lib/qt/lib -R /usr/X11R6/lib -L/usr/X11R6/lib -L/usr/lib/qt/lib |
| 806 |
-L/usr/local/trinity/lib kscribble_client.o -ltdecore |
| 807 |
59 gmake[2]: Leaving directory `/home/caleb/kscribble/src' |
| 808 |
60 gmake[2]: Entering directory `/home/caleb/kscribble' |
| 809 |
61 gmake[2]: Nothing to be done for `all-am'. |
| 810 |
62 gmake[2]: Leaving directory `/home/caleb/kscribble' |
| 811 |
63 gmake[1]: Leaving directory `/home/caleb/kscribble' |
| 812 |
64 *** Success *** |
| 813 |
</programlisting> |
| 814 |
</para> |
| 815 |
<para> |
| 816 |
As you can see, we've put line numbers in front of each line which won't appear on your output but it makes it |
| 817 |
easier to describe what is happening during the build. First of all, gmake works recursively. This means |
| 818 |
that it starts from the directory it is invoked and goes into the subdirectories first, one at a time, then |
| 819 |
returns to the directory it was started, processes it, then finishes. |
| 820 |
</para> |
| 821 |
<para> |
| 822 |
Our first line of interest is 24. Notice on this line that g++, which is our C++ compiler, gets called by make |
| 823 |
to compile the first source code file in our project - in this case main.cpp. Many extra command line options |
| 824 |
are also being used with the g++ compiler; some of which are defaults and some of which can be configured |
| 825 |
via &tdevelop;. |
| 826 |
</para> |
| 827 |
<para> |
| 828 |
Before the next file (kscribble.cpp, line 29) is compiled, the moc (meta object compiler) is first |
| 829 |
invoked on kscribble.h (line 25). This is because KScribble classes use signals/slots, so the |
| 830 |
Q_OBJECT macro must be expanded, and the moc does this for us. The resultant file, kscribble.moc, is |
| 831 |
used by kscribble.cpp via an #include statement inside of the file. |
| 832 |
</para> |
| 833 |
</sect1> |
| 834 |
|
| 835 |
<sect1 id="c3s4"> |
| 836 |
<title>The source skeleton</title> |
| 837 |
<para> |
| 838 |
To conceptualize how a KDE application works, we'll first have a very close look at the source |
| 839 |
skeleton already provided by the Application Wizard. As we already saw, we're having a set of source |
| 840 |
and header files that build the initial code for the application and make it ready-to-run. Therefore, |
| 841 |
the easiest way to explain the code is to follow the implementation line by line as it is processed |
| 842 |
during executing the program until it enters the main event loop and is ready to accept user input. |
| 843 |
Then, we'll have a look at the functionality that enables user interaction and how certain things work. |
| 844 |
This is probably the best way to explain the framework and, as it is similar to almost all KDE |
| 845 |
applications, will enable you to read source codes from other projects as well; additionally, you will |
| 846 |
know where to change what part of the code to make your applications behave the way they are designed for. |
| 847 |
</para> |
| 848 |
|
| 849 |
<sect2 id="c3s4s1"> |
| 850 |
<title>The main() function</title> |
| 851 |
<para> |
| 852 |
As the application begins its execution with entering the <function>main()</function> function, |
| 853 |
this will be the start for our code examination. The <function>main()</function> function of |
| 854 |
KScribble is implemented in the file main.cpp and can also be found using the Class Browser |
| 855 |
by selecting the "Global Functions" folder. |
| 856 |
<programlisting> |
| 857 |
1 int main(int argc, char **argv) |
| 858 |
2 { |
| 859 |
3 TDEAboutData about("kscribble", I18N_NOOP("KScribble"), version, description, |
| 860 |
4 TDEAboutData::License_GPL, "(C) 2002 Your Name", 0, 0, "you@you.com"); |
| 861 |
5 about.addAuthor( "Your Name", 0, "you@you.com" ); |
| 862 |
6 TDECmdLineArgs::init(argc, argv, &about); |
| 863 |
7 TDECmdLineArgs::addCmdLineOptions(options); |
| 864 |
8 TDEApplication app; |
| 865 |
9 |
| 866 |
10 // register ourselves as a dcop client |
| 867 |
11 app.dcopClient()->registerAs(app.name(), false); |
| 868 |
12 |
| 869 |
13 // see if we are starting with session management |
| 870 |
14 if (app.isRestored()) |
| 871 |
15 RESTORE(KScribble) |
| 872 |
16 else |
| 873 |
17 { |
| 874 |
18 // no session.. just start up normally |
| 875 |
19 TDECmdLineArgs *args = TDECmdLineArgs::parsedArgs(); |
| 876 |
20 if (args->count() == 0) |
| 877 |
21 { |
| 878 |
22 KScribble *widget = new KScribble; |
| 879 |
23 widget->show(); |
| 880 |
24 } |
| 881 |
25 else |
| 882 |
26 { |
| 883 |
27 int i = 0; |
| 884 |
28 for (; i < args->count(); i++) |
| 885 |
29 { |
| 886 |
30 KScribble *widget = new KScribble; |
| 887 |
31 widget->show(); |
| 888 |
32 widget->load(args->url(i)); |
| 889 |
33 } |
| 890 |
34 } |
| 891 |
35 args->clear(); |
| 892 |
36 } |
| 893 |
37 |
| 894 |
38 return app.exec(); |
| 895 |
39 } |
| 896 |
</programlisting> |
| 897 |
</para> |
| 898 |
<para> |
| 899 |
Now, what happens first is the usual creation of a <classname>TDEApplication</classname> object, but we've |
| 900 |
added some KDE methods that set program and author information for this application. |
| 901 |
</para> |
| 902 |
</sect2> |
| 903 |
<sect2> |
| 904 |
<title>User Application Start</title> |
| 905 |
|
| 906 |
<para>... (not written yet)</para> |
| 907 |
|
| 908 |
</sect2> |
| 909 |
<sect2> |
| 910 |
<title>The Constructor</title> |
| 911 |
<para> |
| 912 |
Let's have a look at the constructor and see how this instance is called |
| 913 |
<programlisting> |
| 914 |
1 KScribble::KScribble() |
| 915 |
2 : TDEMainWindow( 0, "KScribble" ), |
| 916 |
3 m_view(new KScribbleView(this)), |
| 917 |
4 m_printer(0) |
| 918 |
5 { |
| 919 |
6 // accept dnd |
| 920 |
7 setAcceptDrops(true); |
| 921 |
8 |
| 922 |
9 // tell the TDEMainWindow that this is indeed the main widget |
| 923 |
10 setCentralWidget(m_view); |
| 924 |
11 |
| 925 |
12 // then, setup our actions |
| 926 |
13 setupActions(); |
| 927 |
14 |
| 928 |
15 // and a status bar |
| 929 |
16 statusBar()->show(); |
| 930 |
17 |
| 931 |
18 // allow the view to change the statusbar and caption |
| 932 |
19 connect(m_view, SIGNAL(signalChangeStatusbar(const QString&)), |
| 933 |
20 this, SLOT(changeStatusbar(const QString&))); |
| 934 |
21 connect(m_view, SIGNAL(signalChangeCaption(const QString&)), |
| 935 |
22 this, SLOT(changeCaption(const QString&))); |
| 936 |
23 |
| 937 |
24 } |
| 938 |
</programlisting> |
| 939 |
</para> |
| 940 |
<para> |
| 941 |
Notice that <classname>KScribble</classname> inherits the <classname>TDEMainWindow</classname> class - a |
| 942 |
commonly used base class for TDE applications. We initialize a class called <classname>KScribbleView</classname> |
| 943 |
as our central widget, create a <classname>KStatusBar</classname> via the <methodname>statusBar()</methodname> |
| 944 |
method (line 16), and connect some signals and slots together. |
| 945 |
</para> |
| 946 |
</sect2> |
| 947 |
</sect1> |
| 948 |
</chapter> |
| 949 |
|
| 950 |
|
| 951 |
<chapter id="chapter4"> |
| 952 |
<title>Application View Design</title> |
| 953 |
<sect1 id="c4s1"> |
| 954 |
<title>Introduction</title> |
| 955 |
<para> |
| 956 |
When developing an application with a graphical user interface, the main work takes place in |
| 957 |
providing a so-called "view" for the application. A view generally is a widget that displays the data |
| 958 |
of a document and provides methods to manipulate the document contents. This can be done by the user via |
| 959 |
the events he emits by the keyboard or the mouse; more complex operations are often processed by toolbars |
| 960 |
and menubars which interact with the view and the document. The statusbar then provides information about |
| 961 |
the document, view or application status. As an example, we look at how an editor is constructed and where |
| 962 |
we can find which part. |
| 963 |
</para> |
| 964 |
<para> |
| 965 |
An editor generally is supposed to provide an interface to view and/or change the contents of a text |
| 966 |
document for the user. If you start Kate, you see the visual interface as the following: |
| 967 |
<itemizedlist> |
| 968 |
<listitem><para> |
| 969 |
The menubar: providing complex operations as well as opening, saving and closing files and |
| 970 |
exiting the application. |
| 971 |
</para></listitem> |
| 972 |
<listitem><para> |
| 973 |
The toolbar: offers icons which allow quicker access for most needed functions, |
| 974 |
</para></listitem> |
| 975 |
<listitem><para> |
| 976 |
The statusbar: displays the status of the cursor position by the current row and column, |
| 977 |
</para></listitem> |
| 978 |
<listitem><para> |
| 979 |
The view in the center of the window, displaying a document and offering a cursor connected to |
| 980 |
the keyboard and the mouse to operate on the data. |
| 981 |
</para></listitem> |
| 982 |
</itemizedlist> |
| 983 |
</para> |
| 984 |
<para> |
| 985 |
Now it's easy to understand that a view is the most unique part of the application and the design |
| 986 |
of the view decides about the usability and acceptability of an application. This means that one of |
| 987 |
the first steps in development is to determine the purpose of the application and what kind of view |
| 988 |
design would match best to allow any user to work with the application with a minimum of work |
| 989 |
learning how to handle the user interface. |
| 990 |
</para> |
| 991 |
<para> |
| 992 |
For some purposes like text editing and displaying HTML files, views are provided by the Qt and KDE |
| 993 |
libraries; we will discuss certain aspects of these high-level widgets in the next section. |
| 994 |
But for most applications new widgets have to be designed and implemented. It is that what makes a |
| 995 |
programmer also a designer and where his abilities on creativity are asked. Nevertheless, you should |
| 996 |
watch for intuitivity first. Remember, a lot of users won't accept an application that isn't: |
| 997 |
<itemizedlist> |
| 998 |
<listitem><para> |
| 999 |
graphically nice. |
| 1000 |
</para></listitem> |
| 1001 |
<listitem><para> |
| 1002 |
offering a lot of features |
| 1003 |
</para></listitem> |
| 1004 |
<listitem><para> |
| 1005 |
easy to handle |
| 1006 |
</para></listitem> |
| 1007 |
<listitem><para> |
| 1008 |
fast to learn how to use it |
| 1009 |
</para></listitem> |
| 1010 |
</itemizedlist> |
| 1011 |
</para> |
| 1012 |
<para> |
| 1013 |
Needless to say that stability is a major design goal. Nobody can prevent bugs, but a minimum can |
| 1014 |
be reached at least by clever design goals and wide use of object-oriented design. C++ makes programming |
| 1015 |
a joy if you know how to exploit it's capabilities- inheritance, information hiding and reusablitity of |
| 1016 |
already existing code. |
| 1017 |
</para> |
| 1018 |
<para> |
| 1019 |
When creating a KDE or Qt project, you always have to have a view that inherits QWidget, either by |
| 1020 |
direct inheritance or because the library widget you want to use inherits QWidget. Therefore, the |
| 1021 |
Application Wizard already constructed a view that is an instance of a class yourappView, which |
| 1022 |
inherits QWidget already. |
| 1023 |
</para> |
| 1024 |
<para> |
| 1025 |
This chapter therefore describes how to use library widgets for creating views of KDE or |
| 1026 |
Qt applications that are generated with &tdevelop;, then we look at the libraries and what kind of |
| 1027 |
views are already offered. |
| 1028 |
</para> |
| 1029 |
</sect1> |
| 1030 |
<sect1 id="c4s2"> |
| 1031 |
<title>Using Library Views</title> |
| 1032 |
<para> |
| 1033 |
When your application design has been set up, you first should look for already existing code that |
| 1034 |
will make your life a lot easier. A part of this search is to look for a widget that can be used as |
| 1035 |
a view or at least as a part of it; either directly or by inheritance. The KDE and Qt libraries already |
| 1036 |
contain a set of widgets that can be used for this purpose. To use them, you have two options: |
| 1037 |
<orderedlist> |
| 1038 |
<listitem><para> |
| 1039 |
Remove the new view class and create an instance of a library widget; then set this as the view, |
| 1040 |
</para></listitem> |
| 1041 |
<listitem><para> |
| 1042 |
Change the inheritance of the provided view class to the class of the library widget to use. |
| 1043 |
</para></listitem> |
| 1044 |
</orderedlist> |
| 1045 |
</para> |
| 1046 |
<para> |
| 1047 |
In either way, it is important to know that if the application framework is currently not linked |
| 1048 |
against the library that contains the widget, the linker will fail. After you decided to use a |
| 1049 |
certain widget, look for the library to link to; then open "Project"->"Options" from the &tdevelop; |
| 1050 |
menubar. Switch to the "Linker Options" page and look for the checkmarks indicating the libraries |
| 1051 |
that are currently used. If the library of your view widget is already checked, you can leave the |
| 1052 |
project options untouched and start doing the necessary changes due to your choice. If not, and the |
| 1053 |
linker options offer to add the library by a check box, check it and press "OK" to leave the project |
| 1054 |
options dialog again. In any other case, add the library in the edit line below with the -l option. |
| 1055 |
For libraries that your application has to search for before preparing the Makefiles by the |
| 1056 |
configure script on the end-user machine, add the according search macro to the configure.in file |
| 1057 |
located at the root directory of your project and add the macro to the edit line. Mind that you have |
| 1058 |
to run "Build"->"Autoconf and automake" and "Build"->"Configure" before the Makefiles contain the |
| 1059 |
correct expansion for the library macro. |
| 1060 |
</para> |
| 1061 |
<para> |
| 1062 |
Also, if the include files for the library to add are not in the current include path |
| 1063 |
(which can be seen by the -I options in the output window on "Make"), you have to add the path to the |
| 1064 |
Project Options dialog -"Compiler Options" page with the -I option or the according automake macro at |
| 1065 |
the edit line for "Additional Options". |
| 1066 |
</para> |
| 1067 |
<sect2 id="c4s3s1"> |
| 1068 |
<title>Qt Views</title> |
| 1069 |
<para> |
| 1070 |
Looking at the first page of the Qt online documentation, you will find a link to |
| 1071 |
"Widget Screenshots" where you can have a look at how the widgets Qt contains look like. |
| 1072 |
These are ready to use and can be combined together to form complex widgets to create application |
| 1073 |
views or dialogs. In the following, we'll discuss some of these which are very usable for creating |
| 1074 |
application views, but keep in mind that the KDE libraries sometimes contain other widgets for the |
| 1075 |
same purpose; those will be reviewed in the next section. |
| 1076 |
</para> |
| 1077 |
<para> |
| 1078 |
Here are a set of hints for what purpose you could use which Qt component: |
| 1079 |
<orderedlist> |
| 1080 |
<listitem><para> |
| 1081 |
If your view area isn't big enough to display all your data, the user must be enabled to scroll |
| 1082 |
over the document with bars on the left and bottom of the view. For this, Qt provides the class |
| 1083 |
<classname>QScrollView</classname>, which offers a scrollable child area. As explained, you could |
| 1084 |
inherit your own widget from <classname>QScrollView</classname> or use an instance to manage your |
| 1085 |
document's view widget. |
| 1086 |
</para></listitem> |
| 1087 |
<listitem><para> |
| 1088 |
to create a ScrollView yourself, inherit the View widget from <classname>QWidget</classname> |
| 1089 |
and add vertical and horizontal <classname>QScrollBars </classname>. |
| 1090 |
(This is done by KDE`s TDEHTMLView widget.) |
| 1091 |
</para></listitem> |
| 1092 |
<listitem><para> |
| 1093 |
For text processing, use <classname>QTextEdit</classname>. This class provides a complete |
| 1094 |
text editor widget that is already capable to cut, copy and paste text and is managed by a scrollview. |
| 1095 |
</para></listitem> |
| 1096 |
<listitem><para> |
| 1097 |
Use <classname>QTable</classname> to display data that is arranged in a table. |
| 1098 |
As <classname>QTable</classname> is managed by scrollbars as well, it offers a good solution for |
| 1099 |
table calculation applications. |
| 1100 |
</para></listitem> |
| 1101 |
<listitem><para> |
| 1102 |
To display two different widgets or two widget instances at the same time, use <classname>QSplitter |
| 1103 |
</classname>. This allows to tile views by horizontal or vertical dividers. |
| 1104 |
KMail is a good example what this would look like- the main view is separated by a |
| 1105 |
splitter vertically, the right window then is divided again horizontally. |
| 1106 |
</para></listitem> |
| 1107 |
<listitem><para> |
| 1108 |
<classname>QListView</classname> displays information in a list and tree. |
| 1109 |
This is useful for creating file trees or any other hierarchical information you want to interact with. |
| 1110 |
</para></listitem> |
| 1111 |
</orderedlist> |
| 1112 |
</para> |
| 1113 |
<para> |
| 1114 |
You see that Qt alone offers a whole set of widgets which are ready to use so you don't have to invent |
| 1115 |
new solutions if these match your needs. The sideffect when using standard widgets is that users already |
| 1116 |
know how to handle them and only have to concentrate on the displayed data. |
| 1117 |
</para> |
| 1118 |
</sect2> |
| 1119 |
<sect2 id="c4s3s2"> |
| 1120 |
<title>KDE Views</title> |
| 1121 |
<para> |
| 1122 |
The KDE libraries were invented to make designing applications for the K Desktop Environment easier |
| 1123 |
and capable of more functionality than what Qt alone is offering. The tdeui library offers: |
| 1124 |
<orderedlist> |
| 1125 |
<listitem><para> |
| 1126 |
TDEListView: a more powerful version of <classname>QListView</classname> |
| 1127 |
</para></listitem> |
| 1128 |
<listitem><para> |
| 1129 |
TDEIconView: a graphical viewer of icon files |
| 1130 |
</para></listitem> |
| 1131 |
</orderedlist> |
| 1132 |
</para> |
| 1133 |
<para> |
| 1134 |
The tdehtml library, on the other hand, offers a complete HTML-interpreting widget that is ready to use. |
| 1135 |
It is scrollable already, so you don't even have to take care for that. A possible use could be to |
| 1136 |
integrate it as a preview widget for an HTML editor; used by applications such as Konqueror to display HTML files. |
| 1137 |
</para> |
| 1138 |
</sect2> |
| 1139 |
</sect1> |
| 1140 |
<sect1 id="c4s4"> |
| 1141 |
<title>Creating your own Views</title> |
| 1142 |
<para> |
| 1143 |
Not yet written |
| 1144 |
</para> |
| 1145 |
</sect1> |
| 1146 |
</chapter> |
| 1147 |
|
| 1148 |
<chapter id="chapter5"> |
| 1149 |
<title>Configuring Menubars and Toolbars</title> |
| 1150 |
<sect1 id="c5s1"> |
| 1151 |
<title>Introduction</title> |
| 1152 |
<para> |
| 1153 |
Menubars and toolbars are one of the most important parts of an application to provide methods to |
| 1154 |
work with a document structure. As a general rule, you should make all functions available by the menubar. |
| 1155 |
Those methods that should not be available at a current stage of the application process should be |
| 1156 |
disabled. |
| 1157 |
</para> |
| 1158 |
<para> |
| 1159 |
Further, an application can only contain one menubar, but several toolbars. |
| 1160 |
Toolbars on the other hand should contain only the most frequently used commands by pixmap |
| 1161 |
icons or provide quick access methods like combos to select values. |
| 1162 |
</para> |
| 1163 |
</sect1> |
| 1164 |
<sect1 id="c5s2"> |
| 1165 |
<title>How does it work?</title> |
| 1166 |
<para> |
| 1167 |
Our application inherits the <classname>TDEMainWindow</classname> class, which automatically handles creating |
| 1168 |
a menu bar and tool bars for us. In the <methodname>KScribble::setupActions()</methodname> method there is |
| 1169 |
a call to <methodname>TDEMainWindow::createGUI()</methodname>. This method loads a resource file, in this |
| 1170 |
case kscribbleui.rc, to initialize menus at startup. Note that kscribbleui.rc is listed as one of the |
| 1171 |
project files in the Automake Manager. Opening that file up reveals this: |
| 1172 |
<programlisting> |
| 1173 |
1 <!DOCTYPE kpartgui SYSTEM "kpartgui.dtd"> |
| 1174 |
2 <kpartgui name="kscribble" version="1"> |
| 1175 |
3 <MenuBar> |
| 1176 |
4 <Menu name="custom"><text>C&ustom</text> |
| 1177 |
5 <Action name="custom_action" /> |
| 1178 |
6 </Menu> |
| 1179 |
7 </MenuBar> |
| 1180 |
8 </kpartgui> |
| 1181 |
</programlisting> |
| 1182 |
</para> |
| 1183 |
<para> |
| 1184 |
Explanation... |
| 1185 |
</para> |
| 1186 |
<para> |
| 1187 |
Another way to modify the contents of the menu and tool bars is to directly manipulate them through the |
| 1188 |
methods provided by their class. For example, the <methodname>menuBar()</methodname> method returns the |
| 1189 |
<classname>KMenuBar</classname> widget that the menubar for our program. Looking at the documentation for |
| 1190 |
<classname>KMenuBar</classname> and its inheritor class <classname>QMenuBar</classname>, you will find |
| 1191 |
a large number of <methodname>insertItem()</methodname> methods which allow you to add items to the |
| 1192 |
menu bar. |
| 1193 |
</para> |
| 1194 |
<para> |
| 1195 |
<classname>TDEMainWindow</classname>'s methods <methodname>statusBar()</methodname> and <methodname> |
| 1196 |
toolBar()</methodname> will also provide you with applicable widgets. |
| 1197 |
</para> |
| 1198 |
</sect1> |
| 1199 |
<sect1 id="c5s3"> |
| 1200 |
<title>Keyboard Accelerator Configuration</title> |
| 1201 |
<para> |
| 1202 |
A very professional thing you should always add to your application are keyboard accelerators. |
| 1203 |
Those are mainly used by experienced users that want to work fast with their applications and |
| 1204 |
are willing to learn shortcuts. For this, the KDE libraries provide the class <classname> |
| 1205 |
TDEAction</classname>, which provides the keyboard accelerator keys and access to global configured |
| 1206 |
standard keyboard accelerators. |
| 1207 |
</para> |
| 1208 |
<para> |
| 1209 |
By default, frame applications generated by &tdevelop; only use standard keyboard accelerators |
| 1210 |
such as F1 for accessing online-help, Ctrl+N for New File etc. |
| 1211 |
</para> |
| 1212 |
<para> |
| 1213 |
If your application contains a lot of accelerators, you should make them configurable |
| 1214 |
by an Options-menu; either it could be combined with other application configuration in a QWidget |
| 1215 |
or stand alone. The KDE library already provides a <classname>KKeyChooser</classname> |
| 1216 |
for use in tab dialogs, whereas <classname>KKeyDialog</classname> provides a ready-to use |
| 1217 |
key-configuration dialog. |
| 1218 |
</para> |
| 1219 |
|
| 1220 |
</sect1> |
| 1221 |
</chapter> |
| 1222 |
|
| 1223 |
<!-- |
| 1224 |
<chapter id="chapter6"> |
| 1225 |
<title>Other Features</title> |
| 1226 |
</chapter> |
| 1227 |
|
| 1228 |
<chapter id="chapter7"> |
| 1229 |
<title>Printing Support</title> |
| 1230 |
</chapter> |
| 1231 |
--> |
| 1232 |
<chapter id="chapter8"> |
| 1233 |
<title>Help Functions</title> |
| 1234 |
<sect1 id="c8s1"> |
| 1235 |
<title>Introduction</title> |
| 1236 |
<para> |
| 1237 |
A very important part of the development process is to provide help functionality to the user |
| 1238 |
wherever possible. Most developers tend to delay this, but you should remember that a normal user |
| 1239 |
isn't necessarily a Unix expert. He may come from the the dark side of computer software usage offering |
| 1240 |
all sweets that a user may need to work himself into using an application even without ever touching the |
| 1241 |
manuals. Therefore, the KDE and Qt library provide all means usually considered making an application |
| 1242 |
professional in the eyes of the normal user by help functions that are ready to use. |
| 1243 |
Within the application, those are:</para> |
| 1244 |
<itemizedlist> |
| 1245 |
<listitem><para>Tool-Tips</para></listitem> |
| 1246 |
<listitem><para>Statusbar help</para></listitem> |
| 1247 |
<listitem><para>What's this...? buttons</para></listitem> |
| 1248 |
</itemizedlist> |
| 1249 |
<para> |
| 1250 |
Additionally, the application should provide means to access a HTML-based online manual directly |
| 1251 |
using the standard help key F1. This context based help system is provided automatically through the |
| 1252 |
<classname>TDEMainWindow</classname> class, though as the author you must provide the content. |
| 1253 |
</para> |
| 1254 |
<para> |
| 1255 |
As &tdevelop; also offers all types of help as well as the KDE framework generated by the |
| 1256 |
application wizard already contains support for this, this chapter will help you find out where |
| 1257 |
and how to add your help functionality. </para> |
| 1258 |
<para> |
| 1259 |
During the development of your application you should try to be consistent whatever you're doing; |
| 1260 |
therefore you should do the necessary steps directly while extending the code. This will prevent you |
| 1261 |
from diving into the code again and figuring out what your application does or what you intended by |
| 1262 |
certain parts of the code. |
| 1263 |
</para> |
| 1264 |
</sect1> |
| 1265 |
|
| 1266 |
<sect1 id="c8s2"> |
| 1267 |
<title>Tool-Tips</title> |
| 1268 |
<para> |
| 1269 |
A very easy means of providing help are tool-tips. Those are small help messages popping up while |
| 1270 |
the user moves the mouse over a widget that provides a tool-tip and disappears when the mouse moves away. |
| 1271 |
The most popular usage of tool-tips is made in toolbars where your tool-tips should be kept as small |
| 1272 |
as possible because toolbars can be configured to display their contents in various ways: |
| 1273 |
either displaying the button, button with text on the right, button with text below, text only. |
| 1274 |
This possibility should be made configurable by the user, but isn't a must-be. The text is shown |
| 1275 |
as a tool-tip anyway and a toolbar usually consists of buttons and other widgets like lineedits and |
| 1276 |
combo boxes. For a complete reference, see the <classname>TDEToolBar</classname> class reference located |
| 1277 |
in the tdeui library. |
| 1278 |
</para> |
| 1279 |
<para> |
| 1280 |
As an example, we have a look at the "New File" button in a generic application: |
| 1281 |
</para> |
| 1282 |
<para> |
| 1283 |
There, the part i18n("New File") provides a tool-tip message. It is enclosed by the i18n() |
| 1284 |
macro provided by kapp.h to translate the tool-tip towards the currently selected language. |
| 1285 |
</para> |
| 1286 |
<para> |
| 1287 |
Tool-tips can also be added to any custom widget by using the <classname>QToolTip</classname> |
| 1288 |
provided by Qt. An example of that would be: |
| 1289 |
</para> |
| 1290 |
</sect1> |
| 1291 |
<sect1 id="c8s3"> |
| 1292 |
<title>Extending the Statusbar</title> |
| 1293 |
<para> |
| 1294 |
As the applications that inherit <classname>TDEMainWindow</classname> contain a statusbar as well, |
| 1295 |
it also offers a set of statusbar messages already for all menu and toolbar items. A statusbar |
| 1296 |
help message is a short message that extends the meaning of a tool-tip or can be seen as a replacement |
| 1297 |
for a tool-tip over menubar items and is (as the name suggests) displayed in the statusbar when the user |
| 1298 |
enters a menu and highlights the menu entry. |
| 1299 |
</para> |
| 1300 |
</sect1> |
| 1301 |
<sect1 id="c8s4"> |
| 1302 |
<title>The <guibutton>What's This...?</guibutton> Button</title> |
| 1303 |
<para> |
| 1304 |
The <guibutton>What's This...?</guibutton> button provides help windows with the intention |
| 1305 |
that the user wants to get help about a certain widget within the working view or a toolbar item. |
| 1306 |
It is placed in the toolbar and gets activated once the user hits the button. The cursor changes |
| 1307 |
to an arrow cursor with a question mark like the button itself looks like. The the user can press on |
| 1308 |
a visible widget item and gets a help window. As an exercise, you could try this behavior with the |
| 1309 |
<guibutton>What's this...?</guibutton> button within &tdevelop;. |
| 1310 |
</para> |
| 1311 |
<para> |
| 1312 |
To add the What's This...? help to one of your widgets, use the static method |
| 1313 |
<methodname>QWhatsThis::add(QWidget *widget, const QString &text)</methodname> |
| 1314 |
</para> |
| 1315 |
</sect1> |
| 1316 |
</chapter> |
| 1317 |
|
| 1318 |
<chapter id="chapter9"> |
| 1319 |
<title>Documentation</title> |
| 1320 |
<sect1 id="c9s1"> |
| 1321 |
<title>Introduction</title> |
| 1322 |
<para> |
| 1323 |
Due to the fact that projects often lack a complete set of user documentation, |
| 1324 |
all &tdevelop; projects contain a pre-build handbook that can be easily adapted; |
| 1325 |
therefore fulfiling another goal of KDE: providing enough online-help to support users that |
| 1326 |
are not familiar with an application. This chapter therefore introduces you on how to extend |
| 1327 |
the provided documentation template and what you have to do to make it available to the user. |
| 1328 |
</para> |
| 1329 |
</sect1> |
| 1330 |
<sect1 id="c9s2"> |
| 1331 |
<title>User Documentation</title> |
| 1332 |
<para> |
| 1333 |
The documentation for your project lies in projectdir/doc/en, or perhaps another directory if English |
| 1334 |
isn't your native language. Therein lies a file, index.docbook, in which the documentation is stored. |
| 1335 |
The format for editing this file is explained on |
| 1336 |
<ulink url="http://i18n.kde.org/doc/markup/">KDE's documentation website</ulink>. |
| 1337 |
</para> |
| 1338 |
</sect1> |
| 1339 |
<sect1 id="c9s3"> |
| 1340 |
<title>Programmer Documentation</title> |
| 1341 |
<para> |
| 1342 |
Another important part of the documentation is including a descriptive help for your class interfaces. |
| 1343 |
This will allow you and other programmers to use your classes by reading the HTML class documentation |
| 1344 |
that can be created with KDoc. &tdevelop; supports the use of KDoc completely by creating the |
| 1345 |
KDE-library documentation, also your application frameworks are already documented. To work yourself |
| 1346 |
into the provided code, it would be a good start to read the included documentation online. |
| 1347 |
The following describes what to do to get the API documentation, where &tdevelop; helps you add it |
| 1348 |
and what kind of special tags KDoc provides. |
| 1349 |
</para> |
| 1350 |
</sect1> |
| 1351 |
</chapter> |
| 1352 |
|
| 1353 |
<chapter id="chapter10"> |
| 1354 |
<title>Internationalization</title> |
| 1355 |
<sect1 id="c10s1"> |
| 1356 |
<title>Introdction</title> |
| 1357 |
<para> |
| 1358 |
i18n is an internationalization system that is used to offer internationalized versions of an |
| 1359 |
application or project. The difficulty with writing applications is that they only support the |
| 1360 |
language they originally are composed with; visually this can be seen on labels, menu entries and the |
| 1361 |
like. The goal of the internationalization is to provide applications and library functions in the |
| 1362 |
language of the user; therefore enabling users that are not native speakers the original language to make |
| 1363 |
use of the provided functionality and feel more comfortable. |
| 1364 |
</para> |
| 1365 |
</sect1> |
| 1366 |
<!-- |
| 1367 |
<sect1 id="c10s2"> |
| 1368 |
<title>How KDE support Internationalization</title> |
| 1369 |
<para> |
| 1370 |
</para> |
| 1371 |
</sect1> --> |
| 1372 |
</chapter> |
| 1373 |
<!-- |
| 1374 |
<chapter id="chapter11"> |
| 1375 |
<title>Finding Errors</title> |
| 1376 |
</chapter> |
| 1377 |
|
| 1378 |
<chapter id="chapter12"> |
| 1379 |
<title>Licensing</title> |
| 1380 |
</chapter> |
| 1381 |
|
| 1382 |
<chapter id="chapter13"> |
| 1383 |
<title>References</title> |
| 1384 |
</chapter> |
| 1385 |
--> |
| 1386 |
<chapter id="credits"> |
| 1387 |
<title>Credits</title> |
| 1388 |
|
| 1389 |
<para> |
| 1390 |
(... to be written ...) |
| 1391 |
</para> |
| 1392 |
|
| 1393 |
<!--CREDITS_FOR_TRANSLATORS--> |
| 1394 |
|
| 1395 |
</chapter> <!-- credits --> |
| 1396 |
|
| 1397 |
<appendix id="bibliography"> |
| 1398 |
<title>Bibliography</title> |
| 1399 |
<bibliography> |
| 1400 |
|
| 1401 |
<biblioentry> |
| 1402 |
<title><ulink url="info://make/Top">GNU Make Manual</ulink></title> |
| 1403 |
<authorgroup> |
| 1404 |
<author><firstname>Richard M.</firstname><surname>Stallman</surname></author> |
| 1405 |
<author><firstname>Roland</firstname><surname>McGrath</surname></author> |
| 1406 |
</authorgroup> |
| 1407 |
</biblioentry> |
| 1408 |
|
| 1409 |
<biblioentry> |
| 1410 |
<title><ulink url="info://automake/Top">GNU Automake</ulink></title> |
| 1411 |
<authorgroup> |
| 1412 |
<author><firstname>David</firstname><surname>MacKenzie</surname></author> |
| 1413 |
<author><firstname>Tom</firstname><surname>Tromey</surname></author> |
| 1414 |
</authorgroup> |
| 1415 |
</biblioentry> |
| 1416 |
|
| 1417 |
<biblioentry> |
| 1418 |
<title><ulink url="info://autoconf/Top">GNU Autoconf</ulink></title> |
| 1419 |
<authorgroup> |
| 1420 |
<author><firstname>David</firstname><surname>MacKenzie</surname></author> |
| 1421 |
<author><firstname>Ben</firstname><surname>Elliston</surname></author> |
| 1422 |
</authorgroup> |
| 1423 |
</biblioentry> |
| 1424 |
|
| 1425 |
<biblioentry> |
| 1426 |
<title><ulink url="info://gcc/Top">Using the GNU Compiler Collection</ulink></title> |
| 1427 |
<author><firstname>Richard M.</firstname><surname>Stallman</surname></author> |
| 1428 |
</biblioentry> |
| 1429 |
|
| 1430 |
<biblioentry> |
| 1431 |
<title><ulink url="info://libtool/Top">GNU Libtool</ulink></title> |
| 1432 |
<authorgroup> |
| 1433 |
<author><firstname>Gordon</firstname><surname>Matzigkeit</surname></author> |
| 1434 |
<author><firstname>Alexandre</firstname><surname>Oliva</surname></author> |
| 1435 |
<author><firstname>Thomas</firstname><surname>Tanner</surname></author> |
| 1436 |
<author><firstname>Gary V.</firstname><surname>Vaughan</surname></author> |
| 1437 |
</authorgroup> |
| 1438 |
</biblioentry> |
| 1439 |
|
| 1440 |
<biblioentry> |
| 1441 |
<title>GNU Autoconf, Automake, and Libtool</title> |
| 1442 |
<edition>1st edition</edition> |
| 1443 |
<pubdate>October 2000</pubdate> |
| 1444 |
<authorgroup> |
| 1445 |
<author><firstname>Gary V.</firstname><surname>Vaughan</surname></author> |
| 1446 |
<author><firstname>Ben</firstname><surname>Elliston</surname></author> |
| 1447 |
<author><firstname>Tom</firstname><surname>Tromey</surname></author> |
| 1448 |
<author><firstname>Ian Lance</firstname><surname>Taylor</surname></author> |
| 1449 |
</authorgroup> |
| 1450 |
<publisher><publishername>New Riders Publishing</publishername></publisher> |
| 1451 |
<isbn>ISBN 1578701902</isbn> |
| 1452 |
</biblioentry> |
| 1453 |
|
| 1454 |
|
| 1455 |
<biblioentry> |
| 1456 |
<title>Advanced Programming in the UNIX(R) Environment</title> |
| 1457 |
<edition>1st edition</edition> |
| 1458 |
<pubdate>June 1992</pubdate> |
| 1459 |
<author><firstname>W. Richard</firstname><surname>Stevens</surname></author> |
| 1460 |
<publisher><publishername>Addison-Wesley Pub Co</publishername></publisher> |
| 1461 |
<isbn>ISBN 0201563177</isbn> |
| 1462 |
</biblioentry> |
| 1463 |
|
| 1464 |
<biblioentry> |
| 1465 |
<title>Thinking in C++, Volume 1: Introduction to Standard C++</title> |
| 1466 |
<edition>2nd Edition</edition> |
| 1467 |
<pubdate>April 15, 2000</pubdate> |
| 1468 |
<author><firstname>Bruce</firstname><surname>Eckel</surname></author> |
| 1469 |
<publisher><publishername>Prentice Hall</publishername></publisher> |
| 1470 |
<isbn>ISBN 0139798099</isbn> |
| 1471 |
</biblioentry> |
| 1472 |
|
| 1473 |
<biblioentry> |
| 1474 |
<title>Open Source Development with CVS</title> |
| 1475 |
<edition>2nd Edition</edition> |
| 1476 |
<pubdate>October 12, 2001</pubdate> |
| 1477 |
<authorgroup> |
| 1478 |
<author><firstname>Karl</firstname><surname>Fogel</surname></author> |
| 1479 |
<author><firstname>Moshe</firstname><surname>Bar</surname></author> |
| 1480 |
</authorgroup> |
| 1481 |
<publisher><publishername>The Coriolis Group</publishername></publisher> |
| 1482 |
<isbn>ISBN 158880173X</isbn> |
| 1483 |
</biblioentry> |
| 1484 |
|
| 1485 |
<biblioentry> |
| 1486 |
<title>Programming PHP</title> |
| 1487 |
<edition>1st edition</edition> |
| 1488 |
<pubdate>March 2002</pubdate> |
| 1489 |
<authorgroup> |
| 1490 |
<author><firstname>Rasmus</firstname><surname>Lerdorf</surname></author> |
| 1491 |
<author><firstname>Kevin</firstname><surname>Tatroe</surname></author> |
| 1492 |
</authorgroup> |
| 1493 |
<publisher><publishername>O'Reilly & Associates</publishername></publisher> |
| 1494 |
<isbn>ISBN 1565926102</isbn> |
| 1495 |
</biblioentry> |
| 1496 |
|
| 1497 |
<biblioentry> |
| 1498 |
<title>Programming Python</title> |
| 1499 |
<edition>2nd Edition</edition> |
| 1500 |
<pubdate>March 2001</pubdate> |
| 1501 |
<author><firstname>Mark</firstname><surname>Lutz</surname></author> |
| 1502 |
<publisher><publishername>O'Reilly & Associates</publishername></publisher> |
| 1503 |
<isbn>ISBN 0596000855</isbn> |
| 1504 |
</biblioentry> |
| 1505 |
|
| 1506 |
<biblioentry> |
| 1507 |
<title>Gui Programming With Python : Using the Qt Toolkit</title> |
| 1508 |
<edition>Bk&Cd-r edition</edition> |
| 1509 |
<pubdate>January 2002</pubdate> |
| 1510 |
<author><firstname>Boudewijn</firstname><surname>Rempt</surname></author> |
| 1511 |
<publisher><publishername>Opendocs Llc</publishername></publisher> |
| 1512 |
<isbn>ISBN 0970033044</isbn> |
| 1513 |
</biblioentry> |
| 1514 |
|
| 1515 |
<biblioentry> |
| 1516 |
<title>Programming Perl</title> |
| 1517 |
<subtitle>The Camel book</subtitle> |
| 1518 |
<edition>3rd Edition</edition> |
| 1519 |
<pubdate>July 2000</pubdate> |
| 1520 |
<authorgroup> |
| 1521 |
<author><firstname>Larry</firstname><surname>Wall</surname></author> |
| 1522 |
<author><firstname>Tom</firstname><surname>Christiansen</surname></author> |
| 1523 |
<author><firstname>Jon</firstname><surname>Orwant</surname></author> |
| 1524 |
</authorgroup> |
| 1525 |
<publisher><publishername>O'Reilly & Associates</publishername></publisher> |
| 1526 |
<isbn>ISBN 0596000278</isbn> |
| 1527 |
</biblioentry> |
| 1528 |
|
| 1529 |
<biblioentry> |
| 1530 |
<title>Learning Perl</title> |
| 1531 |
<subtitle>The Lama book</subtitle> |
| 1532 |
<edition>3rd Edition</edition> |
| 1533 |
<pubdate>July 15, 2001</pubdate> |
| 1534 |
<authorgroup> |
| 1535 |
<author><firstname>Randal L.</firstname><surname>Schwartz</surname></author> |
| 1536 |
<author><firstname>Tom</firstname><surname>Phoenix</surname></author> |
| 1537 |
</authorgroup> |
| 1538 |
<publisher><publishername>O'Reilly & Associates</publishername></publisher> |
| 1539 |
<isbn>ISBN 0596001320</isbn> |
| 1540 |
</biblioentry> |
| 1541 |
|
| 1542 |
</bibliography> |
| 1543 |
|
| 1544 |
&underFDL; |
| 1545 |
|
| 1546 |
|
| 1547 |
</appendix> |
| 1548 |
|
| 1549 |
</book> |