<!DOCTYPE book PUBLIC  "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
  <!ENTITY kappname "&kdevelop;" -- this only *seems* redundant -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE" -- change language only here -->
  <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Documentation V1.0//EN">
  <!ENTITY IDE "<acronym>IDE</acronym>">
  <!ENTITY kdevelop "<application>KDevelop</application>">
  <!ENTITY kiconedit "<application>KIconEdit</application>">
  %ents;
]>

<book lang="&language;">

<bookinfo>

<title>The &kdevelop; User Manual</title>

<subtitle>The Reference Guide to the &kdevelop; Integrated Development
Environment for &UNIX; Systems,</subtitle>

<authorgroup>
<author>
<firstname>Ralf</firstname>
<surname>Nolden</surname>
<affiliation>
<address><email>Ralf.Nolden@post.rwth-aachen.de</email></address>
</affiliation>
</author>

</authorgroup>

<copyright>
<year>1999</year><year>2000</year><year>2001</year>
<holder>Ralf Nolden</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>18/1/2000</date>
<releaseinfo>1.4.0</releaseinfo>

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

<keywordset>
<keyword>KDE</keyword>
<keyword>kdevelop</keyword>
<keyword>development</keyword>
<keyword>IDE</keyword>
<keyword>programming</keyword>
</keywordset>

</bookinfo>
  
<chapter id="introduction">
<title>Introduction</title>

<para>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 <acronym>GNU</acronym> 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.</para>

<para>The <indexterm><primary>&kde;</primary></indexterm> &kde; project tries to
close this gap by providing an easy to use desktop and the companion libraries
to extend the variety of available
<indexterm><primary>&GUI;</primary></indexterm> &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.</para>

<para>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 <application>make</application> and
the <acronym>GNU</acronym> C++ Compiler
<indexterm><primary>Compiler</primary></indexterm> and makes them an invisible,
integrated part of the development process.</para>

<para>&kdevelop; manages:</para>

<itemizedlist>
<listitem>
<para>All development tools needed for C++ programming, including the Compiler,
Linker, <application>automake</application> and
<application>autoconf</application>. </para>
</listitem>
<listitem>
<para>KAppWizard, which generates complete, ready-to-go sample
applications.</para>
</listitem>
<listitem>
<para>Classgenerator, for creating new
<indexterm><primary>classes</primary></indexterm> classes and integrating them
into the current project.</para>
</listitem>
<listitem>
<para>File management for sources, headers, documentation &etc;  to be included
in the project.</para>
</listitem>
<listitem>
<para>The creation of User Handbooks written with <indexterm>
<primary><acronym>SGML</acronym></primary> </indexterm> <acronym>SGML</acronym>
and the automatic generation of
<indexterm><primary><acronym>HTML</acronym></primary> </indexterm>
<acronym>HTML</acronym> with the &kde; look and feel</para>
</listitem>
<listitem>
<para>Automatic <acronym>HTML</acronym>-based <acronym>API</acronym>
documentation for your project's classes, with cross-references to the libraries
used.</para>
</listitem>
<listitem>
<para>Internationalization support for your application, allowing translators to
easily add their target language to a project.</para>
</listitem>
<listitem>
<para>Creation of user interfaces through interaction with TrollTech's &Qt;
<application>Designer</application></para>
</listitem>
<listitem>
<para>Managing of your project via <acronym>CVS</acronym> by providing an easy
to use front end for most functions.</para>
</listitem>
<listitem>
<para>Debugging your application with the debugger of your choice - either the
internal &kdevelop; debugger, or use <application>ddd</application> or
<application>kdbg</application></para>
</listitem>
<listitem>
<para>Editing of project specific <indexterm> <primary>pixmaps</primary>
</indexterm> pixmaps with &kiconedit;</para>
</listitem>
<listitem>
<para>The inclusion of any other program you are accustomed to using for
development, by simply adding it to the <guimenu>Tools</guimenu>, according to
your individual needs.</para>
</listitem>
</itemizedlist>

<para>&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.</para>

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

<para>The <interface>Class viewer</interface> 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;</para>

</chapter>

<chapter id="overview-of-this-handbook">
<title>About this Handbook</title>

<para>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 <!-- Link --> <!--
here to programming/index.html --> 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
<ulink url="http://www.andamooka.org">http://www.andamooka.org</ulink>.</para>

<para>This User Guide is broken up into the following parts:</para>

<variablelist>
<varlistentry>
<term>Chapter <xref linkend="installation"></term>
<listitem>
<para>Covers the system requirements, installation, and setting up of
&kdevelop;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="programs"></term>
<listitem>
<para>Tells you how programs are created with standard <acronym>GNU</acronym>
development tools, and how they are built.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="development-with-kdevelop"></term>
<listitem>
<para>Takes you on a short tour describing the main functionality of the
environment.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="overview"></term>
<listitem>
<para>Explains the menus and dialogs, as well as the keyboard shortcuts.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="help-system"></term>
<listitem>
<para>Shows how to use the built-in documentation browser and additional help
functions.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="working-in-the-editor"></term>
<listitem>
<para>Explains the features and functions available to you when working with
file management and in the editor.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="projects"></term>
<listitem>
<para>Describes the creation and maintenance of software projects.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="build-settings"></term>
<listitem>
<para>Contains a reference on how to set compiler and linker flags, and other
project settings.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="class-browser"></term>
<listitem>
<para>Tells you how to make user of &kdevelop;'s powerful Class
Browser</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="qt-designer"></term>
<listitem>
<para>Features how to use &Qt; <application>Designer</application> while working
on your project and how &kdevelop; seamlessly cooperates with
<application>Designer</application>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="internal-debugger"></term>
<listitem>
<para>Gives an overview of the debugging setup, and discusses the use of the
internal debugger.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="cvs-integration"></term>
<listitem>
<para>Tells you how to use the revision control systems <acronym>CVS</acronym>
and <acronym>RCS</acronym> with your &kdevelop; project.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="general-configuration"></term>
<listitem>
<para>Shows you how to set up overall preferences for customizing &kdevelop; to
your own needs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chapter <xref linkend="q-and-a"></term>
<listitem>
<para>Covers questions you might have about using &kdevelop; under different
flavours of &UNIX; and other general solutions to common problems.</para>
</listitem>
</varlistentry>
</variablelist>

<para>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.</para>

<sect1 id="about-kdevelop">
<title>About the &kdevelop; project</title>

<para>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.</para>

<para>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.</para>

<para>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.</para>

<para>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 <acronym>API</acronym> and the
latest technologies &kde; 2.0 offers. Since the release of &Qt; 2.2.0 brought
&Qt;īs <application>Designer</application> for constructing user interfaces
which also supports &kde; widgets, the <application>Designer</application> is
about to replace &kdevelop;'s own dialog editor as it offers dynamic layout
management and directly connecting widgets. To support using the
<application>Designer</application> 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.</para>

<para>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.</para>

<para>Since then John Birch and I decided that we really would like to have a
&kde; 2.x version of our <quote>baby</quote>, &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
<acronym>API</acronym> on a free system to develop software for.</para>

</sect1>

<sect1 id="printed-versions">
<title>Printed Versions</title>

<para>A printed version of the complete &kdevelop; Documentation is available as
the book titled <citetitle>Developing Applications for Linux: KDE
Edition</citetitle>, which can be ordered either online from the &kdevelop;
website at <ulink url="http://www.kdevelop.org">http://www.kdevelop.org</ulink>
or at <ulink url="http://www.opendocs.org">http://www.opendocs.org</ulink>. 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;.</para>

<para>Printable versions of the &kdevelop; documentation can be obtained from
the &kdevelop; website at <ulink
url="http://www.kdevelop.org">http://www.kdevelop.org</ulink> in &DVI;,
&PostScript; and <acronym>PDF</acronym> forat, in both A4 and Letter
size.</para>

</sect1>

</chapter>

<chapter id="installation">
<title>Installation of &kdevelop;</title>

<sect1 id="obtaining">
<title>How to obtain &kdevelop;</title>

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

<para>We're also offering snapshots of the &kdevelop; <acronym>CVS</acronym>
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 <application>KDoc</application> and
<application>KDbg</application>.</para>

<para>If you're experiencing problems with compiling or using &kdevelop;, please
read the <link linkend="q-and-a">Questions and Answers</link> section of this
handbook or the &FAQ; file included with the &kdevelop; package.</para>

<para>If your problem is not addressed, please subscribe to the &kdevelop;
mailing list at <email>kdevelop-request@barney.cs.uni-potsdam.de</email> by
sending a mail with an empty header and <userinput>subscribe
youremailaddress</userinput> 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.</para>

<para>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 <interface>Messages</interface> window.</para>

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>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.</para>

