# The &kdevelop; User Manual

The Reference Guide to the &kdevelop; Integrated Development Environment for &UNIX; Systems,
Ralf
Nolden

    Ralf.Nolden@post.rwth-aachen.de

1999
2000
2001
Ralf Nolden
&FDLNotice;
18/1/2000
1.4.0

This user manual gives the user a complete overview of the &kdevelop; &IDE; and describes the basic development process in brief.

KDE
kdevelop
development
IDE
programming

## Introduction

As everything on earth has it's fashions, today's computer world seems to tend more to the use of free software even for commercial purpose. The most popular free software project is &Linux;. It is now generally agreed that &Linux;, (as well as other projects such as the Apache web server, the Perl language and GNU suite of tools), proves that free software can be of as high a quality as commercial software. But despite the quality, end users must still suffer under the cryptic commands of any &UNIX; Systems. For &Linux; to thrive, it needs applications, both free and commercial, and ease of use.

The
&kde; project tries to close this gap by providing an easy to use desktop and the companion libraries to extend the variety of available
&GUI; based software. But especially as free software is often made in the author's free time, the question for many programmers is how much they like the current code development environment. &kdevelop; wants to take another major step: making the programmer's life easier and more efficient: products created with &kdevelop; can reach a higher level of reliability and functionality in the same development period.

To fulfill this goal, the &kdevelop; Integrated Development Environment provides many features that developers need, at the same time wrapping the functionality of thirdparty projects such as make and the GNU C++ Compiler
and makes them an invisible, integrated part of the development process.

&kdevelop; manages:

- All development tools needed for C++ programming, including the Compiler, Linker, automake and autoconf.

- KAppWizard, which generates complete, ready-to-go sample applications.

- Classgenerator, for creating new
  classes and integrating them into the current project.

- File management for sources, headers, documentation &etc; to be included in the project.

- The creation of User Handbooks written with
  SGML and the automatic generation of
  HTML with the &kde; look and feel

- Automatic HTML-based API documentation for your project's classes, with cross-references to the libraries used.

- Internationalization support for your application, allowing translators to easily add their target language to a project.

- Creation of user interfaces through interaction with TrollTech's &Qt; Designer

- Managing of your project via CVS by providing an easy to use front end for most functions.

- Debugging your application with the debugger of your choice - either the internal &kdevelop; debugger, or use ddd or kdbg

- Editing of project specific
  pixmaps with &kiconedit;

- The inclusion of any other program you are accustomed to using for development, by simply adding it to the Tools, according to your individual needs.

&kdevelop; makes development a joy by allowing you to work with all your applications in one place, and saves time by automating standard development processes, while still giving you direct and transparent access to all the information you need while working.

The integrated browsing mechanisms are designed to support documentation requests that developers have, in conjunction with their project.

The Class viewer and error finder can take you anywhere in your project code with a mouse click, and no need to search for files. File trees give direct access to the project files, and the integrated help system offers superb access to online documentation from anywhere within the &IDE;

## About this Handbook

This user manual gives the user a complete overview of the &kdevelop; &IDE; and describes the basic development process in brief. For more information about specific programming issues, we suggest reading the KDevelop Programming Handbook included with &kdevelop;, which covers themes such as understanding generated application frameworks, and how to create full-featured &kde; applications using example projects. See also the included Tutorial Handbook as well as the &kde; 2.0 Development book available at local bookstores in printed form or online at http://www.andamooka.org.

This User Guide is broken up into the following parts:

Chapter

  Covers the system requirements, installation, and setting up of &kdevelop;.

Chapter

  Tells you how programs are created with standard GNU development tools, and how they are built.

Chapter

  Takes you on a short tour describing the main functionality of the environment.

Chapter

  Explains the menus and dialogs, as well as the keyboard shortcuts.

Chapter

  Shows how to use the built-in documentation browser and additional help functions.

Chapter

  Explains the features and functions available to you when working with file management and in the editor.

Chapter

  Describes the creation and maintenance of software projects.

Chapter

  Contains a reference on how to set compiler and linker flags, and other project settings.

Chapter

  Tells you how to make user of &kdevelop;'s powerful Class Browser

Chapter

  Features how to use &Qt; Designer while working on your project and how &kdevelop; seamlessly cooperates with Designer.

Chapter

  Gives an overview of the debugging setup, and discusses the use of the internal debugger.

Chapter

  Tells you how to use the revision control systems CVS and RCS with your &kdevelop; project.

Chapter

  Shows you how to set up overall preferences for customizing &kdevelop; to your own needs.

Chapter

  Covers questions you might have about using &kdevelop; under different flavours of &UNIX; and other general solutions to common problems.

For programming beginners, and for new users of this product, we recommend you read this manual thoroughly before starting to actually work with the &IDE;, as it covers the usage in depth. The understanding of how things are done and how different parts of the &IDE; relate to each other will save you a lot of time searching for functions and features, and it will enable you to immediately make use of the the first-class development tools available to you.

### About the &kdevelop; project

The &kdevelop; project was started in summer of 1998 after &kde; 1.0 was available on &Linux;/&UNIX; to make the attempt of creating an easy to use C/C++ &IDE; for programmers, especially targeting on the &kde; desktop. Since then the project has found a lot of helpers and supporters as well as sponsors who want to help the team continue their work on this now widely recognized programming environment. Within one and a half year, the &IDE; developed to a full-featured &kde; application with the most possible functionality and stability as the creators started to develop the &IDE; with the &IDE; itself at the time enough usability was given. Therefore bugs were mostly found by the authors and could be fixed very quickly as well as needed extensions for programming &kde; applications.

The first official stable release was made with version 1.0 on December 6, 1999. Thereafter, the &kdevelop; Team introduced more features and stability into the &IDE; by new code or code that was unstable before, which lead to the second release as version 1.1 on February 28, 2000.

Since then, the project continued by integrating more functionality and simplifying the current codebase. At the same time, many translators began working to transfer &kdevelop; to as many languages as possible, to provide the international developer community the &IDE; in their own language, including the handbooks that ship with it. Many users contributed their experience and knowledge to the project as one of the most promising products for &Linux;/&UNIX; developers to make it even more stable and portable to other Unices.

After the 1.2 release on May 4th, we continued fixing several bugs while working on a 2.0 version using the &kde; 2.0 API and the latest technologies &kde; 2.0 offers. Since the release of &Qt; 2.2.0 brought &Qt;īs Designer for constructing user interfaces which also supports &kde; widgets, the Designer is about to replace &kdevelop;'s own dialog editor as it offers dynamic layout management and directly connecting widgets. To support using the Designer within &kdevelop;, the templates and &kdevelop; have been updated to make easy use of it while working on a &kde; 2.0 or &Qt; 2.2.x project.

The 1.3 release marked another milestone. It was the last version that needed &kde; 1.x libraries to run and was much anticipated through the offers it made towards development for the new &kde; 2.0 platform when it was released on December 11th, 2000.

Since then John Birch and I decided that we really would like to have a &kde; 2.x version of our baby, &kdevelop;. We took the time and made it; by the end of 2000, we roughly had the functionality to say we were almost ready. While &kde; 2.1 was shortly to come out in early 2001, we decided to ship &kdevelop; with the base &kde; distribution as this version will make many new &kde; developers happy to start working on a great API on a free system to develop software for.

### Printed Versions

A printed version of the complete &kdevelop; Documentation is available as the book titled Developing Applications for Linux: KDE Edition, which can be ordered either online from the &kdevelop; website at http://www.kdevelop.org or at http://www.opendocs.org. A share of the Gross Profits from the sales of this book goes back to the &kdevelop; project to support continuing the further development of &kdevelop;.

Printable versions of the &kdevelop; documentation can be obtained from the &kdevelop; website at http://www.kdevelop.org in &DVI;, &PostScript; and PDF forat, in both A4 and Letter size.

## Installation of &kdevelop;

### How to obtain &kdevelop;

&kdevelop; can be found either on the &kde; applications page, at http://www.kde.org/current.html or on the &kdevelop; homepage at http://www.kdevelop.org. &kdevelop; is also available with &Linux; distributions such as SuSE 6.x and 7.x and others.

We're also offering snapshots of the &kdevelop; CVS repository on our homepage for those who want to stay up to date with &kdevelop;. Usually, the snapshots are not intended to be used for production but as a test for new features and to give an insight into development progress of the &kdevelop; team. Also we offer various third party software needed by &kdevelop; directly such as KDoc and KDbg.

If you're experiencing problems with compiling or using &kdevelop;, please read the Questions and Answers section of this handbook or the &FAQ; file included with the &kdevelop; package.

If your problem is not addressed, please subscribe to the &kdevelop; mailing list at kdevelop-request@barney.cs.uni-potsdam.de by sending a mail with an empty header and `subscribe youremailaddress` as contents. Requests and problem report should only target the usage of the &kdevelop; &IDE; and not any questions that regard any implementation problem you may have while coding your own application. All e-mail sent to the mailing list should be written in English, so that all participants can take part on discussions and are able to provide better help. The mailing list is also intended for those users willing to contribute and who found solutions for any problems they experienced, so we can fix errors and include that knowledge to give beginners an even more qualified first-hand help.

An good way to report problems is to send the output you get by starting &kdevelop; from the console or to copy and paste the contents of &kdevelop;'s internal Messages window.

### Requirements

In order to successfully compile and use &kdevelop;, you need the following programs and libraries which are available on most platforms as distribution packages and thereby can be installed easily.

Required

  - g++ 2.7.2/g++ 2.8.1/egcs 1.1 (or compatible), available at http://www.gnu.org.

  - Perl 5.004, available at http://www.perl.org

  - autoconf 2.13, also available from http://www.gnu.org

  - automake 1.4, also from http://www.gnu.org

  - flex 2.5.4

  - GNU gettext available at http://www.gnu.org

  - &Qt; 2.2.x, available from http://www.trolltech.no

  - &kde; 2.1, available from http://www.kde.org

