# The &appname; Handbook

## Introduction

&appname; is a collection of software and Python packages to support the creation and installation of TDE applications.

## Installation & Distutils support

C++ projects on TDE traditionally use autoconf, automake and libtool to handle the building and installation. These tools and difficult to use, even for experianced developers.

Fortunately Python has a its own system for building and installing modules and software. Distutils is a standard Python package and comes with every Python installation. &appname; builds on Distutils with extensions tailored for handling TDE programs.

A typical TDE program comes not only with the program itself but also extra files such as a manual written in Docbook format, translation files, icons, images and other auxiliary data files. &appname; provides support for handling all these other files types.

### Using Distutils with TDE programs

It is advised that you first read the standard Distutils documentation to learn about how it works. &appname; adds some TDE specific extensions which are documented below.

Distutils is based around writing a `setup.py` file which then uses the distutils package To use the TDE extensions, the first thing you need to do in your `setup.py` file is include the tdedistutils package.

    #!/usr/bin/env python
    # Setup.py file for MyTDEApplication

    import tdedistutils

You need to call the setup() function from tdedistutils with all of the configuration information about your application, much like the standard setup() from distutils.

    tdedistutils.setup(name="pytdeextensions",
        version="0.1.0",
        author="Simon Edwards",
        author_email="simon@simonzone.com",
        url="http://www.simonzone.com/software/pykdeextensions/",
        min_kde_version = "3.0.0",
        min_tqt_version = "3.0.0",
        license = "LGPL" )

min_kde_version and min_tqt_version specify the minimum versions of the TQt library and TDE needed to install and run the software. These requirements are checked during install.

The other arguments shown here are standard distutils.setup() arguments.

### Application data files

Each TDE application as a data directory of it's own for storing any extra data files it may need to run.

Data files are specified using the the application_data argument for setup(). application_data is a list of files to install.

        application_data = ['extracode.py', ('pics', ['pics/warning.png'])]

You can simply specify the name of each file as a string and they will be installed directly in the application data directory. Or you can use a tuple containing the name of the sub-directory under the application data directory to install into, and as the second tuple item, the list of files to install into the given sub-directory.

Since most large Python programs are broken up into multiple source files it is recommended that all of the Python files that comprise your application be installed into the application directory. This helps eliminate problems with the Python module path and the interpreter not being able find the correct file to import.

Even with all of the python files in the Application data directory, it is still desirable to have your application's "executables" available in TDE's `bin` directory. &appname; provides an easy way for creating symbolic links from the "bin" directory to scripts in the application directory.

        executable_links = [('myapplication','myapplication.py'), ('myapplicationgui','myapplicationgui.py')]

This example specifies an executable symbolic link `myapplication` that points to the `myapplication.py` script in the application data directory.

### Uninstall command

Standard Distutils does not feature an uninstall command. &appname; does and it can be easily invoked with:

    python setup.py uninstall

It is quite basic. The install writes the list of files it installed to the file `install_log.txt`. The uninstall command simply reads this file and removes the files and directories that are listed within.

## Manuals & Docbook files

Docbook is an XML based file format for writing manuals and books. More information about using Docbook to write manuals and documentation using Docbook is here. Manuals are written in the Docbook format, but need to be converted into HTML when installed and made available for the TDE Help Center.

Docbooks files and images are usually organised under a `doc` directory which is then further divided by two letter language code. For example `doc/en`, `doc/nl`, en `doc/fr`. The Docbook files themselves are named `index.docbook`

By using the docbooks argument to setup() in your `setup.py`, you can specify the directories containing docbook files. You also need to specify the language used in that directory.

        docbooks = [ ('doc/en','en'), ('doc/nl','nl'), ('doc/fr','fr') ]

The argument to docbooks is a list of tuples. The first item of a tuple is the relative path to a docbook directory. The second item is the two letter language code.

Docbook files specified this way will automatically be converted to HTML during install.

## Run-time integration with TQt-Designer

Qt-Designer is a graphical application used for designing user interfaces. It creates `.ui` files. These files need to be converted into Python classes before they can be used in a Python application. This can be manually done using the `pyuic` command from the shell. But it is a lot more convenient to let &appname; to this automatically for you. All you need to do is import the tqtdesigner or tdedesigner module, depending on whether your application is pure TQt or uses TDE, and then you can import your user interface files as though they were normal Python files.

    #!/usr/bin/env python
    from tdeui import *

    import tdedesigner     # This module lets us import .ui file directly.
    from MyWindow import * # Loads MyWindow.ui

    # Subclass the TQt-designer form.
    class MyWindowCode(MyWindow):
        # Implement extra functionality and methods.

The tdedesigner/tqtdesigner module converts `.ui` on demand to `.py` files.

## Internationalization & translation

i18n (an abbreviation of internationalization) is the process of translating the user interface and documentation of a piece of software into another language. i18n.kde.org is the central information point for the effort to translate TDE software into other languages.

Translation of the user interface an application is done using `.pot` files and `.po` files. A `.pot` file, is generated from the source code of the program itself, and contains all of the strings / fragments of text, that are used in the program.

Before a string in a program is include in the `.pot` file, it needs to be marked with the `i18n()`.

    #!/usr/bin/env python
    from kdecode import *

            ...
            mylabel = QLabel(i18n("Select new directory:"))
            ...