<variablelist>
<varlistentry>
<term>Required</term>
<listitem>
<itemizedlist>
<listitem>
<para><application>g++</application> 2.7.2/g++ 2.8.1/egcs 1.1 (or compatible),
available at <ulink url="http://www.gnu.org">http://www.gnu.org</ulink>.</para>
</listitem>
<listitem>
<para><application>Perl</application> 5.004, available at <ulink
url="http://www.perl.org">http://www.perl.org</ulink></para>
</listitem>
<listitem>
<para><application>autoconf</application> 2.13, also available from <ulink
url="http://www.gnu.org">http://www.gnu.org</ulink></para>
</listitem>
<listitem>
<para><application>automake</application> 1.4, also from <ulink
url="http://www.gnu.org">http://www.gnu.org</ulink></para>
</listitem>
<listitem>
<para><application>flex</application> 2.5.4</para>
</listitem>
<listitem>
<para><acronym>GNU</acronym> <application>gettext</application> available at <ulink
url="http://www.gnu.org">http://www.gnu.org</ulink></para>
</listitem>
<listitem>
<para>&Qt; 2.2.x, available from <ulink
url="http://www.trolltech.no">http://www.trolltech.no</ulink></para>
</listitem>
<listitem>
<para>&kde; 2.1, available from <ulink url="http://www.kde.org">
http://www.kde.org</ulink></para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>Optional</term>
<listitem>
<itemizedlist>
<listitem>
<para><application>enscript</application> for printing support.</para>
</listitem>
<listitem>
<para><application>ghostview</application> or &kghostview for printing
review</para>
</listitem>
<listitem>
<para><application>glimpse</application> 4.0 for the search index, available at 
<ulink url="http://glimpse.cs.arizona.edu">http://glimpse.cs.arizona.edu</ulink>
</para>
</listitem>
<listitem>
<para>sgmltools 1.0, available at <ulink url="http://www.sgmltools.org">
http://www.sgmltools.org</ulink></para>
</listitem>
<listitem>
<para>&kde;-<acronym>SDK</acronym> (the <emphasis>K</emphasis>DE
<emphasis>S</emphasis>oftware <emphasis>D</emphasis>evelopment
<emphasis>K</emphasis>it), which includes <application>KDoc</application>,
<application>KTranslator</application> and <application>KBabel</application>,
(available at <ulink
url="http://developer.kde.org">http://developer.kde.org</ulink>.</para>
</listitem>
<listitem>
<para><application>KDbg</application>, available from <ulink
url="http://members.telecom.at/~johsixt/kdbg.html">
http://members.telecom.at/~johsixt/kdbg.html</ulink></para>
</listitem>
<listitem>
<para>&kiconedit;, available at <ulink url="http://www.kde.org">
http://www.kde.org</ulink></para>
</listitem>
<listitem>
<para>&Qt; <application>Designer</application> and <acronym>uic</acronym>, which
come with &Qt; 2.2.x</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>

<para>&kdevelop; was tested with SuSE &Linux; as well as on several other
platforms.</para>

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

</sect1>

<sect1 id="installing-documentation">
<title>Documentation</title>

<para>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
<application>KDoc</application>, included in the
&kde;-<acronym>SDK</acronym></para>

<para>We also offer from our homepage at <ulink url="http://www.kdevelop.org">
http://www.kdevelop.org</ulink> 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 <systemitem><!-- class="username"
-->root</systemitem> into your $<envar>KDEDIR</envar> and untar it with
<userinput><command>tar</command> <option>zxvf</option>
<filename>c_c++_reference.tar.gz</filename></userinput>, 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.</para>

</sect1>

<sect1 id="compilation-and-installation">
<title>Compilation and Installation</title>

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

<screen><prompt>&percnt;</prompt> <userinput><command>./configure</command></userinput>
<prompt>&percnt;</prompt> <userinput><command>make</command></userinput>

(as <systemitem><!-- LW: class="username" -->root</systemitem>)

<prompt>&percnt;</prompt> <userinput><command>make</command> <option>install</option></userinput>
</screen>

<para>Since &kdevelop; uses <application>autoconf</application> you should have
not trouble compiling it.</para>

<para>In order to compile the &kdevelop; <acronym>CVS</acronym> snapshot, type
the following: </para>

<screen><prompt>&percnt;</prompt> <userinput><command>make</command> <option>-f</option> <filename>Makefile.cvs</filename></userinput>
<prompt>&percnt;</prompt> <userinput><command>./configure</command></userinput>
<prompt>&percnt;</prompt> <userinput><command>make</command></userinput>

(as <systemitem><!-- class="username"-->root</systemitem>)

<prompt>&percnt;</prompt> <userinput><command>make</command> <option>install</option></userinput>
</screen>

<para>If your system's make command is <application>gmake</application>, type
<userinput><command>gmake</command></userinput> instead of
<userinput><command>make</command></userinput></para>

</sect1>

<sect1 id="starting-kdevelop">
<title>Starting &kdevelop;</title>

<para>If you use &kde; as your window manager, &kdevelop; can be started by
choosing <menuchoice><guimenu>K</guimenu> <guisubmenu>Development</guisubmenu>
<guimenuitem>KDevelop 1.4</guimenuitem></menuchoice>.  As &kdevelop; supports
&kde; mime types, you can also start a &kdevelop, project file (<literal
role="extension">*.kdevprj</literal>, displayed with the &kdevelop; project
icon) in the &kde; file manager, &konqueror;.  This will start &kdevelop; and
load the project.</para>

<para>Under other window managers, open a console and type:</para>

<screen><prompt>&percnt;</prompt> <userinput><command>kdevelop</command> <filename><replaceable>yourProject</replaceable>.kdevprj</filename></userinput>
</screen>

<para>Under each user account, &kdevelop; will invoke the <link
linkend="installation-program"> automatic installation process</link> 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:</para>

<!-- LW: can't put two dashes in sgml, it is a comment starter.  This can be -->
<!-- changed back when we go to XML -->

<screen><prompt>&percnt;</prompt> <userinput><command>kdevelop</command> <option>&#45;&#45;setup</option></userinput>
</screen>

<para>or, when using &kde;, by choosing <menuchoice><guimenu>K</guimenu>
<guisubmenu>Development</guisubmenu> <guimenuitem>KDevelop
Setup</guimenuitem></menuchoice></para>

</sect1>

<sect1 id="installation-program">
<title>The Installation Program</title>

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

<para>The Installation dialog's buttons execute the following actions:</para>

<variablelist>
<varlistentry>
<term><guibutton>Help</guibutton></term>
<listitem>
<para>Will open the &khelpcenter; program</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Proceed</guibutton></term>
<listitem>
<para>This stats the installation process and executes following actions:</para>
<itemizedlist>
<listitem>
<para>Checking for <application>make</application> or
<application>gmake</application>, <application>autoconf</application>,
<application>autoheader</application>, <application>automake</application> and
<application>perl</application> for the creation and compilation of new
applications generated by &kdevelop;. If <application>gmake</application> is
installed, the <command>make</command> command will be set to automatically
use <application>gmake</application>.  Other commandline options to your
<application>make</application> program can be set in the
<guilabel>Setup</guilabel> dialog which you can later access through the
<guimenu>Options</guimenu> menu.</para>
</listitem>
<listitem>
<para>Checking for <application>KDoc</application> and
<application>glimpse</application>.  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.</para>
</listitem>
<listitem>
<para>Checking for <application>enscript</application> 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.</para>
</listitem>
<listitem>
<para>Checking for <application>KDbg</application>, &kiconedit; and
<application>KTranslator</application>.  We encourage you to install these
programs, as they assist in creating complete &kde; applications.  Note that
<application>KDbg</application> 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
<application>KDbg</application>, &kiconedit;, and
<application>KTranslator</application> are then configured to be available in
the <guimenu>Tools</guimenu> menu of the &kdevelop; menu bar, if they are found.
Other tools can be added to the <guimenu>Tools</guimenu> menu by selecting
<guimenuitem>Tools...</guimenuitem> in the <guimenu>Options</guimenu>
menu.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>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
<filename class="directory">qt/html</filename>  After you have done this, the
installation can continue with the selection of <guibutton>Proceed</guibutton>
again.</para>
</listitem>
<listitem>
<para>If <application>KDoc</application> 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 <ulink url="http://www.kde.org">http://www.kde.org</ulink> and
untar the sources on your system.  If you wish to use the documentation provided
by <ulink url="http://developer.kde.org">http://developer.kde.org</ulink>,
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.</para>
<para>The <guilabel>Update KDE Library documentation</guilabel> dialog is set
up to use a default path for the location of the documentation, in <filename
class="directory">$HOME/.kde/share/apps/kdevelop/KDE-Documentation
</filename>.  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
<guibutton>OK</guibutton>.  As an example, if you got the
<filename>kdelibs.tar.gz</filename> package from <ulink
url="http://www.kde.org">http://www.kde.org</ulink> and downloaded it to your
home directory, you should open a console or terminal, and enter
<userinput><command>tar</command> <option>zxvf</option>
<filename>kdelibs.tar.gz</filename></userinput>.  This will untar the sources
into a directory at <filename
class="directory">$HOME/kdelibs</filename>, which then contains
the sources for each library in a subdirectory.  For kdecore on my machine, for
example, this would now be <filename
class="directory">/home/rnolden/kdelibs/kdecore</filename>.  Now the path you
have to ender for the &kde; library documentation dialog would be the path for
all the libraries, in this example, <filename
class="directory">/home/rnolden/kdelibs</filename>.  After pressing the
<guibutton>OK</guibutton> button, a message in the installation window shows
that the documentation is in progress, and you should wait for the next message.</para>
<note>
<para>On a multi user system, or systems with disk quotats for user accounts,
the installation of a complete set of <acronym>HTML</acronym> 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 <filename
class="directory">$KDEDIR/share/apps/kdevelop/KDE-Documentation</filename>.This path can then be set up later by each user in their &kdevelop; setup
dialog, available in the <guimenu>Options</guimenu> menu.</para>
</note>
</listitem>
<listitem>
<para>If the system check found the <application>glimpse</application> 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.</para>
</listitem>
<listitem>
<para>During the creation of the search index, the installation window will show
a message that this is in progress.</para>
</listitem>
<listitem>
<para>If all the above installation steps were completed correctly, a final
message states that &kdevelop; will be started after pressing
<guibutton>OK</guibutton>.  Keep in mind that you can set up additional options
like auto saving in the <link linkend="general-configuration">&kdevelop;
Setup</link> dialog that can be accessed through the <guimenu>Options</guimenu>
menu.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>

</sect1>
</chapter>

<chapter id="programs">
<title>Programs</title>

<para>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 <acronym>GNU</acronym> tools in general, and in particular what part
&kdevelop; plays in this game.</para>

<sect1 id="compiler">
<title>The Compiler</title>

<para>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.</para>

<para>Normally you would start like this:</para>

<para>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:</para>

<screen>
<userinput>
#include &lt;iostream.h&gt;

int main(){

cout &lt;&lt; "Hello World" &lt;&lt; endl;

}
</userinput>
</screen>

<para>Actually, all this program will do is print out the string
<computeroutput>&quot;Hello World&quot;</computeroutput> 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
<application>g++</application>.  Then we can save the file with the source code
as, lets say, <filename>myprogram.cpp</filename> and invoke the compiler with
this filename (in a console):</para>

<screen>
<prompt>&percnt;</prompt> <userinput><command>g++</command> <option>-o</option> <filename>myprogram.cpp</filename></userinput>
</screen>

<para>Then we can start our program.  Just type
<userinput><command>myprogram</command></userinput> on the console, and the
program prints out it's <computeroutput>&quot;Hello
World&quot;</computeroutput> string and then exits.</para>

</sect1>

<sect1 id="make">
<title>Make and the <filename>Makefile</filename>s.</title>

<para>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?</para>

<para>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 <filename>Makefile</filename>.  Then, you should have the tool
<application>make</application> or <application>gmake</application> 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
<filename>Makefile</filename>, and save it.  Now you will only have to run
<command>make</command> or <command>gmake</command> on the console in the
directory where your <filename>Makefile</filename> is located, and then
<application>make</application> takes over, leading the compiler through the
steps needed to create your application.  The <application>make</application>
utility has many other advantages, and can be used for a lot of purposes.  To
get an overview, open a console and type <userinput><command>man</command>
<option>make</option></userinput> or search for <userinput>GNU Make</userinput>
in &khelpcenter;.  This will give you at the least an insight into why a
developer needs the <application>make</application> utility to help in compiling
his application.</para>

<para>Until now, writing the <filename>Makefile</filename> 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
<application>Make</application> utility: you just have to set the
<command>make</command> command in the <link
linkend="general-configuration">&kdevelop; setup</link> dialog, and then you're
done.  Alll projects generated with &kdevelop; will use that
<command>make</command> 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
<guimenu>Build</guimenu> menu.</para>

<para>The toolbar and the <guimenu>Build</guimenu> menu offer the most common
functions you will use to let <application>make</application> do the dirty work
for you:</para>

<itemizedlist>
<listitem>
<para><guimenuitem>Compile File</guimenuitem> 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.</para>
</listitem>
<listitem>
<para><guimenuitem>Make</guimenuitem> just calls make and creates your
target</para>
</listitem>
<listitem>
<para><guimenuitem>Rebuild All</guimenuitem> rebuilds the whole project.</para>
</listitem>
<listitem>
<para><guimenuitem>Clean/Rebuild all</guimenuitem> cleans the whole prject
first, and then runs <application>make</application> again.</para>
</listitem>
<listitem>
<para><guimenuitem>Stop Build</guimenuitem> cancels the current build process.
This is mostly used if you are watching make working and staring at your
sources.  And then you think <quote>ahhhh - I forgot about this line...</quote>,
and you have to correct your code.  Just hit <guimenuitem>Stop
Build</guimenuitem> correct the error you found, and run
<application>make</application> again.</para>
</listitem>
</itemizedlist>

<para>This is not the only way &kdevelop; works together with
<application>make</application> 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.</para>

<para>Now you know about sources, the compiler, and why
<application>make</application> 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 <filename>configure</filename>
script.</para>

</sect1>

<sect1 id="configure">
<title>Configure</title>

<para>The title of this section probably has you asking <quote>Configure?  What
has to be configured? Or who?</quote></para>

<para>Well assume you have written a program, including a
<filename>Makefile</filename>.  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 <acronym>RISC</acronym> hardware, you have to
recompile the program.  The easiest way would be to copy the source package to
the target machine and run <command>make</command> 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
<filename class="directory">/opt/kde/</filename> on one machine, while it is
installed in <filename class="directory">/usr/local/kde</filename> on another.
In this case you would have to rewrite the <filename>Makefile</filename> each
time, to ensure a correct compilation and installation of your product.</para>

<para>Fortunately, <acronym>GNU</acronym> tools have even more to provide than
that mighty <application>make</application> - the  commonly used
<application>automake</application> and <application>autoconf</application>
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.</para>

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

<para>Having said this, who is finally creating me my
<filename>Makefile</filename>?  Now, here comes
<application>autoconf</application>.  <application>autoconf</application>
requires several macro files for the project.  These are in the
<filename>Makefile.in</filename>'s generated by
<application>automake</application> and a file called
<filename>configure.in</filename>, also containing macros.  The
<filename>Makefile.am</filename> and <literal role="extension">in</literal>'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.
<filename>Configure.in</filename> on the other hand contains macros for what the
final <command>configure</command> shell script will check for on the system
where <command>configure</command> 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.</para>

<para>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
<filename>configure.in</filename> 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.</para>

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

<procedure>
<step>
<para>Write the sources for your project</para>
</step>
<step>
<para>Write a <filename>Makefile.am</filename> for each subdirectory, including
the main project directory of your project</para>
</step>
<step>
<para>Write a <filename>configure.in</filename> file, to be placed in the main
project directory, and containing the macros for the system requirements.</para>
</step>
<step>
<para>Run <application>automake</application>.</para>
</step>
<step>
<para>Run <application>autoconf</application>.</para>
</step>
</procedure>

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

<para>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.</para>

<para>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 <acronym>GNU</acronym> tools in a very
user friendly way.</para>

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

<para>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
<filename>Makefile</filename>s at all when using &kdevelop;</para>

</sect1>

<sect1 id="debugging">
<title>Debugging</title>

<para>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
<quote>bug</quote> in the code.</para>

<para>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 <quote>bug</quote>, and debugging means to throw out bugs that are
hiding where they shouldn't be.</para>

<para>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 <errorname>Segmentation
fault</errorname>.</para>

<para><acronym>GNU</acronym> provides another tool called
<application>gdb</application>, the <acronym>GNU</acronym> debugger.  This
terminal program allows you to watch the internal values of an application, and
to watch the execution step by step by setting <quote>breakpoints</quote> in the
code.  <application>gdb</application> 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.</para>

<para>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 <application>gdb</application>, &kdevelop; makes use of
<application>KDbg</application>.  To debug your program, you just have to select
<guimenuitem>Debug</guimenuitem> in the <guimenu>Build</guimenu> menu, or press
the corresponding toolbar button (which looks like a <guiicon>wheel with glasses
over it</guiicon>, indicating you want to watch the execution.)</para>

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

<para>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 <acronym>GNU</acronym> tools, you should read the documentation
provided with them, commonly accessed via the <command>man</command> command, or
available in &khelpcenter;.</para>

</sect1>

</chapter>

<chapter id="development-with-kdevelop">
<title>Development with &kdevelop;</title>

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

<para>All tools are described along with their use in the development process.
If you are a beginner with C++/<acronym>GUI</acronym> design and programming,
you should read the <ulink url="programming/index.html">&kdevelop;
Programming Handbook</ulink>, 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 <xref
linkend="programs"> 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 <filename>Makefile</filename>s &etc;.</para>

<sect1 id="what-are-project-applications">
<title>What are &kdevelop; Project Applications?</title>

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

<para>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.</para>

<para>For projects where several developers, maybe working in different places,
are involved, this should be an easy way to ensure consistency of the
<filename>Makefile</filename>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.</para>

<para>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; <application>Designer</application>.</para>

<para>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.</para>

<para>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.</para>

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

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

<para>Even for non <acronym>GUI</acronym> 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.</para>

</sect1>

<sect1 id="tools">
<title>A Short description of &kdevelop;'s tols</title>

<para>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
<application>Designer</application> that comes with &Qt; 2.2.x.  Further, all
necessary programs that are helpful for designing applicaitons are embedded in
one way or another.</para>

<sect2 id="programming-environment-and-qt-designer">
<title>The Programming Environment and the &Qt;
<application>Designer</application></title>

<para>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 <interface>Help
browser</interface>, as well as the <interface>Class Browser</interface>, 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.</para>

<para>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.</para>

</sect2>

<sect2 id="qt-designer">
<title>&Qt;'s <application>Designer</application></title>

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

<para>However, &kdevelop; comes with a converter script
(<filename>kdlgdesigner</filename>), that helps you port existing <literal
role="extension">*.kdevdlg</literal> files, created with &kdevelop;'s internal
dialog editor, into <literal role="extension">.ui</literal> files that can be
processed with &Qt; <application>Designer</application>.  You can find this
script in the <filename class="directory">tools</filename> subdirectory of your
&kdevelop; installation.</para>

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

</sect2>

</sect1>

<sect1 id="kappwizard-and-classtools">
<title>KAppWizard and the Class tools</title>

<para>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
<acronym>GUI</acronym> application design, as results can be achieved very
quickly.</para>

<sect2 id="kappwizard">
<title>KAppWizard</title>

<para>KAppWizard is intended to create fully functional application projects
that are ready-to-run, by using <acronym>GNU</acronym> standard tools, and, for
<acronym>GUI</acronym> 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;.</para>

<para>KAppWizard provides you a so called <quote>application skeleton</quote>,
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.</para>

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

<itemizedlist>
<listitem>
<para>An <acronym>SDI</acronym> interface, for working with one document per
application window, based on the document-view-controller model.</para>
</listitem>
<listitem>
<para>Menus and dialogs for opening and saving files, as well as printing
dialogs.</para>
</listitem>
<listitem>
<para>A toolbar and statusbar, already providing complete functionality.</para>
</listitem>
<listitem>
<para>A Help system, containing an <acronym>SGML</acronym> based user manual,
and statusbar help.</para>
</listitem>
<listitem>
<para>A complete <acronym>HTML</acronym> based <acronym>API</acronym>
(Application Programming Interface) documentation set, for the current state of
the project.</para>
</listitem>
<listitem>
<para>An installation routing using <application>make</application></para>
</listitem>
</itemizedlist>

<para>The KAppWizard is available in the <guimenu>Project</guimenu> with the
entry <guimenuitem>New...</guimenuitem></para>

</sect2>

<sect2 id="classtools">
<title>Classtools</title>

<para>The term <quote>Classtools</quote> 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.</para>

<para>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.</para>

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

<sect3>
<title>Creating a new class with the Class Generator</title>

<para>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.</para>

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

<para>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.</para>

<para>The rest of the work is done automatically for you, you don't have to
worry about the <filename>Makefile.am</filename> and the class itself.  A new
<command>make</command> 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 <menuchoice><guimenu>Project</guimenu><guimenuitem>New
Class</guimenuitem></menuchoice></para>

</sect3>

<sect3>
<title>The Class Browser</title>

<para>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.</para>

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

<para>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 <link
linkend="class-browser">Using the Class Browser</link></para>

</sect3>

</sect2>

</sect1>

</chapter>

<chapter id="development-process">
<title>The Development Process</title>

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

<procedure>
<step>
<para>Generate a program skeleton with KAppWizard</para>
</step>
<step>
<para>The rest of the development using &kdevelop;'s features, and your own
ability as a programmer.</para>
</step>
</procedure>

<para>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
<quote>HOW-TO</quote> in the use of &kdevelop;</para>

<sect1 id="creating-a-program-skeleton">
<title>Creating a program skeleton</title>

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

<para>The wizard automatically creates a project file for the application, and
inserts the &kdevelop; areas into the <filename>Makefile.am</filename>'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.</para>

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

<itemizedlist>
<listitem>
<para><guilabel>GNU-Standard Files (INSTALL, README,
COPYING...)</guilabel></para>
</listitem>
<listitem>
<para><guilabel>User Documentation</guilabel></para>
</listitem>
<listitem>
<para><guilabel>API Documentation</guilabel></para>
</listitem>
<listitem>
<para><guilabel>lsm File (Linux Software Map)</guilabel></para>
</listitem>
<listitem>
<para><guilabel>.desktop file</guilabel></para>
</listitem>
<listitem>
<para><guilabel>Program Icon</guilabel></para>
</listitem>
<listitem>
<para><guilabel>Mini Icon</guilabel></para>
</listitem>
</itemizedlist>

<para>
Choosing <guibutton>Next &lt;</guibutton> brings you to a third page where you
can set up <guilabel>Version Control System Support</guilabel>.  We will assume
for this project that you are not using <acronym>VCS</acronym>, and this is
described in it's own section <xref linkend="cvs-integration">.
</para>

<para>
The next two pages allow you to edit the header template files (for <literal
role="extension">.h</literal>) and the source template files (for <literal
role="extension">.cpp</literal>).  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.
</para>

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

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

</sect1>

<sect1 id="developing-an-application">
<title>Developing an Application</title>

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

<para>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.</para>

<para>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.</para>

<para>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.</para>

<sect2 id="user-interfaces">
<title>User Interfaces</title>

<para>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.</para>

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

<para>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;
<application>Designer</application>.</para>

<para>So, how do you create those great looking dialogs?  As the &Qt; library is
a <acronym>GUI</acronym> toolkit, it provides a base set of
<quote>widgets</quote>.  These include things like labels displaying plain text,
<quote>lineedits</quote> for text input, and buttons for navigation and
selection commands.  Besides these <quote>low-level</quote> 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.</para>

<para>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;
<acronym>UI</acronym> library, offering other widgets.  Libraries such as khtml
contain very specialized widgets that a lot of programs make use of.</para>

<para>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.</para>

<para>Dialogs are technically programmed in C++ code, in a class that is derived
from <classname>QWidget</classname>.  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.</para>

<para>The &Qt; <application>Designer</application> that comes with &Qt; can be
used to easily create dialogs and user interfaces.  You can use the
<guiicon>Switch to Qt Designer</guiicon> icon on &kdevelop;'s menubar. 
<!-- Check where that actually lives! --> This will bring up
<application>Designer</application>, where you can create a new dialog.  You can
also choose an existing <literal role="extension">.ui</literal> file from the
<guilabel>Files</guilabel> viewer and &kdevelop; will open
<application>Designer</application> with the selected dialog.</para>

<para>You can add dialogs easily by adding a new <literal
role="extension">.ui</literal> file from the <guimenu>File</guimenu>
menu.</para>

<para>The <application>Designer</application> creates <literal
role="extension">.ui</literal> files which contain an <acronym>xml</acronym>
description of the class.  Once you have added the file to your project,
&kdevelop; will take care of adding it to your <filename>Makefile</filename>.
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
<application>Designer</application> 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.</para>

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

</sect2>

<sect2>
<title>Binding New Elements</title>

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

<para>As described above, a normal <acronym>GUI</acronym> 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.</para>

<para>In terms of object-oriented design, you would describe
the given architecture as the <quote>Document-View-Controller</quote> 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.</para>

<para>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.</para>

<para>To build your main view, the generated source code for your application
already contains a class in the form of
<classname><replaceable>YourApplication</replaceable>View</classname> which
inherits the <classname>QWidget</classname> class.
<classname>QWidget</classname> is the minimal class that handles user interfaces
in &Qt;, and therefore in &kde; as well.</para>

<para>In general, there are three ways to extend the given class:</para>

<itemizedlist>
<listitem>
<para>Remove the document view structure, and use one of the predefined
<quote>big</quote> widgets that already contain a lot of functionality.  Just
remove the view class, and replace the view object with another.</para>
</listitem>
<listitem>
<para>Change the inheritance of the view class.  Change the inheritance to, for
example, <classname>QMultiLineEdit</classname>, and your application becomes an
editor.</para>
</listitem>
<listitem>
<para>If your main view will consist of several separate parts, create the
widgets and their classes with the &Qt; <application>Designer</application>, and
create objects of these classes in the view class constructors that in
combination will build the main view.</para>
</listitem>
</itemizedlist>

<para>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.</para>

<para>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.</para>

<para>You must also specify an <acronym>ID</acronym> for the menu entry. The
frame applications have all <acronym>ID</acronym>'s already given, collected in
a file <filename class="headerfile">resource.h</filename>, so you have only to
add the <acronym>ID</acronym> and give it a new number.</para>

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

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

<para>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
<application>make</application> tool or <guimenuitem>Execute</guimenuitem> and
the changed files will be recompiled, so the results of your changes can be
tested immediately.</para

</sect2>
</sect1>
</chapter>

<chapter id="complete-development-process">
<title>The Complete Development Process</title>

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

<para>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.</para>

<sect1 id="source-code-management">
<title>Source Code Management</title>

<para>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; <application>Designer</application> 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 <acronym>GUI</acronym> applications?</para>

<para>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
<filename>Makefile</filename>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.</para>

<para>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.</para>

<para>&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.</para>

<para>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.</para>

<para>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 <xref linkend="class-browser">.</para>

</sect1>

<sect1 id="building-and-executing-your-application">
<title>Building and Executing your Application</title>

<para>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.</para>

<para>You start the build process by either clicking on the symbols
<guiicon>Build</guiicon> or <guiicon>Rebuild All</guiicon> in the toolbar, or by
selecting <menuchoice> <guimenu>Build</guimenu> <guimenuitem>Make</guimenuitem>
</menuchoice> or <menuchoice> <guimenu>Build</guimenu> <guimenuitem>Rebuild
All</guimenuitem> </menuchoice></para>

<para>To execute your application, you can choose the symbol
<guiicon>Execute</guiicon> or <guiicon>Debug</guiicon> (which starts
<application>KDbg</application> with your program) from the toolbar, or you can
use the corresponding menu entries in the <guimenu>Build</guimenu> menu.  You
can also choose <guimenuitem>Execute with Arguments</guimenuitem> to start your
application with additional arguments.  For more information about the build
process, see <xref linkend="projects">.</para>

</sect1>

<sect1 id="searching-for-program-errors">
<title>Searching for Program Errors</title>

<para>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.</para>

<para>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 <errorname>Unresolved
symbols</errorname>.  See <xref linkend="linker-options"> for more information
about the linker.</para>

<para>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
<application>make</application> 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.</para>

<para>Where there are more than one error, youcan navigate with the entries in
the <guimenu>View</guimenu> menu: <guimenuitem>Next Error</guimenuitem> or
<guimenuitem>Previous Error</guimenuitem>, 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.</para>

<para>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.</para>

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

<para>For more information about debugging applications, see <link
linkend="projects">Projects</link> and <ulink
url="programming/index-12.html">The &kdevelop; Programming
Handbook</ulink></para>

</sect1>

<sect1 id="additional-information">
<title>Additional Information</title>

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

<itemizedlist>
<listitem>
<para><ulink url="programming/index.html">The &kdevelop; Programming
Handbook</ulink>, covering a complete introduction into <acronym>GUI</acronym>
application design and programming with the &Qt; and &kde; libraries.</para>
</listitem>
<listitem>
<para>This handbook, sections <link linkend="overview">Overview</link> to <link
linkend="projects">Projects</link>, describing all available functions within
&kdevelop;</para>
</listitem>
<listitem>
<para>This handbook, section <link
linkend="using-qt-designer-in-your-project">Using &Qt;
<application>Designer</application> in your projects</link></para>
</listitem>
<listitem>
<para>The Online Reference documentation to the &Qt; library, which covers
examples of using the &Qt; <acronym>GUI</acronym> toolkit, as well as a class
reference and screenshots for most of the important ready-to-use widgets
included.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
</itemizedlist>

<para>On the Internet you will find:</para>

<itemizedlist>
<listitem>
<para><ulink url="http://www.trolltech.no">http://www.trolltech.no</ulink>, for
information about &Qt; and additional third party widgets.</para>
</listitem>
<listitem>
<para><ulink url="http://www.kde.org">http://www.kde.org</ulink> for information
about the &kde; project, and developer guidelines.</para>
</listitem>
<listitem>
<para><ulink url="http://developer.kde.org">http://developer.kde.org</ulink> for
additional references to &kde; application development.</para>
</listitem>
<listitem>
<para>The &kdevelop home page, at <ulink
url="http://www.kdevelop.org">http://www.kdevelop.org</ulink></para>
</listitem>
</itemizedlist>

</sect1>
</chapter>

<chapter id="overview">
<title>Overview</title>

<para>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.)</para>

<para>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.</para>

<sect1 id="main-window">
<title>The Main Window</title>

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

<!-- LW: A screenshot would be a good thing here -->

<itemizedlist>
<listitem>
<para>First comes the <guilabel>Header/Resource Files</guilabel> window, which
shows headers and other text files, including the documentation
<acronym>SGML</acronym> files.  </para>
</listitem>
<listitem>
<para>Next is the <guilabel>C/C++ Files</guilabel> window, which is used for
editing your source code.</para>
</listitem>
<listitem>
<para>These are followed by the <guilabel>Documentation-Browser</guilabel>,
displaying installed documentation in <acronym>HTML</acronym> format.</para>
</listitem>
<!-- LW: Tools tab? it's gone, apps are not being embedded - is this final? 
<listitem>
<para>Finally is the <guilabel>Tools</guilabel> window, for external programs
such as &kiconedit; and <application>KDbg</application>, which are embedded into
the &IDE;.  Any tool that is registered can be accessed via the
<guimenu>Tools</guimenu> menu.  The registration of third party programs can
easily be done in the <link linkend="general-configuration">Configuration
Dialog</link>.</para>
</listitem> -->
</itemizedlist>

<para>For a description of the two editor windows functionality, see the chapter
on <link linkend="working-in-the-editor">Working With the Editor</link> and
for more information on the <guilabel>Documentation-Browser</guilabel>, you
should look in the section <link linkend="using-the-documentation-browser">Using
the Documentation Browser</link>.</para>

</sect1>

<sect1 id="class-browser-and-file-viewers">
<title>The Class browser and File viewers</title>

<sect2>
<title>The <guilabel>Classes</guilabel> Viewer</title>

<para>The <guilabel>Classes</guilabel> 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. </para>

<!-- LW: add copies of the symbol icons  here -->

<para>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 <guilabel>Classes</guilabel> viewer also provides popup menus
that offer more specific options.  See <xref linkend="class-browser"> for more
detailed information.</para>

<note>
<para>The <guilabel>Classes</guilabel> viewer does
<emphasis>not</emphasis> display generated files such as those generated by
<application>moc</application> and <application>uic</application>, as they are
removed from the distribution, and are not present on a clean development
tree.</para>
</note>

</sect2>

</sect1>

<sect1 id="logical-file-viewer">
<title>The Logical File Viewer</title>

<para>The Logical File Viewer (labelled <guilabel>Groups</guilabel>) allows the
sorting of files by filters into groups.  Individual gropus can be added with
the <guimenuitem>Properties</guimenuitem> entry in the
<guimenu>Project</guimenu> 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.</para>

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

</sect1>

<sect1 id="real-file-viewer">
<title>The Real File Viewer</title>

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

</sect1>

<sect1 id="documentation-tree">
<title>The Documentation Tree</title>

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

</sect1>

<sect1 id="output-window">
<title>The Output Window</title>

<para>The Output Window contains several tabs as follows:</para>

<!-- LW: put a screenshot here -->

<variablelist>
<varlistentry>
<term><guilabel>messages</guilabel></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>stdout</guilabel></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>stderr</guilabel></term>
<listitem>
<para>Displays all error messages that your program produces.  This is useful
for testing purposes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>breakpoint</guilabel></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>frame stack</guilabel></term>
<listitem>
<para><!-- LW: What is the frame stack window for --></para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>disassemble</guilabel></term>
<listitem>
<para><!-- What is the disassemble window for --></para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

</chapter>

<chapter id="menu-reference">
<title>The Menu reference</title>