Optional

  - enscript for printing support.

  - ghostview or &kghostview for printing review

  - glimpse 4.0 for the search index, available at http://glimpse.cs.arizona.edu

  - sgmltools 1.0, available at http://www.sgmltools.org

  - &kde;-SDK (the KDE Software Development Kit), which includes KDoc, KTranslator and KBabel, (available at http://developer.kde.org.

  - KDbg, available from http://members.telecom.at/~johsixt/kdbg.html

  - &kiconedit;, available at http://www.kde.org

  - &Qt; Designer and uic, which come with &Qt; 2.2.x

&kdevelop; was tested with SuSE &Linux; as well as on several other platforms.

As far as is known to the authors, SuSE &Linux; and FreeBSD contain all necessary packages, including enscript, either as packages or rpm's, so you should have no problem installing all the required third party software.

### Documentation

For creating the &kde; library documentaiton, you need the kdelibs package in source form available on your system, as provided by the &kde; project, or as included in the source packages of your distribution. You also need KDoc, included in the &kde;-SDK

We also offer from our homepage at http://www.kdevelop.org a C/C++ reference that is integrated in the &kdevelop; documentation browser after it's installation. Download the package and copy the source file as root into your $`KDEDIR` and untar it with ``tar` `zxvf` `c_c++_reference.tar.gz``, and then the reference is available in your documentation tree. If you have not done this, selecting the reference book in the browser will show an error page which includes a link to the &kdevelop; homepage, and a description of the installation process.

### Compilation and Installation

In order to compile and install &kdevelop; on your system, type the following in the base directory of the &kdevelop; distribution:

    &percnt; ./configure
    &percnt; make

    (as root)

    &percnt; make install

Since &kdevelop; uses autoconf you should have not trouble compiling it.

In order to compile the &kdevelop; CVS snapshot, type the following:

    &percnt; make -f Makefile.cvs
    &percnt; ./configure
    &percnt; make

    (as root)

    &percnt; make install

If your system's make command is gmake, type ``gmake`` instead of ``make``

### Starting &kdevelop;

If you use &kde; as your window manager, &kdevelop; can be started by choosing K Development KDevelop 1.4. As &kdevelop; supports &kde; mime types, you can also start a &kdevelop, project file (`*.kdevprj`, displayed with the &kdevelop; project icon) in the &kde; file manager, &konqueror;. This will start &kdevelop; and load the project.

Under other window managers, open a console and type:

    &percnt; kdevelop yourProject.kdevprj

Under each user account, &kdevelop; will invoke the automatic installation process on the first startup. This allows for a quick configuration of the most commonly used options. If your installation is not functioning correctly, you can reconfigure &kdevelop; any time by entering:

    &percnt; kdevelop --setup

or, when using &kde;, by choosing K Development KDevelop Setup

### The Installation Program

&kdevelop; includes an automatic installation program module which is invoked whenever &kdevelop; is started and the configuration file `kdeveloprc` does not exist. We suggest you follow the installation steps by choosing Proceed to automatically check your system and to set up your &kdevelop; environment.

The Installation dialog's buttons execute the following actions:

Help

  Will open the &khelpcenter; program

Proceed

  This stats the installation process and executes following actions:

  - Checking for make or gmake, autoconf, autoheader, automake and perl for the creation and compilation of new applications generated by &kdevelop;. If gmake is installed, the `make` command will be set to automatically use gmake. Other commandline options to your make program can be set in the Setup dialog which you can later access through the Options menu.

  - Checking for KDoc and glimpse. These allow you to create &kde; library documentation, and a search index. If tey are found this will happen automatically, later in the setup process.

  - Checking for enscript to ensure that printing is available. This program has to be installed to allow correct printing, but if it is not installed, you can do this at any time later, without having to run the setup process again.

  - Checking for KDbg, &kiconedit; and KTranslator. We encourage you to install these programs, as they assist in creating complete &kde; applications. Note that KDbg is used directly for debugging your current project within &kdevelop;. &kiconedit; is used to display and edit the pixmaps selected in the file-viewer trees. The programs KDbg, &kiconedit;, and KTranslator are then configured to be available in the Tools menu of the &kdevelop; menu bar, if they are found. Other tools can be added to the Tools menu by selecting Tools... in the Options menu.

  - The installer will next list a summary of the programs found and those it didn't. Additional hints are displayed if you are missing one of the necessary programs.

  - Detection of your &Qt; documentation path. This checks several standard paths in your system for the documentation, and sets the path automatically. If your &Qt; documentation could not be found, either because it is not installed, or because your system keeps it in a different location, a message will appear that asks you to set the correct path manually or to continue. Choosing to set the path will return to the main installation window, which shows an editing field with a button on the right to choose the path. Usually this is in the `qt/html` After you have done this, the installation can continue with the selection of Proceed again.

  - If KDoc was detected, you are asked to create/update your &kde; library documentation. For this you need to have the &kde; libraries in source form. For &Linux; users who have installed &kde; from a distribution, we suggest copying and extracting the source of the kdelibs package to your system. For FreeBSD users who installed the kdelibs as a package, you should look for the appropriate distfile package in the ports collection. If neither of these cases match your situation, you should download the sources from http://www.kde.org and untar the sources on your system. If you wish to use the documentation provided by http://developer.kde.org, cancel the creation and continue with creating the search index. After the installer is finished, and &kdevelop; has been started, set the path to the extracted documentation package in the &kdevelop; Setup dialog, and run the search index setup again, which can be found in the same Setup page of the dialog.

    The Update KDE Library documentation dialog is set up to use a default path for the location of the documentation, in `$HOME/.kde/share/apps/kdevelop/KDE-Documentation` . The only thing you have to do is choose the path to your library sources with the selection button at the top of the dialog, and then press OK. As an example, if you got the `kdelibs.tar.gz` package from http://www.kde.org and downloaded it to your home directory, you should open a console or terminal, and enter ``tar` `zxvf` `kdelibs.tar.gz``. This will untar the sources into a directory at `$HOME/kdelibs`, which then contains the sources for each library in a subdirectory. For kdecore on my machine, for example, this would now be `/home/rnolden/kdelibs/kdecore`. Now the path you have to ender for the &kde; library documentation dialog would be the path for all the libraries, in this example, `/home/rnolden/kdelibs`. After pressing the OK button, a message in the installation window shows that the documentation is in progress, and you should wait for the next message.

    On a multi user system, or systems with disk quotats for user accounts, the installation of a complete set of HTML documentation for each user would be a waste of disk space. In this case, ask your system administrator to run &kdevelop; under the root account, to allow write access to the system's root directory. Then installing the documentation within the &kde directory, under `$KDEDIR/share/apps/kdevelop/KDE-Documentation`.This path can then be set up later by each user in their &kdevelop; setup dialog, available in the Options menu.

  - If the system check found the glimpse program on your system, you are offered the chance now to create a search database. The search database can be created with the options of including the &kde; documentation and the &Qt; documentation (this is the default). Additionally, the &kdevelop; documentation is included and will be indexed. If you have other documentation that you want indexed, you can select the directories and add them to the indexing process as well.

  - During the creation of the search index, the installation window will show a message that this is in progress.

  - If all the above installation steps were completed correctly, a final message states that &kdevelop; will be started after pressing OK. Keep in mind that you can set up additional options like auto saving in the &kdevelop; Setup dialog that can be accessed through the Options menu.

## Programs

Now that &kdevelop; installed successfully, and the most commonly used options are set, you are probably wondering if it can live up to it's promises. This chapter aims to give you a guideline as to how programs are created using the GNU tools in general, and in particular what part &kdevelop; plays in this game.

### The Compiler

The Compiler is actually the one program on your system that has to be installed at a minimum in order to create running programs. He is the one that compiles the source code into object files and creates the program.

Normally you would start like this:

Open up an editor (a text editor - don't use a word-processor!) Type in something like this to create the source for your first program:

    #include <iostream.h>

    int main(){

    cout << "Hello World" << endl;

    }

Actually, all this program will do is print out the string `"Hello World"` to your standard output. But this is just the source code for the program, not the program itself. Therefore, we need a Compiler, in this case a C++ compiler like g++. Then we can save the file with the source code as, lets say, `myprogram.cpp` and invoke the compiler with this filename (in a console):

    &percnt; g++ -o myprogram.cpp

Then we can start our program. Just type ``myprogram`` on the console, and the program prints out it's `"Hello World"` string and then exits.

### Make and the `Makefile`s.

So you're thinking - but I have everything I need: an editor, a compiler, and I can execute my own C++ program. But it isn't all that easy. What happens if you have more than one source file? And do you have to compile all your sources over and over again if you only changed one file?

Compiling will become more and more complicated and time-consuming, because you have to type in all the commands and options yourself. So you could write a so called `Makefile`. Then, you should have the tool make or gmake installed, or any other tool that is capable of keeping track of a project's compilation. Insert all your compiler commands in the right syntax into the `Makefile`, and save it. Now you will only have to run `make` or `gmake` on the console in the directory where your `Makefile` is located, and then make takes over, leading the compiler through the steps needed to create your application. The make utility has many other advantages, and can be used for a lot of purposes. To get an overview, open a console and type ``man` `make`` or search for `GNU Make` in &khelpcenter;. This will give you at the least an insight into why a developer needs the make utility to help in compiling his application.

Until now, writing the `Makefile` has been hard work, and you had to dig yourself into yet another set of complicated syntax and options. But here is the good news about &kdevelop; and the Make utility: you just have to set the `make` command in the &kdevelop; setup dialog, and then you're done. Alll projects generated with &kdevelop; will use that `make` to build the target application and no typing at all. Just hit the buttons on the toolbar of &kdevelop;, beginning with the one after the second seperator line, or choose the desired function in the Build menu.

The toolbar and the Build menu offer the most common functions you will use to let make do the dirty work for you:

- Compile File is only active if you're working on a source file. It invokes make with the correct command to compile only the currently open source.

- Make just calls make and creates your target

- Rebuild All rebuilds the whole project.

- Clean/Rebuild all cleans the whole prject first, and then runs make again.

- Stop Build cancels the current build process. This is mostly used if you are watching make working and staring at your sources. And then you think ahhhh - I forgot about this line..., and you have to correct your code. Just hit Stop Build correct the error you found, and run make again.

This is not the only way &kdevelop; works together with make for &kde; applications, there are some things that are special, like creating messages for internationalization. These functions are also included, so no worrying about these things anymore.

Now you know about sources, the compiler, and why make is needed. In the next section we'll discuss how it is that projects created with &kdevelop; can automatically be compiled on most other &UNIX; platforms using the `configure` script.

### Configure

The title of this section probably has you asking Configure? What has to be configured? Or who?

Well assume you have written a program, including a `Makefile`. Then you would like to distribute it, but the compiled binary only runs on your system, or on systems that are compatible with yours. To support other platforms, such as different &UNIX; systems, and other machines, such as Alpha or RISC hardware, you have to recompile the program. The easiest way would be to copy the source package to the target machine and run `make` again. But, what if the target machine uses another compiler, or has some other problem building your binary? Not to mention more difficult issues such as installation paths for your program and documentation. For example, &kde; might be installed in `/opt/kde/` on one machine, while it is installed in `/usr/local/kde` on another. In this case you would have to rewrite the `Makefile` each time, to ensure a correct compilation and installation of your product.

Fortunately, GNU tools have even more to provide than that mighty make - the commonly used automake and autoconf packages. It sounds good to hear something with "auto"- seems like something about application design can be done quick and easy, which exactly hits the point.

Automake's purpose is generally to create a so-called `Makefile.in` from a file `Makefile.am` which you have to write for your project. This `Makefile.am` consists of macros which can be interpreted and reduce the complexity that make offers, so a `Makefile.am` is written safer and quicker than the final `Makefile`.

Having said this, who is finally creating me my `Makefile`? Now, here comes autoconf. autoconf requires several macro files for the project. These are in the `Makefile.in`'s generated by automake and a file called `configure.in`, also containing macros. The `Makefile.am` and `in`'s contain all the macros that are responsible for how to build the software in terms of which sources have to be compiled, which files belong to the package, and what name the final binary or library will have after a build. `Configure.in` on the other hand contains macros for what the final `configure` shell script will check for on the system where `configure` is executed. Those could be &eg; the compiler command, required libraries against which the final binary will be linked, include files the project needs, and locations of all of these.

For example, you want to write a &kde; application. After writing your sources, you want to distribute the program to the user community, and each user has to compile the binary on his own. So you would write a `configure.in` file that contains the macros for a &kde; compliant application. That one macro eventually expands to a check on the system whether The &Qt; libraries are installed, checks for &Qt; header files, the &kde; libraries and headers and so on.

In summary: to create a GNU compliant application that is portable to different &UNIX; operating systems and machines other than yours, you will need to do the following:

1. Write the sources for your project

2. Write a `Makefile.am` for each subdirectory, including the main project directory of your project

3. Write a `configure.in` file, to be placed in the main project directory, and containing the macros for the system requirements.

4. Run automake.

5. Run autoconf.

Now the main work is done. Automake creates the `Makefile.in`īs, autoconf processes the `configure.in` and generates an executable shell script called `configure`. All you then have to do is to execute it with `./configure` and the script will run the checks of your choice. Finally the `Makefile`s will be generated, allowing a final execution of make (or gmake) that will process all the `Makefile`s and you are done.

This seems to be a lot of stuff for writing a small application, and much to learn, especially how to write the correct macros. But the fact that you can provide compilation on almost all &UNIX; systems will be worth this work sooner or later. Finally you only have to do this work once for your project, and as your project increases in size you have only to add the new filenames to the macros.

So how far does &kdevelop; support this kind of application development, and how complicated does it become for the programmer? The good news is, you don't actually have to learn anything about macros and scripts. All details are hidden behind an easy to use graphical interface that does all the work for you. An applicatin is therefore created with GNU tools in a very user friendly way.

Just generate your application with the KAppWizard, choosing the type of application as appropriate, be it a pure C++ terminal application, a GUI program using &Qt; or the &Qt; and &kde; libraries. All the work is done automatically, and your project will immediately contain the `Makefile`s that are created by an autoexecution of the GNU tools and the `configure` script.

This is it. Now you're ready to extend the source of your project, be it by adding classes, dialogs, translations or documentation, all of which are automated. Just concentrate on the real work of the developer, which is providing functionality for the final application you want to create. In most cases you probably won't even come in contact with the `Makefile`s at all when using &kdevelop;

### Debugging

This section covers a term that is widely used by developers: debugging. It means that although your compiler produces the final application, your application may not run or it may crash during execution, do to a so called bug in the code.

A program error being described by the name of an insect comes from the history of computing. One of the first errors that caused a machine to crash was not obviously a malfunction - real bugs were inside the computer and were responsible for the crash. So, an error that is not detectable at first glance is called a bug, and debugging means to throw out bugs that are hiding where they shouldn't be.

Of course, you don't have to hunt for them for real, assuming you have a modern computer designed to keep them out by some kind of outer cover for protection! They have to be found in the doce, mostly by their ending the execution of a program with the message Segmentation fault.

GNU provides another tool called gdb, the GNU debugger. This terminal program allows you to watch the internal values of an application, and to watch the execution step by step by setting breakpoints in the code. gdb stops the execution every time the program comes to a breakpoint while executing. Like most other tools however, the debugger is easily handled by another program, which provides a front end, allowing you to easily watch values and set the breakpoints.

For this purpose, your project's application is by default created with the compiler option for debugging turned on, thereby storing additional data in the executable to allow the localization of values and lines in the code. As a third-party front end to gdb, &kdevelop; makes use of KDbg. To debug your program, you just have to select Debug in the Build menu, or press the corresponding toolbar button (which looks like a wheel with glasses over it, indicating you want to watch the execution.)

&kdevelop; then opens the Tools window and starts your application with KDbg. The KDbg interface appears inside the Tools window, and allows the same usage and features as if you had started it separately.

In general the above sections describe the normal steps a developer must complete when starting to write his own application, and cover issues that are common to all projects. We have also explained some of the ways &kdevelop; can help the developer, and how &kdevelop; supports the idea of providing an easy introduction to &UNIX; programming. For further information about the role and purpose of the GNU tools, you should read the documentation provided with them, commonly accessed via the `man` command, or available in &khelpcenter;.

## Development with &kdevelop;

In this chapter you will get a general overview how you can use &kdevelop; and the &Qt; designer to create your own applications.

All tools are described along with their use in the development process. If you are a beginner with C++/GUI design and programming, you should read the &kdevelop; Programming Handbook, which describes some basics of program design, and shows in detail the use of &kdevelop; through the use of sample projects. You can follow these sample projects step by step, and get used to the way applications are created using &kdevelop;. You should also read chapter to gain a eneral understanding why &UNIX; applications should make use of the provided development tools. This will make things easier when you meet references to `Makefile`s &etc;.

### What are &kdevelop; Project Applications?

Projects created with &kdevelop; make it very easy for developers to use the GNU standard development tools. Instead of self-creating `Makefile`s (which you would have to do anyway, because of the project's complexity), these tools provide not only a better way of `Makefile` generation, but also a simpe and safe way to quickly adapt t different systems, through the use of autoconf generated `configure` scripts.

The distribution of your applications does not require the end-user to have anything different installed than a C++ compiler and the development libraries. These are often installed by default, but you can just as well distribute binary packages of your application. Either way, the end-user of your product does not have to have &kdevelop; installed. For giving away your sources, we recommend you include your &kdevelop; project file, as this makes it easy for other developers to work with your sources if they do have &kdevelop; installed.

For projects where several developers, maybe working in different places, are involved, this should be an easy way to ensure consistency of the `Makefile`s, so you don't run into trouble. This is especially the case on multi-lingual applications, for translators who aren't actually working on the source code, except in those cases that require corrections for enabling translation support. They will be thankful, as &kdevelop; simplifies their work as much as possible, allowing their effort to be concentrated on the translation itself.

When using &kdevelop; for your own projects, you would start creating a new application with the KAppWizard. There you can also set the project type, according to the goals of your program. Next you would start developing the user interface by adding widgets that are already constructed in the libraries, and have only to be called by your application, or by self-constructions that can be made in &Qt; Designer.

Next comes the extension of the user interface by changing and extending those parts that are already made by &kdevelop;, such as the statusbar, menu bar and toolbars.

As resources are collected in a resource file, they can be extended simply by adding new values to the already existing ones. The existing resources can also be used as a guideline for adding your own application specific ones.

After implementing the functionality to methods that are either generated empty by the &Qt; Designer or are already containing the code for standard user actions, you should extend the User Manual by simply editing the provided SGML `index.docbook` file, adding descriptions of your application's capabilities.

The last step is to generate translation files and to distribute your project to translators doing their part to enhance internationalization.

Even for non GUI application designers, the &IDE; offers an easy way to create new projects. The editor and class browser, in conjunction with &kdevelop;'s powerful project management, will reduce the time it takes for development to a minimum required for implementation of functionality.

### A Short description of &kdevelop;'s tols

With &kdevelop;, you have chosen a package that, in conjunction with other tools, will provide you a perfect and flexible environment for object-oriented application development under &UNIX; systems. Generally, &kdevelop; consists of the programming environment, and integrates the Designer that comes with &Qt; 2.2.x. Further, all necessary programs that are helpful for designing applicaitons are embedded in one way or another.

#### The Programming Environment and the &Qt; Designer

The programming environment is the user interface that &kdevelop; provides for creating and maintaining projects, implicitly using many other tools, and simplifying their use. &kdevelop;'s build in editor and Help browser, as well as the Class Browser, reduce the amount of work that development processes usually burden the programmer with. This ease of use makes writing applications for &UNIX; an enjoyment on it's own, and will probably result in shorter release cycles and many development improvements.

From here, you're managing your project through all it's details, keeping an overview of your classes, and you don't have to use multiple additional consoles for your work. The integration of all user interfaces results in your only having to work in one window under &X; and you don't have to keep an eye on several windows spread all over your desktop.

#### &Qt;'s Designer

In it's current release, &kdevelop; makes use of the &Qt; Designer for all &kde; 2.0.x/&Qt; 2.x project templates. Keep in mind that Designer has to be included in your `PATH` variable to be automaticaly called from within &kdevelop;. The `configure` scripts of &kde; 2.0.x/&Qt; 2.x templates will search for the uic as well, to generate C++ output from your `.ui` files created with Designer. &kdevelop; takes care of automatically adding `.ui` files to `Makefile.am` under the `_SOURCES` line, while dependencies are automatically resolved by the `am_edit` script.

However, &kdevelop; comes with a converter script (`kdlgdesigner`), that helps you port existing `*.kdevdlg` files, created with &kdevelop;'s internal dialog editor, into `.ui` files that can be processed with &Qt; Designer. You can find this script in the `tools` subdirectory of your &kdevelop; installation.

Note that you can add native support for &kde; in &Qt; Designer by reconfiguring &Qt; with the `-kde` switch, once &kde; has been installed. If you then recompile &Qt;'s `tools` directory, you will get a Designer that has native support for most of the &kde; widgets, and integrates seamlessly into &kde; in terms of look and feel.

### KAppWizard and the Class tools

The KAppWizard and the Class tools proved for project generation and automatic code extension are intended to make the creation of applications as easy and safe as possible. They offer a good way for beginners in &Qt;/&kde; programming to start actually working themselves into the details of GUI application design, as results can be achieved very quickly.

#### KAppWizard

KAppWizard is intended to create fully functional application projects that are ready-to-run, by using GNU standard tools, and, for GUI programs, by taking advantage of the &kde; and &Qt; libraries. By specifying only the information that is required as a minimum, users are able to start working at a new project within seconds. Calling KAppWizard should be the first step for creating a new application with &kdevelop;.

KAppWizard provides you a so called application skeleton, with all the necessary C++ source code files for a running application. After you specify a project name, and set your preferences, your new project will be generated and you will instantly have a complete application. This new application already contains a lot of functionality (for &kde; and &Qt; projects), without you even having to type one line of C++ code.

When specifying the complete set of options the program generator offers, you application already contains:

- An SDI interface, for working with one document per application window, based on the document-view-controller model.

- Menus and dialogs for opening and saving files, as well as printing dialogs.

- A toolbar and statusbar, already providing complete functionality.

- A Help system, containing an SGML based user manual, and statusbar help.

- A complete HTML based API (Application Programming Interface) documentation set, for the current state of the project.

- An installation routing using make

The KAppWizard is available in the Project with the entry New...

#### Classtools

The term Classtools describes a variety of functions that are available for the developer to work on a project, not only through an object-oriented language, but using the sources in an object-oriented way.

Working with classes instead of having to watch for files offers a very flexible way to extend a project, and lets the developer concentrate on the objects the project contains.

The tools that &kdevelop; offers are a Class Generator and a Class Browser, where each one provides a lot of automated functionality.

##### Creating a new class with the Class Generator

After generating a project with the KAppWizard, your work as a developer is to add a set of classes that match the design of the application.

The typical process when not using &kdevelop; would be to create a new header and source file, add them manually to the appropriate `Makefile.am` and to start writing the classes declaraton and implementation.

To simplify this process, the Class Generator lets you do this by specifying only the name of your new class, the classes it inherits, inheritance attribute, and any other information such as class documentation. Additionally you can change the filenames that are preset by the generator, and if the class is &Qt; signal/slot enabled by default.

The rest of the work is done automatically for you, you don't have to worry about the `Makefile.am` and the class itself. A new `make` invocation is enough to include the new class in the compilation process. As the Class Browser updates itself after the addition of a class, the declaration and implementation are available at once, and you can start working on the extension of the class. The Class Generator is invoked from Project New Class

##### The Class Browser

The Class Browser displays all types of objects and functions in your project in a tree left of the editing window. A Class parser scans all files for methods and classes and makes them available as graphical symbols.

Over these symbols, context menus offer specialized functionality for working with the sources by focusing on the classes and functions.

Selecting a class will result in opening the file that contains the declaration. Selecting methods and functions will show you the implementation. For a full description see the section titled Using the Class Browser

## The Development Process

The development of a new application with &kdevelop; can generally be divided into two major steps:

1. Generate a program skeleton with KAppWizard

2. The rest of the development using &kdevelop;'s features, and your own ability as a programmer.

To describe the development process, we assume you want to create a &Qt;/&kde; application, which implies using most of &kdevelop;'s features. Even if this is not your primary aim in development, it will serve as a general HOW-TO in the use of &kdevelop;

### Creating a program skeleton

To start creating your application, you will usually call the KAppWizard, enter your project name, and generate a program.

The wizard automatically creates a project file for the application, and inserts the &kdevelop; areas into the `Makefile.am`'s which will be used later when extending the application. A project file is created, and this project file is the file you will have to load in later sessions to reopen your project.

You call KAppWizard from the Project New... menu choice. When the wizard appears, you first must specify the project type on the first page. Selecting Next < brings you to the next page, where you should insert the Project Name, Project Directory, your project's Version number, and your own details, your name as the Author and your Email address. Here you also have several choices as to what sources you wish to be automatically generated for you:

- GNU-Standard Files (INSTALL, README, COPYING...)

- User Documentation

- API Documentation

- lsm File (Linux Software Map)

- .desktop file

- Program Icon

- Mini Icon

Choosing Next < brings you to a third page where you can set up Version Control System Support. We will assume for this project that you are not using VCS, and this is described in it's own section .

The next two pages allow you to edit the header template files (for `.h`) and the source template files (for `.cpp`). These templates are automatically inserted according to your choice. If you already have file headers you want to use, then you can choose those files here as well.

The last page contains an output and an error window. If you press the Create button here your application will now be generated, and the actions that are being executed can be seen in the (upper) output window. If `READY` appears in the output window, the KAppWizard is finished, and you can select Exit to return to the programming environment.

Your newly generated application is ready to compile and run, although it doesn't do very much yet. Choose Make from the Build. You can test the functions already present by then choosing Build Execute

### Developing an Application

This section describes the development phase of applications within &kdevelop; and the &Qt; Designer - and how all the work can be done within the &IDE;.

The development steps are generally to edit the source files, the compilation of the project sources, followed by the linker process binding all object files to the final binary. Then errors have to be located, which either prevented compilation or linking, or are semantic bugs which can be found by a debugging session. Finally documentation has to be extended, and translations added.

Of course, all these steps don't happen necessarily in this order, but it's not too easy to describe a general way that all applications are developed. As for the actual editing of the source files, typically you first create the visible parts of the project, such as the main view and the dialogs for configuring options. Then generate the source code and implement all the necessary connections, changing the menubar and toolbar, adding status bar help for new menu entries, and filling in the new member functions with objects that are displaying your dialogs. Then you compile your application, test it's capabilities, fix errors, and test it again.

The following sections describe one way this could be done, for your particular application, you may choose another way. &kdevelop; gives you enough flexibility to decide what to do and when to do it.

#### User Interfaces

The User Interface of an application is what the user actually sees and how he interacts with the program. A program generally has a menubar, toolbar(s) and a statusbar, as well as a main view which is different depending on the type of application. For an editor, the main view would probably be a text input window.

KAppWizard generated applications already contain complex functionality in the graphical interface. The frame structure takes care of standard elements such as bars and buttons.

When developing your application, you have to extend the given structure to give the program the user interaction capability you want to provide. One part of the work is the design of dialogs, &eg; for changing values such as the brush width in a paint application. This can now be done easily in &Qt; Designer.

So, how do you create those great looking dialogs? As the &Qt; library is a GUI toolkit, it provides a base set of widgets. These include things like labels displaying plain text, lineedits for text input, and buttons for navigation and selection commands. Besides these low-level parts of user interfaces, standard dialogs are provided for things such as printing, opening and saving files. The &kde; libraries are in turn based on the &Qt; library, and contain replacements for certain dialogs, as well as additional widgets that can be used in your application.

When you start designing your applications behavior, you should make yourself comfortable with the widgets provided with &Qt; and &kde;. The online documentation for &Qt; offers screenshots for most of them, so you should look there first. Then we advise you take a closer look at the &kde; UI library, offering other widgets. Libraries such as khtml contain very specialized widgets that a lot of programs make use of.

It simplifies application design to use predefined dialogs and widgets such as those provided with &Qt; and &kde;. For your own dialogs, these low-level widgets are the ones you need. A dialog after all merely consists of a collection of different widgets combined together, and building the interface.

Dialogs are technically programmed in C++ code, in a class that is derived from `QWidget`. The program using the widget therefore needs an object of the widget's class - this is almost all you have to understand about how dialogs or views are used to begin using them yourself.

The &Qt; Designer that comes with &Qt; can be used to easily create dialogs and user interfaces. You can use the Switch to Qt Designer icon on &kdevelop;'s menubar. This will bring up Designer, where you can create a new dialog. You can also choose an existing `.ui` file from the Files viewer and &kdevelop; will open Designer with the selected dialog.

You can add dialogs easily by adding a new `.ui` file from the File menu.

The Designer creates `.ui` files which contain an xml description of the class. Once you have added the file to your project, &kdevelop; will take care of adding it to your `Makefile`. The build system will automatially create the header and implementation files for you. Now all you have to do is either create a new class that inherits the dialog class and implement functionality, or use the dialog directly. Using Designer to create dialogs has a clear advantage: Code and layout are strictly seperated, allowing you to change the design of your dialog without rewriting one line of code. This way you can concentrate on what's really important, the actual coding process.

For further information on the Designer's concepts, read the &Qt; Designer handbook which can be found in &kdevelop; in the Books documentation viewer.

#### Binding New Elements

After you have created your user interfaces, and generated the sources, you are ready to make your application use them as objects.

As described above, a normal GUI based program contains bars and the main view. Additionally, the main view interoperates with the bars, which are part of the main application class, and the document object to which it is connected.

In terms of object-oriented design, you would describe the given architecture as the Document-View-Controller model. This model describes the basic functions for objects in an application, in relation to their role within the program. The controller represents the one coordinating the main application and providing user interaction through a menubar (and additionally toolbars and a statusbar). The document class takes the task of representing the document the user works with, therefore a document class should do all actions such as loading files and saving them again. The view now is the center of the application window, showing the user part of the document visually, and providing all functions for the user to manipulate the data.

As the bars and toolbars are already present, your task is to create the main view and additional dialogs through which users can change settings, or access additional functions.

To build your main view, the generated source code for your application already contains a class in the form of `YourApplicationView` which inherits the `QWidget` class. `QWidget` is the minimal class that handles user interfaces in &Qt;, and therefore in &kde; as well.

In general, there are three ways to extend the given class:

- Remove the document view structure, and use one of the predefined big widgets that already contain a lot of functionality. Just remove the view class, and replace the view object with another.

- Change the inheritance of the view class. Change the inheritance to, for example, `QMultiLineEdit`, and your application becomes an editor.

- If your main view will consist of several separate parts, create the widgets and their classes with the &Qt; Designer, and create objects of these classes in the view class constructors that in combination will build the main view.

For dialogs, things are a bit different. Normally you would call a dialog through a menu entry, and additionally through a toolbar icon. After you have constructed your dialog and generated the sources, the class is available for creating the object that will be the dialog.

First you have to look for a suitable place in the menubar to add an entry which will open this dialog when seleced by the user. If the already present menus do not match your needs, you can create a new popup menu just like the others, and insert your entry, and also the slot you want to call when the menuitem is selected.

You must also specify an ID for the menu entry. The frame applications have all ID's already given, collected in a file `resource.h`, so you have only to add the ID and give it a new number.

Then implement the slot by creating an instance of the dialog classand call the dialog with the member functions given by the base class.

Now you're done. You could additionally create a new toolbar icon, and add status help messages.

Your application now offers a new function which is visible to the user. NExt you have to add the implementation of methods that your dialog will be operating with, to manipulate any values. Finally call your make tool or Execute and the changed files will be recompiled, so the results of your changes can be tested immediately.

## The Complete Development Process

Above we discussed the normal way to start working on a new application using &kdevelop;, and how to extend the user interface.

These are the standard steps where the &IDE; helps you, but &kdevelop; does more than providing tools for creating applications and their visual parts. The following sections give a sohrt description of the additional functionality that is offered to enhance application development.

### Source Code Management

The &kdevelop; &IDE; provides a lot of methods to help a programmer achieve his goals in the minimum of time. As described previously, the KAppWizard and the &Qt; Designer shorten the time normally taken to get the same result manually. This doesn't cover much of the work a programmer normally has to do: working on the implementation of his application to provide a proper execution by the end user. So why is &kdevelop; the &IDE; you would want to use as a coding environment, especially when developing non GUI applications?

The &IDE; implicitly keeps track of your project in general, so you don't have to worry about much other than saving changes and regenerating `Makefile`s. This is project management, and &kdevelop; handles this very powerfully, in any case of C++ application development. It is easy to see that having removed the burden of management from the developer, he can concentrate more on working on the source code.

On the other hand, the code is usually spread over any different files across the project, so you can separate certain parts from each other. This sill means working the hard way. Being the developer, you still have to struggle with creating these files and writing standard contents, for example file headers containing the authors name and license terms. Further, you have to remember where your functions are, where youre classes are, and where in your project your structures and methods are.

&kdevelop; can help. The Class Generator lets you create a new class, including inheritance, attributes, and documentation, very easily. For object oriented work, the Class browser brings you to the location of your objects, and it really doesn't matter any more where, or in which file, the code actually is. The browser scans all your sources automatically, and rebuilds itself after additions, to keep up with your work, enabling you to access the new code immediately and directly.

Through context menus, the browser offers even more functionality. It can take you directly to the implementation or to the declaration of member functions. The addition of members is handled graphically, with dialogs. No more search for the file and the right place to add entries. Yet all this is done without hiding from you where the code is, so you can always see how things are fitting together.

Finally, you can get an even more specialized view of your projects classes with the Classtool dialog, providing you trees that show usage, contents and inheritance of the classes and their objects. For more detailed information, see .

### Building and Executing your Application

The &kdevelop; &IDE; is especially designed to take away all the steps normally involved in periodically building and executing your program, as well as locating errors in the source.

You start the build process by either clicking on the symbols Build or Rebuild All in the toolbar, or by selecting Build Make or Build Rebuild All

To execute your application, you can choose the symbol Execute or Debug (which starts KDbg with your program) from the toolbar, or you can use the corresponding menu entries in the Build menu. You can also choose Execute with Arguments to start your application with additional arguments. For more information about the build process, see .

### Searching for Program Errors

Errors naturally occur during the build process (where they are detected by the compiler, and are called syntactical errors, because they result from incorrect syntax in the sources) or during the execution of the application. This second type must be found and removed by the programmer.

To help locate errors, the developer needs information about exactly what caused it's occurrence. As mentioned, the compiler is able to detect syntax errors by itself, resulting in an executable that can't be built. They can also be detected by the linker, which will report Unresolved symbols. See for more information about the linker.

As these tools give out a detailed description of the error, these errors are easily found (and usually, easily removed.) During the build proess, you will see the output window pop up, showing you what your make tool and the compiler have to say. In the case of errors or warnings, just press the mouse button over the error line, and the editor will open the affected file and set the cursor to the line reported as having the error.

Where there are more than one error, youcan navigate with the entries in the View menu: Next Error or Previous Error, or the corresponding keyboard shortcuts. You will find this is very functional, and makes finding and correcting errors very quick and simple, although, for the actual removing, your skill as a programmer is required.

Runtime errors, which occur during execution, and mostly result in a segmentation fault, are sometimes much harder to find. You can enable the compiler to add information to the binary to watch it's execution in the source code. A debugger is another program that lets you do this, by starting the application and letting you set breakpoints in the code where execution stops. In this way, you can control critical implementations, and detect at least the line that causes the error. Finding the real cause is another task, and depends on the programmer.

The gdb is a debugger that is provided with the GNU compiler, and programs like ddd and KDbg are front ends that make gdb easier to use. &kdevelop; therefore uses KDbg and lets you invoke the debugging process with the commands Debug in the Build menu, or with the Debug symbol in the toolbar.

For more information about debugging applications, see Projects and The &kdevelop; Programming Handbook

### Additional Information

The topics addressed within this chapter are described in more detail within the documentation provided with the &kdevelop; &IDE; and in other documentation:

- The &kdevelop; Programming Handbook, covering a complete introduction into GUI application design and programming with the &Qt; and &kde; libraries.

- This handbook, sections Overview to Projects, describing all available functions within &kdevelop;

- This handbook, section Using &Qt; Designer in your projects

- The Online Reference documentation to the &Qt; library, which covers examples of using the &Qt; GUI toolkit, as well as a class reference and screenshots for most of the important ready-to-use widgets included.

- The &kde; Library class reference, generated automatically by &kdevelop; from the &kde; library sources, containing descriptions of all classes and widgets including example code for their use.

On the Internet you will find:

- http://www.trolltech.no, for information about &Qt; and additional third party widgets.

- http://www.kde.org for information about the &kde; project, and developer guidelines.

- http://developer.kde.org for additional references to &kde; application development.

- The &kdevelop home page, at http://www.kdevelop.org

## Overview

Looking at &kdevelop; the interface can be best described by it's logical divisions: the main window, the tree view, the output window, and the general interface (consisting of the menus, toolbars and statusbar.)

This chapter describes the purpose of each part of the interface, starting with teh windows, followed by the menus and toolbars and the functions they provide.

### The Main Window

The main window consists of three tabs, of which the left two are for editing.

- First comes the Header/Resource Files window, which shows headers and other text files, including the documentation SGML files.

- Next is the C/C++ Files window, which is used for editing your source code.

- These are followed by the Documentation-Browser, displaying installed documentation in HTML format.

For a description of the two editor windows functionality, see the chapter on Working With the Editor and for more information on the Documentation-Browser, you should look in the section Using the Documentation Browser.

### The Class browser and File viewers

#### The Classes Viewer

The Classes Viewer shows the classes of your project as well as global functions and variables. Opening the tree will show all member functinos and members, with symbols for attributes ( private, protected and public, signals and slots), so you can see the properties of members visually without switching to the header file.

Selecting the class name will open the corresponding header file containing the class in the editor, and set the cursor to the beginning of the class declaration. Selecting member functions will open the implementation file, and place the cursor at the function header. For elements &kdevelop; will look for the header file, and put the cursor at the line the element is declared. The Classes viewer also provides popup menus that offer more specific options. See for more detailed information.

The Classes viewer does not display generated files such as those generated by moc and uic, as they are removed from the distribution, and are not present on a clean development tree.

### The Logical File Viewer

The Logical File Viewer (labelled Groups) allows the sorting of files by filters into groups. Individual gropus can be added with the Properties entry in the Project menu. This allows a more specialized search for files that you want to access quickly, in the first place by only showing files included in the project.

Selected files will be opened according to their mime type. You will like the Groups tab for things like selecting pixmaps. This will start &kiconedit; (if it's installed on the system) in the Tools window, and opens the chosen picture.

### The Real File Viewer

The Real File Viewer (Files) shows the project directory with all files, so you can edit non-project files or files hidden by the Groups tab, such as `configure.in` or `Makefile`s. Popup menus also provide functions such as adding or removing files in the current project.

### The Documentation Tree

The Docuemntation Tree, (labelled Books) displays all available HTML based documentation that &kdevelop; knows about. Selecting a book will open the first page in the Documentation Browser window. A popup menu provides personal configuration for additional HTML based documentation packages.

### The Output Window

The Output Window contains several tabs as follows:

messages

  Displays all the output of the compiler. Clicking on an error message will change the editor to set the cursor on the line the compiler found an error.

stdout

  Display for terminal based applications that send messages to the standard output of the computer. Note that terminal applications are now started in an external console window.

stderr

  Displays all error messages that your program produces. This is useful for testing purposes.

breakpoint

frame stack

disassemble

## The Menu reference

### The File menu

&Ctrl;N File New...

  Opens the New File dialg, allowing you to create a new file. This dialog is described more completely in section .

&Ctrl;O F Open...

  Displays the Open dialog and lets you choose a file to be opened.

&Ctrl;W File Close

  Closes the file in the frontmost editing window

File Close All

  Closes all open files.

&Ctrl; S File Save

  Saves the file open in the frontmost editing window. If the file has not been saved yet, the Save File As... dialog will be opened to let you choose a path and filename for the file to be saved.

  This item is disabled if you are browsing documentation.

File Save As...

  Opens the Save File As... dialog, allowing you to save the current file with a new name.

File Save All

  Saves all open files that contain unsaved changes.

&Ctrl; P File Print...

  Opens the Print File dialog where you can set various options for printing via either enscript or lpr.

&Ctrl; Q File Exit

  Exits &kdevelop;. If any open files contain unsaved changes, you will be given the opportunity to save them.

### The Edit menu

&Ctrl; Z Edit Undo

  Allows you to undo the last action you performed.

&Ctrl; Y Edit Redo

  Repeat a previously undone action.

&Ctrl; X E Cut

  Cut to the clipboard the currently selected text, removing it from the source file.

&Ctrl; C Edit Copy

  Copy to the clipboard the currently selected text, without removing it from the source file.

&Ctrl; V Edit Paste

  Paste the contents of the clipboard at the cursor.

&Ctrl; I Edit Indent

  Moves the selection to the right.

&Ctrl; U Edit Unindent

  Moves the selection to the left.

&Ctrl; M Edit Comment

  Adds // to the beginning of each of the selected lines.

&Ctrl; &Alt; M Edit Uncomment

  Removes // from the beginning of each of the selected lines.

Edit Insert File...

  Inserts a file at the current cursor position.

&Ctrl; F Edit Search

  Searches the file for an expression.

F3 Edit Repeat Search

  Repeats the last search.

&Ctrl; R Edit Replace

  Searches for and replaces an expression.

F2 Edit Search in Files

  Opens the search in files dialog to search for an expression over several files.

&Ctrl; A Edit Select All

  Selects the whole documents contents.

Edit Deselect All

  Deselects the whole documents contents.

Edit Invert Selection

  Inverts the current selection.

### The View menu

&Ctrl; G View Goto Line

  Goes to the line number

F4 View Next Error

  Switches to the file and line the next error was reported in.

Shift F4 View Previous Error

  Switches to the file and line the previous error was reported in.

View Dialog Editor

  Starts Qt's Designer (Dialog Editor)

&Ctrl;T View Tree View

  Enables/Disables the Tree View

&Ctrl; B View Output View

  Enables/Disables the output view.

View Toolbar

  Enables/Disables the toolbar.

View Browser Toolbar

  Enables/Disables the browser toolbar.

View Statusbar

  Enables/Disables the status bar.

View Tab Text

  Changes the appearance of the tabs on the tree view.

  - Text only

  - Icons only

  - Text and Icons

View Refresh

  Refreshes current view.

### The Project menu

Project New

  Generates a new project with the Application Wizard.

Project Generate Project File...

  Creates a project file for an existing `Automake` project.

Project Open

  Opens an existing project.

Project Open Recent Project

  Opens a recently opened project.

Project Close

  Closes the current project.

Project New Class...

  Creates a new class frame structure and files.

Project Add Existing File(s)...

  Adds an existing file or files to the project.

Project Add new Translation File

  Adds a new language for internationalization to the project.

Shift F7 Project File Properties

  Shows the current file properties.

Project Make Messages and Merge

  Invokes `make` to create the messages file by extracting all the `i18n()` macros.

Project API Doc Tool...

  Switches the documentation tool.

  - KDoc

  - Doxygen

  - Configure Doxygen

Project Make API Doc

  Creates API documentation for the project.

Project Make User Manual

  Creates an SGML User manual for the project.

Project Make Distribution

  Creates a distribution package from the current project.

  Source tar.gz

    Creates a source `tar.gz` file from the current sources.

  Build RPM Package

    Releases your project as RPM package

  Configure RPM Package

F7 Project Options

  Configure uptions for creating RPM packages

### The Build menu

Shift F8 Project Compile File

  Compiles the current source file.

F8 Project Make

  Invokes `make` command.

Project Clean

  Invokes `make` `clean`, which deletes all object and metaobject files.

Project Rebuild

  Rebuilds the program.

Project DistClea/Rebuild All

  Invokes `make` `clean` and rebuild all.

F10 Project Stop Build

  Stops `make` immediately.

F9 Project Execute

  Invokes the `make` and runs the program.

&Alt; F9 Project Execute with Arguments...

  Lets you set runtime arguments for the program, then invokes `make` and finally runs the program.

Project DistClean

  Invokes `make` `distclean` which deletes all compiled files.

Project Autoconf and Automake

  Invokes `automake` and `autoconf`.

Project Configure...

  Invokes `./configure`.

### The Debug menu

Project Start

  Invokes the debugger on the current executable.

Project Start (other)...

  Various other startup options for the debugger.

  Examine core file

    Examine a core file.

  Debug another executable

    Debug an application other than the current executable.

  Attach to process

    Attach to a running process.

  Debug with arguments

    Lets you debug your project application after starting the application with command line arguments.

Project Run

  Continues application execution.

Project Run to cursor

  Continues application execution until the current cursor position is reached.

Project Step over

  Step over.

Project Step over instr

  Step over instruction.

Project Step into

  Step into.

Project Step into instr

  Step into instruction.

Project Step out

  Run to end of function.

Project Viewers

  Various views into the app.

Project Interrupt

  Interrupt the app.

Project Stop

  Kills the app and exits the debugger.

### The Tools menu

Tools

### The Options menu

Settings Editor..

  Sets up the editor's behavior.

Settings Editor Colors...

  Sets the editor's colors.

Settings Editor Defaults...

  Sets the highlighting default colors.

Settings Syntax Highlighting

  Sets the highlighting colors.

Settings Documentation Browser...

  Configures the browser options.

Settings Configure Printer...

  Configures printing options.

Settings Tools...

  Configures the Tools menu entries.

Settings KDevelop Setup...

  Configures KDevelop.

### The Window menu

Window

### The Bookmarks menu

&Ctrl; &Alt; T Bookmarks Toggle Bookmark

  Toggle a bookmark in the current open file.

F5 Bookmarks Next bookmark

  Goes to the next bookmark in the current file.

Shift F5 Bookmarks Previous Bookmark

  Goes to the previous bookmark in the current file.

&Ctrl; &Alt; C Bookmarks Clear Bookmarks

  Clears the bookmarks for the current file.

Bookmarks Header Window

Bookmarks C/C++ Window

Bookmarks Browser Window

### The Help menu

Help Back

Help Forward

Shift F2 Help Search Marked Text

Help Search for Help on...

Shift F1 Help What's This

F1 Help The User Manual to KDevelop

Help The KDevelop Programming Handbook

Help KDE Application Tutorials

Help The KDE Library Reference Guide

Help C/C++ Reference

Help Project API-Doc

Help Project User-Manual

Help Tip of the Day

Help KDevelop Homepage

Help Report Bug...

Help About KDevelop

Help About KDE

### The &kdevelop; toolbar

### Keyboard Shortcuts

This section covers the predefined and standard values for the keyboard commands available in the &kdevelop; &IDE;. These can be customised with the menu entry Configure Keybindings.

#### Shortcuts for Text Processing

##### Keybindings: Cursor Movements

One letter to the left | Left Arrow
One letter to the right | Right Arrow
One word to the left | &Ctrl;Left Arrow
One word to the right | &Ctrl;Right Arrow
One line upwards | Up Arrow
One line downwards | Down Arrow
To the beginning of the line | Home
To the end of the line | End
One page up | Page Up
One page down | Page Down
To the beginning of the current file | &Ctrl;Page Up
To the end of the current file | &Ctrl;Page Down

##### Keybindings: Text Selections

One letter to the left | Shift Left Arrow
One letter to the right | Shift Right Arrow
One word to the left | &Ctrl; Shift Left Arrow
One word to the right | &Ctrl; Shift Right Arrow
One line upwards | &Ctrl; Up Arrow
One line downwards | &Ctrl; Down Arrow
To the beginning of the current line | &Ctrl; Home
To the end of the current line | &Ctrl; End
One page up | Shift Page Up
One page down | Shift Page Down
To the beginning of the current file | &Ctrl; Shift Page Up
To the end of the current file | &Ctrl; Shift Page Down

##### Keybindings: Inserting and Copying Text, Tabulators

Enable/Disable insert mode | Insert
Copy selection to the clipboard | &Ctrl; C, &Ctrl; Insert
Insert text from the clipboard | &Ctrl; V, Shift Insert
Delete current line | &Ctrl; K
Insert line after current line | End Enter
Insert Line before current line | Home Enter
Undo editing step | &Ctrl; Z
Redo editing step | &Ctrl; Y
Tabulator | Tab

##### Keybindings: Deleting Text

Delete letter left of cursor position | Backspace
Delete letter right of cursor position | Delete
Delete selected text | Select text then Backspace or Delete

##### Keybindings: Searching within the editor

open Goto Line... dialog | &Ctrl; G
Open Find Text dialog | &Ctrl; F | Repeat last search | F3
Open Search and Replace dialog | &Ctrl; R
Open Search in Files dialog (grep) | &Ctrl; &Alt; F
Locate next error | F4
Locate previous error | Shift F4

##### Keybindings: Searching within the Documentation Browser

Search for the selected editor text in the documentation | F2
Search for the selected browser text in the documentation | F2
Display next search hit on the same page | F3
Search for the selected browser text within the project | Shift F2

##### Keybindings: Browser Shortcuts

Previous page | &Alt; Left Arrow
Next page | &Alt; Right Arrow

##### Keybindings: Managing Bookmarks

Add bookmark | &Ctrl; &Alt; A
Clear bookmark list | &Ctrl; &Alt; C

#### Shortcuts for Toolbar Symbols

##### Keybindings: toolbar symbols

Open File | &Ctrl;O
Save File | &Ctrl; S
Print File | &Ctrl; P
Undo | &Ctrl; Z
Redo | &Ctrl; Y
Cut | &Ctrl; X
Copy | &Ctrl; C
Paste | &Ctrl; V
Compile File | &Ctrl; F8
Make | F8
Execute | F9
Execute with arguments | &Alt; F9
Back | &Alt; Left Arrow (if the browser is open)
Forward | &Alt; Right Arrow (if the browser is open)
Search for selected text | F2

#### Window Management

To switch to a certain window, press &Alt; The unerlined letter in the window title. For example, to switch to the Tools window would be &Alt; T

#### Shortcuts to compilation processes

##### Keybindings: Compilation processes

Compile current source file | &Ctrl; F8
Build current project target | F8
Execute the target after the build process | &Ctrl; F9
Execute the target with arguments | &Alt; F9
Stop the current process | F10

### Status bar help

The status bar of &kdevelop; offers much information about the current activity, as well as status messages, and short descriptions of commands.

The statusbar contains the following items:

- A general message field, on the far left. This is used for help messages, and displaying the current activity.

- The progressbar indicates the progress for actions that require a comparatively long time to complete. Examples are saving large files, and the scan-progress of the Classes Browser. The progressbar only appears while these processes are in executed.

- An insert/overwrite indicator is next. Here you can see which mode the editor is currently in, with INS indicating insert mode, and OVR indicating overwrite mode. You can toggle between the two with the Insert key on your keyboard.

- There is a line counter, displaying the current position of the cursor.

- Finally, there is a column counter, also displaying the current position of the cursor.

The statusbar also informs you about the actions of menu entries. If you open a menu and place the mouse over a menu entry, without clicking, the function that menu item represents is displayed in the statusbar. Pressing the &LMB; mouse button on a toolbar icon, without releasing it, will display similar information for that icon. You can prevent execution of the selected menu or toolbar item by moving the mouse away from it, without releasing the button.

For actions that are currently in execution, &kdevelop; displays the description of the action. This applies to processes running in the background, such as saving of files, as well as to dialogs. If a process such as a make invocation exits, the statusbar display will change back to the Read state.

When using the documentation browser, the statusbar displays link URLs while the cursor is positioned over a link. This gives you an easy way to find out if a link is to a local file (installed on your computer) or a remote file that will require a network connection.

The caption of the &kdevelop; &IDE; shows you the currently active open filename. This would be an HTML file if you are in the documentation browser, or a source file name if you are in the editing windows. The project name is also displayed, so you can always see what you are working on, useful if you have several projects to work on.

## The Help System

Much of &kdevelop;'s strength is contained in the help system. It is also an example of how to extend your own &kde; applicatoin with a complete set of help functionality, and is, in part, already realized in the template applications.

A &kde;/&Qt; application framework as generated by the KAppWizard already contains the basic functionality for statusbar help and documentation, and this needs only be extended by the programmer.

This section aims to introduce the usage of the general help within the &IDE;, as well as showing you the usage of the Help browser.

### The What's This? icon and Quickhelp

Looking at &kdevelop;'s top toolbar, you will see a What's this? button on the right. Selecting the button will turn your cursor into a pointer with a question mark, just as you see on the icon. You can now select any visible part of the &kdevelop; user interface and click on it. This will result in a small popup help window, giving you a short description of the function this item provides.

Some of the user interface items that have help function available are the main view, the tree views, and the toolbar buttons.

When you click, or press a key, the popup disappears, and the cursor returns to normal.

If you just rest the normal cursor over a toolbar button, you will find that another form of help is available. The icon will be raised, and after a short time, you will see a tool-tip window, describing the function the button represents. This disappears as soon as you move the mouse away from the button.

For user interaction dialogs, Quick Help provides you help windows with a short description of the selected item. These are accessed with a &RMB; click to the item. A context menu pops up, which includes the item Quick Help, and selecting this will pop up a help window.

All these functions are very helpful for learning your way around the &kdevelop; interface. Note also that most dialogs offer a Help button, which will show you detailed context-help for that dialog's options, as provided by the online manual.

### Configuring the HTML help browser

The browser included in &kdevelop; is completely HTML based, so you have the normal browser options available to you, such as setting color preferences and font sizes. You can set all these preferences in the Documentation Browser entry of the Options menu.

#### Font preferences

The first option for the font display is the size. You may choose between small, medium and Large The default is small.

You may also specify here a monospaced font (one in which all characters take up the same amount of space across the screen, whether they are an i or a w, &eg; courier), for displaying code samples in the documentation, and a proportional font for the rest of the text, (one in which an i takes up less space on the screen than a w &eg; helvetica).

#### Color preferences

The color preferences dialog allows you to configure the colors for ordinary text, the page background, links, and links you have already followed.

The colored buttons on the right display the current settings. Selecting a button will open a Select Color dialog, where you can choose the color. The center contains a preview of the color selected.

You can also specify if the browser should underline links, to make them easier to distinguish from surrounding text, or leave them bare, to make them less distracting.

Finally, you can choose if you wish to always use the colors you have set here, or if the page can set it's own colors.

Apply will execute your changes, but leave the dialog open so you can make further customizations. OK will execute the changes and close the dialog. Cancel closes the dialog without executing any changes you have made.

### Using the Documentation Browser

The documentation browser allows quick and easy access to all the manuals and documentation provided with &kdevelop;. Also available is the documentation generated for the &kde; libraries, and that you have created for your own project.

The Documentation tree in the tree view pane lets you customize a special Others folder that contains any documentation you have added separately.

### Requirements

To make use of all features of the documentation browser, you should have KDoc and Glimpse installed.

KDoc is used to generate all kinds of online class documentation for the &kde; libraries. This is normally done during the setup process, but KDoc can also be invoked with the KDevelop Setup. KDoc is also used for generation of API (Application Programming Interface) Documentation for your project's classes.

For generating API documentation, KDoc is called with the menu entry Project Make API Doc. This will process all current header files of the project, and additionally cross-reference to the &Qt; and &kde; libraries, if they are available in the documentation browser.

For the generation of project handbooks you have written, you should have

To extend and change your project's online documentation, you should edit the documentation source file by selecting it from the Files viewer. After saving your changes, call Make User Manual from the Project menu. If there are syntax errors detected, these will be displayed in the output window allowing you to find the error line directly.

The program Glimpse is used to create a personal search index for the documentation you have installed. The index is generally created during the installation process, but can also be built with the &kdevelop; Setup dialog. For a description of the search functions provided, see .

### Provided Documentation

The &kdevelop; &IDE; comes with two sets of online documentation. These can be accessed either via the Help menu, or through the documentation tree in the tree view, where they are in the &kdevelop; folder.

The first book provided is this online handbook, containing all the information you need regarding installation, configuration and functionality.

The second book is the &kdevelop; programming handbook. The programming handbook covers most questions related to the creation and extension of projects within &kdevelop;. Through tutorials, the user gets an introduction to the rich facilities that applications created with the &Qt; or the &kde; libraries have to offer. There are guidelines towards &kde; compliance issues, as covered also on the web site http://developer.kde.org/.

The &Qt; and &kde; libraries documentation folder allows direct access to the HTML documentation from your local copy of the &Qt; library. The path to the library documentation is usually automatically detected by the &kdevelop; installation process, but can also be set later from within the program.

Any available documentation for the &kde; libraries is listed in order of the library name. The &kde; library documentation is usually generated during the &kdevelop; installation, and requires that KDoc is installed before you install &kdevelop;. If this is not the case, you can generate (or update) the library documentation at any time, from within &kdevelop;.

The documentation tree also contains an Other folder, which is intended to contain any personal documentation you have installed, as described in the section Adding Documentation to the Help Browser.

Finally, the documentation tree gives you access to the API and user manuals for your current project.

### Adding Documentation to the Help Browser

To customize your documentation browser, open the tree view and select the tab. You will see an opened tree containing four folders. The Others folder is initially empty.

&RMB; click over this folder, and in the resulting context menu, choose Add Entry. The Add Entry dialog will open.

You must enter two values here in this dialog. The first is the name that you want this new entry to be displayed with in the documentation tree. The second is a normal filename entry line, where you can enter the path and filename of the initial starting page of the documentation you are adding. You can also use the browse button to choose the start page graphically. Note that at this time only HTML documentation is supported.

Choose OK to add the entry and close the dialog. Your new documentation is available immediately.

You might at this time choose to rebuild the search index, to include your newly added documentation. This is described in the next section.

### Using the Search index

&kdevelop; includes a set of functions that help you search for information with HTML documentation. To use these features, your system needs to have the program glimpse installed. glimpse is a free database generator, which creates the search index, and executes searches within the documentation.

To set up the search index, see the section on &kdevelop; setup. The index is also generated automatically during the installation procedure.

The search functions are accessible several ways:

- In the editor, select the text you want help on, or place the cursor in the word you want to look for. Then press the &RMB; mouse button, and select the menu entry look up: expression from the context menu.

- In the editor, select the text you want help on, or place the cursor in the word you want to lok for. Choose Search marked text from the Help menu, or press the F2 key.

- In the documentation browser, select the text you want to look up, and follow the same procedures as for the editor.

- If you want to search for a specific keyword, select Search for Help on... in the Help menu, or select the Search for Help on... icon in the toolbar. A dialog will open where you can enter the word you want to search for.

The documentation browser also offers support for grep, to search for a selection within your current project. For example, you've opened the documentation page for the `KTMainWindow` and you want to know where in your code `KTMainWindow` appears. Mark `KTMainWindow` and either &RMB; click and select Grep: KTMainWindow or press Shift F2.

The Search in Files dialog opens, and displays the result of your grep search directly. You can choose from there a result line to jump directly to the corresponding source code.

## Working in the Editor

Possibly the most important part of the &IDE; is the editor. You'll be using it for:

- Creating, opening, and saving your source an dproject files.

- Editing source and project files.

- Writing your documentation.

- Printing your project files.

In general, the editor itself isn't so much different than any other editor. It will be even more familiar to many of you, as it's an embedded version of &kwrite;, &kde;'s Advanced Editor.

In addition, &kdevelop; contains a new printing system, especially adapted for working with sources. You can choose between this and the standard printing program you normally use, from within &kdevelop;'s configuration dialog.

This section gives you some more information about handling project files, and an overview of the editor's functionality.

### Managing Project Files

The following sections describe how to create, save, open, and close your project files. Please note we are not handling translation files, pixmaps, or &Qt; designer `.ui` files. These are recognized automatically and the appropriate editor will be launched to edit these.

To give you easy access to your files, &kdevelop; contains two easy to handle tree views, similar to a file manager. These are aware if you have selected a file, and will open it in the editor window.

Within the &IDE; you can open as many text files as you like. All open files are listed in the Window menu, so you can switch between them easily. The currently active file name is displayed in the &kdevelop; title bar.

### Creating and Saving Files

To create a new file choose New from the File menu. This opens the New File dialog, where you can specify the file name and type. Here you also set the destination directory, and if the file is to be added to the current project or not. Finally, you can choose to use your header template for the project, in case you are adding a new source file without generating a new clas in the class generator.

After the file has been created, you can edit the new file as usual. If you want to switch files, you do this with the Window menu, or by choosing another file in either the Files or Groups tree views.

For saving any chagnes, &kdevelop; offers a variety of options. The normal way is to simply save the file using the Save or Save as entries in the File menu, or by choosing the corresponding icons on the toolbar. To save all changed files at once, you can choose Save all from the File menu.

When working on a project, it is very annoying if something critical happens while you have a lot of unsaved changes in your files. Sometimes you will be kicking yourself for not having saved the changes. If something untoward happens, &kdevelop; is there to help you out by offering Autosaving. This is enabled by default, and will automatically save your files in intervals of 5 minutes. To select a different interval, or to disable it, see where the setup options are described.

Additionally, &kdevelop; automatically takes care of saving all changes if you open another project, or if you exit &kdevelop;. You will be asked if you want to save changes, and you can also specify which files you want to save and which files you want to drop the changes to.

When invoking any build processes, your files are saved automatically, so you don't have to wonder why your application isn't running as expected due to unsaved changes to the sources. The only exception is the Compile File command, which only saves the currently active source file.

### Opening and Closing Files

To open an existing source file, you again have several options. One way, as you might expect from any editor, is to select Open from the File menu. You will be presented with a standard Open File dialog, which allows you to choose the file you wish to edit.

Another, probably more frequently used way is to select the file from the Groups or Files tabs in the tree view pane. The advantage of these file trees is they provide a quick visual access to your project's files, especially the Groups tab, which displays only files that are included in your project, but sorts them by their type, and collected into folders.

To close files, select the file to close from the Window menu, which loads that file into the editor. Then select Close from the File menu. If your file has been chnaged, you will be asked to save it. When closing a project, all currently opened files will be checked for changes and you will be asked if you want to save them.

### Navigating Within Files

The following sections give you a general guideline how to locate certain positions within your files.

#### How to find a certain line in a file

1. Select Goto Line in the view menu or press &Ctrl; G. The Goto Line dialog will appear.

2. Insert the line number you want to jump to.

3. Press OK.

#### How to set a bookmark

1. Set the cursor to the line you wish to access by referring to a bookmark.

2. Select Set Bookmark from the Bookmarks menu.

3. From the resulting context menu, select the bookmark number you wish to assign to this position.

Another way to set bookmarks is to select Add Bookmark from the Bookmarks menu. This sets a bookmark to the current line, and appends it to the bookmark list. the Documentation browser also offers the ability to set a bookmark at the current page, through the context menu entry Add Bookmark.

The bookmarks are set for each editing window separately. Note that the bookmarks aren't connected to a file, and are not saved with the file. To delete the bookmarks for the currently active file, choose Delete Bookmarks from the Bookmarks menu. This deletes all bookmarks for the active file.

#### How to go to a bookmarked line

1. Select the Bookmarks menu and open the submenu containing the bookmarks for the window you want to view.

2. Select the bookmarked line.

Selecting a bookmark for the browser window will open the browser and load that page.

### Edit Window Settings

The editor inside &kdevelop; can be configured for special editing needs with a global effect on all editor windows. You can set color modes, highlighting colors, and automatic text settings such as tab-width and selection modes.

The following sections describe how to set these options in the configuration dialogs provided by the Options menu.

#### General Settings

The editor's general settings can be configured with the Editor in the Options menu. Select the appropriate values, and press OK when you are happy with your configuration.

##### Edit Settings

Auto Indent:

  Sets the editor to place the cursor below the first literal upon creation of a new line.

Backspace Indent:

  Sets the cursor below the first literal of the line above, when a backspace is pressed.

Word Wrap

  Words are moved to the next line after the column set in Wrap words at:.

Replace Tabs:

  Tabs in the current text are replaced with tabs of the current Tab Width: value.

Remove Trailing Spaces:

  Removes trailing spaces at the ends of lines.

Wrap Cursor:

  Sets the cursor to the end of the previous line, when backspace enters the beginning of a line.

Auto Brackets:

  Creates a closing bracket in front of the cursor when a bracket (any kind) is opened.

##### Select Settings

Persistent Selections:

  Selections made stay marked after setting the cursor to a different place.

Multiple Selections:

  Allows multiple independent selections within the text.

Vertical Selections:

  Allow vertical (column wise) selection of text.

Delete on Input

  Deletes a selection when typing into the selection.

Toggle Old:

  Allows only one selection. A selection is deselected when another selection is made.

Wrap Words At:

  Sets the maximum columns a line can have. The word that contains a letter that reaches over this value is automatically moved to the next line.

#### Color Settings

To change the editors general appearance, you can define a set of colors that the editor uses by selecting Editor Colors in the Options menu.

You can configure colors for:

Background

  The editor background.

Text Background:

  The background of displayed text.

Selected:

  The color of selected text.

Found:

  The color of text found by any kind of search, including Search, Repeat Search and Replace.

Selected + Found:

  The color of text that is both selected and found.

#### Syntax Highlighting Settings

The syntax highlighting for &kdevelop;'s editor can be configured in two dialogs.

First you can set default colors for syntax highlighting in the Editor Defaults entry in the Options menu. There you can set colors and fonts as well as the font size for different elements in the source code, for example, keywords. Select the Default item and set the options as you require.

The second configuration dialog is accessed by Syntax Highlighting in the Options dialog. This allows you to set the file filters for the programming language, &eg; `*.cpp`, `*.h` for C++.

Next, select the item you wish to configure. If you want to use the default values as you set in the Editor Defaults dialog, select the default checkboxes in the Item Style and Item Font sections. This reads the default settings for the selected item.

After pressing OK, your new values will be enabled and used in the editor.

### Searching and Replacing

#### Single File Search

1. Select Search in the Edit menu. The Search dialog will open.

2. Specify the expression to search for. The drop down menu offers the ability to select from previous search expressions.

3. Select any additional options such as Whole Words only

4. Press OK

To repeate the search for an expression, press F3

#### Searching in multiple files with grep

The search function only searches over a single file that is currently visible. Often you will want to search for the same expression across your whole project.

&kdevelop; contains a grep dialog which lets you search over all the files you specify, either by setting a directory to search in, or by setting a &MIME; type.

Specifying the exact directory and &MIME; type will therefore reduce the time that &kdevelop; needs to read your files and display the results. To start a search over several files, select Search in Files... from the Edit menu. The search dialog opens and lets you enter:

- The expression to search for.

- The template to be used for the search

- The &MIME; type of files to search in.

- The directory to search from.

- If the search is to be recursive over all the included subdirectories.

By default the grep dialog is set to start at your project directory and works recursively over implementation and header files.

You can extend your search with the following options:

Expression:
Meaning:
.
Match any character
^
Match the beginning of any line
$
Match the end of a line
<
Match the beginning of a word
>
Match the end of a word

For a repeating search, you can also use these operators:

Expression:
Meaning:
?
The preceding item matches less than once
*
The preceding item is matched zero or more times
+
The preceding item is matched once or more times
{ n }
The preceding item is matched exactly n times
{ n,}
The preceding item matches n or more times
{,n }
The preceding item matches less than n times
{n,m}
The preceding item matches at least n times but less than m times.

Back references to bracketed sub-expressions are also available with the notation `\n`.

After specifying your search, press Search. The results are then displayed in the result window.

To jump to a file and line number, select the result line and press Enter or double click the result. The editor will automatically open the corresponding file and place the cursor on the appropriate line. This allows a complete specification for any search action to give exact results.

&kdevelop; also offers some more specialized functionality to use grep with the editor and browser. Select the expression you want to search for in either of the windows, and press Shift F2 or select grep: expression from the &RMB; mouse click context menu. This will ask grep to search for the selection in your project files, and will show the results immediately.

Switching the results window after searching for the selected expression works as described above.

From within the editor window, it is sufficient to place the cursor over a word, and start searching. The word under the cursor will be the search pattern.

#### Searching Within Documentation

While working on a project, you often need to have information about the parameters of member functions you want to use. Most often you remember the name of the function that matches your needs, but the parameters are much harder to keep in mind.

&kdevelop; contains a search functionality that combines searching for expressions that occur in your files with the documentation browser.

To make use of this search functionality, you should have set up the documentation browser correctly, and created the search database.

To invoke a search through the documentation, do the following:

1. Place your cursor at the word you want to search for, or select an expression.

2. Select Search marked text from the Help menu, or press the &RMB; mouse button to open the context menu, and select Look Up: "expression"

3. After the search result page is displayed in the documentation browser, select the page that looks like it contains the information you are looking for.

4. The selected documentation page will be displayed and your search results are marked.

5. To display the next result on the same page, press F3

This allows you to easily find the information you need. To use the results, the documentation browser allows selecting a result and copying it to the clipboard. Then you can return to the file you're editing and select Paste from the Edit menu.

For a full description of how to use the Documentation, see .

#### Replacing Text

To replace an expression, select Search and Replace from the Edit menu.

The Search and Replace dialog allows you to specify an expression to be replaced, as well as a replacement expression.

When you have filled in the expressions, press OK.

The first expression which is found will be highlighted, so you can see where the expression is, and it's context. You can specify in the resulting dialog if the expression should be replaced or not.

When the search reaches the end of the document, you will be asked if you want to start searching again from the beginning of the document. If you're finished, press Cancel

### Printing

As &kdevelop; is designed to give developers the very best access to files and information, to reduce development cycles, it also contains a new printing utility which makes use of enscript, a common printing program available for &UNIX; systems.

You can also print directly using `lpr` (the line printer device).

As the use of enscript offers you the most options, it's use is highly recommended. enscript ships with many distributions, but isn't always installed by default.

Before printing anything, you should take a look at the configuration dialog, and prepare the output according to your needs. The following section describes how to configure &kdevelop; for printing files.

#### Configuring the Printer

The printing program can be configured by selecting Print from the File menu.

In the printing dialog, select the program you wish to use from the drop down menu in the upper left corner.

Press the Options button on the right to open the configuration dialog for the print program you selected.

Another way to access this dialog is to choose Printer Configuration... from the Options.

The options available to Enscript are described in the next section.

##### The Enscript Configuration Options

###### Header

Fancy Header:

  Adds a fancy header

Header Text:

  Enables adding a header text:

  text:

    Sets the text contents

  position:

    Sets the text position to the left, center or right

Login:

  Add the User ID to the header:

  Login:

    Enables adding the UserID

  position:

    Sets the position for the UserID

Filename:

  Add the filename to the header:

  Size of filename:

    Add the filename as either full (with the full path) or short (as a filename only).

  Position:

    Sets the position for the filename.

Hostname

  Add the hostname to the header:

  hostname:

    Enables adding the hostname.

  Size of hostname

    Sets the size of the hostname

  Position:

    Sets the position for the hostname.

###### Date and Time

Current Date

  Include the current date.

  Current date

    Enables adding the current date.

  Position:

    Sets the position for the date entry

  Format

    Sets the date format

Modification Date

  Include the last modification date.

  Modification date:

    Enables adding the last modification date.

  Position:

    Sets the position for the date entry

  Format

    Sets the date format

Current Time:

  Include the current time:

  Current Time:

    Include the current time:

    Modification time

      Enables adding the modification time.

    AM/PM:

      Use AM/PM or 24 hour format.

    Position

      Sets the position for the time entry.

    Format:

      Sets the time format

###### Layout

Numbering & Border:
  Numbering lines:

    Adds line numbers to the document while printing.

  Borders

    Adds a border to the page when printing.

  Numbering Pages:

    Numbers pages for printing.

  Align Files:

    Appends files one after the other, for page numbering purposes.

  Lines Per Page:

    The maximum value for lines per page.

Format and TAB
  Set TAB Size:

    Sets the TAB size for printing.

  Font for Header:

    Sets the font used for the header text.

  Font for the Body:

    Sets the font for the body text (the file contents).

Text:
  Cut lines:

    Cut off the lines if they are too long. If unchecked, the lines are wrapped instead.

  Replace non-printing characters:

    Replaces characters that the printing charset doesn't support with spaces.

Other Options:
  Table of Contents:

    Adds a table of contents page that contains information about printed files, page numbers, &etc;.

  Highlight Bars:
    Highlight Bars:

      Highlights rows for printing.

    Cycle of Change:

      Sets the number of rows to change highlight style.

  Wrapped Lines:
    Mark Wrapped Lines

      Lines that are broken get marked for printing.

    Value for wrapped lines:

      The preset value for the new line the line is broken into.

###### Underlay

Text

  Sets the text to underlay

Position:

  Sets the position of underlay text.

Font

  Sets the font used for the underlay.

Angle:

  Sets the angle for the underlay text.

Gray scaling

  Sets the grayscaling for the underlay text.

Style

  Sets the underlay text to be printed as outlined or filled.

#### The Printing Dialog

##### Direct Printing Options

Program

  Sets the printing program to be used for printing. You can choose between enscript or lpr.

Printer:

  Sets the printer to be used for printing.

Output Location:

  If you print to a file, choose the location to save the file.

Orientation

  Sets the orientation for printing, either landscape or portrait.

Copy:

  Sets the number of copies to be printed of each page.

Paper Size:

  Sets the paper size to be used.

Output Format:

  When using enscript, you can choose between &PostScript; and HTML printing.

Default Printsettings:

  Sets the default settings to be used for printing.

  Out Printing:
    Page Printing:

      Sets one or two pages per sheet of paper.

    Pages:

      Select all, odd, or even (only available with enscript.

    Pretty-Print:
      Pretty-Print:

        Enables pretty print mode for enscript.

      Color:

        Use color printing.

      Pretty Print Mode:

        Sets the printing mode, dependent on your file format.

##### File Selection

The file selection dialog is accessed with the Files on the printing dialog.

The file selection allows you to specify which files to print through the following criteria:

current

  The currently active file in the editor.

All in project:

  All files in the project currently open.

Self chosen files:

  Choose the files individually from a file selector.

All CPP files:

  Prints out all the source files of the project.

All Headers:

  Prints out all the header files of the project.

Changed files:

  Specify files that were changed during a particular time span:

  Between

    Specifies files changed after:

    Date

      The date the files were changed.

    Time:

      The time the files were changed.

  And:

    Specifies files changed before:

    Date:

      The date the files were changed.

    Time:

      The Time the files were changed.

Self Chosen Files:

  Becomes active if Self chosen files is selected above.

  Add

    Press this to add a selected file for printing to the list on the left.

  Delete:

    Delete a selected file from the printing list.

  Clear:

    Clear the printing list.

##### Print Preview

The print preview is available for you to check the appearance of the output.

&kdevelop; uses the program ghostview or &kghostview; if available.

When the preview button is pressed in either printing dialog, you will be presented with a preview of template output, showing you the effect of the currently set options.

## Projects

&kdevelop; creates a project file with a `.kdevprj` extension. This file contains all your project information, so be careful not to delete it.

The project file is stored in the project's base directory, and loads the project into the &IDE; when opened. The project file contains all the information for your project, including file properties, install paths, distribution status, and compiler options (`CXXFLAGS`).

### Project Types

#### Programs

With KAppwizard, you can create a new application project, with one of the following kinds of framework already set up for you:

A single document interface (SDI) application

  This is a &kde; application, and includes a menubar, a toolbar, and a statusbar. It contains basic control resource management, to allow you to extend the frame application into a unique &kde; application.

  From a programming point of view, it is based on three application specific classes, built on the MVC or Model-View-Controller model.

A &kde; based application frame.

  This application type offers the most flexibility for those wanting to develop their program from scratch, but can also be used as a basis for developing wizard applications or modules.

A &Qt; based program framework.

  This option is for programmers who want to use only the &Qt; library as the GUI interface. As &Qt; only programming is fully supported, you should have no problems creating a fully functional application without the use of the &kde; libraries.

A C++ program framework.

  This application type is intended for those who want to create a terminal based C++ program.

  Just remove the Hello Wold line in the `main()` function, and construct your classes in the usual &kdevelop; way.

A C program framework.

  Again aimed at developing terminal based applications, but this time using only the C compiler.

A Gnome application

  Allows you to use &kdevelop; to create a GTK+ based application.

Additionally, &kdevelop; enables you to work with already existing projects.

You can set options yourself for the `configure` and `Makefile`s, but as far as the execution and build process is concerned, currently you are limited to the same structure as the other base classes.

Create a custom project with the application wizard, and add your files to the project to allow scanning with the Classes browser.

To ensure the build process succeeds, your custom project must have all the sources in a subdirectory which is named the same as your project, in lower case. The execution of the binary is also restricted to this lowercase project name.

Note that in this case, &kdevelop; does not write any information into `Makefile`s or configuration files. You will be responsible for project behaviour and build settings by yourself.

#### Libraries

A general project type to create libraries is not yet available. This doesn't mean that building libraries is impossible with &kdevelop;, so here are some helpful guidelines.

- Whenever your project subdirectory gets another subdirectory containing source files, &kdevelop; will build a static library of these.

  This means that static libraries are already supported in an automatic fashion, in order to sort project source files.

  Be aware that a static library later becomes part of the binary, and is not installed on your target systems.

- To create a shared library, &kdevelop; offers an easy way to convert a static library as already mentioned, into a shared library:

  ##### Turning a static library into a shared library:

  1. Open the Files tree on the left of &kdevelop;'s main window, and browse to the subdirectory containing your sources.

  2. Click with the &RMB; mouse button over the subdirectory. You will see a context menu with the following options:

     - Update Makefile.am

     - Change to static lib

     - Change to shared lib

  3. Select Change to shared lib to convert the default generated static library into a shared one.

  4. If you later decide to reverse your change, repeat these steps, but choose Change to static lib.

#### Multiple Targets

For some projects, the facilities of &kdevelop; are not yet sufficient on their own.

These include projects with multiple targets, such as packages of several applications. Since commands such as Execute require that only one target is built by the developer, these types of projects are only partially supported.

To use &kdevelop; for such a project at this stage, you will need to write your own entries to the `Makefile.am`s, and you will need to create your own directories for additional libraries or binaries to be built.

Nevertheless, a build process always invokes the make program independently of what the targets actually are. In other words, you can still use these functions, with the restriction that the build process is invoked from within the main project subdirectory.

There is another way to ease working with this type of project, and still have access to the binary itself.

You can create empty projects, and later move their subdirectories, and the project files they contain, into a top level subdirectory that contains all the sources. Then you can load each target independently, through it's own project file. This allows you to execute and debug the target normally.

Multiple binaries or libraries withint he main project subdirectory are possible, so long as you stick to the rules described in the section Project Hacking, and the following guidelines for editing the main project's `Makefile.am`.

All these modifications should be outside the marked &kdevelop; write area.

- Add your target to the `bin_PROGRAMS` line if it is an executable.

- Add your library declaration line, if it is a shared library.

- Add the same declarations as for the original project binary build:

  - `newtargetnewtarget_METASOURCES`

  - `newtarget_LD_FLAGS`

  - `DISTCLEANFILES`

  - Copy the `messages:` entry for the original binary, and replace `target_SOURCES` with `newtarget_SOURCES`, and `target.pot` with `newtarget.pot`.

- Add your sources the same way the &kdevelop; write area contains them, but outside the write area, and adapting for your binary or library.

- For installing static libraries, create the library with &kdevelop;'s auto creation in subdirectories. Then modify the `Makefile.am` as required, but outside the &kdevelop; write area.

### New Projects

The &kdevelop; application wizard allows the creation of different types of projects, and constructs a framework for each. All the projects use the GNU standard development tools, as described previously in the requirements section of this manual.

For &kde; applications, there are six different frameworks.

Mini

  Creates a &kde; application, with an empty main widget.

Normal

  Creates a &kde; application with session management, menubar, toolbar, statusbar, and support for a document-view codeframe model.

Normal-OpenGL

  Creates a &kde; application with session management, menubar, toolbar, statusbar, and support for a document-view codeframe model. OpenGL support with Mesa3D is added.

&kde; 2 Normal

  Creates a &kde; 2 application, with session management, menubar, toolbar, statusbar, and support for a document-view codeframe model.

&kde; 2 Mini

  Creates a &kde; 2 application with an empty main widget.

&kde; 2 MDI

  Creates a &kde; 2 MDI (Multiple Document Interface) applicatoin with menubar, toolbar, statusbar, and support for a document-view codeframe model.

If you don't wish to depend on the &kde; libraries being available on your end users machinse, you can choose to make a &Qt; only project, from the following types:

Normal

  Creates a &Qt; application with a main window, containing a menubar, toolbar, and statusbar, and support for a generic document-view model.

&Qt; 2.x SDI

  Creates a &Qt; 2.x application with a main window containing a menubar, toolbar, and statusbar, and including support for a single document-view interface (SDI) model.

&Qt; 2.x MDI

  Creates a &Qt; 2.x application with a main window containing a menubar, toolbar and a statusbar, with support for a multiple document interface (MDI) model.

QextMDI

  Creates an MDI framework based on the `QextMDI` library, and &Qt; 2.x. This allows you to switch between two modes, Toplevel and Childframe. This requires the `QextMDI` library, see http://www.geocities.com/gigafalk/qextmdi.htm page for more details.

Note that &Qt; 2 normal and &Qt; 2 MDI templates make use of the &kde; automake system. This will make it easier to later switch your existing &Qt; application into a &kde; application, as the automatic checks needed for &kde; libraries and headers can be added to the project very easily.

See the section on Project Hacking for more information.

The &Qt; 2 normal and &Qt 2 MDI templates also allow you to internationalize the GUI of your application, through the integration of &Qt; Linguist. The handling of adding languages by &kdevelop; is identical to the &kde; projects.

The application wizard also offers a template for creating GNOME compliant applications with the GTK+ C library. This will give you a ready to run main window, containing a menubar, toolbar and statusbar.

The two C and C++ application types offere a framework for creating command line applications.

Finally, you can create an entirely empty projcct. This is useful for working with existing projects.

The wizard will ask for your project name, the version, and the location to build the project directory. Your name and email address are requested to insert them in the header and cpp templates, which will put them in the top of your source files, as well as the entries in the `*.lsm` file.

To add revision control to your projects, see the chapter on CVS inegration..

### Opening and Closing of Projects

&kdevelop; is by default configured to load whichever file was open when you last closed the &IDE;.

This behavior allows you to get off to a quick start in most cases, but you may want to change that so that you start the &IDE; without any project loaded. You can change this with the Load last project: option in the &kdevelop; Setup dialog.

To open another project, select Open from the Project menu, or press the Open Project button on the toolbar.

If you have another project open already, it will be closed. If you have unsaved changes in any of the open files, you will be offered a chance to save some or all of those changes, and to select which changes to save.

You will be presented with an Open Project dialog, where you can browse to the directory containing the project you wish to load. &kdevelop; project files have the `*.kdevprj` extension, and are displayed with a project icon, to make them easy to find.

Select the project file and press Open.

When loading a project, the Classes browser will scan all the files and build an initial classtree, so you can start working on your project by using the Classes browser directly.

Another way to open a project is to simply select the project file in &konqueror;, the &kde; file manager. This will start &kdevelop;, and load the selected project file.

You could also open a project on the command line, entering ``kdevelop` `projectname.kdevprj``.

When closing &kdevelop;, your project file will be saved automatically, and the &IDE; detects if you have changed any project files. You will be prompted to save any changes before exiting.

### Editing a Project

After you have created a new project with the KAppWizard, your task is to extend the project by editing the newly created sources, adding classes, pixmaps, pictures, and whatever else your project needs.

Editing a project allows you to change the default project after it's generation, using the menus and dialogs according to your needs.

The next section Adding and Removing Files and Classes, describes how you can add existing files and classes, as well as creating new files.

Later we decribe how to set project options that affect the end-user. This includes things such as additional files you may want installed, documentation, and pixmaps. This is covered in the section Setting Project File Options.

Another task in project maintenance is internationalization, which is described in the the section Adding Translations.

The section Extending the Project Documentation covers some issues that will help you create a good set of online help documentation, enabling the user to help himself in times of trouble, and to make the best use of your product.

Finally, the section Project Hacking describes how you can work around the &kdevelop; project management, if you have a special requirement.

### Adding and Removing Files and Classes

Adding a new file is most used in cases where you separate your class implementation into several file into several files.

To do this, you need to create a new file wich will contain the part of the class implementation you want to move. You can create a new file by choosing New from the File menu, which will open the New File dialog.

This dialog enables you to specify the file type, the name, and the location. When you enter the filename, &kdevelop; automatically enters the extension, based on the file type you have chosen, but you can override this if you use a different naming scheme.

&kdevelop; will also automatically include the header template for source files, so that you don't have to copy your contact and copyright information into each file yourself.

You can also select in this dialog if the new file is to be part of the project or not.

Note that you cannot set the installation destination here, this must be configured later by setting the file preferences.

After the file has been created, the project file will be updated, as will the corresponding `Makefile.am`s.

To add a complete class to your project, you can construct a new class with the Class Generator, which is invoked from New Class in the Project menu.

If you have an existing projec,t and you want to add classes that will be reused throughout your project, select Add File(s) to Project... from the Project menu. Choose Add existing files, which will open a dialog that allows you to specify which files to add to the project, and the destination directory.

Note that the files will be copied into the specified directory, and added to the project.

You should call Make after adding sources, so &kdevelop; will include your newly added files into the build process.

If you are adding files that will be installed on the end user's computer, for example icons, you should update the file properties for the newly added file, and specify the installation path. The section Setting Project File Options covers this process in detail.

To add a file to the project that is already in the project directory, go to the Files view, where all project included files are displayed with a red ! over their file icon. Select the file you want to add to the project (it will currently have an ordinary file icon), and press the &RMB; mouse button to display the context menu. Choose Add.

Files can also be removed from your project. This might happen because you don't want to use the pre-generated files from the KAppWizard, or because you no longer need files that were previously part of the project.

When removing a file, you have the choice between removing it from the project, but leaving the file intact, or deleting it entirely.

To remove a file from the project, select the file in the Groups tree, or the Files tree, and press the &RMB; mouse button. Select Remove from the context menu.

To delete a file, follow the same procedure, but choose Delete physically from the menu.

### Setting Project File Options

The file properties dialog can be accessed via the Project menu, or within the Groups viewer with a &RMB; mouse click.

The file properties dialog shows the project files in groups, as they are sorted in the Groups viewer, and displays properties such as file size, file type, and if the file is included in the project.

The dialog also shows the installation path, if the file is to be installed on the end user's computer with the ``make` `install`` command. It is important for things like documentation and images to specify the destination location at installation time. For standard &kde; locations, you should look in your `Makefile.am`, where the location macros are specified.

### Adding Translations

#### Internationalization of &kde; 2.x Applications

As &kde; alllows configuring the desktop, and the behavior of applications, users also have the option to choose the language that applications use, both for documentation and for the interface.

For documentation files, this appears to be a fairly trivial task. Add a subdirectory named for the desired language code, &eg; de for German, to the `docs` directory of your project, and copy the english documentation into that directory. Then generate the documentation, and set all the project options for the installation directories. Simply translating the source SGML or XML file to the desired language, regenerate the documentation and you are done.

For the application interface, things are a little more difficult.

First, you must enclose all strings that will be visible to the user, &eg; in dialogs, or error messages, with the `i18n()` macro.

This macro is a replacement for the function `klocale->translate()` from the `KLocale` class, and the macro is much easier to use.

As this macro is declared in the `kapp.h` include file, you should add `&num;include <kapp.h>` to the source file, or the class declaration file of the class that makes use of the macro.

It should also be noted that although `i18n()` is a macro, and it might be tempting to just use the original function, this won't work. This is because the strings that are set up for translation have to be read out of the sources, and stored in the application's translation file, `YourApp.pot`, in the `/po` subdirectory.

This task is handled by a program xgettext. As xgettext depends on the `i18n()` macro, the original function won't do the job.

For the translations themselves, you first must create the message file containing all the string sthat are used in your sources, and contained in `i18n()` macros. This is most easily done by choosing Make messages and merge from the Build menu.

Next, select the languages that your application is to support, by choosing Add Translation File from the Project menu. In the resulting language selection dialog, choose the language(s) you want to add, and press OK.

An ASCII file will be build, containing the entries for each string, with a filename and the line where the original string is placed. You will see lines with `msgid`, containing the string to translate, followed by `msgstr`. The msgstr line is mostly empty, except for those strings which already have translations provided in the &kde; libraries. The rest of them need to be filled in with the appropriate translations for your target languages.

You could think about writing the translations by hand, in the editor. That would be a very tedious job, so the &kde; SDK offers a program called KTranslator which helps you reuse strings and translations from other applications, to aid in your translation.

To access KTranslator, the easiest way is selecting a `language.po` file in the `/po` directory, in either the Files pane or the Groups pane.

KTranslator will open, with the file, to help you with your translation. Note that you have to set up KTranslator's properties separately, to include the authors name and contact address, and the language, as well as the destination files. KTranslator by default only opens your translation file.

For all translation files, make uses the program msgfmt to format your message files to use with the binary. You don't have to worry about either this task, or specifying destinations for the installed translation files, as &kdevelop; takes care of these automatically.

For more information about internationalization support, see http://i18n.kde.org/, where you will find a lot of people doing translations to their own languages, and you will find contacts who may be able to help you with this job.

#### Internationalizatoin of &kde; 2.x Applications

&kde; 2.x projects have a slightly different method of handling `po` files and keeping them up to date than &kde; 1 did.

The first thing to watch for when generating a &kde; 2.x project is that ``make` `package-messages`` is called from the base directory of your project, rather than in the project's subdirectory as was the case in &kde; 1.x applications.

While merging strings is done by calling ``make` `merge`` in the `po` directory in &kde; 1.x, this is now handled automatically when you run ``make` `package-messages``. Obviously this will result in an error message while initially creating your project with the application wizard.

Another issue to watch out is that &kdevelop; installs a script called `extractrc` into your `$KDEDIR/bin` directory. This script is from the &kde; CVS module `kdesdk/scripts`, and is called automatically within ``make` `package-messages``, if your `Makefile.am` contains the line `messages:rc.cpp` instead of `messages:`. This is the default for the &kde; 2 normal and &kde; 2 MDI project types. The &kde; 2 mini uses only `messages:`

What this script does is extract the strings out of your XML resource file (`yourappui.rc`) to build the application's &GUI;, and then stores these strings in a temporary file called `rc.cpp`. This way, the strings in the XML file are processed as usual when building the `pot` file, and are included in your internationalization efforts.

If you intend to build a &kde; 2.x application based on the &kde; 2 mini template, it is best to change the `Makefile.am` in this section. The necessary changes are already noted there in comments.

#### Internationalization of &Qt; 2.x Applications

Since &Qt; now includes the `tr()` method, together with the `QTranslator`, you can easily internationalize your &Qt; only project as well.

&kdevelop; supports this by using the tools that come with &Qt;'s Linguist: lupdate and lrelease.

The strings inside `tr()` functions are read into the language-dependent `*.ts` files by lupdate, and lrelease then covnerts the translated XML file to a file named `*.qm`, which stores the translations in a binary form.

### Extending the Project Documentation

### Project Hacking

When working with a project, you should never edit the project file by hand. Doing so would prevent &kdevelop; from loading your project correctly under certain circumstances, and any changes you make won't be reflected in the appropriate `Makefile`s.

To change any settings for your project, &eg; adding files or setting file properties, you should use the appropriate menu entries. For experts that are not comfortable with certain options for things, or need additional project configuration, you can edit the `Makefile.am` macros, but you should add any custom entries after the section separated with the text `KDevelop write area`.

As the GNU tools use the commands at the end of the macro files, you can overwrite &kdevelop;'s settings in this manner. Bear in mind that this will prevent the use of &kdevelop; for any changes to the affected project settings.

#### Project Type Definitions

&kdevelop;'s project files store the project information in the style of human-readable &kde; config files, so you should have no trouble finding the sections you're looking for.

To convert an existing project to another project type can dramatically shorten the time it takes to port an existing &kde; 1.x project over to &kde; 2.x (or from &Qt; 1.x to 2.x.)

Change the following sections according to the project type:

    [General]
    author=Ralf Nolden
    project_type=normal_kde2

Valid project types are:

normal_empty

  Custom project

normal_kde

  KDE 1.x Normal (SDI project.

mini_kde

  KDE 1.x Mini project

normalogl_kde

  KDE 1.x OpenGL project.

normal_kde2

  KDE 2.x Normal (SDI) project.

mini_kde2

  KDE 2.x Mini project.

mdi_kde2

  KDE 2.x MDI project.

normal_qt

  &Qt; 1.44 project (SDI).

normal_qt2

  &Qt; 2.2.x project (SDI).

mdi_qt2

  &Qt; 2.x project (MDI, uses `QWorkspace`.)

mdi_qextmdi

  &Qt; 2.x project (uses the QextMDI library.)

#### Converting `*.kdevdlg` files

&kdevelop; comes with a converter script, `kdevdlg2ui`, to turn already constructed dialogs from previous versions of &kdevelop; into `.ui` files.

You should be aware that you may have to re-inherit from the class gernerated by &Qt;'s `uic`, and add your implementation from the former &kdevelop; there. The converter script is mainly used to convert the dialog's user interface, rather than your methods, signals, and slots. Re-editing the converted `.ui` file may be necessary, as well as inheriting from it's generated class.

Existing &kde; 1.x applications can't make use of `.ui` files, so you must therefore generate a new framework for your &kde; 2.x/&Qt; 2.x application, and move over your implementation, `.kdevprj` and `Makefile.am`'s of your subdirectories.

### Compiler and Linker Flags for Projects

Each new project contains all the required options for the compiler and linker, as well as general settings.

By default, youre project is set to use debugging, witht he `-g` flag, and warnings are set to the standard `-Wall`. This ensures you can debug your applications, and detect constructions that may cause program errors.

For some applications, you would need additional compiler and linker flags, especally if you're using libraries that are not currently included by the linker. You need to update the project by configuring the correct settings with the Project Options dialog.

See Build Settings for more information how and where to set compiler options, warnings, and linker options.

### External Projects

Existing `automake`/`autoconf` compatible projects (those which make use of `Makefile.am`'s to store their information) can be used together with &kdevelop; by creating a &kdevelop; project file with the `kimport` script.

After the project file has been built, you should edit it with your favorite editor, setting the project type according to your needs. See Project Hacking for more details about available project types.

Be careful to deselect Modify Makefiles in the Project Options after you load your project for the first time.

## Build Settings

The Project Options dialog, accessed from the Project menu, allows you to specify all the necessary parameters for your project. These will be used by the `Makefile.am`'s and the `configure.in` script, to set things like version number changes and compiler warnings, and other compilation preferences.

After changing the project options, you should invoke make clean or rebuild all to compile your project with the new options.

Debugging is only available if the project options are set to create debugging information. The amount can be set with the debug level, between `0` and `3`.

If you add functions that belong to a library that is not included in the linker flags, your program will not link correctly, so remember to keep track of your library linking and add those required libraries to your options.

For a release build of your application, or for distributing the source code package, you should change the options to the following standard settings:

- Disable debugging.

- Enable optimization, and set optimization level to `-02`.

- Set the compiler warnings to `-Wall`.

- For each new release, increment the version number and update the `project.lsm` file with the new version and any changed requirements.

### General Options

The first page of the Project Options dialog sets the general options for your project. These are the Project name: and Version:, the handbook SGML file containing your user documentation, and some specific author information. The short description field is for additional information that you want to include, such as the program's purpose.

### Compiler Options

The Target section contains options relating to your target system, that is, the system on which you will be building this project.

Target Machine

  Choose the target from the drop down list. The choices currently available are your machine or i386v. The latter is an option if you have configured your compiler as a cross compiler for an Intel 386 compatible machine running System V. This is the equivalent of setting the `-b` on the compiler. The default (your machine) is normally the right choice.

optimize

  Select this check box if you want to compile a binary optimized for your target system, as selected in the drop down list above.

Optimization level

  Choose the level of optimization to be used when building. Choose from a range between 0 (no optimization) and 3 (highly optimized). This is the equivalent of setting the `-O` compiler flag. For a release version of your applicaiton, enable optimization, and set the level to 2.

The Debugging section has options relating to the level of debugging information to be compiled into your project's binary.

generate debugging information

  Enable or disable debugging here. By default, debugging is enabled, but you should turn it off before creating binary or source code packages for distribution. This sets the `-g` flag for the compiler.

Debug level

  Select the level of debugging information that should be compiled into your binary. Choose from a range between 0 (no or little debugging information) and 3 (lots of debugging information.) Remember that debugging information slows down the execution of your program, and increases the size of the binary.

generate extra information for gprof

  This sets the `-pg` flag, with the result that the compiler will include extra information, which the `gprof` program can use to generate graphs of your program's functions.

Store temporary intermediate files

  This sets the `-save-temps` flag, so the normally temporary files created by the preprocessor and the assembler will instead be saved. With this enabled, compiling will produce three files: the `.o` file that you would normally expect as the output of the compiler, an `.i` file as produced by the preprocessor, and an `.s` file as the output of the assembler.

You can enter any additional compiler options directly in the field labelled additional options:. These are stored in the `CXXFLAGS` environment variable in the `Makefile`s, so make sets these flags before the build process begins, and resets them again when complete.

For a complete description of all available compiler flags, you should see your compiler documentation. For `gcc` and `egcs` this can be done with ``man` `gcc``. ``man` `g++`` will show you information about the C++ script that is used to lead the compiler.

### Compiler Warnings

This section gives a description of the compiler warnings that can be set on page 3 of the Project Options dialog. The explanations are based on the man page for `gcc`, `egcs` version 1.1.1. the warnings themselves are diagnostic messages that indicate a construction that may cause errors.

`-Wall`

  Standard `-W` options combined.

`-W`

  Compile with `-W`. This option sets options not included in `-Wall` which are very specific. Please read `gcc` `info` for more information.

`-Wtraditional`

  Warn about certain contsructs that behave differently in traditional and ANSI C.

`-Wundef`

  Warn if an undefined identifier is evaluated in an `&num;if` directive.

`-Wshadow`

  Warn whenever a local variable shadows another local variable.

`-Wid-clash-LEN`

  Warn whenever two distinct identifiers match in the first LEN characters. This may help you prepare a program to compile with certain obsolte, brain-damaged compilers.

`-Wlarger-than-LEN`

  Warn whenever an object larger than LEN bytes is defined.

`-Wpointer-arith`

  Warn about anything that depends on the size of a function type or of void. GNU C assigns these types a size of 1, for convenience in calculations with `void * pointers` and pointers to functions.

`-Wbad-function-cast`

  Warn when a function call is cast to a non matching type. For example, warn if `int malloc()` is cast to `anything *`.

`-Wcast-equal`

  Warn whenever a pointer is cast so as to remove a type qualifier from the target type. For example, warn if a `const char *` is cast to an ordinary `char *`.

`-Wcast-align`

  Warn whenever a pointer is cast such tha the required alignment of the target is increased. For example, warn if a char * is cast to an int * on machines where integers can only be accessed at two- or four-byte boundaries.

`-Wwrite-strings`

  Give string constants the const char[length] so that copying the address of one into a non-const char * pointer will get a warning. These warnings will help you find at compile time code that can try to write into a string constant, but only if you have been vary careful about using `const` in declarations and prototypes. Otherwise, it will just be a nuisance. This is why we did not make `-Wall` request these warnings.

`-Wconversion`

  Warn if a prototype causes a type conversion that is different from what would happen to the same argument in the absence of a prototype. this includes conversions of fixed point to floating, and vice versa, and conversions changing the width or signedness of a fixed point argument, except when the same as the default promotion.

`-Wsign-compare`

  Warn when a comparison between signed and unsigned values could produce an incorrect result when the signed value is converted to unsigned.

`-Waggregate-return`

  Warn if any functions that return structures or unions are defined or called. In languages where you can return an array, this also elicits a warning.

`-Wmissing-prototypes`

  Warn if a global function is defined without a previous prototype declaration. This warning is issued even if the definition itself provides a prototype. The aim is to detect global functions that fail to be declared in header files.

`-Wmissing-declarations`

  Warn if a global function is defined without a previous declaration. do so even if the definition itself provides a prototype. Use this option to detect global functions that are not declared in header files.

`-Wredundant-decls`

  Warn if anything is declared more than once in the same scope, even in cases where multiple declarations is valid and changes nothing.

`-Wnested-externs`

  Warn if an extern declaration is encountered within a function.

`-Winline`

  Warn if a function can not be inlined, and either it was declared as inline, or else the `-fin*line-functions` option was given.

`-Wold-style-cast`

  Warn if an old style (C style) cast is used within a program.

`-Woverloaded-virtual`

  (C++ only.) In a derived class, the definitions of virtual funcitons must match the type signature of a virtual function declared in the base class. Use this option to request warnings when a derived class declares a function that may be an erroneous attempt to define a virtual function. In other words, warn when a function with the same name as a virtual function in the base claass, but with a type signature that doesn't match any virtual functions from the base class.

`-Wsynth`

  Warn when `g++`'s synthesis behaviour does not match that of cfront.

make all Warnings into errors

  This sets the `-Werror` flag, telling the compiler to treat warnings as errors, and abort compilation after any warning.

For a release of your project, it is recommended to enable `-Wall`

### Linker Options

The `Linker Options` for your current project can be set on the fourth page of the project options dialog. You should enable those libraries that your application uses, in order to link them to your binary with the linker. For example, if your application uses the class `KFileDialog`, which is part of the KFile library, you should enable kfile.

For classes or or functions that are not listed as checkboxes, use the additional libraries: field.

Other options available to you are:

remove all symbol table and relocation information from the executable:

  This means that all redundant information will be removed from the object files and the binary. Debugging will not be possible. For as long as you are still working on your application, and not being prepared for a release, you should leave this option disabled.

prevent using shared libraries

  This option disables the use of shared libraries on systems that support this. On systems using no shared libraries, this option will have no effect.

additional flags

  Here you can enter any further flags for the linker. This will result in `make` setting the `LDFLAGS` environment variable for the duration of the compile. The available options can be taken from the man page for `ld`, or from your compiler documentation.

#### Libraries

The libraries section contains checkboxes for the most commonly used libraries for &Qt;/&kde; applications. You should enable those libraries that your application uses, or the linker will complain about unresolved symbol tables.

The libraries that are available as checkboxes are:

X11

  The X11 library. Recommended for all &X; programs.

Xext

  The X11 extension library. Almost all &X; programs also depend on this.

qt

  The &Qt; library. Obviously recommended for &Qt; and &kde; applications.

kdecore

  The &kde; core library, contains the classes for &kde; application frameworks.

kdeui

  The &kde; user interface library, containing &kde; specific widgets.

khtmlw

  The KHTML widget library.

kfm

  The KFM library containing classes for KFM functions

kfile

  The KFile library, containing file dialogs &etc;

kspell

  The KSpell library. Contains an interface for programs to use `ispell` for spell checking.

kab

  The &kab; library, necessary for access to the address book, as well as providing addressbook widgets.

You can enter any additional libraries that your application needs in the additional libraries field. Set the libraries with the `-l`, for example, `-lkom`.

### Make Options

As GNU `make` supports some useful options, the Project Options dialog contains a page called Make Options where they can be enabled or disabled.

The available settings are:

Print debug information

  Print out all information about the project files, and what `make` determines for rebuilding them.

Continue after errors

  Tries to continue with the compilation after an error occurred, &eg; if a file couldn't be compiled due to an error, `make` will carry on with the next file.

Print the data base

  Prints out the `make` database for the current process, which contains the changes from the last build run.

Environment variables

  Give the current environment variables a higher priroity than the ones currently set in the `Makefile`s.

No built-in rules

  Doesn't use built-in rules for `make`

Touch files

  Don't run the compiler on changed files, instead only touch them. This sets them as already processed by `make`.

Ignore all errors

  Ignores all errors that occur.

Silent operation

  Doesn't print out any information about the build process.

Print working directory

  Prints the current directory during the make process.

job number

  Sets the amount of parallel processes for `make`. For a single CPU system, we recommend setting this to one or two.

set modified

  Sets the selected file modified. Choose the file by clicking the folder button on the right, and browsing to it. Setting a file modified means that the file will be processed by `make` and compiled if it is a source file.

additional options

  Set additional options for `make`. The options available to you can be found in your local man page for GNU `make`.

Rebuild behavior on run

  Sets the actions taken when you choose run. There are three options available:

  Always Rebuild

    Always rebuild the entire application, without checking for modified files.

  Warning on modification

    Warn if the sources have been modified, and ask if the project should be rebuilt.

  Only on modification

    Check if sources have been changed, and rebuild if so.

  The default is to alays rebuild.

## The Classes Browser

The &kdevelop; Classes viewer is one of the most useful and important tools the &IDE; provides the developer for managing his sources.

When a project is loaded, a class parser reads all the project sources for functions, classes &etc;, then displays the results in the Classes tree view.

This chapter shows you how to use the Classes viewer, and how to let the provided functionality eas your workload.

### The Classes Viewer

Classes and their methods can be further accessed with the browser toolbar. There, the &LMB; mouse button selects the class, and the &RMB; lets you choose the methods of the selected class.

When you select a method, the class browser will automatically take you to the implementation file, and set the cursor at the method.

Finally, the class-assistant button on the right of the method combo will bring you to the declaration of the method with a click. Another click will take you to the definition. If you click and hold the mouse button on the Class assistant icon, a menu will appear, which offers additional functionality. These functions are also available in the Classes viwer context menus, and include:

Goto Declaration:

  Browse to the declaration of the method.

Goto Definition:

  Browse to the definition of the method.

Goto Class Declaration:

  Browse to the class declaration.

New Class:

  Opens the New Class dialog to construct a new class.

Add Method:

  Adds a method to the selected class.

Add Attribute

  Adds an attribute to the selected class.

Show graphical classview:

  Opens the graqphical inheritance tree.

#### Available Objects

C++ code can be seen as a collection of objects. Classes, their members, global functions and more, can all be seen as objects. The Classes tree displays these objects logically, and orders them according to their character, so they are easy to locate in the tree.

The tree contains both a Classes folder and a Globals folder.

The Classes folder generally contains the project's classes. If your project contains subdirectories to manage your sourcefiles, these are also displayed by their original folder name, and contain all classes that are stored in the files located within them.

When popping up a class, the tree displays the class contents by separating methods and attributes. As these can have attributes as well, such as `public`, `private`, and `protected`, these are indicated by modified icons.

You will see that a class displayed in the browser contains all the objects that are present in the class declaration.

Classes are very common things when programming in C++, and they contain most of the code. However, applications also contain objects that have a global appearance to the program. These include structs and functions. Notably, the `main()` appears in every application, and you will need to modify it in one way or another.

To access these objects, the viewer provides the Globals folder, containing the subfolders for the following object types:

- Structs

- Functions

- Variables

As the icons displaying these items are similar to those used in the class viewer, their meaning should be easy to determine and remember for the programmer.

Finally, it can be stated that the class viewer displays your project graphically as objects reated to their appearance in the code. In the next section, you will learn how to use the class viewer and it's tools.

#### Browsing Object Declarations and Implementations

The Classes viewer's major strength is in providing fast and easy access to the code, by keeping it's view of the code independent of that code's location within the source files.

Selections made here with a mouse click will result in the following actions:

On a class name:

  Switches you to the class declaration.

On a class method:

  Switches you to the method implementation.

On a class attribute:

  Switches to the attributes declaration within the class declaration.

On a struct:

  Switches to the struct's declaration.

On a global function:

  Switches to the function's implementation.

This provides you with direct access to code objects. As an example, you might need to change a method's header, with the result that you will have to change it's declaration in the class, as well as in the implementation. The class viewer supports this by providing &RMB; mouse button context menu's over items. On a method or function, this means you can select where to go next:

Go to definition:

  Switch to the implementation. This is the default behavior, which you can also access with a &LMB; click.

Go to declaration:

  Switch to the declaration of the method or function.

In this way, the browser offers you access to every location you might need to go while coding your C++ application.

The next section will give you a description of the other tools that the Classes pane offers. You will find them very useful when working with large projects, as they enhance the object-oriented method of working with C++ programming.

### The Class Tools

The class tools are dialogs that make it even easier for the developer to access information about his project's classes.

The Classes viewer displays all the objects, but sometimes you want to get more information about a class without having to look inside the code. The class tool dialogs are for displaying specific class attributes.

The classtool is invoked from the context menu over a class in the Classes viewer tree. Choose Properties and the dialog will appear.

The properties dialog defaults to the class that you had selected when it was invoked, but you can select another class from the combo box on the right.

The initial tab is the Class Viewer. The toolbar contains several icons, which change the view of the class as follows:

Show Parents

  Display the parents of the selected class, in other words the class it inherits. This is especially useful for multiple inheritance, as well as to see why a class behaves one way or another. For example, for dialogs, your parent class could be `QWidget` or `QDialog`.

Show children

  Displays the children classes that inherit the currently selected class.

Show Clients

  Shows classes that make use of the selected class through an attribute in their class declaration.

Show Suppliers

  Show the suppliers that give attributes to the selected class.

Show Attributes

  Show the attributes of the class.

Show methods

  Show the methods of the selected class.

You can further modify the display of attributes, methods, and virtual methods with the combo box on the far right. The default is to show all, but you can filter by public, protected or private.

### Managing Classes

## Using &Qt; Designer in Your Project

The &Qt; Designer allows the easy construction of the widgets and dialogs uses, through all graphical means. You see the appearance of your dialog as it will be presented to the user, while you are building it.

Using the Designer is usually the first step you would take after creating a new project with the KAppWizard. You need to create your main view, the user interaction dialogs, and after finishing the graphical work, the code generation. This way, your project will contain all the usually considered difficult parts that normally take a long time to implement.

After that, the rest of your work is implementing the functionality in the generated code.

This chapter deals with how to use the Designer to create your project widgets, as well as what to do in case you see your widgets need alterations or addiciotns later in the development process.

You can switch to the Designer either by selecting Dialog Editor from the View menu, or with the corresponding toolbar icon. When you are finished, you can simply close the Designer window.

The following sections give you an overview of the Designer's interface, show you how to create a new dialog, and how to set up the properties of the child widgets that your dialog contains.

For more in depth information, you might want to have a look at the Designer tutorial from Trolltech, which can also be found offline in &kdevelop;'s documentation browser.

### Create a New Dialog With the Designer

If you want to create a new dialog, simply add a new Designer file.

On the menu bar choose File New. From the choices offered, choose Qt Designer file, and enter a name (for our examples, enter ``ktestdlg.ui``.)

The `.ui` file is where the Designer stores the information about the dialog.

The Designer will open, and ask you which kind of template you want to use for your class. Let's choose QDialog for our example.

The Designer presents you with an empty form, called Form1, and the Property Editor.

Your first step should be to give a human-readable name to our dialog, so we click on the form's background, and choose a suitable name for it by simply changing the name property from Form1 to something more suitable. For consistency reasons, you might want to call the class the same as the file it is stored in (or vice versa, depending on your point of view,) so we call it `KTestDlg`.

In order to become familiar with the Designer, we recommend reading the Designer handbook. It provides vital information about the usage of the Designer user interface, and the concepts behind signal and slot handling inside the Designer.

#### Excursion: how `.ui` Files Become Source

The Designer stores the dialog class in an XML format. So, how do we get a C++ file out of the Designer file?

The answer is easily!. &kdevelop; takes care of this! It adds the `.ui` to the `Makefile` which will then ensure that a header and source file are created at compile time. So, you can just use it, without really having to take care of the source.

Because the files are recreated on every compile, you cannot implement your functionality directly into the generated files, but must derive from it. Continue reading the next section to learn how this works.

### Using Your New Dialog Inside &kdevelop;

To continue with our example, we create a class inside &kdevelop; that will derive from the class created in Designer.

From the Project menu, choose New Class. Enter `KTest` as classname. Since we will derive from `KTestDlg`, enter `KTestDlg` in Baseclass.

As `QDialog` (the baseclass for our dialog) derives from `QWidget`, you will also need to enable the generate a QWidget child class checkbox.

This is all the information &kdevelop; requires. If you now choose OK, &kdevelop; will create two new files, `ktest.cpp` and `ktest.h`, which hold the `KTest` class that derives from `KTestDlg`. Note that the `#include` statement for `ktestdlg.h` has already been inserted by &kdevelop;. Now you can simply implement all your functions and use the class in your project.

#### Dialing With Virtual Slots

If you want to reimplement virtual slots, use the &RMB; mouse click context menu in the Classes browser, and choose Add slot, or use the Class Wizard button situated on the right of the method combobox in &kdevelop;'s toolbar. <-- Screenshot of icon -->

Do not call the underlying virtual function (&eg; `KTestDlg::slotCancel()`) in the overriding method!

## The Internal Debugger

The default setup for &kdevelop; is to use the internal debugger. You can change this in the Options menu, by selecting the KDevelop Setup menu item, and then the Debugger tab.

Click on Use external debugger if you wish to use a different debugger, and enter the name of the debugger to use. See your debuggers documentation on how to run it.

Selecting the internal debugger enables an additional set of options you can choose from:

Display static members

  Displaying static members makes `gdb` slower in producing data within &kde; and &Qt;. It may change the signature of the data which `QString` and friends rely on. However, if you need to debug into these values, then check this option.

Display mangled names

  When displaying the disassembled code, you can select to see the methods mangled names. However, non-mangled names are easier to read.

Try setting breakpoints on lib load

  This will try to set pending breakpoints on loading a library. If `gdb` hasn't seen a library that will be loaded via `dlopen`, then it will refuse to set a breakpoint in that code. We can get `gdb` to stop on a library load, and then try to set the pending breakpoints. See Shared Libraries and Breakpoints for more details and a gotcha relating to this behavior. If you are not using `dlopen` to open libs, leave this option off.

Enable floating toolbar

  This will allow you to use the floating toolbar to control the debugger, in addition to the normal menu and buttons. The toolbar is most useful for debugging GUI applications. For details, see The Floating Toolbar.

Enable separate terminal for application i/o

  This allows you to enter terminal input when your application contains terminal input code (&eg; `cin`, `fget`s, &etc;) If you use terminal input in your app, then tick this option, otherwise leave it off.

  This option is most useful if you use it in combination with the The Floating Toolbar, because this way, the terminal window won't be hidden behind the &kdevelop; window when you control the debugger.

### Using the Internal Debugger

If you choose the internal debugger, four tabs are addded to your tree and output view windows, and you will notice some changes to the Debug menu and the toolbar.

#### On the tree view window

Watch

  A tree view of the local variables at the point in the program you are currently stopped at. You can also see local variables in the function that called this function. The watch window allows you to see the value of global variables, or you may want to see only one local variable rather than the variable in a large list of local variables.

#### On the output view window

breakpoint

  A list of breakpoints set, and their current state.

framestack

  The calling stack.

disassemble

  A machine instruction view of the code showing the current instruction to be executed.

#### On the panel

Two new icons and two new combo boxes to control the debugger functions will become available as soon as you start the debugger.

#### In the Debug menu

When you start debugging, ten items to control the debugger will be enabled.

Run

  Continue the program from the current point.

Run to cursor

  Execute the program up to the current cursor position.

Step over

  Execute one line of code, stopping on the next line of code in the same source file. This will run any functions encountered until the above condition is met.

Step over i(nstruction

  Execute one machine instruction as above.

Step in

  Execute exactly one line of source code. This means you will step into the current function, if necessary.

Step in i(nstruction)

  Execute one machine instruction as above.

Step out

  Run to the end of the current stack frame (function.)

Viewers

  Allows a variety of views into the data. Currently implemented views are:

  - Memory address

  - Disassemble code

  - Current registers

  - Current libraries

Interrupt

  Stop the application executing.

Stop

  Stop the application executing and exit the debugger.

### Details

#### Breakpoints

Breakpoints can be set against source lines in a file (referred to as breakpoints,) or on variables in the source (referred to as watchpoints.) Both types of breakpoints can be set at any time, however watchpoints on local variables only have any meaning in the local scope of the variable. Watchpoints have more meaning when you are dealing with global variables.

#### Set/Unset Breakpoints

Setting breakpoints is a simple one click operation. Click on the icon border to the left of the text in the editor at the line you want the breakpoint. Click again on this line to unset the breakpoint.

#### Alternative Breakpoint Manipulation Via Menus

By right clicking on a breakpoint in the breakpoint list, or on a breakpoint in the editor icon border, you will get a menu of breakpoint options. This allows you to remove this breakpoint, clear all breakpoints, or edit the breakpoint.

#### Editing Breakpoints

Use the above menu to display the Edit Breakpoint dialog. This contains the following fields:

Conditional

  Enter the condition that must be met before `gdb` will interrupt the program execution.

Ignore Count

  How many times you want to the code to pass through this breakpoint before `gdb` interrupts the program execution.

Enable

  When enabled, `gdb` will break at this breakpoint. When disabled, `gdb` will not break here.

#### Clear all breakpoints

This menu entry removes all the breakpoints for this program. Use it carefully!

#### Set/Unset Watchpoints

In the VAR view, click with the &RMB; mouse button on a variable. The resulting context menu will allow you to set a watchpoint on the local variable. This functionality is limited to the scope that the local variable is in. As the variable goes out of scope, the program breaks, and the watchpoint is deleted.

This is known to be problematic, so use caution when setting watchpoints on local variables.

The watchpoint can also be set by a &RMB; mouse click on a previously entered watch variable, and selecting toggle watchpoint.

#### Set/Unset Watch Variables

-at the bottom of the Watch tab, you can enter the variable name you wish to see display in the watch list. Enter the variable name, and then press Enter or click the Add alongside the field. Right clicking on the watch variable in the tree view will bring up a menu where you can remove the variable from the list.

You can also enter a watch variable by &RMB; clicking on a variable name in the editor window. Choose watch: variable name from the resulting context menu.

#### Changing Variable Values

You can change a variable value in the Watch vew. If you have a variable `test`, then to set `test` to 5, type ``test`=5` in the watch field, and add it to the list. Note that `test` will then be set to 5 every time the program stops at a breakpoint, so once you have set the variable, you would normally want to remove the item from the watch view.

### The Floating Toolbar

The floating toolbar is a feature of the internal debugger, and it will greatly improve the comfort and efficiency when debugging GUI applications.

The toolbar is either on top of all windows displayed, or docked into the main toolbar with only a single icon showing.

When docked, you can run your code by clicking on the docked icon. The function this performs is the step over function.

Right clicking on the docked toolbar allows you to restore the whole toolbar, and optionally place focus on &kdevelop;.

Besides the functions available from the Debug menu, the floating toolbar offers two additional functions:

Set focus on KDevelop

  Set the focus back on &kdevelop;

Set focus on application

  This sets the focus on the window that had the focus when you pressed the Set focus on KDevelop button. This is a compromise, as it should set the focus on the application being debugged, but this is difficult to do. If anyone has a better solution than the current functionality, please let us know.

When `gdb` interrupts the program, usually because a breakpoint has been triggered, we highlight the Set focus on KDevelop button. We do not automatically switch focus to &kdevelop;, so you can view the application window at this point. Click the Set focus on KDevelop button to switch to &kdevelop;, or press another button on the toolbar to perform another function.

### Shared Libraries and Breakpoints

Setting breakpoints in shared libraries is a problem, because `gdb` will not accept such breakpoints in libraries that have not yet been opened, and will be opened at some future point with `dlopen`.

There is a reasonable solution, which is to have `gdb` tell us when a shared library has been opened. This is done by setting `stop on 1`.

This means that when a user sets a breakpoint, we flag this breakpoint as pending, try to set the breakpoint, and if `gdb` says it succeeded, then we flag it as active. If `gdb` is not successful, then we leave the breakpoint as pending. The next instruction will always be `continue`.

This is known as lazy breakpoints.

This can however lead to a problem when you use the `step over` command and step over the code that would load the library. This will trigger a break on libary load, and normally the debugger would do a `continue` (&ie; run to the next breakpoint or the end of the code.) The user, however, is expecting the program to stop at the next line, so in this situation we do not continue, but leave it at that point (which will be somewhere inside a `dlopen` command. This can be disconcerting, but it cannot be helped.

## CVS Integration

Among it's many features, &kdevelop; also handles managing your project via CVS repositories.

The goal behind CVS (Concurrent Version Control) is to enable groups of developers to work on the same source-tree independently, and to merge changes into the repository.

Usually, the repository is located on a server, and the initial repository contains the base set of files that the project includes. Directories and files are then added to or removed from the CVS by the developers.

Locally, the developer works on his own copy of the CVS tree. He writes his changes into his own copy of the files, and then tests locally. If the project still works, at least to the point where incomplete sources don't prevent other developers from working, then he commits his changes to the main CVS repository. The other developers will then receive the changes the next time they update their own local copy of the CVS tree.

### Creating a Repository

When creating a new project with &kdevelop;, you can directly import the project as a CVS module. To enable this, you must have CVS installed. CVS is installed by default on a great many distributions, but if not you should find it on your original &cdrom;s.

To create an initial repository in &kdevelop;, you must have write access to the CVS root directory. Also, the CVS root directory must be on the same machine as you are running &kdevelop; on.

If you want to have the repository on a dedicated server, either contact this server's system administrator to create the project with &kdevelop; on the server machine, or take the following steps:

1. Create your project locally.

2. Import the project source tree as a module on the CVS server.

3. Delete the local project source tree.

4. Check out the project source tree from CVS.

5. After loading the project file from the CVS copy you checked out, enable CVS support in the Project Options dialog, as described below,

On the third page of the KAppWizard, labelled VCS support, choose CVS. The rest of the fields on the page will be enabled, and you should fill them in as appropriate.

The options available to you are:

VCS Location

  This is the CVS root directory where the project source tree will be imported to, and where `commit`s, `checkout`s and `update`s take place.

Repository in CVS

  This is the module name for your project. This is the same as the project directory, so you cannot change it.

Vendor Tag

  This is the tag for the entire branch.

Log Message

  This is for the first log message entry of the new module. When adding or committing to the repository, you will be asked for a log message each time, to document your changes to the repository source tree. The log message you enter here is used only for the initial import.

Release Tag

  This specifies the tag under which your project source tree can be found. You can create several different projects with the same module name in the CVS root, so long as they differ from tag. This enables you to have separate development teams working on different versions of your application. As an example, &kde; is developed mainly in the HEAD (the default) branch, and a branch is tagged for each release: KDE_1_1_2_RELEASE, KDE_2_0_RELEASE, and so on.

After creating your project with the KAppWizard, the CVS support option is already set for your project.

### Enabling CVS Support

As CVS support is most often only needed if you will be working on your project in conjunction with other developers, perhaps as a professional programmer or in a large open source project such as &kde;, CVS support is optional. To enable the CVS commands, open the Project Options diialog and change the option for Version Control to CVS.

### Using CVS Commands

Once CVS support is enabled, the following commands are available from the &RMB; click context menu in the Files and Groups tree view panes:

#### Over a file not included in the repository:

Add to Repository

  Adds the file to the repository. The file is set up to be added, and will be introduced to the repository on the next `commit` command that includes the directory it is located in.

#### Over a file included in the repository

Update

  Update the selected file with the CVS version.

Commit

  Commit the selected file to the CVS repository.

Remove from Repository

  Remove the selected file from the repository.

#### Over a folder

Add

  Add the entire folder to the repository.

Remove

  Remove the folder from the repository.

Update

  Update the folder recursively to be in sync with the repository.

Commit

  Commit any changes recursively to the repository.

The CVS commands all require a working network connection to the CVS server. When invoking a command, you will be shown a dialog with the command sent to the CVS server, and the retrieved output. This lets you monitor the success of the command.

As the CVS commands of &kdevelop; only work with the `cvs` and it's commandline options, you should have no trouble to use the CVS features.

## General Configuration

This chapter describes how you can set your individual preferences as to how &kdevelop; works. All settings addressed below can be found through the appropriate entries in the Options menu.

### Configuring the Tools Menu

As &kdevelop; supports the use of third-party programs within it's user interface, you are able to configure any program that suits your needs to be added to the Tools menu.

To add an application to the Tools menu, select Tools from the Options menu.

The resulting dialog allows you to specify new entries, by adding the executable name of the new application in the Executable field, or browsing to it with the folder icon. Add the text you want it to appear in the menu as to the Menu Text field, using a & character to mark the letter you want to be the menu accelerator. Take care not to duplicate accelerators within the menu. Finally, you can add any commandline arguments the application requires to the Arguments field.

Select Add to add your application to the menu. You can rearrange the menu with the Move Up and Move Down buttons, and delete any unnecessary entries with Delete. Choose OK to save your changes and close the dialog if you are happy with it, and Cancel to close the dialog without saving your changes.

Newly added applications will be available immediately in the Tools menu.

### File Viewer Options

The Groups viewer can be configured entirely through context menus.

As it's intention is to separate files in a logical manner, to keep an overview of complex projects, one of the most used customizations is to create file groups.

You can set up new groups and other operations, by opening the context menu with a &RMB; click over the project icon, which is displayed as the root of the tree, or the slightly different context menu available from a &RMB; click over a group folder.

The menu offers:

#### The Project Icon Context Menu

New File

  Open the New File dialog. This is the equivalent of choosing the menu item File New.

New Class

  Opens the class generator, to create a new class. This is the equivalent of the menu item Project New Class.

New Group

  Opens a dialog to create a new group. There, set the group name and the file filter for the project files that will be displayed in this group.

Show relative path

  Display the files with their path, starting from the main project directory. If this is unchecked, only the file name is shown.

#### The Group Folder Context Menu

New Group

  Opens a dialog to create a new group. There, set the group name and the file filter for the project files that will be displayed in this group.

Remove Group

  Removes the group from the Groups pane.

Properties

  Opens the properties of the group. There you can edit the file filters, through a list of wildcards separated by commas.

### KDevelop Setup

The general configuration for &kdevelop; is reached through the Options menu entry KDevelop Setup.

The dialog contains several sections:

- General

- Keys

- Documentation

- Debugger

- Path

### General

Select Make-Command

enable Autosave

Select Autosave time-interval

enable Autoswitch

use Class View as default

Startup Logo

Tip of the Day

Load last project

### Keys

### Documentation

To set up the documentation browser to work correctly, &kdevelop; needs some information about where the HTML documentation is stored on the system.

The Documentation Path properties dialog needs the path of the &Qt; online documentation in HTML as well as the path to the &kde; Library documentation.

Usually, the &Qt; Documentation is placed in the same directory where &Qt; is installed; &eg; if &Qt; resides in `/usr/local/qt`, the path you have to enter is `/usr/local/qt/html`.

Qt-Library-Doc:

  The path to your &Qt; documentation.

  Usually, the &Qt; Documentation is placed in the same directory where &Qt; is installed; &eg; if &Qt; resides in `/usr/local/qt`, the path you have to enter is `/usr/local/qt/html`.

KDE-Libraries-Doc

  The path to your &kde; documentation.

  For the &kde; Documentation, you have to set the directory to the root of the documentation, assumed all &kde; Libs documentation resides in the same directory. Both path's can be selected by pressing the appropriate browse buttons, displaying a path selection dialog. If your system doesn't contain the documentation for the &kde; libs, you should first enter the next configuration section, Update &kde; Documentation. This will create the documentation to a path of your choice, also setting the &kde; Library Doc path automatically.

Update KDE-Documentation:

  For those users who don't have a recent documentation of the &kde; libraries, especially the documentation for the files installed on the system, the Update KDE-Documentation dialog creates a new one or updates existing documentations. This function requires your system to have `KDoc` and `qt2kdoc` installed, included in the KDE-SDK package. First of, you have to set up the path to your recent kdelibs sources, which is not the include path for &kde,! Just enter the path to the sources, like: `/home/rnolden/kdelibs-2.1/`.

  You can choose from three different installation modes:

  Delete old Documentation and install to recent Documentation-path:

    This assumes you already have documentation installed, and it is placed in the path you entered in the Documentation path dialog. This will delete all documentation and install the newly generated documentation in it's place.

  Delete old Documentation and install to new Documentation-path

    This will result in deleting the old documentation, and installing the new documentation to a different place.

  Leave old Documentation untouched and install to new Documentation path

    This is the recommended choice if you have two different generations of &kde; libs installed, and would like to have the documentation for both available, or for your first time generating documentation.

  The new KDE Libs Documentation path must to be set for option 2 and 3 of the installation mode. This is also recommended for users who generate a new documentation from scratch.

  After you press the OK button, &kdevelop; will create a subdirectory `KDoc-reference` in the documentation path, containing the `KDoc` reference files. First the &Qt; library documentation classes will be indexed, to connect the &Qt; documentation with the documentation that will be generated for &kde; libs, so it is important that you have already set up the &Qt; documentation path. This process is done by the `qt2kdoc` script. Finally the &kde; libs will be indexed, and the documentation will be built with cross references, to give you the most functionality.

  When using `KDoc` 2, you can add a set of documentation for the the libraries in the &kde;base and &koffice; package. To do this, create the &kde; Libs documentation as described above. Then reopen the dialog and choose the path to the `kdoc.rules` file in the kdebase package and the koffice packages respectively, which is located in kdebase in the root directory of the sources, in KOffice in `koffice/lib`. Select option 3 (Leave old Documentation untouched) and leave the output path below that option as it is. This will keep the kdelibs documentation and generate the kdebase-libraries (resp. the koffice-libraries) documentation to the same location with cross-references to the kdelibs documentation additionally. After generating the documentation the libraries are available in the documentation tree automatically. For further &kde; packages coming with additional libraries you should look for the `kdoc.rules` file to generate additional documentation as with the &kde; Base and KOffice packages.

Create Search Database

  The Create Search Database dialog, accessed via the create button, allows the programmer to create a database to search for a keyword interactively. To create and use the documentation search function, you must have the program `glimpse` 4.0 or ht://Dig installed. Preset are the options to index the given &kde; Library documentation as well as the &Qt; Documentation, assuming the path to the documentation files were set in the Documentation Path dialog of the options- menu. Additionally, the index can include directories the user can set up himself by the additional directories to index field. After setting a path to an additional directory, the Add button must be pushed to set the path. A path once set can be removed from the index by selecting the path in the path field and pushing Remove. Furthermore, the user is offered three different modes for the index size: tiny, small and medium. The higher the index size, the more the index files will grow. On the other hand, a search in a bigger search-database will be faster and more successful, so we suggest choosing a medium size.

Create also KDOC-reference of your project

  This option allows you to create a cross-reference file for your project when generating the API documentation with `KDoc`. The cross-reference file will be placed in the references directory and make your project available in the documentation tree. If you donīt have write access to the directory containing the reference files you have to uncheck this option to generate the API documentation without errors.

### Debugger

Already covered in detail in

### Paths

Qt 2.x directory:

KDE 2.x directory:

Project Path:

## Other Useful Things to Know

### Bug Reporting

Like most large applications, &kdevelop; is a work in progress. Unfortunately, works in progress sometimes experience bugs.

If you experience a bug while using &kdevelop;, you have the option to send the &kdevelop; development team a bug report either in your email-client or with the bug report dialog. All bug-reports are collected on the &kdevelop; web site and can be reviewed on http://bugs.kde.org//db/pa/lkdevelop.html.

To send bug reports, please use the email address submit@bugs.kde.org. If you want to use &kdevelop; for direct bug-reporting, choose Bug Report from the Help menu. You will be presented the report dialog that lets you enter all necessary information about the bug you found. After pressing OK, the dialog's contents is sent to the above address automatically.

## Questions and Answer

### More Information

I have a question that is not addressed in the FAQ file, nor in the manuals of &kdevelop;. Where should I turn?

You can find help on any and all aspects of using &kdevelop; by subscribing to the &kdevelop; mailing list at kdevelop-request@barney.cs.uni-potsdam.de. Send an email to that address with an empty header and ``subscribe` youremailaddress` as the contents of the body.

As a member of the list, you can participate in discussions. All questions should be sent there, and will be addressed there as well. The &kdevelop; developers are on the list, as well as experienced users, and discussions on this list are used to keep the FAQ updated with the issues that people are facing.

The &kdevelop; home page at http://www.kdevelop.org/ also contains a mailing list archive that allows you to browse and search through previous postings to the list. You should probably check there first, as most common problems have already been addressed there by the developers or by other users.

### Library and System Problems

I get an error saying

Wrong JPEG library version: library is 61, caller expects 62

, so what's wrong?

There are two ways to solve this issue.

1. When the kdelis are installed, header files for the jpeg libraries are also installed, and these are version 61. Many distributions use the version 62 libraries. To fix this, remove `jpeglib.h` from `$`KDEDIR`/include`. The pukka include file for version 62 should then be picked up.

   There is always the small possibility it's the other way around, and you need to remove your distribution's copy of the header. In any case, ensure you have only one copy of `jpeglib.h`, and that it is the same version as the library. The `locate` command is useful to verify that there is only one copy of the files in question.

2. Recompile kdesupport without the jpeg library. (``./configure` `––with-libjpeg` `with-libgif``)

I get an automake error saying

aclocal.m4: 2709: `AM_PROG_INSTALL' is obsolete; use `AC_PROG_INSTALL'

. What shall I do?

If you are seeing errors like this:

    make[2]: Entering directory `/usr/local/src/kdevelop-0.3/po'
    cd .. && automake --gnu --include-deps po/Makefile
    aclocal.m4: 2709: `AM_PROG_INSTALL' is obsolete; use `AC_PROG_INSTALL'
    make[2]: *** [Makefile.in] Error 1

The workaround for `automake` 1.4 through `automake` 2.13 users is to run `aclocal` manually, and the application will then compile.

What must I do if configure said that I need giflib23

Try another snapshot of the kdesupport package, or check that you don't have a conflicting copy of giflib installed. If you do, remove it.

How can I convert a &kdevelop; 0.2 project to a 0.3 one?

Change the AC_OUTPUt line in the `configure.in` to a one line version.

for example, from the old version:

    AC_OUTPUT(Makefile \
    kdevelop/kwrite/Makefile \
    kdevelop/templates/Makefile
    )

change this to:

    AC_OUTPUT(Makefile kdevelop/kwrite/Makefile kdevelop/templates/Makefile)

`configure` complains about not being able to compile a small &kde; application. Examining `config.log` reveals that it can't find libXext.

Install the xdevel package (or your distribution's equivalent)

### Usage Questions

&kdevelop; won't let me use the delete key, or backspace to delete selected text.

Go to Options Editor... and make sure that Delete on Input is enabled. Your Backspace and Delete keys will now work.

If I add files to my project, will they be automatically included and compiled?

Yes, they are included in the `Makefile.am`'s and if you do a Rebuild All, then `./configure` will update the `Makefile`s and your files will now be included.

If I remove a file, I get some weird linker messages. What's wrong with my project?

If the removed file is a header file, one that is automatically processed by automoc (running the &Qt; Meta Object Compiler automatically on all headers), youre removed header is still present as a moc-genertaed `*.moc.cpp` file, and is still compiled. Remove the appropriate `*.moc.cpp` and rebuild the project.

I'm developing an application where I need to set `-D` options to the preprocessor. If I add these in &kdevelop; to my project, everything is ok, but when I distribute my package, the `-D` options set in &kdevelop; are not used. What do I have to do to make this work?

Edit the file `configure.in`, in your top level source directory. Enter somewhere near the beginning `CXXFLAGS=$(CXXFLAGS) " -DYOURDEFINE" AC_SUBST(CXXFLAGS)`.

I don't have any &kde; widgets in the &Qt; Designer. How do I add them?

You will have to recompile &Qt, with the `-kde` enabled. That is, ``./configure` `-kde` ...`, in addition to your usual configure options. Rembember to set $`QTDIR` and $`KDEDIR` to the appropriate values. After doing this, you will have a new KDE option in the Tools menu of Designer.

I use &RedHat; &Linux; with &kdevelop; and tried to recompile the &Qt; library with `-kde` in order to use the designer with &kde; widget support but during configure it says that $`KDEDIR` does not contain a valid &kde; installation?

&RedHat; uses non-standard directory setting with &kde;. The normal case would be that the libs are in `$`KDEDIR`kdedir/lib`, binaries in `$`KDEDIR`/bin` and includes in `$`KDEDIR`/include`. &RedHat; uses `/usr` as $`KDEDIR` but`$`KDEDIR`/include/kde` as directory for header files. Therefore configure from &Qt; fails to detect the correct directories. It searches for `dcopserver` in the binaries folder and the header files in their folder. So if you choose $`KDEDIR` to be `/usr`, configure can't find the includes. A possible solution for this is to create a `/usr/local/kde` directory and set symlinks to `/usr/bin` and `/usr/include/kde` in this pseudo kde dir. Then ``export` `KDEDIR`=`/usr/local/kde`` and do the ``./configure` `-kde``. After compiling &Qt; you have the &kde; entries in the Tools menu of the &Qt; designer.

Is there any HOWTO documentation available on working with &Qt; Designer made dialogs?

Yes, there is a great tutorial on http://women.kde.org/docs/tut_kdevelop/.

I have installed htdig but there is no `htsearch` available. What's up?

On some systems (notably &RedHat;), the `htsearch` executable is placed in the `/cgi-bin` of apache. You can create symlinks in `/usr/bin/` or simply add this to your path in your shell `rc` file.

I have `htdig`, `htmerge` and `htsearch` available but I get an error message thet the config file of `htdig` could not be found or is invalid, so what can I do?

Read `README.htdig` in the source directory tree and create an `htdig.conf` file. Then copy it to `$`KDEDIR`/share/apps/kdevelop/tools`. Now create your search index with the KDevelop Setup menu item.

## Credits and Licenses

&kdevelop;

Copyright the &kdevelop; team, 1999, 2000, 2001

Sandy Meier smeier@kdevelop.de

  Maintainer, development coordinator, and homepage provider. Main development of frame structure, &IDE; look'n feel and project management.

Stefan Heidrich sheidric@rz.uni-potsdam.de

  Main development of KAppWizard and printing functionality.

Ralf Nolden rnolden@kdevelop.de

  Main development of &kdevelop; <--> Dialog Editor interface, configuration functionality, online help and handbooks.

Jonas Nordin jonas.nordin@cenacle.se

  Main development of the Class viewer and Class parser.

Pascal Krahmer pascal@beast.de

  Main development of the Dialog Editor.

Bernd Gehrmann bernd@physik.hu-berlin.de

  Main development of the Grep Dialog, CVS integration, and the new Documentation tree.

&underFDL; &underGPL;