<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
 <!ENTITY kdevelop "<application>KDevelop</application>">
 <!ENTITY % addindex "IGNORE">
 <![ %addindex; [ <!ENTITY docindex SYSTEM "docindex.docbook"> ]]>
]>
<book lang="en">
  <bookinfo>
    <title>The User Manual to KDevelop</title>
    <subtitle>The Reference Guide to the KDevelop Integrated Development Environment for Unix Systems, Version 1.2</subtitle>
<authorgroup>
<author>
<firstname>Ralf</firstname><surname>Nolden </surname>
<affiliation><orgname>The KDevelop Team</orgname>
<address><email>Ralf.Nolden@post.rwth-aachen.de</email></address></affiliation>
</author>
<corpauthor>The Kdevelop Team</corpauthor>
<othercredit role="reviewer">
<firstname>Lauri</firstname><surname>Watts</surname>
<contrib>Reviewer</contrib>
<affiliation><address><email>vampyr@atconnex.net</email></address></affiliation>
</othercredit>
</authorgroup>

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

<date>21/03/2000</date>
<releaseinfo>1.02.00</releaseinfo>

<keywordset>
<keyword>KDE</keyword>
<keyword>Kdevelop</keyword>
</keywordset>

<abstract>
<para>This handbook is part of the <application>KDevelop</application> Integrated Development Environment, for KDE 1.x and KDE 2.0 </para>
</abstract>
</bookinfo>

  <chapter id="introduction">
    <title>Introduction</title>
    
    <para>Just as everything on earth has its fashions, todays computer world seems to be tending to the use of free software, even for commercial purposes. The most popular free software project is Linux. It is now generally agreed that Linux, (as well as other projects such as the <application>Apache</application> web server, the Perl language and the <abbrev>GNU</abbrev> 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 from the often cryptic commands of any Unix System. For Linux to thrive, it needs applications, both free and commercial, and it needs ease of use.</para>
    <para>The KDE <indexterm><primary>KDE</primary></indexterm> project tries to close the gap with commercial software, by providing an easy to use desktop, and the companion libraries to extend the variety of available <abbrev>GUI</abbrev><indexterm><primary>GUI</primary></indexterm>-based software. As free software is often made in the author's free time, the question for many programmers is how much they like their current code development environment. <application>kdevelop</application>; wants to take a major step towards making the programmer's life easier and more efficient. Products created with <application>kdevelop</application>; can reach a higher level of reliability and functionality in the same development period.</para>
    <para>To fulfill this goal, the <application>KDevelop Integrated Development Environment</application> provides many features that developers need, at the same time as it wraps the functionality of third party projects such as <application>make</application> and the <abbrev>GNU</abbrev> C++ Compiler<indexterm><primary>Compiler</primary></indexterm>, and makes them an invisible, integrated part of the development process.</para>

    <para><application>kdevelop</application>; manages:</para>
    <itemizedlist>
	<listitem>    
	  <para> All development tools needed for C++ programming including the <application>Compiler</application> <indexterm><primary>Compiler</primary></indexterm>, the <application>Linker</application><indexterm><primary>Linker</primary></indexterm>, <application>automake</application><indexterm><primary><application>automake</application></primary></indexterm>, and <application>autoconf</application><indexterm><primary>autoconf</primary></indexterm></para>
	</listitem>
	<listitem>
	  <para> <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm>, which generates complete, ready-to-go sample applications</para>
	</listitem>
	<listitem>
	  <para> Class-generator, for creating new classes <indexterm><primary>classes</primary></indexterm> and integrating them into the current project</para>
	</listitem>
	<listitem>
	  <para> File management for sources, headers, documentation <abbrev>etc.</abbrev>, to be included in the project</para>
	</listitem>
	<listitem>
	  <para> The creation of User Handbooks written in <abbrev>SGML</abbrev> <indexterm><primary>SGML</primary></indexterm> and the automatic generation of <abbrev>HTML</abbrev><indexterm><primary>HTML</primary></indexterm>-output <indexterm><primary>output</primary></indexterm> with the KDE look and feel</para>
	</listitem>
	<listitem>
	  <para> Automatic <abbrev>HTML</abbrev><indexterm><primary>HTML</primary></indexterm>based <abbrev>API</abbrev> documentation <indexterm><primary>API-documentation</primary></indexterm> for your project's classes, <indexterm><primary>classes</primary></indexterm> with cross-references to the used libraries</para>
	</listitem>
	<listitem>
	  <para> Internationalization support for your application, allowing translators to easily add their target language to a project</para>
	</listitem>
	<listitem>
	  <para> <abbrev>WYSIWYG</abbrev> (What you see is what you get) creation of user interfaces, with a built-in dialog editor <indexterm><primary>dialog editor</primary></indexterm></para>
	</listitem>
	<listitem>
	  <para> Managing your project via <abbrev>CVS</abbrev>, by providing an easy-to-use front end for the most needed functions</para>
	</listitem>
	<listitem>
	  <para>Debugging your application, by integrating <application>kdbg</application>;<indexterm><primary>KDbg</primary></indexterm></para>
	</listitem>
	<listitem>
	  <para>Editing of project-specific pixmaps <indexterm><primary>pixmaps</primary></indexterm> with <application>KIconEdit</application> <indexterm><primary>KIconEdit</primary></indexterm></para>
	</listitem>
	<listitem>
	  <para>The inclusion of any other program you need for development by adding it to the <guimenu>"Tools<indexterm><primary>Tools</primary></indexterm>"</guimenu> menu, according to your individual needs</para>
	</listitem>
      </itemizedlist>  
    <para><application>kdevelop</application>; makes it a joy to work with all the necessary programs in one place, and saves time by automating standard development processes, while giving you direct and transparent access to all the information you need. The integrated browsing mechanisms are designed to support the documentation <indexterm><primary>documentation</primary></indexterm> requirements that developers have in conjunction with their project.</para>
    <para>The class viewer <indexterm><primary>class viewer</primary></indexterm> and error finder bring you anywhere in the project code with a mouse click, without needing to search for files. File trees give direct access to the project files, <indexterm><primary>project files</primary></indexterm> and the integrated help system offers superb access to online-documentation from anywhere within the <abbrev>IDE</abbrev>.</para>

    <sect1 id="changes">
      <title>Changes</title>

      <para>Version 1.2 of <application>kdevelop</application>; contains the most needed facilities for C/C++ development. During the development phase of <application>kdevelop</application>;, the project has made great improvements since the 1.0 final release, followed by the release of version 1.1. The current version is to be expected to be the final release for the KDE 1.x series, giving developers the environment they want to use.</para>
      <para>Improvements were made in the following sections:</para>
      <itemizedlist>
	<listitem>
	  <para>fast class-parser and -browser with graphical class-tree view and dialog-based adding of members and classes</para>
	</listitem>
	<listitem>
	  <para><abbrev>CVS</abbrev> support for the most needed functions such as adding, removing, updating, and committing files and directories</para>
	</listitem>
	<listitem>
	  <para>updated and extended documentation, now comprising five handbooks shipping with <application>kdevelop</application>;</para>
	</listitem>
	<listitem>
	  <para>bug-fixed dialog-editor and error-finder</para>
	</listitem>
	<listitem>
	  <para>updated documentation tree which lets you access the class documentation, up to any method of classes directly</para>
	</listitem>
      </itemizedlist>
      <para>Any comments about the <abbrev>IDE</abbrev>, its documentation, or feature requests are welcome.</para>
    </sect1>

    <sect1 id="about-this-handbook">
      <title>About this Handbook</title>

      <para>This user manual gives the user a complete overview of the <application>kdevelop</application>; <abbrev>IDE</abbrev> and describes the basic development process in brief. For more information about specific programming issues, we suggest reading the <ulink url="programming/index.html">KDevelop Programming Handbook</ulink> included with <application>kdevelop</application>;, which covers themes such as understanding generated application framework<indexterm><primary>application framework</primary></indexterm>s, and how to create full-featured KDE <indexterm><primary>KDE</primary></indexterm> applications, using example projects.</para>

      <para>The design of this handbook is therefore separated into the following parts:</para>
      <itemizedlist>
	  <listitem>
	    <para>Chapter <link linkend="Installation">Installation</link>, covers the system requirements, installation and setting up of the <application>kdevelop</application>; <abbrev>IDE</abbrev>. </para>
	  </listitem>
	  <listitem>
	    <para>Chapter <link linkend="Programs">Programs</link>, tells you how programs are created with standard <abbrev>GNU</abbrev> development tools and how they are built.</para>
	  </listitem>
	  <listitem>
	    <para>Chapter <link linkend="Development-with-kdevelop">Development with <application>kdevelop</application>;</link>, takes you on a short tour, describing the main functionality of the environment.</para>
	  </listitem>
	  <listitem>
	    <para>Chapter <link linkend="Overview">Overview</link>, explains the menus and dialogs, as well as keyboard shortcuts<indexterm><primary>shortcuts</primary></indexterm>.</para>
	  </listitem>
	  <listitem>
	    <para>Chapter <link linkend="The-Help-System">The Help System</link>, shows how to use the built-in documentation browser <indexterm><primary>documentation browser</primary></indexterm> and additional help functions.</para>
	  </listitem>
	  <listitem>
	    <para>Chapter  <link linkend="Working-with-the-Editor">Working with the Editor</link>, explains the features for file management and editing.</para>
	  </listitem>
	  <listitem>
	    <para>Chapter <link linkend="Projects">Projects</link>, describes the creation and maintaining of software projects.</para>
	  </listitem>
	  <listitem>
	    <para>Chapter <link linkend="Build-Settings">Build Settings</link>, contains a reference on how to set Compiler <indexterm><primary>Compiler</primary></indexterm> and linker flags, as well as project options.</para>
	  </listitem>
	  <listitem>
	    <para>Chapter <link linkend="The-Class-Browser">The Class Browser</link>, tells you how to make use of <application>kdevelop</application>;'s powerful Class Browser.</para>
	  </listitem>
	  <listitem>
	    <para>Chapter <link linkend="The-Dialog-Editor">The Dialog Editor</link>, features the integrated visual <abbrev>GUI</abbrev> <indexterm><primary>GUI</primary></indexterm> constructor and how it generates C++ output <indexterm><primary>output</primary></indexterm>.</para>
	  </listitem>
	  <listitem>
	    <para>Chapter<link linkend="The-Internal-Debugger">The Internal Debugger</link>,gives an overview of the debugging setup and use of the internal debugger</para>
	  </listitem>
	  <listitem>
	    <para>Chapter<link linkend="CVS-Integration">CVS Integration</link>, tells you how to use the revision control system <abbrev>CVS</abbrev>, and <abbrev>RCS</abbrev> with your <application>kdevelop</application>; project.</para>
	  </listitem>
	  <listitem>
	    <para>Chapter <link linkend="General-Configuration">General Configuration</link> shows how you  can set overall preferences for using <application>kdevelop</application>;.</para>
	  </listitem>
	  <listitem>
	    <para>Chapter <link linkend="Questions-and-Answers">Questions and Answers</link>, covers questions regarding the usage of <application>kdevelop</application>; under different flavors of Unix systems, and problem solutions in general. </para>
	  </listitem>
	</itemizedlist>
      <para>For programming beginners, and new users of this product, we recommend you read entirely through this manual before starting to actually work with the <abbrev>IDE</abbrev>, as it covers the usage in depth. The understanding of how things are done the quickest way will save you a lot of time searching for functions and features, as it will enable you to make full use of first-class development tools.</para>
    </sect1>
    
    <sect1 id="about-the-kdevelop-project">
      <title>About the <application>kdevelop</application>; Project</title>
      
      <para>The <application>kdevelop</application>; project was started in summer of 1998 (after KDE 1.0 was available on Linux/Unix,) as an attempt to create an easy to use C/C++ <abbrev>IDE</abbrev> for programmers, especially targeting 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 years, the <abbrev>IDE</abbrev> developed to a full-featured KDE application with the most possible functionality and stability, as the creators started to develop the <abbrev>IDE</abbrev> within the <abbrev>IDE</abbrev> itself once enough usability was established. Bugs were mostly found by the authors themselves, 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 <application>kdevelop</application>; Team introduced more features and stability into the <abbrev>IDE</abbrev> 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 has continued to integrate more functionality and has been simplifying the current code-base.  Many translators are transferring <application>kdevelop</application>; to as many languages as possible, to provide the international developer community the <abbrev>IDE</abbrev> in their own language, including the handbooks that ship with it. Many users have contributed their experience and knowledge to the project as one of the most promising products for Linux/Unix developers, helping to make it even more stable and portable to other Unices.</para>
    </sect1>
    
    <sect1 id="printed-versions">
      <title>Printed Versions</title>
      
      <para>A printed version of the complete <application>kdevelop</application>; Documentation is available as the book titled <emphasis>Developing Applications for Linux: KDE Edition</emphasis>, which can be ordered either online from the <application>kdevelop</application>; web site 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 <application>kdevelop</application>; project, to support continuing the further development of <application>kdevelop</application>;.</para>
      <para>Printable versions of the <application>kdevelop</application>; Documentation can also be obtained from the <application>kdevelop</application>; web site at <ulink url="http://www.kdevelop.org">http://www.kdevelop.org</ulink> in <abbrev>DVI</abbrev>, Postscript and <abbrev>PDF</abbrev> format, both in A4 and in Letter size.</para>
    </sect1>
  
  </chapter>
  
  <chapter id="installation">
    <title>Installation <indexterm><primary>Installation</primary></indexterm></title>

    <sect1 id="how-to-obtain-kdevelop">
      <title>How to obtain <application>kdevelop</application></title>

      <para><application>kdevelop</application>; can be found either on the KDE <indexterm><primary>KDE</primary></indexterm> Applications page at <ulink url="http://www.kde.org/current.html">http://www.kde.org/current.html</ulink>, or on the <application>kdevelop</application>; home page at <ulink url="http://www.kdevelop.org">http://www.kdevelop.org</ulink>.</para>
      <para><application>kdevelop</application> is also available on Linux distributions, such as SuSE 6.1.</para>
      <para>We're also offering snapshots of the <application>kdevelop</application> <abbrev>CVS</abbrev> repository on our home page, for those who want to stay up to date with <application>kdevelop</application>. 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 <application>KDevelop</application> team. We also offer various third party software needed by <application>KDevelop</application> directly such as <application>KDoc</application> <indexterm><primary>KDoc</primary></indexterm> and <application>kdbg</application>;<indexterm><primary>KDbg</primary></indexterm>.</para>
      <para>If you are experiencing problems with compiling or using <application>KDevelop</application>, please read the <link linkend="Questions-and-Answers">Questions and Answers</link> section of this handbook or the <abbrev>FAQ</abbrev> file included with the <application>KDevelop</application> package. If your problem is not addressed, please subscribe to the <application>KDevelop</application> mailing list at <email>kdevelop-request@barney.cs.uni-potsdam.de</email> by sending an email with an empty header and <userinput>"subscribe youremailaddress"</userinput> as contents.</para>
      <para> Requests and problem reports should only target the usage of the <application>KDevelop</application> <abbrev>IDE</abbrev>, and not questions that regard any implementation <indexterm><primary>implementation</primary></indexterm> problems you may have while coding your own application. All email sent to the mailing list should be written in English, so that all participants can take part in discussions and are able to provide better help. The mailing list is also intended for those users willing to contribute and who have found solutions for any problems they experienced.  This enables us to fix errors <indexterm><primary>errors</primary></indexterm> and include that knowledge to give beginners even more qualified first-hand help.</para>
      <para>A good way to report problems is to send the output <indexterm><primary>output</primary></indexterm> you get from starting <command>kdevelop</command> from the console or to copy and paste the contents of <application>KDevelop</application>'s internal Messages-window <indexterm><primary>Messages-window</primary></indexterm>.</para>
    </sect1>

    <sect1 id="requirements-requirements">
      <title>Requirements <indexterm><primary>Requirements</primary></indexterm></title>
      
      <para>In order to successfully compile and use <application>KDevelop</application>, you need the following programs and libraries.  These are available on most platforms as distribution packages and can thereby be installed easily.</para>
      
      <para><emphasis>Required:</emphasis></para>
      <itemizedlist>
	<listitem>
	  <para><application>g++ 2.7.2/g++ 2.8.1/egcs 1.1</application> (or compatible), available at <ulink url="http://www.gnu.org">http://www.gnu.org/</ulink></para>
	</listitem>
	<listitem>
	  <para><application>GNU make</application> (or compatible), available at <ulink url="http://www.gnu.org">http://www.gnu.org/</ulink></para>
	</listitem>
	<listitem>
	  <para><application>Perl 5.004</application>, available at <ulink url="http://www.perl.com">http://www.perl.com/</ulink></para>
	</listitem>
	<listitem>
	  <para><application>autoconf</application> <indexterm><primary>autoconf</primary></indexterm> 2.12, available at <ulink url="http://www.gnu.org">http://www.gnu.org/</ulink></para>
	</listitem>
	<listitem>
	  <para><application>automake</application> <indexterm><primary>automake</primary></indexterm> 1.2, available at <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><application>GNU gettext</application>, available at <ulink url="http://www.gnu.org">http://www.gnu.org/</ulink></para>
	</listitem>
	<listitem>
	  <para><application>Qt 1.42</application>, available at <ulink url="http://www.troll.no">http://www.troll.no/</ulink></para>
	</listitem>
	<listitem>
	  <para>KDE <indexterm><primary>KDE</primary></indexterm> 1.1.x, available at <ulink url="http://www.kde.org">http://www.kde.org/</ulink></para>
	</listitem>
      </itemizedlist>
      <para><emphasis>Optional:</emphasis></para>
      <itemizedlist>
	<listitem>
	  <para><application>enscript</application> <indexterm><primary>enscript</primary></indexterm> for printing <indexterm><primary>printing</primary></indexterm> support</para>
	</listitem>
	<listitem>
	  <para><application>ghostview</application> or <application>kghostview</application> for printing <indexterm><primary>printing</primary></indexterm> preview</para>
	</listitem>
	<listitem>
	  <para><application>glimpse</application> <indexterm><primary>glimpse</primary></indexterm> 4.0 for the search index <indexterm><primary>search index</primary></indexterm>, available at <ulink url="http://glimpse.cs.arizona.edu">http://glimpse.cs.arizona.edu/</ulink></para>
	</listitem>
	<listitem>
	  <para><application>sgmltools</application> 1.0, available at <ulink url="http://www.sgmltools.org">http://www.sgmltools.org/</ulink></para>
	</listitem>
	<listitem>
	  <para><abbrev>KDE-SDK</abbrev> <indexterm><primary>KDE-SDK</primary></indexterm> (<emphasis>KDE S</emphasis>oftware <emphasis>D</emphasis>evelopment <emphasis>K</emphasis>it), which includes <application>KDoc</application> <indexterm><primary>KDoc</primary></indexterm>, <application>KSgml2Html</application> <indexterm><primary>KSgml2Html</primary></indexterm>, <application>KTranslator</application> <indexterm><primary>KTranslator</primary></indexterm> (available at <ulink url="http://developer.kde.org">http://developer.kde.org/</ulink>)</para>
	</listitem>
	<listitem>
	  <para><application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm>, available at <ulink url="http://members.telecom.at/~johsixt/kdbg.html">http://members.telecom.at/~johsixt/kdbg.html</ulink></para>
	</listitem>
	<listitem>
	  <para><application>KIconEdit</application> <indexterm><primary>KIconEdit</primary></indexterm> available at <ulink url="http://www.kde.org">http://www.kde.org/</ulink></para>
	</listitem>
      </itemizedlist>
      <para><application>KDevelop</application> was tested  on an AMD K6 200, 64MB RAM with SuSE Linux 5.2 and with Free-BSD 3.0-Release, and also SuSE Linux 6.0 on an Intel 200 MMX, 128MB RAM.</para>
      <para>As far as known to the authors, SuSE Linux and Free-BSD contain all necessary packages, including <application>enscript</application> <indexterm><primary>enscript</primary></indexterm> as packages or rpms, so you should have no problem installing the required third-party software.</para>
      <para><emphasis>Documentation:</emphasis></para>
      <para>For creating the KDE <indexterm><primary>KDE</primary></indexterm> library documentation, you need the kdelibs package in source available on your system as provided by the KDE project or included with the source packages of your distribution, and <application>KDoc</application><indexterm><primary>KDoc</primary></indexterm> (included in the <abbrev>KDE-SDK</abbrev> <indexterm><primary>KDE-SDK</primary></indexterm>).</para>
      <para>We are also offering a C/C++ Reference <indexterm><primary>Reference</primary></indexterm> on our home-page at <ulink url="http://www.kdevelop.org">http://www.kdevelop.org</ulink> that is integrated into the documentation browser <indexterm><primary>documentation browser</primary></indexterm> after it's installation. Download the package and copy the source file as root into your KDE <indexterm><primary>KDE</primary></indexterm> directory, and untar it with <command>tar zxvf c_c++_reference.tar.gz</command>, then the reference is available in the documentation tree; otherwise selecting the reference book in the browser shows an error page with the <application>KDevelop</application> home-page <abbrev>URL</abbrev> offering a download and describing the installation process. </para>
    </sect1>

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

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

<prompt>bash$</prompt> <userinput>./configure</userinput>
<prompt>bash$</prompt> <userinput>make</userinput>

<lineannotation>and as root</lineannotation>

<prompt>bash#</prompt> <userinput>make install</userinput></screen>

      <para>Since <application>KDevelop</application> uses <application>autoconf</application> <indexterm><primary>autoconf</primary></indexterm> you should have no trouble compiling it.</para>
      <para>In order to compile the <application>KDevelop</application> <abbrev>CVS</abbrev> snapshot, type the following :</para>

<screen>
<prompt>bash$</prompt> <userinput>make -f Makefile.cvs</userinput>
<prompt>bash$</prompt> <userinput>./configure</userinput>
<prompt>bash$</prompt> <userinput>make</userinput>

<lineannotation>change to `root` and type:</lineannotation>
	
<prompt>bash#</prompt> <userinput>make install</userinput></screen>
     
      <para>If your system's <command>make</command> command <indexterm><primary>make-command</primary></indexterm> is <filename>gmake</filename>, type <command>gmake</command> instead of <command>make</command>.</para>
    </sect1>

    <sect1 id="starting-kdevelop">
      <title>Starting <application>KDevelop</application></title>

      <para>If you use KDE <indexterm><primary>KDE</primary></indexterm> as your window manager, <application>KDevelop</application> can be started by choosing <guimenu>"K"</guimenu>-&gt;<guisubmenu>"Development"</guisubmenu>-&gt;<guimenuitem>"KDevelop 1.2"</guimenuitem>". As <application>KDevelop</application> supports KDE<indexterm><primary>KDE</primary></indexterm>-Mime-types, you can also start by selecting a <application>KDevelop</application> project file ("<filename>*.kdevprj</filename>", displayed with the <application>KDevelop</application> project icon) in the KDE <indexterm><primary>KDE</primary></indexterm> File Manager, which will start <application>KDevelop</application> and load the project. Under other window managers, open a console and type:</para>

<screen>

<prompt>bash$</prompt> <command>kdevelop</command></screen>

      <para>To start <application>KDevelop</application> with an existing project, change into the project-directory and type:</para>

<screen>

<prompt>bash$</prompt> <command>kdevelop</command> <userinput><replaceable> &lt;yourProject&gt;.kdevprj</replaceable></userinput></screen>

      <para>Under each user account <application>KDevelop</application> will invoke the <link linkend="The-Installation-Program">automatic installation</link> process on the first start, allowing a quick configuration of the most needed options. If your installation is messed up, you can reconfigure <application>KDevelop</application> any time either by entering</para>

<screen>

<prompt>bash$</prompt> <command>kdevelop --setup</command></screen>

      <para>or, when using KDE, by choosing <menuchoice><guimenu>"K"</guimenu<guisubmenu>"Development"</guisubmenu><guimenuitem>"KDevelop Setup"</guimenuitem></menuchoice>.</para>
    </sect1>

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

      <para><application>KDevelop</application> includes an automatic installation program module, which is invoked whenever <application>KDevelop</application> 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 <application>KDevelop</application> environment.</para>
      <para>The Installation dialog's buttons execute the following actions:</para>
      <para><guibutton>Help:</guibutton>  Will open the KDEHelp program.</para>
      <para><guibutton>Proceed:</guibutton> This starts the installation process and executes the following actions:</para>
      <orderedlist>
	<listitem>
	  <para> Checking for <application>make</application>/<application>gmake</application>, <application>autoconf</application><indexterm><primary>autoconf</primary></indexterm>, <application>autoheader</application>, <application>automake</application> <indexterm><primary>automake</primary></indexterm> and <application>perl</application> for the creation and compilation of new applications generated by <application>KDevelop</application>. If <application>gmake</application> is installed, the make command <indexterm><primary>make-command</primary></indexterm> will be set automatically to use <application>gmake</application>.  Other command-line options to your make program can be set in the setup <indexterm><primary>setup</primary></indexterm> dialog accessed by the <guimenu>"Options"</guimenu> menu later. An introduction into development under Unix is explained in section <link linkend="Programs">Programs</link>.</para>
	</listitem>
	<listitem>
	  <para> Checking for <application>KDoc</application><indexterm><primary>KDoc</primary></indexterm> and <application>glimpse</application> <indexterm><primary>glimpse</primary></indexterm>.  These will allow the creation of new KDE-Library <indexterm><primary>KDE-Library</primary></indexterm> documentation, and a search index <indexterm><primary>search index</primary></indexterm> to be created automatically in a later setup <indexterm><primary>setup</primary></indexterm> step, if found.</para>
	</listitem>
	<listitem>
	  <para> Checking for <application>enscript</application> <indexterm><primary>enscript</primary></indexterm> to ensure that printing <indexterm><primary>printing</primary></indexterm> is available.  This program must be installed to allow correct printing <indexterm><primary>printing</primary></indexterm>. If it isn't installed, you can optionally do this at any time later on, without having to run the setup <indexterm><primary>setup</primary></indexterm> again.</para>
	</listitem>
	<listitem>
	  <para> Checking for <application>kdbg</application>;<indexterm><primary>KDbg</primary></indexterm>, <application>KIconEdit</application> <indexterm><primary>KIconEdit</primary></indexterm>, and <application>KTranslator</application><indexterm><primary>KTranslator</primary></indexterm>.  We encourage you to install those programs, as they are helpful for creating complete KDE <indexterm><primary>KDE</primary></indexterm>applications. <application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm> is used directly for debugging <indexterm><primary>debugging</primary></indexterm> your current project within <application>KDevelop</application>; <application>KIconEdit</application> <indexterm><primary>KIconEdit</primary></indexterm> is used to display and edit pixmaps <indexterm><primary>pixmaps</primary></indexterm> selected in the file-viewer trees. The programs <application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm>, <application>KIconEdit</application><indexterm><primary>KIconEdit</primary></indexterm>, and <application>KTranslator</application> <indexterm><primary>KTranslator</primary></indexterm> are then configured to be available in the <guimenu>Tools</guimenu> <indexterm><primary>Tools</primary></indexterm> menu of the <application>KDevelop</application> menu bar, if they are found. Other tools can be added to the <guimenu>"Tools"</guimenu> <indexterm><primary>Tools</primary></indexterm>-menu by selecting <guimenuitem>"Tools<indexterm><primary>Tools</primary></indexterm>..."</guimenuitem> in the <guimenu>"Options"</guimenu> menu later.</para>
	</listitem>
	<listitem>
	  <para> Summary of detected programs: the installer lists those programs it found and those it didn't. Additional hints are given, if a needed program is not found.</para>
	</listitem>
	<listitem>
	  <para>Detection of your Qt Documentation <indexterm><primary>Qt-Documentation</primary></indexterm> path. This checks for several standard paths in your system for the documentation, and sets the path automatically. If your Qt Documentation <indexterm><primary>Qt-Documentation</primary></indexterm> could not be found, either because it is not installed, or your system keeps it at a different location, a message will appear that asks you to either set the correct path manually or to continue. Choosing the button to set the path will return to the main installation window, and shows an editing field with a button on the right of it to choose the path. Usually this is in the <filename>qt/html</filename> directory. After doing so, the installation can continue with the selection of <guibutton>"Proceed"</guibutton> again.</para>
	</listitem>
	<listitem>
	  <para> If <application>KDoc</application> <indexterm><primary>KDoc</primary></indexterm> was detected, you are asked to create/update your KDE <indexterm><primary>KDE</primary></indexterm> library documentation.  For that, you need to have the kde-libraries in source form.</para>
	  <para>For Linux users who have installed KDE <indexterm><primary>KDE</primary></indexterm> from a distribution, we suggest copying and extracting the source of the <filename>kdelibs-package</filename> to your system. Free BSD users who installed the kdelibs as a package should look for their appropriate distfile package in the ports-collection.</para>
	  <para> If none of these cases match your situation, you should download the sources from <ulink url="http://www.kde.org">http://www.kde.org</ulink> and <application>untar</application> the sources on your system. If you wish to use the documentation package provided by <ulink url="http://developer.kde.org">http://developer.kde.org/</ulink>, cancel the creation and continue on with creating the search index <indexterm><primary>search index</primary></indexterm>.</para>
<para> After the installer finished and <application>KDevelop</application> has been started, set the path to the extracted documentation package in the <application>KDevelop</application> Setup dialog, and run the search index <indexterm><primary>search index</primary></indexterm> setup <indexterm><primary>setup</primary></indexterm> again, which can be found at the same setup <indexterm><primary>setup</primary></indexterm> page of the dialog.</para>
	  <para>The "Update KDE <indexterm><primary>KDE</primary></indexterm>-Library documentation" dialog is set up to use a default path for the location of the documentation, in <filename>$(HOME)/.kde/share/apps/kdevelop/KDE-Documentation</filename>.  The only thing you have to do is choosing the path to your library sources you extracted on the system with the selection button on top of the dialog, and 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 <command>tar zxvf kdelibs.tar.gz</command> This will untar the sources into a directory <filename>$HOME/kdelibs</filename>, which then contains the sources for each library in a subdirectory, <abbrev>e.g.</abbrev> for <filename>kdecore</filename>, this would be on my computer in <filename>/home/rnolden/kdelibs/kdecore</filename>. Now, the path you have to enter in the KDE-Library documentation dialog would be the path to all libraries, in the example <filename>/home/rnolden/kdelibs</filename>. After pressing the <guibutton>"OK"</guibutton> button, a message in the installation window shows that the documentation generation is in progress and you should wait for the next message.</para>
	  <tip><para> On a multi-user system <indexterm><primary>multi-user system</primary></indexterm> or systems with disk-quotas <indexterm><primary>disk-quotas</primary></indexterm> for user accounts, the installation of a complete <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm> documentation for each user would be a waste of disk space. In this case, ask your system administrator to run <application>KDevelop</application> under the root account, to allow write access to the system's root directory. Then install the documentation within the KDE <indexterm><primary>KDE</primary></indexterm>directory, under <filename>$KDEDIR/share/apps/kdevelop/KDE-Documentation</filename>. The correct path can then be set up later in the <application>KDevelop</application> setup <indexterm><primary>setup</primary></indexterm> dialog, available in the <guimenu>"Options"</guimenu> menu <indexterm><primary>"Options"-menu</primary></indexterm>.</para></tip>
	</listitem>
	<listitem>
	  <para> If the system check found the <application>glimpse</application> <indexterm><primary>glimpse</primary></indexterm> program on your system, you are offered to create a search database. The search database can be created with the options of including both the KDE Documentation <indexterm><primary>KDE-Documentation</primary></indexterm> and the Qt Documentation <indexterm><primary>Qt-Documentation</primary></indexterm> (the default). Additionally the <application>KDevelop</application> 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 <indexterm><primary>search index</primary></indexterm>, the installation window will show a message that this is in progress.</para>
	</listitem>
	<listitem>
	  <para> If all installation steps were done correctly,  a final message states that <application>KDevelop</application> will be started after pressing <guibutton>"OK"</guibutton>. Mind that you can set up additional options like auto saving in the <link linkend="General-Configuration"><application>KDevelop</application> Setup</link> dialog that can be accessed through the <guimenu>"Options"</guimenu> menu.</para>
	</listitem>
      </orderedlist>
      <para><guibutton>Cancel:</guibutton>  Will show a warning message that the installation process is going to be canceled.  This warning message allows you to return to the installation (<guibutton>"Back"</guibutton>) or to start <application>KDevelop</application> with the default values (<guibutton>"Continue"</guibutton>). Mind that in this case you will have to set all options manually with the configuration dialog<indexterm><primary>configuration dialog</primary></indexterm>s provided in the <guimenu>"Options"</guimenu> menu.</para>
    </sect1>
  </chapter>

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

    <para>Now that <application>KDevelop</application> installed successfully and the most commonly used options are set, you are probably wondering if it keeps its promises. This chapter gives you a guideline to how programs are created using the <abbrev>GNU</abbrev> tools in general, and especially what part <application>KDevelop</application> plays in this game.</para>

    <sect1 id="the-compiler">
      <title>The Compiler</title>
      <para>The Compiler <indexterm><primary>Compiler</primary></indexterm> is actually the program on your system that has to be installed as a minimum 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: Open an editor of your choice - don't use a word-processor! Type in something like this to create the source for your first program:</para>
<screen>
#include &lt;iostream.h&gt;

int main(){

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

}
</screen>
      <para>Well, actually all the program will do is to print out the string "Hello World" to your standard output <indexterm><primary>output</primary></indexterm>. But this is just the source code for the program to be built, not the program itself. Therefore, we need a Compiler <indexterm><primary>Compiler</primary></indexterm>, in this case a C++-Compiler <indexterm><primary>Compiler</primary></indexterm> like <application>g++</application>. Then we can save the file with the source code, as, let's say, <filename>myprogram.cpp</filename> and invoke the Compiler <indexterm><primary>Compiler</primary></indexterm> with the filename (on a console):</para>

<screen>
<command>g++ -o myprogram myprogram.cpp</command>
</screen>

      <para>Now we can start our program: just type <command>myprogram</command>  on the console, and the program prints out the string, then exits.</para>
    </sect1>

    <sect1 id="make">
      <title>Make and Makefile<indexterm><primary>Makefile</primary></indexterm>s</title>
      
      <para>I have everything I need: an editor, a Compiler <indexterm><primary>Compiler</primary></indexterm> 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? Do you have to compile all 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. You could write a so-called "<filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm>" (You could also call it some other name, except the name of the program to build.) Then, you should have the tool <command>make</command> or <command>gmake</command> installed, or any other tool that is capable of keeping track of a project's compilation. Insert all your Compiler <indexterm><primary>Compiler</primary></indexterm> commands in the correct syntax into that <filename>Makefile</filename> <indexterm><primary>Makefile</primary></indexterm> and save it, and then you will only have to type <command>make</command> or <command>gmake</command> on the console in the directory where your <filename>Makefile</filename> <indexterm><primary>Makefile</primary></indexterm> is located, and then make takes over, leading the Compiler <indexterm><primary>Compiler</primary></indexterm> to create your application. The make utility has many other advantages and can be used to a lot of purposes.</para>
      <para>To get a complete overview, open a console and type:</para>
      <para><command>man make</command></para>
      <para>or search for "GNU Make" in <application>KDEHelp</application>, under "System GNU Info contents".</para>
      <para>Now you have some insight why a developer needs the <application>make</application> utility for making it easier to compile his application.</para>
      <para>Writing a <filename>Makefile</filename> <indexterm><primary>Makefile</primary></indexterm>s is not only hard work up, but you also have to dig yourself into the whole syntax and options. Here is the good news about <application>KDevelop</application> and any Make utility: You just have to set the Make Command in the <link linkend="General-Configuration">KDevelop Setup</link> dialog, and then you're done. All projects generated with <application>KDevelop</application> will use that Make command to build the target application, and no more typing at all. Just hit the buttons on the toolbar of <application>KDevelop</application>, beginning with the one after the second separator line, or choose the desired function for Make in the <guimenu>"Build"</guimenu> menu.</para>
      <para>The toolbar and the <guimenu>"Build"</guimenu> menu  offer the most common functions that you need to let <command>make</command> do the dirty work:</para>
      <variablelist>
	<varlistentry>
	  <term><menuchoice>
	      <guimenu>Build</guimenu>
	      <guimenuitem>Compile File</guimenuitem>
	    </menuchoice></term>
	  <listitem>
	    <para><action>Invokes the <command>make</command> command with the correct parameters to compile only the current source.</action> Only active if you're working on a source file.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
<menuchoice>
	      <guimenu>Build</guimenu><guimenuitem>Make</guimenuitem>
	    </menuchoice>
</term>
	  <listitem>
	    <para><action>Calls <command>make</command> and creates your target.</action></para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
<menuchoice>
	      <guimenu>Build</guimenu>
	      <guimenuitem>Rebuild All</guimenuitem>
	    </menuchoice>
</term>
	  <listitem>
	    <para><action>Rebuilds the whole project</action></para>
	  </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term>
<menuchoice>
	      <guimenu>Build</guimenu>
	      <guimenuitem>Clean/Rebuild All</guimenuitem>
	    </menuchoice>
</term>
	  <listitem>
	    <para><action>Cleans the project directory first and then runs <command>make</command> again</action></para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><menuchoice>
	      <guimenu>Build</guimenu>
	      <guimenuitem>Stop Build</guimenuitem>
	    </menuchoice></term>
	  <listitem>
	    <para><action>Cancels the current process</action>.</para><para>This is mostly used if you watch make working and staring at your sources. Then -ahh- I forgot about this line... and you have to correct your code. Just hit <guibutton>"Stop"</guibutton>, correct the error you found by yourself and run <command>Make</command> again.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
      
      <para>But this is not the only way <application>KDevelop</application> works together with <command>make</command> for KDE <indexterm><primary>KDE</primary></indexterm> applications.  There are some special extras, like creating the message files for internationalization. These functions are included, so no need to worry about them anymore.</para>
      <para>Now, you know about sources, the Compiler <indexterm><primary>Compiler</primary></indexterm> and why <application>make</application> is needed. In the next section, we'll discuss how projects created with <application>KDevelop</application> 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: Configure? What has to be configured? Or who?</para>
<para>Well, assume you have written a program, including a <filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm>. Then you would like to distribute it, but the compiled binary only runs on your system or on systems that are compatible with yours.</para>
<para>To support other platforms, like different Unix-systems or machines like Alphas or <abbrev>RISC</abbrev>s, 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 <indexterm><primary>Compiler</primary></indexterm> command or has some other problem to build your binary? Not to mention more difficult issues like installation paths for your program and documentation <abbrev>e.g.</abbrev>, KDE <indexterm><primary>KDE</primary></indexterm> can be installed in <filename>opt/kde/</filename> on one machine, while it is installed under <filename>/usr/local/kde/</filename> on another. In this case, you would have to rewrite the <filename>Makefile</filename> <indexterm><primary>Makefile</primary></indexterm> each time to ensure a correct compilation and installation of your product.</para>
      <para>Fortunately, <abbrev>GNU</abbrev> tools have even more to offer than that mighty <command>make</command> - the commonly used <command>automake</command> <indexterm><primary>automake</primary></indexterm> and <command>autoconf</command> <indexterm><primary>autoconf</primary></indexterm>packages. It sounds good to hear something with "auto" in the name, seems like something about application design can be done quick and easy, which exactly is the point.</para>
      <para><application>Automake</application>'s purpose is generally to create a so-called <filename>Makefile.in</filename> <indexterm><primary>Makefile.in</primary></indexterm> from a file <filename>Makefile.am</filename> <indexterm><primary>Makefile.am</primary></indexterm> which you have to write for your project. This <filename>Makefile.am</filename> <indexterm><primary>Makefile.am</primary></indexterm> consists of macros which are interpreted, and reduce the complexity that <command>make</command> offers.  A <filename>Makefile.am</filename> <indexterm><primary>Makefile.am</primary></indexterm> is written more safely and more quickly than creating the final <filename>Makefile</filename> <indexterm><primary>Makefile</primary></indexterm>by hand.</para>
      <para>Having this said, you may wonder, who is finally creating me my <filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm>? Here comes <application>autoconf</application><indexterm><primary>autoconf</primary></indexterm>. <application>Autoconf</application> requires several macro files for the project. These are in <filename>Makefile.in</filename><indexterm><primary>Makefile.in</primary></indexterm>'s generated by <application>automake</application> <indexterm><primary>automake</primary></indexterm> and a file called <filename>configure.in</filename>, also containing macros.</para>
      <para>The <filename>Makefile.am</filename> <indexterm><primary>Makefile.am</primary></indexterm> and <filename>Makefile.in</filename> files contain 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 <filename>configure</filename> shell script will check for on the system at the time <command>configure</command> is executed. These could be <abbrev>e.g.</abbrev>, the Compiler <indexterm><primary>Compiler</primary></indexterm> command, required libraries against which the final binary will be linked, include-files the project needs, and their locations.</para>
      <para>For example: you want to write a KDE <indexterm><primary>KDE</primary></indexterm> 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. Then you would write a <filename>configure.in</filename> file that contains the macros for a KDE <indexterm><primary>KDE</primary></indexterm> compliant application. That single macro eventually expands. to a check on the system whether the Qt-library is installed, checks for the Qt header files, the KDE libraries <indexterm><primary>KDE-libraries</primary></indexterm> and headers etc.</para>
      <para><emphasis>Summary:</emphasis>  To create a <abbrev>GNU</abbrev>-compliant application that is portable to different Unix OS's 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<indexterm><primary>Makefile.am</primary></indexterm></filename> for each subdirectory, including the main project directory of your project</para></step>
	<step><para>write a <filename>configure.in</filename> file, placed in the main project directory, containing the macros for system requirements.</para></step>
	<step><para>run <command>automake</command><indexterm><primary>automake</primary></indexterm></para></step>
	<step><para>run <command>autoconf</command> <indexterm><primary>autoconf</primary></indexterm></para></step>
      </procedure>
      <para>Then the main work is done. <application>Automake</application> creates the <filename>Makefile.in</filename><indexterm><primary>Makefile.in</primary></indexterm> files, then <application>autoconf</application> <indexterm><primary>autoconf</primary></indexterm> 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 <filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm> files will be generated, that allow a final execution of <command>make</command> (or <command>gmake</command>) that will process all <filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm> files and then you're done.</para>
      <para>This seems to be a lot of stuff, for simply writing a small application, and much to learn, especially how to write correct macros. But even the fact that you provide a 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 if your project's files increase in number, you only have to add the filenames to the macros.</para>
      <para>Now, how far does <application>KDevelop</application> support this kind of application development and how complicated does it get for the programmer? The good news is, that you don't even have to know anything about macros and scripts. All details are hidden behind an easy to use graphical interface doing the work for you. An application is therefore created with <abbrev>GNU</abbrev> tools in a very user friendly way.</para>
      <para>Just generate your application with <application>kappwiz</application>;<indexterm><primary>KAppWizard</primary></indexterm>, by choosing your application's needs: may it be a pure C++ terminal application, or a kind of <abbrev>GUI</abbrev><indexterm><primary>GUI</primary></indexterm> program using Qt, or the Qt/KDE <indexterm><primary>KDE</primary></indexterm> libraries. All work is done automatically and your project already contains the <filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm>s that are created by an auto execution of the <abbrev>GNU</abbrev> tools and the <filename>configure</filename> script.</para>
      <para>This is it - you're ready to extend the source of your project, may it be by adding classes <indexterm><primary>classes</primary></indexterm>, dialogs, translations or documentation, which is also completely automated. Just concentrate on the real work of the developer, which is providing functionality for the final application that you want to create. In most cases, you probably won't come in touch with <filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm> files at all when using <application>KDevelop</application>.</para>
    </sect1>

    <sect1 id="debugging">
      <title>Debugging</title>
      
      <para>The following section covers a term that is widely used by developers: Debugging.  It means that, although your Compiler <indexterm><primary>Compiler</primary></indexterm> produces the final application, your application may not run or crash during execution due to a so-called "bug" in the code. A program error described by the name of an insect, comes from the history of computing; one of the first errors <indexterm><primary>errors</primary></indexterm> that caused a machine to crash was not obviously a malfunction - real bugs were inside the computer, which were responsible for the crashes. Therefore, an error not detectable on the first look is called a "bug", so "debugging <indexterm><primary>debugging</primary></indexterm>" means to throw out bugs where they shouldn't be. </para>
      <para>Nowadays, you don't have to hunt them for real, assuming that todays computers are designed to keep them out by some kind of outer protection. They are to be found inside the code instead, mostly ending the execution of a program with the message "Segmentation fault".</para>
      <para> <abbrev>GNU</abbrev> provides another tool called <application>gdb</application>, the GNU debugger. This terminal program allows you to watch the internal values of an application, and the execution, step by step, by setting "breakpoints" in the code. <application>Gdb</application> stops the execution every time the program comes to a breakpoint while executing. But like most other tools, the debugger is handled by another program providing a front-end to it, making it easy to watch values, and set breakpoints in the code.</para>
      <para>For this purpose, your project's application is by default created with a Compiler <indexterm><primary>Compiler</primary></indexterm> option for debugging <indexterm><primary>debugging</primary></indexterm>,  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>, <application>KDevelop</application> makes use of <application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm>, the <application>KDebugger</application>.</para>
      <para>To debug your program, you just have to select <guimenuitem>"Debug"</guimenuitem> in the <guimenu>"Build"</guimenu> menu or press the corresponding tool-bar button, displayed by a wheel with  glasses over it, signaling that you want to watch the execution.</para>
      <para><application>KDevelop</application> then opens the Tools <indexterm><primary>Tools</primary></indexterm>-window and starts your application with <application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm>. The <application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm> interface appears inside the Tools <indexterm><primary>Tools</primary></indexterm> window, and allows usage just as if you started it from outside.</para>
      <para>In general, the above steps show the required steps that a developer must complete when starting to write his own application, and cover issues that are common to all projects. Also, we explained what part <application>KDevelop</application> does for a developer and how it supports the idea of providing an easy way to Unix programming. To get further information about the role and purpose of GNU tools, you should read the documentation provided with them, commonly accessed via the <command>man</command> command or by the "System GNU Info contents" section in <application>KDEHelp</application>.</para>
    </sect1>
  </chapter>

  <chapter id="development-with-kdevelop">
    <title>Development with <application>KDevelop</application></title>

    <para>In this chapter you will get a general overview of how you can use <application>KDevelop</application> and the internal dialog editor <indexterm><primary>dialog editor</primary></indexterm> to create your own applications.</para>
    <para>All tools are described by their use during the development process. If you are a beginner in C++/GUI <indexterm><primary>GUI</primary></indexterm> design and programming, you should read <ulink url="programming/index.html">The <application>KDevelop</application> Programming Handbook</ulink>, which describes some basics for program design and shows a more detailed use of <application>KDevelop</application> through sample projects which you can follow step-by-step, to get used with the way applications are created using <application>KDevelop</application>. Also you should have read chapter <link linkend="Programs">Programs</link> to gain a general understanding why Unix applications should make use of provided development tools.  This will make things easier when you hit references to what a <filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm> is, <abbrev>etc</abbrev>.</para>

    <sect1 id="what-are-kdevelop-project-applications">
      <title>What are <application>KDevelop</application> Project Applications?</title>
      
      <para>Projects created with <application>KDevelop</application> make it very easy for developers to use the <abbrev>GNU</abbrev> standard development tools. Instead of the self-creation of <filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm> files, which have to be written anyway  because of the project's complexity, the <abbrev>GNU</abbrev> tools provide not only a better method of <filename>Makefile</filename> <indexterm><primary>Makefile</primary></indexterm> generation, but also a good and safe way to provide fast adaption towards different systems through <application>autoconf</application><indexterm><primary>autoconf</primary></indexterm>-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 <indexterm><primary>Compiler</primary></indexterm> and the development libraries, which is most often the case anyway, but you can also distribute binary packages of your application. Either way, the end-user of your product does not have to have <application>KDevelop</application> installed. For giving away your sources, we advise to include the project file of <application>KDevelop</application> as well, as this makes it very easy for other developers to work with your sources if they use <application>KDevelop</application> as well. For projects where several developers, maybe working on different places, are involved, this should the case anyway, to ensure consistency of the <filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm> files so you don't run into trouble. Especially on multi-language applications, translators won't actually work with the source code, except in cases that require corrections to enable translation support. Even in those cases, translators will be thankful as <application>KDevelop</application> reduces their work to a minimum by adding their language and reducing the work to concentrating on the translation.</para>
      <para>When using <application>KDevelop</application> for your own projects, you would start creating a new application with the <application>kappwiz</application>;<indexterm><primary>KAppWizard</primary></indexterm>. There, you can set the project type according the goals of your program. Then, you would start developing the user interface by adding widgets <indexterm><primary>widgets</primary></indexterm> that are already constructed in the libraries and only have to be called by your application, or by self-constructions that can be made with the dialog editor. Next comes the extension of the user interface by changing and extending those parts that are already created by <application>KDevelop</application> like the <interface>status-bar</interface>, <interface>menu-bar</interface> and <interface>tool-bars</interface>. As resources are collected in a resource file, this can be extended simply by adding new values to the already existing ones.  The given resources can also be used as a guideline for adding your specific ones. After implementing the functionality to methods that are either generated empty by the dialog editor <indexterm><primary>dialog editor</primary></indexterm>, or already containing code for standard user actions, you should extend the User Manual by simply editing the provided <abbrev>SGML</abbrev> <indexterm><primary>SGML</primary></indexterm> index file to describing your applications capabilities. The last step would be to generate translation files and to distribute your project to translators working to enhance internationalization.</para>
      <para>But even for non-<abbrev>GUI</abbrev> <indexterm><primary>GUI</primary></indexterm> application designers the <abbrev>IDE</abbrev> offers an easy way to create new projects: the editor and Class Browser in conjunction with <application>KDevelop</application>'s powerful project management will reduce the time for development to the minimum that is required for implementation <indexterm><primary>implementation</primary></indexterm> of functionality.</para>
    </sect1>

    <sect1 id="short-description-of-kdevelops-tools-tools">
      <title>Short Description of <application>KDevelop</application>'s Tools <indexterm><primary>Tools</primary></indexterm></title>

      <para>With <application>KDevelop</application> you have chosen a package, that, in conjunction with the use of other tools, will provide you a prefect and flexible environment for object-oriented application development under Unix-Systems. Generally, <application>KDevelop</application> consists of the programming environment, and the dialog editor <indexterm><primary>dialog editor</primary></indexterm>. Besides these, all needed programs that can be helpful for designing applications are embedded in one or the other way.</para>

      <sect2 id="programming-environment-and-dialog-editor">
	<title>Programming Environment and Dialog Editor</title>
	
	<sect3 id="the-programming-environment">
	  <title>The Programming Environment</title>
	  
	  <para>The Programming Environment is the user interface that <application>KDevelop</application> provides for creating and maintaining projects, using many other tools while simplifying their use. It's built-in Editor and Help-browser <indexterm><primary>Help-browser</primary></indexterm> as well as the Class Browser reduce the amount of work that development processes usually burden on the programmer. The ease of use features make writing applications for Unix an enjoyment on it's own and will probably result in shorter release cycles and better development improvements. From here, you're managing your project throughout all its details, keep the overview over your classes <indexterm><primary>classes</primary></indexterm> and don't have to use additional consoles for your work. The integration of all user interfaces results in the fact that you only have to work with one window under X and don't have to watch for several windows spread all over your desktop.</para>
	</sect3>

	<sect3 id="the-dialog-editor">
	  <title>The Dialog Editor</title>
	  
	  <para><application>KDevelop</application>'s built-in dialog editor <indexterm><primary>dialog editor</primary></indexterm> offers a simple way of designing user interfaces with the Qt and KDE <indexterm><primary>KDE</primary></indexterm> libraries. Its simple way to do almost everything with the mouse allows a rapid construction of dialogs and main views for applications and their direct transformation into C++ code, which is directly added to the project. As the dialog editor <indexterm><primary>dialog editor</primary></indexterm> is embedded into the rest of <application>KDevelop</application>'s user interface, you have these same commands available when working in Programming mode. This allows e.g., construction of a dialog, generation of the code output, <indexterm><primary>output</primary></indexterm> and it's direct testing, all within the program, by the availability of the <command>make</command> command<indexterm><primary>make-command</primary></indexterm>. You can also still control the Compiler <indexterm><primary>Compiler</primary></indexterm> output <indexterm><primary>output</primary></indexterm> without having to switch back to the programming view. For a detailed description, see <link linkend="The-Dialog-Editor">The Dialog Editor</link>.</para>
	</sect3>
      </sect2>

      <sect2 id="kappwizard-kappwizard-and-the-classtools">
	<title><application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> and the Class-tools</title>

	<para>The <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> and the Class-tools provided for project generation and automatic code extension are intended to make the creation of applications as easy and safe as possible.  It offers a good way for beginners in Qt/KDE <indexterm><primary>KDE</primary></indexterm> programming to start actually working themselves into the details of <abbrev>GUI</abbrev> <indexterm><primary>GUI</primary></indexterm> application design, as results can be achieved very quickly.</para>

	<sect3 id="kappwizard-kappwizard">
	  <title><application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm></title>
	  
	  <para><application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> is intended to create full-functional application projects that are ready-to-run by using <abbrev>GNU</abbrev> standard tools and, for <abbrev>GUI</abbrev> <indexterm><primary>GUI</primary></indexterm>-programs, taking advantage of the KDE <indexterm><primary>KDE</primary></indexterm> and Qt libraries. By specifying only the information that is required as a minimum, users are able to start working on a new project within seconds. Calling <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> should be the first step to be to creating a new application with <application>KDevelop</application>.</para>

	  <para><application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> provides you a so called application skeleton, with all needed C++ source code files for a running application. After you have specified a project-name and set the needed preferences, your new project will be generated and you have a complete application that already contains a lot of functionality (for KDE and Qt projects), without you even having to type one line of C++ code yourself.</para>
	  <para>When specifying the complete set of options the program generator offers, your application already contains:</para>
	  <itemizedlist>
	      <listitem>
		<para>an <abbrev>SDI</abbrev>-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 <indexterm><primary>printing</primary></indexterm> dialogs</para>
	    </listitem>
	    <listitem>
	      <para>a tool-bar and status-bar already providing complete functionality</para>
	    </listitem>
	    <listitem>
	      <para>a help-system, containing an <abbrev>SGML</abbrev> <indexterm><primary>SGML</primary></indexterm>-based user manual and status-bar help</para>
	    </listitem>
	    <listitem>
	      <para>a complete <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm> based <abbrev>API</abbrev> <indexterm><primary>API</primary></indexterm> (application programming interface) documentation for the current state of the project</para>
	    </listitem>
	    <listitem>
	      <para>an installation routine though make</para>
	    </listitem>
	  </itemizedlist>

	  <para>The <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> is available under the <guimenu>"Project"</guimenu> menu entry <guimenuitem>"New..."</guimenuitem>.</para>
	</sect3>

	<sect3 id="classtools">
	  <title>Class-tools</title>

	  <para>The term "Class-tools" describes a variety of functions that are available for the developer to work on a project not only by an object-oriented language, but using the sources in an object-oriented way. Working with classes <indexterm><primary>classes</primary></indexterm> instead of having to watch for files offers a very flexible way to extend a project and lets the user concentrate on the objects the project contains.</para>
	  <para>The tools that <application>KDevelop</application> offers are a Class-generator and a Class Browser, each one providing a lot of automated functionality.</para>

	  <sect4 id="creating-a-new-class-with-the-classgenerator">
	    <title>Creating a new class with the Class-generator</title>
	    
	    <para>After generating a project with the <application>kappwiz</application>;, <indexterm><primary>KAppWizard</primary></indexterm> your work as a developer would be to add a set of classes <indexterm><primary>classes</primary></indexterm> that match the design of the application. The typical process without using <application>KDevelop</application>, would be to create a new header and source file, add them manually to the appropriate <filename>Makefile.am</filename>, <indexterm><primary>Makefile.am</primary></indexterm> and to start writing the new class <indexterm><primary>classes</primary></indexterm> declaration <indexterm><primary>declaration</primary></indexterm> and implementation<indexterm><primary>implementation</primary></indexterm>.</para>
	    <para>To simplify the whole process, the Class-generator lets you do this by only specifying the new class by its name, inherited class, and inheritance attribute, and any further information such as class documentation by it's purpose for the project. Additionally, you can change the filenames that are preset by the generator, and if the class should be Qt-signal/slot enabled by default.</para>
	    <para>The rest of the work is done automatically.  You don't have to take care of <filename>Makefile.am</filename> <indexterm><primary>Makefile.am</primary></indexterm> files and the class itself. A new <application>make</application> invocation is enough to include the new class in the compilation process.</para>
	    <para> As the Class Browser updates itself after the addition of a class, the declaration <indexterm><primary>declaration</primary></indexterm> and implementation <indexterm><primary>implementation</primary></indexterm> are available at once, and you can start working on the extension of the class. The Class-generator is invoked by the <guimenu>"Project"</guimenu> menu, entry <guimenuitem>"New Class<indexterm><primary>New Class</primary></indexterm>"</guimenuitem>.</para>
	  </sect4>

	  <sect4 id="the-class-browser">
	    <title>The Class Browser</title>

	    <para>The Class Browser displays all types of objects and functions of your project, in a tree left of the editing windows. A class parser scans all files for methods and classes, <indexterm><primary>classes</primary></indexterm> and makes them available as graphical symbols. Further, context-menus offer a specialized functionality to work with the sources, by focusing on the classes <indexterm><primary>classes</primary></indexterm> and functions.</para>
	    <para>Selecting a class will result in opening the file that contains the declaration <indexterm><primary>declaration</primary></indexterm>; on methods and functions this will
show you the implementation <indexterm><primary>implementation</primary></indexterm>. For a full description, see <link linkend="The-Class-Browser">The Class Browser</link></para>
	  </sect4>
	</sect3>
      </sect2>
    </sect1>

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

      <para>The development of a new application with <application>KDevelop</application> can generally be divided into two major steps: first, you have to generate a program skeleton with <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm>, then the "rest" of the development has to be done using <application><application>KDevelop</application>'s</application> features, which only requires your abilities as a programmer. To describe the development process, we assume you want to create a Qt/KDE <indexterm><primary>KDE</primary></indexterm> application, which implies using most of <application>KDevelop</application>'s features for working with these types of project, so you have a general "HOW-TO".</para>

      <sect2 id="creating-a-program-skeleton">
	<title>Creating a Program Skeleton</title>

	<para>To start creating your application, you normally would call the <application>kappwiz</application>;<indexterm><primary>KAppWizard</primary></indexterm>, enter the project name, and generate the program. The wizard automatically creates a project file for the application and inserts the <application>KDevelop</application> areas into the Makefile.a<indexterm><primary>Makefile.am</primary></indexterm>'s, which will be used later when extending the application. The project file is the file you load to open the project in later sessions.</para>
	<para>You call <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> with the <guimenu>"Project"</guimenu> menu entry <guimenuitem>"New..."</guimenuitem>. When the wizard appears, you first specify the project type on the first page. Selecting <guibutton>"Next &gt;&gt;"</guibutton> brings you to the next page, where you insert the project name, version, directory, and your personal information. Page 3 offers more detailed options.  Pages 4 and 5 allow the editing of file headers for header and implementation <indexterm><primary>implementation</primary></indexterm> files that are inserted automatically according to your selection. If you already have file headers you want to use, you can choose those files as well. The last page contains an output <indexterm><primary>output</primary></indexterm> window and an error message window.</para>
	<para> When selecting <guibutton>"Create"</guibutton>, your application will be generated and the actions that are executed can be seen in the output <indexterm><primary>output</primary></indexterm> window. If "READY" appears in the output <indexterm><primary>output</primary></indexterm> window, the <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> is finished, and you can select <guibutton>"Exit"</guibutton> to return to the Programming Environment. To build the binary, choose <guimenuitem>"Make"</guimenuitem> from the <guimenu>"Build"</guimenu> menu, or choose the corresponding button in the tool-bar. You can also test the functions already present, by choosing <guimenuitem>"Execute"</guimenuitem> from the <guimenu>"Build"</guimenu> menu.</para>
      </sect2>

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

	<para>This section describes the development phase of applications with <application>KDevelop</application> and the dialog editor <indexterm><primary>dialog editor</primary></indexterm>, and all work can be done within the <abbrev>IDE</abbrev>.</para>
	<para>The development steps are generally to edit the source files, the compilation of the project sources, followed by the Linker <indexterm><primary>Linker</primary></indexterm> process binding all object files to the final binary. Then errors <indexterm><primary>errors</primary></indexterm> have to be located which either prevented a compilation or linking, or are semantical bugs that can be found by a debugging <indexterm><primary>debugging</primary></indexterm> session. Finally, the documentation has to be extended and translations have to be added. But as all those steps can mix which each other, it is not that easy to describe a general way how to develop your own application. </para>
	<para>Typically, the procedure would be to first create all visible parts of the project such as the main view, and the dialogs for configuring options, then generate the source code and implement all needed connections that remain, like changing the menu-bar and tool-bars, adding status-bar help for new menu entries and filling the new member functions with the objects that display your dialogs. Then you would compile your application and test it's capabilities, fix errors <indexterm><primary>errors</primary></indexterm> and test it again.</para>
	<para>The following sections describe how this would be done; for your particular application you may choose another way. <application>KDevelop</application> leaves you enough flexibility to decide what to do at what time.</para>

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

	  <para>The User Interface of an application is what the user sees, and what he uses to interact with the program. A program generally has a menu-bar, tool-bars, and a status-bar, as well as a main view which could be for example a text input window for an editor.</para>
	  <para><application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> generated applications already contain a complex functionality in graphical interfaces; the frame structure takes care of standard elements such as bars and buttons. When developing your application, you have to extend the given structure to give the program the user interaction capability you want to provide. </para>
	  <para>One part of the work is the design of dialogs <abbrev>e.g.</abbrev>, for changing values like the brush width in a paint application. This can be done easily with the dialog editor <indexterm><primary>dialog editor</primary></indexterm> inside <application>KDevelop</application>. Now, how do you create those good-looking dialogs? As the Qt-library <indexterm><primary>Qt-library</primary></indexterm> is a <abbrev>GUI</abbrev> <indexterm><primary>GUI</primary></indexterm> toolkit, it provides a base set of so-called "widgets<indexterm><primary>widgets</primary></indexterm>" such as labels displaying plain text, line-edits for text input, and buttons for navigation and selection commands. Besides these "low-level" parts of user interfaces, standard dialogs are provided, and are ready to use, such as printing <indexterm><primary>printing</primary></indexterm> dialogs.</para>
	  <para>The KDE-libraries <indexterm><primary>KDE-libraries</primary></indexterm> are based on the Qt-library and contain replacements for certain dialogs as well as additional widgets <indexterm><primary>widgets</primary></indexterm> that can be used in your application.</para>
	  <para>So, when you start designing your application's behavior towards the user, you should make yourself comfortable with the widgets <indexterm><primary>widgets</primary></indexterm> provided with Qt and KDE <indexterm><primary>KDE</primary></indexterm>. The online-documentation of Qt offers screen-shots for most of them, so you should have a look there first. Then we advise to have a closer look at the KDE-UI library, offering other widgets <indexterm><primary>widgets</primary></indexterm>. Libraries like the KHTML <indexterm><primary>HTML</primary></indexterm> library contains very specialized widgets <indexterm><primary>widgets</primary></indexterm> that a lot of programs make use of. It just simplifies application design, using the predefined dialogs provided with Qt.</para>
	  <para>For your own dialogs, those low-level widgets <indexterm><primary>widgets</primary></indexterm> are the one you need. A dialog merely consists of a collection of different widgets<indexterm><primary>widgets</primary></indexterm>, combined together to build the interface, and is technically programmed by C++ code, in a class that is derived from <indexterm><primary>QWidget</primary></indexterm><classname>QWidget</classname>, or a more specialized dialog class that inherits <indexterm><primary>QWidget</primary></indexterm><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 how dialogs or views are used. </para>
	  <para>The dialog editor <indexterm><primary>dialog editor</primary></indexterm> of <application>KDevelop</application> now offers a nice, simple way to construct dialogs and user interfaces visually, instead of you having to combine dialogs with pure C++ code, the hard way to create interfaces. Switch to the dialog editor <indexterm><primary>dialog editor</primary></indexterm> by choosing the appropriate entry in the <guimenu>"View"</guimenu> menu (or by using the tool-bar button). You will see that <application>KDevelop</application>'s face has changed but the menubar and the toolbar are very similar. This makes it very easy to switch back and forth between the two working modes, and you will feel comfortable in both after some time.</para>
	  <para>In the dialog editor you can construct your views and dialogs as you like, and set all available preferences for the items the view will contain. When you're finished, select <guimenuitem>"Generate Sources"</guimenuitem> from the <guimenu>"Build"</guimenu> menu.  The dialog editor <indexterm><primary>dialog editor</primary></indexterm> and project management will take care of the rest. You can test if everything went OK by selecting <guimenuitem>Make</guimenuitem> or <guimenuitem>Execute</guimenuitem> from the <guimenu>"Build"</guimenu> menu.  This will build your application, including your new sources. Don't expect that dialogs are immediately usable, this is a matter of implementation<indexterm><primary>implementation</primary></indexterm>, as is the usual way a developer works. Don't worry, implementation isn't too difficult either.</para>
	  <para>For more information about creating dialogs, see <link linkend="The-Dialog-Editor">The Dialog Editor</link>. Examples and guidelines can also be found in <ulink url="programming/index-6.html">The <application>KDevelop</application> Programming Handbook</ulink>.</para>
	</sect3>

	<sect3 id="binding-new-elements">
	  <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. As described above, a usual <abbrev>GUI</abbrev><indexterm><primary>GUI</primary></indexterm>-based program contains among other things tool-bars and the main view.  In addition, the main view interacts with the bars, which are part of the main application class, and it interacts with the document object it is connected to.</para>
	  <para>In terms of object-oriented design, you would describe the given architecture as the "Document-View-Controller" model. This model describes the basic functions for objects in an application, regarding their role within the program. The Controller represents the one coordinating the main application, and provides user interaction through a menubar, toolbars, and a statusbar. The Document class takes the task of representing a document the user works with. Therefore, a document class should do all actions like loading files, and saving them again.</para>
	  <para>The view now is in the center of the application window, showing the user a part of the document visually, and providing all functions to manipulate the data by the user. As the bars and toolbars are already present, your task is to create the main view and additional dialogs, through which the user can change settings, and 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>&lt;YourApplication&gt;View</classname> which inherits the <indexterm><primary><literal>QWidget</literal></primary></indexterm><classname>QWidget</classname> class. This is the minimal class that handles visual interfaces in Qt and therefore in KDE <indexterm><primary>KDE</primary></indexterm> 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 "big" widgets <indexterm><primary>widgets</primary></indexterm> already containing a lot of functionality; just remove the View-class and replace the view-object by another.</para>
	    </listitem>
	    <listitem><para>Change the inheritance of the View-class. Change the inheritance to <abbrev>e.g.</abbrev> <classname>QMultiLineEdit</classname> and your application would be an editor.</para>
	    </listitem>
	    <listitem><para>If your main view will consist of several separated parts, create the widgets <indexterm><primary>widgets</primary></indexterm> and the classes <indexterm><primary>classes</primary></indexterm> you need with the dialog editor,<indexterm><primary>dialog editor</primary></indexterm> and create objects of these classes <indexterm><primary>classes</primary></indexterm> in the view-class constructors, that in combination, will build the main view.</para>
	    </listitem>
	  </itemizedlist>
	<para>For dialogs, things are a bit different. The usual way to call a dialog is through a menu-bar entry or a tool-bar icon. After you have constructed your dialog, and generated the sources, the class is available for creating an object that will be the dialog. So you first have to look for a suitable place in the menu-bar to add an entry which will open the dialog when selected by the user. If the already given menus do not match your needs, create a new pop-up menu just like the others, and insert in it your entry and the slot you want to call when the menu-item is selected. Then implement the slot by creating an instance of the dialog class, and call the dialog with the member functions <indexterm><primary>member functions</primary></indexterm> given by the base class.</para>
	  <para>You must also specify an ID for the menu-entry. The frame applications have all the IDs already issued collected in a file called <filename>resource.h</filename>, so you have only to add the ID and give it a new number, then you're done.  Additionally you could construct another tool-bar icon and add the status-help message. Your application now offers a new functionality which is visible to the user.</para>
<para>Now you must add the implementation <indexterm><primary>implementation</primary></indexterm> of methods that your dialog will be operating with to manipulate any values. Finally, call your make-tool or <guimenuitem>"Execute"</guimenuitem> and the changed files will be recompiled; the result of your changes can then be tested immediately.</para>
	</sect3>

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

	  <para>Above, we discussed the usual way to start working on a new application using <application>KDevelop</application> and how to extend the user interface. These are the standard steps where the <abbrev>IDE</abbrev> helps you, but <application>KDevelop</application> does more than providing tools for creating applications and their visual components. The following gives a short description of the main functionality that is offered for enhancing application development.</para>

	  <sect4 id="sourcecode-management">
	    <title>Sourcecode Management</title>

	    <para>The <application>KDevelop</application> <abbrev>IDE</abbrev> provides a lot of methods for programmers to achieve their goals within the shortest time.  As described above, the <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> and the dialog editor <indexterm><primary>dialog editor</primary></indexterm> shorten the time you would usually need to get to the same result manually. But this didn't cover the further work a programmer has to do usually: working on the implementation <indexterm><primary>implementation</primary></indexterm> of his application to provide a proper execution for the end-user.</para>
	    <para>Why is <application>KDevelop</application> the <abbrev>IDE</abbrev> you would want to use as a coding environment, including using it to create even non-<abbrev>GUI</abbrev> <indexterm><primary>GUI</primary></indexterm> applications?</para>	 
	    <para>The <abbrev>IDE</abbrev> keeps track of your project in general; that means you don't have to take care of saving changes, the <filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm> generation and so on. This is full project-management, and <application>KDevelop</application> plays out all it's power here, in any case of C++ application development. It is easy to understand, after taking away the management from the programmer, he is able to concentrate more on working out the sourcecode.</para>
	    <para>On the other hand, the code is usually spread over many different files across the project, so you can separate certain parts. This could mean working the hard way: being the developer, you still would have to struggle with creating these files and writing standard contents, like file headers containing the date and the author's name, or things like license terms for the code. This requires that you remember where your functions, class declaration<indexterm><primary>declaration</primary></indexterm>s, and implementation<indexterm><primary>implementation</primary></indexterm>s are in the project.</para>
	    <para><application>KDevelop</application> contains the "Class-tools," a variety of actions that allow fast work and move the developer's focus from files, to objects: classes,<indexterm><primary>classes</primary></indexterm> structures, and methods.</para>
	    <para>The class-generator lets you easily create a new class, including inheritance, attributes, <indexterm><primary>attributes</primary></indexterm> and documentation.</para>
	    <para>For object-oriented work, the Class Browser brings you to the location of your objects.  It doesn't matter any more where the code actually is. The Browser scans all sources automatically and rebuilds itself after additions to keep up with your work and enables you to access the new code directly. Through context-menus, the browser offers even more functionality, such as bringing you to the implementation, <indexterm><primary>implementation</primary></indexterm> or to the declaration <indexterm><primary>declaration</primary></indexterm> of member functions <indexterm><primary>member functions</primary></indexterm>. The addition of members are done graphically, in dialogs. No need to search for the file, and then the place you would have to add your entries.</para>
	    <para>Finally, you can get an even more specialized view of your project's classes <indexterm><primary>classes</primary></indexterm> through the Class-tool dialog, which provides trees that show the usage, contents, and inheritance of classes <indexterm><primary>classes</primary></indexterm> and their objects. For more detailed information, see <link linkend="The-Class-Browser">The Class Browser</link>.</para>
	  </sect4>

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

	    <para>The <application>KDevelop</application> <abbrev>IDE</abbrev> is specially designed to take away all those tasks that you have to do periodically like building and executing your program as well as locating errors <indexterm><primary>errors</primary></indexterm> in the sourcecode.</para>
	    <para>You start the build-process by:</para>
	    <itemizedlist>
	      <listitem>
		<para>clicking on the symbols <guiicon>"Build"</guiicon> or <guiicon>"Rebuild All"</guiicon> in the tool-bar</para>
	      </listitem>
	      <listitem>
		<para>or selecting <menuchoice><guimenu>Build</guimenu><guimenuitem>Rebuild All</guimenuitem></menuchoice> from the menu.</para>
	      </listitem>
	    </itemizedlist>	 
	    <para>To execute your application, choose</para>
	    <itemizedlist>
	      <listitem>
		  <para>the symbol <guiicon>"Execute"</guiicon> or <guiicon>"Debug"</guiicon> (starting <application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm> with your program) from the tool-bar</para>
	      </listitem>
	      <listitem>
		  <para>
		  <menuchoice>
		    <guimenu>Build</guimenu><guimenuitem>Execute</guimenuitem>
		  </menuchoice>or
		<menuchoice>
		  <guimenu>Build</guimenu><guimenuitem>Debug</guimenuitem></menuchoice> from the menu.</para>
	      </listitem>
	      <listitem><para>
		<menuchoice><guimenu>Build</guimenu><guimenuitem>Execute with Arguments</guimenuitem></menuchoice> to start your application with additional arguments</para>
	      </listitem>
	    </itemizedlist>
	    <para>For more information about the build-process, see <link linkend="Projects">Projects</link>.</para>
	  </sect4>

	  <sect4 id="searching-program-errors">
	    <title>Searching For Program Errors</title>

	    <para>Errors may<indexterm><primary>errors</primary></indexterm> occur either during the build-process (which are detected by the Compiler <indexterm><primary>Compiler</primary></indexterm> and are called syntactical errors <indexterm><primary>errors</primary></indexterm> because they result from a wrong syntax of the sources), or during the execution of the application.  Those errors have to be found and removed by the programmer. To locate errors<indexterm><primary>errors</primary></indexterm>, the developer needs the information as to what exactly caused its occurrence.</para>
	    <para>As mentioned, the Compiler <indexterm><primary>Compiler</primary></indexterm> is able to detect syntax errors <indexterm><primary>errors</primary></indexterm> itself, resulting in an error message that the executable can't be built. Note that this can also happen from the Linker <indexterm><primary>Linker</primary></indexterm> when it detects "unresolved symbols"; see <link linkend="Linker-Options">Linker Options</link>).</para>
	    <para>As the compiler gives as detailed as possible a description of the error, the error can be found and removed. During the build-process, you will see the output <indexterm><primary>output</primary></indexterm> window pop up showing you what your make-tool and the Compiler <indexterm><primary>Compiler</primary></indexterm> has to say. In case of errors <indexterm><primary>errors</primary></indexterm> or warnings <indexterm><primary>warnings</primary></indexterm>, just press the mouse button over the error line and the editor will open the affected file and sets the cursor to the error line. This can also be done by the entries in the <guimenu>"View"</guimenu>menu, <guimenuitem>"Next Error"</guimenuitem> and <guimenuitem>"Previous Error"</guimenuitem> or by the appropriate keyboard shortcuts <indexterm><primary>shortcuts</primary></indexterm>. You will find that this is very functional and saves a lot of time to get to the error, although to remove the cause, your knowledge as a programmer is asked.</para>
	    <para>Runtime Errors, which occur during execution and will mostly result in a segmentation fault, are sometimes hard to find. Therefore, you can enable the Compiler <indexterm><primary>Compiler</primary></indexterm> to add information within the binary to watch the execution by the sourcecode. A debugger is a program that lets you do this by starting the application and letting you set breakpoints in the code, where the execution stops, so you can control critical implementation<indexterm><primary>implementation</primary></indexterm>s and by this detect at least the line that caused the error. Finding the real cause is another task, it depends on the programmer to locate this.</para>
	    <para>The <command>gdb</command> is a debugger that is provided with the <abbrev>GNU</abbrev> Compiler <indexterm><primary>Compiler</primary></indexterm> and programs like <application>ddd</application> or <application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm> are front-ends that allow easier use. <application>KDevelop</application> uses <application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm> and lets you invoke the debugging <indexterm><primary>debugging</primary></indexterm> process by the commands <guimenuitem>"Debug"</guimenuitem> in the <guimenu>"Build"</guimenu>menu or by the <guiicon>"Debug"</guiicon> icon in the tool-bar. For more information about debugging <indexterm><primary>debugging</primary></indexterm> applications, see <link linkend="Projects">Projects</link> and <ulink url="programming/index-12.html">The <application>KDevelop</application> Programming Handbook</ulink>.</para>
	  </sect4>
	</sect3>
      </sect2>
    </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 <application>KDevelop</application> <abbrev>IDE</abbrev> and in the following other documentation:</para>

      <itemizedlist>
	<listitem>
	  <para><ulink url="programming/index.html">The <application>KDevelop</application> Programming Handbook</ulink>, covering a complete introduction into <abbrev>GUI</abbrev> <indexterm><primary>GUI</primary></indexterm> application design and programming with the Qt and KDE <indexterm><primary>KDE</primary></indexterm> libraries.</para>
	</listitem>
	<listitem>
	  <para>This handbook, sections <link linkend="Overview">Overview</link> to <link linkend="Projects">Projects</link>, describing all available functions within <application>KDevelop</application>. </para>
	</listitem>
	<listitem>
	  <para>This handbook, section <link linkend="The-Dialog-Editor">The Dialog Editor</link>, addressing the use of the dialog editor <indexterm><primary>dialog editor</primary></indexterm> to create your own widgets. <indexterm><primary>widgets</primary></indexterm></para>
	</listitem>
	<listitem>
	  <para>The <emphasis>Online-Reference <indexterm><primary>Reference</primary></indexterm> Documentation</emphasis> to the Qt-library <indexterm><primary>Qt-library</primary></indexterm>, which covers examples of using the Qt <abbrev>GUI</abbrev><indexterm><primary>GUI</primary></indexterm>-toolkit, as well as a class reference and screenshots for the most important ready-to-use widgets <indexterm><primary>widgets</primary></indexterm> included.</para>
	</listitem>
	<listitem>
	  <para>The KDE-Library Class-Reference <indexterm><primary>Reference</primary></indexterm>, generated automatically by <application>KDevelop</application> from the KDE-Library sources, containing descriptions for all classes <indexterm><primary>classes</primary></indexterm> and widgets <indexterm><primary>widgets</primary></indexterm> including example code for their use,</para>
	</listitem>
	<listitem>
	  <para>And on the Internet, see:
            <itemizedlist>
	      <listitem>
		<para><ulink url="http://www.troll.no">http://www.troll.no/</ulink> for information about Qt and additional third-party widgets <indexterm><primary>widgets</primary></indexterm></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>on the <application>KDevelop</application> home page <ulink url="http://www.kdevelop.org">http://www.kdevelop.org/</ulink></para>
	      </listitem>
	    </itemizedlist>
          </para>
	</listitem>
      </itemizedlist>
    </sect1>
  </chapter>

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

    <para>Looking at <application>KDevelop</application>, the user interface can be described by it's logical separation: the main window, the treeview and the output <indexterm><primary>output</primary></indexterm> window, surrounded by the menubar, toolbars and the statusbar. This section describes the purpose of each part of the interface, starting with the windows, followed by the bars and the functions they provide.</para>

    <sect1 id="main-window">
      <title>Main Window</title>
      
      <para>The main window consists of four tabs, of which the left two are for editing purposes. First comes the <guilabel>Header/Resource window</guilabel> for headers and any other text files, e.g., the documentation <abbrev>SGML</abbrev><indexterm><primary>SGML</primary></indexterm>'s.   Next is the <guilabel>C/C++ window</guilabel> for sourcecodes. These are followed by the <guilabel>Documentation window</guilabel> displaying documentation in <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm>format. Finally there is the Tools <indexterm><primary>Tools</primary></indexterm> window for external programs like <application>KIconEdit</application> <indexterm><primary>KIconEdit</primary></indexterm>and <application>kdbg</application>;, <indexterm><primary>KDbg</primary></indexterm> which are embedded into the <abbrev>IDE</abbrev>.</para>
      <para>Any Tool that is registered, can be accessed via the <guimenu>"Tools"</guimenu><indexterm><primary>Tools</primary></indexterm> menu. The registration of third-party programs can easily be done in a configuration dialog <indexterm><primary>configuration dialog</primary></indexterm> (see <link linkend="General-Configuration">General Configuration</link>).</para>
      <para> For a description of the Editor windows functionality, see chapter <link linkend="Working-with-the-Editor">Working with the Editor</link>, and for the Helpbrowser <indexterm><primary>Helpbrowser</primary></indexterm>, you should look at section <link linkend="Using-the-Documentation-Browser">Using the Documentation Browser</link>.</para>
    </sect1>

    <sect1 id="the-class-browser-and-fileviewers">
      <title>The Class Browser and File-viewers</title>
      
      <sect2 id="the-class-viewer-class-viewer">
	<title>The Class Viewer <indexterm><primary>Class Viewer</primary></indexterm></title>
	
	<para>The Class Viewer <indexterm><primary>Class Viewer</primary></indexterm> (<abbrev>CV</abbrev><indexterm><primary>CV</primary></indexterm>) shows the classes <indexterm><primary>classes</primary></indexterm> of your project, as well as global functions and variables<indexterm><primary>variable</primary></indexterm>. </para>
	<para>Opening the tree will show all member functions <indexterm><primary>member functions</primary></indexterm> and members, with symbols for attributes <indexterm><primary>attributes</primary></indexterm> (private, protected and public, signals, and slots,) so you can see the properties of members visually without switching to the header file. </para>
	<para> Selecting the class name will open the headerfile containing the class, and set the cursor to the class declaration <indexterm><primary>declaration</primary></indexterm> beginning.</para>
	<para> Selecting member functions <indexterm><primary>member functions</primary></indexterm> will open the implementation <indexterm><primary>implementation</primary></indexterm> file, and place the cursor at the function header. For elements, <application>KDevelop</application> will look for the header file and place the cursor at the line the element is declared.</para>
	<para>The class-viewer <indexterm><primary>classviewer</primary></indexterm> also provides pop-up-menus that offer more specified options.  See <link linkend="The-Class-Browser">The Class Browser</link> for more detailed information.</para>
      </sect2>

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

	<para>The Logical File Viewer (<abbrev>LFV</abbrev><indexterm><primary>LFV</primary></indexterm>) allows sorting files, by filters and in groups.</para>
	<para> Individual groups can be added by the <guimenuitem>properties</guimenuitem> entry of the <guimenu>"Project"</guimenu> menu or by a <mousebutton>right</mousebutton> click on the tree items. This allows a more specialized search for files that you want to access quickly, in the first place only showing project-included files. According to their Mime-type, the files will be opened when selected. You will like the <abbrev>LFV</abbrev> <indexterm><primary>LFV</primary></indexterm> for things like selecting pixmaps. <indexterm><primary>pixmaps</primary></indexterm> This will start <application>KIconEdit</application> <indexterm><primary>KIconEdit</primary></indexterm> (if installed on the system,) in the <interface>Tools</interface> <indexterm><primary>Tools</primary></indexterm>window, and open the chosen picture.</para>
      </sect2>

      <sect2 id="the-real-file-viewer">
	<title>The Real File Viewer</title>
	
	<para>The Real File Viewer (<abbrev>RFV</abbrev><indexterm><primary>RFV</primary></indexterm>) shows the project directory tree with all files, so you can edit non-project files, <indexterm><primary>project files</primary></indexterm> or files hidden by the <abbrev>LFV</abbrev> <indexterm><primary>LFV</primary></indexterm> e.g.,<filename>configure.in</filename> and <filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm>s. Pop-up menus also provide functions like adding or removing files to the current project.</para>
      </sect2>

      <sect2 id="the-documentation-tree">
	<title>The Documentation Tree</title>
	
	<para>The Documentation Tree (<abbrev>DOC</abbrev><indexterm><primary>DOC</primary></indexterm>) displays all available <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm>based documentation that is configured, as books. Selecting a book will open the first page in the Browser window. Also, a pop-up menu provides personal configuration for additional <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm>based documentation packages.</para>
      </sect2>
    </sect1>
    
    <sect1 id="output-window">
      <title>Output window</title>

      <para>The Output window is separated further into a messages window, a stdin/stdout window and a stderr window, for the following necessities:</para>
      <variablelist>
	<varlistentry>
	  <term>Messages Window</term>
	  <listitem><para>Displays all output<indexterm><primary>output</primary></indexterm> of the Compiler<indexterm><primary>Compiler</primary></indexterm>. Clicking on error messages will change the edit widget to set the cursor to the line where the Compiler <indexterm><primary>Compiler</primary></indexterm> found an error.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>stdout Window</term>
	  <listitem><para>Display for terminal based applications that send messages to the standard output<indexterm><primary>output</primary></indexterm> of the computer. Note that Terminal applications are now started in an external console window.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>stderr window</term>
	  <listitem><para>Displays all the error messages your program produces. This is useful for testing purposes. The Output window is programmed to show up each time an external process is called, such as make or a terminal application.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect1>
    
    <sect1 id="menubar-menubar-commands">
      <title>Menu-bar <indexterm><primary>Menu-bar</primary></indexterm> Commands</title>
      
      <sect2 id="file-management-and-printing">
	<title>File Management and Printing</title>
	
	<para>This section covers the functions that <application>KDevelop</application> provides about files, accessed via the <guimenu>File</guimenu> menu in the menu-bar or by the corresponding icons in the toolbar:
<indexterm><primary>"File"-menu</primary></indexterm></para>

	<variablelist>
	  <varlistentry>
	    <term>
              <menuchoice>
		<shortcut>
		  <keycombo><keycap>Ctrl</keycap><keycap>N</keycap></keycombo>
		</shortcut>
		<guimenu>File</guimenu>
		<guimenuitem>New</guimenuitem>
	      </menuchoice>
	      </term>
	    <listitem><para><action>Opens the "New File<indexterm><primary>New File</primary></indexterm>" dialog, allowing the creation of a new file. The file can be created using different templates and the filename must be given, as well as the path where the file will be created.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
		<menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>O</keycap></keycombo></shortcut>
		<guimenu>File</guimenu><guimenuitem>Open</guimenuitem>
	      </menuchoice>
	      </term>
	    <listitem>
	      <para><action>displays the "Open File..." dialog and lets you choose a file to be opened.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
		<menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo></shortcut>
		<guimenu>File</guimenu><guimenuitem>Close</guimenuitem>
	      </menuchoice>
	      </term>
	    <listitem>
	      <para><action>Closes the file in the top editing window</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo></shortcut>
		<guimenu>File</guimenu><guimenuitem>Save</guimenuitem>
	      </menuchoice>
	      </term>
	    <listitem><para><action>Saves the file open in the top editing window.  If the file has never been saved, the "Save File As..." dialog will be opened, to let you choose a path and filename for the file.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
              <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>A</keycap></keycombo></shortcut>
		<guimenu>File</guimenu><guimenuitem>Save As...</guimenuitem>
	      </menuchoice></term>
	    <listitem>
	      <para><action>Opens the "Save File As..." dialog to let you save the current file under a new filename</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
              <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>l</keycap></keycombo></shortcut>
		<guimenu>File</guimenu><guimenuitem>Save All</guimenuitem>
	      </menuchoice>
		</term>
	    <listitem>
	      <para><action>Saves all changed files.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>P</keycap></keycombo></shortcut>
		<guimenu>File</guimenu><guimenuitem>Print...</guimenuitem>
	      </menuchoice>
	   </term>
	    <listitem><para><action>Opens the "Print File" dialog where you can set various options for printing, using either <application>enscript</application> or <application>lpr</application>.
		    </action>
		  </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo></shortcut>
		<guimenu>File</guimenu><guimenuitem>Quit</guimenuitem>
	      </menuchoice>
		</term>
	    <listitem><para><action>Exits <application>KDevelop</application>. If files have been changed, you will be asked if you want to save these files.</action></para>
	    </listitem>
	  </varlistentry>
	</variablelist>

      </sect2>

      <sect2 id="editing-files">
	<title>Editing Files</title>
	
	<para><indexterm><primary>"Edit" menu</primary></indexterm>
Here, the <guimenu>"Edit"</guimenu> menu and the corresponding icons in the tool-bar are covered. The editing functions are also available via a context-menu in the editor<indexterm><primary>editor</primary></indexterm>.</para>
	
	<variablelist>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>Z</keycap></keycombo></shortcut>
		<guimenu>Edit</guimenu><guimenuitem>Undo</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Reverts the last editing operation</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo></shortcut>
		<guimenu>Edit</guimenu><guimenuitem>Redo</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Lets you do the last undone step again.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut>
		  <keycombo>
		    <keycap>Ctrl</keycap>
		    <keycap>X</keycap>
		  </keycombo>
		</shortcut>
		<guimenu>Edit</guimenu>
		<guimenuitem>Cut</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para>
		<action>Cuts out the selection and copies it to the system clipboard.
		</action>
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut>
		  <keycombo>
		    <keycap>Ctrl</keycap>
		    <keycap>C</keycap>
		  </keycombo>
		</shortcut>
		<guimenu>Edit</guimenu>
		<guimenuitem>Copy</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem><para><action>copies a selection to the system clipboard.  This also includes selections made in the documentation browser</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo></shortcut>
		<guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem><para><action>Inserts the clipboard contents at the current cursor position</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>I</keycap></keycombo></shortcut>
		<guimenu>Edit</guimenu><guimenuitem>Indent</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Moves a selection to the right</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>U</keycap></keycombo></shortcut>
		<guimenu>Edit</guimenu><guimenuitem>UnIndent</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Moves a selection to the left.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>Insert</keycap></keycombo></shortcut>
		<guimenu>Edit</guimenu><guimenuitem>Insert File..</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Lets you select a file and the inserts that files contents at the current cursor position.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>F</keycap></keycombo></shortcut>
		<guimenu>Edit</guimenu><guimenuitem>Search...</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the Search dialog that looks for an expression in the current file.  To search across several files, "Search in Files..." should be used.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>F3</keycap></keycombo></shortcut>
		<guimenu>Edit</guimenu><guimenuitem>Repeat Search</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Repeats the last search for an expression.  This also works for searches made across documentation, where more than one hit was found in the same page.  The next hit will be displayed by choosing <guimenuitem>Repeat Search</guimenuitem> or pressing <keycap>F3</keycap>.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>R</keycap></keycombo></shortcut>
		<guimenu>Edit</guimenu><guimenuitem>Replace...</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the "Search and Replace" dialog, which allows the search for an expression, and replaces the found text with a new expression.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F</keycap></keycombo></shortcut>
		<guimenu>Edit</guimenu><guimenuitem>Search in Files...</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>
		  Displays the "Search in files..." dialog, that works <application>grep <indexterm><primary>grep</primary></indexterm></application> on whole directories with wildcards. Search results are displayed with a list of the filenames, line and expression. Choosing an entry will open that file and the cursor is set to the line of the search result. <indexterm><primary>search result</primary></indexterm></action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>A</keycap></keycombo></shortcuT>
		<guimenu>Edit</guimenu><guimenuitem>Select All</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Selects the whole text of the file currently open in the editing window</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Edit</guimenu><guimenuitem>Deselect All</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Deselects the whole text of the current file.  This is often used for multiple selections so you don't have to find and deselect each one separately.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Edit</guimenu><guimenuitem>Invert Selection</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Inverts the selection. Text previously selected becomes deselected, and text which was not selected becomes selected.</action></para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect2>

      <sect2 id="view-configuration">
	<title>View Configuration</title>
	
	<para><indexterm><primary>"View"-menu"</primary></indexterm>The <guimenu>View-Menu</guimenu> covers closing and opening functions for windows, and commands to enable/disable the tool- and status-bar, as well as to jump to errors <indexterm><primary>errors</primary></indexterm> in the code.</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>G</keycap></keycombo></shortcut>
		<guimenu>View</guimenu><guimenuitem>Goto Line</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens a "Go to Line..." dialog that lets you insert a line-number to show in the actual file.  The last line-number is remembered and marked, so you can either jump to that line again directly, or enter a new line number that you want to see.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>F4</keycap></keycombo></shortcut>
		<guimenu>View</guimenu><guimenuitem>Next Error</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Jumps to the next error <application>KDevelop</application> detects from the output<indexterm><primary>output</primary></indexterm>.  The output <indexterm><primary>output</primary></indexterm> message of <application>Make</application> or other tools should give you a description of the problem is, so you can correct the error.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Shift</keycap><keycap>F4</keycap></keycombo></shortcut>
		<guimenu>View</guimenu><guimenuitem>Previous Error</guimenuitem>
	      </menuchoice
	    </term>
	    <listitem>
	      <para><action>Jumps to the previous reported error</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>D</keycap></keycombo></shortcut>
		<guimenu>View</guimenu><guimenuitem>Dialog Editor</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action> Switches to the dialog editor. <indexterm><primary>dialog editor</primary></indexterm></action> </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>T</keycap></keycombo></shortcut>
		<guimenu>View</guimenu><guimenuitem>Tree-View</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Enables or disables the Tree window on the left side of the main view containing the Class Browser, <guilabel>LFV</guilabel><indexterm><primary>LFV</primary></indexterm>, <guilabel>RFV</guilabel><indexterm><primary>RFV</primary></indexterm> and <guilabel>DOC</guilabel><indexterm><primary>DOC</primary></indexterm>-tree.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>B</keycap></keycombo></shortcut>
		<guimenu>View</guimenu><guimenuitem>Output-View</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Enables or disables the Output window on the bottom of the main view.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>View</guimenu><guimenuitem>Tool-bar</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Enables or disables the tool-bar.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>View</guimenu><guimenuitem>Browser-Tool-bar</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Enables or disables the browser tool-bar, containing the back, forward, and search buttons for the browser.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>View</guimenu><guimenuitem>Refresh</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Rescans all files to rebuild the Class Browser.  The scanning progress is shown in the status-bar progress display.</action></para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect2>

      <sect2 id="creating-and-maintaining-projects">
	<title>Creating and Maintaining Projects</title>
	
	<para><indexterm><primary><guimenu>"Project"menu</guimenu></primary></indexterm>This section describes functions that are available in the <guimenu>"Project"</guimenu> menu and cover the creation and maintenance of projects.</para>
	
	<variablelist>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Project</guimenu><guimenuitem>New...</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Starts the <application>kappwiz</application>;, and allows you to create a new project by choosing application type, name, version, and other options.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Project</guimenu><guimenuitem>Open</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Shows the "Open Project" dialog, where you can choose a <application>KDevelop</application> project file to be opened.  After selection, the project will be loaded.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Project</guimenu><guimenuitem>Open Recent Project</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Contains a sub-menu with the last 5 opened projects.  You can open a project more easily using the recent project menu.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Project</guimenu><guimenuitem>Close</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Closes the current project.  This is mostly done automatically when you quit <application>KDevelop</application>, invoke the <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm>or open another project.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Project</guimenu><guimenuitem>New Class</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Starts the class generator to create a new class that will be added to the current project. The class generator lets you specify classname, inheritance and filenames for the new class.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Project</guimenu><guimenuitem>Add Existing File(s)</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action> Opens a selection dialog where you can choose the files that you want to add to the current project, and the path where they will be copied to. If you choose a destination that was currently not included in the project, for example, creating a new subdirectory, <application>KDevelop</application> will copy the files to add to the new subdirectory, and create a new <filename>Makefile.am</filename><indexterm><primary>Makefile.am</primary></indexterm>. After the copy process, your project will be rebuilt by <application>automake</application><indexterm><primary>automake</primary></indexterm> and <application>autoconf</application><indexterm><primary>autoconf</primary></indexterm> to include the new subdirectory into the make-process.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Project</guimenu><guimenuitem>Add new translation file</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens a language selection dialog that lets you choose the translation file language that will be added to the project. This is mostly used by translators, who can easily add their language to the project and work on the translation without having to care about the <filename>Makefile.am<indexterm><primary>Makefile.am</primary></indexterm>'s</filename>.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Shift</keycap><keycap>F7</keycap></keycombo></shortcut>
		<guimenu>Project</guimenu><guimenuitem>File Properties</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the File Properties dialog showing a copy of the <guilabel>LFV</guilabel> <indexterm><primary>LFV</primary></indexterm> and the project file options. Here, the properties for your files have to be set, like installation path, and file type.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Project</guimenu><guimenuitem>Make messages and merge</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>This is intended to create the messages file for your project. The message file is the one containing all strings that are set up in the sources for internationalization, and is used by translators to create the .po file for their target language.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Project</guimenu><guimenuitem>Make API<indexterm><primary>API</primary></indexterm>-Doc</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action> Calls <application>KDoc</application> <indexterm><primary>KDoc</primary></indexterm> on your header files, and generates a HTML <indexterm><primary>HTML</primary></indexterm> output <indexterm><primary>output</primary></indexterm> with the documentation of your project classes<indexterm><primary>classes</primary></indexterm>.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Project</guimenu><guimenuitem>Make User Manual</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Runs <application>KSgml2Html</application> <indexterm><primary>KSgml2Html</primary></indexterm> on your manual SGML <indexterm><primary>SGML</primary></indexterm> file, creating an HTML <indexterm><primary>HTML</primary></indexterm> user manual. If <application>KSgml2Html</application> <indexterm><primary>KSgml2Html</primary></indexterm> is not installed, <application>sgml2html</application> will be used to do this.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Project</guimenu><guisubmenu>Make Distribution</guisubmenu><guimenuitem>tar.gz</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Creates a distribution file of your current project in the project directory that is ready to ship to the end-users containing the sources of your project. The end-user has to run <command>tar zxvf <replaceable>yourproject.tar.gz</replaceable> </command> to unpack it to a source directory, and then use the standard commands <command>./configure</command>,<command>make</command> and <command>make install</command>.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>F7</keycap></keycombo></shortcut>
		<guimenu>Project</guimenu><guimenuitem>Options</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem> 
	      <para><action>Opens the Project Options dialog that lets you change various settings for your project. This could be a new version number, or perhaps to set the compiler options <indexterm><primary>compiler options</primary></indexterm> to <option>-02</option> for a release with optimization.</action></para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect2>

      <sect2 id="building-projects">
	<title>Building Projects</title>
	
	<para><indexterm><primary>"Build" menu</primary></indexterm> This section describes the <guimenu>Build</guimenu> menu that contains all actions to be done with <command>make</command> or actions like rebuilding the project's online help or <abbrev>API</abbrev> <indexterm><primary>API</primary></indexterm> documentation.</para>
	
	<variablelist>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>F8</keycap></keycombo></shortcut>
		<guimenu>Build</guimenu><guimenuitem>Compile file...</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Active, if the top editing window is the C++ Window. This only compiles the current implementation <indexterm><primary>implementation</primary></indexterm> file, and lets you save time in case you suspect errors<indexterm><primary>errors</primary></indexterm>.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>F8</keycap></keycombo></shortcut>
		<guimenu>Build</guimenu><guimenuitem>Make</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Invokes the make-command <indexterm><primary>make-command</primary></indexterm> on your project, and builds the target.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Build</guimenu><guimenuitem>Clean Rebuild All</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Cleans the project directory from all make-created files and rebuilds the target.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>F10</keycap></keycombo></shortcut>
		<guimenu>Build</guimenu><guimenuitem>Stop Build</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Stops the current process.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>	      
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>F9</keycap></keycombo></shortcut>
		<guimenu>Build</guimenu><guimenuitem>Execute</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Executes your target, after building the program with <application>make</application>.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Alt</keycap><keycap>F9</keycap></keycombo></shortcut>
		<guimenu>Build</guimenu><guimenuitem>Execute with Arguments</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Executes your target with arguments. First, a dialog appears to let you specify the execution arguments (which are saved in the project for the next session), then your application uses the entered commandline. Note that your application program is started from the project directory directly.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Build</guimenu><guimenuitem>Debug...</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens <application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm> in the Tools<indexterm><primary>Tools</primary></indexterm>-Window to debug your application. In this case, <application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm> automatically opens the file containing the main() function and executes your application.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Build</guimenu><guimenuitem>DistClean</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Removes all files that are generated by the project like object files etc. Distclean has to be done before distributing your project, so the distribution file doesn't contain any platform-specific files like those that were generated by your Compiler<indexterm><primary>Compiler</primary></indexterm>.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Build</guimenu><guimenuitem>Autoconf and automake</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Calls <command>Make</command> on the file <filename>Makefile.dist</filename><indexterm><primary>Makefile.dist</primary></indexterm>, located in your main project directory. Makefile.dist <indexterm><primary>Makefile.dist</primary></indexterm> contains all the commands for automake <indexterm><primary>automake</primary></indexterm>, autoconf <indexterm><primary>autoconf</primary></indexterm> etc., to build your project. If you added files manually or changed macros yourself, you should run <command>Autoconf</command> afterwards, followed by <command>Configure</command> to recreate all <filename>Makefile<indexterm><primary>Makefile</primary></indexterm>s</filename>.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Build</guimenu><guimenuitem>Configure</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Executes the configure-script generated by <command>autoconf</command> <indexterm><primary>autoconf</primary></indexterm>. If this command cannot be executed, run <command>Autoconf</command> and then run <command>Configure</command> again.</action></para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect2>

      <sect2 id="calling-tools-tools">
	<title>Calling Tools <indexterm><primary>Tools</primary></indexterm></title>
	
	<para><indexterm><primary>"Tools"-menu</primary></indexterm>The <guimenu>"Tools"</guimenu> <indexterm><primary>Tools</primary></indexterm> menu contains by default the entries for the following programs if installed: <application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm>, KIconEdit <indexterm><primary>KIconEdit</primary></indexterm> and KTranslator <indexterm><primary>KTranslator</primary></indexterm>. These are
checked by the <application>KDevelop</application> installation program and inserted in the given order into the menu. Invoking a tool will open the "Tools" window and start the selected program inside this window. The <guimenu>"Tools"</guimenu> <indexterm><primary>Tools</primary></indexterm> menu can be edited by the <guimenuitem>"Tools"</guimenuitem> <indexterm><primary>Tools</primary></indexterm>-entry in the <guimenu>"Options"</guimenu> menu; see <link linkend="Configuring-the-Tools-Menu">Configuring the Tools Menu</link>.</para>
      </sect2>

      <sect2 id="changing-kdevelops-settings">
	<title>Changing <application><application>KDevelop</application>'s</application> settings</title>
	
	<para><indexterm><primary>"Options"-menu</primary></indexterm>The <guimenu>"Options"</guimenu> menu contains all entries for invoking configuration dialogs, <indexterm><primary>configuration dialog</primary></indexterm>s with which you can change <application>KDevelop</application>'s default settings.</para>
	<para>Major settings like those for the editor <indexterm><primary>editor</primary></indexterm> or printing <indexterm><primary>printing</primary></indexterm> have their own entries; general setting of <application>KDevelop</application>'s behavior can be made with the <link linkend="KDevelop-Setup"><application>KDevelop</application> Setup</link> dialog.</para>

	<variablelist>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Options</guimenu><guimenuitem>Editor</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Allows the configuration of the editors behavior such as word-breaking, selections, etc.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Options</guimenu><guimenuitem>Editor Colors...</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem><para><action>Here, you can set the color-configuration of the editor <indexterm><primary>editor</primary></indexterm>  e.g. the background and text colors.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Options</guimenu><guimenuitem>Editor Defaults...</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>This sets the default display, e.g., the default font and font size for the editor <indexterm><primary>editor</primary></indexterm></action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Options</guimenu><guimenuitem>Syntax-Highlighting</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>This dialog lets you configure the fonts and colors for the highlighting of several programming languages, including HTML<indexterm><primary>HTML</primary></indexterm>.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Options</guimenu><guimenuitem>Documentation Browser</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>In this tab-dialog, you can set the fonts, sizes and colors for the internal Helpbrowser <indexterm><primary>Helpbrowser</primary></indexterm>.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Options</guimenu><guimenuitem>Configure Printer...</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Contains the entries for the printer configuration dialog <indexterm><primary>configuration dialog</primary></indexterm>s.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Options</guimenu><guisubmenu>Configure Printer...</guisubmenu><guimenuitem>enscript</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action> Configures the printer for use with <application>enscript</application> <indexterm><primary>enscript</primary></indexterm>. See <link linkend="printing">Printing</link> for more information.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Options</guimenu><guimenuitem>Tools</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the Configure Tools <indexterm><primary>Tools</primary></indexterm> dialog. Here, you can configure the "Tools<indexterm><primary>Tools</primary></indexterm>" menu by adding or removing programs that will be started in the Tools <indexterm><primary>Tools</primary></indexterm>-window.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Options</guimenu><guimenuitem>KDevelop Setup</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the <application>KDevelop</application> Setup dialog. The first tab configures general settings, followed by the key-configuration and the Documentation settings. The Documentation settings also include the generation of a new set of HTML <indexterm><primary>HTML</primary></indexterm>-library documentation, and the rebuilding of the search index <indexterm><primary>search index</primary></indexterm> for the Helpbrowser <indexterm><primary>Helpbrowser</primary></indexterm>.</action></para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect2>

      <sect2 id="the-window-menu">
	<title>The Window Menu</title>
	
	<para><indexterm><primary>"Window"-menu</primary></indexterm>The <guimenu>Window</guimenu> menu contains a list with all currently open files. This allows a quick switch between files you're currently working on.</para>
      </sect2>

      <sect2 id="managing-bookmarks">
	<title>Managing Bookmarks</title>
	
	<para><indexterm><primary>"Bookmarks"-menu</primary></indexterm> The <guimenu>Bookmarks</guimenu> menu is intended for adding and removing bookmarks <indexterm><primary>bookmarks</primary></indexterm> you want to set in the current editing file. As <application>KDevelop</application> uses two editing windows, each one configures it's bookmarks <indexterm><primary>bookmarks</primary></indexterm> separately.</para>

	<variablelist>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Bookmarks</guimenu><guimenuitem>Set Bookmark</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens a context-menu with up to nine configurable bookmarks<indexterm><primary>bookmarks</primary></indexterm>. This allows setting a bookmark to a certain entry in the bookmarks <indexterm><primary>bookmarks</primary></indexterm> menu by logical reasons.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>A</keycap></keycombo></shortcut>
		<guimenu>Bookmarks</guimenu><guimenuitem>Add Bookmark</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Adds the line of the current cursor position to the bookmarks <indexterm><primary>bookmarks</primary></indexterm> menu as a bookmark. Mind that this could overwrite a bookmark set with the Set Bookmark-option. If the browser is opened, a bookmark will be added to the Browser-Window bookmarks <indexterm><primary>bookmarks</primary></indexterm> menu.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>C</keycap></keycombo></shortcut>
		<guimenu>Bookmarks</guimenu><guimenuitem>Clear Bookmarks</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Clears the bookmark-entries for the top editing window or the browser, e.g., if
the Header-Window is visible and you call <guimenuitem>Clear Bookmarks</guimenuitem>, the entries for the Header-Window are deleted.</action></para>
	    </listitem>
	  </varlistentry>
	  
	  
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Bookmarks</guimenu><guimenuitem>Header-Window</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Contains the bookmark-list for the Header-Window. Selecting a bookmark will set the cursor to the selected bookmarks <indexterm><primary>bookmarks</primary></indexterm>' line. Mind that bookmarks <indexterm><primary>bookmarks</primary></indexterm> are specifically assigned to the file they are set in, so if you change to another file, the bookmarks <indexterm><primary>bookmarks</primary></indexterm> are not deleted, but choosing a bookmark won't automatically change to the file they are assigned to as well.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Bookmarks</guimenu><guimenuitem>C/C++ Window</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Contains the bookmark-list for the C/C++-Window. The preferences are the same as for the Header-Window.</action></para>
	    </listitem>
	  </varlistentry>  
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Bookmarks</guimenu><guimenuitem>Browser Window</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action> Contains the browser bookmarks <indexterm><primary>bookmarks</primary></indexterm>. Selecting a bookmark will open the browser with the selected page.</action></para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect2>
      
      <sect2 id="online-help-online-help">
	<title>Online Help <indexterm><primary>Online Help</primary></indexterm></title>
	
	<para><indexterm><primary>Help-menu</primary></indexterm> The <guimenu>Help</guimenu> menu contains entries for navigating in the Helpbrowser, <indexterm><primary>Helpbrowser</primary></indexterm> as well as most recently used entries for library and online-documentation. Accessing additional online-documentation can be achieved with the <guilabel>DOC</guilabel><indexterm><primary>DOC</primary></indexterm>-tree in the treeview, which is automatically opened (if Autoswitch is enabled) when changing to the Documentation Browser window.</para>
	
	<variablelist>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Alt</keycap><keycap>Left Arrow</keycap></keycombo></shortcut>
		<guimenu>Help</guimenu><guimenuitem>Back</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the page opened before the currently displayed one.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>Alt</keycap><keycap>Right Arrow</keycap></keycombo></shortcut>
		<guimenu>Help</guimenu><guimenuitem>Forward</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the next page of the browser-history, available after a "Back" action.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>F2</keycap></keycombo></shortcut>
		<guimenu>Help</guimenu><guimenuitem>Search Marked Text</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Scans the search-index for text currently marked in the editing windows or the browser-window. After the search, a result page is shown which lets you select the help-page to switch to. After choosing a page, the browser will highlight the found entry for the expression the search was invoked for. With the <keycap>F3</keycap> key the next search result <indexterm><primary>search result</primary></indexterm> on the same page
will be displayed, if more than one hit was reported for the search on one page.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Help</guimenu><guimenuitem>Search for Help on...</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the "Search for Help on..." dialog that lets you search for a specific expression you want help on.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<shortcut><keycombo><keycap>F1</keycap></keycombo></shortcut>
		<guimenu>Help</guimenu><guimenuitem>The User Manual to KDevelop</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the User's Manual to KDevelop index page (this handbook).</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Help</guimenu><guimenuitem>The KDevelop Programming Handbook</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the <ulink url="programming/index.html"><application>KDevelop</application> Programming Handbook</ulink> index page. This handbook contains a complete programming guide to KDE development.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Help</guimenu><guimenuitem>KDE Application Tutorials</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Changes to the index page of the <ulink url="tutorial/index.html">KDE Application Tutorials</ulink> handbook. This handbook explains how to build the Qt tutorial applications and introduces you to KDE programming by developing an example application.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Help</guimenu><guimenuitem>The KDE Library Reference Guide</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Changes to the index page of the <ulink url="kde_libref/index.html">KDE Library Reference Guide</ulink>. This handbook contains detailed information about using the KDE/Qt libraries, separated on topics such as event handling.</action></para>
	    </listitem>
	  </varlistentry>
 	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Help</guimenu><guimenuitem>The KDE 2 Developer´s Guide</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Changes to the index page of the <ulink url="addendum/index.html">KDE 2 Developer´s Guide</ulink>. This Handbook contains information about the most recent KDE development and how to prepare your application to be KDE 2-ready.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Help</guimenu><guimenuitem>C/C++ Reference</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Displays the language reference index page. If the reference is not installed, an error page shows you how to get the reference and how to install it correctly.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Help</guimenu><guimenuitem>Tip of the Day</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the Tip of the Day dialog to inform you about <application>KDevelop</application>'s features.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Help</guimenu><guimenuitem>KDevelop Home page</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action> Opens the <application>KDevelop</application> Home page in the browser window if Internet access is provided.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Help</guimenu><guimenuitem>Bug Report</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the <application>KDevelop</application> Bug Report dialog, where you can send a bug-report directly to the <application>KDevelop</application> Team by email. See <link linkend="Bug-Reporting">Bug Reporting</link></action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Help</guimenu><guimenuitem>Project-API-Doc</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action> Changes to the project's class-documentation index file.<indexterm><primary>KDoc</primary></indexterm><indexterm><primary>API</primary></indexterm></action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Help</guimenu><guimenuitem>Project-User-Manual</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Opens the User manual's index file of your current project. This can be used to review the HTML <indexterm><primary>HTML</primary></indexterm>-output <indexterm><primary>output</primary></indexterm> generated by KSgml2Html <indexterm><primary>KSgml2Html</primary></indexterm></action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <menuchoice>
		<guimenu>Help</guimenu><guimenuitem>About KDevelop</guimenuitem>
	      </menuchoice>
	    </term>
	    <listitem>
	      <para><action>Shows the about box of <application>KDevelop</application> containing the version number, the authors' names and email-addresses, as well as reference to the licensing of <application>KDevelop</application>.</action></para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect2>
      
    </sect1>

    <sect1 id="toolbar-toolbar-items">
      <title>Toolbar <indexterm><primary>Toolbar</primary></indexterm> Items</title>

      <para><application>KDevelop</application> provides quick access to a various set of commands through it's toolbars. These are the standard and the browser toolbar. In dialog editor <indexterm><primary>dialog editor</primary></indexterm> mode, only the standard toolbar is visible. Both can be en-/disabled through the according menu entries in the <guimenu>"View"</guimenu> menu, and can also be dragged out of the main window and placed on each side of the working area.</para>

      <sect2 id="the-standard-toolbar-toolbar">
	<title>The Standard Toolbar <indexterm><primary>Toolbar</primary></indexterm></title>

	<para>The standard toolbar provides quick access to the most recently used functions for file processing and editing, as well as those for  building your application. </para>
	<para>The buttons execute the following commands from left to right: <indexterm><primary>"File"-menu</primary></indexterm><indexterm><primary>"Edit"-menu</primary></indexterm><indexterm><primary>"Project"-menu"</primary></indexterm><indexterm><primary>"Build"-menu</primary></indexterm><indexterm><primary>debugging</primary></indexterm><indexterm><primary>Tree-View</primary></indexterm><indexterm><primary>Output-View</primary></indexterm><indexterm><primary>execute target</primary></indexterm></para>
	<variablelist>	
	  <varlistentry>
	    <term>
	      <guiicon>Open Project</guiicon></term>
	    <listitem><para><action>Shows the open project dialog</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Open File</guiicon></term>
	    <listitem><para><action>Shows the open file dialog and contains a delayed pop-up to fast select the current project header and source files.</action></para>
	  </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Save File</guiicon></term>
	  <listitem>
	    <para><action>Saves the currently opened file to disk</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Print File</guiicon></term>
	    <listitem>
	      <para><action>Opens the printer dialog</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>(Separator)</term>
	    <listitem>
	      <para></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Undo</guiicon></term>
	    <listitem>
	      <para><action>Reverts the last action</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Redo</guiicon></term>
	    <listitem>
	      <para><action>Executes a reverted action again</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Cut</guiicon></term>
	    <listitem>
	      <para><action>Cuts out the current selection</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Copy</guiicon></term>
	    <listitem>
	      <para><action>Copies the current selection to the system clipboard</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Paste</guiicon></term>
	  <listitem>
	    <para><action>Pastes the current clipboard contents to the actual cursor position</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>(Separator)</term>
	    <listitem>
	      <para></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Compile File <indexterm><primary>Compile File</primary></indexterm></guiicon></term>
	    <listitem>
	      <para><action>Compiles the file currently visible in the source file window. In Dialog-editor mode this is  replaced by the <guiicon>Generate Files</guiicon> button.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Make</guiicon></term>
	    <listitem>
	      <para><action>Invokes <command>make</command> on the project</action></para>
	    </listitem>   
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Rebuild All</guiicon></term>
	    <listitem>
	      <para><action>Rebuilds the project</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Debug</guiicon></term>
	    <listitem>
	      <para><action>Opens <application>kdbg</application>; <indexterm><primary>KDbg</primary></indexterm> with the application binary for debugging <indexterm><primary>debugging</primary></indexterm> in the Tools <indexterm><primary>Tools</primary></indexterm> window</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Execute</guiicon</term>
	    <listitem>
	      <para><action>Runs the application target binary</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Stop</guiicon></term>
	    <listitem>
	      <para><action>Cancels the current process</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>(Separator)</term>
	    <listitem>
	      <para></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Dialog-editor</guiicon></term>
	    <listitem>
	      <para><action>Switches to Dialog-editor mode. There, the button is replaced by a Sourcecode editor <indexterm><primary>editor</primary></indexterm> button</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Tree-View</guiicon></term>
	    <listitem>
	      <para><action>En/disables the treeview and works as a toggle button to display the current state</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Output-View</guiicon></term>
	    <listitem>
	      <para><action>En/disables the output <indexterm><primary>output</primary></indexterm> view and works as a toggle button to display the current state</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>(Separator)</term>
	    <listitem>
	      <para></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>What's this..?</guiicon></term>
	    <listitem>
	      <para><action> Help button - changes the cursor to a question arrow and lets you get information about GUI <indexterm><primary>GUI</primary></indexterm> components of <application>KDevelop</application></action></para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect2>
      
      <sect2 id="the-browser-toolbar-toolbar">
	<title>The Browser Toolbar <indexterm><primary>Toolbar</primary></indexterm></title>
	
	<para>The browser <indexterm><primary>browser</primary></indexterm> toolbar is another toolbar that provides a lot of useful commands for browsing files and the documentation <indexterm><primary>documentation</primary></indexterm>.</para>
	<para>The toolbar contains:<indexterm><primary>documentation browser</primary></indexterm><indexterm><primary>Help-menu"</primary></indexterm></para>

	<variablelist>
	  <varlistentry>
	    <term>The Class Combo-box</term>
	    <listitem><para>Lets you select a class of the current project to browse to</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>the Method Combo-box</term>
	    <listitem><para>Lets you select a method of the current class, and browses to the implementation of that method</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>the <guiicon>Class Assistant button</guiicon></term>
	    <listitem><para>On a single click, this will bring you to the declaration of the method currently selected.  Also contains a delayed pop-up menu to access the Classtools, for adding Classes, Methods and Attributes, as well as the browsing commands</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Back</guiicon></term>
	    <listitem><para><action>Browses back in the documentation browser <indexterm><primary>documentation browser</primary></indexterm> history; contains a delayed pop-up to select a certain page of the back history.</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Forward</guiicon></term>
	    <listitem><para><action>Browses forward in the documentation browser <indexterm><primary>documentation browser</primary></indexterm> history; contains a delayed pop-up to select a certain page of the forward history.</action></para>
	  </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Stop</guiicon></term>
<listitem><para><action>Stops the browser from loading a documentation file request</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Reload</guiicon></term>
	    <listitem><para><action>Reloads the currently displayed page</action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Home</guiicon></term>
	    <listitem><para><action>Opens the <application>KDevelop</application> User Manual index page in the browser</action></para>
	  </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Search Marked Text</guiicon></term>
	    <listitem>
	    <para><action>Searches the documentation index for the selected text; works with the browser and the editor <indexterm><primary>editor</primary></indexterm> windows</action></para>
	  </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><guiicon>Search for Help on...</guiicon></term>
	    <listitem><para><action>Opens the "Search for Help on..." dialog, to let you enter a keyword to search for in the documentation</action></para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect2>
    </sect1>

    <sect1 id="keyboard-shortcuts">
      <title>Keyboard Shortcuts</title>

      <para>This section handles the predefined as well as the standard values for configurable keyboard commands used in the <application>KDevelop</application> <abbrev>IDE</abbrev>. You should see section <link linkend="Changing-Keyboard-Shortcuts">Changing Keyboard Shortcuts</link> for a detailed explanation how to change assigned values to commands.</para>

      <sect2 id="shortcuts-for-text-processing">
	<title>Shortcuts for Text Processing</title>

	<para><indexterm><primary>Keyboard Shortcuts</primary></indexterm><indexterm><primary>Shortcuts</primary></indexterm></para>

	<sect3 id="cursor-movements">
	  <title>Cursor Movements</title>

	  <informaltable pgwide="1">
	    <tgroup cols="2">
	      <tbody>
		<row>
		  <entry><para><action>One letter to the left</action></para></entry>
		  <entry><keycombo><keycap>Left Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One letter to the right</action></para></entry>
		  <entry><keycombo><keycap>Right Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One word to the left</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Left Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One word to the right</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Right Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One line upwards</action></para></entry>
		  <entry><keycombo><keycap>Up Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One line downwards</action></para></entry>
		  <entry><keycombo><keycap>Down Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>To beginning of the line</action></para></entry>
		  <entry><keycombo><keycap>Home</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>To end of line</action></para></entry>
		  <entry><keycombo><keycap>End</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One page up</action></para></entry>
		  <entry><keycombo><keycap>Page Up</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One page down</action></para></entry>
		  <entry><keycombo><keycap>Page Down</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>To the beginning of the current file</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Page Up</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>To the end of the current file</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Page Down</keycap></keycombo></entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>
	</sect3>

<sect3 id="text-selections">
<title>Text Selections</title>

	  <informaltable pgwide="1">
	    <tgroup cols="2">
	      <tbody>
		<row>
		  <entry><para><action>One letter to the left</action></para></entry>
		  <entry><keycombo><keycap>Shift</keycap><keycap>Left Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One letter to the right</action></para></entry>
		  <entry><keycombo><keycap>Shift</keycap><keycap>Right Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One word to the left</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>Left Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One word to the right</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>Right Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One line upwards</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Up</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One line downwards</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Down</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>To the beginning of the line</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Home</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One page up</action></para></entry>
		  <entry><keycombo><keycap>Shift</keycap><keycap>Page Up</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One page down</action></para></entry>
		  <entry><keycombo><keycap>Shift</keycap><keycap>Page Down</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>To the beginning of the current file</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>Page Down</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>To the end of the current file</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>Page Up</keycap></keycombo></entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>
	</sect3>

<sect3 id="inserting-and-copying-text-tabulators">
<title>Inserting and Copying Text, Tabulators</title>
<informaltable pgwide="1">
	    <tgroup cols="2">
	      <tbody>
		<row>
		  <entry><para><action>En/Disable insert mode</action></para></entry>
		  <entry><keycombo><keycap>Insert</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Copy selection to the clipboard</action></para></entry>
		  <entry><para><keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> or <keycombo><keycap>Ctrl</keycap><keycap>Insert</keycap></keycombo></para></entry>
		</row>
		<row>
		  <entry><para><action>Insert text from the clipboard</action></para></entry>
<entry><para><keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo> or <keycombo><keycap>Shift</keycap><keycap>Insert</keycap></keycombo></para></entry>
		</row>
		<row>
		  <entry><para><action>Delete current line</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>K</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Insert line after current line</action></para></entry>
		  <entry><para><keycombo><keycap>End</keycap></keycombo> then <keycombo><keycap>Enter</keycap></keycombo></para></entry>
		</row>
		<row>
		  <entry><para><action>Insert line before current line</action></para></entry>
		  <entry><para><keycombo><keycap>Home</keycap></keycombo> then <keycombo><keycap>Enter</keycap></keycombo></para></entry>
		</row>
		<row>
		  <entry><para><action>Undo editing step</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Z</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Redo an undo step</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Y</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Tabulator</action></para></entry>
		  <entry><keycombo><keycap>Tab</keycap></keycombo></entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>
	</sect3>
	<sect3 id="deleting-text">
	  <title>Deleting Text</title>
<informaltable pgwide="1">
	    <tgroup cols="2">
	      <tbody>
		<row>
		  <entry><para><action>Delete letter left of cursor position</action></para></entry>
		  <entry><keycombo><keycap>Backspace</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Delete letter right of cursor position</action></para></entry>
		  <entry><keycombo><keycap>Delete</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Delete selected text</action></para></entry>
		  <entry><para>Select text, then <keycombo><keycap>Backspace</keycap></keycombo></para></entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>
	</sect3>

	<sect3 id="searching-text-within-the-editor-editor">
	  <title>Searching Text within the Editor <indexterm><primary>Editor</primary></indexterm></title>

	  <informaltable pgwide="1">
	    <tgroup cols="2">
	      <tbody>
		<row>
		  <entry><para><action>open "Goto Line..." dialog</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>G</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Open "Find text" dialog</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>F</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Repeat last search</action></para></entry>
		  <entry><keycombo><keycap>F3</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Open Search and Replace dialog</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>R</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Open Search in Files dialog (grep)</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Search marked text with grep</action></para></entry>
		  <entry><keycombo><keycap>Shift</keycap><keycap>F2</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Locate next error</action></para></entry>
		  <entry><keycombo><keycap>F4</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Locate previous error</action></para></entry>
		  <entry><keycombo><keycap>Shift</keycap><keycap>F4</keycap></keycombo></entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>
	</sect3>

	<sect3 id="searching-text-with-the-documentation-browse">
	  <title>Searching Text with the Documentation Browser</title>
	  <informaltable pgwide="1">
	    <tgroup cols="2">
	      <tbody>
		<row>
		  <entry><para><action>search selected editor text in documentation</action></para></entry>
		  <entry><keycombo><keycap>F2</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>search selected browser text in documentation</action></para></entry>
		  <entry><keycombo><keycap>F2</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>display next search hit on the same page</action></para></entry>
		  <entry><keycombo><keycap>F3</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>search selected browser text within project</action></para></entry>
		  <entry><keycombo><keycap>Shift</keycap><keycap>F2</keycap></keycombo></entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>
	</sect3>

<sect3 id="browser-shortcuts">
<title>Browser Shortcuts</title>
<informaltable pgwide="1">
	    <tgroup cols="2">
	      <tbody>
		<row>
		  <entry><para><action>previous page</action></para></entry>
		  <entry><keycombo><keycap>Alt</keycap><keycap>Left Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>next page</action></para></entry>
		  <entry><keycombo><keycap>Alt</keycap><keycap>Right Arrow</keycap></keycombo></entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>
	</sect3>

	<sect3 id="managing-bookmarks-0">
	  <title>Managing Bookmarks</title>
	  
           <informaltable pgwide="1">
	    <tgroup cols="2">
	      <tbody>
		<row>
		  <entry><para><action>Add bookmark</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>A</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Clear bookmark list</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>C</keycap></keycombo></entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>
	</sect3>
      </sect2>

      <sect2 id="shortcuts-for-toolbar-toolbar-symbols">
	<title>Shortcuts for Toolbar <indexterm><primary>Toolbar</primary></indexterm> Symbols</title>

           <informaltable pgwide="1">
	    <tgroup cols="2">
	      <tbody>
		<row>
		  <entry><para><action>Icon <guiicon>"Open File"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>O</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Save File"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Print File"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>P</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Undo</guiicon></action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Z</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Redo"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Y</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Cut"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Copy"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Paste"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Compile File"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>F8</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Make"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>F8</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Execute"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>F9</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Execute with Arguments"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>Alt</keycap><keycap>F9</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Dialog Editor"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>D</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Back"</guiicon></action></para></entry>
		  <entry><para><keycombo><keycap>Alt</keycap><keycap>Left Arrow</keycap></keycombo> if browser is open</para></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Forward"</guiicon></action></para></entry>
		  <entry><para><keycombo><keycap>Alt</keycap><keycap>Right Arrow</keycap></keycombo> if browser is open</para></entry>
		</row>
		<row>
		  <entry><para><action>Icon <guiicon>"Search marked text"</guiicon></action></para></entry>
		  <entry><keycombo><keycap>F2</keycap></keycombo></entry>
		</row>
	    </tbody>
	  </tgroup>
	</informaltable>
      </sect2>

      <sect2 id="window-management">
	<title>Window Management</title>
	
	<para>To switch to a certain window, press <keycombo><keycap>Alt</keycap></keycombo>plus the underlined letter in the window title, e.g. Tools <indexterm><primary>Tools</primary></indexterm> would be <keycombo><keycap>Alt</keycap><keycap>T</keycap></keycombo></para>
      </sect2>

      <sect2 id="shortcuts-to-compilation-processes">
<title>Shortcuts to Compilation Processes</title>

           <informaltable pgwide="1">
	    <tgroup cols="2">
	      <tbody>
		<row>
		  <entry><para><action>Compile current source file</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>F8</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Build current project target</action></para></entry>
		  <entry><keycombo><keycap>F8</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Execute target after Build process </action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>F9</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Execute target with Arguments</action></para></entry>
		  <entry><keycombo><keycap>Alt</keycap><keycap>F9</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>Stop the current process</action></para></entry>
		  <entry><keycombo><keycap>F10</keycap></keycombo></entry>
		</row>
	    </tbody>
	  </tgroup>
	</informaltable>
</sect2>
    </sect1>
  </chapter>

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

    <para>Most of <application>KDevelop</application>'s strength is accumulated in the Help System.  It is also an example of how to extend your own KDE application with a complete set of help functionality.  This is, in part, already realized in the template applications, so KDE/Qt application frameworks<indexterm><primary>application framework</primary></indexterm> generated with the <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> already contain the basic functionality for status-bar help, and for documentation, which needs only to be extended by the programmer.</para>
    <para>This section introduces the usage of the general help provided within the <abbrev>IDE</abbrev>, as well as showing the usage of the Helpbrowser <indexterm><primary>Helpbrowser</primary></indexterm>, which, with some intelligent use, will make it very easy to get the information you need for development.</para>

    <sect1 id="the-whats-this-button-and-quickhelp-quickhel">
      <title>The "What's this ?"-Button and Quickhelp <indexterm><primary>Quickhelp</primary></indexterm></title>

      <para>Looking at <application>KDevelop</application>'s top toolbar, you will see the <guiicon>"What's this?"</guiicon> button on the far right end. After selecting this button, the cursor will change to a pointer with a question mark on the right, the same as the button in the toolbar. You can now select any visible part of the <application>KDevelop</application> user interface and click on it. This will display a help-window giving you a short description of the function the item you clicked gives you, or what it can do for you. Included are the main view, the tree-views and the tool-bars, for which help is provided for very button. </para>
      <para>After another mouse click or a keyboard input, the What's this? help window disappears and your cursor is set to the last active position. Note, if you place the mouse pointer over a button, it becomes raised, and after a short time, you will get a QuickTip window, describing the function the button represents in the menubar; this will disappear when you move the mouse pointer away.</para>
      <para>For user interaction dialogs, Quickhelp <indexterm><primary>Quickhelp</primary></indexterm> provides your help windows with a short description of the selected item for which help was requested. These are accessed by a <mousebutton>right</mousebutton> button mouse click to the item, which pops up a context-menu that allows the selection of "Quick-Help". Selecting this will pop up the help window. This is always useful for dialogs where you can't see the action's purpose for as long, especially if you are not yet familiar with <application>KDevelop</application>. Note that most dialogs offer a Help-button which will show you the detailed context-help for that dialog's options, within the provided online-manual in the help-browser.</para>
    </sect1>

    <sect1 id="the-statusbar-statusbar-help">
      <title>The Statusbar <indexterm><primary>Statusbar</primary></indexterm> Help</title>

      <para>The statusbar of <application>KDevelop</application> offers many functions to inform you about the current activity state, as well as "status messages" offering a short description of commands.</para>

      <sect2 id="statusbar-statusbar-entries">
	<title>Statusbar <indexterm><primary>Statusbar</primary></indexterm> Entries</title>

	<para>The Statusbar <indexterm><primary>Statusbar</primary></indexterm> contains:</para>
	<orderedlist>
	  <listitem>
	      <para> a general message field, most left. This is used for help messages and displays the current activity.</para>
	  </listitem>
	  <listitem><para> the progress-bar, indicating the progress for actions that require a comparatively long time to complete, such as saving files, and the scan-progress of the Class Browser. The progress-bar only appears when such processes are executed.</para>
	  </listitem>
	  <listitem><para> an Insert/Overwrite indicator. It shows the editor <indexterm><primary>editor</primary></indexterm> mode for insert actions by <guilabel>INS</guilabel> for Insert mode and <guilabel>OVR</guilabel> for Overwrite mode. The mode can be changed by the <keycombo><keycap>Insert</keycap></keycombo> key on the keyboard.</para>
	  </listitem>
	  <listitem><para> a line counter, displaying the current line in which the cursor is placed.</para>
	  </listitem>
	  <listitem><para> a column counter, indicating the current column position of the cursor in a line.</para>
	  </listitem>
	</orderedlist>
      </sect2>

      <sect2 id="help-messages">
	<title>Help Messages</title>

	<para>The statusbar informs you about the action of menu entries, if you select a menu within the menu-bar and select an action, without executing it. If you press on a toolbar icon, without releasing the mouse-button, the help message for the button is displayed in the same way as for the menu entries. You can prevent the execution of the selected icon by moving the mouse-pointer away from the icon, still holding the mouse button pressed. When the cursor is off the icon, release the mouse button.</para>
	<para>For actions that are currently executing, <application>KDevelop</application> displays the action. This includes processes running in the background such as saving files, as well as for dialogs. If the process has exited, such as a <application>make</application> invocation, the status-bar display changes back to "Ready" state.</para>
	<para>When using the documentation browser <indexterm><primary>documentation browser</primary></indexterm>, the status-bar displays link urls for as long as the cursor is placed over an <abbrev>URL</abbrev> link in the browser window. In this manner, you can easily find out if the file is a local or a remote file which can only accessed by network connection.</para>
	<para>The caption of the <application>KDevelop</application> Project Editor shows you the currently opened filename in the top window. This would be a HTML <indexterm><primary>HTML</primary></indexterm> file
for the documentation browser, <indexterm><primary>documentation browser</primary></indexterm> or a text file for the editing windows. Further, the Project name is displayed, so you have constant
control where you are and what you're currently working at.</para>
      </sect2>
    </sect1>

    <sect1 id="configuring-the-html-html-browser">
      <title>Configuring the HTML <indexterm><primary>HTML</primary></indexterm> Browser</title>

      <para>The browser included in <application>KDevelop</application> is completely HTML <indexterm><primary>HTML</primary></indexterm>based. You can specify the usual options, such as background and the like. You can set all preferences by the <guimenuitem>"Documentation Browser"</guimenuitem> entry of the <guimenu>"Options"</guimenu> menu. This configuration dialog <indexterm><primary>configuration dialog</primary></indexterm> shows you two tabs; the first for setting the font preferences, the second for color selection.</para>

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

	<para>The first option for the font display is the size. Available are small, medium and large. The best display for normal use is set to small by default. For the font selection you must specify a standard font for normal text as it appears in <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm> documents; the fixed font is the one used for displaying e.g., code within the <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm> file.</para>
      </sect2>

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

	<para>The color preferences dialog allows configuration of background, normal text, URL Link and followed link color. The colored buttons on the right display the current settings and selecting a button will result in opening the "Select Color" dialog. There, you can specify the color either by choosing a System Color, a custom color, selecting the color in the multi-colored window, or by setting the values directly. The center contains a preview for the color selected.</para>

	<para>You may also specify if the browser should underline links, to easier detect them visually, and if you would like to use your own colors always independent of the page's preset ones. <guibutton>"Apply"</guibutton> will execute all changes, while <guibutton>"OK"</guibutton> will apply changes and close the dialog. <guibutton>"Cancel"</guibutton> leaves all settings untouched, and exits the configuration dialog.</para>
      </sect2>
    </sect1>

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

      <para>The documentation browser <indexterm><primary>documentation browser</primary></indexterm> allows quick and easy access to all manuals and documentations that are provided with <application>KDevelop</application> or are generated automatically, including online-documentation for the KDE-libraries, <indexterm><primary>KDE-libraries</primary></indexterm> and your project documentation. Plus, the Documentation Tree in the tree-view lets you customize a special "Others" folder that contains all individually added documentation.</para>

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

	<para>To make use of all features of the Helpbrowser <indexterm><primary>Helpbrowser</primary></indexterm>, you should have <application>KDoc</application> <indexterm><primary>KDoc</primary></indexterm> and <application>glimpse</application> <indexterm><primary>glimpse</primary></indexterm> installed. <application>KDoc</application> <indexterm><primary>KDoc</primary></indexterm> will generate all kind of online class-documentation for the KDE-libraries <indexterm><primary>KDE-libraries</primary></indexterm> during the setup <indexterm><primary>setup</primary></indexterm> process, but can also invoked by option in the <link linkend="General-Configuration">KDevelop Setup</link>.</para>
	<para> For the generation of an <abbrev>API</abbrev> <indexterm><primary>API</primary></indexterm> (Application Programming Interface) Documentation for your project's classes <indexterm><primary>classes</primary></indexterm>, <application>KDoc</application> <indexterm><primary>KDoc</primary></indexterm> is also used and called by the <guimenu>Project</guimenu> menu, entry <guimenuitem>"Make API Doc"</guimenuitem> <indexterm><primary>API</primary></indexterm>Doc". This will process all current header files of the project plus the addition of a cross-reference to the Qt and KDE-libraries <indexterm><primary>KDE-libraries</primary></indexterm> if those are available in the Helpbrowser <indexterm><primary>Helpbrowser</primary></indexterm>.</para>
	<para>For the generation of the project handbooks, you should have <application>KSgml2Html</application> <indexterm><primary>KSgml2Html</primary></indexterm> (provided with the <abbrev>KDE-SDK</abbrev> <indexterm><primary>KDE-SDK</primary></indexterm>) and, as a minimum, <abbrev>SGML</abbrev> <indexterm><primary>SGML</primary></indexterm>tools installed on your system. To extend and change your project's online-documentation, you have to edit the documentation file for your project by selecting it in the <abbrev>RFV</abbrev> <indexterm><primary>RFV</primary></indexterm>. After saving your changes, call <guimenuitem>"Make User-Manual"</guimenuitem> from the <guimenu>Project</guimenu>menu. In case <abbrev>SGML</abbrev> <indexterm><primary>SGML</primary></indexterm>tools detect formatting errors <indexterm><primary>errors</primary></indexterm>, these will be displayed in the output <indexterm><primary>output</primary></indexterm> window, to allow you to find the error line directly.</para>
	<para>The program <application>"glimpse<indexterm><primary>glimpse</primary></indexterm>"</application> is used to create a personal search-index for your documentation automatically. The index is generally built during the installation process, but can also be built with the <link linkend="General-Configuration"><application>KDevelop</application> Setup</link> dialog. For a description of the provided search functions see <link linkend="Using-the-Searchindex">Using the Searchindex</link>.</para>
      </sect2>

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

	<para>The <application>KDevelop</application> <abbrev>IDE</abbrev> comes with two sets of online-documentation, which can be accessed either via the <guimenu>"Help"</guimenu> menu or in the Doc-tree, in the Tree-View, in the <application>KDevelop</application> folder.</para>
	<para> The first book provided is this online-handbook, containing all information you need regarding installation, configuration, available functionality, and introduction to application development.</para>
	<para>The second book is <ulink url="programming/index.html">The <application>KDevelop</application> Programming Handbook</ulink> in it's first edition. The programming handbook covers most questions related to the creation and extension of projects that work with <application>KDevelop</application>. Through tutorials, the user gets an introduction to the rich facilities that applications created with the Qt- and/or KDE-libraries <indexterm><primary>KDE-libraries</primary></indexterm> have to offer, as well as given a guideline for ensuring KDE <indexterm><primary>KDE</primary></indexterm> compliance.  These tutorials cover the same instructions given on the Internet site at <ulink url="http://developer.kde.org">http://developer.kde.org/</ulink>. However, the programming handbook cannot replace any additional documentation available in printed or electronic form about the C++ programming language, nor documentation about the usage of the Qt-library.</para>
	<para>The C/C++-Reference <indexterm><primary>Reference</primary></indexterm> used with <application>KDevelop</application> is currently only available on the <application>KDevelop</application> home-page at <ulink url="http://www.kdevelop.org">http://www.kdevelop.org/</ulink>. In certain Linux distributions the reference may be included, see your distribution installation program index for more information. It can be installed easily by downloading and copying the sourcefile to the main KDE-directory (<envar>$KDEDIR</envar>). There, you must untar it as root with <command>tar zxvf c_c++_reference.tar.gz</command>. The reference will then be copied the documentation directory of <application>KDevelop</application>. To uninstall the reference documentation, you just have to delete the <filename>reference</filename> folder under <filename>($KDEDIR)/share/doc/HTML/default/kdevelop/reference</filename>.</para>
	<para>The Qt/KDE-libraries <indexterm><primary>KDE-libraries</primary></indexterm> documentation folder, allows direct access to the HTML <indexterm><primary>HTML</primary></indexterm>online documentation of your copy of the Qt-library. The path to the library documentation is usually automatically detected by the <application>KDevelop</application> installation program, but can be set manually in the <link linkend="General-Configuration"><application>KDevelop</application> Setup</link> dialog. All available documentation for the KDE-libraries <indexterm><primary>KDE-libraries</primary></indexterm> are listed in order of the library name, so if you would use classes <indexterm><primary>classes</primary></indexterm> of a certain library it is easy to determine the library type to be added to the Linker <indexterm><primary>Linker</primary></indexterm> settings in the project. Note that the whole KDE-Library documentation is only accessible when generated by <application>KDoc</application>, <indexterm><primary>KDoc</primary></indexterm> so this program, included in the <abbrev>KDE-SDK</abbrev> <indexterm><primary>KDE-SDK</primary></indexterm>, has to be installed before the documentation can be generated. As the installation program of <application>KDevelop</application> does this automatically, it should be installed before running the <application>KDevelop</application> Setup. If this is not the case, and the documentation cannot be built, you are able to create it afterwards at any time with the <link linkend="General-Configuration">KDevelop Setup</link> dialog.</para>
	<para>The documentation tree also contains the "Others" folder, which is intended to contain all personally customized documentation as described below. Finally, the Doc-Tree allows access to the <abbrev>API</abbrev> <indexterm><primary>API</primary></indexterm> and the Manual for your current project.</para>
      </sect2>

      <sect2 id="adding-documentation-to-the-helpbrowser-help">
	<title>Adding Documentation to the Helpbrowser <indexterm><primary>Helpbrowser</primary></indexterm></title>
	<para>To customize your Helpbrowser<indexterm><primary>Helpbrowser</primary></indexterm>, open the Tree-View and select the <guilabel>"DOC<indexterm><primary>DOC</primary></indexterm>"</guilabel> Tab. You will see an opened tree containing four folders. The <guilabel>"Others"</guilabel> folder is, by default, empty. On a <mousebutton>right</mousebutton> mouse-button click over this folder, a context menu opens that has an entry <guimenuitem>"Add Entry"</guimenuitem>. Select this to open the Add Entry dialog where you must enter two values: the upper one for the name that will be displayed for the documentation within the Doc-tree, and, below that, a file-entry line. Here, you enter the path and filename to the start page that will be opened by the selection of the entry later. You can enter the path and filename directly, or by selection of the pushbutton on the right to open a file chooser dialog. This allows a quick browsing on your system to the path for your start page. Mind that only <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm> documentation can be selected, so only <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm> files are available to choose. Selecting <guibutton>"OK"</guibutton> will add the entry to the Doc-tree and it is then available directly.</para>
</sect2>

      <sect2 id="using-the-searchindex">
	<title>Using the Searchindex</title>

	<para><application>KDevelop</application> includes a set of functions to help you search information within <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm> documentation. To use these features, your system needs to have the program <application>"glimpse<indexterm><primary>glimpse</primary></indexterm>"</application> installed. <application>Glimpse</application> is a free database generator, which creates the search index <indexterm><primary>search index</primary></indexterm> and executes searches within the documentation. To set up the index, see <link linkend="General-Configuration"><application>KDevelop</application> Setup</link>. The index is also automatically generated during the installation program.</para>
	<para>The search functions are available through several ways which you can choose from:</para>
	<orderedlist>
	  <listitem>
	    <para>in the editor <indexterm><primary>editor</primary></indexterm>, select the text you want to have help on, or place the cursor in the word that you want to look for. Then press the <mousebutton>right</mousebutton> mouse button and select <guimenuitem>look up: "expression"</guimenuitem> This can also be done by selecting <guimenuitem>"Search Marked Text"</guimenuitem> from the <guimenu>Help</guimenu> menu, the shortcut key <keycombo><keycap>F2</keycap></keycombo>or by selecting the <guiicon>Search icon</guiicon> from the toolbar.</para>
	  </listitem>
	  <listitem>
	    <para>in the Documentation browser, select the text you want to look up and press the <mousebutton>right mouse button</mousebutton>, select <guimenuitem>look up:"expression"</guimenuitem> or select <guimenuitem>"Search Marked Text"</guimenuitem> or the <guiicon>search</guiicon> icon as above.</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 from the toolbar, in all cases opening a search dialog where you can enter the expression you want to get information for.</para>
	  </listitem>
	</orderedlist>
	<para>Direct access to specific documentation is given by selecting the according icon in the <guilabel>"DOC<indexterm><primary>DOC</primary></indexterm>"</guilabel> tree-view or through the <guimenu>"Help"</guimenu> menu entries.</para>

	<para>The Helpbrowser <indexterm><primary>Helpbrowser</primary></indexterm> also offers support for grep <indexterm><primary>grep</primary></indexterm> to search for a selection within your current project.  For example,  you have opened the documentation page for the <classname>KTMainWindow</classname> class (KDEUI library,) and you want to know where in your code <classname>KTMainWindow</classname> appears. Mark <classname>KTMainWindow</classname> and either select <guimenuitem>"Grep: KTMainWindow"</guimenuitem> or press <keycombo><keycap>Shift</keycap><keycap>F2</keycap></keycombo>. The "Search in Files" dialog opens with the results from <application>grep</application> <indexterm><primary>grep</primary></indexterm> search directly. Then you can choose a result line, to jump to the according sourcecode.</para>
      </sect2>
    </sect1>
  </chapter>

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

    <para>An important part of the integrated development environment is the editor <indexterm><primary>editor</primary></indexterm>. You will be using it for:</para>
    <itemizedlist>
      <listitem>
	<para>creating, opening, and saving source and project files <indexterm><primary>project files</primary></indexterm></para>
      </listitem>
      <listitem>
	<para>editing source and project files <indexterm><primary>project files</primary></indexterm></para>
      </listitem>
      <listitem>
	<para>writing your <abbrev>SGML</abbrev> <indexterm><primary>SGML</primary></indexterm> documentation</para>
      </listitem>
      <listitem>
	<para>printing <indexterm><primary>printing</primary></indexterm> your project files <indexterm><primary>project files</primary></indexterm></para>
      </listitem>
    </itemizedlist>
    <para>Generally, the editor <indexterm><primary>editor</primary></indexterm> itself won't be much different in comparison to other editors, especially as it is a built-in version of the popular <application>KWrite</application>, also known as the <application>"Extended Editor"</application>. If you're familiar with that, you won't have any problems using it for managing your projects. In addition to normal editors, <application>KDevelop</application> contains a new printing <indexterm><primary>printing</primary></indexterm> system, that is specialized for use with sourcecode, and you can choose which printing <indexterm><primary>printing</primary></indexterm> program you want to use.</para>
    <para>This section gives you more information about how to handle your project's files <indexterm><primary>project files</primary></indexterm>, and to make you more familiar with the editor <indexterm><primary>editor</primary></indexterm>'s functionality. A lot of Unix hard-liners would prefer using <application>Emacs</application> or <application>XEmacs</application> they're fine with that. But <application>Emacs</application> isn't necessary for easy programming, and especially for beginners, to work themselves into powerful editors, which in the end, only allow you to enter your code.</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<indexterm><primary>project files</primary></indexterm>. Note this section doesn't apply to translation files or pixmaps<indexterm><primary>pixmaps</primary></indexterm>. Those are recognized automatically, and the appropriate editing program such as <application>KTranslator</application> <indexterm><primary>KTranslator</primary></indexterm> opens those files for you.</para>
      <para>To give you an easy access to your files, <application>KDevelop</application> contains two easy-to-handle tree-views, similar to a file manager, that recognize if you have selected a file, and open it in the appropriate editor<indexterm><primary>editor</primary></indexterm> window.</para>
      <para> The main view contains two windows that are used independently, but are connected via the Project Editor, so all menu-bar actions operate the same way. The intention behind this is to allows you to handle two windows at the same time, although only one is visible. The C/C++ window has another task, to allow you to easily compile your sources one by one, so you can check the implementations without having to run a complete build process over your project.</para>
      <para>File by file compilation can be done while the C/C++ window is on top. Select <guimenuitem>"Compile File"</guimenuitem><indexterm><primary>Compile File</primary></indexterm> from the <guimenu>Build</guimenu> menu, or press the corresponding button in the toolbar. Your file is saved and compiled, and you can control any errors <indexterm><primary>errors</primary></indexterm> by the Compiler <indexterm><primary>Compiler</primary></indexterm> output <indexterm><primary>output</primary></indexterm> in the output <indexterm><primary>output</primary></indexterm> window.</para>
      <para>Within the <abbrev>IDE</abbrev> you can open as many text files as you like. All currently open files are listed in the <guimenu>Window</guimenu> menu, so you can switch between them by selecting the filename from the menu. Further, the actual opened file is displayed with its name in the window title-bar of <application>KDevelop</application>.</para>

      <sect2 id="creating-and-saving-files">
	<title>Creating and Saving Files</title>

	<para>To create a new file, choose <guimenuitem>"New"</guimenuitem> from the <guimenu>"File"</guimenu> menu. This opens the "New File <indexterm><primary>New File</primary></indexterm>" dialog, where you can specify the filename and it's type. Additionally, you set the destination directory, and if the file is added to the project or not. Finally, you can also select here to use your header template for the project, in case you want to add a new sourcefile without generating a new class through the Class-Generator.</para>
	<para>After the file has been created, you can edit the new file as usual. If you have to switch between different files, you can always turn back to the file either via the file-trees or by the Window-menu.</para>
	<para>For saving any changes, <application>KDevelop</application> offers a whole variety of options. The standard way would be to save the file by selecting <guimenuitem>"Save"</guimenuitem> or <guimenuitem>"Save As"</guimenuitem> from the <guimenu>"File"</guimenu> menu or by the <guimenu>"Save"</guimenu> button on the toolbar. For saving all changed files at once, there is also <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 after you have done a lot of changes on your files; sometimes you will kick yourself that you have forgotten to save the changes. <application>KDevelop</application> takes care of this by offering "Autosaving", which is by default enabled, and set to save all files in intervals of 5 minutes. To select another Autosave period, or to disable this, see <link linkend="KDevelop-Setup">KDevelop Setup</link>, where the setup <indexterm><primary>setup</primary></indexterm> options are described.</para>
	<para><application>KDevelop</application> takes care of all changes if you open another project, or exit <application>KDevelop</application>. You will be asked if you wish to  save the changed files, and you also have the option to specify which one to save,e and which you want to stay unsaved. Further, when invoking any build-processes, your files get saved automatically, so you won't ever wonder why your application doesn't run the way you expected it to do after your changes to the source files. The only exception is the <guimenuitem>"Compile File"</guimenuitem><indexterm><primary>Compile File</primary></indexterm> command, which only saves the currently opened source file visible in the source editor <indexterm><primary>editor</primary></indexterm> window.</para>
      </sect2>

      <sect2 id="opening-and-closing-files">
	<title>Opening and Closing Files</title>
	
	<para>To open a source file, you have a lot of options. One way could be, as is standard for editors, to select <guimenuitem>"Open"</guimenuitem> from the <guimenu>"File"</guimenu> menu. You will be presented an "Open File" dialog, which allows you to choose the file you want to edit. Another, probably more frequently used way, is to select the file from the <guilabel>LFV</guilabel>, <indexterm><primary>LFV</primary></indexterm> the Logical File Viewer, or the <guilabel>RFV</guilabel><indexterm><primary>RFV</primary></indexterm>, the Real File Viewer (see <link linkend="Overview">Overview</link>). The advantage of the file trees is that they provide a quick visual access to your files, especially the <guilabel>LFV</guilabel><indexterm><primary>LFV</primary></indexterm>,which only displays your project files, sorted <indexterm><primary>project files</primary></indexterm> by their type, and collected into folders. You can also configure the <guilabel>LFV</guilabel> <indexterm><primary>LFV</primary></indexterm> to sort your files in another manner by a <mousebutton>right</mousebutton> mouse click on the tree. Select <guimenuitem>"New Group"</guimenuitem> from the pop-up menu, and you can configure a new group. Select <guimenuitem>"Edit Group"</guimenuitem> to install new file filters by specifying the group's file extensions, separated by commas.</para>
	<para>The standard file groups for a project generated by <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> are the Headers, Sources, <abbrev>GNU</abbrev>, and Others. Additionally, after adding a translation file, <application>KDevelop</application> adds a folder "Translations", containing your <filename>*.po</filename> files.</para>
	<para>To close files, select the file to close from the <guimenu>Window</guimenu> menu, which loads the opened file into the front editor <indexterm><primary>editor</primary></indexterm>. Then select <guimenuitem>"Close"</guimenuitem> from the <guimenu>"File"</guimenu> menu. If your file has been changed, 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 about saving as well.</para>
      </sect2>
    </sect1>

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

      <para>The following gives you a general guideline how to locate certain positions within your files for a quicker access.</para>
      <procedure>
	<title> How to find a certain line in a file</title>
	<step><para>Select <guimenuitem>"Goto Line"</guimenuitem> in the <guimenu>"View"</guimenu> menu or press <keycombo><keycap>CTRL</keycap><keycap>G</keycap></keycombo>. The dialog "Goto Line" appears.</para></step>
	<step><para>Insert the linenumber you want to go 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 want to access via a bookmark</para></step>
	<step><para>Select "Set Bookmark" from the "Bookmarks"-menu.</para></step>
	<step><para>A pop-up-menu opens that allows you to select the bookmark number you want to set for the new bookmark.</para></step>
	<step><para>Select the bookmark number.</para></step>
      </procedure>
      <para>Another way to set bookmarks <indexterm><primary>bookmarks</primary></indexterm> would be 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 bookmarks <indexterm><primary>bookmarks</primary></indexterm>-list. The documentation browser <indexterm><primary>documentation browser</primary></indexterm> also offers setting a bookmark to the current page by a context menu entry <guimenuitem>"Add Bookmark"</guimenuitem>.</para>
      <procedure>
	<title>How to delete bookmarks</title>
	<step><para>To delete all bookmarks, select <guimenuitem>"Delete Bookmarks"</guimenuitem> from the <guimenu>"Bookmarks"</guimenu> menu.  This deletes the bookmarks <indexterm><primary>bookmarks</primary></indexterm> for the window actually on top, either the Header window, the C++ window or the browser window.</para></step>
      </procedure>
      <note><para>The bookmarks <indexterm><primary>bookmarks</primary></indexterm> are set for each editing window separately.  Be aware that your bookmarks <indexterm><primary>bookmarks</primary></indexterm> aren't connected to the certain file you set the bookmark for.</para></note>
      <procedure>
	<title>How to go to a bookmarked line</title>
	<step><para>Select the <guimenu>"Bookmarks"</guimenu> menu and open the appropriate popup menu containing the bookmarks <indexterm><primary>bookmarks</primary></indexterm>  you want to view; either the C++-Window or the Header-Window entry.</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 the page.</para>
    </sect1>

<sect1 id="working-with-keyboard-shortcuts">
<title>Working with Keyboard Shortcuts</title>

<para>For using the editor <indexterm><primary>editor</primary></indexterm>, you should make yourself comfortable with some keyboard shortcuts <indexterm><primary>shortcuts</primary></indexterm> that make it easier to position the cursor and edit the file. The complete shortcut reference is also listed in section <link linkend="Overview">Overview</link>.</para>

<informaltable pgwide="1">
	    <tgroup cols="2">
	      <tbody>
		<row>
		  <entry><para><action>One letter to the left</action></para></entry>
		  <entry><keycombo><keycap>Left Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One letter to the right</action></para></entry>
		  <entry><keycombo><keycap>Right Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One word to the left</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Left Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One word to the right</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Right Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One line upwards</action></para></entry>
		  <entry><keycombo><keycap>Up Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One line downwards</action></para></entry>
		  <entry><keycombo><keycap>Down Arrow</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>To beginning of the line</action></para></entry>
		  <entry><keycombo><keycap>Home</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>To end of line</action></para></entry>
		  <entry><keycombo><keycap>End</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One page up</action></para></entry>
		  <entry><keycombo><keycap>Page Up</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>One page down</action></para></entry>
		  <entry><keycombo><keycap>Page Down</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>To the beginning of the current file</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Page Up</keycap></keycombo></entry>
		</row>
		<row>
		  <entry><para><action>To the end of the current file</action></para></entry>
		  <entry><keycombo><keycap>Ctrl</keycap><keycap>Page Down</keycap></keycombo></entry>
		</row>
	      </tbody>
	    </tgroup>
      </informaltable>

    </sect1>

    <sect1 id="edit-windows-settings">
      <title>Edit Windows Settings</title>

      <para>The editor <indexterm><primary>editor</primary></indexterm> inside <application>KDevelop</application> can be configured for special editing needs with a global effect on all editing windows. You can set the color modes, highlighting colors, (also configurable in reference to the programming language of the file,) and automatic text settings like tab-with and selection modes. The following describes how to set these options in the configuration dialogs provided in the <guimenu>"Options"</guimenu> menu.</para>

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

	<para>The editor<indexterm><primary>editor</primary></indexterm>'s general settings can be configured with the <guimenuitem>"Editor"</guimenuitem> entry in the <guimenu>"Options"</guimenu> menu. Select the appropriate values and press <guibutton>"OK"</guibutton> after you have finished your configuration.</para>

	<sect3 id="edit-options">
	  <title>Edit Options</title>

	  <variablelist>
	      <varlistentry>
		<term>Auto Indent:</term>
		<listitem>
		  <para>this sets the editor to place the cursor below the first literal when a new line is entered.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Backspace Indent:</term>
		<listitem>
		  <para>this option sets the cursor below the first literal of the line above when backspace is pressed.</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Word Wrap:</term>
		<listitem>
		  <para>words are taken into the next line after the column set in "Wrap Words At:"</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Replace Tabs:</term>
		<listitem>
		  <para>tabs in the current text are replaced with tabs of the "Tab Width:" value</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Remove Trailing Spaces:</term>
		<listitem>
		  <para>removes trailing spaces</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Wrap Cursor:</term>
		<listitem>
		  <para>sets the cursor to the end of the last line when backspace enters the beginning of a line</para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Auto Brackets:</term>
		<listitem>
		  <para>creates a closing bracket in front of the cursor when a bracket (any kind) is opened.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	</sect3>

	<sect3 id="select-options">
	  <title>Select Options</title>

	  <variablelist>
	    <varlistentry>
	      <term>Persistent Selections:</term>
	      <listitem>
		<para>selections made stay marked after setting the cursor to a different place</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Multiple Selections:</term>
	      <listitem>
		<para>allows multiple independent selections within the text</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Vertical Selections:</term>
	      <listitem>
		<para>allows vertical selections of text</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Delete On Input:</term>
	      <listitem>
		<para>deletes a selection when writing in the selection.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Toggle Old:</term>
	      <listitem>
		<para>allows only one selection. A selection made gets deselected when another selection is made.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Wrap Words At:</term>
	      <listitem>
		<para>sets the maximum columns that a line can have. The word that contains a letter that reaches over this value will be automatically broken into the next line.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</sect3>
      </sect2>

      <sect2 id="colors">
	<title>Colors</title>

	<para>To change the editor<indexterm><primary>editor</primary></indexterm>'s general appearance, you can define a set of colors that the editor uses by selecting <guimenuitem>"Editor Colors"</guimenuitem> from the <guimenu>"Options"</guimenu> menu.</para>
<para>You can configure colors for:</para>

	<variablelist>
	  <varlistentry>
	    <term>background</term>
              <listitem>
		<para>the editor's background</para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>selected</term>
	      <listitem><para>the color of selected text</para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>found</term>
	      <listitem><para>the color of text found by a search via the menu <guimenu>"Edit"</guimenu> - e.g., with <guimenuitem>"Search"</guimenuitem>,<guimenuitem>"Repeat Search"</guimenuitem>, and <guimenuitem>"Replace"</guimenuitem></para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>selected + found</term>
	      <listitem><para>the color of text selected to search for, and then found</para></listitem>
	  </varlistentry>
	</variablelist>
      </sect2>

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

	<para>The syntax-highlighting mode of <application>KDevelop</application>'s editor <indexterm><primary>editor</primary></indexterm> can be configured by two dialogs. </para>
	<para> First you can set default colors for syntax-highlighting by 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 e.g. keywords. Select the default item, and set all needed options.</para>
	<para>The second configuration dialog <indexterm><primary>configuration dialog</primary></indexterm> is accessed by the <guimenuitem>"Syntax-Highlighting"</guimenuitem> entry in the <guimenu>"Options"</guimenu> menu. This allows you to set the file filters for the programming language, e.g. <filename>*.cpp</filename>, and <filename>*.h</filename>  for C++. Then select the item that you want to configure. If you wish to use the default values you've set in the "Editor Defaults" dialog, select the "default" check-boxes in the Item-style and Item-Font sections. This reads the default settings for the selected item. After pressing <guibutton>"OK"</guibutton>, your new values will be enabled and used by the editor <indexterm><primary>editor</primary></indexterm>.</para>
      </sect2>
    </sect1>

    <sect1 id="searching-and-replacing">
      <title>Searching and Replacing</title>

      <sect2 id="single-file-search">
	<title>Single File Search</title>
	<procedure>
	  <title>How to find one or more characters in the current editing window</title>
	  <step><para>Select <guimenuitem>"Search"</guimenuitem> from the <guimenu>"Edit"</guimenu> menu. This opens the search dialog.</para></step>
	  <step><para>Specify the expression to search for in the edit field. The drop-down menu offers selecting a previous search expression.</para></step>
	  <step><para>Select additional options like "Whole Words only", as required</para></step>
	  <step><para>Press <guibutton>"OK"</guibutton>.</para></step>
	</procedure>
	<para>To repeat searching for an expression entered in the search dialog, press <keycombo><keycap>F3</keycap></keycombo>.</para>
      </sect2>

      <sect2 id="searching-over-several-files">
	<title>Searching over Several Files</title>

<para>The search function is limited to referencing the single file that is currently visible, but often you want to search for the same expression all over your project. <application>KDevelop</application> contains a <command>grep<indexterm><primary>grep</primary></indexterm></command> dialog, which lets you search in all files that you specify, either by setting the directory to start the search from, and/or by mime-type. Specifying the exact directory and the mime-type will reduce the time that <application>KDevelop</application> 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.</para>
<para> The search dialog opens and lets you enter:</para>
	<itemizedlist>
	  <listitem>
	    <para>The expression to search for (the pattern)</para>
	  </listitem>
	  <listitem>
	    <para>The template used for the search</para>
	  </listitem>
	  <listitem>
	    <para>The mime-type of files to search in</para>
	  </listitem>
	  <listitem>
	    <para>The directory to start from</para>
	  </listitem>
	  <listitem>
	    <para>If the search is recursive over all included subdirectories</para>
	  </listitem>
	</itemizedlist>
    	<para>By default, the grep <indexterm><primary>grep</primary></indexterm>-dialog is set to start at your project directory, and works recursively over implementation <indexterm><primary>implementation</primary></indexterm> and header files.</para>
	<para>You can even extend your search pattern by using the following options:</para>
	<orderedlist>
	  <listitem>
	    <para><option>.</option> Match any character</para>
	  </listitem>
	  <listitem>
	    <para><option>^</option> Match the beginning of a line</para>
	  </listitem>
	  <listitem>
	    <para><option>$</option> Match the end of a line</para>
	  </listitem>
	  <listitem>
	    <para><option>\&lt; </option> Match the beginning of a word</para>
	  </listitem>
	  <listitem>
	    <para><option>\&gt; </option> Match the end of a word</para>
	  </listitem>
	</orderedlist>
	<para>For a repeating search, you can also use these available operators:</para>
	<orderedlist>
	  <listitem>
	    <para><option>?</option> The preceding item matches less than once</para>
	  </listitem>
	  <listitem>
	    <para><option>*</option> The preceding item is matched zero or more times</para>
	  </listitem>
	  <listitem>
	    <para><option>+</option> The preceding item is matched once or more times</para>
	  </listitem>
	  <listitem>
	    <para><option>{ <replaceable>n</replaceable> }</option> The preceding item is matched exactly <replaceable>n</replaceable> times</para>
	  </listitem>
	  <listitem>
	    <para><option>{ <replaceable>n</replaceable>,}</option> The preceding item is matched <replaceable>n</replaceable> or more times</para>
	  </listitem>
	  <listitem>
	    <para><option>{,<replaceable>n</replaceable> }</option> The preceding item matches less than <replaceable>n</replaceable> times</para>
	  </listitem>
	  <listitem>
	    <para><option>{<replaceable>n</replaceable>,}</option> The preceding item matches at least <replaceable>n</replaceable> times but less than <replaceable>m</replaceable> times</para>
	  </listitem>
	</orderedlist>

	<para>Back-references to bracketed subexpressions are also available by the notation <option>\n</option>.</para>
	<para>After specifying your search parameters, press <guibutton>"Search"</guibutton>. The results are then displayed in the result window. To jump to a file and line number, select the result line and press <keycombo><keycap>Enter</keycap></keycombo> or double click the result. The editor will automatically open the corresponding file and place the cursor to the line of the result.</para>
	<para><application>KDevelop</application> offers more specialized functionality to use <application>grep</application> <indexterm><primary>grep</primary></indexterm> within the editor<indexterm><primary>editor</primary></indexterm>s, and the browser. Select the expression you want to search for in either of the windows, and press <keycombo><keycap>Shift</keycap><keycap>F2</keycap></keycombo> or select <guimenuitem>"grep <indexterm><primary>grep</primary></indexterm>:&lt;your_expression&gt;"</guimenuitem> from the <mousebutton>right button</mousebutton> pop-up menu. This will ask <application>grep</application> <indexterm><primary>grep</primary></indexterm> to search for the selected text in your project directory's files, and will show the results immediately. Switching to the result works as described above. From within the editor window, simply place the cursor over a word and start searching; the word under the cursor will be the search pattern.</para>
      </sect2>

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

	<para>While working on a project, you often need to have information about the parameters of member functions <indexterm><primary>member functions</primary></indexterm> you want to use.  Most often you remember the function name that matches your needs, but the parameters are a very hard thing to keep in mind. <application>KDevelop</application> contains a search functionality that allows searching for  expressions that appear in your files in the documentation browser <indexterm><primary>documentation browser</primary></indexterm>.</para>
	<para> To make use of this search functionality, you must have set up the documentation browser <indexterm><primary>documentation browser</primary></indexterm> correctly and created the search database.</para>
<para>To invoke a search through the documentation, do the following:</para>

	<orderedlist>
	  <listitem>
	    <para>place your cursor at the word you want to search, or mark an expression</para>
	  </listitem>
	  <listitem>
	    <para>select <guimenuitem>"Search Marked Text"</guimenuitem> from the <guimenu>Help</guimenu> menu <indexterm><primary>Help-menu</primary></indexterm> or press the <mousebutton>right mouse</mousebutton> button to open the context menu; then select <guimenuitem>"Look Up: "expression"</guimenuitem>.</para>
	  </listitem>
	  <listitem>
	    <para>after the search result <indexterm><primary>search result</primary></indexterm> page is displayed in the documentation browser <indexterm><primary>documentation browser</primary></indexterm>, select the page that you think could contain the information you need.</para>
	  </listitem>
	  <listitem>
	    <para>the selected documentation page is displayed and your search result <indexterm><primary>search result</primary></indexterm> is marked. To display the next result within the same
documentation page, press <keycombo><keycap>F3</keycap></keycombo>.</para>
	  </listitem>
	</orderedlist>      
	<para>This functionality allows you to easily find the information you need. To aid in using the results, the documentation browser <indexterm><primary>documentation browser</primary></indexterm> allows marking a selection and copying it to the clipboard. Then 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 <link linkend="Using-the-Searchindex">Using the Searchindex</link>.</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. The "Search and Replace" dialog lets you specify the expression to be replaced, as well as the replacement expression. Then press <guibutton>OK</guibutton>. The first expression which is found will be marked, so you can see where the expression is and in which context. Then you can specify in a dialog if the expression should be replaced or not. When the search is finished by reaching the end of the current file, you will be asked if you want to start the search again from the beginning. If you're finished, select <guibutton>"Cancel"</guibutton>.</para>
      </sect2>
    </sect1>

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

      <para>As <application>KDevelop</application> is designed to give developers the 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. Besides this, you can also print by directly using <application>lpr</application> (the line-printer device).</para>
      <para>As using <application>enscript</application> offers the most options for printing, you should install it on your system; it is usually shipped with distributions, so you shouldn't have any problem finding it.</para>
      <para>Before printing, you should have a look at the configuration dialog, to prepare the output according to your needs. The following section describes how to configure <application>KDevelop</application> for printing files.</para>

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

	<para>The printing <indexterm><primary>printing</primary></indexterm> program can be configured by selecting <guimenuitem>"Print"</guimenuitem> from the <guimenu>"File"</guimenu> menu <indexterm><primary>"File"-menu</primary></indexterm>.  In the printing <indexterm><primary>printing</primary></indexterm> dialog, select the preferred program in the drop-down-menu in the left upper corner. Then press the <guibutton>"Options"</guibutton> button on the right. This opens the configuration for the selected program.  Another way to configure the program is selecting <guimenuitem>"Printer Configuration..."</guimenuitem> from the <guimenu>"Options"</guimenu> menu, then select "enscript <indexterm><primary>enscript</primary></indexterm>".</para>

	<sect3 id="the-enscript-enscript-configuration-options">
	  <title>The enscript <indexterm><primary>enscript</primary></indexterm> Configuration Options</title>

	  <sect4 id="header">
	    <title>Header</title>

	    <variablelist>
	      <varlistentry>
		<term>Fancy Header</term>
		<listitem><para><action>Adds a fancy header</action></para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Header Text</term>
		<listitem><para><action>Enables adding a header text</action></para>
		  <variablelist>
		    <varlistentry>
		      <term>Text</term>
		      <listitem><para><action>Sets the text contents</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>Position</term>
		      <listitem><para><action>Sets the text position to left, center, or right</action></para></listitem>
		    </varlistentry>
		  </variablelist>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Login</term>
		<listitem><para><action>Add the User-ID to the header</action></para>
		  <variablelist>
		    <varlistentry>
		      <term>login</term>
		      <listitem><para><action>Enables adding the User-ID</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>position</term>
		      <listitem><para><action>Sets the position for the User-ID to left, center, or right</action></para></listitem>
		    </varlistentry>
		  </variablelist>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Filename</term>
		<listitem><para><action>Add the filename to the header</action></para>
		  <variablelist>
		    <varlistentry>
		      <term>Size of filename</term>
		      <listitem><para><action>Add filename as full (i.e., with full path) or short (i.e., filename only</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>Position</term>
		      <listitem><para><action>Sets the position for the filename</action></para></listitem>
		    </varlistentry>
		  </variablelist>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Hostname</term>
		<listitem><para><action>Add the hostname to the header</action></para>
		  <variablelist>
		    <varlistentry>
		      <term>hostname</term>
		      <listitem><para><action>Enables adding the hostname</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>size of hostname</term>
		      <listitem><para><action>Sets the size  for the hostname</action></para></listitem>
		      </varlistentry>
		      <varlistentry>
		      <term>Position</term>
		      <listitem><para><action>Sets the position for the hostname</action></para></listitem>
		    </varlistentry>
		  </variablelist>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </sect4>

	  <sect4 id="date-time">
	    <title>Date & Time</title>
	    <variablelist>
	      <varlistentry>
		<term>Current Date</term>
		<listitem><para><action>Include the current date</action></para>
		  <variablelist>
		    <varlistentry>
		      <term>current date</term>
		      <listitem><para><action>Enables adding the current date</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>position</term>
		      <listitem><para><action>Sets the position for the date entry</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>format</term>
		      <listitem><para><action>Sets the date format</action></para></listitem>
		    </varlistentry>
		  </variablelist>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Modification Date</term>
		<listitem><para><action>Include the last modification date</action></para>
		  <variablelist>
		    <varlistentry>
		      <term>modification date</term>
		      <listitem><para><action>Enables modification date adding</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>position</term>
		      <listitem><para><action>Sets the position for modification date entry</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>format</term>
		      <listitem><para><action>sets the date format</action></para></listitem>
		    </varlistentry>
		  </variablelist>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Current Time</term>
		<listitem><para><action>Include the current time</action></para>
		  <variablelist>
		    <varlistentry>
		      <term>current time</term>
		      <listitem><para><action>Enables adding the current time</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>AM/PM</term>
		      <listitem><para><action>Use AM/PM or 24 hour format</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>Position</term>
		      <listitem><para><action>Sets the position for the time entry</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>Format</term>
		      <listitem><para><action>Sets the time format</action></para></listitem>
		    </varlistentry>
		  </variablelist>
		</listitem>
	      </varlistentry>
	      <varlistentry>		
		<term>Modification Time</term>
		<listitem><para><action>Include the modificaiton time</action></para>
		  <variablelist>
		    <varlistentry>
		      <term>current time</term>
		      <listitem><para><action>Enables adding the current time</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>AM/PM</term>
		      <listitem><para><action>Use AM/PM or 24 hour format</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>Position</term>
		      <listitem><para><action>Sets the position for the time entry</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>Format</term>
		      <listitem><para><action>Sets the time format</action></para></listitem>
		    </varlistentry>
		  </variablelist>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </sect4>

	  <sect4 id="layout">
	    <title>Layout</title>

	    <variablelist>
	      <varlistentry>
		<term>Numbering &amp; Border</term>
		<listitem><para></para>
		  <variablelist>
		    <varlistentry>
		      <term>numbering lines</term>
		      <listitem><para><action>Adds the line numbers to the printed document</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>borders</term>
		      <listitem><para><action>Adds a border to the printed pages</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>numbering pages</term>
		      <listitem><para><action>Number printed pages</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>align files</term>
		      <listitem><para><action>Appends files, for page numbering</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>lines per page</term>
		      <listitem><para><action>The maximum value for lines per page</action></para></listitem>
		    </varlistentry>
		  </variablelist>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Format and Tab</term>
		<listitem><para></para>
		  <variablelist>
		    <varlistentry>
		      <term>set TAB size</term>
		      <listitem><para><action>Sets the TAB size for interpreting TABs</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>Font for header</term>
		      <listitem><para><action>Sets the font used for the header text</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>Font for body</term>
		      <listitem><para><action>Sets the font for the body text (the file contents)</action></para></listitem>
		    </varlistentry>
		  </variablelist>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Textprinting</term>
		<listitem><para></para>
		  <variablelist>
		    <varlistentry>
		      <term>Cut lines</term>
		      <listitem><para><action>Cuts the lines if too long.  If left unchecked, lines are broken (wrapped)</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>replace non-printing characters by space</term>
		      <listitem><para><action>Replaces characters that the printing charset doesn't support with space characters</action></para></listitem>
		    </varlistentry>
		  </variablelist>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Other Options</term>
		<listitem><para></para>
		  <variablelist>
		    <varlistentry>
		      <term>Table of Contents</term>
		      <listitem><para><action>Adds a table of contents page that contains information about printed files, page numbers, etc.</action></para></listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>Highlight bars</term>
		      <listitem><para></para>
			<variablelist>
			  <varlistentry>
			    <term>highlight bars</term>
			    <listitem><para><action>Highlights rows for printing</action></para></listitem>
			  </varlistentry>
			  <varlistentry>
			    <term>Cycle to change</term>
			    <listitem><para><action>Sets the number of rows to change the highlight style</action></para></listitem>
			  </varlistentry>
			</variablelist>
		      </listitem>
		    </varlistentry>
		    <varlistentry>
		      <term>Wrapped link</term>
		      <listitem><para></para>
			<variablelist>
			  <varlistentry>
			    <term>mark wrapped lines</term>
			    <listitem><para><action>Mark lines that have been broken for printing</action></para></listitem>
			  </varlistentry>
			  <varlistentry>
			    <term>value for wrapped lines</term>
			    <listitem><para><action>The preset value for the newline the line is broken into</action></para></listitem>
			  </varlistentry>
			</variablelist>
		      </listitem>
		    </varlistentry>
		  </variablelist>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </sect4>

	  <sect4 id="underlay">
	    <title>Underlay</title>

	    <variablelist>
	      <varlistentry>
		<term>Text</term>
		<listitem><para><action>Sets the text to underlay</action></para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Position</term>
		<listitem><para><action>Sets the position of the underlay text</action></para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Font</term>
		<listitem><para><action>Set the font used for the underlay</action></para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Angle</term>
		<listitem><para><action>Sets the angle for the underlay text</action></para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Gray scaling</term>
		<listitem><para><action>Sets the gray scaling value for the underlay text</action></para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Style</term>
		<listitem><para><action>Sets the underlay text to be printed as outlined or as filled</action></para></listitem>
	      </varlistentry>
	    </variablelist>
	  </sect4>
	</sect3>
      </sect2>

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

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

	  <variablelist>
	    <varlistentry>
	      <term>Program</term>
	      <listitem><para><action>Sets the printing<indexterm><primary>printing</primary></indexterm> program to be used for printing:<indexterm><primary>printing</primary></indexterm> <application>enscript</application><indexterm><primary>enscript</primary></indexterm> or <application>lpr</application></action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Printer</term>
	      <listitem><para><action>Sets the printer to be used for printing<indexterm><primary>printing</primary></indexterm></action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Output location</term>
	      <listitem><para><action>for printing into a file, select the output<indexterm><primary>output</primary></indexterm> location</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Orientation</term>
	      <listitem><para><action>Sets the orientation for printing</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Copy</term>
	      <listitem><para><action>Sets the number of copies to be made of each page</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Paper Size</term>
	      <listitem><para><action>Sets the paper size to be used</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Output Format</term>
	      <listitem><para><action>When using enscript <indexterm><primary>enscript</primary></indexterm> as printing <indexterm><primary>printing</primary></indexterm> program, you can choose between postscript or html printing <indexterm><primary>printing</primary></indexterm></action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Default Printsettings</term>
	      <listitem><para><action>Sets the default settings to use for printing</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>Outprinting</term>
	      <listitem><para></para>
		<variablelist>
		  <varlistentry>
		    <term>Page Printing</term>
		    <listitem><para><action>Sets on or two pages, per sheet of paper</action></para></listitem>
		  </varlistentry>
		  <varlistentry>
		    <term>Pages</term>
		    <listitem><para><action>Select all, odd, or even (when using <application>enscript</application></action></para></listitem>
		  </varlistentry>
		  <varlistentry>
		    <term>Pretty Print</term>
		    <listitem><para></para>
		      <variablelist>
			<varlistentry>
			  <term>pretty-print</term>
			  <listitem><para><action>Enables pretty-print mode for enscript</action></para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>Color</term>
			  <listitem><para><action>Use color printing</action></para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>Pretty Print Mode</term>
			  <listitem><para><action>Sets the mode, dependent on your file format</action></para></listitem>
			</varlistentry>
		      </variablelist>
		    </listitem>
		  </varlistentry>
		</variablelist>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</sect3>

	<sect3 id="file-selection">
	  <title>File Selection</title>
	  <para>The file selection dialog is accessed through the <guibutton>"Files"</guibutton> button on the printing <indexterm><primary>printing</primary></indexterm> dialog. The file selection allows you to specify which files to print out by certain criteria:</para>
	  <variablelist>
	    <varlistentry>
	      <term>File Selection</term>
	      <listitem>
		<variablelist>
		  <varlistentry>
		    <term>Current</term>
		    <listitem><para><action>The currently opened file, visible in the editing window</action></para></listitem>
		  </varlistentry>
		  <varlistentry>
		    <term>All in project</term>
		    <listitem><para><action>All files included in the project currently open</action></para></listitem>
		  </varlistentry>
		  <varlistentry>
		    <term>Self chosen files</term>
		    <listitem><para><action>Allows you to choose the files to be printed</action></para></listitem>
		  </varlistentry>
		  <varlistentry>
		    <term>all cpp files</term>
		    <listitem><para><action>Prints out all source files of the project</action></para></listitem>
		  </varlistentry>
		  <varlistentry>
		    <term>all headers</term>
		    <listitem><para><action>prints out all the header files of the project</action></para></listitem>
		  </varlistentry>
		  <varlistentry>
		    <term>Changed files</term>
		    <listitem><para><action>Allows specifying the printing of files changed within a certain timespan</action></para>
		      <variablelist>
			<varlistentry>
			  <term>Between</term>
			  <listitem><para><action>Specifies all files changed after:</action></para>
			    <variablelist>
			      <varlistentry>
				<term>Date</term>
				<listitem><para><action>The Date files were changed</action></para></listitem>
			      </varlistentry>
			      <varlistentry>
				<term>Time</term>
				<listitem><para><action>The time the files were changed</action></para></listitem>
			      </varlistentry>
			    </variablelist>
			  </listitem>
			</varlistentry>
			<varlistentry>
			  <term>And</term>
			  <listitem><para><action>specifies all files changed before:</action></para>
			    <variablelist>
			      <varlistentry>
				<term>Date</term>
				<listitem><para><action>The Date files were changed</action></para></listitem>
			      </varlistentry>
			      <varlistentry>
				<term>Time</term>
				<listitem><para><action>The time the files were changed</action></para></listitem>
			      </varlistentry>
			    </variablelist>
			  </listitem>
			</varlistentry>
		      </variablelist>
		    </listitem>
		  </varlistentry>
		  <varlistentry>
		    <term>Self Chosen Files</term>
		    <listitem><para><action>Available only if "self chosen files" is selected (see above)</action></para>
		      <variablelist>
			<varlistentry>
			  <term>Add</term>
			  <listitem><para><action>Press this to add a file selected for printing<indexterm><primary>printing</primary></indexterm> in the lineedit field to the left</action></para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>Delete</term>
			  <listitem><para><action>Deletes a selected file from the printing<indexterm><primary>printing</primary></indexterm> list</action></para></listitem>
			</varlistentry>
			<varlistentry>
			  <term>Clear</term>
			  <listitem><para><action>Clears the printing<indexterm><primary>printing</primary></indexterm> list</action></para></listitem>
			</varlistentry>
		      </variablelist>
		    </listitem>
		  </varlistentry>
		</variablelist>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</sect3>
	
	<sect3 id="print-preview">
	  <title>Print Preview</title>

	  <para>Print Preview is available for you to control what the output <indexterm><primary>output</primary></indexterm> will look like. Therefore, <application>KDevelop</application> uses the program <application>ghostview</application> or <application>kghostview</application>. When the <guibutton>preview</guibutton> button is pressed on either printing <indexterm><primary>printing</primary></indexterm> dialog, you will be presented a templated output <indexterm><primary>output</primary></indexterm> that shows you the effect of the currently set options.</para>
	</sect3>
      </sect2>
    </sect1>
  </chapter>

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

    <sect1 id="projecttypes">
      <title>Project types</title>

      <sect2 id="programs-1">
	<title>Programs</title>
	<para><application>KDevelop</application> creates a projectfile with the <filename>.kdevprj</filename> ending. This file contains all your project information, so be careful not to delete it. It is stored in the project's base directory, and is opened to load the project. The projectfile keeps all information for your files, like the file properties, install path, distribution status, and compiler options <indexterm><primary>compiler options</primary></indexterm> (<envar>CXXFLAGS</envar>). Setting file properties allows you to keep track of where the files should go.</para>
	<para>With <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm>, you can create a new application project according to your choice of application type. For now, <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> generates five kinds of frame applications, as follows:</para>
	<itemizedlist>
	  <listitem><para>a single document interface (<abbrev>SDI</abbrev>) KDE <indexterm><primary>KDE</primary></indexterm> application, including a menubar, a toolbar, and a statusbar. It contains basic control resource management, to allow extending the frame application into a unique KDE <indexterm><primary>KDE</primary></indexterm> application. The application frame also contains statusbar help messages, as seen from commercial products, and just like <application>KDevelop</application> itself.</para>
	    <para> From the programmer's point of view, it is based on three application-specific classes <indexterm><primary>classes</primary></indexterm> leaning on the MVC-concept (Model-View-Controller). Technically, the base classes <indexterm><primary>classes</primary></indexterm> may not be viewed that way, but it's construction is at least created most logical to create applications with a <abbrev>GUI</abbrev><indexterm><primary>GUI</primary></indexterm>.</para>
	  </listitem>
	  <listitem>
	    <para>a KDE <indexterm><primary>KDE</primary></indexterm>based application frame window. This application type offers the most flexibility to those wanting to develop their program from scratch, but can also be used as a basis for developing wizard applications or modules.</para>
	  </listitem>
	  <listitem>
	    <para>a Qt-only based program framework. For those programmers who want to use only the Qt-library <indexterm><primary>Qt-library</primary></indexterm> as the <abbrev>GUI</abbrev> <indexterm><primary>GUI</primary></indexterm> interface, we have tried to offer you a smart framework to support your application development. As Qt programming is fully supported, you should have no problems to create a full-functional application by using Qt only.</para>
	  </listitem>
	  <listitem>
	    <para>a C++ program framework. This application type is intended for those wanting to write a terminal based C++ program. Just remove the "Hello World" line in <function>main()</function> and construct your classes <indexterm><primary>classes</primary></indexterm> the same way with <application>KDevelop</application> as you would for KDE <indexterm><primary>KDE</primary></indexterm> applications.</para>
	  </listitem>
	  <listitem>
	    <para>a C program framework for C programmers. This is also a terminal based application but only uses the C compiler.</para>
	  </listitem>
	</itemizedlist>
	<para>Further, <application>KDevelop</application> allows you to create projects for KDE 2 and Qt 2.x. These projects require installing the required libraries as well as setting the according installation path in the <application>KDevelop</application> Setup dialog, (see <link linkend="General-Configuration">General Configuration</link>) before generating a project, to ensure everything will work automatically. The <application>KDevelop</application> 1.2 Appwizard adds a GNOME-template so that developers wanting to use <application>KDevelop</application> to create GTK+-based applications can do so as well.</para>
	<para>Additionally, <application>KDevelop</application> enables you to work with already existing projects. Those can have any options set by the programmer himself in <filename>configure</filename> and Makefiles. As far as the execution and the build-process is concerned, the current state only allows the same structure as for the other base classes. Create a custom project with the application wizard and add your files to the project to allow scanning by the class-browser.</para>
	<para>To ensure the build process, your custom project has to have all sources in a subdirectory matching the lowercase name of your project.  The execution of the binary is also restricted to this lowercase project name.</para>
	<note><para><application>KDevelop</application> does not write any information into your custom <filename>Makefile</filename> or configuration files. You are responsible for any project behavior and build settings yourself in this case.</para></note>
      </sect2>

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

	<para>A general project-type for creating libraries is not available at the moment. Still, building libraries is not impossible with <application>KDevelop</application>.</para>
	<para>Here are a few guidelines and workarounds:</para>

	<itemizedlist>
	  <listitem>
	    <para>Whenever your project subdirectory gets another subdirectory that contains source files, <application>KDevelop</application> will build a static library of these. That means static libraries are already supported by automatic creation, in order to sort project sourcefiles. Mind that the static library is part of the binary later, and won't be installed.</para>
	  </listitem>
	  <listitem><para>To create a shared library <application>KDevelop</application> offers an easy way to turn a such created static library into a shared library: Open the <guilabel>RFV</guilabel> on the left of <application>KDevelop</application>'s main window, and browse to the created subdirectory. There, use the <mousebutton>right</mousebutton> mouse button over the subdirectory. The pop-up menu offers 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>
	    <para>Use <guimenuitem>"change to shared lib"</guimenuitem> to convert the default generated static library into a shared one. You can reverse your decision later if you decide that using it as a static library will work as well for your project.  Simply repeat the same steps again and select <guimenuitem>"change to static lib"</guimenuitem>.</para>
	  </listitem>
	</itemizedlist>
      </sect2>

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

	<para>For some projects, the facilities of <application>KDevelop</application> in it's current state are not be sufficient. Those are projects that include multiple targets, such as packages containing several applications. As commands like "Execute" require that only one target is built by the developer, multiple target projects are only supported to a point.  You will have to write your own entries to the <filename>Makefile.am<indexterm><primary>Makefile.am</primary></indexterm></filename> files, and create your directories for the additional libraries or binaries to build. Nevertheless, a build-process always invokes your make-program independent from what actually the targets are; so these functions still can be used (with the restriction that the build is invoked from the main project subdirectory).</para>
	<para>Another way to work with multiple target projects,  and to still have access to the binaries themselves, is to create empty projects and move the appropriate subdirectories, in conjunction with the project files, <indexterm><primary>project files</primary></indexterm> back to the directory containing all sources later. Then you could load each target independently by its project file.  This also allows executing and debugging <indexterm><primary>debugging</primary></indexterm> the target on it's own.</para>
	<para>Multiple binaries or libraries within the main project subdirectory are possible by following the rules explained in section<link linkend="Project-Hacking">Project Hacking</link>, and the following guidelines for editing the main project's subdirectory <filename>Makefile.am</filename> (all modifications outside the <application>KDevelop</application> write area):</para>
	<itemizedlist>
	  <listitem>
	    <para>add your target to the <option>bin_PROGRAMS</option> 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 those of the original project binary:</para>
	    <itemizedlist>
	      <listitem>
		<para><option><replaceable>newtarget</replaceable>_METASOURCES</option></para>
	      </listitem>
	      <listitem>
		<para><option><replaceable>newtarget</replaceable>_LD_FLAGS</option></para>
	      </listitem>
	      <listitem>
		<para><option>DISTCLEANFILES</option></para>
	      </listitem>
	      <listitem>
		<para>copy the messages: entry for the original binary and replace <option><replaceable>target</replaceable>_SOURCES</option> with <option><replaceable>newtarget</replaceable>_SOURCES</option>, and <filename>target.pot</filename> with <filename>newtarget.pot</filename></para>
	      </listitem>
	    </itemizedlist>
	  </listitem>
	  <listitem>
	    <para>add the sources for your binary or library the same as the <application>KDevelop</application> write area contains, but outside the write area.</para>
	  </listitem>
	  <listitem>
	    <para>to install static libraries, create the library with <application><application>KDevelop</application>'s</application> auto-creation inside subdirectories. Then modify the <filename>Makefile.am</filename> outside the write area according to the needed settings</para>
	  </listitem>
	</itemizedlist>
      </sect2>
    </sect1>

    <sect1 id="new-project-new-projects">
      <title>New Project<indexterm><primary>New Project</primary></indexterm>s</title>

      <para>The <application>KDevelop</application> Application Wizard allows the creation of different types of projects, constructing a framework for each. All projects use the <abbrev>GNU</abbrev> standard development tools as described in the requirements section of this handbook.</para>

      <para>For KDE <indexterm><primary>KDE</primary></indexterm> 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.  OpenGL(tm) (Mesa3D) support is added.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>KDE 2 Normal</term>
	  <listitem>
	  <para>Creates a KDE-2 application with session management, menubar, toolbar, status-bar, and support for a document-view codeframe 
model.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	  <term>KDE 2 Mini</term>
	  <listitem>
	  <para>KDE 2 Mini: Creates a KDE-2 application with an empty main widget.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	  <term>KDE 2 MDI</term>
	  <listitem><para>KDE 2 <abbrev>MDI</abbrev>: Creates a KDE-2 <abbrev>MDI</abbrev> (Multiple Document Interface) application with menubar, toolbar, statusbar, and support for a document-view codeframe model.</para>
	</listitem>
	</varlistentry>
      </variablelist>
      <para>If you wish to build an application with no dependencies on the KDE-libraries <indexterm><primary>KDE-libraries</primary></indexterm> for end-users, you can choose from four Qt-only types:</para>
      <variablelist>
	<varlistentry>
	  <term>Normal</term>
	  <listitem><para> Creates a Qt-Application with a main window containing a menubar, toolbar and statusbar, and including support for a generic document-view model.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>QT 2.x SDI</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 (<abbrev>SDI</abbrev>) model.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>QT 2.1 MDI</term>
	  <listitem><para>Creates a Qt-2.1 Application with a main window containing a menubar, toolbar and statusbar, and including support for a multiple document interface (<abbrev>MDI</abbrev>) model.</para></listitem>
	</varlistentry>
	<varlistentry>
	  <term>QextMDI</term>
	  <listitem><para>QextMDI: Creates an <abbrev>MDI</abbrev> framework based on the QextMDI library and Qt2.0x. Allows switching between two modes, Toplevel and Childframe. Requires the QextMDI library, see <ulink url="http://www.geocities.com/gigafalk/qextmdi.htm">http://www.geocities.com/gigafalk/qextmdi.htm</ulink> for more information.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <para>Further, the Application Wizard offers a template for creating <application>GNOME</application> compliant applications with the GTK+ C-library, with a ready-to-run main window containing a menubar, toolbar, and statusbar.</para>
      <para>The two C and C++ -Application types offer a framework for creating commandline applications.</para>
      <para>Last but not least, you can create an empty project, <abbrev>e.g.</abbrev>, to work with pre-existing projects.</para>
      <para>The wizard asks for your project name, version, and the location where the project directory will be built. Your Name and Email address are asked for, so they may be inserted header and cpp templates on top of your source files, as well as for entries in the <filename>*.lsm</filename> file.</para>
      <para>For adding revision control to your project, see <link linkend="CVS-Integration">CVS Integration</link>.</para>
    </sect1>

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

      <para><application>KDevelop</application> is by default configured to open the last project loaded when starting. This allows a fast start, but you may want to change that to just start the <abbrev>IDE</abbrev> without any project. To prevent the default behavior, disable the "Load last project" 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. If you have another project currently open, this will be closed. If your currently open project contains files that aren't saved, you are asked to save all changed files. You can select which file to save and which you want to close without saving, or to save all at once.</para>
      <para>You will then  get an "Open Project" dialog, where you can change to the directory containing the project file to be loaded. <application>KDevelop</application> project files <indexterm><primary>project files</primary></indexterm> have the <filename>*.kdevprj</filename> extension, which is also displayed with a project icon. Select the project file and press <guilabel>"Open"</guilabel>. When loading a project, the Class Browser scans all files and builds the initial classtree, so you can start working on the project by using the Class Browser directly.</para>
      <para>Another way to open a project is to select the project file in the <application>KFM</application>, the KDE <indexterm><primary>KDE</primary></indexterm> File Manager. This will start <application>KDevelop</application>,  loading the selected project file. You could also open a project on the commandline, entering <command>kdevelop projectname.kdevprj</command>.</para>
      <para>When closing <application>KDevelop</application>, your project file will be saved automatically, and the <abbrev>IDE</abbrev> detects if you have changed any project files. Then you will be asked to save any changes before exiting. The available options for closing are the same as for closing a project before loading another.</para>
    </sect1>

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

      <para>After you created a new project with the <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm>, the usual next task is to extend the project by editing the already created sources, and adding classes<indexterm><primary>classes</primary></indexterm>, pixmaps<indexterm><primary>pixmaps</primary></indexterm>, pictures, and whatever else your project needs. Editing a project means that you can change the default project after its generation, through menus and dialogs, according to your needs. The next section  describes how you can add existing files and classes <indexterm><primary>classes</primary></indexterm> to your project, as well as creating new files. This is necessary for building your project, but won't help you for the installation process by the end-user. Therefore, section <link linkend="Setting-Project-File-Options">Setting Project File Options</link> describes how to set File Properties, especially for additional files that you want <application>make</application> to install, like documentation or pixmaps <indexterm><primary>pixmaps</primary></indexterm>. Another part in project maintenance is adding translations, for applications that support internationalization, which is described in <link linkend="Adding-Translations">Adding Translations</link>.</para>
      <para><link linkend="Extending-the-Project-Documentation">Extending the Project Documentation</link> covers questions on how to create a good set of documentation for online help, enabling the end-user to help himself in case of trouble, as well as telling the user how to use your product.</para>
      <para>Finally, <link linkend="Project-Hacking">Project Hacking</link> describes how you can work around the <application>KDevelop</application> project management for special cases.</para>

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

	<para>Adding a new file is often used when you think that you should separate your class implementation <indexterm><primary>implementation</primary></indexterm> file into several files. Then you need to create an new file, which will contain the part of the class implementation <indexterm><primary>implementation</primary></indexterm> you want to move. You can do this by choosing <guimenuitem>"New"</guimenuitem> from the <guimenu>"File"</guimenu> menu <indexterm><primary>"File"-menu</primary></indexterm>, opening the "New File <indexterm><primary>New File</primary></indexterm>" dialog.</para>
	<para>This dialog enables you to specify the file-type, name, and the location. When entering the filename, <application>KDevelop</application> automatically enters the extension for you, but you can change the extensions towards your own preferences.You can include the header template for sourcefiles, so you don't have to copy this into your new file yourself. Also, you can decide, if the file is included in the project or not. This doesn't cover the installation destination, which has to be configured later by setting the file preferences.</para>
	<para>After the new file has been created, the project file will be updated as well as the according <filename>Makefile.am<indexterm><primary>Makefile.am</primary></indexterm></filename>.</para>
	<para>To add a complete class to your project, you can construct a new class with the Classgenerator, which is invoked by <guimenuitem>"New Class"</guimenuitem><indexterm><primary>New Class</primary></indexterm> from the <guimenu>"Project"</guimenu> menu.</para>
	<para>If you have an existing project, and you have certain classes <indexterm><primary>classes</primary></indexterm> that you want to re-use in your current project, select <guimenuitem>"Add File(s) to Project..."</guimenuitem> from the <guimenu>"Project"</guimenu> menu <indexterm><primary>"Project"-menu</primary></indexterm>. Select <guilabel>"Add existing files"</guilabel>, which will open a dialog to let you specify which files will be added to the project and the destination directory. Mind that the files will be copied into the specified directory and added to the project. You should call <guimenuitem>"Make"</guimenuitem> after adding sources; then your added files will be included in the build-process. If you want to add e.g., pixmaps<indexterm><primary>pixmaps</primary></indexterm> to be installed by the end-user, you should update the File Properties for the added file, and specify the installation path (see <link linkend="Setting-Project-File-Options">Setting Project File Options</link>.)</para>
	<para>To add a file to the project that is already in the project directory, go to the <guilabel>RFV</guilabel><indexterm><primary>RFV</primary></indexterm>, where all project-included files are displayed by their project status, with a red ! over the file icon. Select the file you want to add to the project (which will have a normal file icon) and press the <mousebutton>right</mousebutton> mouse button to get the popup-menu. Then select <guimenuitem>"Add"</guimenuitem>.</para>
	<para>Files can also be removed from your project. This could be for example, in cases where you don't want to use pre-generated files that are already given by the <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm>. When removing a file, you have the option to remove a file from the project, or to delete it completely. To remove a file from the project, select the file in the <guilabel>LFV</guilabel><indexterm><primary>LFV</primary></indexterm> or the <guilabel>RFV</guilabel><indexterm><primary>RFV</primary></indexterm>, press the <mousebutton>right mouse button</mousebutton> and select <guimenuitem>"remove"</guimenuitem>. To delete a file, select <guimenuitem>"delete physically"</guimenuitem>.</para>
      </sect2>

      <sect2 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>LFV</guilabel> <indexterm><primary>LFV</primary></indexterm> by a <mousebutton>right mouse</mousebutton> click.  It shows the project files in groups, as they are sorted in the <guilabel>LFV</guilabel><indexterm><primary>LFV</primary></indexterm>, and displays the file properties such as file size, file type, and if the file is included in the project, as well as the installation path if the file is going to be installed by the end-user's <command>make install</command> command.  It is important for documentation files, as well as pixmaps<indexterm><primary>pixmaps</primary></indexterm>, to specify the location where the files should go when the
project is built and installed by end users, so you must set up those locations. For standard KDE <indexterm><primary>KDE</primary></indexterm> location macros you should look in your <filename>Makefile.am</filename><indexterm><primary>Makefile.am</primary></indexterm>, where the location macros are specified.</para>
      </sect2>

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

	<para>As KDE <indexterm><primary>KDE</primary></indexterm> allows configuring your desktop and the behavior of your applications, you also have the option to choose the language that your application uses, in online-documentation as well as the application's <abbrev>GUI</abbrev>. For documentation files, this seems a trivial task. You would add a subdirectory labeled by the desired language, e.g. <filename>de</filename> for German, to the <filename>docs</filename> directory of your project and copy the English documentation into that directory.  Next you would generate the documentation, and set all project file options for the installation directories. Then you could start translating the <abbrev>SGML</abbrev> <indexterm><primary>SGML</primary></indexterm> file to your desired language, and regenerate the documentation, then you're done.  Now we will explain how to enable internationalization support for your application, and how to add the languages you want to support.</para>
	<para>First, you must enclose all visible strings in your application, those that appear in bars, or dialogs, with the <function role="macro">i18n <indexterm><primary>i18n</primary></indexterm>()</function> macro.  This macro is a replacement for the function <function>klocale-&gt;translate()</function> of the <classname>KLocale</classname> class and much easier to use. As this macro is declared in the <filename>kapp.h</filename> include file, you have to add <option>&num;include &lt;kapp.h&gt;</option> to the source file, or the class declaration <indexterm><primary>declaration</primary></indexterm> file of the class that makes use of the macro.</para>
	<note><para>Although <function role="macro">i18n<indexterm><primary>i18n</primary></indexterm>()</function> is a macro and therefore you could think about using the original function, this won't work because the strings that are set up for translation have to be read out of the sources, and are stored in the application's translation file (<filename>&lt;YourApp&gt;.pot</filename> in the <filename>/po</filename> subdirectory). This task is handled by the program <application>xgettext</application>, and to do this, you would enter <command>make messages</command> <indexterm><primary>messages</primary></indexterm> in your project directory containing the sources. As <application>xgettext</application> depends on the <function role="macro">i18n <indexterm><primary>i18n</primary></indexterm>()</function> macro, the original function won't do the job.</para></note>
	<para>For translations themselves, you first have to create the message file containing all strings that are used in your sources, with the <function>i18n<indexterm><primary>i18n</primary></indexterm>()</function> macro. This can be done by choosing <guimenuitem>"Make messages <indexterm><primary>messages</primary></indexterm> and merge"</guimenuitem> from the <guimenu>"Build"</guimenu> menu.</para>
	<para>Then you have to add the languages that you want your application to support. To do this, select <guimenuitem>"Add Translation File"</guimenuitem> from the <guimenu>"Project"</guimenu> menu. This opens a language selection dialog. Select the language and press <guibutton>OK</guibutton>. This will build the <acronym>ASCII</acronym> file containing entries for the filename of the string, and the line where the original string is placed. Then you will see a msgid line containing the string to translate, followed by msgstr. The msgstr line is mostly empty, except for the translations already provided by the KDE-libraries <indexterm><primary>KDE-libraries</primary></indexterm>. They are to be filled with the appropriate translations of your language.</para>
	<para>You could think about writing the translations by hand. But the <abbrev>KDE-SDK</abbrev> <indexterm><primary>KDE-SDK</primary></indexterm> offers the use of the program <application>KTranslator</application><indexterm><primary>KTranslator</primary></indexterm>. <application>KTranslator</application> reads the already existing files, from other applications installed on the system, so you can reuse already translated strings to support your language.</para>
	<para>To access <application>KTranslator</application> <indexterm><primary>KTranslator</primary></indexterm>, the easiest way is selecting a <filename>&lt;language&gt;.po</filename> file in the <filename>/po</filename> directory either in the <guilabel>LFV</guilabel><indexterm><primary>LFV</primary></indexterm> or in the <guilabel>RFV</guilabel> <indexterm><primary>RFV</primary></indexterm>. This opens <application>KTranslator</application> <indexterm><primary>KTranslator</primary></indexterm> and lets you do the translation easily. Mind that you have to set up <application>KTranslator</application><indexterm><primary>KTranslator</primary></indexterm>'s properties yourself to include the author name and the language, as well as the destination file. <application>KTranslator</application> <indexterm><primary>KTranslator</primary></indexterm> by default only opens your translation file.</para>
	<para>For all translation files, <command>make<indexterm><primary>make</primary></indexterm></command> uses the program <application>msgfmt</application> to format your message files to use with the binary, but you don't have to take care of that, nor of specifying the destination directory for installing the translation files.  These are all done by <application>KDevelop</application> automatically.</para>
	<para>For more information about internationalization support, see <ulink url="http://www.kde.org">http://www.kde.org/</ulink>; a lot of people are involved in doing translations for you to support their language. You will find a list of email-addresses of the translators you could write to, and who will help you with this. Also read <link linkend="The-Dialog-Editor">The Dialog Editor</link> and <ulink url="programming/index-11.html">The <application>KDevelop</application> Programming Handbook</ulink> where questions about internationalization are covered again.</para>
      </sect2>

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

	<para>All projects created with <application>KDevelop</application> contain a pre-configured documentation set, which already contains standard chapters for installation, project name and version, as well as the author name and email-address. As <application>KDevelop</application> uses <abbrev>SGML</abbrev><indexterm><primary>SGML</primary></indexterm> templates, it's very easy to extend the documentation to a fully descriptive help system. The only thing you have to do is edit the <abbrev>SGML</abbrev> <indexterm><primary>SGML</primary></indexterm> file, at <filename>docs/en/index.sgml</filename>.</para>
	<para> The reference documentation included with your sgml-tools package can be added to the Helpbrowser, <indexterm><primary>Helpbrowser</primary></indexterm> and will allow you direct access to special tags, as well as a short description of how to extend the documentation. <abbrev>SGML</abbrev> <indexterm><primary>SGML</primary></indexterm> has a lot of advantages.</para>
	<para>KDE <indexterm><primary>KDE</primary></indexterm> makes wide use by this documentation type with the additional <application>KSgml2Html</application><indexterm><primary>KSgml2Html</primary></indexterm> tool. This creates the typical KDE <indexterm><primary>KDE</primary></indexterm> style documentation, and makes it look nice. The sgmltools alone are enough to produce an <abbrev>HTML</abbrev> output <indexterm><primary>output</primary></indexterm> that is already included in your application. To create the documents using <application>KSgml2Html</application><indexterm><primary>KSgml2Html</primary></indexterm>, install the tool and run <guimenuitem>"Make User-Manual"</guimenuitem> from the <guimenu>"Build"</guimenu> menu.</para>
	<para> The Documentation Browser allows a direct controlling of the output <indexterm><primary>output</primary></indexterm> by selecting <guimenuitem>"Project User-Manual"</guimenuitem> from the <guimenu>"Help"</guimenu> menu or the corresponding icon in the <guilabel>DOC</guilabel> <indexterm><primary>DOC</primary></indexterm>tree. Then you can browse the documentation online in <application>KDevelop</application> and have a better overview of the output<indexterm><primary>output</primary></indexterm> errors <indexterm><primary>errors</primary></indexterm> that result from missing tags.</para>
	<para>While extending the documentation, you can't avoid that additional files may be produced that have to be included into the project as each <markup>sect</markup> tag creates a new <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm> file. The output <indexterm><primary>output</primary></indexterm> generated by the <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm> is already included in the project, so you don't have to worry about their installation path. What you have to watch out for is any <filename>index-<replaceable>xx</replaceable>.html</filename> file, where <replaceable>xx</replaceable> is higher than 6 (as the first six pages are already included in the project). After generating the documentation, switch to the <guilabel>RFV</guilabel> <indexterm><primary>RFV</primary></indexterm> and browse to your documentation directory. Press the <mousebutton>right</mousebutton> mouse button over the files to add, and select <guimenuitem>"Add"</guimenuitem>.</para>
	<para><application>KSgml2Html</application> <indexterm><primary>KSgml2Html</primary></indexterm> adds the KDE <indexterm><primary>KDE</primary></indexterm> logo to the documentation directory. This file, <filename>logotp3.gif</filename>, has to be added to the project as well. Select the <guimenuitem>"File Properties"</guimenuitem> either from the <guimenu>"Project"</guimenu> menu or in the popup menu in the file-viewers.</para>
	<para> The easiest way to set the installation path is to select a documentation file that is already set up for installation such as <filename>index.html</filename>. You see that <guilabel>Install</guilabel> is checked and the <guilabel>Installdir + filename</guilabel> already contains the destination. Mark the "Installdir" and enter <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> to copy the installation path to the clipboard. Then select the file you want to specify for installation. Enable <guilabel>"Install"</guilabel>, and this will enable the installdir-entry field, already containing the filename. Place the cursor in front of the filename and enter <keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo> to insert the clipboard contents (the installation path copied before.) This is the fastest way to specify the installation path.</para>
	<para> For more options about specifying installation destinations, see <ulink url="programming/index-14.html">The KDevelop Programming Handbook</ulink>.</para>
      </sect2>

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

	<para>When working with a project, you should never edit the project file by hand. This will prevent <application>KDevelop</application> from loading your project correctly under certain circumstances.  It could mean that changes will not result in updating the <filename>Makefile<indexterm><primary>Makefile</primary></indexterm>s</filename>.</para>
	<para>To change any settings for your project, you have to use the given menu entries  For experts that are
not comfortable with certain options for e.g. the Linker, <indexterm><primary>Linker</primary></indexterm> or need additional project configuration, you should work yourself into the <filename>Makefile.am</filename> <indexterm><primary>Makefile.am</primary></indexterm> macros and add all changes in the <filename>Makefile.am<indexterm><primary>Makefile.am</primary></indexterm>'s</filename> after the section separated with the entry "KDevelop write area".</para>
	<para>As the <abbrev>GNU</abbrev>-tools are using the commands at the end of all macro files, you can overwrite <application><application>KDevelop</application>'s</application> settings with this.</para>
	<warning><para>Doing this will prevent using <application>KDevelop</application> for any further changes related to project configuration.</para></warning>
      </sect2>
    </sect1>

    <sect1 id="compiler-and-linker-linker-flags-for-project">
      <title>Compiler and Linker <indexterm><primary>Linker</primary></indexterm> Flags for Projects</title>

      <para>Each new project contains all necessary options for the Compiler <indexterm><primary>Compiler</primary></indexterm> and Linker <indexterm><primary>Linker</primary></indexterm> as well as general settings.</para>
      <para>By default, your project is set to use debugging <indexterm><primary>debugging</primary></indexterm> by the <option>-g</option> flag, and warnings <indexterm><primary>warnings</primary></indexterm> are set to the standard, <option>-Wall</option>. This ensures you can debug your application and detect constructions that may cause program errors<indexterm><primary>errors</primary></indexterm>. For some applications, you would need additional Compiler <indexterm><primary>Compiler</primary></indexterm> or Linker <indexterm><primary>Linker</primary></indexterm> flags, especially if you're using libraries that are not currently included by the Linker <indexterm><primary>Linker</primary></indexterm>. Then you need to update the project by configuring the correct settings with the Project Options dialog. See <link linkend="Build-Settings">Build Settings</link> for more information how and where to set Compiler Options, Warnings and Linker <indexterm><primary>Linker</primary></indexterm> Options.</para>
    </sect1>

    <sect1 id="external-projects">
      <title>External Projects</title>

      <para>Existing projects can be converted to <application>KDevelop</application> projects by selecting <guimenuitem>"New"</guimenuitem> from the <guimenu>"Project"</guimenu> menu.  The dialog creates an empty project file with your project name, version, and type information, as well as your name and email address.  Next copy all your compilation and construction files to the new project directory, and choose <guimenuitem>"Add Files"</guimenuitem> from the <guimenu>"Project"</guimenu> menu.  The files selected will be copied into your project directory and the <filename>Makefile.am<indexterm><primary>Makefile.am</primary></indexterm></filename> files are updated.</para>
      <para>Be sure to change all <filename>Makefile.am</filename> <indexterm><primary>Makefile.am</primary></indexterm> entries existing before the conversion, to the newly created entries placed by <application>KDevelop</application> in the <application>KDevelop</application> area.</para>
      <para>After this procedure, test that your program can still be compiled and installed after the conversion to ensure the project's consistency.</para>
    </sect1>
  </chapter>

  <chapter id="build-settings">
    <title>Build Settings</title>

    <para>The Project Options dialog, accessed by the <guimenu>"Project"</guimenu> menu, lets you specify all needed parameters for your project. These will be used for the <filename>Makefile.am</filename><indexterm><primary>Makefile.am</primary></indexterm> files and the <filename>configure<indexterm><primary>configure</primary></indexterm>.in</filename> script (e.g. version number change, or compiler warnings<indexterm><primary>compiler warnings</primary></indexterm>) and will thereby set the compilation preferences as well. After changing the project options, you should invoke <guimenuitem>"make <indexterm><primary>make</primary></indexterm> clean"</guimenuitem> or <guimenuitem>"rebuild all"</guimenuitem> to compile your project with the new options.</para>
<para>Please note that debugging <indexterm><primary>debugging</primary></indexterm> is only available if the project options are set to create debugging <indexterm><primary>debugging</primary></indexterm> information, and the amount can be set with the debug level (0-3).</para>
<para>If you add functions that belong to a library that is not included in the Linker <indexterm><primary>Linker</primary></indexterm> flags, your program will not link correctly if those are not updated, so keep track of your library linking.</para>
<para>For a release build of your application or for distributing the sourcecode package, you should watch the following standard settings:</para>

    <itemizedlist>
      <listitem>
	<para>disable debugging <indexterm><primary>debugging</primary></indexterm></para>
      </listitem>
      <listitem>
	<para>enable optimization and set optimization level to <option>-02</option></para>
      </listitem>
      <listitem>
	<para>set the compiler warnings <indexterm><primary>compiler warnings</primary></indexterm> to <option>-Wall</option></para>
      </listitem>
      <listitem>
	<para>for each new release, increase the version number and update the <filename>project.lsm</filename> file for version and requirements.</para>
      </listitem>
    </itemizedlist>

    <sect1 id="general-options">
      <title>General Options</title>

      <para>The first page of the Project Options dialog sets the general options for your project. These are project name and number, the handbook sgml file which is used for generating a set of <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm> files that are included in the project, and specific information about the author. The short description field is for additional information that you want to include such as the program's purpose and the like.</para>
    </sect1>

    <sect1 id="compiler-options">
      <title>Compiler Options</title>

      <para>The compiler options <indexterm><primary>compiler options</primary></indexterm> page sets the compiler flags for your target, debugging <indexterm><primary>debugging</primary></indexterm> and additional options as described below.</para>

      <sect2 id="target">
	<title>Target</title>
	
	<para>The target box contains two options that can be set:</para>
	<variablelist>
	  <varlistentry>
	    <term>Target Machine</term>
	    <listitem><para>You have the choice to set the target machine option here, by choosing between your machine (default), and i386v, which is the option if you configure<indexterm><primary>configure</primary></indexterm>d your Compiler <indexterm><primary>Compiler</primary></indexterm> as a cross-compiler for an Intel 386 compatible machine running System V. This option sets the <option>-b</option> flag for the Compiler <indexterm><primary>Compiler</primary></indexterm>. Usually you would leave this to the default.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>Optimize</term>
	    <listitem><para>You can enable optimization for your build process by this option, by setting the <option>-O</option> flag. If not checked, the flag is set to <option>-O0</option>, so no optimization will be used. If you enable optimization by checking this option, you can also specify the optimization level below to a value between 1 and 3.</para>
	      <para>For a release version of your application, enable optimization and set the level to 2.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect2>

      <sect2 id="debugging-1">
	<title>Debugging</title>

	<para>Right of the Target box, you can see the debugging <indexterm><primary>debugging</primary></indexterm>-section. This means that you can set your Compiler <indexterm><primary>Compiler</primary></indexterm> to include information for debuggers within the final binary, so the programmer can follow the execution of the application with the debugger in direct context of the sourcecode.</para>
	<variablelist>
	  <varlistentry>
	    <term>Enable debugging <indexterm><primary>debugging</primary></indexterm></term>
	    <listitem><para>Sets the <option>-g</option> flag; the debugging <indexterm><primary>debugging</primary></indexterm> level specifies the amount of information to be included in the binary. Available are levels 1 to 3 to choose from. Mind that the binary execution will be slower by setting any debugging <indexterm><primary>debugging</primary></indexterm> option, and that the binary size will increase by the debugging <indexterm><primary>debugging</primary></indexterm> level.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>Generate extra information for <application>gprof</application></term>
<listitem><para>Sets the <option>-pg</option> flag, causing the Compiler <indexterm><primary>Compiler</primary></indexterm> to include information for the <application>gprof</application> program that displays caller graphs of your program's function.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>Store temporary intermediate files</term>
	    <listitem><para>Sets the <option>-save-temps</option> flag. This will result in storing the (usually temporary) files produced by the preprocessor and the assembler. A compilation of a sourcefile will therefore produce three output <indexterm><primary>output</primary></indexterm> files: an <filename>*.o</filename> file which is the final output <indexterm><primary>output</primary></indexterm> of the Compiler<indexterm><primary>Compiler</primary></indexterm>, an <filename>*.i</filename> file produced by the preprocessor and an <filename>*.s</filename> file as the output <indexterm><primary>output</primary></indexterm> of the assembler.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	<para>For a release of your project, disable any debugging <indexterm><primary>debugging</primary></indexterm>.</para>
      </sect2>

      <sect2 id="additional-options">
	<title>Additional Options</title>
	
	<para>The text entry field on the bottom is intended for you to manually set any flags for the Compiler <indexterm><primary>Compiler</primary></indexterm> by setting the <envar>CXXFLAGS</envar> environment variable <indexterm><primary>variable</primary></indexterm> in the <filename>Makefile<indexterm><primary>Makefile</primary></indexterm>s</filename>, so that make sets the flags before the build process, and resets them afterwards. For a complete description of all available Compiler <indexterm><primary>Compiler</primary></indexterm> flags you should see your Compiler <indexterm><primary>Compiler</primary></indexterm> documentation; for <application>gcc</application> and <application>egcs</application> this can be done by <command>man gcc</command>. <command>man g++</command> will show you information about the c++ script that is used to lead the Compiler <indexterm><primary>Compiler</primary></indexterm>.</para>
      </sect2>
    </sect1>

    <sect1 id="compiler-warnings">
      <title>Compiler Warnings</title>

      <para>The following gives a description about the Compiler <indexterm><primary>Compiler</primary></indexterm> warning options that can be set on page 3 of the project options dialog. The explanations are taken from the man page for GCC, <application>egcs</application> version 1.1.1. The warnings <indexterm><primary>warnings</primary></indexterm> themselves are diagnostic messages that indicate that constructions may cause errors <indexterm><primary>errors</primary></indexterm>.</para>

      <variablelist>
	<varlistentry>
	  <term><option>-Wall</option></term>
	  <listitem>
	    <para>Standard `<option>-W</option>' options combined.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-W</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 GCC-Info for more information.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wtraditional</option></term>
	  <listitem>
	    <para>Warn about certain constructs that behave differently in traditional and <acronym>ANSI</acronym> C.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wundef</option></term>
	  <listitem>
	    <para>Warn if an undefined identifier is evaluated in an `&num;if' directive.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wshadow</option></term>
	  <listitem>
	    <para>Warn whenever a local variable <indexterm><primary>variable</primary></indexterm> shadows another local variable <indexterm><primary>variable</primary></indexterm>.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wid-clash-LEN</option></term>
	  <listitem>
	    <para>Warn whenever two distinct identifiers match in the first len characters. This may help you prepare a program that will compile with certain obsolete, brain-damaged Compilers <indexterm><primary>Compiler</primary></indexterm>s.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wlarger-then-LEN</option></term>
	  <listitem>
	    <para>Warn whenever an object of larger than LEN bytes is defined.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wpointer-arith</option></term>
	  <listitem>
	    <para>Warn about anything that depends on the «size of» a function type or of void. <abbrev>GNU</abbrev> C assigns these types a size of 1, for convenience in calculations with <literal>void *</literal> pointers and pointers to functions.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wbad-function-cast</option></term>
	  <listitem>
	    <para>Warn whenever 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>-Wcast-equal</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 const <literal>char *</literal> is cast to an ordinary <literal>char *</literal>.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wcast-align</option></term>
	  <listitem>
	    <para>Warn whenever a pointer is cast such that the required alignment of the target is increased. For example, warn if a <literal>char *</literal> is cast to an <literal>int *</literal> on machines where integers can only be accessed at two- or four-byte boundaries.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wwrite-strings</option></term>
	  <listitem>
	    <para>Give string constants the type <constant>const char[length]</constant> so that copying the address of one into a non-const <literal>char * pointer</literal> will get a warning. These warnings <indexterm><primary>warnings</primary></indexterm> will help you find at compile time code that can try to write into a string constant, but only if you have been very careful about using const in declaration <indexterm><primary>declaration</primary></indexterm>s and prototypes. Otherwise, it will just be a nuisance; this is why we did not make <option>`-Wall'</option> request these warnings <indexterm><primary>warnings</primary></indexterm>.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wconversion</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>-Wsign-compare</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>-Waggregate-return</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>-Wmissing-prototypes</option></term>
	  <listitem>
	    <para>Warn if a global function is defined without a previous prototype declaration <indexterm><primary>declaration</primary></indexterm>. 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>-Wmissing-declaration</option><indexterm><primary>declaration</primary></indexterm>s</term>
	  <listitem>
	    <para>Warn if a global function is defined without a previous declaration <indexterm><primary>declaration</primary></indexterm>. 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>-Wredundant-decls</option></term>
	  <listitem><para>Warn if anything is declared more than once in the same scope, even in cases where multiple declaration <indexterm><primary>declaration</primary></indexterm> is valid and changes nothing.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wredundant-decls</option></term>
	  <listitem>
	    <para>Warn if anything is declared more than once in the same scope, even in cases where multiple declaration <indexterm><primary>declaration</primary></indexterm> is valid and changes nothing.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wnested-externs</option></term>
	  <listitem>
	    <para>Warn if an extern declaration <indexterm><primary>declaration</primary></indexterm> is encountered within an function.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Winline</option></term>
	  <listitem>
	    <para>Warn if a function can not be inlined, and either it was declared as inline, or else the -fin*line-functions option was given.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wold-style-cast</option></term>
	  <listitem>
	    <para>Warn if an old-style (C-style) cast is used within a program</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Woverloaded-virtual</option></term>
	  <listitem>
	    <para>(C++ only.) In a derived class, the definitions of virtual functions must match the type signature of a virtual function declared in the base class. Use this option to request warnings <indexterm><primary>warnings</primary></indexterm> when a derived class declares a function that may be an erroneous attempt to define a virtual function: that is, warn when a function with the same name as a virtual function in the base class, but with a type signature that doesn't match any virtual functions from the base class.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Wsynth</option></term>
	  <listitem>
	    <para>Warn when g++'s synthesis behavior does not match that of cfront.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><option>-Werror</option></term>
	  <listitem>
	    <para>Make all warnings <indexterm><primary>warnings</primary></indexterm> into errors<indexterm><primary>errors</primary></indexterm>. Treat warnings <indexterm><primary>warnings</primary></indexterm> as errors <indexterm><primary>errors</primary></indexterm>; 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>Linker <indexterm><primary>Linker</primary></indexterm> Options</title>

      <para><indexterm><primary>linker options</primary></indexterm>The Linker <indexterm><primary>Linker</primary></indexterm> Options for your current project can be set on the last page of the project options dialog. You have to enable those libraries that your application uses, to link them to your binary with the Linker <indexterm><primary>Linker</primary></indexterm>, <abbrev>e.g.</abbrev> your application uses the class
<indexterm><primary><literal>KFileDialog</literal></primary></indexterm><classname>KFileDialog</classname>. As the class <indexterm><primary><literal>KFileDialog</literal></primary></indexterm><classname>KFileDialog</classname> is part of the KFile library, you have to enable kfile. For classes <indexterm><primary>classes</primary></indexterm> or functions that are not listed as checkboxes, use the <guilabel>"additional libraries"</guilabel> field.</para>

      <sect2 id="linker-linker-flags">
	<title>Linker <indexterm><primary>Linker</primary></indexterm> Flags</title>

	<para><indexterm><primary>linker flags</primary></indexterm></para>
	<variablelist>
	  <varlistentry>
	    <term>remove all symbol table and relocation information from the executable:</term>
	    <listitem>
	      <para>This means that all redundant information will be removed from the object files and the binary, and that debugging <indexterm><primary>debugging</primary></indexterm> will not be possible. For as long as your application is in a development stage, and not released as final, you should leave this option disabled.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>prevent using shared libraries:</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>additional flags:</term>
	    <listitem>
	      <para>Here, you can enter additional flags for the Linker <indexterm><primary>Linker</primary></indexterm>, setting the <envar>LDFLAGS</envar> environment variable <indexterm><primary>variable</primary></indexterm> used by <application>make<indexterm><primary>make</primary></indexterm></application>. The available options can be taken from the man page for <command>ld</command> or your Compiler <indexterm><primary>Compiler</primary></indexterm> man page.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect2>

      <sect2 id="libraries-0">
	<title>Libraries</title>
	
	<para>The libraries section contains checkboxes for the most needed libraries in conjuction with Qt/KDE <indexterm><primary>KDE</primary></indexterm> application development. You have to enable those libraries that your application uses, otherwise the Linker <indexterm><primary>Linker</primary></indexterm> will complain about unresolved symbol tables.</para>
	<variablelist>
	    <varlistentry>
	    <term><indexterm><primary>X11</primary></indexterm>X11</term>
	    <listitem>
	      <para>The X11 library. Recommended for all X-Window programs.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><indexterm><primary><literal>Xext</literal></primary></indexterm>Xext</term>
	    <listitem>
	      <para>The X11 extension library. Also most X-Window programs depend on Xext.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><indexterm><primary><literal>qt</literal></primary></indexterm>qt</term>
	    <listitem>
	      <para>The Qt-library <indexterm><primary>Qt-library</primary></indexterm>. Recommended for Qt and KDE <indexterm><primary>KDE</primary></indexterm> applications.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><indexterm><primary><literal>kdecore</literal></primary></indexterm>kdecore</term>
	    <listitem>
	      <para>The KDE Core library; contains the classes <indexterm><primary>classes</primary></indexterm> for KDE Application frameworks.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><indexterm><primary><literal>kdeui</literal></primary></indexterm>kdeui</term>
	    <listitem>
	      <para>The KDE User Interface library; contains KDE-specific widgets <indexterm><primary>widgets</primary></indexterm>.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><indexterm><primary><literal>khtmlw</literal></primary></indexterm>khtmlw</term>
	    <listitem>
	      <para>The KHTML Widget library.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><indexterm><primary><literal>kfm</literal></primary></indexterm>kfm</term>
	    <listitem>
	      <para>The KFM library containing classes <indexterm><primary>classes</primary></indexterm> for KFM functions.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><indexterm><primary><literal>kfile</literal></primary></indexterm>kfile</term>
	    <listitem>
	      <para>The KFile library. Contains file dialogs etc.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><indexterm><primary><literal>kspell</literal></primary></indexterm>kspell</term>
	    <listitem>
	      <para>The KSpell library. Contains an interface for programs to use <application>Ispell</application> for spell-checking.</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><indexterm><primary><literal>kab</literal></primary></indexterm>kab</term>
	    <listitem>
	      <para>The KAdressBook library. Needed for access to the addressbook as well as providing addressbook widgets <indexterm><primary>widgets</primary></indexterm></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>additional libraries:</term>
	    <listitem><para> Here you can enter additional libraries that your application needs, e.g. the KOM library. Set the libraries with the <option>-l</option> option; for the example <option>-lkom</option>.</para></listitem>
	  </varlistentry>
	</variablelist>
      </sect2>
    </sect1>

    <sect1 id="make-options">
      <title>Make <indexterm><primary>Make</primary></indexterm> Options</title>

      <para>As <abbrev>GNU</abbrev> <application>make</application> <indexterm><primary>make</primary></indexterm> supports some useful options, the Project Options dialog contains a page called <guilabel>"Make-Options"</guilabel>, where those can be en/disabled.</para> 
      <para>The available settings are:</para>

      <variablelist>
	<varlistentry>
	  <term>Print debug information</term>
	  <listitem>
	    <para>prints out all information about the project files <indexterm><primary>project files</primary></indexterm> and what <application>make</application><indexterm><primary>make</primary></indexterm> determines for rebuilding them.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Continue after errors <indexterm><primary>errors</primary></indexterm></term>
	  <listitem>
	    <para>tries to continue with the compilation after an error occurred (e.g. a file couldn't be compiled due to an error)</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Print the data base</term>
	  <listitem>
	    <para>prints out the make<indexterm><primary>make</primary></indexterm> database for the current process, which contains the changes from the last build-run. </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Environment variables</term>
	  <listitem>
	    <para>give the current environment variables a higher priority than the currently used variables in the <filename>Makefile<indexterm><primary>Makefile</primary></indexterm></filename>.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>No built-in rules</term>
	  <listitem>
	    <para>doesn't use built-in rules for <application>make</application> <indexterm><primary>make</primary></indexterm>.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Touch files</term>
	  <listitem>
	    <para>don't run the Compiler <indexterm><primary>Compiler</primary></indexterm> on changed files; instead only touches them. This sets them as already processed by <application>make</application> <indexterm><primary>make</primary></indexterm>.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Ignore all errors <indexterm><primary>errors</primary></indexterm></term>
	  <listitem>
	    <para>Ignores all errors <indexterm><primary>errors</primary></indexterm> that occur</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Silent operation</term>
	  <listitem>
	    <para>doesn't print out any information about the build-process</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Print working directory</term>
	  <listitem>
	    <para>prints the current directory during the make <indexterm><primary>make</primary></indexterm> process.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>job number</term>
	  <listitem>
	    <para>sets the amount of parallel processes for <application>make</application> <indexterm><primary>make</primary></indexterm>. For a single-CPU system we recommend setting this to one or two.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>set modified</term>
	  <listitem>
	    <para>sets the selected file modified. Choose the file by clicking the folder button on the right. Setting a file modified means that the file will be processed by <application>make</application> <indexterm><primary>make</primary></indexterm> and compiled if it is a source file.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>additional options</term>
	  <listitem>
	    <para>set additional options to <application>make</application> <indexterm><primary>make</primary></indexterm>; those can be found in your local man page for "<abbrev>GNU</abbrev> <application>Make</application>".</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Rebuild behavior on run</term>
	  <listitem>
	    <para>Sets the actions taken when you choose run. There are three options you can choose from:</para>
	    <variablelist>
	      <varlistentry>
		<term>Always rebuild</term>
		<listitem><para>Always rebuild, without checking for modified files</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Warning on modification</term>
		<listitem><para>Warn if source files have been modified, and ask if the project should be rebuilt</para></listitem>
	      </varlistentry>
	      <varlistentry>
		<term>Only on modification</term>
		<listitem><para>Check if sources have changed, and rebuild if they have</para></listitem>
	      </varlistentry>
	    </variablelist><para>The default is to rebuild always.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect1>
  </chapter>

  <chapter id="the-class-browser-0">
    <title>The Class Browser</title>

    <sect1 id="the-classviewer">
      <title>The Classviewer</title>

      <para><indexterm><primary>classbrowser</primary></indexterm>The <application>KDevelop</application> Classviewer is one of the most useful and important tools that the <abbrev>IDE</abbrev> provides a developer for managing his project sources. When a project is loaded, a class parser reads all project sources for functions, classes<indexterm><primary>classes</primary></indexterm> <abbrev>etc.</abbrev>, then displays the results in the <guilabel>CV<indexterm><primary>CV</primary></indexterm></guilabel> treeview. This chapter shows you how to use the Classviewer and the provided functionality, and how it can improve your work.</para>

<para>Classes and their methods can also be accessed by the browser toolbar. There, the left combobox selects the class and the right lets you choose the methods of the selected class. When you select a method, the classbrowser will automatically bring you to the implementation <indexterm><primary>implementation</primary></indexterm> file, and sets the cursor to the method. Finally, the <guiicon>class-assistant</guiicon> button on the right of the method combo, will bring you to the declaration <indexterm><primary>declaration</primary></indexterm> of the method on one click and on a second click to the definition. The delayed popup menu, displayed by the down-arrow on the button, offers additional functionality that is also available in the classviewer's context menus, such as:</para>

      <variablelist>
	<varlistentry>
	  <term><guimenuitem>Goto Declaration</guimenuitem></term>
	  <listitem>
	    <para>browses to the declaration <indexterm><primary>declaration</primary></indexterm> of the method</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Goto Definition</term>
	  <listitem><para>browses to the definition of the method</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Goto Class Declaration</term>
	  <listitem><para>Goto Class Declaration: browses to the class declaration <indexterm><primary>declaration</primary></indexterm></para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>New Class <indexterm><primary>New Class</primary></indexterm></term>
	  <listitem><para>Opens the New Class <indexterm><primary>New Class</primary></indexterm> dialog to construct a new class</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Add Method</term>
	  <listitem><para>Adds a method to the selected class</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Add Attribute</term>
	  <listitem><para>Adds an attribute to the selected class</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Show graphical classview</term>
	  <listitem><para>Show graphical classview: Opens the graphical inheritance tree</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <sect2 id="available-objects">
	<title>Available Objects</title>
	
	<para>C++ code can be seen as a collection of objects: classes<indexterm><primary>classes</primary></indexterm>, their members, global functions, and more. The classtree displays these objects logically, and orders them by character, so they are easy to locate in the tree, as well by their icon.</para>
	<para> The classtree contains a <guilabel>"Classes"</guilabel> and a <guilabel>"Globals"</guilabel> folder.</para>
	<para>The "Classes" folder generally contains the project's classes <indexterm><primary>classes</primary></indexterm>. If your project contains subfolders to manage your sourcefiles, these are also displayed by their original folder name and contain all classes <indexterm><primary>classes</primary></indexterm> that are stored in the files located in the subfolder.</para>
	<para>When popping up a class, the classtree displays the class contents by separating methods and attributes<indexterm><primary>attributes</primary></indexterm>. As these can have attributes <indexterm><primary>attributes</primary></indexterm>such as public, private, and protected, these are displayed by modified icons. You will see that a class displayed in the Class Browser contains all the objects that are present in the class declaration <indexterm><primary>declaration</primary></indexterm>.</para>
	<para>Classes <indexterm><primary>classes</primary></indexterm> are a very common thing when programming in C++ and will contain most of the code. But applications also contain objects that have a "Global" appearance to the program. These would be structs, functions etc. Especially the <function>main()</function> function, which  appears in every application, and you sometimes need to modify it in one or another.</para>
<para>To access these objects, the Classviewer provides the <guilabel>"Globals"</guilabel> folder, containing sub-folders 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 is easy to guess, and to remember.</para>
	<para>Finally, it can be said that the classviewer <indexterm><primary>classviewer</primary></indexterm> displays your project graphically by their objects, related to their appearance in the code.</para>
	<para> In the following section you will learn how to use the classviewer <indexterm><primary>classviewer</primary></indexterm> and it's tools, in conjunction with your code.</para>
      </sect2>

      <sect2 id="browsing-object-declarations-and-implementat">
	<title>Browsing Object Declarations and Implementations</title>

	<para>The Classviewer's strength is providing a fast and easy access to his code and the code's contents, independent of the location within files. Selections by a mouse click will result in the following actions:</para>
<variablelist>
	  <varlistentry>
	    <term>On a classname</term>
	    <listitem><para><action>Switches to the class declaration<indexterm><primary>declaration</primary></indexterm></action></para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>On a class method</term>
	    <listitem><para><action>Switches to the method implementation<indexterm><primary>implementation</primary></indexterm></action></para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>On a class attribute</term>
	    <listitem><para><action>Switches to the attribute's declaration <indexterm><primary>declaration</primary></indexterm> in the class declaration <indexterm><primary>declaration</primary></indexterm></action></para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>On a struct</term>
	    <listitem><para><action> Switches to the struct's declaration <indexterm><primary>declaration</primary></indexterm></action></para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>On a global function</term>
	<listitem><para><action>Switches to the function's implementation <indexterm><primary>implementation</primary></indexterm></action></para></listitem>
	    </varlistentry>
	</variablelist>
	<para>This provides you the most direct access to code objects.</para>
	<para>Sometimes, it may be needed to change a method's header, with the result that you have to change it's declaration <indexterm><primary>declaration</primary></indexterm> in the class, as well as the implementation<indexterm><primary>implementation</primary></indexterm>. The classviewer <indexterm><primary>classviewer</primary></indexterm> supports this by providing <mousebutton>right</mousebutton> button context menus over items.</para>
	<para>On a method or function, this means that you can select where to go:</para>
	<variablelist>
	  <varlistentry>
	    <term>Go to definition</term>
	    <listitem><para><action>Switches to the implementation <indexterm><primary>implementation</primary></indexterm>- this is the default for a <mousebutton>left</mousebutton> click as described above</action></para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>Go to declaration</term>
	    <listitem><para><action>Switches to the declaration <indexterm><primary>declaration</primary></indexterm> of the method or function.</action></para></listitem>
	    </varlistentry>
	</variablelist>
	<para>By this behavior, the Class Browser offers you access to every place you need to go for coding your C++ application.</para>
	<para>The following sections give you a description of the other tools that the Class Browser offers.  You will find them very useful when working with large projects, as they enhance working object-oriented on C++ programs.</para>
      </sect2>
    </sect1>

    <sect1 id="the-classtools">
      <title>The Classtools</title>

      <para><indexterm><primary>classtools</primary></indexterm>The classtools are dialogs that makes it even easier for the developer to get more information about his project's classes<indexterm><primary>classes</primary></indexterm>.</para>
      <para>The classviewer <indexterm><primary>classviewer</primary></indexterm> displays all objects by their occurrence in the code, but you sometimes want to get more information about classes <indexterm><primary>classes</primary></indexterm> without having to look inside the code. Therefore, the classtool dialogs are specialized on displaying specific class attributes<indexterm><primary>attributes</primary></indexterm>.</para>
      <para>The classtool dialog is invoked by the popup menu over a class in the classviewer <indexterm><primary>classviewer</primary></indexterm>. Select <guimenuitem>"Classtool"</guimenuitem>, and the dialog will appear.  To get information about a class, select the class in the combo box on top. Then the buttons in the toolbar provide functions that give you specific trees for your class. These are:</para>

      <variablelist>
	<varlistentry>
	  <term> Parents:</term>
	  <listitem>
	    <para>The parents of the selected class, which means the class it inherits. This is useful for multiple inheritance, as well as to see why a class behaves in one or the other way.  For example, for a dialog, your parent class could be <classname><indexterm><primary>QWidget</primary></indexterm>QWidget</classname> or <classname><indexterm><primary><literal>QDialog</literal></primary></indexterm>QDialog</classname>.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Children:</term>
	  <listitem>
	    <para><action>Displays the child classes <indexterm><primary>classes</primary></indexterm> that inherit the current class.</action></para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Clients:</term>
	  <listitem>
	    <para><action>Classes that make use of the selected class through an attribute in their class declaration <indexterm><primary>declaration</primary></indexterm></action></para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Suppliers:</term>
	  <listitem>
	    <para><action>The suppliers that give attributes <indexterm><primary>attributes</primary></indexterm> to the selected class.</action></para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Attributes:</term>
	  <listitem>
	    <para><action>The attributes <indexterm><primary>attributes</primary></indexterm> of the class by their name</action></para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Methods:</term>
	  <listitem>
	    <para><action>The Methods of the selected class</action></para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <para>Further, the selection of the attribute public, protected, private, or all, shows Attributes, Methods and Virtual Methods by their attribute value.</para>
    </sect1>

    <sect1 id="managing-classes">
      <title>Managing Classes</title>

      <para>The Class Browser also allows adding methods and attributes <indexterm><primary>attributes</primary></indexterm> directly by dialogs. This means you don't have to type the classdeclaration <indexterm><primary>classdeclaration</primary></indexterm> and the implementation <indexterm><primary>implementation</primary></indexterm> header yourself. After adding a method, you only have to set the formal parameters to the implementation <indexterm><primary>implementation</primary></indexterm> header, and, if the method requires an attribute, to the declaration<indexterm><primary>declaration</primary></indexterm>.</para>
      <procedure>
	<title>How to add a method to a class</title>
	<step><para>select the class you want to add a method</para></step>
	<step><para>press the <mousebutton>right</mousebutton> mouse button; the popup menu appears</para></step>
	<step><para>select <guimenuitem>"Add member function"</guimenuitem>.</para></step>
	<step><para>the "Add member function" dialog appears.</para></step>
	<step><para>insert the type, declaration <indexterm><primary>declaration</primary></indexterm> and documentation for the method</para></step>
	<step><para>specify the access and the modifiers for the method</para></step>
	<step><para>press <guibutton>OK</guibutton> to exit the dialog</para></step>
      </procedure>
      <para>To add a variable <indexterm><primary>variable</primary></indexterm>, is the same procedure, just select "Add member variable <indexterm><primary>variable</primary></indexterm>" in the popup menu.</para>
      <para>The difference between the actions of these dialogs, is that the adding of a variable <indexterm><primary>variable</primary></indexterm> will add the variable <indexterm><primary>variable</primary></indexterm> to the classdeclaration <indexterm><primary>classdeclaration</primary></indexterm>, while the adding of a method will instead add the method's declaration <indexterm><primary>declaration</primary></indexterm> and the method's implementation <indexterm><primary>implementation</primary></indexterm> header to the sources.</para>
      <para> As the classviewer <indexterm><primary>classviewer</primary></indexterm>directly updates itself, you have immediate access to the new method implementation <indexterm><primary>implementation</primary></indexterm>, so you only have to fill out the code for the actual purpose of the method.</para>
    </sect1>
</chapter>

  <chapter id="the-dialog-editor-0">
    <title>The Dialog Editor</title>

    <para>The <application>KDevelop</application> integrated dialog editor <indexterm><primary>dialog editor</primary></indexterm> allows the easy construction of the widgets <indexterm><primary>widgets</primary></indexterm> and dialogs your application uses, all by graphical means.</para>
    <para>You see the direct appearance of your dialog as it will be presented to the user. Using the dialog editor <indexterm><primary>dialog editor</primary></indexterm> is usually the first step you would take after creating a new project with the <application>kappwiz</application>;<indexterm><primary>KAppWizard</primary></indexterm>. Here you can create your main view, the user interaction dialogs and, after finishing the graphical work, the code generation. This way, your project will contain all the usually considered "difficult" parts that normally would take a long time to implement. Then, the "rest" of your work is implementing the functionality in the generated code.</para>
    <para>This chapter deals with how to use the dialog editor <indexterm><primary>dialog editor</primary></indexterm> to create your project widgets<indexterm><primary>widgets</primary></indexterm>, as well as what to do in case you see your widgets <indexterm><primary>widgets</primary></indexterm> need corrections or additions during the further development process.</para>
    <para>You can switch to the dialog editor <indexterm><primary>dialog editor</primary></indexterm> either by selecting <guimenuitem>"Dialog Editor"</guimenuitem> from the <guimenu>"View<indexterm><primary>View</primary></indexterm>"</guimenu> menu or by the corresponding toolbar icon.</para>
<para>To switch back to the Project Editor, select <guimenuitem>"KDevelop"</guimenuitem> from the dialog editor<indexterm><primary>dialog editor</primary></indexterm>'s <guimenu>"View<indexterm><primary>View</primary></indexterm>"</guimenu> menu, or the icon in the toolbar.</para>
    <para>What else does the dialog editor<indexterm><primary>dialog editor</primary></indexterm>'s interface offer you?  Mainly, that its appearance is almost the same as the project editor, in term of the main view separation as well as the menu and toolbars. This allows you to get accustomed to the dialog editor <indexterm><primary>dialog editor</primary></indexterm> very quickly, and, as it completely interacts with the project management, stay in the dialog editor <indexterm><primary>dialog editor</primary></indexterm> if you want to control your build-process. Actions that require to switch back to <application>KDevelop</application> will do that automatically for you, for example,  accessing the documentation browser. Just select the menu commands, and <application>KDevelop</application> reacts to your will.</para>
<para>The following sections give you an overview of the dialog editor <indexterm><primary>dialog editor</primary></indexterm> interface, how to create a new dialog initially and how set up the properties of the child widgets <indexterm><primary>widgets</primary></indexterm> that your dialog contains.</para>

    <sect1 id="the-dialog-editor-view">
      <title>The Dialog Editor View</title>
      
      <sect2 id="the-mainview">
	<title>The Mainview</title>

	<para>The dialog editor <indexterm><primary>dialog editor</primary></indexterm>'s view is logically separated by:</para>
	<itemizedlist>
	  <listitem>
	    <para>The Widgets Tab, containing the <guilabel>"Widgets"</guilabel>, <guilabel>"Dialogs"</guilabel> and <guilabel>"Items"</guilabel> tabs. These are described in <link linkend="Adding-Widgets">Adding Widgets</link>.</para>
	  </listitem>
	  <listitem>
	    <para>The Widget-Editor, representing the editing view for creating your dialog. See <link linkend="The-Widget-Editor">The Widget Editor</link></para>
	  </listitem>
	  <listitem>
	    <para>The Properties window, containing a list of properties and their values, dependent on the currently selected widget in the widget editor. See <link linkend="Setting-Properties">Setting Properties</link> for information how to specialize the widget's behavior and look.</para>
	  </listitem>
	</itemizedlist>
      </sect2>

      <sect2 id="menubar-menubar-toolbar-toolbar-and-statusba">
	<title>Menubar <indexterm><primary>Menubar</primary></indexterm>, Toolbar <indexterm><primary>Toolbar</primary></indexterm> and Statusbar <indexterm><primary>Statusbar</primary></indexterm> differences to <application>KDevelop</application></title>

<para>In Dialogeditor mode, <application>KDevelop</application> changes the menubar, toolbar and statusbar slightly, to provide the functionality you need for creating widgets <indexterm><primary>widgets</primary></indexterm>.</para>
<para>The differences are:</para>

	<sect3 id="menubar-menubar">
	  <title>Menubar <indexterm><primary>Menubar</primary></indexterm></title>
	  <variablelist>
	    <varlistentry>
	      <term><guimenu>"File"</guimenu> Menu</term>
	      <listitem><para><guimenuitem>"Open"</guimenuitem> allows you to open a dialog definition file.</para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><guimenu>"View"</guimenu> Menu</term>
	      <listitem><para> replaces <guimenuitem>"Tree-View"</guimenuitem> with <guimenuitem>"Widgets-View"</guimenuitem>, en/disabling the Widgets-View tabs; adds <guimenuitem>"Properties-View"</guimenuitem> to en/disable the Properties-View and <guimenuitem>"Grid Size"</guimenuitem> to let you specify the grid size in pixels for horizontal and vertical values.</para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><guimenu>"Build"</guimenu> Menu</term>
	      <listitem><para>replaces <guimenuitem>"Compile File<indexterm><primary>Compile File</primary></indexterm>"</guimenuitem> with <guimenuitem>"Generate Sources"</guimenuitem>. This lets you actually generate the sources for yourdialog.</para></listitem>
	    </varlistentry>
	  </variablelist>
	</sect3>

	<sect3 id="toolbar-toolbar">
	  <title>Toolbar <indexterm><primary>Toolbar</primary></indexterm></title>

	  <para>The toolbar contains a new icon for <guiicon>"New Dialog"</guiicon> as well as the replacement of <guiicon>"Compile File<indexterm><primary>Compile File</primary></indexterm>"</guiicon> with <guiicon>"Generate Sources"</guiicon>.</para>
	</sect3>

	<sect3 id="statusbar-statusbar">
	  <title>Statusbar <indexterm><primary>Statusbar</primary></indexterm></title>

	  <para>The statusbar now provides information about the currently selected widget, especially displaying the values for X and Y size in the coordinate system. For Statusbar <indexterm><primary>Statusbar</primary></indexterm> help, you are provided the same functionality as in Project-editing mode.</para>

	  <para>While changing widget size, the statusbar shows the current values for width and height of the selected widget.</para>
	</sect3>
      </sect2>
    </sect1>

    <sect1 id="creating-a-new-dialog">
      <title>Creating a New Dialog</title>
      
      <para>After creating your project skeleton, you are provided a ready-to-run application, according to your preferences. As <application>KDevelop</application> provides the project types KDE, and Qt application, the dialog editor <indexterm><primary>dialog editor</primary></indexterm> recognizes this and offers widget construction by the widgets <indexterm><primary>widgets</primary></indexterm> that are provided in the used libraries. To save time, you already should have a design in mind for the intended actions. For information about widget design, see <ulink url="programming/index-6.html">The KDevelop Programming Handbook</ulink>.</para>

      <para>To create a new dialog, select <guimenuitem>"New"</guimenuitem> from the <guimenu>"File"</guimenu> menu <indexterm><primary>"File"-menu</primary></indexterm> or select <guimenuitem>"New"</guimenuitem> from the context menu in the "Dialogs" tab. The New File Dialog appears where you can select the item Qt/KDE Dialog(<filename>*.kdevdlg</filename>). Enter the file name for your dialog to save the layout to. Then press <guibutton>OK</guibutton> and a new dialog will appear. When finished with the new dialog, select <guimenuitem>"Generate Complete Sources"</guimenuitem> from the <guimenu>"Build"</guimenu> Menu. The dialog to generate the widget´s source file will appear. There you have to give <application>KDevelop</application> the dialog-specific information about the base class, the source file names and destination.</para>

      <sect2 id="dialog-class">
	<title>Dialog Class</title>

	<para>The dialog class you can select, is the class that is inherited by your new widget, which is technically represented by a class itself.</para>
	<para>Therefore, you have the following options:</para>
	<variablelist>
	  <varlistentry>
	    <term><classname>QWidget</classname></term>
	    <listitem><para> the base class for all user interaction widgets <indexterm><primary>widgets</primary></indexterm> provided by Qt. Used for main views and top-level widgets <indexterm><primary>widgets</primary></indexterm>.</para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><classname>QFrame</classname></term>
	    <listitem><para>inherits <indexterm><primary><literal>QWidget</literal></primary></indexterm><classname>QWidget</classname> and is used by numerous widgets <indexterm><primary>widgets</primary></indexterm> as a base class. This is useful for widgets <indexterm><primary>widgets</primary></indexterm> that want to have a <classname><indexterm><primary><literal>QFrame</literal></primary></indexterm>QFrame</classname> functionality in addition to <classname><indexterm><primary><literal>QWidget</literal></primary></indexterm>QWidget</classname> methods.</para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>Custom</term>
	    <listitem><para>inherits a custom class that has to be set in the "Custom Properties". This could be an already designed class provided by your project or the libraries.</para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><classname>QDialog</classname></term>
	    <listitem><para> the base class for dialogs that you would inherit for user interaction like setting properties or changing values.</para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><classname>QTabDialog</classname></term>
	    <listitem><para>inherits <indexterm><primary><literal>QDialog</literal></primary></indexterm><classname>QDialog</classname> and provides a dialog with predefined buttons and a set of tabs, which you will provide by the widgets <indexterm><primary>widgets</primary></indexterm> that you create.</para></listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>Custom Properties</term>
	    <listitem><para>For the inheritance of a custom class as selected in the dialog class field, you have to specify the classname, which goes to "Custom Class". The dialog editor <indexterm><primary>dialog editor</primary></indexterm> uses this for the code-generation; therefore, you also have to insert the "Custom Header", where the header filename of the custom class has to be set.</para></listitem>
	  </varlistentry>
	</variablelist>
      </sect2>

      <sect2 id="files">
	<title>Files</title>

	<para>In the "Files" section, you have to enter the widget's specific information. This is the classname (which would be e.g. <classname>KColorSelectDlg</classname> for a dialog that allows selecting the color of a pen), the header, C++, and Data filenames. When inserting the Classname, the filenames are given by the dialog editor <indexterm><primary>dialog editor</primary></indexterm>, but you can change the filenames.</para>
	<para>Now, what about the files? When you are ready with constructing the widget visually, you will have to generate the files that contain the implementation <indexterm><primary>implementation</primary></indexterm> for your widget. As this will be a class, the dialog will exist by the header file containing the classdeclaration <indexterm><primary>classdeclaration</primary></indexterm>, and a C++ file containing the method implementation <indexterm><primary>implementation</primary></indexterm> for your widget's methods and slots. The Data file is the file that will contain a function that is called by the constructor of your widget, the <function>initDialog()</function> method. This file itself shouldn't be changed as it will contain the generated code from the dialog editor <indexterm><primary>dialog editor</primary></indexterm> to create the widget on the screen.</para>
	<para>If you ever have to change values, you should do this by the constructor, or be sure that you won't change the dialog during the development process, as the Data file will be overwritten each time the code is generated for your widget. The header and C++ file contain sections, where the dialog editor <indexterm><primary>dialog editor</primary></indexterm> writes and these are marked by comments. After file generation, you can change any values and settings, but only outside these sections, otherwise your changes will get lost by the next code-creation.</para>
      </sect2>

      <sect2 id="location">
	<title>Location</title>

	<para>For generating the widget's sources, the dialog editor <indexterm><primary>dialog editor</primary></indexterm> needs to know the location these will go. The default value for the output <indexterm><primary>output</primary></indexterm> directory is the current project subdirectory containing the sources, already present.</para>
	<para>After pressing <guibutton>"OK"</guibutton>, your default values are generated and an empty Widget constructor is opened. Then you are ready to go for creating
your own widget. Mind that the dialog editor <indexterm><primary>dialog editor</primary></indexterm> currently only supports static widgets <indexterm><primary>widgets</primary></indexterm> without geometry management. If you're about to use geometry management for your widgets <indexterm><primary>widgets</primary></indexterm>, you should make yourself accustomed with the classes <indexterm><primary>classes</primary></indexterm> that Qt provides for this, create a new class with the classgenerator, and write your widget by hand. For more information, see <ulink url="programming/index.html">The KDevelop Programming Handbook</ulink>.</para>
      </sect2>
    </sect1>

    <sect1 id="adding-widgets">
      <title>Adding Widgets</title>

      <para>After specifying the dialogs or widgets <indexterm><primary>widgets</primary></indexterm> class and filenames, you are ready to start creating the widget and filling it with contents.</para>
      <para>Adding low-level widgets <indexterm><primary>widgets</primary></indexterm> to your dialog is a very easy task. Just select the widget you want to add from the <guilabel>"Widgets"</guilabel> tab on the left by a single click on the according widget icon. The widget will then be laid on the left upper corner of the currently opened main widget.</para>
      <para>An added widget then gets the default size of 100x30 pixels on the editor <indexterm><primary>editor</primary></indexterm> view. To move a widget, click over it to activate the drawing frame, which is displayed in dark grey with hot spots on the corners and on the center of each of the top, bottom, left and right sides of the widget. A cross-cursor indicates that the widget can be moved. To move it, press the <mousebutton>left</mousebutton> mouse button and keep it pressed. then move the widget with your mouse to the place you want to have it displayed later.</para>
      <para>To resize a widget, move your mouse cursor over one of the hot spots of the already activated item. The mouse cursor then changes to a double-arrow indicating the directions, in which resizing can be done. Press the <mousebutton>left</mousebutton> mouse button and hold it pressed. The widget item will change it's size when the mouse is moved to the direction indicated by the cursor.</para>
      <para>Further, the widget editor contains a lot of context menus to help you coordinate your work. Those are available over all items in the widgets <indexterm><primary>widgets</primary></indexterm> tab and give you a quick help message window that shows the class name of the selected widget with a short description.</para>
<para>Over a selected widget, the context menu shows the class name of the selected item and offers:</para>
      <itemizedlist>
	<listitem>
	  <para><guimenuitem>Raise</guimenuitem></para>
	</listitem>
	<listitem>
	  <para><guimenuitem>Lower</guimenuitem></para>
	</listitem>
	<listitem>
	  <para><guimenuitem>Raise to top</guimenuitem></para>
	</listitem>
	<listitem>
	  <para><guimenuitem>Lower to bottom</guimenuitem></para>
	</listitem>
	<listitem>
	  <para><guimenuitem>Cut</guimenuitem></para>
	</listitem>
	<listitem>
	  <para><guimenuitem>Delete</guimenuitem></para>
	</listitem>
	<listitem>
	  <para><guimenuitem>Copy</guimenuitem></para>
	</listitem>
	<listitem>
	  <para><guimenuitem>Paste</guimenuitem></para>
	</listitem>
	<listitem>
	  <para><guimenuitem>Help</guimenuitem></para>
	</listitem>
      </itemizedlist>
      <para>After setting the size and position, you can edit the preferences for the selected item on the Preferences window.</para>

      <sect2 id="the-widgets-tabulator">
	<title>The Widgets Tab</title>

	<para><indexterm><primary>dialog editor widgets</primary></indexterm>The widgets <indexterm><primary>widgets</primary></indexterm> tab represents the available widgets <indexterm><primary>widgets</primary></indexterm> you can place on the dialog. If you want information about a certain widget, press the <mousebutton>right</mousebutton> mouse button over a widget icon and select <guimenuitem>"Quick-Help"</guimenuitem> from the popup-menu. Mind that the dialog editor <indexterm><primary>dialog editor</primary></indexterm> automatically determines, if your project type is Qt-only or KDE. This prevents you from using KDE-widgets <indexterm><primary>widgets</primary></indexterm> in a Qt only application.</para>
	<para>After you selected a widget item, it is placed with default sizes and values on the editing window and marked selected by a frame and darkened corners. To resize a widget, move your mouse over one of the dark spots and your cursor will change to display which resizing directions are possible. Then press the mousebutton and move the mouse while holding it. When you're finished with resizing the widget, release the mouse. While resizing, the statusbar displays the current position of the item by X and Y values and the current size by W(Width) and H(Height) values.</para>
      </sect2>

      <sect2 id="the-dialogs-tabulator">
	<title>The Dialogs Tab</title>

	<para><indexterm><primary>project dialogs</primary></indexterm>The dialogs tab is intended to let you open your project's dialogs by a mouseclick. As the dialog's structure is saved in a <filename>*.kdevdlg</filename> file within the directory that contains the generated files, only those dialog definition files are shown. Mind that you don't delete these definition files.</para>
	<para>On selecting a dialog, it will be shown as by the state it was saved in the last editing step in the Widget-Editor view.</para>
      </sect2>

      <sect2 id="the-items-tabulator">
	<title>The Items Tab</title>

	<para><indexterm><primary>dialog items</primary></indexterm>The Items tab lets you have a hierarchal overview over the currently present widget items of the dialog. This means, that, as your background represents the parent of all widgets <indexterm><primary>widgets</primary></indexterm> within the dialog, it is shown on top of the tree. The children of the main dialog are then listed in the next tree-level.</para>
<para>On selecting an item, it gets marked in the editor view, and the properties are shown in the properties window. Using the items view is sometimes important if your widgets <indexterm><primary>widgets</primary></indexterm> behavior depends on the parent-child relationship.</para>
      </sect2>
    </sect1>

    <sect1 id="the-widget-editor">
      <title>The Widget Editor</title>

      <para>The Widget Editor is the main view that is placed in the middle, and is where you construct your widget. After adding items, they can be selected and resized, as well as moved to the place you need them. On all items, popup menus provide a quick access to functions like cut, copy and insert.</para>
    </sect1>

    <sect1 id="setting-properties">
      <title>Setting Properties</title>
      
      <para><indexterm><primary>setting widget properties</primary></indexterm>The properties window on the right is the place where you set the default behavior for the widget and its items. It displays the pre-set values for each selected item right away; changing values will result in direct changes on the Widget Editor view, e.g. naming labels or buttons.</para>

      <para>To separate certain property values by their effect, the properties window contains four folders; selecting a folder will pop up all values for the properties group. All possible values are described below. Mind that the properties are dependent on the widget, <abbrev>e.g.</abbrev> a label and button will have a property for their on-screen name, while lineedits will have properties for methods like <function>setText()</function>.</para>
      <para>For a complete list of the available values per item, you should see the class-reference of the widget which explains the used methods and all possible values. Note that most values are implemented in <classname><indexterm><primary><literal>QWidget</literal></primary></indexterm>QWidget</classname> and are used for all widgets <indexterm><primary>widgets</primary></indexterm> that inherit
<indexterm><primary><literal>QWidget</literal></primary></indexterm><classname>QWidget</classname>. Also mind that the final code does not contain any method calls that are unchanged by the user, and therefore use the default values as given in the widget's constructors.</para>
</sect1>

    <sect1 id="generating-files">
      <title>Generating Files</title>

      <para><indexterm><primary>dialog sourcecode generation</primary></indexterm></para>
      <para>After creating a widget, you have to generate the sourcecode to make it available in your project. This can be done either with the <guimenuitem>"Generate Sources"</guimenuitem> from the <guimenu>"Build"</guimenu> menu or by the corresponding icon in the dialog editor <indexterm><primary>dialog editor</primary></indexterm> toolbar. Your <filename>Makefile<indexterm><primary>Makefile</primary></indexterm></filename> files will be updated automatically to include the new widget in the compiling process; therefore, after calling <guimenuitem>"Generate Sources"</guimenuitem>, you can build your project again within the dialog editor <indexterm><primary>dialog editor</primary></indexterm>. The output <indexterm><primary>output</primary></indexterm> window pops up below the Widget-Editor window, as in Project Editor mode.</para>
      <para>Now that your project contains a new widget, your work as a programmer is to implement functionality to the used slots and eventually add other methods you may need. <footnote><para>See <ulink url="programming/index-6.html">The KDevelop Programming Handbook, The Dialogeditor</ulink> for more information about widget properties and sourcecode generation.</para></footnote></para>
    </sect1>
  </chapter>

  <chapter id="the-internal-debugger">
    <title>The Internal Debugger</title>
    
    <sect1 id="setup">
      <title>Setup</title>
      
      <para>The default setup for <application>KDevelop</application> is to use the internal debugger. You can change this under <guilabel>"Options"</guilabel> selected from the <guimenuitem>"KDevelop setup"</guimenuitem> menu item, and then the Debugger tab.</para>
<para>Click on "Use external debugger" if you wish to use a different debugger and enter the name of the debugger to use. See your debuggers documentation on how to run it.</para>
<para>Selecting the internal debugger enables an additional set of options you can choose from:</para>

      <variablelist>
	<varlistentry>
	  <term>Display static members</term>
	  <listitem><para>Displaying static members makes <application>gdb</application> slower in producing data within kde and qt. It may change the "signature" of the data which <classname>QString</classname> and friends rely on. If you need to debug into these values, then check this option.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	  <term>Display mangled names</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>Try setting <abbrev>BP</abbrev>s on lib load</term>
	  <listitem><para>Try setting <abbrev>BP</abbrev>s on lib load: This will try to set pending breakpoints on loading a library. If <application>gdb</application> hasn't seen a library that will be loaded via "dlopen" then it will refuse to set a breakpoint in that code. We can get <application>gdb</application> to stop on a library load and hence try to set the pending breakpoints. See <link linkend="Shared-libraries-and-breakpoints">Shared libraries and breakpoints</link> for more details and a "gotcha" relating to this behaviour. If you are not "dlopen"ing libs, leave this off.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	  <term>Enable floating toolbar</term>
	<listitem><para>Enable floating toolbar: This will allow you to use the floating toolbar to control the debugger in addition to the menu and buttons. The toolbar is most useful for debugging <abbrev>GUI</abbrev> applications. For details see <link linkend="The-floating-toolbar">The floating toolbar</link>.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	  <term>Enable separate terminal for application I/O</term>
	<listitem><para>This allows you to enter terminal input when your application contains terminal input code (<abbrev>e.g.</abbrev> cin, fgets <abbrev>etc.</abbrev>). If you use terminal input in your app, then tick this option. Otherwise leave this off.</para>
	  <tip>
	    <para>Tip: This option is most useful if you use it in combination with <link linkend="The-floating-toolbar">the floating toolbar</link>, because this way, the terminal window won't be hidden behind the <application>KDevelop</application> window when you control the debugger.</para>
	  </tip>
	  </listitem>
	</varlistentry>
      </variablelist>
     </sect1>

    <sect1 id="using-the-internal-debugger">
      <title>Using the internal debugger</title>

      <sect2 id="changes-made-in-the-tree-and-output-view-win">
	<title>Changes made in the tree and output view window</title>
	
	<para>If you choose the internal debugger, four tabs are added to your tree and output view windows.</para>

	<sect3 id="on-the-tree-view-window">
	  <title>On the tree view window</title>
	  
	  <variablelist>
	    <varlistentry>
	    <term><guilabel>VAR</guilabel> tab</term>
	      <listitem><para>A tree view of the local variables at the current place in the  program you have stopped at. You can also see local variables in the function that called this functions. The <guilabel>VAR</guilabel> tab also contains a watch window. This allows you to see the value of global variables, or perhaps you may want to see only  one local variable rather than the variable in a large list of local variables.</para>
	    </listitem>
	    </varlistentry>
	  </variablelist>
	</sect3>

	<sect3 id="on-the-output-view-window">
	  <title>On the output view window</title>
	  <variablelist>
	    <varlistentry>
	      <term>breakpoint</term>
	      <listitem><para>A list of breakpoints set, and their current state</para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>framestack</term>
	      <listitem><para>The calling stack</para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>disassemble</term>
	      <listitem><para>A machine instruction view of the code, showing the current instruction to be executed</para></listitem>
	    </varlistentry>
	  </variablelist>
	</sect3>
      </sect2>

      <sect2 id="changes-made-in-the-debug-menu-and-on-the-pa">
	<title>Changes made in the Debug menu and on the panel</title>
	
	<sect3 id="on-the-panel">
	  <title>On the panel</title>
	  
	  <para>Two normal and two dropdown buttons to control the debugger functions will be accessible as soon as you start the debugger.</para>
	</sect3>
	
	<sect3 id="available-functions">
	  <title>In the Debug menu</title>
	  
	  <para>When you start debugging, ten items to control the debugger will be enabled.</para>
	  
	  <para>Available functions: </para>
	  <variablelist>
	    <varlistentry>
	      <term><menuchoice><guimenu>Debug</guimenu><guimenuitem>Run</guimenuitem></menuchoice></term>
	      <listitem><para><action>Continue the program from the current point</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><menuchoice><guimenu>Debug</guimenu><guimenuitem>Run to cursor</guimenuitem></menuchoice></term>
	      <listitem><para><action>Execute the program up to the current cursor position</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><menuchoice><guimenu>Debug</guimenu><guimenuitem>Step over</guimenuitem></menuchoice></term>
	      <listitem><para><action>Execute one line of code, stopping in the next line of code in the same source file.  This will run any functions encountered until the above condition is met</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><menuchoice><guimenu>Debug</guimenu><guimenuitem>Step over i(nstruction)</guimenuitem></menuchoice></term>
	      <listitem><para><action>Execute one machine instruction, as above</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><menuchoice><guimenu>Debug</guimenu><guimenuitem>Step in</guimenuitem></menuchoice></term>
	      <listitem><para><action>Execute exactly one line of source code.  This means you will "step into" the current function, if necessary</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><menuchoice><guimenu>Debug</guimenu><guimenuitem>Step in i(nstruction)</guimenuitem></menuchoice></term>
	      <listitem><para><action>Execute one machine instruction as above</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><menuchoice><guimenu>Debug</guimenu><guimenuitem>Step out</guimenuitem></menuchoice></term>
	      <listitem><para><action>Run to the end of the current stack frame (function)</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><menuchoice><guimenu>Debug</guimenu><guimenuitem>Viewers</guimenuitem></menuchoice></term>
	      <listitem><para><action> Allows a variety of views into the data.</action></para>
		<para>Currently implemented views are:</para>
		<itemizedlist>
		  <listitem>
		    <para> Memory address</para>
		  </listitem>
		  <listitem>
		    <para> Disassemble code</para>
		  </listitem>
		  <listitem>
		    <para> Current registers</para>
		  </listitem>
		  <listitem>
		    <para> Current libraries</para>
		  </listitem>
		</itemizedlist>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><menuchoice><guimenu>Debug</guimenu><guimenuitem>Interrupt</guimenuitem></menuchoice></term>
	      <listitem><para><action>Stop the application executing</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><menuchoice><guimenu>Debug</guimenu><guimenuitem>Stop</guimenuitem></menuchoice></term>
	      <listitem><para><action>Stop the application executing, and exit the debugger</action></para></listitem>
	    </varlistentry>
	  </variablelist>
	</sect3>
      </sect2>

      <sect2 id="details">
	<title>Details</title>
	
	<sect3 id="breakpoints">
	  <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 anytime, however watchpoints on local variables only have meaning  in the variables local scope. Watchpoints have more meaning when you are dealing with global variables.</para>
	</sect3>

	<sect3 id="setunset-breakpoints">
	  <title>Set/Unset breakpoints</title>

	  <para>Simple one click set/unset. Click on the "icon" border to the left of the text in the editor at the line you want the breakpoint. Click again on this line to unset the breakpoint.</para>
	</sect3>

	<sect3 id="alternative-beakpoint-manipulating-via-menus">
	  <title>Alternative beakpoint manipulating via menus</title>

	  <para>By <mousebutton>right</mousebutton> clicking on a breakpoint in the breakpoint list or on a breakpoint in the editors icon border you will get a menu of breakpoint options. This allows you to remove this breakpoint, clear all breakpoints, or edit the breakpoint.</para>
	</sect3>

	<sect3 id="editing-breakpoints">
	  <title>Editing breakpoints</title>

	  <para>Use the above menu to display the edit breakpoint dialog. This contains the following fields :</para>
	  <variablelist>
	    <varlistentry>
	      <term><guimenuitem>Conditional</guimenuitem></term>
	      <listitem><para><action>Enter the condition that must be met before <application>gdb</application> will interrupt the program execution</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><guimenuitem>Ignore count</guimenuitem></term>
	      <listitem><para><action>How many times you want the code to pass through this breakpoint before <application>gdb</application> interrupts the program execution</action></para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><guimenuitem>Enable</guimenuitem></term>
	      <listitem><para><action>When enabled, <application>gdb</application> will break at this breakpoint.  When disabled <application>gdb</application> will not break here</action></para></listitem>
	    </varlistentry>
	  </variablelist>
	</sect3>

	<sect3 id="clear-all-breakpoints">
	  <title>Clear all breakpoints</title>
	  
	  <para>Removes all the breakpoints for this program.</para>
	</sect3>

	<sect3 id="setunset-watchpoints">
	  <title>Set/Unset watchpoints</title>

	  <para>In the <guilabel>VAR</guilabel> view click with the <mousebutton>Right</mousebutton> Mouse button on a variable. A popup menu will be displayed allowing you to set a watchpoint on the local variable. This functionality is limited to the scope that the local variable is in. As the variable goes out of scope, the program breaks, and the watchpoint is deleted.</para>
	  
	  <warning><para>WARNING: 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 <mousebutton>right</mousebutton> mouse click on a previously entered watch variable, and selecting "toggle watchpoint"</para>
	</sect3>

	<sect3 id="setunset-watch-variables">
	  <title>Set/Unset Watch variables</title>

	  <para>At the bottom of the <guilabel>VAR</guilabel> view there is the <guilabel>"Watch"</guilabel> field where you can enter the variable name you wish to see display in the watch list. Enter the variable name and type <userinput>enter</userinput> or click on the <guibutton>"Add"</guibutton> button alongside the field. <mousebutton>Right</mousebutton> Mouse clicking on the watch variable in the treeview will bring up a menu so that you can remove the variable from the list.</para>

	  <para>You can also enter a watch variable by <mousebutton>right</mousebutton> mouse clicking on a variable name in the editor window. This displays a popup menu with <guimenuitem>"watch: variable name"</guimenuitem> on it.</para>
	</sect3>

	<sect3 id="changing-variable-values">
	  <title>Changing variable values</title>

	  <para>This is done via the watch variable. If you have a variable <varname>"test"</varname> then to set <varname>"test"</varname> to 5, type <userinput>"test=5"</userinput> in the watch field and add it to the list. Note that <varname>"test"</varname> will be set to "5" <emphasis>every</emphasis> time the program stops at a breakpoint, so once you have set the variable, usually you should remove the item from the watch view.</para>
	</sect3>
      </sect2>
    </sect1>

    <sect1 id="the-floating-toolbar">
      <title>The floating toolbar </title>

      <para>The floating toolbar is a feature of the internal debugger, which greatly improves your comfort in debugging <abbrev>GUI</abbrev> applications. The toolbar is either on top of all windows displayed, or docked into the panel. When docked you can run your code by clicking on the docked icon. The function this performs is the "step over" function. <mousebutton>Right</mousebutton> clicking on the docked item allows you to restore the toolbar and optionally place focus on <application>Kdevelop</application>.</para>
      <para>Besides the <link linkend="Available-functions">functions available from the Debug Menu</link>, the floating toolbar offers two additional 
functions:</para>
      <variablelist>
	<varlistentry>
	  <term>Set focus on <application>KDevelop</application></term>
	      <listitem>
		<para>Set the focus on <application>KDevelop</application></para>
	      </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Set focus on app</term>
	  <listitem>
	    <para>Set focus on app : This sets the focus on the window that had focus
when you pressed the "set focus on <application>KDevelop</application>" button. This is a compromise, 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 then please let us know.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>When <application>gdb</application> interrupts the program, probably because a breakpoint has been triggered, we highlight the "Set focus on <application>KDevelop</application>". We do not automatically switch focus to <application>KDevelop</application> so that you can view the application window at this point. Click on the <guiicon>"set focus"</guiicon> button to switch to <application>KDevelop</application> or press a button on the toolbar to perform your selected function.</para>
    </sect1>

    <sect1 id="shared-libraries-and-breakpoints">
      <title>Shared libraries and breakpoints </title>

      <para>Shared libraries and breakpoints have a problem but that problem has a reasonable solution. The problem is that <application>gdb</application> will not accept breakpoints in source that is in a shared library which has not yet been opened, but will be opened via a dlopen.</para>
      <para>The solution is to get <application>gdb</application> to tell us when a shared library has been opened. We do so by setting "stop-on 1". This means that when the user sets a breakpoint, we flag this breakpoint as pending, try to set the breakpoint and if <application>gdb</application> says it succeeded then flag it as active. If <application>gdb</application> is not successful then we leave the breakpoint as pending. The next instruction will always be "continue" .</para>
      <para>This is known as "lazy breakpoints"</para>
      <para>However, this can lead to a problem when you use the "step over" command and step over code that will load a library. This will trigger a break on the library load, and, normally the debugger would do a "continue" (<abbrev>i.e.</abbrev> run to the next breakpoint or the end of the code). The user, however, is expecting the program to stop at the next line, so in this situation we do not continue, but leave it at that point (which will be somewhere inside a dlopen command). This is disconcerting but cannot be helped.</para>
    </sect1>
  </chapter>

  <chapter id="cvs-integration">
    <title>CVS Integration</title>

    <para><application>KDevelop</application> also takes care of managing your project via <abbrev>CVS</abbrev> repositories. The goal behind <abbrev>CVS</abbrev> (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. The initial repository contains the base set of files that the project includes; directories and files are then added or removed to the <abbrev>CVS</abbrev> by the developers. Locally, the developer works on his own copy of the <abbrev>CVS</abbrev> tree. He writes his changes into his local files and tests if his project still works, at least to the extent where incomplete sources don't prevent other developers from still working on the <abbrev>CVS</abbrev> repository if they receive the changes. </para>

    <sect1 id="creating-a-repository">
      <title>Creating a Repository</title>

      <para>When creating a new project with <application>KDevelop</application>, you can directly import the project as a <abbrev>CVS</abbrev> module. To enable this, you have to have <abbrev>CVS</abbrev> installed (which should be already, if not, revise your system installation or contact your system administrator).</para>

      <para>On the third page of the <application>kappwiz</application>; (<guilabel>VCS support</guilabel>), choose <guilabel>"CVS"</guilabel>. Then the editing fields of this page become active and you can specify the import parameters, see below for the given options. The <application>kappwiz</application>; will then import the project source tree as a module into the <abbrev>CVS</abbrev> root directory and create your new project as a local copy of the <abbrev>CVS</abbrev> source tree that you will be working on.</para>
      <important><para>Attention: to create an initial repository, you have to have write  access to the <abbrev>CVS</abbrev> root directory! Also the <abbrev>CVS</abbrev> root directory has to be on the same machine where you´re running <application>KDevelop</application> at the time of it's creation! If you want to have the repository on a dedicated <abbrev>CVS</abbrev> server either contact this servers´ system administrator to create the project with <application>KDevelop</application> on the server machine or do 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 <abbrev>CVS</abbrev> server</para></step>
	<step><para>delete local project source tree</para></step>
	<step><para>check out the project source tree from <abbrev>CVS</abbrev></para></step>
	<step><para>enable <abbrev>CVS</abbrev> support in the project options dialog as described below after loading the project file of your <abbrev>CVS</abbrev> copy you checked out.</para></step>
      </procedure>
      </important>

      <para>For more details on <abbrev>CVS</abbrev> commands, please revise your system help on <application>cvs</application>, e.g. by doing a <command>man cvs</command>.</para>
      <para>In the following we will discuss the options when creating a repository with the <application>kappwiz</application>;</para>

      <variablelist>
	<varlistentry>
	  <term>VCS Location:</term>
	  <listitem>
	    <para>This is the <abbrev>CVS</abbrev> root directory where the project source tree will be imported and where commits, checkouts and updates take place.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Repository in <abbrev>CVS</abbrev></term>
	  <listitem>
	    <para>This is the module name given for your project. As this is the same as your project directory you can´t change that.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Vendor Tag</term>
	  <listitem>
	    <para>this is a tag for the entire branch</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Log Message</term>
	  <listitem>
	    <para>is the first log message entry of the new module. When adding or commiting to the repository, you will be asked for a log message each time to document your changes to the repository source tree.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Release Tag</term>
	  <listitem>
	    <para>this specifies the tag under which your project source tree can be found, meaning that you can create several projects with the same module name in the <abbrev>CVS</abbrev> root which differ in the tag, so you can work on different branches of the same project. Example: KDE 2 is developed under the tag HEAD (default tag), KDE 1.1.2. can be found in the tag KDE_1_1_2_RELEASE.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>After creating your project with the <application>kappwiz</application>;, the <abbrev>CVS</abbrev> support option is already set for your project, so you can commit and add changes in the way described below in the section "Using <abbrev>CVS</abbrev> Commands".</para>
    </sect1>

    <sect1 id="enabling-cvs-support">
      <title>Enabling <abbrev>CVS</abbrev> Support</title>

      <para>As <abbrev>CVS</abbrev> support is most often only needed by professionals or companies as well as by KDE developers maintaining their project over the KDE <abbrev>CVS</abbrev> server, using the <abbrev>CVS</abbrev> commands of <application>KDevelop</application> is optional. To enable the <abbrev>CVS</abbrev> commands, open the Project-Options dialog and change the option for Version Control to <abbrev>"CVS"</abbrev>.</para>
    </sect1>

    <sect1 id="using-cvs-commands">
      <title>Using CVS Commands</title>
      
      <para>The following commands are available in the <guilabel>LFV</guilabel> and <guilabel>RFV</guilabel> through context menus:</para>

<para>Over a file not included in the repository:</para>
      <variablelist>
	<varlistentry>
	  <term>Add to Repository</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 where the added file is located locally.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <para>Over a file included in the repository:</para>
      <variablelist>
	<varlistentry>
	  <term>Update</term>
	  <listitem><para>Update the selected file with the <abbrev>CVS</abbrev> version</para>
</listitem>
	</varlistentry>
	<varlistentry>
	  <term>Commit</term>
	  <listitem><para>Commit the selected file to the <abbrev>CVS</abbrev> repository</para>
</listitem>
	</varlistentry>
	<varlistentry>
	  <term>Remove from Repository</term>
	  <listitem><para>Remove the file from the repository</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>Over a folder:</para>
      <variablelist>
	<varlistentry>
	  <term>Add</term>
	  <listitem><para>Adds the folder to the repository</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Remove</term>
	  <listitem><para>removes the folder from the repository</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Update</term>
	  <listitem><para>Update the folder recursively to be in sync with the repository</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Commit</term>
	  <listitem><para>Commit any changes recursively to the repository</para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <para>The <abbrev>CVS</abbrev> commands all require a working network connection to the <abbrev>CVS</abbrev> server. When invoking a command, you will be shown a dialog with the command sent to the <abbrev>CVS</abbrev> server and the retrieved output. Thereby you can control what actually happens and if the command was successful or not.</para>
      <para>As the <abbrev>CVS</abbrev> commands of <application>KDevelop</application> only work with the <command>cvs</command> system command and its commandline options, you should have no trouble to use the <abbrev>CVS</abbrev> features.</para>
    </sect1>
  </chapter>

  <chapter id="general-configuration">
    <title>General Configuration</title>

    <para>This chapter describes how you can set your individual preferences about how <application>KDevelop</application> works. All settings addressed below can be found by the according entry in the <guimenu>"Options"</guimenu> menu.</para>

    <sect1 id="configuring-the-tools-menu">
      <title>Configuring the <guimenu>"Tools"</guimenu> Menu</title>

      <para><indexterm><primary>configuring the Tools menu</primary></indexterm><indexterm><primary>"Options"-menu</primary></indexterm></para>
      <para>As <application>KDevelop</application> supports the use of third-party programs within it's user interface, you are able to configure <indexterm><primary>configure</primary></indexterm> any program that suits your application development needs. This can be done by adding programs to the pre-defined ones in the <guimenu>"Tools"</guimenu> menu <indexterm><primary>"Tools"-menu</primary></indexterm>.</para>
      <para>To change the <guimenu>"Tools"</guimenu> menu, select <guimenuitem>"Tools<indexterm><primary>Tools</primary></indexterm>"</guimenuitem> from the <guimenu>"Options"</guimenu> menu. This dialog allows you to specify the entry name, program, and any additional command line options you want to pass on execution.</para>
      <para>To add a program, specify the menu entry, where an ampersand (&amp;) is used as a menu-accelerator; you may compare with the already configured entries with the entry list. Select the binary and pass your commandline options. Then hit <guibutton>"Add"</guibutton> and the entry is added to the list.</para>
      <para> To remove a program from the menu, select the entry name, and choose <guibutton>"Delete"</guibutton>.</para>
      <para>After leaving the configuration dialog <indexterm><primary>configuration dialog</primary></indexterm>, the <guimenu>"Tools"</guimenu> menu updates itself, so the new configuration is already usable without restarting <application>KDevelop</application>.</para>
    </sect1>

    <sect1 id="file-viewer-options">
      <title>File Viewer Options</title>

      <para><indexterm><primary>file viewers</primary></indexterm></para>

      <para>The Logical File Viewer can be configured by context menus completely. As it's intention is to separate files logically, to give a better overview over complex projects, one of the most used configurations is to create file groups. These can be set by opening the context menu with a <mousebutton>right</mousebutton> mouse button click over the project icon displayed at the root of the tree. The menu offers:</para>
      <variablelist>
	<varlistentry>
	  <term><guimenuitem>New File</guimenuitem></term>
	  <listitem><para><action>Opens the New File <indexterm><primary>New File</primary></indexterm> dialog.</action>Equal to the menubar command <menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice></para></listitem>
	</varlistentry>
	<varlistentry>
	  <term><guimenuitem>New Class</guimenuitem></term>
	  <listitem><para><action>Opens the Classgenerator to create a new class.</action>>Equals to the menubar command <menuchoice><guimenu>Project</guimenu><guimenuitem>New Class<indexterm><primary>New Class</primary></indexterm></guimenuitem></menuchoice><indexterm><primary>"Project"-menu</primary></indexterm></para></listitem>
	</varlistentry>
	<varlistentry>
	  <term><guimenuitem>New Group</guimenuitem></term>
	  <listitem><para><action>Opens a dialog to create a new group.</action> There, set the group name and the file filter for the project files <indexterm><primary>project files</primary></indexterm> that will be displayed in this group.</para></listitem>
	</varlistentry>
	<varlistentry>
	  <term><guimenuitem>Show relative path</guimenuitem></term>
	  <listitem><para><action>Displays the files with their path name starting from the main project directory if checked; otherwise only the filename is shown.</action></para></listitem>
	</varlistentry>
      </variablelist>
      <para>Over a group folder, the according context menu offers:</para>
      <variablelist>
	<varlistentry>
	  <term><guimenuitem>New Group</guimenuitem></term>
	  <listitem><para><action>Opens the New Group dialog as in the context menu described above.</action></para></listitem>
	</varlistentry>
	<varlistentry>
	  <term><guimenuitem>Remove Group</guimenuitem></term>
	  <listitem><para><action>removes the group from the <guilabel>LFV</guilabel><indexterm><primary>LFV</primary></indexterm>.</action></para></listitem>
	</varlistentry>
	<varlistentry>
	  <term><guimenuitem>Properties</guimenuitem></term>
	  <listitem><para><action>Opens the properties of the group. There, you can edit the file filters as a list of wildcards, separated by commas.</action></para></listitem>
	</varlistentry>
      </variablelist>
    </sect1>

    <sect1 id="kdevelop-setup">
      <title><application>KDevelop</application> Setup <indexterm><primary>KDevelop Setup</primary></indexterm></title>
      <variablelist>
	<varlistentry>
	  <term>Make-command<indexterm><primary>Make-command</primary></indexterm>:</term>
	  <listitem><para>The General Options dialog lets you configure <application>KDevelop</application>'s general settings. First, you should set the make-command <indexterm><primary>make-command</primary></indexterm> to that  available on your system (generally <command>make</command> or <command>gmake</command>.) If the selected program does not exist, <application>KDevelop</application> will warn you the next time you invoke a <command>make</command> command.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Autosave<indexterm><primary>Autosave</primary></indexterm>:</term>
	  <listitem><para>If Autosave is checked, <application>KDevelop</application> will save all changed files periodically.  The autosaving time range can be set to 3, 5, 15, or 30 minutes.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Autoswitch<indexterm><primary>Autoswitch</primary></indexterm>:</term>
	  <listitem><para>If Autoswitch is enabled, the <application>KDevelop</application> windows will switch on and off according to the usage context, e.g. if you switch to documentation in the <guimenu>"Help"</guimenu> menu, the Documentation browser will be opened, together with the documentation tree, and the output <indexterm><primary>output</primary></indexterm>window will be turned off.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Startup <indexterm><primary>Startup</primary></indexterm>:</term>
	  <listitem><para>For starting <application>KDevelop</application>, you have the option to enable/disable the start-logo<indexterm><primary>start-logo</primary></indexterm>, normally shown during the time <application>KDevelop</application> is loading. Further, if you don't like the last project to be opened on startup, you can disable this default behavior.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect1>

    <sect1 id="changing-keyboard-shortcuts">
      <title>Changing Keyboard Shortcuts <indexterm><primary>Keyboard Shortcuts</primary></indexterm></title>

      <para>The Configure Keys dialog lets you configure the <application>KDevelop</application> key bindings.   A key function can be configured by first choosing the menu entry, then the configuration can be changed by checking values like the <keycombo><keycap>Alt</keycap></keycombo> /<keycombo><keycap> Ctrl</keycap></keycombo>keys etc.</para>
      <note><para>Note that global keys can be configured in the KDE Control Center, such as open file and print.</para></note>
    </sect1>

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

      <sect2 id="directoriesdocumentation-path">
	<title>Directories<indexterm><primary>documentation path</primary></indexterm></title>

	<para>For setting up the documentation browser <indexterm><primary>documentation browser</primary></indexterm> to work correctly, <application>KDevelop</application> needs some information about where the <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm>documentation is placed on the system. Therefore, the Documentation Path properties dialog needs the path of the Qt online documentation in <abbrev>HTML</abbrev> <indexterm><primary>HTML</primary></indexterm> as well as the path to the KDE-Library documentation.</para>
	<para>Usually, the Qt-Documentation <indexterm><primary>Qt-Documentation</primary></indexterm> is placed in the same directory where Qt is installed; e.g. if Qt resides in <filename>/usr/local/qt</filename>, the path you have to enter is <filename>/usr/local/qt/html</filename>. 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 paths can be selected by pressing the appropriate buttons, displaying a path-selection. If your system doesn't contain the documentation for the KDE-libs,  you should first enter the next configuration dialog <indexterm><primary>configuration dialog</primary></indexterm>, <guilabel>Update KDE-Documentation</guilabel><indexterm><primary>KDE-Documentation</primary></indexterm>. This will create the documentation to a path of your choice, and also sets the KDE Library Doc path automatically.</para>
      </sect2>

      <sect2 id="options">
	<title>Options</title>

	<sect3 id="update-kde-documentation-kde-documentation">
	  <title>Update KDE-Documentation <indexterm><primary>KDE-Documentation</primary></indexterm></title>

	  <para>For those users who don't have a recent copy of the KDE-libraries <indexterm><primary>KDE-libraries</primary></indexterm> documentation, especially the documentation for the files installed on the system, the "Update KDE-Documentation" <indexterm><primary>KDE-Documentation</primary></indexterm> dialog creates a new one or updates existing documentation. This function requires your system to have <application>KDoc</application> <indexterm><primary>KDoc</primary></indexterm> and <application>qt2kdoc</application> installed, included in the <abbrev>KDE-SDK</abbrev> <indexterm><primary>KDE-SDK</primary></indexterm> package. First you have to set up the path to your recent kdelibs sources, which is <emphasis>not</emphasis> the include-path for KDE! Just enter the path to the sources, like: <filename>/home/rnolden/kdelibs-1.1/</filename>.</para>
	  <para>Next, you can choose from three different installation modes, as:</para>
	  <variablelist>
	    <varlistentry>
	      <term>Delete old Documentation and install to recent Documentation-path</term>
	      <listitem><para> this assumes that you already have documentation installed and it is placed in the path the entered in the Documentation Path-dialog. This will delete all documentation and install the newly generated documentation into the same path.</para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term> Delete old Documentation and install to new Documentation-path</term>
	      <listitem><para> this will result in deleting the old documentation as above, but gives you the choice to set up a new documentation path.</para></listitem>
	    </varlistentry>
	    <varlistentry>
	      <term> Leave old Documentation untouched and install to new Documentation path</term>
	    <listitem>
	      <para>  This is recommended for a new generation of the kdelibs documentation for users who didn't have one before, and for those who want to keep the previous documentation for an older kdelibs version. </para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	  <para>The "new KDE Libs Documentation path" needs to be set for options 2 and 3 of the installation mode.  This is also recommended for users who generate a new documentation from scratch.</para>

	  <para>After pressing the <guibutton>OK</guibutton> button, <application>KDevelop</application> will create a subdirectory <filename><application>KDoc</application><indexterm><primary>KDoc</primary></indexterm>-reference</filename> in the documentation path containing the <application>KDoc</application> <indexterm><primary>KDoc</primary></indexterm> reference files.  First, the qt library documentation classes <indexterm><primary>classes</primary></indexterm> will be indexed, to connect the Qt documentation with the documentation to be generated for the kdelibs.  So it is important that you have set up the Qt documentation path first to ensure that it can be found by <application>qt2kdoc</application>. Finally, the KDE libs will be indexed and the documentation will be built with cross-references, to give browsing the most functionality.</para>
	  <note><para><emphasis>NOTE:</emphasis> When using <application>KDoc</application> 2, you can additionally 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 or the koffice package respectively.  For kdebase, this is located in <filename>kdebase/</filename>, in the root directory of the sources, for  <application>KOffice</application> in <filename>koffice/lib</filename>. Select option 3 (Leave old Documentation untouched) and leave the output path below that option as it is. This will keep the kdelibs documentation and generate the kdebase-libraries (resp. the koffice-libraries) documentation to the same location, with cross-references to the kdelibs documentation. 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, in the same way as with the KDE-Base and KOffice packages.</para></note>
	</sect3>

	<sect3 id="create-search-database">
	  <title>Create Search Database</title>

	  <para>The Create Search Database dialog, accessed via the <guibutton>create</guibutton> button, allows the programmer to create a database, used to search for a keyword interactively.  To create and use the documentation search function, you must have the program <application>glimpse <indexterm><primary>glimpse</primary></indexterm> 4.0</application> or <application>ht://Dig</application> installed.</para>
	  <para>Preset are the options to index the given KDE-Library documentation, as well as the Qt Documentation<indexterm><primary>Qt-Documentation</primary></indexterm>, assuming the path to the documentation files were set in the "Documentation Path" dialog of the <guimenu>"Options</guimenu> menu.   Additionally, the index can include directories the user has set up himself in the "additional directories to index" field.</para>
	  <para>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, obviously the more the index files will grow. On the other hand, a search in a bigger search-database will be faster and more successful, so we suggest choosing a "medium" size. For help on using the search function, see section <link linkend="Using-the-Documentation-Browser">Using the Documentation Browser</link>.</para>
	</sect3>

	<sect3 id="create-also-kdoc-reference-of-your-project">
	  <title>Create also KDOC-reference of your project</title>

	  <para>This option allows you to create a cross-reference file for your project when generating the <abbrev>API</abbrev> documentation with <application>KDoc</application>. The cross-reference file will be placed in the references directory,  and will make your project available  in the documentation tree. If you don´t have write access to the directory containing the reference files, you have to uncheck this option to generate the API documentation without errors.</para>
	</sect3>
      </sect2>
    </sect1>

    <sect1 id="debugger">
      <title>Debugger </title>
      
      <para>The default setup for <application>KDevelop</application> is to use <link linkend="The-Internal-Debugger">the internal debugger</link>. Click on <guibutton>"Use external debugger"</guibutton> if you wish to use a different debugger, and enter the name of the debugger to use. See your debuggers documentation for help on how to run it.</para>
      <para>Selecting the internal debugger enables an additional set of options you can choose from:</para>
      <variablelist>
	<varlistentry>
	  <term>Display static members</term>
	  <listitem><para>Displaying static members makes <application>gdb</application> slower in producing data within KDE and Qt.  It may change the "signature" of data which <classname>Qstring</classname> and friends rely on. Check this option if you need to debug into these values.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Display mangled names</term>
	  <listitem><para>When displaying the disassembled code, you can select to see the method's mangled names. Non-mangled names are, however,  easier to read.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Try setting <abbrev>BP</abbrev>s on lib load</term>
	  <listitem><para>This will try to set pending breakpoints on loading a library. If <application>gdb</application> hasn't seen a library that will be loaded via "dlopen" then it will refuse to set a breakpoint in that code. We can get gdb to stop on a library load and hence try to set the pending breakpoints. See <link linkend="Shared-libraries-and-breakpoints">Shared libraries and breakpoints</link> for more details, and a "gotcha" relating to this behaviour. If you are not "dlopen"ing libs, leave this off.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Enable floating toolbar</term>
	  <listitem>
	    <para>This will allow you to use the floating toolbar to control the debugger, in addition to the menu and buttons. The toolbar is most useful for debugging GUI applications. For details see <link linkend="The-floating-toolbar">The floating toolbar</link>.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Enable separate terminal for application I/O</term>
	  <listitem><para>This allows you to enter terminal input when your application contains terminal input code (eg cin, fgets etc.). If you use terminal input in your app, then tick this option. Otherwise leave this off.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect1>

    <sect1 id="setting-paths">
      <title>Setting Paths </title>

      <para>On the paths tab you can enter the paths to your Qt 2.x and KDE 2 installations, as well as where to create new projects.</para>
      <para> To learn more about installing Qt 2.x / KDE 2 and configuring <application>KDevelop</application> for Qt 2.x and KDE 2 read the <ulink url="tutorial/index.html">KDE Application Tutorials</ulink>.</para>
      <para>The default location for <application>KDevelop</application> to create new projects, is in the user's home directory. If you want to change this behaviour you can enter the desired location into the default project path field.</para>
    </sect1>
  </chapter>

  <chapter id="questions-and-answers">
    <title>Questions and Answers</title>

    <para>This section addresses questions by users that were answered by the <application>KDevelop</application> Team or by their supporters on the <application>KDevelop</application> mailing list during experiences with the current versions of <application>KDevelop</application>, as well as bug reporting in general.</para>

    <sect1 id="bug-reporting">
      <title>Bug Reporting <indexterm><primary>Bug Reporting</primary></indexterm> </title>

      <para>Another innovation of <application>KDevelop</application> is the integrated bug-reporting system via email. If you experience a bug, you have the option to send the <application>KDevelop</application> development team a bug report either by your email client or by the bug-report dialog. All bug-reports are collected on the <application>KDevelop</application> 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 <application>KDevelop</application> for direct bug-reporting, choose "Bug Report" from the <guimenuitem>Help-menu</guimenuitem><indexterm><primary>Help-menu</primary></indexterm>. You are presented a report dialog that lets you enter all necessary information about the bug you found. After pressing <guibutton>"OK"</guibutton>, the dialog's contents are  sent automatically to the correct place.</para>
    </sect1>

    <sect1 id="where-to-get-information">
      <title>Where to get Information</title>

      <qandaset>
	<qandaentry>
	  <question><para>I have a question which is not addressed in the <abbrev>FAQ</abbrev> file, nor in the manuals of <application>KDevelop</application>. Where should I turn to?</para></question>
	  <answer><para>Send all requests that are regarding <application>KDevelop</application> to the <application>KDevelop</application> mailing list.  You can subscribe by sending an email with empty headers, and <userinput>"subscribe youremailaddress"</userinput> to <email>kdevelop-request@barney.cs.uni-potsdam.de</email>. All questions should go there and will be addressed there as well. If you stick to that, you will get the most help by the developers and all users having the same problems, as well as helping to keep the <abbrev>FAQ</abbrev> up to date.</para>
	    <para>The <application>KDevelop</application> Homepage <indexterm><primary>KDevelop Homepage</primary></indexterm> at <ulink url="http://www.kdevelop.org">http://www.kdevelop.org/</ulink> also contains a mailing-list <indexterm><primary>mailing-list</primary></indexterm> archive that allows you to browse the emails already sent by the subscribers.  You should look there first as most problems should have been addressed already by the team or other users.</para></answer></qandaentry></qandaset>
    </sect1>

    <sect1 id="library-and-system-problems">
      <title>Library and System Problems</title>
      
      <qandaset>
	<qandaentry>
	  <question><para>Wrong JPEG library version: library is 61, caller expects 62</para></question>
	  <answer><para>There are 2 possible fixes.</para>
	    <orderedlist><listitem>
		<para> When the kdelibs are installed it installs header files for the jpeg libraries, these are version 6.1, however most distributions (Redhat) use version 6.2 libraries. To fix this just remove <filename>jpeglib.h</filename>from <filename>/opt/kde/include</filename>. The pukka include file for version 6.2 should then be picked up. However looking at the  error message above it may be the other way round. In any case ensure  you only have one version of the header file, the library and that they are consistent.</para>
		<para>It is useful to use the <command>locate</command> command to verify that you have the correct version of a library and header files e.g.</para><screen>
<command>updatedb</command>
<command>locate libjpeg</command>
<command>locate jpeglib</command></screen>
	      </listitem>
	      <listitem>
		<para> You must recompiled kdesupport without jpeg library (<command>./configure <indexterm><primary>configure</primary></indexterm> <option>--with-libjpeg --with-libgif</option></command>).</para>
	      </listitem>
	    </orderedlist>
	  </answer>
	</qandaentry>
	<qandaentry>
	  <question><para>I get an error message that "AM_PROG_INSTALL is obsolete". What do I do?</para></question>
	  <answer><para>If this is what you're seeing:</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>then the workaround for <application>automake</application>-1.4/<application>automake</application>-2.13 users: Just run <command>aclocal</command> manually, then it will compile.</para></answer>
	</qandaentry>
	<qandaentry>
	  <question>
	    <para>What must I do, if <command>configure</command> <indexterm><primary>configure</primary></indexterm> said that I need <filename>giflib23</filename>.</para></question>
	  <answer><para>Try a newer snap of kdesupport, or maybe you have another giflib installed?</para></answer>
	</qandaentry>
	<qandaentry>
	  <question><para>How can I convert a <application>KDevelop</application> 0.2 project to a 0.3 one?</para></question>
	  <answer><para>Please change the <option>AC_OUTPUT</option> in the <filename>configure<indexterm><primary>configure</primary></indexterm>.in</filename> to a oneline version</para>
	    
	    <para>for example:</para>
<para>old version:</para>
<screen>
<userinput>AC_OUTPUT(Makefile \
kdevelop/kwrite/Makefile \
kdevelop/templates/Makefile
)</userinput>
</screen>
<para>new version:</para>
<screen>
<userinput>AC_OUTPUT(Makefile kdevelop/kwrite/Makefile kdevelop/templates/Makefile)</userinput>
</screen>

	  </answer>
	</qandaentry>
	<qandaentry>
	  <question><para> I get the following Linker <indexterm><primary>Linker</primary></indexterm> errors <indexterm><primary>errors</primary></indexterm> when using SuSE Linux with KDE 1.1, what do I have to do to get <application>KDevelop</application> linked ?</para>
	    <screen><computeroutput>
/usr/lib/libqt.so:
warning: multiple common of `QArrayT&lt;char&gt; type_info node'
ckdevelop.o: warning: previous common is here
ckdevelop.o: In function `CKDevelop::slotFileSaveAll(void)':
ckdevelop.o(.text+0x784): undefined reference to `kdebug(unsigned short,
unsigned short, char const *,...)'
ckdevelop.o(.text+0x839): undefined reference to `kdebug(unsigned short,
unsigned short, char const *,...)'
ckdevelop.o(.text+0x89d): undefined reference to `kdebug(unsigned short,
unsigned short, char const *,...)'
ckdevelop.o: In function `CKDevelop::slotFileSaveAs(void)':
ckdevelop.o(.text+0xd28): undefined reference to `kdebug(unsigned short,
unsigned short, char const *,...)'
ckdevelop.o: In function `CKDevelop::slotFileClose(void)':
ckdevelop.o(.text+0x1216): undefined reference to `kdebug(unsigned short,
unsigned short, char const *,...)'
ckdevelop.o(.text+0x1263): more undefined references to `kdebug(unsigned
short, unsigned short, char const     *,...)' follow  collect2: ld returned 1
exit status  make[2]: ***
[kdevelop] Error 1  make[2]: Leaving directory
'/home/LinuXDaten/Programme_Updates_Packete/KDE_Updates/Kdevelop_actual_snapshot/kdevelop-0.3/kdevelop'
make[1]: *** [all-recursive] Error 1  make[1]: Leaving directory
`/home/LinuXDaten/Programme_Updates_Packete/KDE_Updates/Kdevelop_actual_snapshot/kdevelop-0.3'
make: *** [all-recursive-am] Error 2</computeroutput>
</screen>
	  </question><answer><para>If you have the SuSE rpms of KDE-1.1, you must recompile the kdelibs without the patch commited by SuSE, and reinstall them, or get an updated rpm of the kdelibs from <ulink url="ftp://ftp.suse.com">ftp://ftp.suse.com</ulink></para>
	  </answer>
	</qandaentry>
      </qandaset>
    </sect1>

    <sect1 id="Usagee-questions">
      <title>Usage Questions</title>

      <qandaset>
	<qandaentry>
	  <question><para>I see the <application>KDevelop</application> does not allow for usage of the delete key (or backspace deleting when text is marked).</para></question>
	  <answer><para>Go to <menuchoice><guimenu>Options</guimenu><guimenuitem>Editor</guimenuitem></menuchoice> and make sure that "Delete on Input" is enabled, then backspace and delete will 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><indexterm><primary>Makefile.am</primary></indexterm> files then, and if you make a "Rebuild All" (<command>./configure</command> <indexterm><primary>configure</primary></indexterm> updates the <filename>Makefile</filename><indexterm><primary>Makefile</primary></indexterm> files), your new added files will be included as well.</para></answer>
	</qandaentry>
	<qandaentry>
	  <question><para>If I removed a file, I get some weird Linker <indexterm><primary>Linker</primary></indexterm> messages. What is wrong with my project?</para></question>
	  <answer><para>If the removed file is a header file, that is automatically processed by <application>automoc</application> (running the Qt-Meta-Object-Compiler automatically on all headers), your removed header is still present as a moc-generated <filename>*.moc.cpp</filename> file and compiled.  Remove the appropriate <filename>*.moc.cpp</filename> file and rebuild the project.</para></answer>
	</qandaentry>
	<qandaentry>
	  <question><para> Configure complains about not being able to compile a small KDE application. Examining <filename>config.log</filename> reveals that it can't find the library <filename>libXext</filename>.</para></question>
	  <answer><para>Install the package xdevel</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 <application>KDevelop</application> to my project options, everything is ok, but when I distribute my package, the <option>-D</option> options set in <application>KDevelop</application> 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. Here, you have to enter somewhere at the beginning:</para>
	    
<screen><userinput>
CXXFLAGS=$(CXXFLAGS) " -DYOURDEFINE"
AC_SUBST(CXXFLAGS)</userinput></screen>
	  </answer>
	</qandaentry>
	<qandaentry>
	  <question><para>I´m already running a KDE 2 snapshot and I want to use <application>KDevelop</application> under KDE 2. What is the best way to do this ?</para></question>
	  <answer><para>As <application>KDevelop</application> for KDE 2 is currently under development, you should consider using the current stable 1.x release of <application>KDevelop</application> for production usage. Running <application>KDevelop</application> 1.x under KDE 2 can be done by creating a shell-script:</para>
	    <para>
<informalexample><screen>
#/bin/bash
QTDIR=/usr/lib/qt-1.44 export QTDIR
KDEDIR=/opt/kde export KDEDIR
exec /opt/kde/bin/kdevelop</screen></informalexample></para>

	    <para>Save this file as e.g. <filename>kdevelop1</filename> and set this file to executable with</para>
	    
	    <para><command>chmod 755 kdevelop1</command>
</para>
	    
	    <para>Then you can run <application>KDevelop</application> 1.x under KDE 2 by calling <command>kdevelop1</command>.
For developing KDE 2 applications with <application>KDevelop</application> 1.x you have to set the correct path in the <application>KDevelop</application> Setup even if you´re running <application>KDevelop</application> under KDE 2.</para>
	  </answer>
	</qandaentry>
      </qandaset>
    </sect1>
  </chapter>

  <chapter id="authors">
    <title>Authors</title>
    <sect1 id="acknowledgement">
      <title>Authors</title>
      <sect2 id="authors-main">
      <title>Main Developers</title>
      <itemizedlist spacing="compact">
	<listitem><para>Sandy Meier - Maintainer, Development co-ordinator, and homepage provider  <email>smeier@kdevelop.de</email></para><para>Main development of: frame structure, <abbrev>IDE</abbrev> look'n feel, project management.</para></listitem>
	<listitem><para>Stefan Heidrich <email>sheidric@rz.uni-potsdam.de</email></para><para>Main development of: <application>kappwiz</application>; <indexterm><primary>KAppWizard</primary></indexterm>, printing <indexterm><primary>printing</primary></indexterm> functionality</para></listitem>
	<listitem><para>Ralf Nolden <email>rnolden@kdevelop.de</email></para><para>Main development of: <application>KDevelop</application>&lt;-&gt;Dialog Editor interface, configuration functionality, online-help and handbooks</para></listitem>
	<listitem><para>Jonas Nordin <email>jonas.nordin@cenacle.se</email></para><para>Main development of: Classviewer and -parser</para></listitem>
	<listitem><para>Pascal Krahmer <email>pascal@beast.de</email></para><para>Main development of: Dialog Editor</para></listitem>
	<listitem><para>Bernd Gehrmann <email>bernd@physik.hu-berlin.de</email></para><para>Main development of: Grep Dialog, <abbrev>CVS</abbrev> integration, new <guilabel>DOC</guilabel> tree</para></listitem>
	<listitem><para>Jörgen Olsson <email>jorgen@cenacle.net</email></para><para>Main development of: Visual Classtree</para></listitem>
	<listitem><para>Stefan Bartel <email>bartel@rz.uni-potsdam.de</email></para><para>Main development of: Real File Viewer</para></listitem>
	<listitem><para>Walter Tasin <email>tasin@kdevelop.de</email></para><para>Main development of: Enhancements and Bug fixing</para></listitem>
      <listitem><para>John Birch <email>jbb@ihug.co.nz</email></para><para>Main development of: Integrated Debugger</para></listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="translation">
    <title>Translation Co-ordination</title>
	<itemizedlist>
	<listitem><para>Martin Piskernig <email>mpiskernig@kdevelop.de</email></para>
</listitem>
</itemizedlist>

      
      
    </sect2>
	    <sect2 id="author-startlogo">
      <title>Startlogo</title>
      <itemizedlist>
	<listitem><para><application>KDevelop</application> 1.0: Jacek Wojdel <email>wojdel@kbs.twi.tudelft.nl</email></para></listitem>
    	<listitem><para><application>KDevelop</application> 1.1, 1.2: Ralph Kocher <email>RKocher@t-online.de</email></para>
	</listitem>
      </itemizedlist>
      </sect2>
    <sect2 id="author-additions-patches-bugfixes">
      <title>Additions, patches, and bugfixes</title>
      <itemizedlist>
	<listitem><para>Pau Estalella Fernandez <email>pef@upcnet.upc.es</email></para></listitem>
	<listitem><para>Jost Schenk <email>jost@schenk.de</email></para></listitem>
	<listitem><para>David Barth <email>dbarth@videotron.ca</email></para></listitem>
	<listitem><para>Matthias Hipp <email>matthias.hipp@gmx.de</email></para></listitem>
	<listitem><para>Martin Piskernig <email>martin.piskernig@stuwo.at</email></para></listitem>
	<listitem><para>Jochen Wilhelmy <email>digisnap@cs.tu-berlin.de</email></para></listitem>
	<listitem><para>Matthias Hoelzer-Kluepfel <email>mh@caldera.de</email></para></listitem>
	<listitem><para>Matt Koss <email>koss@napri.sk</email></para></listitem>
	<listitem><para>Torsten Uhlmann <email>tulmann@debis.com</email></para></listitem>
	<listitem><para>Stefan Mars <email>mars@lysator.liu.se</email></para></listitem>
	<listitem><para>Nikolay Liber <email>nikolay_liber@mail.ru</email></para></listitem>
	<listitem><para>Gordon Tyler <email>gtyler@iafrica.com</email></para></listitem>
	<listitem><para>Huy Cuong Nguyen <email>huyc@iquebec.com</email></para></listitem>
	<listitem><para>John R. Zedlewski <email>zedlwski@princeton.edu</email></para></listitem>
	<listitem><para>Stephan Uhlmann <email>suhlmann@gmx.de</email></para></listitem>
	<listitem><para>Charles Egan <email>cega@oklahoma.net</email></para></listitem>
	<listitem><para>Andrew Morton <email>morton@nortelnetworks.com</email></para></listitem>
	<listitem><para>p_george <email>p_george@club-internet.fr</email></para></listitem>
	<listitem><para>Lubos Lunak <email>l.lunak@sh.cvut.cz</email></para></listitem>
	<listitem><para>Armin L. Schneider <email>armin@uumail.de.uu.net</email></para></listitem>
	<listitem><para>Martin Spirk <email>spirk@kla.pvt.cz</email></para></listitem>
	<listitem><para>Ralf Palsa <email>rpalsa@eso.org</email></para></listitem>
	<listitem><para>Richard Dale <email>richard_dale@tipitina.demon.co.uk</email></para></listitem>
	<listitem><para>Holger Schurig <email>holger@holger.om.org</email></para></listitem>
	<listitem><para>Dag Andersen <email>dandersen@c2i.net</email></para></listitem>
	<listitem><para>Alexis Mikhailov <email>alexis@abc.cap.ru</email></para></listitem>
	<listitem><para>Nils Ulltveit-Moe <email>nils.ulltveit-moe@hia.no</email></para></listitem>
	<listitem><para>Nick Hudson <email>nick@nthcliff.demon.co.uk</email></para></listitem>
	<listitem><para>R. Imura <email>imura@cs.titech.ac.jp</email></para></listitem>
	<listitem><para>Falk Brettschneider <email>gigafalk@yahoo.com</email></para></listitem>
	<listitem><para>Ralf Funken <email>rfunken@kdevelop.de</email></para></listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="authors-other-contributions">
      <title>Other Contributions</title>
      <para>Kdevelop contains sourcecode from the following applications:</para>
      <itemizedlist>
	<listitem><para><application>KWrite 0.98</application> &copy; by Jochen Wilhelmy <email>digisnaps@cs.tu-berlin.de</email></para></listitem>
	<listitem><para><application>KDE Help</application> &copy; by Martin R. Jones <email>mjones@kde.org</email></para></listitem>
	<listitem><para><application>KSwallow</application> &copy; by Matthias Hoelzer <email>hoelzer@physik.uni-wuerzburg.de</email></para></listitem>
	<listitem><para><application>kcmlocale</application> &copy; by Matthias Hoelzer <email>hoelzer@physik.uni-wuerzburg.de</email></para></listitem>
	
      </itemizedlist>
      <para>Proofread and converted to Docbook SGML by Lauri Watts <email>vampyr@atconnex.net</email></para>
    </sect2>
    </sect1>
  </chapter>
  
  <chapter id="thanks">
    <title>Thanks</title>

    <para>We would like to express special thanks to all of our family members and friends, who supported us in several ways to let us construct and improve <application>KDevelop</application>.</para>

    <para>Further, we thank Jochen Wilhelmy for offering his program <application>KWrite</application>, and his help on integrating it into <application>KDevelop</application>.</para>
    
    <para>Thanks also to the KDE team, and Stephan Kulow, who gave us the possibility to work on <application>KDevelop</application> via CVS</para>
    
    <para>We hope that our free work on this product will lead to a better acceptance of Free Software and it's development. Without the help and idealism of many, the <application>KDevelop</application> IDE would never have been realized in such a short period of time, and we're proud that so many users already have reported good experiences and brought <application>KDevelop</application> to it's destiny: helping free software programmers to build a better world where users have the freedom of choice. </para>
  </chapter>
  
  <chapter id="copyright">
<title>Copyright </title>

<para>
<application>KDevelop</application> Copyright 1998, 1999, 2000 The <application>KDevelop</application> Team.</para>
<para>
This program is free software; you can redistribute it and/or modify it under the terms of the <ulink url="common/gpl-licence.html">GNU General Public License</ulink> as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
</para><para>
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
</para><para>
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
</para>

</chapter>
<![ %addindex; [ &docindex; ]]>
</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
sgml-general-insert-case: lower
End:
-->