<sect1 id="file-menu">
<title>The <guimenu>File</guimenu> menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">
&Ctrl;<keycap>N</keycap>
</keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>N</accel>ew...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>Opens the <link linkend="new-file-dialog"><guilabel>New
File</guilabel></link> dialg, allowing you to create a new file.  This dialog is
described more completely in section <xref linkend="new-file-dialog">.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">
&Ctrl;<keycap>O</keycap>
</keycombo>
</shortcut>
<guimenu><accel>F</accel></guimenu>
<guimenuitem><accel>O</accel>pen...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>Displays the <guilabel>Open</guilabel> dialog and lets you choose a file
to be opened.</para> 
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">
&Ctrl;<keycap>W</keycap>
</keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>C</accel>lose</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>Closes the file in the frontmost editing window</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>Close All <!-- LW: Report bug, missing Accelerator --></guimenuitem>
</menuchoice>
</term>
<listitem>
<para>Closes all open files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">
&Ctrl; <keycap>S</keycap>
</keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>S</accel>ave</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>Saves the file open in the frontmost editing window. If the file has not
been saved yet, the <guilabel>Save File As...</guilabel> dialog will be opened
to let you choose a path and filename for the file to be saved.</para>
<para>This item is disabled if you are browsing documentation.</para> 
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>Save <accel>A</accel>s...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>Opens the <guilabel>Save File As...</guilabel> dialog, allowing you to
save the current file with a new name. </para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>Save A<accel>l</accel>l</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>Saves all open files that contain unsaved changes.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">
&Ctrl; <keycap>P</keycap>
</keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem><accel>P</accel>rint...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>Opens the <guilabel>Print File</guilabel> dialog where you can set various
options for printing via either <application>enscript</application> or
<application>lpr</application>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">
&Ctrl; <keycap>Q</keycap>
</keycombo>
</shortcut>
<guimenu><accel>F</accel>ile</guimenu>
<guimenuitem>E<accel>x</accel>it</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>Exits &kdevelop;.  If any open files contain unsaved changes, you will be
given the opportunity to save them.</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="edit-menu">
<title>The <guimenu>Edit</guimenu> menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; <keycap>Z</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>U<accel>n</accel>do</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Allows you to undo the last action you performed.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; <keycap>Y</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>R<accel>e</accel>do</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Repeat a previously undone action.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; <keycap>X</keycap>
</keycombo>
</shortcut>
<guimenu><accel>E</accel></guimenu>
<guimenuitem>C<accel>u</accel>t</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Cut to the clipboard the currently selected text, removing it from the source
file.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; <keycap>C</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem><accel>C</accel>opy</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Copy to the clipboard the currently selected text, without removing it from the
source file.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul"> &Ctrl; <keycap>V</keycap></keycombo></shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem><accel>P</accel>aste</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Paste the contents of the clipboard at the cursor.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul"> &Ctrl; <keycap>I</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>In<accel>d</accel>ent</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Moves the selection to the right.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; <keycap>U</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Uninden<accel>t</accel></guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Moves the selection to the left.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; <keycap>M</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>C<accel>o</accel>mment</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Adds // to the beginning of each of the selected lines.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; &Alt; <keycap>M</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Unco<accel>m</accel>ment</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Removes // from the beginning of each of the selected lines.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem><accel>I</accel>nsert File...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Inserts a file at the current cursor position.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; <keycap>F</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem><accel>S</accel>earch</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Searches the file for an expression.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycap>F3</keycap>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Repeat Searc<accel>h</accel></guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Repeats the last search.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; <keycap>R</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem><accel>R</accel>eplace</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Searches for and replaces an expression.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycap>F2</keycap>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Search in <accel>F</accel>iles</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Opens the search in files dialog to search for an expression over several files.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; <keycap>A</keycap></keycombo>
</shortcut>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Select <accel>A</accel>ll</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Selects the whole documents contents.
</action>
</para>
</listitem>
</varlistentry>



<varlistentry>
<term>
<menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Deselect All</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Deselects the whole documents contents.
</action>
</para>
</listitem>
</varlistentry>


<varlistentry>
<term>
<menuchoice>
<guimenu><accel>E</accel>dit</guimenu>
<guimenuitem>Invert Selection</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Inverts the current selection.
</action>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="view-menu">
<title>The <guimenu>View</guimenu> menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; <keycap>G</keycap></keycombo>
</shortcut>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem>Goto <accel>L</accel>ine</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Goes to the line number
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycap>F4</keycap>
</shortcut>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem><accel>N</accel>ext Error</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Switches to the file and line the next error was reported in.
</action>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul"><keycap>Shift</keycap><keycap>F4</keycap></keycombo>
</shortcut>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem><accel>P</accel>revious Error</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Switches to the file and line the previous error was reported in.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem><accel>D</accel>ialog Editor</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Starts Qt's Designer (Dialog Editor) <!-- application & tm not valid -->
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo>
</shortcut>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem><accel>T</accel>ree View</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Enables/Disables the Tree View
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; <keycap>B</keycap></keycombo>
</shortcut>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem><accel>O</accel>utput View</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Enables/Disables the output view.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem>Toolb<accel>a</accel>r</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Enables/Disables the toolbar.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem><accel>B</accel>rowser Toolbar</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Enables/Disables the browser toolbar.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem><accel>S</accel>tatusbar</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Enables/Disables the status bar.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guisubmenu>Tab Te<accel>x</accel>t</guisubmenu>
</menuchoice>
</term>
<listitem>
<para>
<action>
Changes the appearance of the tabs on the tree view.
</action>
</para>
<itemizedlist>
<listitem>
<para>
<guimenuitem>Text only</guimenuitem>
</para>
</listitem>
<listitem>
<para>
<guimenuitem>Icons only</guimenuitem>
</para>
</listitem>
<listitem>
<para>
<guimenuitem>Text and Icons</guimenuitem>
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>V</accel>iew</guimenu>
<guimenuitem><accel>R</accel>efresh</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Refreshes current view.
</action>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="project-menu">
<title>The <guimenu>Project</guimenu> menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>New</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Generates a new project with the Application Wizard.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Generate Project File...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Creates a project file for an existing <command>Automake</command> project.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem><accel>O</accel>pen</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Opens an existing project.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Open <accel>R</accel>ecent Project</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Opens a recently opened project.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem><accel>C</accel>lose</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Closes the current project.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem><accel>N</accel>ew Class...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Creates a new class frame structure and files.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem><accel>A</accel>dd Existing File(s)...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Adds an existing file or files to the project.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Add new <accel>T</accel>ranslation File</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Adds a new language for internationalization to the project.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul"><keycap>Shift</keycap><keycap>F7</keycap></keycombo>
</shortcut>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem><accel>F</accel>ile Properties</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Shows the current file properties.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Make <accel>M</accel>essages and Merge</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Invokes <command>make</command> to create the messages file by extracting all
the <function>i18n()</function> macros.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guisubmenu>API Doc Tool...</guisubmenu>
</menuchoice>
</term>
<listitem>
<para>
<action>
Switches the documentation tool.
</action>

<itemizedlist>
<listitem>
<para>
<guimenuitem>KDoc</guimenuitem>
</para>
</listitem>
<listitem>
<para>
<guimenuitem>Doxygen</guimenuitem>
</para>
</listitem>
<listitem>
<para>
<guimenuitem>Configure Doxygen</guimenuitem>
</para>
</listitem>
</itemizedlist>

</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Make AP<accel>I</accel> Doc</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Creates API documentation for the project.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Make <accel>U</accel>ser Manual</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Creates an SGML User manual for the project. <!-- this will be XML soon -->
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guisubmenu>Make <accel>D</accel>istribution</guisubmenu>
</menuchoice>
</term>
<listitem>
<para>
<action>
Creates a distribution package from the current project.
</action>
</para>

<variablelist>
<varlistentry>
<term>
<guimenuitem><accel>S</accel>ource tar.gz</guimenuitem>
</term>
<listitem>
<para>
Creates a source <literal role="extension">tar.gz</literal> file from the
current sources.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guimenuitem><accel>B</accel>uild RPM Package</guimenuitem>
</term>
<listitem>
<para>
Releases your project as RPM package
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guimenuitem><accel>C</accel>onfigure RPM Package</guimenuitem>
</term>
<listitem>
<para>

</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycap>F7</keycap>
</shortcut>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem><accel>O</accel>ptions</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Configure uptions for creating RPM packages
</action>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="build-menu">
<title>The <guimenu>Build</guimenu> menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul"><keycap>Shift</keycap><keycap>F8</keycap></keycombo>
</shortcut>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Compile <accel>F</accel>ile</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Compiles the current source file.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycap>F8</keycap>
</shortcut>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem><accel>M</accel>ake</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Invokes <command>make</command> command.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Clea<accel>n</accel></guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Invokes <command>make</command> <option>clean</option>, which deletes all object
and metaobject files.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem><accel>R</accel>ebuild</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Rebuilds the program.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Dist<accel>C</accel>lea/Rebuild All</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Invokes <command>make</command> <option>clean</option> and rebuild all.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycap>F10</keycap>
</shortcut>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem><accel>S</accel>top Build</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Stops <command>make</command> immediately.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycap>F9</keycap>
</shortcut>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem><accel>E</accel>xecute</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Invokes the <command>make</command> and runs the program.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Alt; <keycap>F9</keycap></keycombo>
</shortcut>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Execute <accel>w</accel>ith Arguments...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Lets you set runtime arguments for the program, then invokes
<command>make</command> and finally runs the program.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>DistC<accel>l</accel>ean</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Invokes <command>make</command> <option>distclean</option> which deletes all
compiled files.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem><accel>A</accel>utoconf and Automake</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Invokes <command>automake</command> and <command>autoconf</command>.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>C<accel>o</accel>nfigure...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Invokes <command>./configure</command>.
</action>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="debug-menu">
<title>The <guimenu>Debug</guimenu> menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem><accel>S</accel>tart</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Invokes the debugger on the current executable.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guisubmenu>Start (other)...</guisubmenu>
</menuchoice>
</term>
<listitem>
<para>
<action>
Various other startup options for the debugger.
</action>
</para>

<variablelist>
<varlistentry>
<term><guimenuitem>Examine core file</guimenuitem></term>
<listitem>
<para>
<action>
Examine a core file.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Debug another executable</guimenuitem></term>
<listitem>
<para>
<action>
Debug an application other than the current executable.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Attach to process</guimenuitem></term>
<listitem>
<para>
<action>
Attach to a running process.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Debug with arguments</guimenuitem></term>
<listitem>
<para>
<action>
Lets you debug your project application after starting the application with
command line arguments.
</action>
</para>
</listitem>
</varlistentry>
</variablelist>

</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Run</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Continues application execution.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Run to cursor</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Continues application execution until the current cursor position is reached.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Step over</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Step over.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Step over instr</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Step over instruction.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Step into</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Step into.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Step into instr</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Step into instruction.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Step out</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Run to end of function.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Viewers</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Various views into the app.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Interrupt</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Interrupt the app.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>P</accel>roject</guimenu>
<guimenuitem>Stop</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Kills the app and exits the debugger.
</action>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="tools-menu">
<title>The <guimenu>Tools</guimenu> menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu><accel>T</accel>ools</guimenu>
</menuchoice>
</term>
<listitem>
<para>
<!-- Submenu of configure tools -->
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="options-menu">
<title>The <guimenu>Options</guimenu> menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem><accel>E</accel>ditor..</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Sets up the editor's behavior.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem>Editor <accel>C</accel>olors...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Sets the editor's colors.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem>Editor <accel>D</accel>efaults...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Sets the highlighting default colors.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem><accel>S</accel>yntax Highlighting</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Sets the highlighting colors.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem>Documentation <accel>B</accel>rowser...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Configures the browser options.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guisubmenu>Configure <accel>P</accel>rinter...</guisubmenu>
</menuchoice>
</term>
<listitem>
<para>
<action>
Configures printing options.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem>Tools...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Configures the Tools menu entries.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>S</accel>ettings</guimenu>
<guimenuitem><accel>K</accel>Develop Setup...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Configures KDevelop.
</action>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="window-menu">
<title>The <guimenu>Window</guimenu> menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu><accel>W</accel>indow</guimenu>
</menuchoice>
</term>
<listitem>
<para>
<action>
<!-- Display list of open windows -->
</action>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="bookmarks-menu">
<title>The <guimenu>Bookmarks</guimenu> menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; &Alt; <keycap>T</keycap></keycombo>
</shortcut>
<guimenu><accel>B</accel>ookmarks</guimenu>
<guimenuitem><accel>T</accel>oggle Bookmark</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Toggle a bookmark in the current open file.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycap>F5</keycap>
</shortcut>
<guimenu><accel>B</accel>ookmarks</guimenu>
<guimenuitem><accel>N</accel>ext bookmark</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Goes to the next bookmark in the current file.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul"><keycap>Shift</keycap> <keycap>F5</keycap></keycombo>
</shortcut>
<guimenu><accel>B</accel>ookmarks</guimenu>
<guimenuitem><accel>P</accel>revious Bookmark</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Goes to the previous bookmark in the current file.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl; &Alt; <keycap>C</keycap></keycombo>
</shortcut>
<guimenu><accel>B</accel>ookmarks</guimenu>
<guimenuitem><accel>C</accel>lear Bookmarks</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>
Clears the bookmarks for the current file.
</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>B</accel>ookmarks</guimenu>
<guisubmenu><accel>H</accel>eader Window</guisubmenu>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>B</accel>ookmarks</guimenu>
<guimenuitem>C/C++ <accel>W</accel>indow</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>B</accel>ookmarks</guimenu>
<guisubmenu><accel>B</accel>rowser Window</guisubmenu>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="help-menu">
<title>The <guimenu>Help</guimenu> menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem><accel>B</accel>ack</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem><accel>F</accel>orward</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul"><keycap>Shift</keycap><keycap>F2</keycap></keycombo>
</shortcut>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem><accel>S</accel>earch Marked Text</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>Search for Help on...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycombo action="simul"><keycap>Shift</keycap><keycap>F1</keycap></keycombo>
</shortcut>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>What's <accel>T</accel>his</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<shortcut>
<keycap>F1</keycap>
</shortcut>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>The User Manual to KDevelop</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>The KDevelop Programming Handbook</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>KDE Application Tutorials</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>The KDE Library Reference Guide</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>C/C++ Reference</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>Project <accel>A</accel>PI-Doc</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>Project <accel>U</accel>ser-Manual</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>Tip of the Day</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>KDevelop Homepage</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem><accel>R</accel>eport Bug...</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem><accel>A</accel>bout KDevelop</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice>
<guimenu><accel>H</accel>elp</guimenu>
<guimenuitem>About <accel>K</accel>DE</guimenuitem>
</menuchoice>
</term>
<listitem>
<para>
<action>

</action>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="toolbar">
<title>The &kdevelop; toolbar</title>

<para></para>

</sect1>

<sect1 id="keybindings">
<title>Keyboard Shortcuts</title>

<para>
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
<menuchoice><guimenu><!-- LW: Look up where this one is -->
</guimenu><guimenuitem>Configure Keybindings</guimenuitem></menuchoice>.
</para>

<sect2>
<title>Shortcuts for Text Processing</title>

<table>
<title>Keybindings: Cursor Movements</title>
<tgroup cols="2">
<tbody>
<row>
<entry>
One letter to the left
</entry>
<entry>
<keycap>Left Arrow</keycap>
</entry>
</row>
<row>
<entry>
One letter to the right
</entry>
<entry>
<keycap>Right Arrow</keycap>
</entry>
</row>
<row>
<entry>
One word to the left
</entry>
<entry>
<keycombo action="simul">&Ctrl;<keycap>Left Arrow</keycap></keycombo>
</entry>
</row>
<row>
<entry>
One word to the right
</entry>
<entry>
<keycombo action="simul">&Ctrl;<keycap>Right Arrow</keycap></keycombo>
</entry>
</row>
<row>
<entry>
One line upwards
</entry>
<entry>
<keycap>Up Arrow</keycap>
</entry>
</row>
<row>
<entry>
One line downwards
</entry>
<entry>
<keycap>Down Arrow</keycap>
</entry>
</row>
<row>
<entry>
To the beginning of the line
</entry>
<entry>
<keycap>Home</keycap>
</entry>
</row>
<row>
<entry>
To the end of the line
</entry>
<entry>
<keycap>End</keycap>
</entry>
</row>
<row>
<entry>
One page up
</entry>
<entry>
<keycap>Page Up</keycap>
</entry>
</row>
<row>
<entry>
One page down
</entry>
<entry>
<keycap>Page Down</keycap>
</entry>
</row>
<row>
<entry>
To the beginning of the current file
</entry>
<entry>
<keycombo action="simul">&Ctrl;<keycap>Page Up</keycap></keycombo>
</entry>
</row>
<row>
<entry>
To the end of the current file
</entry>
<entry>
<keycombo action="simul">&Ctrl;<keycap>Page Down</keycap></keycombo>
</entry>
</row>
</tbody>
</tgroup>
</table>

<table>
<title>Keybindings: Text Selections</title>
<tgroup cols="2">
<tbody>
<row>
<entry>
One letter to the left
</entry>
<entry>
<keycombo action="simul"><keycap>Shift</keycap><keycap>Left Arrow</keycap>
</keycombo>
</entry>
</row>
<row>
<entry>
One letter to the right
</entry>
<entry>
<keycombo action="simul"><keycap>Shift</keycap><keycap>Right Arrow</keycap>
</keycombo>
</entry>
</row>
<row>
<entry>
One word to the left
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>Shift</keycap><keycap>Left
Arrow</keycap>
</keycombo>
</entry>
</row>
<row>
<entry>
One word to the right
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>Shift</keycap><keycap>Right
Arrow</keycap>
</keycombo>
</entry>
</row>
<row>
<entry>
One line upwards
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>Up Arrow</keycap></keycombo>
</entry>
</row>
<row>
<entry>
One line downwards
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>Down Arrow</keycap></keycombo>
</entry>
</row>
<row>
<entry>
To the beginning of the current line
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>Home</keycap></keycombo>
</entry>
</row>
<row>
<entry>
To the end of the current line
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>End</keycap></keycombo>
</entry>
</row>
<row>
<entry>
One page up
</entry>
<entry>
<keycombo action="simul"><keycap>Shift</keycap> <keycap>Page Up</keycap>
</keycombo>
</entry>
</row>
<row>
<entry>
One page down
</entry>
<entry>
<keycombo action="simul"><keycap>Shift</keycap> <keycap>Page Down</keycap>
</keycombo>
</entry>
</row>
<row>
<entry>
To the beginning of the current file
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>Shift</keycap> <keycap>Page Up</keycap>
</keycombo>
</entry>
</row>
<row>
<entry>
To the end of the current file
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>Shift</keycap> <keycap>Page
Down</keycap></keycombo>
</entry>
</row>
</tbody>
</tgroup>

</table>

<table>
<title>Keybindings: Inserting and Copying Text, Tabulators</title>
<tgroup cols="2">
<tbody>
<row>
<entry>
Enable/Disable insert mode
</entry>
<entry>
<keycap>Insert</keycap>
</entry>
</row>
<row>
<entry>
Copy selection to the clipboard
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>C</keycap></keycombo>, 
<keycombo action="simul">&Ctrl; <keycap>Insert</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Insert text from the clipboard
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>V</keycap></keycombo>,
<keycombo action="simul"><keycap>Shift</keycap>
<keycap>Insert</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Delete current line
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>K</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Insert line after current line
</entry>
<entry>
<keycombo action="seq"><keycap>End</keycap><keycap>Enter</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Insert Line before current line
</entry>
<entry>
<keycombo action="seq"><keycap>Home</keycap><keycap>Enter</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Undo editing step
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>Z</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Redo editing step
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>Y</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Tabulator
</entry>
<entry>
<keysym>Tab</keysym>
</entry>
</row>
</tbody>
</tgroup>
</table>

<table>
<title>Keybindings: Deleting Text</title>
<tgroup cols="2">
<tbody>
<row>
<entry>
Delete letter left of cursor position
</entry>
<entry>
<keysym>Backspace</keysym>
</entry>
</row>
<row>
<entry>
Delete letter right of cursor position
</entry>
<entry>
<keycap>Delete</keycap>
</entry>
</row>
<row>
<entry>
Delete selected text
</entry>
<entry>
Select text then <keysym>Backspace</keysym> or <keycap>Delete</keycap>
</entry>
</row>
</tbody>
</tgroup>
</table>

<table>
<title>Keybindings: Searching within the editor</title>
<tgroup cols="2">
<tbody>
<row>
<entry>
open <guilabel>Goto Line...</guilabel> dialog
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>G</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Open <guilabel>Find Text</guilabel> dialog
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>F</keycap></keycombo>
</entry>
<entry>
Repeat last search
</entry>
<entry>
<keycap>F3</keycap>
</entry>
</row>
<row>
<entry>
Open <guilabel>Search and Replace</guilabel> dialog
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>R</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Open <guilabel>Search in Files</guilabel> dialog (grep)
</entry>
<entry>
<keycombo action="simul">&Ctrl; &Alt; <keycap>F</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Locate next error
</entry>
<entry>
<keycap>F4</keycap>
</entry>
</row>
<row>
<entry>
Locate previous error
</entry>
<entry>
<keycombo action="simul"><keycap>Shift</keycap><keycap>F4</keycap></keycombo>
</entry>
</row>
</tbody>
</tgroup>
</table>

<table>
<title>Keybindings: Searching within the Documentation Browser</title>
<tgroup cols="2">
<tbody>
<row>
<entry>
Search for the selected editor text in the documentation
</entry>
<entry>
<keycap>F2</keycap>
</entry>
</row>
<row>
<entry>
Search for the selected browser text in the documentation
</entry>
<entry>
<keycap>F2</keycap>
</entry>
</row>
<row>
<entry>
Display next search hit on the same page
</entry>
<entry>
<keycap>F3</keycap>
</entry>
</row>
<row>
<entry>
Search for the selected browser text within the project
</entry>
<entry>
<keycombo action="simul"><keycap>Shift</keycap><keycap>F2</keycap></keycombo>
</entry>
</row>
</tbody>
</tgroup>
</table>

<table>
<title>Keybindings: Browser Shortcuts</title>
<tgroup cols="2">
<tbody>
<row>
<entry>
Previous page
</entry>
<entry>
<keycombo action="simul">&Alt; <keycap>Left Arrow</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Next page
</entry>
<entry>
<keycombo action="simul">&Alt; <keycap>Right Arrow</keycap></keycombo>
</entry>
</row>
</tbody>
</tgroup>
</table>

<table>
<title>Keybindings: Managing Bookmarks</title>
<tgroup cols="2">
<tbody>
<row>
<entry>
Add bookmark
</entry>
<entry>
<keycombo action="simul">&Ctrl; &Alt; <keycap>A</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Clear bookmark list
</entry>
<entry>
<keycombo action="simul">&Ctrl; &Alt; <keycap>C</keycap></keycombo>
</entry>
</row>
</tbody>
</tgroup>
</table>

</sect2>

<sect2>
<title>Shortcuts for Toolbar Symbols</title>