The `i18n()` is part of the kdecode package and needs to be imported.

&appname; provides support for generating `.pot` files and managing and updating `.po` files.

By using the i18n argument to setup() in your `setup.py`, you can specify the directory that should contain the `.pot` and `.po` files. The argument for i18n is a tuple. The first item is the relative path to the directory where the translation files should be stored. The second item is a list of directories that should be scanned for Python source files containing translatable strings.

        i18n = ('po',['.','mymodule'])

Once your `setup.py` is configured, use this command in the shell to generate the `.pot` file.

    python setup.py update_messages

This command also updates any already existing `.po` files with any new messages.

&appname; also handles installing translation files and converting `.po` files into the special binary format needed by the application at runtime.

## Trinity Control Center Modules

&appname; can also help create modules for the Trinity Control Center. C++ glue code is needed when writing in module in Python. Fortunately &appname; can generate this glue for you automatically.

The best way to start learning about creating modules is to read the TDEConfig Module HOWTO. It is written for C++, but the concepts are the same for Python.

In your `setup.py` file you can specify the list of kcontrol modules that need to be installed.

        kcontrol_modules = [ ('src/kcontrol_module.desktop','kcontrol_module.py')] )

This is just a list of tuples. The first item is name of the `.desktop` file that you've made for your module. The second item is the name of the Python program to run when the user views the module in kcontrol. This program is expected to be in the application's data files directory.

The KControl Module Guidelines provides useful information about how to design a KControl module that fits into the rest of TDE.

&appname; typically installs the `.desktop` file into the `/usr/share/applications/tde/` directory. This is normally enough to make the module appear in the Trinity Control Center. But for some distributions, most notably Mandriva but probably others too, this isn't enough. Mandriva in particular uses the Debian menu system for managing the TDE menu and also for KControl modules. In order to get a module to appear in the kcontrol it is best to createa a `.menu` file and copy it into `/usr/lib/menu`, and then use `update-menus` as root to update all of the menus and the list of kcontrol modules.

Right now there is no support for "module-testing" or "X-TDE-Test-Module=true" features in `.desktop` files.

## TDEIO Slaves

&appname; can be used for the creation of tdeio-slaves. &appname; handles the C++ glue code needed for making tdeioslaves in Python. developer.kde.org has some documentation about TDEIO-slaves aimed at C++ programmers.

In your `setup.py` file you can specify the list of tdeioslaves that need to be installed.

        tdeioslaves = [ ('src/tdeioslave.protocol','tdeioslave.py')] )

This is just a list of tuples. The first item is name of the `.protocol` file that you've made for your tdeio-slave. The second item is the name of the Python program to run when the user views the module in kcontrol. This program is expected to be in the application's data files directory.

## Application templates

The `app_templates` directory contains a number of application templates. An application template is just a collection of files in a directory structure that should be copied and used as starting point when developing a new application. An application template typically contains default documentation files, icons, source file and `setup.py` file which can later be modified.

Every application template has a number of files in common. They are described below.

`AUTHORS`

- Lists the authors of this software.

`ChangeLog`

- An itemised log or list of changes to the software.

`COPYING`

- A copy of the GNU GPL, explaining the terms under which this software may be distributed. This file does not need to be changed.

`INSTALL`

- Instructions for installing the software.

`MANIFEST.in`

`NEWS`

- News about what is new in the current version of this software.

`README`

- Important instructions and information that the user should read first.

`setup.py`

- .

`TODO`

- List of features and work that may be available in a future version of the software.

`po/`

- This directory is initially empty. It is used for `.pot` and `.po` translation files.

`doc/`

- This directory is initially empty. It is used for holding the directores for the different langauge version of the manual.

`doc/en`

- This directory for the english version of the manual.

`doc/en/index.docbook`

- The english manual in docbook format. The default is a template which can then be filled in.

`src`

- This directory containing the source code for the software. The default contents of this directory depends on the particular application template.

### Simple TDE utility template

The `kdeutility` application template is a simple utility that uses an interface designed in TQt-Designer. It doesn't have a menubar or toolbar.

### TDE application template

The `kdeapp` application template is an application with menubar, toolbar and separated document and view classes. The menubar and toolbars are defined using XML.

### Kcontrol Module Application Template

The `kcontrol_module` application template is a simple module for the Trinity Control Center. The module can also be run as a separate application outside of KControl to ease development and debugging.

### TDEIO-slave Application Template

The `tdeioslave` application template is a simple TDEIO-slave that implements a simple RAM disk. Once installed it can be accessed using tdeioslave:/ in konqueror. It is initially empty. Files and directories can be made and deposited. `tdeioslave.py` contains more information and comments.

Note that the TDEIO subsystem usually creates multiple running instances of a tdeio-slave backend. For the application template, files and directories are specific to each particular backend instance. When using konqueror the same instance will be used, but if you try to access tdeioslave:/ from a different process a new (empty!) instance will be craeted. This can be confusing! Be aware.

## Credits and License

&appname;

Program copyright 2005 Simon Edwards simon@simonzone.com

Contributors:

- Konqui the KDE Dragon konqui@kde.org

- Tux the Linux Penguin tux@linux.org

Documentation copyright 2005 Simon Edwards simon@simonzone.com

&underFDL;
&documentation.index;