# 8.4. Editing a Project

After you created a new project with the KAppWizard , the usual task is to extend the project by editing the already created sources and adding classes , pixmaps , pictures and whatelse you project needs. Now, editing a project means that you can change the default project after its generation by menus and dialogs according to your needs. The next section therefore describes how you can add existing files and classes as well as creating new files. This is needed for building your project, but this won't help you for the installation process by the end-user. Therefore, section Setting Project File Options describes how to set File Properties especially for additional files that you want make to install, like documentation or pixmaps . Another part in project maintaining is adding translations for applications that support internationalization, which is described in Adding Translations.

Extending the Project Documentation covers questions on how to create a good set of documentation for online help enabling the end-user to help himself in case of troubles as well as how to use your product.

Finally, Project Hacking describes how you can eventually work around the KDevelop project management in special cases.

## 8.4.1. Adding and Removing Files and Classes

Adding a new file is often used when you think that you should separate your class implementation file into several ones. Then you need to create an new file which will contain the part of the class implementation you want to move. You can do this by choosing "New" from the "File"-menu , opening the "New File " dialog. This enables you to specify the file-type, name and the location. When entering the filename, KDevelop automatically enters the extension for you, but you can as well change the extensions towards your own preferences. Further, 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. Mind that this doesn't cover the installation destination; this has to be configured later by setting the file preferences.

After the new file has been created, the project file will be updated as well as the according Makefile.am 's. To add a complete class to your project, you can construct a new class with the Classgenerator which is invoked by "New Class " from the Project-menu.