<table>
<title>Keybindings: toolbar symbols</title>
<tgroup cols="2">
<tbody>
<row>
<entry>
<guiicon>Open File</guiicon>
</entry>
<entry>
<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
</entry>
</row>
<row>
<entry>
<guiicon>Save File</guiicon>
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>S</keycap></keycombo>
</entry>
</row>
<row>
<entry>
<guiicon>Print File</guiicon>
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>P</keycap></keycombo>
</entry>
</row>
<row>
<entry>
<guiicon>Undo</guiicon>
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>Z</keycap></keycombo>
</entry>
</row>
<row>
<entry>
<guiicon>Redo</guiicon>
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>Y</keycap></keycombo>
</entry>
</row>
<row>
<entry>
<guiicon>Cut</guiicon>
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>X</keycap></keycombo>
</entry>
</row>
<row>
<entry>
<guiicon>Copy</guiicon>
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>C</keycap></keycombo>
</entry>
</row>
<row>
<entry>
<guiicon>Paste</guiicon>
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>V</keycap></keycombo>
</entry>
</row>
<row>
<entry>
<guiicon>Compile File</guiicon>
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>F8</keycap></keycombo>
</entry>
</row>
<row>
<entry>
<guiicon>Make</guiicon>
</entry>
<entry>
<keycap>F8</keycap>
</entry>
</row>
<row>
<entry>
<guiicon>Execute</guiicon>
</entry>
<entry>
<keycap>F9</keycap>
</entry>
</row>
<row>
<entry>
<guiicon>Execute with arguments</guiicon>
</entry>
<entry>
<keycombo action="simul">&Alt; <keycap>F9</keycap></keycombo>
</entry>
</row>
<row>
<entry>
<guiicon>Back</guiicon>
</entry>
<entry>
<keycombo action="simul">&Alt; <keycap>Left Arrow</keycap></keycombo> (if the
browser is open)
</entry>
</row>
<row>
<entry>
<guiicon>Forward</guiicon>
</entry>
<entry>
<keycombo action="simul">&Alt; <keycap>Right Arrow</keycap></keycombo> (if the
browser is open)
</entry>
</row>
<row>
<entry>
<guiicon>Search for selected text</guiicon>
</entry>
<entry>
<keycap>F2</keycap>
</entry>
</row>
</tbody>
</tgroup>
</table>

</sect2>

<sect2>
<title>Window Management</title>

<para>
To switch to a certain window, press <keycombo action="simul">&Alt; <keycap>The
unerlined letter in the window title</keycap></keycombo>.  For example, to
switch to the <guilabel>Tools</guilabel> window would be <keycombo
action="simul">&Alt; <keycap>T</keycap></keycombo>
</para>

</sect2>

<sect2>
<title>Shortcuts to compilation processes</title>

<table>
<title>Keybindings: Compilation processes</title
<tgroup cols="2">
<tbody>
<row>
<entry>
Compile current source file
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>F8</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Build current project target
</entry>
<entry>
<keycap>F8</keycap>
</entry>
</row>
<row>
<entry>
Execute the target after the build process
</entry>
<entry>
<keycombo action="simul">&Ctrl; <keycap>F9</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Execute the target with arguments
</entry>
<entry>
<keycombo action="simul">&Alt; <keycap>F9</keycap></keycombo>
</entry>
</row>
<row>
<entry>
Stop the current process
</entry>
<entry>
<keycap>F10</keycap>
</entry>
</row>
</tbody>
</tgroup>
</table>

</sect2>

</sect1>

<sect1 id="statusbar-help">
<title>Status bar help</title>

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

<!-- LW: Screenshot of statusbar -->

<para>
The statusbar contains the following items:
</para>

<itemizedlist>
<listitem>
<para>
A general message field, on the far left.  This is used for help messages, and
displaying the current activity.
</para>
</listitem>
<listitem>
<para>
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 <guilabel>Classes</guilabel> Browser.  The progressbar only appears while
these processes are in executed.
</para>
</listitem>
<listitem>
<para>
An insert/overwrite indicator is next.  Here you can see which mode the editor
is currently in, with <guilabel>INS</guilabel> indicating insert mode, and
<guilabel>OVR</guilabel> indicating overwrite mode.  You can toggle between the
two with the <keycap>Insert</keycap> key on your keyboard.
</para>
</listitem>
<listitem>
<para>
There is a line counter, displaying the current position of the cursor.
</para>
</listitem>
<listitem>
<para>
Finally, there is a column counter, also displaying the current position of the
cursor.
</para>
</listitem>
</itemizedlist>

<para>
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.
</para>

<para>
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 <guilabel>Read</guilabel>
state.
</para>

<para>
When using the documentation browser, the statusbar displays link
<acronym>URL</acronym>s 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.
</para>

<para>
The caption of the &kdevelop; &IDE; shows you the currently active open
filename.  This would be an <acronym>HTML</acronym> 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.
</para>

</sect1>

</chapter>

<chapter id="help-system">
<title>The Help System</title>

<para>
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.
</para>

<para>
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.
</para>

<para>
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. 
</para>

<sect1 id="whats-this-and-quick-help">
<title>The <guiicon>What's This?</guiicon> icon and Quickhelp</title>

<para>
Looking at &kdevelop;'s top toolbar, you will see a <guiicon>What's
this?</guiicon> 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.
</para>

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

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

<para>
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.
</para>

<para>
For user interaction dialogs, <interface>Quick Help</interface> 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
<guimenuitem>Quick Help</guimenuitem>, and selecting this will pop up a help
window.</para>

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

</sect1>

<sect1 id="configuring-the-help-browser">
<title>Configuring the <acronym>HTML</acronym> help browser</title>

<para>
The browser included in &kdevelop; is completely <acronym>HTML</acronym> 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
<guimenuitem>Documentation Browser</guimenuitem> entry of the
<guimenu>Options</guimenu> menu.
</para>

<sect2 id="font-preferences">
<title>Font preferences</title>

<para>
The first option for the font display is the size.  You may choose between
<guilabel>small</guilabel>, <guilabel>medium</guilabel> and
<guilabel>Large</guilabel> <!-- LW: Check there's not a new option here --> The
default is <guilabel>small</guilabel>.
</para>

<para>
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 <quote>i</quote>
or a <quote>w</quote>, &eg; courier), for displaying code samples in the
documentation, and a proportional font for the rest of the text, (one in which
an <quote>i</quote> takes up less space on the screen than a <quote>w</quote>
&eg; helvetica).
</para>

</sect2>

<sect2 id="color-preferences">
<title>Color preferences</title>

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

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

<para>
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.
</para>

<para>
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.
</para>

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

</sect2>

</sect1>

<sect1 id="using-the-documentation-browser">
<title>Using the Documentation Browser</title>

<para>
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. 
</para>

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

</sect1>

<sect1 id="requirements-for-help">
<title>Requirements</title>

<para>
To make use of all features of the documentation browser, you should have
<application>KDoc</application> and <application>Glimpse</application>
installed.
</para>

<para>
<application>KDoc</application> is used to generate all kinds of
online class documentation for the &kde; libraries.  This is normally done
during the setup process, but <application>KDoc</application> can also be
invoked with the <link linkend="general-configuration">KDevelop Setup</link>.
<application>KDoc</application> is also used for generation of
<acronym>API</acronym> (Application Programming Interface) Documentation for
your project's classes.
</para>

<para>
For generating <acronym>API</acronym> documentation,
<application>KDoc</application> is called with the menu entry
<menuchoice><guimenu>Project</guimenu><guimenuitem>Make API
Doc</guimenuitem></menuchoice>. 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.
</para>

<para>
For the generation of project handbooks you have written, you should have 

<!-- link here to Eric's page on how to install them, and to the rpm's on the
ftp site? -->

</para>

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

<para>
The program <application>Glimpse</application> 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 <link
linkend="general-configuration">&kdevelop; Setup</link> dialog.  For a
description of the search functions provided, see <xref
linkend="using-the-search-index">.
</para>

</sect1>

<sect1 id="provided-documentation">
<title>Provided Documentation</title>

<para>

<!-- LW: This whole paragraph needs rewriting after we have consolidated the -->
<!-- documentation structure - in the meantime, it's copied direct from the -->
<!-- old documentation-->

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

<para>
The first book provided is this online handbook, containing all the information
you need regarding installation, configuration and functionality. <!-- removed -->
<!-- "and an introduction to application development because that shouldn be in -->
<!-- one of the other documents... the programmers manual probably, or -->
<!-- tutorial. -->
</para>

<para>
The second book is <!-- link to programming manual -->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 <ulink
url="http://developer.kde.org/">http://developer.kde.org/</ulink>.
</para>

<para>
The &Qt; and &kde; libraries documentation folder allows direct access to the
<acronym>HTML</acronym> 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.
</para>

<para>
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 <application>KDoc</application> 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;.
</para>

<para>
The documentation tree also contains an <guilabel>Other</guilabel> folder, which
is intended to contain any personal documentation you have installed, as
described in the section <link linkend="adding-documentation">Adding
Documentation to the Help Browser</link>.
</para>

<para>
Finally, the documentation tree gives you access to the <acronym>API</acronym>
and user manuals for your current project.
</para>

</sect1>

<sect1 id="adding-documentation">
<title>Adding Documentation to the Help Browser
<anchor id="extending-the-project-documentation">
</title>

<para>
To customize your documentation browser, open the tree view and select the
<guilabel><!-- LW: what is DOC called now? -->  </guilabel> tab.  You will see
an opened tree containing four folders.  The <guilabel>Others</guilabel> folder
is initially empty.
</para>

<para>
&RMB; click over this folder, and in the resulting context menu, choose
<guimenuitem>Add Entry</guimenuitem>.  The <guilabel>Add Entry</guilabel> dialog
will open.
</para>

<para>
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 <acronym>HTML</acronym> documentation is supported.
</para>

<para>
Choose <guibutton>OK</guibutton> to add the entry and close the dialog.  Your
new documentation is available immediately.
</para>

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

</sect1>

<sect1 id="using-the-search-index">
<title>Using the Search index</title>

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

<para>
To set up the search index, see the section on <link
linkend="general-configuration">&kdevelop; setup</link>.  The index is also
generated automatically during the installation procedure.
</para>

<para>
The search functions are accessible several ways:
</para>

<itemizedlist>
<listitem>
<para>
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 <guimenuitem>look up: expression</guimenuitem> from the context menu.
</para>
</listitem>
<listitem>
<para>
In the editor, select the text you want help on, or place the cursor in the word
you want to lok for. Choose <guimenuitem>Search marked text</guimenuitem> from
the <guimenu>Help</guimenu> menu, or press the <keycap>F2</keycap> key.
</para>
</listitem>
<listitem>
<para>
In the documentation browser, select the text you want to look up, and follow
the same procedures as for the editor.
</para>
</listitem>
<listitem>
<para>
If you want to search for a specific keyword, select <guimenuitem>Search for
Help on...</guimenuitem> in the <guimenu>Help</guimenu> menu, or select the
<guiicon>Search for Help on...</guiicon> icon in the toolbar.  A dialog will
open where you can enter the word you want to search for.
</para>
</listitem>
</itemizedlist>

<para>
The documentation browser also offers support for
<application>grep</application>, to search for a selection within your current
project.  For example, you've opened the documentation page for the
<classname>KTMainWindow</classname> and you want to know where in your code
<classname>KTMainWindow</classname> appears.  Mark
<classname>KTMainWindow</classname> and either &RMB; click and select
<guimenuitem>Grep: KTMainWindow</guimenuitem> or press <keycombo action="simul">
<keycap>Shift</keycap><keycap>F2</keycap></keycombo>.
</para>

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

</sect1>

</chapter>

<chapter id="working-in-the-editor">
<title>Working in the Editor</title>

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

<itemizedlist>
<listitem>
<para>
Creating, opening, and saving your source an dproject files.
</para>
</listitem>
<listitem>
<para>
Editing source and project files.
</para>
</listitem>
<listitem>
<para>
Writing your documentation.
</para>
</listitem>
<listitem>
<para>
Printing your project files.
</para>
</listitem>
</itemizedlist>

<para>
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 <quote>Advanced Editor</quote>.
</para>

<para>
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.
</para>

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

<sect1 id="managing-project-files">
<title>Managing Project Files</title>

<para>
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 <literal role="extension">.ui</literal> files.  These are
recognized automatically and the appropriate editor will be launched to edit
these.
</para>

<para>
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. 
</para>

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

</sect1>

<sect1 id="creating-and-saving-files">
<title>Creating and Saving Files
<anchor id="new-file-dialog">
</title>

<para>
To create a new file choose <guimenuitem>New</guimenuitem> from the
<guimenu>File</guimenu> menu.  This opens the <guilabel>New File</guilabel>
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.
</para>

<para>
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 <guimenu>Window</guimenu> menu, or by
choosing another file in either the <guilabel>Files</guilabel> or
<guilabel>Groups</guilabel> tree views.
</para>

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

<para>
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
<quote>Autosaving</quote>.  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 <xref linkend="kdevelop-setup"> where the setup options are
described.
</para>

<para>
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.
</para>

<para>
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 <guimenuitem>Compile
File</guimenuitem> command, which only saves the currently active source file.
</para>

</sect1>

<sect1 id="opening-and-closing-files">
<title>Opening and Closing Files</title>

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

<para>
Another, probably more frequently used way is to select the file from the
<guilabel>Groups</guilabel> or <guilabel>Files</guilabel> 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 <guilabel>Groups</guilabel> tab, which
displays only files that are included in your project, but sorts them by their
type, and collected into folders.
</para>

<para>
To close files, select the file to close from the <guimenu>Window</guimenu>
menu, which loads that file into the editor.  Then select
<guimenuitem>Close</guimenuitem> from the <guimenu>File</guimenu> 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.
</para>

</sect1>

<sect1 id="navigating-within-files">
<title>Navigating Within Files</title>

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

<procedure>
<title>How to find a certain line in a file</title>
<step>
<para>
Select <guimenuitem>Goto Line</guimenuitem> in the view menu or press 
<keycombo action="simul">&Ctrl; <keycap>G</keycap></keycombo>. The
<guilabel>Goto Line</guilabel> dialog will appear.
</para>
</step>
<step>
<para>
Insert the line number you want to jump to.
</para>
</step>
<step>
<para>
Press <guibutton>OK</guibutton>.
</para>
</step>
</procedure>

<procedure>
<title>How to set a bookmark</title>
<step>
<para>
Set the cursor to the line you wish to access by referring to a bookmark.
</para>
</step>
<step>
<para>
Select <guimenuitem>Set Bookmark</guimenuitem> from the
<guimenu>Bookmarks</guimenu> menu.
</para>
</step>
<step>
<para>
From the resulting context menu, select the bookmark number you wish to assign
to this position.
</para>
</step>
</procedure>

<para>Another way to set bookmarks is to select <guimenuitem>Add
Bookmark</guimenuitem> from the <guimenu>Bookmarks</guimenu> 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 <guimenuitem>Add Bookmark</guimenuitem>.
</para>

<para>
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 <guimenuitem>Delete
Bookmarks</guimenuitem> from the <guimenu>Bookmarks</guimenu> menu.  This
deletes all bookmarks for the active file.
</para>

<procedure>
<title>How to go to a bookmarked line</title>
<step>
<para>
Select the <guimenu>Bookmarks</guimenu> menu and open the submenu containing the
bookmarks for the window you want to view.
</para>
</step>
<step>
<para>
Select the bookmarked line.
</para>
</step>
</procedure>

<para>
Selecting a bookmark for the browser window will open the browser and load that
page.
</para>

</sect1>

<sect1 id="edit-window-settings">
<title>Edit Window Settings</title>

<!-- LW: This should all be in a generic "how to configure Kdevelop" chapter -->

<para>
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.
</para>

<para>
The following sections describe how to set these options in the configuration
dialogs provided by the <guimenu>Options</guimenu> menu.
</para>

<sect2 id="general-edit-window-settings">
<title>General Settings</title>

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

<sect3 id="edit-settings">
<title>Edit Settings</title>

<variablelist>
<varlistentry>
<term><guilabel>Auto Indent:</guilabel></term>
<listitem>
<para>
<action>Sets the editor to place the cursor below the first literal upon
creation of a new line.</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Backspace Indent:</guilabel></term>
<listitem>
<para>
<action>
Sets the cursor below the first literal of the line above, when a backspace is
pressed.</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Word Wrap</guilabel></term>
<listitem>
<para>
<action>Words are moved to the next line</action> after the column set in
<guilabel>Wrap words at:</guilabel>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Replace Tabs:</guilabel></term>
<listitem>
<para>
<action>Tabs in the current text are replaced</action> with tabs of the current
<guilabel>Tab Width:</guilabel> value.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Remove Trailing Spaces:</guilabel></term>
<listitem>
<para>
<action>Removes trailing spaces at the ends of lines.</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Wrap Cursor:</guilabel></term>
<listitem>
<para>
<action>Sets the cursor to the end of the previous line, when backspace enters
the beginning of a line.</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Auto Brackets:</guilabel></term>
<listitem>
<para>
<action>Creates a closing bracket in front of the cursor when a bracket (any
kind) is opened.</action>
</para>
</listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="select-settings">
<title>Select Settings</title>

<variablelist>
<varlistentry>
<term><guilabel>Persistent Selections:</guilabel></term>
<listitem>
<para>
<action>Selections made stay marked after setting the cursor to a different
place.</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Multiple Selections:</guilabel></term>
<listitem>
<para>
<action>Allows multiple independent selections within the text.</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Vertical Selections:</guilabel></term>
<listitem>
<para>
<action>Allow vertical (column wise) selection of text.</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Delete on Input</guilabel></term>
<listitem>
<para>
<action>Deletes a selection when typing into the selection.</action>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Toggle Old:</guilabel></term>
<listitem>
<para>
<action>Allows only one selection.</action>  A selection is deselected when
another selection is made.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Wrap Words At:</guilabel></term>
<listitem>
<para>
<action>Sets the maximum columns a line can have.</action> The word that
contains a letter that reaches over this value is automatically moved to the
next line.
</para>
</listitem>
</varlistentry>

</variablelist>

</sect3>

</sect2>

<sect2 id="color-settings">
<title>Color Settings</title>

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

<para>
You can configure colors for:
</para>

<variablelist>
<varlistentry>
<term><guilabel>Background</guilabel></term>
<listitem>
<para>
The editor background.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Text Background:</guilabel></term>
<listitem>
<para>
The background of displayed text.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Selected:</guilabel></term>
<listitem>
<para>
The color of selected text.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Found:</guilabel></term>
<listitem>
<para>
The color of text found by any kind of search, including
<guimenuitem>Search</guimenuitem>, <guimenuitem>Repeat Search</guimenuitem> and
<guimenuitem>Replace</guimenuitem>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Selected + Found:</guilabel></term>
<listitem>
<para>
The color of text that is both selected and found.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="syntax-highlighting-settings">
<title>Syntax Highlighting Settings</title>

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

<para>
First you can set default colors for syntax highlighting in the
<guimenuitem>Editor Defaults</guimenuitem> entry in the
<guimenu>Options</guimenu> 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 <guilabel>Default</guilabel> item and set the options as you require.
</para>

<para>
The second configuration dialog is accessed by <guimenuitem>Syntax
Highlighting</guimenuitem> in the <guimenu>Options</guimenu> dialog.  This
allows you to set the file filters for the programming language, &eg; <literal
role="extension">*.cpp</literal>, <literal role="extension">*.h</literal> for
C++.
</para>

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

<para>
After pressing <guibutton>OK</guibutton>, your new values will be enabled and
used in the editor.
</para>

</sect2>

</sect1>

<sect1 id="search-and-replace">
<title>Searching and Replacing</title>

<procedure>
<title>Single File Search</title>
<step>
<para>
Select <guimenuitem>Search</guimenuitem> in the <guimenu>Edit</guimenu>
menu.  The Search dialog will open.
</para>
</step>
<step>
<para>
Specify the expression to search for.  The drop down menu offers the ability to
select from previous search expressions.
</para>
</step>
<step>
<para>
Select any additional options such as <guilabel>Whole Words only</guilabel>
</para>
</step>
<step>
<para>
Press <guibutton>OK</guibutton>
</para>
</step>
</procedure>

<para>
To repeate the search for an expression, press <keycap>F3</keycap>
</para>

<sect2>
<title>Searching in multiple files with grep</title>

<para>
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.
</para> 

<para>
&kdevelop; contains a <application>grep</application> 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.
</para>

<para>
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 <guimenuitem>Search in Files...</guimenuitem>
from the <guimenu>Edit</guimenu> menu.  The search dialog opens and lets you
enter:
</para>

<itemizedlist>
<listitem>
<para>
The expression to search for.
</para>
</listitem>
<listitem>
<para>
The template to be used for the search
</para>
</listitem>
<listitem>
<para>
The &MIME; type of files to search in.
</para>
</listitem>
<listitem>
<para>
The directory to search from.
</para>
</listitem>
<listitem>
<para>
If the search is to be recursive over all the included subdirectories.
</para>
</listitem>
</itemizedlist>


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

<para>
You can extend your search with the following options:
</para>

<segmentedlist>
<segtitle>Expression:</segtitle>
<segtitle>Meaning:</segtitle>
<seglistitem>
<seg>.</seg>
<seg>Match any character</seg>
</seglistitem>
<seglistitem>
<seg>^</seg>
<seg>Match the beginning of any line</seg>
</seglistitem>
<seglistitem>
<seg>$</seg>
<seg>Match the end of a line</seg>
</seglistitem>
<seglistitem>
<seg>&lt;</seg>
<seg>Match the beginning of a word</seg>
</seglistitem>
<seglistitem>
<seg>&gt;</seg>
<seg>Match the end of a word</seg>
</seglistitem>
</segmentedlist>

<para>
For a repeating search, you can also use these operators:
</para>

<segmentedlist>
<segtitle>Expression:</segtitle>
<segtitle>Meaning:</segtitle>
<seglistitem>
<seg>?</seg>
<seg>The preceding item matches less than once</seg>
</seglistitem>
<seglistitem>
<seg>*</seg>
<seg>The preceding item is matched zero or more times</seg>
</seglistitem>
<seglistitem>
<seg>+</seg>
<seg>The preceding item is matched once or more times</seg>
</seglistitem>
<seglistitem>
<seg>{ n }</seg>
<seg>The preceding item is matched exactly <replaceable>n</replaceable> times</seg>
</seglistitem>
<seglistitem>
<seg>{ n,}</seg>
<seg>The preceding item matches <replaceable>n</replaceable> or more times</seg>
</seglistitem>
<seglistitem>
<seg>{,n }</seg>
<seg>The preceding item matches less than <replaceable>n</replaceable> times</seg>
</seglistitem>
<seglistitem>
<seg>{n,m}</seg>
<seg>The preceding item matches at least <replaceable>n</replaceable> times but
less than <replaceable>m</replaceable> times.</seg>
</seglistitem>
</segmentedlist>

<para>
Back references to bracketed sub-expressions are also available with the
notation <userinput>\n</userinput>.
</para>

<para>
After specifying your search, press <guibutton>Search</guibutton>.  The results
are then displayed in the result window.
</para>

<para>
To jump to a file and line number, select the result line and press
<keycap>Enter</keycap> 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.
</para>

<para>
&kdevelop; also offers some more specialized functionality to use
<application>grep</application> with the editor and browser.  Select the
expression you want to search for in either of the windows, and press <keycombo
action="simul"><keycap>Shift</keycap><keycap>F2</keycap></keycombo> or select
<guimenuitem>grep: <replaceable>expression</replaceable></guimenuitem> from the
&RMB; mouse click context menu. This will ask <application>grep</application> to
search for the selection in your project files, and will show the results
immediately.
</para>

<para>
Switching the results window after searching for the selected expression works as described above.
</para>

<para>
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.
</para>

</sect2>

<sect2 id="searching-in-documentation">
<title>Searching Within Documentation</title>

<para>
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.
</para>

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

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

<para>
To invoke a search through the documentation, do the following:
</para>

<procedure>
<step>
<para>
Place your cursor at the word you want to search for, or select an expression.
</para>
</step>
<step>
<para>
Select <guimenuitem>Search marked text</guimenuitem> from the
<guimenu>Help</guimenu> menu, or press the &RMB; mouse button to open the
context menu, and select <guimenuitem>Look Up: "expression"</guimenuitem>
</para>
</step>
<step>
<para>
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.
</para>
</step>
<step>
<para>
The selected documentation page will be displayed and your search results are
marked.
</para>
</step>
<step>
<para>
To display the next result on the same page, press <keycap>F3</keycap>
</para>
</step>
</procedure>

<para>
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
<guimenuitem>Paste</guimenuitem> from the <guimenu>Edit</guimenu> menu.
</para>

<para>
For a full description of how to use the Documentation, see <xref
linkend="using-the-search-index">.
</para>

</sect2>

<sect2 id="replacing-text">
<title>Replacing Text</title>

<para>
To replace an expression, select <guimenuitem>Search and Replace</guimenuitem>
from the <guimenu>Edit</guimenu> menu.
</para>

<para>
The <guilabel>Search and Replace</guilabel> dialog allows you to specify an
expression to be replaced, as well as a replacement expression.
</para>

<para>
When you have filled in the expressions, press <guibutton>OK</guibutton>.
</para>

<para>
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.
</para>

<para>
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 <guibutton>Cancel</guibutton>
</para>

</sect2>

</sect1>

<sect1 id="printing">
<title>Printing</title>

<para>
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 <application>enscript</application>, a common
printing program available for &UNIX; systems.
</para>

<para>
You can also print directly using <command>lpr</command> (the line printer
device). 
</para>

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

<para>
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.
</para>

<sect2 id="configuring-the-printer">
<title>Configuring the Printer</title>

<para>
The printing program can be configured by selecting
<guimenuitem>Print</guimenuitem> from the <guimenu>File</guimenu> menu.
</para>

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

<para>
Press the <guibutton>Options</guibutton> button on the right to open the
configuration dialog for the print program you selected.
</para>

<para>
Another way to access this dialog is to choose <guimenuitem>Printer
Configuration...</guimenuitem> from the <guimenu>Options</guimenu>.
</para>

<para>
The options available to <application>Enscript</application> are described in
the next section.
</para>

<sect3>
<title>The <application>Enscript</application> Configuration Options</title>

<sect4>
<title>Header</title>

<variablelist>
<varlistentry>
<term><guilabel>Fancy Header:</guilabel></term>
<listitem>
<para>
Adds a fancy header
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Header Text:</guilabel></term>
<listitem>
<para>
Enables adding a header text:</para>

<variablelist>
<varlistentry>
<term><guilabel>text:</guilabel></term>
<listitem>
<para>Sets the text contents</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>position:</guilabel></term>
<listitem>
<para>Sets the text position to the left, center or right</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Login:</guilabel></term>
<listitem>
<para>
Add the User ID to the header:
</para>

<variablelist>
<varlistentry>
<term><guilabel>Login:</guilabel></term>
<listitem>
<para>
Enables adding the UserID
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>position:</guilabel></term>
<listitem>
<para>
Sets the position for the UserID
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Filename:</guilabel></term>
<listitem>
<para>
Add the filename to the header:
</para>
<variablelist>
<varlistentry>
<term><guilabel>Size of filename:</guilabel></term>
<listitem>
<para>
Add the filename as either full (with the full path) or short (as a filename
only).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Position:</guilabel></term>
<listitem>
<para>
Sets the position for the filename.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Hostname</guilabel></term>
<listitem>
<para>
Add the hostname to the header:
</para>
<variablelist>
<varlistentry>
<term><guilabel>hostname:</guilabel></term>
<listitem>
<para>
Enables adding the hostname.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Size of hostname</guilabel></term>
<listitem>
<para>
Sets the size of the hostname
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Position:</guilabel></term>
<listitem>
<para>
Sets the position for the hostname.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>

</sect4>

<sect4>
<title>Date and Time</title>

<variablelist>
<varlistentry>
<term><guilabel>Current Date</guilabel></term>
<listitem>
<para>
Include the current date.
</para>
<variablelist>
<varlistentry>
<term><guilabel>Current date</guilabel></term>
<listitem>
<para>
Enables adding the current date.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Position:</guilabel></term>
<listitem>
<para>
Sets the position for the date entry
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Format</guilabel></term>
<listitem>
<para>
Sets the date format
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Modification Date</guilabel></term>
<listitem>
<para>
Include the last modification date.
</para>
<variablelist>
<varlistentry>
<term><guilabel>Modification date:</guilabel></term>
<listitem>
<para>
Enables adding the last modification date.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Position:</guilabel></term>
<listitem>
<para>
Sets the position for the date entry
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Format</guilabel></term>
<listitem>
<para>
Sets the date format
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Current Time:</guilabel></term>
<listitem>
<para>
Include the current time:
</para>
<variablelist>
<varlistentry>
<term><guilabel>Current Time:</guilabel></term>
<listitem>
<para>
Include the current time:
</para>
<variablelist>
<varlistentry>
<term><guilabel>Modification time</guilabel></term>
<listitem>
<para>
Enables adding the modification time.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>AM/PM:</guilabel></term>
<listitem>
<para>
Use AM/PM or 24 hour format.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Position</guilabel></term>
<listitem>
<para>
Sets the position for the time entry.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Format:</guilabel></term>
<listitem>
<para>
Sets the time format
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>

</sect4>

<sect4>
<title>Layout</title>

<variablelist>
<varlistentry>
<term><guilabel>Numbering &amp; Border:</guilabel></term>
<listitem>

<variablelist>
<varlistentry>
<term><guilabel>Numbering lines:</guilabel></term>
<listitem>
<para>
Adds line numbers to the document while printing.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Borders</guilabel></term>
<listitem>
<para>
Adds a border to the page when printing.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Numbering Pages:</guilabel></term>
<listitem>
<para>
Numbers pages for printing.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Align Files:</guilabel></term>
<listitem>
<para>
Appends files one after the other, for page numbering purposes.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Lines Per Page:</guilabel></term>
<listitem>
<para>
The maximum value for lines per page.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Format and TAB</guilabel></term>
<listitem>

<variablelist>
<varlistentry>
<term><guilabel>Set TAB Size:</guilabel></term>
<listitem>
<para>
Sets the TAB size for printing.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Font for Header:</guilabel></term>
<listitem>
<para>
Sets the font used for the header text.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Font for the Body:</guilabel></term>
<listitem>
<para>
Sets the font for the body text (the file contents).
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Text:</guilabel></term>
<listitem>

<variablelist>
<varlistentry>
<term><guilabel>Cut lines:</guilabel></term>
<listitem>
<para>
Cut off the lines if they are too long.  If unchecked, the lines are wrapped
instead.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Replace non-printing characters:</guilabel></term>
<listitem>
<para>
Replaces characters that the printing charset doesn't support with spaces.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Other Options:</guilabel></term>
<listitem>

<variablelist>
<varlistentry>
<term><guilabel>Table of Contents:</guilabel></term>
<listitem>
<para>
Adds a table of contents page that contains information about printed files,
page numbers, &etc;.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Highlight Bars:</guilabel></term>
<listitem>

<variablelist>
<varlistentry>
<term><guilabel>Highlight Bars:</guilabel></term>
<listitem>
<para>
Highlights rows for printing.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Cycle of Change:</guilabel></term>
<listitem>
<para>
Sets the number of rows to change highlight style.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Wrapped Lines:</guilabel></term>
<listitem>
<variablelist>
<varlistentry>
<term><guilabel>Mark Wrapped Lines</guilabel></term>
<listitem>
<para>
Lines that are broken get marked for printing.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Value for wrapped lines:</guilabel></term>
<listitem>
<para>
The preset value for the new line the line is broken into.
<!-- LW: I haven't the faintest clue what this means :) -->
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>

</sect4>

<sect4>
<title>Underlay</title>

<variablelist>
<varlistentry>
<term><guilabel>Text</guilabel></term>
<listitem>
<para>
Sets the text to underlay
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Position:</guilabel></term>
<listitem>
<para>
Sets the position of underlay text.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Font</guilabel></term>
<listitem>
<para>
Sets the font used for the underlay.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Angle:</guilabel></term>
<listitem>
<para>
Sets the angle for the underlay text.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Gray scaling</guilabel></term>
<listitem>
<para>
Sets the grayscaling for the underlay text.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Style</guilabel></term>
<listitem>
<para>
Sets the underlay text to be printed as outlined or filled.
</para>
</listitem>
</varlistentry>

</variablelist>

</sect4>

</sect3>

</sect2>

<sect2 id="printing-dialog">
<title>The Printing Dialog</title>

<sect3 id="direct-printing-options">
<title>Direct Printing Options</title>

<variablelist>
<varlistentry>
<term><guilabel>Program</guilabel></term>
<listitem>
<para>
Sets the printing program to be used for printing.  You can choose between
<application>enscript</application> or <application>lpr</application>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Printer:</guilabel></term>
<listitem>
<para>
Sets the printer to be used for printing.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Output Location:</guilabel></term>
<listitem>
<para>
If you print to a file, choose the location to save the file.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Orientation</guilabel></term>
<listitem>
<para>
Sets the orientation for printing, either landscape or portrait.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Copy:</guilabel></term>
<listitem>
<para>
Sets the number of copies to be printed of each page.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Paper Size:</guilabel></term>
<listitem>
<para>
Sets the paper size to be used.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Output Format:</guilabel></term>
<listitem>
<para>
When using <application>enscript</application>, you can choose between
&PostScript; and <acronym>HTML</acronym> printing.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Default Printsettings:</guilabel></term>
<listitem>
<para>
Sets the default settings to be used for printing.
</para>

<variablelist>
<varlistentry>
<term><guilabel>Out Printing:</guilabel></term>
<listitem>

<variablelist>
<varlistentry>
<term><guilabel>Page Printing:</guilabel></term>
<listitem>
<para>
Sets one or two pages per sheet of paper.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Pages:</guilabel></term>
<listitem>
<para>
Select all, odd, or even (only available with
<application>enscript</application>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Pretty-Print:</guilabel></term>
<listitem>

<variablelist>
<varlistentry>
<term><guilabel>Pretty-Print:</guilabel></term>
<listitem>
<para>
Enables pretty print mode for <application>enscript</application>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Color:</guilabel></term>
<listitem>
<para>
Use color printing.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Pretty Print Mode:</guilabel></term>
<listitem>
<para>
Sets the printing mode, dependent on your file format.
</para>
</listitem>
</varlistentry>

</variablelist>

</listitem>
</varlistentry>
</variablelist>

</listitem>
</varlistentry>
</variablelist>

</listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="printing-file-selection">
<title>File Selection</title>

<para>
The file selection dialog is accessed with the <guibutton>Files</guibutton> on
the printing dialog.
</para>

<para>
The file selection allows you to specify which files to
print through the following criteria:
</para>

<variablelist>
<varlistentry>
<term><guilabel>current</guilabel></term>
<listitem>
<para>
The currently active file in the editor.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>All in project:</guilabel></term>
<listitem>
<para>
All files in the project currently open.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Self chosen files:</guilabel></term>
<listitem>
<para>
Choose the files individually from a file selector.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>All CPP files:</guilabel></term>
<listitem>
<para>
Prints out all the source files of the project.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>All Headers:</guilabel></term>
<listitem>
<para>
Prints out all the header files of the project.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Changed files:</guilabel></term>
<listitem>
<para>
Specify files that were changed during a particular time span:
</para>
<variablelist>
<varlistentry>
<term><guilabel>Between</guilabel></term>
<listitem>
<para>
Specifies files changed after:
</para>
<variablelist>
<varlistentry>
<term><guilabel>Date</guilabel></term>
<listitem>
<para>
The date the files were changed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Time:</guilabel></term>
<listitem>
<para>
The time the files were changed.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>And:</guilabel></term>
<listitem>
<para>
Specifies files changed before:
</para>
<variablelist>
<varlistentry>
<term><guilabel>Date:</guilabel></term>
<listitem>
<para>
The date the files were changed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Time:</guilabel></term>
<listitem>
<para>
The Time the files were changed.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Self Chosen Files:</guilabel></term>
<listitem>
<para>
Becomes active if <guilabel>Self chosen files</guilabel> is selected above. 
</para>
<variablelist>
<varlistentry>
<term><guilabel>Add</guilabel></term>
<listitem>
<para>
Press this to add a selected file for printing to the list on the left.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Delete:</guilabel></term>
<listitem>
<para>
Delete a selected file from the printing list.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Clear:</guilabel></term>
<listitem>
<para>
Clear the printing list.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>

</sect3>

<sect3 id="print-preview">
<title>Print Preview</title>

<para>
The print preview is available for you to check the appearance of the output.
</para>

<para>
&kdevelop; uses the program <application>ghostview</application> or &kghostview;
if available.
</para>

<para>
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.
</para>

</sect3>

</sect2>

</sect1>

</chapter>

<chapter id="projects">
<title>Projects</title>

<para>
&kdevelop; creates a project file with a <literal
role="extension">.kdevprj</literal> extension.  This file contains all your
project information, so be careful not to delete it.
</para>

<para>
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 (<option>CXXFLAGS</option>).
</para>

<sect1 id="project-types">
<title>Project Types</title>

<sect2>
<title>Programs</title>

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

<variablelist>

<varlistentry>
<term>A single document interface (<acronym>SDI</acronym>) application</term>
<listitem>
<para>
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.
</para>

<para>
From a programming point of view, it is based on three application specific
classes, built on the <acronym>MVC</acronym> or
<quote>Model-View-Controller</quote> model.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>A &kde; based application frame.</term>
<listitem>
<para>
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
<quote>wizard</quote> applications or modules.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>A &Qt; based program framework.</term>
<listitem>
<para>
This option is for programmers who want to use only the &Qt; library as the
<acronym>GUI</acronym> 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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>A C++ program framework.</term>
<listitem>
<para>
This application type is intended for those who want to create a terminal based
C++ program.
</para>
<para>
Just remove the <quote>Hello Wold</quote> line in the
<function>main()</function> function, and construct your classes in the usual
&kdevelop; way.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>A C program framework.</term>
<listitem>
<para>
Again aimed at developing terminal based applications, but this time using only
the C compiler.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>A Gnome application</term>
<listitem>
<para>
Allows you to use &kdevelop; to create a GTK+ based application.
</para>
</listitem>
</varlistentry>
</variablelist>

<para>
Additionally, &kdevelop; enables you to work with already existing projects.
</para>

<para>
You can set options yourself for the <filename>configure</filename> and
<filename>Makefile</filename>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.
</para>

<para>
Create a custom project with the application wizard, and add your files to the
project to allow scanning with the <guilabel>Classes</guilabel> browser.
</para>

<para>
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.
</para>

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

</sect2>

<sect2 id="libraries">
<title>Libraries</title>

<para>
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.
</para>

<itemizedlist>
<listitem>
<para>
Whenever your project subdirectory gets another subdirectory containing source
files, &kdevelop; will build a static library of these.
</para>
<para>
This means that static libraries are already supported in an automatic fashion,
in order to sort project source files.  
</para>
<note>
<para>
Be aware that a static library later becomes part of the binary, and is not
installed on your target systems.
</para>
</note>
</listitem>
<listitem>
<para>
To create a shared library, &kdevelop; offers an easy way to convert a static
library as already mentioned, into a shared library:
</para>
<procedure>
<title>Turning a static library into a shared library:</title>
<step>
<para>
Open the <guilabel>Files</guilabel> tree on the left of &kdevelop;'s main
window, and browse to the subdirectory containing your sources. 
</para>
</step>
<step>
<para>
Click with the &RMB; mouse button over the subdirectory.  You will see a context
menu with the following options:
</para>
<itemizedlist>
<listitem>
<para>
<guimenuitem>Update Makefile.am</guimenuitem>
</para>
</listitem>
<listitem>
<para>
<guimenuitem>Change to static lib</guimenuitem>
</para>
</listitem>
<listitem>
<para>
<guimenuitem>Change to shared lib</guimenuitem>
</para>
</listitem>
</itemizedlist>
</step>
<step>
<para>
Select <guimenuitem>Change to shared lib</guimenuitem> to convert the default
generated static library into a shared one.
</para>
</step>
<step performance="optional">
<para>
If you later decide to reverse your change, repeat these steps, but choose
<guimenuitem>Change to static lib</guimenuitem>.
</para>
</step>
</procedure>
</listitem>
</itemizedlist>

</sect2>

<sect2 id="multiple-targets">
<title>Multiple Targets</title>

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

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

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

<para>
Nevertheless, a build process always invokes the <application>make</application>
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.
</para>

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

<para>
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.
</para>

<para>
Multiple binaries or libraries withint he main project subdirectory are
possible, so long as you stick to the rules described in the section 
<link linkend="project-hacking">Project Hacking</link>, and the following
guidelines for editing the main project's <filename>Makefile.am</filename>.  
</para>

<para>
All these modifications should be outside the marked &kdevelop; write area.
</para>

<itemizedlist>
<listitem>
<para>
Add your target to the <varname>bin_PROGRAMS</varname> line if it is an
executable.
</para>
</listitem>
<listitem>
<para>
Add your library declaration line, if it is a shared library.
</para>
</listitem>
<listitem>
<para>
Add the same declarations as for the original project binary build:
</para>
<itemizedlist>
<listitem>
<para>
<varname><replaceable>newtargetnewtarget</replaceable>_METASOURCES</varname>
</para>
</listitem>
<listitem>
<para>
<varname><replaceable>newtarget</replaceable>_LD_FLAGS</varname>
</para>
</listitem>
<listitem>
<para>
<varname>DISTCLEANFILES</varname>
</para>
</listitem>
<listitem>
<para>
Copy the <literal>messages:</literal> entry for the original binary, and replace
<varname><replaceable>target</replaceable>_SOURCES</varname> with
<varname><replaceable>newtarget</replaceable>_SOURCES</varname>, and
<filename><replaceable>target</replaceable>.pot</filename> with
<filename><replaceable>newtarget</replaceable>.pot</filename>.
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Add your sources the same way the &kdevelop; write area contains them, but
outside the write area, and adapting for your binary or library.
</para>
</listitem>
<listitem>
<para>
For installing static libraries, create the library with &kdevelop;'s auto
creation in subdirectories.  Then modify the <filename>Makefile.am</filename>
as required, but outside the &kdevelop; write area.
</para>
</listitem>
</itemizedlist>

</sect2>

</sect1>

<sect1 id="new-projects">
<title>New Projects</title>

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

<para>
For &kde; applications, there are six different frameworks.
</para>

<variablelist>
<varlistentry>
<term>Mini</term>
<listitem>
<para>
Creates a &kde; application, with an empty main widget.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Normal</term>
<listitem>
<para>
Creates a &kde; application with session management, menubar, toolbar,
statusbar, and support for a document-view codeframe model.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Normal-OpenGL</term>
<listitem>
<para>
Creates a &kde; application with session management, menubar, toolbar,
statusbar, and support for a document-view codeframe model.
<trademark>OpenGL</trademark> support with Mesa3D is added.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>&kde; 2 Normal</term>
<listitem>
<para>
Creates a &kde; 2 application, with session management, menubar, toolbar,
statusbar, and support for a document-view codeframe model.
</para>
</listitem>
</varlistentry>


<varlistentry>
<term>&kde; 2 Mini</term>
<listitem>
<para>
Creates a &kde; 2 application with an empty main widget.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>&kde; 2 <acronym>MDI</acronym></term>
<listitem>
<para>
Creates a &kde; 2 <acronym>MDI</acronym> (Multiple Document Interface)
applicatoin with menubar, toolbar, statusbar, and support for a document-view
codeframe model.
</para>
</listitem>
</varlistentry>
</variablelist>

<para>
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:
</para>

<variablelist>
<varlistentry>
<term>Normal</term>
<listitem>
<para>
Creates a &Qt; application with a main window, containing a menubar, toolbar,
and statusbar, and support for a generic document-view model.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>&Qt; 2.x <acronym>SDI</acronym></term>
<listitem>
<para>
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
(<acronym>SDI</acronym>) model.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>&Qt; 2.x <acronym>MDI</acronym></term>
<listitem>
<para>
Creates a &Qt; 2.x application with a main window containing a menubar, toolbar
and a statusbar, with support for a multiple document interface
(<acronym>MDI</acronym>) model.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>QextMDI</term>
<listitem>
<para>
Creates an <acronym>MDI</acronym> framework based on the
<literal>QextMDI</literal> library, and &Qt; 2.x.  This allows you to switch
between two modes, Toplevel and Childframe.  This requires the
<literal>QextMDI</literal> library, see <ulink
url="http://www.geocities.com/gigafalk/qextmdi.htm">http://www.geocities.com/gigafalk/qextmdi.htm</ulink>
page for more details.
</para>
</listitem>
</varlistentry>
</variablelist>

<para>
Note that &Qt; 2 normal and &Qt; 2 <acronym>MDI</acronym> 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.
</para>

<para>
See the section on <link linkend="project-hacking">Project Hacking</link> for
more information.
</para>

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

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

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

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

<para>
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 <literal
role="extension">*.lsm</literal> file.
</para>

<para>
To add revision control to your projects, see the chapter on <link
linkend="cvs-integration">CVS inegration.</link>.
</para>

</sect1>

<sect1 id="opening-and-closing-projects">
<title>Opening and Closing of Projects</title>

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

<para>
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 <guilabel>Load last project:</guilabel> option in the
<link linkend="kdevelop-setup">&kdevelop; Setup</link> dialog.
</para>

<para>
To open another project, select <guimenuitem>Open</guimenuitem> from the
<guimenu>Project</guimenu> menu, or press the <guiicon>Open Project</guiicon>
button on the toolbar.
</para>

<para>
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.
</para>

<para>
You will be presented with an <guilabel>Open Project</guilabel> dialog, where
you can browse to the directory containing the project you wish to load.
&kdevelop; project files have the <literal role="extension">*.kdevprj</literal>
extension, and are displayed with a project icon, to make them easy to find.
</para>

<para>
Select the project file and press <guibutton>Open</guibutton>.
</para>

<para>
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
<guilabel>Classes</guilabel> browser directly.
</para>

<para>
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.  
</para>

<para>
You could also open a project on the command line, entering
<userinput><command>kdevelop</command>
<filename><replaceable>projectname</replaceable>.kdevprj</filename></userinput>.
</para>

<para>
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.
</para>

</sect1>

<sect1 id="editing-a-project">
<title>Editing a Project</title>

<para>
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.
</para>

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

<para>
The next section <link linkend="adding-and-removing-files-and-classes">Adding
and Removing Files and Classes</link>, describes how you can add existing files
and classes, as well as creating new files.
</para>

<para>
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 <link
linkend="setting-project-file-options">Setting Project File Options.</link>
</para>

<para>
Another task in project maintenance is internationalization, which is described
in the the section <link linkend="adding-translations">Adding
Translations</link>.
</para>

<para>The section <link linkend="extending-the-project-documentation">
Extending the Project Documentation</link> 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.
</para>

<para>
Finally, the section <link linkend="project-hacking">Project Hacking</link>
describes how you can work around the &kdevelop; project management, if you have
a special requirement.
</para>

</sect1>

<sect1 id="adding-and-removing-files-and-classes">
<title>Adding and Removing Files and Classes</title>

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

<para>
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
<guimenuitem>New</guimenuitem> from the <guimenu>File</guimenu> menu, which will
open the <guilabel>New File</guilabel> dialog.
</para>

<para>
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.
</para>

<para>
&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.
</para>

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

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

<para>
After the file has been created, the project file will be updated, as will the
corresponding <filename>Makefile.am</filename>s.
</para>

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

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

<note>
<para>
Note that the files will be copied into the specified directory, and added to
the project.
</para>
</note>

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

<para>
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 <link
linkend="setting-project-file-options">Setting Project File Options</link>
covers this process in detail.
</para>

<para>
To add a file to the project that is already in the project directory, go to the
<guilabel>Files</guilabel> view, where all project included files are displayed
with a red <guiicon>!</guiicon> 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
<guimenuitem>Add</guimenuitem>.
</para>

<para>
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.
</para>

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

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

<para>
To delete a file, follow the same procedure, but choose <guimenuitem>Delete
physically</guimenuitem> from the menu.
</para>

</sect1>

<sect1 id="setting-project-file-options">
<title>Setting Project File Options</title>

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

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

<para>
The dialog also shows the installation path, if the file is to be installed on
the end user's computer with the <userinput><command>make</command>
<option>install</option></userinput> 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
<filename>Makefile.am</filename>, where the location macros are specified.
</para>

</sect1>

<sect1 id="adding-translations">
<title>Adding Translations</title>

<para>

</para>

<sect2 id="internationalization-of-kde-2-apps">
<title>Internationalization of &kde; 2.x Applications</title>

<para>
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.
</para>

<para>
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
<filename class="directory">docs</filename> 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 <acronym>SGML</acronym> or <acronym>XML</acronym> file to
the desired language, regenerate the documentation and you are done.
</para>

<para>
For the application interface, things are a little more difficult.
</para>

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

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

<para>
As this macro is declared in the <filename class="headerfile">kapp.h</filename>
include file, you should add <userinput>&num;include &lt;kapp.h&gt;</userinput>
to the source file, or the class declaration file of the class that makes use of
the macro.
</para>

<para>
It should also be noted that although <function>i18n()</function> 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,
<filename><replaceable>YourApp</replaceable>.pot</filename>, in the <filename
class="directory">/po</filename> subdirectory.
</para>

<para>
This task is handled by a program <application>xgettext</application>.
<!-- LW: Check the name.. is it xgettext, or just gettext? -->
As <application>xgettext</application> depends on the
<function>i18n()</function> macro, the original function won't do the job.
</para>

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

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

<para>
An <acronym>ASCII</acronym> 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 <computeroutput>msgid</computeroutput>, containing the
string to translate, followed by <computeroutput>msgstr</computeroutput>.  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.
</para>

<para>
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 
<!-- LW: The old stuff is about KTranslator.. wouldn't it be better to write -->
<!-- about  Kbabel now? --><application>KTranslator</application> which helps
you reuse strings and translations from other applications, to aid in your
translation. 
</para>

<para>
To access <application>KTranslator</application>, the easiest way is selecting a
<filename><replaceable>language</replaceable>.po</filename> file in the
<filename class="directory">/po</filename> directory, in either the
<guilabel>Files</guilabel> pane or the <guilabel>Groups</guilabel> pane.
</para>

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

<para>
For all translation files, <application>make</application> uses the program
<application>msgfmt</application> 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.
</para>

<para>
For more information about internationalization support, see <ulink
url="http://i18n.kde.org/">http://i18n.kde.org/</ulink>, 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.
</para>

</sect2>

<sect2>
<title>Internationalizatoin of &kde; 2.x Applications</title>

<para>
&kde; 2.x projects have a slightly different method of handling <literal
role="extension">po</literal> files and keeping them up to date than &kde; 1
did.
</para>

<para>
The first thing to watch for when generating a &kde; 2.x project is that
<userinput><command>make</command> <option>package-messages</option></userinput>
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. 
</para>

<para>
While merging strings is done by calling <userinput><command>make</command>
<option>merge</option></userinput> in the <literal role="extension">po</literal>
directory in &kde; 1.x, this is now handled automatically when you run
<userinput><command>make</command>
<option>package-messages</option></userinput>.  Obviously this will result in an
error message while initially creating your project with the application wizard.
</para>

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

<para>
What this script does is extract the strings out of your <acronym>XML</acronym>
resource file (<filename><replaceable>yourapp</replaceable>ui.rc</filename>) to
build the application's &GUI;, and then stores these strings in a temporary file
called <filename>rc.cpp</filename>.  This way, the strings in the
<acronym>XML</acronym> file are processed as usual when building the <literal
role="extension">pot</literal> file, and are included in your
internationalization efforts.
</para>

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

</sect2>

<sect2 id="internationalization-of-qt-2-apps">
<title>Internationalization of &Qt; 2.x Applications</title>

<para>
Since &Qt; now includes the <function>tr()</function> method, together with the
<classname>QTranslator</classname>, you can easily internationalize your &Qt;
only project as well.
</para>

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

<para>
The strings inside <function>tr()</function> functions are read into the
language-dependent <literal role="extension">*.ts</literal> files by
<application>lupdate</application>, and <application>lrelease</application> then
covnerts the translated <acronym>XML</acronym> file to a file named <literal
role="extension">*.qm</literal>, which stores the translations in a binary form.
</para>

</sect2>

</sect1>

<sect1 id="extending-project-documentation">
<title>Extending the Project Documentation</title>


<!-- LW: needs an entire rewrite.. and we're updating very soon to XML, so it -->
<!-- should probably cover that rather than sgml -->

<para></para>

</sect1>

<sect1 id="project-hacking">
<title>Project Hacking</title>

<para>
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 <filename>Makefile</filename>s.
</para>

<para>
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 <filename>Makefile.am</filename> macros, but you
should add any custom entries after the section separated with the text
<computeroutput>KDevelop write area</computeroutput>.
</para>

<para>
As the <acronym>GNU</acronym> 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.
</para>

<sect2>
<title>Project Type Definitions</title>

<para>
&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.
</para>

<para>
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.)
</para>