In case you have an existing project and you want to add certain classes that you want to re-use in your project, select "Add File(s) to Project..." from the "Project"-menu . Select "Add existing files", 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 "Make" after adding sources; then your added files will be included in the build-process. In case you want to add e.g. pixmaps that have to be installed by the end-user, you should update the File Properties for the added file and specify the installation path (see Setting Project File Options

To add a file to the project that is already in the project directory, go to the RFV , where all project-included files are displayed by their project status by a red ! over the file icon. Select the file you want to add to the project (which has a normal file icon) and press the right mouse button to get the popup-menu. Then select "Add".

Files can also be removed from your project. This could be needed in cases where you don't want to use pre-generated files that are already given by the KAppWizard . To remove a file, you have additionally the option between removing a file from the project or delete it completely. To remove a file from the project, select the file in the LFV or the RFV , press the right mouse button and select "remove". To delete a file, select "delete physically".

## 8.4.2. Setting Project File Options

The file properties dialog can be accessed via the project menu or within the LFV by a right mouseclick. It shows the project files in groups as they are sorted in the LFV and displays the file properties like 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 make install command. It is important for documentation files as well as pixmaps to specify the location where the files should go when the project is build and installed by end users, so you have to set up those locations. For standard KDE location macros you should look in your Makefile.am where the location macros are specified.

## 8.4.3. Adding Translations

As KDE allows configuring your desktop and the behavior of your applications, you also have the option to choose the language that your application uses, in regards of the use of online-documentation as well as the application's look. For documentation files, this seems a trivial task. You would add a subdirectory labeled by the desired language, e.g. `de` for German, to the `docs` directory of your project and copy the english documentation into that directory. Then you would generate the documentation and set all project file options for the installation directories. Then you could start translating the SGML file to your desired language and regenerate the documentation; then you're done. For the application, this seems a bit more difficult for the programmer. Now, we want to explain how to enable internationalization support for your application and how to add the languages you want to support.

First, you have to enclose all visible strings of your application that appear in bars or dialogs with the `i18n ()` macro. This macro is a replacement for the function `klocale->translate()` of the KLocale class and much easier to use. As this macro is declared in the `kapp.h` include file, you have to add `&#;include &<;kapp.h&>;` to the source file or the class declaration file of the class that makes use of the macro. Also it should be mentioned, that although `i18n ()` 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 get stored in the application's translation file (&<;YourApp&>;.pot in the /po subdirectory). This task is done by the program xgettext, and to do this, you would enter `make messages` in your project directory containing the sources. As xgettext depends on the `i18n ()` macro, the original function won't do the job.

For translations themselves, you first have to create the message file containing all strings that are used in your sources with the `i18n ()` macro. This can be done by choosing "Make messages and merge" from the Build-menu. Then you have to add the languages that your application wants to support. Therefore, select "Add Translation File" from the Project-menu. This opens a language selection dialog. Select the language and press OK. This will build the ASCII 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 . Those have to be filled with the according translations of your language.

You could think about writing the translations by hand, which can also be done. But the KDE-SDK offers the use of the program KTranslator , which ready the already existing files from other applications installed on the system, so you can reuse already translated strings to support your language.

To access KTranslator , the easiest way is selecting a &<;language&>;.po file in the /po directory either in the LFV or in the RFV . This opens KTranslator and lets you do the translating easily. Mind that you have to set up KTranslator 's properties yourself to include the author name and the language as well as the destination file. KTranslator by default only opens your translation file.

For all translation files, `make` uses the program `msgfmt` to format your message files to use with the binary, but you don't have to take care for that, as well as specifying the destination directory for installing the translation files; this is all done by KDevelop automatically.

For more information about internationalization support, see \|\|; a lot of people are 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 El editor de diálogos and The KDevelop Programming Handbook where questions about internationalization are covered again.

## 8.4.4. Extending the Project Documentation

All projects created with KDevelop contain a pre-configured documentation, which already contains standard chapters for installation, project name and version as well as the author name and email-address. As KDevelop uses SGML -templates, it's very easy to extend the documentation to a full descriptive helpsystem. The only thing you have to do is editing the SGML file, placed in docs/en as index.sgml. The reference documentation included with your sgml-tools package can be added to the Helpbrowser and allow you direct access to special tags as well as a short description of how to extend the documentation. SGML has a lot of advantages, whereas KDE makes wide use by this documentation type with the additional KSgml2Html tool. This creates the typical KDE -style documentation and makes it look nicer. Anyway, the sgmltools alone are enough to produce a html output that is already included in your application. To create the documents using KSgml2Html , install the tool and run "Make User-Manual" from the Build-menu. The Documentation Browser allows a direct controlling of the output by selecting "Project User-Manual" from the Help-menu or the according icon in the DOC -tree. Then you can browse the documentation online in KDevelop and have a better overview by the output over errors that result in missing tags.

Now, while extending the documentation, you can't avoid that additional files are produced that have to be included into the project as each `sect`-tag creates a new HTML file. The output generated by the KAppWizard is already included in the project, so you don't have to care for their installation path. What you have to watch out for is any index-xx.html file, where xx is higher than 6 (as the first six pages are already included in the project). After generating the documentation, switch to the RFV and browse to your documentation directory. Press the right mouse button over the files to add and select "Add". Further, KSgml2Html adds the KDE logo to the documentation directory. This file, `logotp3.gif`, has to be added to the project as well. Then you have to select the "File Properties" either from the Project menu or by the popup menu in the file-viewers. The easiest way to set the installation path is to select a documentation file already set up for installation such as `index.html`. You see that `Install` is checked and the Installdir+filename already contains the destination. Mark the Installdir and enter Ctrl+C to copy the installation path to the clipboard. Then select the file you want to specify for installation. Enable `Install`, this will enable the installdir-entry field, already containing the filename. Place the cursor in front of the filename and enter Ctrl+V to insert the clipboard contents (which was the installation path copied before). This is the fastest way to specify the installation path. For more options about specifying installation destinations, see The KDevelop Programming Handbook.

## 8.4.5. Project Hacking

When working with a project, you should never edit the project file by hand. This will prevent KDevelop from loading your project correctly under certain circumstances, as well as changes will not result in updating the Makefile s. To change any settings for your project, you have to use the given menu entries like e.g. for adding files or setting file properties. For experts that are not comfortable with certain options for e.g. the Linker or need additional project configuration, you should work yourself into the Makefile.am macros and add all changes in the Makefile.am 's after the section separated with the entry "KDevelop write area". As the GNU-tools are using the commands at the end of all macro files, you can overwrite KDevelop's settings with this. Mind that this will prevent using KDevelop for any changes related to project configuration.