<para>
Change the following sections according to the project type:
</para>

<screen>
<computeroutput>
[General]
author=Ralf Nolden
project_type=normal_kde2
</computeroutput>
</screen>

<para>
Valid project types are:
</para>

<variablelist>
<varlistentry>
<term>normal_empty</term>
<listitem>
<para>
Custom project
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>normal_kde</term>
<listitem>
<para>
KDE 1.x Normal (<acronym>SDI</acronym> project.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>mini_kde</term>
<listitem>
<para>
KDE 1.x Mini project
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>normalogl_kde</term>
<listitem>
<para>
KDE 1.x OpenGL project.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>normal_kde2</term>
<listitem>
<para>
KDE 2.x Normal (<acronym>SDI</acronym>) project.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>mini_kde2</term>
<listitem>
<para>
KDE 2.x Mini project.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>mdi_kde2</term>
<listitem>
<para>
KDE 2.x <acronym>MDI</acronym> project.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>normal_qt</term>
<listitem>
<para>
&Qt; 1.44 project (<acronym>SDI</acronym>).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>normal_qt2</term>
<listitem>
<para>
&Qt; 2.2.x project (<acronym>SDI</acronym>).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>mdi_qt2</term>
<listitem>
<para>
&Qt; 2.x project (<acronym>MDI</acronym>, uses
<classname>QWorkspace</classname>.)
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>mdi_qextmdi</term>
<listitem>
<para>
&Qt; 2.x project (uses the QextMDI library.)
</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>
<!-- LW: I think this should be with the other Qt stuff -->
<sect2>
<title>Converting <literal role="extension">*.kdevdlg</literal> files</title>

<para>
&kdevelop; comes with a converter script, <filename>kdevdlg2ui</filename>, to
turn already constructed dialogs from previous versions of &kdevelop; into
<literal role="extension">.ui</literal> files.
</para>

<para>
You should be aware that you may have to re-inherit from the class gernerated by
&Qt;'s <command>uic</command>, 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 <literal role="extension">.ui</literal> file may be necessary, as well
as inheriting from it's generated class.
</para>

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

</sect2>

</sect1>

<sect1 id="compiler-and-linker-flags-for-projects">
<title>Compiler and Linker Flags for Projects</title>

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

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

<para>
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 <guilabel>Project Options</guilabel> dialog.
</para>

<para>
See <link linkend="build-settings">Build Settings</link> for more information
how and where to set compiler options, warnings, and linker options.
</para>

</sect1>

<sect1 id="external-projects">
<title>External Projects</title>

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

<para>
After the project file has been built, you should edit it with your favorite
editor, setting the project type according to your needs.  See <link
linkend="project-hacking">Project Hacking</link> for more details about
available project types.
</para>

<para>
Be careful to deselect <guilabel>Modify Makefiles</guilabel> in the
<guilabel>Project Options</guilabel> after you load your project for the first
time.
</para>

<!-- LW A reason to deselect that option might be helpful there -->

</sect1>

</chapter>

<chapter id="build-settings">
<title>Build Settings</title>

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

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

<para>
Debugging is only available if the project options are set to create debugging
information.  The amount can be set with the <guilabel>debug level</guilabel>,
between <option>0</option> and <option>3</option>.  
</para>

<para>
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.
</para>

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

<itemizedlist>
<listitem>
<para>
Disable debugging.
</para>
</listitem>
<listitem>
<para>
Enable optimization, and set optimization level to <option>-02</option>.
</para>
</listitem>
<listitem>
<para>
Set the compiler warnings to <option>-Wall</option>.
</para>
</listitem>
<listitem>
<para>
For each new release, increment the version number and update the
<filename>project.lsm</filename> file with the new version and any changed
requirements.
</para>
</listitem>
</itemizedlist>

<sect1 id="build-settings-general">
<title><guilabel>General Options</guilabel></title>

<para>
The first page of the <guilabel>Project Options</guilabel> dialog sets the
general options for your project.  These are the <guilabel>Project
name:</guilabel> and <guilabel>Version:</guilabel>, the handbook
<acronym>SGML</acronym> 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.
</para>

<!-- LW
  Make proper list of options and descriptions:
  Project Name:
  Version:
  Author:
  Email:
  Modify Makefiles (check box)
  Version Control: CVS/None
  Short Information
     -->

</sect1>

<sect1 id="compiler-options">
<title><guilabel>Compiler Options</guilabel></title>

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

<variablelist>
<varlistentry>
<term><guilabel>Target Machine</guilabel></term>
<listitem>
<para>
Choose the target from the drop down list.  The choices currently available are
<guilabel>your machine</guilabel> or <guilabel>i386v</guilabel>.  The latter is
an option if you have configured your compiler as a cross compiler for an
<trademark>Intel</trademark> 386 compatible machine running System V.  This is
the equivalent of setting the <option>-b</option> on the compiler.  The default
(<guilabel>your machine</guilabel>) is normally the right choice.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>optimize</guilabel></term>
<listitem>
<para>
Select this check box if you want to compile a binary optimized for your target
system, as selected in the drop down list above.  
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Optimization level</guilabel></term>
<listitem>
<para>
Choose the level of optimization to be used when building.  Choose from a range
between <guilabel>0</guilabel> (no optimization) and <guilabel>3</guilabel>
(highly optimized).  This is the equivalent of setting the <option>-O</option>
compiler flag.  For a release version of your applicaiton, enable optimization,
and set the level to <guilabel>2</guilabel>.
</para>
</listitem>
</varlistentry>
</variablelist>

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

<variablelist>
<varlistentry>
<term><guilabel>generate debugging information</guilabel></term>
<listitem>
<para>
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 <option>-g</option> flag for the compiler.
</para>
</listitem>
</varlistentry>

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

<varlistentry>
<term><guilabel>generate extra information for gprof</guilabel></term>
<listitem>
<para>
This sets the <option>-pg</option> flag, with the result that the compiler will
include extra information, which the <command>gprof</command> program can use to
generate graphs of your program's functions.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Store temporary intermediate files</guilabel></term>
<listitem>
<para>
This sets the <option>-save-temps</option> 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 <literal
role="extension">.o</literal> file that you would normally expect as the output
of the compiler, an <literal role="extension">.i</literal> file as produced by
the preprocessor, and an <literal role="extension">.s</literal> file as the
output of the assembler.
</para>
</listitem>
</varlistentry>

</variablelist>

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

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

</sect1>

<sect1 id="compiler-warnings">
<title>Compiler Warnings</title>

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

<variablelist>
<varlistentry>
<term><option><guilabel>-Wall</guilabel></option></term>
<listitem>
<para>
Standard <option>-W</option> options combined.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-W</guilabel></option></term>
<listitem>
<para>
Compile with <option>-W</option>. This option sets options not included in
<option>-Wall</option> which are very specific.  Please read
<command>gcc</command> <command>info</command> for more information.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wtraditional</guilabel></option></term>
<listitem>
<para>
Warn about certain contsructs that behave differently in traditional and
<acronym>ANSI</acronym> C.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wundef</guilabel></option></term>
<listitem>
<para>
Warn if an undefined identifier is evaluated in an
<userinput>&num;if</userinput> directive.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wshadow</guilabel></option></term>
<listitem>
<para>
Warn whenever a local variable shadows another local variable.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wid-clash-<replaceable>LEN</replaceable></guilabel></option></term>
<listitem>
<para>Warn whenever two distinct identifiers match in the first
<replaceable>LEN</replaceable> characters.  This may help you prepare a program
to compile with certain obsolte, brain-damaged compilers.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wlarger-than-<replaceable>LEN</replaceable></guilabel></option></term>
<listitem>
<para>
Warn whenever an object larger than <replaceable>LEN</replaceable> bytes is
defined.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wpointer-arith</guilabel></option></term>
<listitem>
<para>
Warn about anything that depends on the <quote>size of</quote> a function type
or of void.  <acronym>GNU</acronym> C assigns these types a size of
<returnvalue>1</returnvalue>, for convenience in calculations with <literal>void
* pointers</literal> and pointers to functions.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wbad-function-cast</guilabel></option></term>
<listitem>
<para>
Warn when a function call is cast to a non matching type.  For example, warn if
<function>int malloc()</function> is cast to <literal>anything *</literal>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wcast-equal</guilabel></option></term>
<listitem>
<para>
Warn whenever a pointer is cast so as to remove a type qualifier from the target
type.  For example, warn if a <literal>const char *</literal> is cast to an
ordinary <literal>char *</literal>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wcast-align</guilabel></option></term>
<listitem>
<para>
Warn whenever a pointer is cast such tha the required alignment of the target is
increased.  For example, warn if a <type>char *</type> is cast to an <type>int
*</type> on machines where integers can only be accessed at two- or four-byte
boundaries.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wwrite-strings</guilabel></option></term>
<listitem>
<para>
Give string constants the <type>const char[length]</type> so that copying the
address of one into a non-const <type>char *</type> 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
<literal>const</literal> in declarations and prototypes.  Otherwise, it will
just be a nuisance.  This is why we did not make <option>-Wall</option> request
these warnings.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wconversion</guilabel></option></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wsign-compare</guilabel></option></term>
<listitem>
<para>
Warn when a comparison between signed and unsigned values could produce an
incorrect result when the signed value is converted to unsigned.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Waggregate-return</guilabel></option></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wmissing-prototypes</guilabel></option></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wmissing-declarations</guilabel></option></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wredundant-decls</guilabel></option></term>
<listitem>
<para>
Warn if anything is declared more than once in the same scope, even in cases
where multiple declarations is valid and changes nothing.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wnested-externs</guilabel></option></term>
<listitem>
<para>
Warn if an extern declaration is encountered within a function.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Winline</guilabel></option></term>
<listitem>
<para>
Warn if a function can not be inlined, and either it was declared as inline, or
else the <option>-fin*line-functions</option> option was given.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wold-style-cast</guilabel></option></term>
<listitem>
<para>
Warn if an old style (C style) cast is used within a program.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Woverloaded-virtual</guilabel></option></term>
<listitem>
<para>
(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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><option><guilabel>-Wsynth</guilabel></option></term>
<listitem>
<para>
Warn when <command>g++</command>'s synthesis behaviour does not match that of
cfront.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>make all Warnings into errors</guilabel></term>
<listitem>
<para>
This sets the <option>-Werror</option> flag, telling the compiler to treat
warnings as errors, and abort compilation after any warning.
</para>
</listitem>
</varlistentry>

</variablelist>

<para>
For a release of your project, it is recommended to enable
<option>-Wall</option>
</para>

</sect1>

<sect1 id="linker-options">
<title><guilabel>Linker Options</guilabel></title>

<para>
The <option>Linker Options</option> 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
<classname>KFileDialog</classname>, which is part of the KFile library, you
should enable <guilabel>kfile</guilabel>.</para>

<para>
For classes or or functions that are not listed as checkboxes, use the
<guilabel>additional libraries:</guilabel> field.  
</para>

<para>
Other options available to you are:
</para>

<variablelist>
<varlistentry>
<term><guilabel>remove all symbol table and relocation information from the
executable:</guilabel></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>prevent using shared libraries</guilabel></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>additional flags</guilabel></term>
<listitem>
<para>
Here you can enter any further flags for the linker.  This will result in
<command>make</command> setting the <envar>LDFLAGS</envar> environment variable
for the duration of the compile.  The available options can be taken from the
man page for <command>ld</command>, or from your compiler documentation.
</para>
</listitem>
</varlistentry>
</variablelist>

<sect2>
<title><guilabel>Libraries</guilabel></title>

<para>
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.
</para>

<para>
The libraries that are available as checkboxes are:
</para>

<variablelist>
<varlistentry>
<term><guilabel>X11</guilabel></term>
<listitem>
<para>
The X11 library.  Recommended for all &X; programs.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Xext</guilabel></term>
<listitem>
<para>
The X11 extension library. Almost all &X; programs also depend on this.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>qt</guilabel></term>
<listitem>
<para>
The &Qt; library.  Obviously recommended for &Qt; and &kde; applications.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>kdecore</guilabel></term>
<listitem>
<para>
The &kde; core library, contains the classes for &kde; application frameworks.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>kdeui</guilabel></term>
<listitem>
<para>
The &kde; user interface library, containing &kde; specific widgets.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>khtmlw</guilabel></term>
<listitem>
<para>
The KHTML widget library.
</para>
</listitem>
</varlistentry>

<varlistentry><!-- FIXME: is it still called libkfm? -->
<term><guilabel>kfm</guilabel></term>
<listitem>
<para>
The KFM library containing classes for KFM functions
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>kfile</guilabel></term>
<listitem>
<para>
The KFile library, containing file dialogs &etc;
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>kspell</guilabel></term>
<listitem>
<para>
The KSpell library.  Contains an interface for programs to use
<command>ispell</command> for spell checking.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>kab</guilabel></term>
<listitem>
<para>
The &kab; library, necessary for access to the address book, as well as
providing addressbook widgets.
</para>
</listitem>
</varlistentry>

</variablelist>

<para>
You can enter any additional libraries that your application needs in the
<guilabel>additional libraries</guilabel> field.  Set the libraries with the
<option>-l</option>, for example, <option>-lkom</option>.
</para>

</sect2>

</sect1>

<sect1 id="make-options">
<title><guilabel>Make Options</guilabel></title>

<para>
As <acronym>GNU</acronym> <command>make</command> supports some useful options,
the <guilabel>Project Options</guilabel> dialog contains a page called
<guilabel>Make Options</guilabel> where they can be enabled or disabled.
</para>

<para>
The available settings are:
</para>

<variablelist>
<varlistentry>
<term><guilabel>Print debug information</guilabel></term>
<listitem>
<para>
Print out all information about the project files, and what
<command>make</command> determines for rebuilding them.
</para><!-- FIXME: that last paragraph doesn't make any sense -->
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Continue after errors</guilabel></term>
<listitem>
<para>
Tries to continue with the compilation after an error occurred, &eg; if a file
couldn't be compiled due to an error, <command>make</command> will carry on with
the next file.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Print the data base</guilabel></term>
<listitem>
<para>
Prints out the <command>make</command> database for the current process, which
contains the changes from the last build run.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Environment variables</guilabel></term>
<listitem>
<para>
Give the current environment variables a higher priroity than the ones currently
set in the <filename>Makefile</filename>s.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>No built-in rules</guilabel></term>
<listitem>
<para>
Doesn't use built-in rules for <command>make</command>
</para> <!-- FIXME: built into what? make? kdevelop? -->
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Touch files</guilabel></term>
<listitem>
<para>
Don't run the compiler on changed files, instead only touch them.  This sets
them as already processed by <command>make</command>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Ignore all errors</guilabel></term>
<listitem>
<para>
Ignores all errors that occur.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Silent operation</guilabel></term>
<listitem>
<para>
Doesn't print out any information about the build process.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Print working directory</guilabel></term>
<listitem>
<para>
Prints the current directory during the make process.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>job number</guilabel></term>
<listitem>
<para>
Sets the amount of parallel processes for <command>make</command>.  For a single
<acronym>CPU</acronym> system, we recommend setting this to one or two.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>set modified</guilabel></term>
<listitem>
<para>
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 <command>make</command> and compiled if it is a source
file.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>additional options</guilabel></term>
<listitem>
<para>
Set additional options for <command>make</command>.  The options available to
you can be found in your local man page for <acronym>GNU</acronym>
<command>make</command>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Rebuild behavior on run</guilabel></term>
<listitem>
<para>
Sets the actions taken when you choose <guimenuitem>run</guimenuitem>.  There
are three options available:
</para>

<variablelist>
<varlistentry>
<term><guilabel>Always Rebuild</guilabel></term>
<listitem>
<para>
Always rebuild the entire application, without checking for modified files.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Warning on modification</guilabel></term>
<listitem>
<para>
Warn if the sources have been modified, and ask if the project should be
rebuilt.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Only on modification</guilabel></term>
<listitem>
<para>
Check if sources have been changed, and rebuild if so.
</para>
</listitem>
</varlistentry>

</variablelist>

<para>
The default is to alays rebuild.
</para>

</listitem>
</varlistentry>

</variablelist>

</sect1>

</chapter>

<chapter id="class-browser">
<title>The <guilabel>Classes</guilabel> Browser</title>
<para>
The &kdevelop; <guilabel>Classes</guilabel> viewer is one of the most useful and
important tools the &IDE; provides the developer for managing his sources.
</para>

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

<para>
This chapter shows you how to use the <guilabel>Classes</guilabel> viewer, and
how to let the provided functionality eas your workload.
</para>

<sect1 id="class-viewer">
<title>The <guilabel>Classes</guilabel> Viewer</title>

<para>
<!-- Screenshot here -->
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.
</para>

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

<para>
<!-- screenshot here too -->
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 <guilabel>Classes</guilabel> viwer
context menus, and include:
</para>

<variablelist>
<varlistentry>
<term><guimenuitem>Goto Declaration:</guimenuitem></term>
<listitem>
<para>
Browse to the declaration of the method.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Goto Definition:</guimenuitem></term>
<listitem>
<para>
Browse to the definition of the method.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Goto Class Declaration:</guimenuitem></term>
<listitem>
<para>
Browse to the class declaration.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>New Class:</guimenuitem></term>
<listitem>
<para>
Opens the <guilabel>New Class</guilabel> dialog to construct a new class.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Add Method:</guimenuitem></term>
<listitem>
<para>
Adds a method to the selected class.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Add Attribute</guimenuitem></term>
<listitem>
<para>
Adds an attribute to the selected class.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Show graphical classview:</guimenuitem></term>
<listitem>
<para>
Opens the graqphical inheritance tree.
</para>
</listitem>
</varlistentry>
</variablelist>

<sect2>
<title>Available Objects</title>

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

<para>
The tree contains both a <guilabel>Classes</guilabel> folder and a
<guilabel>Globals</guilabel> folder.
</para>

<para>
The <guilabel>Classes</guilabel> 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.
</para>

<para>
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
<literal>public</literal>, <literal>private</literal>, and
<literal>protected</literal>, these are indicated by modified icons.
</para>

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

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

<para>
To access these objects,  the viewer provides the <guilabel>Globals</guilabel>
folder, containing the subfolders for the following object types:
</para>

<itemizedlist>
<listitem>
<para>
Structs
</para>
</listitem>
<listitem>
<para>
Functions
</para>
</listitem>
<listitem>
<para>
Variables
</para>
</listitem>
</itemizedlist>

<para>
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.
</para>

<para>
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.
</para>

</sect2>

<sect2>
<title>Browsing Object Declarations and Implementations</title>

<para>
The <guilabel>Classes</guilabel> 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.
</para>

<para>
Selections made here with a mouse click will result in the following actions:
</para>

<variablelist>
<varlistentry>
<term>On a class name:</term>
<listitem>
<para>
Switches you to the class declaration.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>On a class method:</term>
<listitem>
<para>
Switches you to the method implementation.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>On a class attribute:</term>
<listitem>
<para>
Switches to the attributes declaration within the class declaration.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>On a struct:</term>
<listitem>
<para>
Switches to the struct's declaration.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>On a global function:</term>
<listitem>
<para>
Switches to the function's implementation.
</para>
</listitem>
</varlistentry>

</variablelist>

<para>
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:
</para>

<variablelist>
<varlistentry>
<term><guimenuitem>Go to definition:</guimenuitem></term>
<listitem>
<para>
Switch to the implementation.  This is the default behavior, which you can also
access with a &LMB; click.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Go to declaration:</guimenuitem></term>
<listitem>
<para>
Switch to the declaration of the method or function.
</para>
</listitem>
</varlistentry>

</variablelist>

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

<para>
The next section will give you a description of the other tools that the
<guilabel>Classes</guilabel> 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.
</para>

</sect2>

</sect1>

<sect1 id="class-tools">
<title>The Class Tools</title>

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

<para>
The <guilabel>Classes</guilabel> 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.
</para>

<para>
The classtool is invoked from the context menu over a class in the
<guilabel>Classes</guilabel> viewer tree.  Choose
<guimenuitem>Properties</guimenuitem> and the dialog will appear. 
</para>

<!-- Screenshot here -->

<para>
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.
</para>

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

<variablelist>
<varlistentry>
<term><guiicon><!-- screenie --> Show Parents</guiicon></term>
<listitem>
<para>
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 <classname>QWidget</classname> or <classname>QDialog</classname>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guiicon><!-- screenie --> Show children</guiicon></term>
<listitem>
<para>
Displays the children classes that inherit the currently selected class.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guiicon><!-- screenie --> Show Clients</guiicon></term>
<listitem>
<para>
Shows classes that make use of the selected class through an attribute in their
class declaration.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guiicon><!-- screenie --> Show  Suppliers</guiicon></term>
<listitem>
<para>
Show the suppliers that give attributes to the selected class.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guiicon><!-- screenie --> Show Attributes</guiicon></term>
<listitem>
<para>
Show the attributes of the class.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guiicon><!-- screenie --> Show methods</guiicon></term>
<listitem>
<para>
Show the methods of the selected class.
</para>
</listitem>
</varlistentry>
</variablelist>

<para>
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
<guilabel>all</guilabel>, but you can filter by <guilabel>public</guilabel>,
<guilabel>protected</guilabel> or <guilabel>private</guilabel>.
</para>

</sect1>

<sect1 id="managing-classes">
<title>Managing Classes</title>

<para>
</para>

<!-- FIXME: This stuff needs much more writing about -->
<!-- 
Tabs: Attributes 
Methods
Signals
Slots
Connection Implementation

Context menu:
Add member function... - methods tab
Add member variable... - attributes tab
Add signal... - Signals tab
Add slot... - Slots tab
-->

</sect1>

</chapter>

<chapter id="using-qt-designer-in-your-project">
<title>Using &Qt; <application>Designer</application> in Your Project</title>

<para>
The &Qt; <application>Designer</application> 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.
</para>

<para>
Using the <application>Designer</application> 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 <quote>difficult</quote> parts that normally take a long time to
implement.
</para>

<para>
After that, the <quote>rest</quote> of your work is implementing the
functionality in the generated code.
</para>

<para>
This chapter deals with how to use the <application>Designer</application> 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.
</para>

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

<para>
The following sections give you an overview of the
<application>Designer</application>'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. 
</para>

<para>
For more in depth information, you might want to have a look at the <ulink
url="http://doc.trolltech.com/designer/book1.html">Designer tutorial from
Trolltech</ulink>, which can also be found offline in &kdevelop;'s documentation
browser.
</para>

<!-- a note about setting it up with KDE widgets and a link to where the -->
<!-- instructions are would be nice here -->

<sect1 id="create-a-new-dialog-with-the-designer">
<title>Create a New Dialog With the Designer</title>

<para>
If you want to create a new dialog, simply add a new
<application>Designer</application> file.
</para>

<para>
On the menu bar choose <menuchoice><guimenu>File</guimenu>
<guimenuitem>New</guimenuitem></menuchoice>.  From the choices offered, choose
<guilabel>Qt Designer file</guilabel>, and enter a name (for our examples, enter
<userinput><filename>ktestdlg.ui</filename></userinput>.)
</para>

<para>
The <literal role="extension">.ui</literal> file is where the
<application>Designer</application> stores the information about the dialog.
</para>

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

<para>
The <application>Designer</application> presents you with an empty form, called
<guilabel>Form1</guilabel>, and the <guilabel>Property Editor</guilabel>.
</para>

<para>
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 <guilabel>name</guilabel> property from <guilabel>Form1</guilabel>
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 <userinput>KTestDlg</userinput>.
</para>

<para>
In order to become familiar with the <application>Designer</application>, we
recommend reading the <ulink url="http://doc.trolltech.com/designer/book1.html">
Designer handbook</ulink>.  It provides vital information about the usage of the
<application>Designer</application> user interface, and the concepts behind
signal and slot handling inside the <application>Designer</application>.
</para>

<sect2>
<title>Excursion: how <literal role="extension">.ui</literal> Files Become
Source</title>

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

<para>
The answer is <quote>easily!</quote>. &kdevelop; takes care of this!  It adds
the <literal role="extension">.ui</literal> to the <filename>Makefile</filename>
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.
</para>

<para>
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.
</para>

</sect2>

</sect1>

<sect1 id="using-your-new-dialog-in-kdevelop">
<title>Using Your New Dialog Inside &kdevelop;</title>

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

<para>
From the <guimenu>Project</guimenu> menu, choose <guimenuitem>New
Class</guimenuitem>.  Enter <userinput>KTest</userinput> as classname.  Since we
will derive from <classname>KTestDlg</classname>, enter
<userinput>KTestDlg</userinput> in <guilabel>Baseclass</guilabel>.
</para>

<para>
As <classname>QDialog</classname> (the baseclass for our dialog) derives from
<classname>QWidget</classname>, you will also need to enable the
<guilabel>generate a QWidget child class</guilabel> checkbox.
</para>

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

<sect2>
<title>Dialing With Virtual Slots</title>

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

<note>
<para>
Do <emphasis>not</emphasis> call the underlying virtual function (&eg;
<function>KTestDlg::slotCancel()</function>) in the overriding method!
</para>
</note>

</sect2>

</sect1>

</chapter>

<chapter id="internal-debugger">
<title>The Internal Debugger</title>

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

<para>
Click on <guilabel>Use external debugger</guilabel> 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.
</para>

<para>
Selecting the internal debugger enables an additional set of options you can
choose from:
</para>

<variablelist id="debugger-options">
<varlistentry>
<term><guilabel>Display static members</guilabel></term>
<listitem>
<para>
Displaying static members makes <command>gdb</command> slower in producing data
within &kde; and &Qt;.  It may change the <quote>signature</quote> of the data
which <classname>QString</classname> and friends rely on. However, if you need
to debug into these values, then check this option.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Display mangled names</guilabel></term>
<listitem>
<para>
When displaying the disassembled code, you can select to see the methods mangled
names.  However, non-mangled names are easier to read.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Try setting breakpoints on lib load</guilabel></term>
<listitem>
<para>
This will try to set pending breakpoints on loading a library.  If
<command>gdb</command> hasn't seen a library that will be loaded via
<command>dlopen</command>, then it will refuse to set a breakpoint in that code.
We can get <command>gdb</command> to stop on a library load, and then try to set
the pending breakpoints.  See <link
linkend="shared-libraries-and-breakpoints">Shared Libraries and
Breakpoints</link> for more details and a <quote>gotcha</quote> relating to this
behavior.  If you are not using <command>dlopen</command> to open libs, leave
this option off.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Enable floating toolbar</guilabel></term>
<listitem>
<para>
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 <acronym>GUI</acronym> applications. For details, see <link
linkend="floating-toolbar">The Floating Toolbar</link>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Enable separate terminal for application i/o</guilabel></term>
<listitem>
<para>
This allows you to enter terminal input when your application contains terminal
input code (&eg; <literal>cin</literal>, <literal>fget</literal>s, &etc;)  If
you use terminal input in your app, then tick this option, otherwise leave it off.
</para>
<tip>
<para>
This option is most useful if you use it in combination with the <link
linkend="floating-toolbar">The Floating Toolbar</link>, because this way, the
terminal window won't be hidden behind the &kdevelop; window when you control
the debugger.
</para>
</tip>
</listitem>
</varlistentry>

</variablelist>

<sect1 id="using-the-internal-debugger">
<title>Using the Internal Debugger</title>

<para>
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
<guimenu>Debug</guimenu> menu and the toolbar.
</para>

<variablelist>
<title>On the tree view window</title>
<varlistentry>
<term><!--  I don't get a VAR tab, only a Watch one -->
<guilabel>Watch</guilabel></term>
<listitem>
<para>
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. <!-- FIXME: I think this section needs some work -->
</para>
</listitem>
</varlistentry>
</variablelist>

<variablelist>
<title>On the output view window</title>
<varlistentry>
<term><guilabel>breakpoint</guilabel></term>
<listitem>
<para>
A list of breakpoints set, and their current state.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>framestack</guilabel></term>
<listitem>
<para>
The calling stack.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>disassemble</guilabel></term>
<listitem>
<para>
A machine instruction view of the code showing the current instruction to be
executed.
</para>
</listitem>
</varlistentry>
</variablelist>

<formalpara>
<title>On the panel</title>
<para>
Two new icons and two new combo boxes to control the debugger functions
will become available as soon as you start the debugger. 
<!-- This could do with a little more info, maybe a screenie -->
</para>
</formalpara>

<formalpara>
<title>In the <guimenu>Debug</guimenu> menu</title>
<para>
When you start debugging, ten items to control the debugger will be enabled.
</para>
</formalpara>

<variablelist>
<varlistentry>
<term><guimenuitem>Run</guimenuitem></term>
<listitem>
<para>
Continue the program from the current point.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Run to cursor</guimenuitem></term>
<listitem>
<para>
Execute the program up to the current cursor position.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Step over</guimenuitem></term>
<listitem>
<para>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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Step over i(nstruction</guimenuitem></term>
<listitem>
<para>
Execute one machine instruction as above.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Step in</guimenuitem></term>
<listitem>
<para>
Execute exactly one line of source code.  This means you will <quote>step
into</quote> the current function, if necessary.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Step in i(nstruction)</guimenuitem></term>
<listitem>
<para>
Execute one machine instruction as above.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Step out</guimenuitem></term>
<listitem>
<para>
Run to the end of the current stack frame (function.)
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guisubmenu>Viewers</guisubmenu></term>
<listitem>
<para>
Allows a variety of views into the data.  Currently implemented views are:
</para>

<itemizedlist>
<listitem>
<para>
<guimenuitem>Memory address</guimenuitem>
</para>
</listitem>
<listitem>
<para>
<guimenuitem>Disassemble code</guimenuitem>
</para>
</listitem>
<listitem>
<para>
<guimenuitem>Current registers</guimenuitem>
</para>
</listitem>
<listitem>
<para>
<guimenuitem>Current libraries</guimenuitem>
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Interrupt</guimenuitem></term>
<listitem>
<para>
Stop the application executing.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Stop</guimenuitem></term>
<listitem>
<para>
Stop the application executing and exit the debugger.
</para>
</listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="details">
<title>Details</title>

<sect2>
<title>Breakpoints</title>

<para>
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.
</para>

</sect2>

<sect2>
<title>Set/Unset Breakpoints</title>

<para>
Setting breakpoints is a simple one click operation.  Click on the icon border
to the left of the text in the editor <!-- this needs a screenshot --> at the
line you want the breakpoint.  Click again on this line to unset the breakpoint.
</para>

</sect2>

<sect2>
<title>Alternative Breakpoint Manipulation Via Menus</title>

<para>
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 <guimenuitem>remove this breakpoint</guimenuitem>, <guimenuitem>clear all
breakpoints</guimenuitem>, or <guimenuitem>edit the breakpoint</guimenuitem>.
</para>

</sect2>

<sect2>
<title>Editing Breakpoints</title>

<para>
Use the above menu to display the <guilabel>Edit Breakpoint</guilabel> dialog.
This contains the following fields:
</para>

<variablelist>
<varlistentry>
<term><guilabel>Conditional</guilabel></term>
<listitem>
<para>
Enter the condition that must be met before <command>gdb</command> will
interrupt the program execution.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Ignore Count</guilabel></term>
<listitem>
<para>
How many times you want to the code to pass through this breakpoint before
<command>gdb</command> interrupts the program execution.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Enable</guilabel></term>
<listitem>
<para>
When enabled, <command>gdb</command> will break at this breakpoint.  When
disabled, <command>gdb</command> will not break here.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2>
<title>Clear all breakpoints</title>

<para>
This menu entry removes all the breakpoints for this program.  Use it carefully!
</para>

</sect2>

<sect2>
<title>Set/Unset Watchpoints</title>

<para>
In the <guilabel>VAR</guilabel> 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 has moved.. where to? --> 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.
</para>

<warning>
<para>
This is known to be problematic, so use caution when setting watchpoints on
local variables.
</para>
</warning>

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

</sect2>

<sect2>
<title>Set/Unset Watch Variables</title>

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

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

</sect2>

<sect2>
<title>Changing Variable Values</title>

<para>
You can change a variable value in the <guilabel>Watch</guilabel> vew.  If you
have a variable <varname>test</varname>, then to set <varname>test</varname> to
<returnvalue>5</returnvalue>, type
<userinput><varname>test</varname>=<returnvalue>5</returnvalue></userinput> in
the watch field, and add it to the list.  Note that <varname>test</varname> will
then be set to <returnvalue>5</returnvalue> <emphasis>every</emphasis> 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.
</para>

</sect2>

</sect1>

<sect1 id="floating-toolbar">
<title>The Floating Toolbar</title>

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

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

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

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

<para>
Besides the <link linkend="debug-menu">functions available from the
<guimenu>Debug</guimenu> menu</link>, the floating toolbar offers two additional
functions:
</para>

<variablelist>
<varlistentry>
<term><guiicon>Set focus on KDevelop <!-- Screenshot --></guiicon></term>
<listitem>
<para>
Set the focus back on &kdevelop;
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guiicon>Set focus on application <!-- Screenshot --></guiicon></term>
<listitem>
<para>
This sets the focus on the window that had the focus when you pressed the
<guiicon>Set focus on KDevelop</guiicon> 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.
</para>
</listitem>
</varlistentry>
</variablelist>

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

</sect1>

<sect1 id="shared-libraries-and-breakpoints">
<title>Shared Libraries and Breakpoints</title>

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

<para>
There is a reasonable solution, which is to have <command>gdb</command> tell us
when a shared library has been opened.  This is done by setting <option>stop on
1</option>.
</para>

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

<para>
This is known as <quote>lazy breakpoints</quote>.
</para>

<para>
This can however lead to a problem when you use the <command>step over</command>
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
<command>continue</command> (&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 <command>dlopen</command> command.  This can be
disconcerting, but it cannot be helped. 
</para>

</sect1>

</chapter>

<chapter id="cvs-integration">
<title><acronym>CVS</acronym> Integration</title>

<para>
Among it's many features, &kdevelop; also handles managing your project via
<acronym>CVS</acronym> repositories.
</para>

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

<para>
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 <acronym>CVS</acronym> by the developers.
</para>

<para>
Locally, the developer works on his own copy of the <acronym>CVS</acronym>
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 <acronym>CVS</acronym> repository.  The other developers will then
receive the changes the next time they update their own local copy of the
<acronym>CVS</acronym> tree.
</para>

<sect1 id="creating-a-repository">
<title>Creating a Repository</title>

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

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

<para>
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:
</para>

<procedure>
<step>
<para>
Create your project locally.
</para>
</step>
<step>
<para>
Import the project source tree as a module on the <acronym>CVS</acronym> server.
</para>
</step>
<step>
<para>
Delete the local project source tree.
</para>
</step>
<step>
<para>
Check out the project source tree from <acronym>CVS</acronym>.
</para>
</step>
<step>
<para>
After loading the project file from the <acronym>CVS</acronym> copy you checked
out, enable <acronym>CVS</acronym> support in the <guilabel>Project
Options</guilabel> dialog, as described below, 
</para>
</step>
</procedure>

</note>

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

<para>
The options available to you are:
</para>

<variablelist>
<varlistentry>
<term><guilabel>VCS Location</guilabel></term>
<listitem>
<para>
This is the <acronym>CVS</acronym> root directory where the project source tree
will be imported to, and where <command>commit</command>s,
<command>checkout</command>s and <command>update</command>s take place.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Repository in CVS</guilabel></term>
<listitem>
<para>
This is the module name for your project.  This is the same as the project
directory, so you cannot change it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Vendor Tag</guilabel></term>
<listitem>
<para>
This is the tag for the entire branch.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Log Message</guilabel></term>
<listitem>
<para>
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 <emphasis>only</emphasis> for the initial import.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Release Tag</guilabel></term>
<listitem>
<para>
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
<acronym>CVS</acronym> 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.
</para>
</listitem>
</varlistentry>
</variablelist>

<para>
After creating your project with the KAppWizard, the <acronym>CVS</acronym>
support option is already set for your project.  
</para>

</sect1>

<sect1 id="enabling-cvs-support">
<title>Enabling <acronym>CVS</acronym> Support</title>

<para>
As <acronym>CVS</acronym> 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;,
<acronym>CVS</acronym> support is optional.  To enable the
<acronym>CVS</acronym> commands, open the <guilabel>Project Options</guilabel>
diialog and change the option for <guilabel>Version Control</guilabel> to
<guilabel>CVS</guilabel>.
</para>

</sect1>

<sect1 id="using-cvs-commands">
<title>Using <acronym>CVS</acronym> Commands</title>

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

<variablelist>
<title>Over a file not included in the repository:</title>
<varlistentry>
<term><guimenuitem>Add to Repository</guimenuitem></term>
<listitem>
<para>
Adds the file to the repository.  The file is set up to be added, and will be
introduced to the repository on the next <command>commit</command> command that
includes the directory it is located in.
</para>
</listitem>
</varlistentry>
</variablelist>

<variablelist>
<title>Over a file included in the repository</title>
<varlistentry>
<term><guimenuitem>Update</guimenuitem></term>
<listitem>
<para>
Update the selected file with the <acronym>CVS</acronym> version.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Commit</guimenuitem></term>
<listitem>
<para>
Commit the selected file to the <acronym>CVS</acronym> repository.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Remove from Repository</guimenuitem></term>
<listitem>
<para>
Remove the selected file from the repository.
</para>
</listitem>
</varlistentry>
</variablelist>

<variablelist>
<title>Over a folder</title>
<varlistentry>
<term><guimenuitem>Add</guimenuitem></term>
<listitem>
<para>
Add the entire folder to the repository.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Remove</guimenuitem></term>
<listitem>
<para>
Remove the folder from the repository.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Update</guimenuitem></term>
<listitem>
<para>
Update the folder recursively to be in sync with the repository.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Commit</guimenuitem></term>
<listitem>
<para>
Commit any changes recursively to the repository.
</para>
</listitem>
</varlistentry>
</variablelist>

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

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

</sect1>

</chapter>

<chapter id="general-configuration">
<title>General Configuration</title>

<para>
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 <guimenu>Options</guimenu> menu.
</para>

<sect1 id="configuring-the-tools-menu">
<title>Configuring the <guimenu>Tools</guimenu> Menu</title>

<para>
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 <guimenu>Tools</guimenu> menu.
</para>

<para>
To add an application to the <guimenu>Tools</guimenu> menu, select
<guimenuitem>Tools</guimenuitem> from the <guimenu>Options</guimenu> menu.
</para>

<para>
The resulting dialog allows you to specify new entries, by adding the executable
name of the new application in the <guilabel>Executable</guilabel> field, or
browsing to it with the <guiicon>folder</guiicon> icon.  Add the text you want
it to appear in the menu as to the <guilabel>Menu Text</guilabel> field, using a
&amp; 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
<guilabel>Arguments</guilabel> field.
</para>

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

<para>
Newly added applications will be available immediately in the
<guimenu>Tools</guimenu> menu.
</para>

</sect1>

<sect1 id="file-viewer-options">
<title>File Viewer Options</title>

<para>
The <guilabel>Groups</guilabel> viewer can be configured entirely through context
menus.  
</para>

<para>
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.
</para>

<para>
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.
</para>

<para>
The menu offers:
</para>

<variablelist>
<title>The Project Icon Context Menu</title>
<varlistentry>
<term><guimenuitem>New File</guimenuitem></term>
<listitem>
<para>
Open the <guilabel>New File</guilabel> dialog.  This is the equivalent of
choosing the menu item <menuchoice> <guimenu>File</guimenu>
<guimenuitem>New</guimenuitem></menuchoice>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>New Class</guimenuitem></term>
<listitem>
<para>
Opens the class generator, to create a new class. This is the equivalent of the
menu item <menuchoice><guimenu>Project</guimenu> <guimenuitem>New
Class</guimenuitem></menuchoice>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>New Group</guimenuitem></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Show relative path</guimenuitem></term>
<listitem>
<para>
Display the files with their path, starting from the main project directory.  If
this is unchecked, only the file name is shown.
</para>
</listitem>
</varlistentry>
</variablelist>

<variablelist>
<title>The Group Folder Context Menu</title>
<varlistentry>
<term><guimenuitem>New Group</guimenuitem></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Remove Group</guimenuitem></term>
<listitem>
<para>
Removes the group from the <guilabel>Groups</guilabel> pane.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Properties</guimenuitem></term>
<listitem>
<para>
Opens the properties of the group.  There you can edit the file filters, through
a list of wildcards separated by commas.
</para>
</listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="kdevelop-setup">
<title><guimenuitem>KDevelop Setup</guimenuitem></title>

<para>
The general configuration for &kdevelop; is reached through the
<guimenu>Options</guimenu> menu entry <guimenuitem>KDevelop Setup</guimenuitem>.
</para>

<para>
The dialog contains several sections:
</para>

<itemizedlist>
<listitem>
<para>
<link linkend="general-setup"><guilabel>General</guilabel></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="keys-setup"><guilabel>Keys</guilabel></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="documentation"><guilabel>Documentation</guilabel></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="debugger"><guilabel>Debugger</guilabel></link>
</para>
</listitem>
<listitem>
<para>
<link linkend="setting-paths"><guilabel>Path</guilabel></link>
</para>
</listitem>
</itemizedlist>

</sect1>

<sect1 id="general-setup">
<title><guilabel>General</guilabel></title>

<variablelist>
<varlistentry>
<term><guilabel>Select Make-Command</guilabel></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>enable Autosave</guilabel></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Select Autosave time-interval</guilabel></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>enable Autoswitch</guilabel></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>use Class View as default</guilabel></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Startup Logo</guilabel></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Tip of the Day</guilabel></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Load last project</guilabel></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="keys-setup">
<title><guilabel>Keys</guilabel></title>

<para>
</para>

</sect1>

<sect1 id="documentation">
<title>Documentation</title>

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

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

<para>
Usually, the &Qt; Documentation is placed in the same directory where &Qt; is
installed; &eg; if &Qt; resides in <filename
class="directory">/usr/local/qt</filename>, the path you have to enter is
<filename class="directory">/usr/local/qt/html</filename>.
</para>

<variablelist>
<varlistentry>
<term><guilabel>Qt-Library-Doc:</guilabel></term>
<listitem>
<para>
The path to your &Qt; documentation.   
</para>
<para>
Usually, the &Qt; Documentation is placed in the same directory where &Qt; is
installed; &eg; if &Qt; resides in <filename
class="directory">/usr/local/qt</filename>, the path you have to enter is
<filename class="directory">/usr/local/qt/html</filename>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>KDE-Libraries-Doc</guilabel></term>
<listitem>
<para>
The path to your &kde; documentation.
</para>
<para>
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. 
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Update KDE-Documentation:</guilabel></term>
<listitem>
<para>
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
<guilabel>Update KDE-Documentation</guilabel> dialog creates a new one or
updates existing documentations. This function requires your system to have
<command>KDoc</command> and <command>qt2kdoc</command> 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: <filename
class="directory">/home/rnolden/kdelibs-2.1/</filename>.
</para>
<para>
You can choose from three different installation modes:
</para>
<variablelist>
<varlistentry>
<term><guilabel>Delete old Documentation and install to recent
Documentation-path:</guilabel></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Delete old Documentation and install to new
Documentation-path</guilabel></term>
<listitem>
<para>
This will result in deleting the old documentation, and installing the new
documentation to a different place.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Leave old Documentation untouched and install to new
Documentation path</guilabel></term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The <guilabel>new KDE Libs Documentation path</guilabel> 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.
</para>  
<para>
After you press the <guibutton>OK</guibutton> button, &kdevelop; will create a
subdirectory <filename class="directory">KDoc-reference</filename> in the
documentation path, containing the <command>KDoc</command> 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 <command>qt2kdoc</command> script.  Finally
the &kde; libs will be indexed, and the documentation will be built with cross
references, to give you the most functionality.
</para> 
<note>
<para>
When using <command>KDoc</command> 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 <filename>kdoc.rules</filename> 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 <filename
class="directory">koffice/lib</filename>. Select option 3 (<guilabel>Leave old
Documentation untouched</guilabel>) 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 <filename>kdoc.rules</filename> file to generate
additional documentation as with the &kde; Base and KOffice packages.
</para>
</note>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Create Search Database</guilabel></term>
<listitem>
<para>
The Create Search Database dialog, accessed via the
<guibutton>create</guibutton> 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 <command>glimpse</command> 4.0 or
<application>ht://Dig</application> 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
<guilabel>Documentation Path</guilabel> dialog of the options-
menu. Additionally, the index can include directories the user can set up
himself by the <guilabel>additional directories to index</guilabel> field. After
setting a path to an additional directory, the <guibutton>Add</guibutton> 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
<guibutton>Remove</guibutton>. 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
<guilabel>medium</guilabel> size.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Create also KDOC-reference of your project</guilabel></term>
<listitem>
<para>
This option allows you to create a cross-reference file for your project when
generating the <acronym>API</acronym> documentation with
<command>KDoc</command>. 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 <acronym>API</acronym>
documentation without errors.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="debugger">
<title><guilabel>Debugger</guilabel></title>

<para>Already covered in detail in <xref
linkend="debugger-options"></para>

</sect1>

<sect1 id="setting-paths">
<title><guilabel>Paths</guilabel></title>

<variablelist>
<varlistentry>
<term><guilabel>Qt 2.x directory:</guilabel></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>KDE 2.x directory:</guilabel></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Project Path:</guilabel></term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1>

</chapter>

<chapter id="useful-things">
<title>Other Useful Things to Know</title>

<sect1 id="bug-reporting">
<title>Bug Reporting</title>

<para>
Like most large applications, &kdevelop; is a work in progress.  Unfortunately,
works in progress sometimes experience bugs.
</para>

<para>
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 <ulink
url="http://bugs.kde.org//db/pa/lkdevelop.html">http://bugs.kde.org//db/pa/lkdevelop.html</ulink>.
</para>

<para>
To send bug reports, please use the email address
<email>submit@bugs.kde.org</email>. If you want to use &kdevelop; for direct
bug-reporting, choose <guimenuitem>Bug Report</guimenuitem> from the
<guimenu>Help</guimenu> menu. You will be presented the report dialog that lets
you enter all necessary information about the bug you found. After pressing
<guibutton>OK</guibutton>, the dialog's contents is sent to the above address
automatically. 
</para>

</sect1>

</chapter>

<chapter id="q-and-a">
<title>Questions and Answer</title>

<sect1 id="more-information">
<title>More Information</title>

<qandaset>
<qandaentry>
<question>
<para>
I have a question that is not addressed in the <acronym>FAQ</acronym> file, nor
in the manuals of &kdevelop;.  Where should I turn?
</para>
</question>

<answer>
<para>
You can find help on any and all aspects of using &kdevelop; by subscribing to
the &kdevelop; mailing list at
<email>kdevelop-request@barney.cs.uni-potsdam.de</email>.  Send an email to that
address with an empty header and <userinput><command>subscribe</command>
<replaceable>youremailaddress</replaceable></userinput> as the contents of the
body.
</para>

<para>
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 <acronym>FAQ</acronym> updated with the issues
that people are facing.
</para>

<para>
The &kdevelop; home page at <ulink
url="http://www.kdevelop.org/">http://www.kdevelop.org/</ulink> 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.
</para>

</answer>
</qandaentry>
</qandaset>

</sect1>

<sect1 id="library-and-system-problems">
<title>Library and System Problems</title>

<qandaset>
<qandaentry>
<question>
<para>
I get an error saying <msgtext><para>Wrong JPEG library version: library is 61,
caller expects 62</para></msgtext>, so what's wrong?
</para>
</question>

<answer>
<para>
There are two ways to solve this issue.
</para>

<orderedlist>
<listitem>
<para>
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 <filename>jpeglib.h</filename> from <filename
class="directory">$<envar>KDEDIR</envar>/include</filename>.  The pukka include
file for version 62 <!-- what on earth is a pukka include file?? --> should then
be picked up.
</para>

<para>
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 <filename>jpeglib.h</filename>, and that it is the same version
as the library.  The <command>locate</command> command is useful to verify that
there is only one copy of the files in question.
</para>
</listitem>
<listitem>
<para>
Recompile kdesupport without the jpeg library.
(<userinput><command>./configure</command> <option>&ndash;&ndash;with-libjpeg</option>
<option>with-libgif</option></userinput>)
</para>
</listitem>
</orderedlist>

</answer>
</qandaentry>

<qandaentry>
<question>
<para>
I get an automake error saying <msgtext><para>aclocal.m4: 2709: `AM_PROG_INSTALL' is
obsolete; use `AC_PROG_INSTALL'</para></msgtext>.  What shall I do?
</para>
</question>

<answer>
<para>
If you are seeing errors like this:
</para>

<screen>
<computeroutput>
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
</computeroutput>
</screen>

<para>
The workaround for <command>automake</command> 1.4 through
<command>automake</command> 2.13 users is to run <command>aclocal</command>
manually, and the application will then compile.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
What must I do if configure said that I need giflib23
</para>
</question>

<answer>
<para>
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.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
How can I convert a &kdevelop; 0.2 project to a 0.3 one? <!-- is this really -->
<!-- still a faq? -->
</para>
</question>

<answer>
<para>
Change the AC_OUTPUt line in the <filename>configure.in</filename> to a one line
version.
</para>

<para>
for example, from the old version:

<programlisting>
AC_OUTPUT(Makefile \
kdevelop/kwrite/Makefile \
kdevelop/templates/Makefile
)
</programlisting>

change this to:

<programlisting>
AC_OUTPUT(Makefile kdevelop/kwrite/Makefile kdevelop/templates/Makefile)
</programlisting>
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
<command>configure</command> complains about not being able to compile a small
&kde; application.  Examining <filename>config.log</filename> reveals that it
can't find libXext.
</para>
</question>
<answer>
<para>
Install the xdevel package (or your distribution's equivalent)
</para>
</answer>
</qandaentry>
</qandaset>

</sect1>

<sect1 id="usage-questions">
<title>Usage Questions</title>

<qandaset>
<qandaentry>
<question>
<para>
&kdevelop; won't let me use the <keycap>delete</keycap> key, or
<keycap>backspace</keycap> to delete selected text.
</para>
</question>
<answer>
<para>
Go to <menuchoice><guimenu>Options</guimenu>
<guimenuitem>Editor...</guimenuitem></menuchoice> and make sure that <guilabel>Delete on
Input</guilabel> is enabled.  Your <keycap>Backspace</keycap> and
<keycap>Delete</keycap> keys will now work.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
If I add files to my project, will they be automatically included and compiled?
</para>
</question>

<answer>
<para>
Yes, they are included in the <filename>Makefile.am</filename>'s and if you do a
<guimenuitem>Rebuild All</guimenuitem>, then <command>./configure</command> will
update the <filename>Makefile</filename>s and your files will now be included.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
If I remove a file, I get some weird linker messages.  What's wrong with my
project?
</para>
</question>

<answer>
<para>
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 <literal
role="extension">*.moc.cpp</literal> file, and is still compiled.  Remove the
appropriate <literal role="extension">*.moc.cpp</literal> and rebuild the
project.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
I'm developing an application where I need to set <option>-D</option> options to
the preprocessor.  If I add these in &kdevelop; to my project, everything is ok,
but when I distribute my package, the <option>-D</option> options set in
&kdevelop; are not used.  What do I have to do to make this work?
</para>
</question>

<answer>
<para>
Edit the file <filename>configure.in</filename>, in your top level source
directory.  Enter somewhere near the beginning <userinput>CXXFLAGS=$(CXXFLAGS) "
-DYOURDEFINE" AC_SUBST(CXXFLAGS)</userinput>.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
I don't have any &kde; widgets in the &Qt; <application>Designer</application>.
How do I add them?
</para>
</question>

<answer>
<para>
You will have to recompile &Qt, with the <option>-kde</option> enabled.  That
is, <userinput><command>./configure</command> <option>-kde</option>
...</userinput>, in addition to your usual configure options.  Rembember to set
$<envar>QTDIR</envar> and $<envar>KDEDIR</envar> to the appropriate values.
After doing this, you will have a new <guimenuitem>KDE</guimenuitem> option in
the <guimenu>Tools</guimenu> menu of <application>Designer</application>.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
I use &RedHat; &Linux; with &kdevelop; and tried to recompile the &Qt; library
with <option>-kde</option> in order to use the designer with &kde; widget
support but during configure it says that $<envar>KDEDIR</envar> does not
contain a valid &kde; installation?
</para>
</question>

<answer>
<para>
&RedHat; uses non-standard directory setting with &kde;. The normal case would
be that the libs are in <filename
class="directory">$<envar>KDEDIR</envar>kdedir/lib</filename>, binaries in
<filename class="directory">$<envar>KDEDIR</envar>/bin</filename> and includes
in <filename
class="directory">$<envar>KDEDIR</envar>/include</filename>. &RedHat; uses
<filename class="directory">/usr</filename> as $<envar>KDEDIR</envar>
but<filename class="directory">$<envar>KDEDIR</envar>/include/kde</filename> as
directory for header files. Therefore configure from &Qt; fails to detect the
correct directories. It searches for <command>dcopserver</command> in the
binaries folder and the header files in their folder. So if you choose
$<envar>KDEDIR</envar> to be <filename class="directory">/usr</filename>,
configure can't find the includes. A possible solution for this is to create a
<filename class="directory">/usr/local/kde</filename> directory and set symlinks
to <filename class="directory">/usr/bin</filename> and <filename
class="directory">/usr/include/kde</filename> in this <quote>pseudo</quote>
kde dir. Then <userinput><command>export</command>
<envar>KDEDIR</envar>=<filename
class="directory">/usr/local/kde</filename></userinput> and do the
<userinput><command>./configure</command>
<option>-kde</option></userinput>. After compiling &Qt; you have the &kde;
entries in the <guimenu>Tools</guimenu> menu of the &Qt; designer.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
Is there any HOWTO documentation available on working with &Qt;
<application>Designer</application> made dialogs?
</para>
</question>

<answer>
<para>
Yes, there is a great tutorial on <ulink
url="http://women.kde.org/docs/tut_kdevelop/">http://women.kde.org/docs/tut_kdevelop/</ulink>.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
I have installed <application>htdig</application> but there is no
<command>htsearch</command> available.  What's up?
</para>
</question>

<answer>
<para>
On some systems (notably &RedHat;), the <command>htsearch</command> executable
is placed in the <filename class="directory">/cgi-bin</filename> of
<application>apache</application>.  You can create symlinks in <filename
class="directory">/usr/bin/</filename> or simply add this to your path in your
shell <literal role="extension">rc</literal> file.
</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>
I have <command>htdig</command>, <command>htmerge</command> and
<command>htsearch</command> available but I get an error message thet the config
file of <command>htdig</command> could not be found or is invalid, so what can I
do?
</para>
</question>

<answer>
<para>
Read <filename>README.htdig</filename> in the source directory tree and create
an <filename>htdig.conf</filename> file. Then copy it to <filename
class="directory">$<envar>KDEDIR</envar>/share/apps/kdevelop/tools</filename>. Now
create your search index with the <guimenuitem>KDevelop Setup</guimenuitem> menu
item.
</para>
</answer>
</qandaentry>								    

</qandaset>


</sect1>

</chapter>

<chapter id="credits-and-license">
<title>Credits and Licenses</title>

<para>&kdevelop;</para>

<para>Copyright the &kdevelop; team, 1999, 2000, 2001</para>

<variablelist>
<varlistentry>
<term>Sandy Meier <email>smeier@kdevelop.de</email></term>
<listitem>
<para>Maintainer, development coordinator, and homepage provider.  Main
development of frame structure, &IDE; look'n feel and project management.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Stefan Heidrich <email>sheidric@rz.uni-potsdam.de</email></term>
<listitem>
<para>Main development of KAppWizard and printing functionality.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Ralf Nolden <email>rnolden@kdevelop.de</email></term>
<listitem>
<para>Main development of &kdevelop; <--> Dialog Editor interface, configuration
functionality, online help and handbooks.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Jonas Nordin <email>jonas.nordin@cenacle.se</email></term>
<listitem>
<para>Main development of the Class viewer and Class parser.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Pascal Krahmer <email>pascal@beast.de</email></term>
<listitem>
<para>Main development of the Dialog Editor.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Bernd Gehrmann <email>bernd@physik.hu-berlin.de</email></term>
<listitem>
<para>Main development of the Grep Dialog, CVS integration, and the new
Documentation tree.</para>
</listitem>
</varlistentry>
</variablelist>
<!-- This is incomplete -->
&underFDL;
&underGPL;

</chapter>

<![ %addindex; [ &kdedocindex; ]]>

</book>

<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-omittag:t
sgml-shorttag:t
sgml-namecase-general:t
sgml-always-quote-attributes:t
sgml-indent-step:0
sgml-indent-data:nil
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->