# Tutoriels Applications KDE

Le Manuel Tutoriels Applications KDE pour l'Environnement de Développement Intégré KDevelop
Ralf
Nolden

    Ralf.Nolden@post.rwth-aachen.de

François-Xavier
Duranceau
Traducteur

    duranceau@kde.org

L'Équipe KDevelop
Version 0.1, Lun 21 Juin 1999

Le Manuel Tutoriels Applications KDE pour l'Environnement de Développement Intégré est un ensemble de tutoriels sur comment créer des applications KDE par l'exemple et décrit comment construire les exemples du tutoriel inclus avec la bibliothèque Qt. Ce manuel fait partie de l'Environnement de Développement Intégré KDevelop et est donc distribué sous la Licence GPL du GNU ; consultez le Copyright pour plus d'informations.

The kdesu Configuration Manual

KDE
su

## Introduction

Puisque KDE est actuellement en train de devenir un standard pour les bureaux des Systèmes Unix, de plus en plus de développeurs veulent tirer parti de l'excellente API incluse dans le projet KDE pour créer de nouvelles applications ayant une interface graphique (GUI), et utiliser facilement les classes fournies par Qt/KDE. Le projet KDevelop essaie donc de fournir un EDI qui permet aux développeurs de créer et d'étendre rapidement leurs applications basées sur KDE. Comme les néophytes ont toujours du mal à commencer, ce manuel essaie d'expliquer certains aspects de la création d'applications pour KDE. Il décrit comment créer des applications KDE par l'exemple et des applications fonctionnelles avec l'échantillon de code inclus dans la bibliothèque Qt et l'EDI KDevelop.

Le chapitre suivant expliquera donc comment créer, avec KDevelop, un projet qui est déjà une application complète. Ensuite, nous parcourrons la documentation en ligne de Qt qui contient les sources des exemples d'utilisation de la bibliothèque Qt.

Cela vous donnera un premier aperçu des fonctions de la bibliothèque Qt et comment utiliser les classes fournies avec ; Qt est le point de départ car KDE est bâti au-dessus des classes de la bibliothèque Qt et les applications KDE en font une utilisation intensive.

Ensuite, nous traiterons la création d'une mini-application KDE avec l'assistant d'application de KDevelop. A partir de l'architecture minimale fournie, nous créerons une application KDE exemple qui utilisera les bibliothèques KDE et nous expliquerons en détail les différentes parties de l'application.

L'Équipe KDevelop vous souhaite un bon apprentissage de KDE et Qt avec ce manuel et espère qu'il vous permettra de devenir un programmeur supplémentaire contribuant au projet KDE.

## Ce que vous devriez déjà savoir

Ce manuel nécessite une connaissance de base du langage de programmation C++ pour comprendre les exemples de code et leurs fonctionnalités. De plus, nous supposons que vous avez lu Le Manuel d'Utilisation de KDevelop ainsi que Le Manuel de Programmation de KDevelop et que vous savez comment fonctionne globalement l'EDI KDevelop et ce que sont les projets générés.

## Pour Commencer

Pour commencer signifie que vous devez avoir installé et configuré KDevelop pour qu'il fonctionne correctement. Assurez-vous que vous avez accès à la documentation de référence de Qt en ligne par le menu "Aide" ou le manuel correspondant dans l'arborescence de documentation. Lorsque vous regarderez la première page de la documentation de Qt, vous verrez qu'elle contient un lien vers les sections "Tutorials" et "Examples". Sous "Tutorials", vous trouverez une introduction en 14 étapes à l'utilisation de la bibliothèque Qt pour construire des applications. Par ailleurs, "Examples" vous conduira à une liste d'exemples de programmes inclus dans Qt et pris comme référence d'exemple d'utilisation de certaines classes. Maintenant, si vous débutez complètement, vous devriez vous sentir à l'aise avec la philosophie de Qt, à savoir fournir une bibliothèque qui offre :

- une classe d'application de base (`QApplication`)

- une bibliothèque de widgets pour les interfaces graphiques utilisateur

- un ensemble de classes supplémentaires facilitant la gestion des fichiers, du graphisme et des données

- un mécanisme signal-slot pour la communication entre objets

- la gestion des événements pas des boucles d'événements et des méthodes virtuelles

Si cela ne vous dit rien, vous devriez découvrir la bibliothèque Qt dans Le Manuel de Programmation de KDevelop où les bases d'une application Qt sont décrites en détail. Vous y trouverez aussi une introduction sur la différence entre une application Qt et une application KDE, ce qui n'est pas vraiment la première étape dans le tutoriel Qt.

Commencer par apprendre Qt devrait aussi être un bon début pour la programmation d'applications KDE. Nous allons donc créer un projet qui aboutira aux applications du tutoriel après édition.

Pour cela, commencez par lancer KDevelop et sélectionner "Projet" - "Nouveau" dans la barre de menus. L'assistant d'application s'ouvre et vouz devez sélectionner le type du projet que vous voulez construire. Pour les applications Qt, vous choisiriez Application Qt mais nous allons utiliser le type de projet mini-application KDE pour construire nos exemples. La raison est simple : les tutoriels de Qt ne contiennent pas beaucoup de code et en choisissant Application Qt dans l'assistant d'application, vous auriez à effectuer beaucoup de modifications sur le code fourni pour créer les "vrais" exemples.

Et comme la mini-application KDE n'est constituée que d'une fenêtre principale et vérifie la bibliothèque Qt et les fichiers d'en-tête, cela conviendra parfaitement à nos besoins et ne nécessitera pas trop de modifications.

Lorsque vous passez à la page suivante de l'assistant, vous devez saisir les informations spécifiques au projet. Vous pouvez laisser telles quelles les informations supplémentaires spécifiques à KDE comme la mini-icône, l'icône principale, la documentation, etc. Nous remplissons uniquement les informations qui seront utiles à la création d'une base adéquate pour les tutoriels. Comme la structure des étapes du tutoriel construit l'étape suivante en partant du code de l'étape précédente, nous pouvons commencer avec `MyWidget`> comme nom du projet. Cela nous construira déjà la classe de base requise au chapitre 4 donc nous n'aurons plus à nous en préoccuper . Comme nous voulons débuter avec la première étape du tutoriel, nous utiliserons '1' comme numéro de projet et nous l'augmenterons plus tard en passant à l'étape suivante.

Ensuite, remplissez les autres informations requises telles que votre nom, votre adresse électronique et le répertoire du projet. C'est tout ce dont nous avons besoin et nous pouvons sauter à la page suivante. Insérez ici votre en-tête pour les fichiers d'en-tête du projet ou utilisez l'exemple donné. De même pour la quatrième page où vous devez définir l'en-tête des fichiers sources. Enfin, vous pouvez passer à la dernière page où vous devez cliquer sur le bouton "Créer" pour construire le projet. Si le bouton est grisé, recommencez depuis la première page et assurez-vous que vous n'avez pas oublié d'insérer une information nécessaire.

Si tout s'est bien passé, le projet a été créé et la fenêtre des messages de l'assistant d'application doit contenir "PRET" sur la dernière ligne. Sélectionnez "Quitter" pour fermer l'assistant.

Si vous regardez l'arborescence sur la gauche, vous verrez que le projet contient déjà une classe "MyWidget" - parce que nous avons choisi ceci comme nom de l'application. En ouvrant "Fonctions" dans le dossier "Globals" du visualiseur de classes, vous verrez que l'application contient déjà une fonction `main()`> où l'exécution commencera.

L'application est déjà définie. Vous pourriez faire un "Exécuter" ou "Construire" mais comme nous voulons créer les applications du tutoriel, nous pouvons nous lancer et modifier d'abord le code pour créer nos applications exemples - ce que nous ferons à la prochaine étape.

## Construction des Tutoriels Qt

## Étape 1 : Hello World!

Comme l'explique le chapitre précédent, nous avons créé un projet appelé `MyWidget`> - si nous regardons à la première page du tutoriel de la documentation de Qt, nous voyons que la première application utilise uniquement la fonction `main()`>. Il nous suffit donc de modifier la fonction `main()`> de notre projet généré pour franchir la première étape du tutoriel.

Pour accéder à la fonction `main()`>, sélectionnez-la dans le dossier "Globals" du visualiseur de classes qui contient un sous-dossier "Fonctions" où sont listées les fonctions qui n'appartiennent pas à une classe. Cela ouvre le fichier `main.cpp`> dans la fenêtre des "Fichiers C/C++" et le curseur d'édition est directement positionné au début de la première ligne de `main()`.

### Quoi modifier en premier

Nous pourrions commencer par modifier le code donné pour obtenir ce qui est listé dans le tutoriel mais il y a encore plus simple. Sélectionnez le contenu de la fonction `main()`> avec la souris ou en maintenant la touche Shift enfoncée pendant la sélection des lignes avec la touche flèche vers le bas. Sélectionnez ensuite "Couper" dans le menu "Edition" ou appuyez sur la touche Suppr. pour supprimer le code sélectionné. Cela effacera la fonction main et nous pourrons commencer à zéro la construction de notre tutoriel.

### Saisie du code source

Pour insérer le code du tutoriel, vous pourriez le lire attentivement et essayer de vous souvenir de chaque ligne de code qu'il contient. Ensuite, après avoir lu ligne par ligne la description du tutoriel, vous pourriez l'utiliser comme exemple pour écrire le tutoriel vous-même.

Pour ceux qui veulent se simplifier la vie : sélectionnez dans le navigateur le contenu de la fonction `main()`> listée et cliquez sur l'icône "Copier" dans la barre d'outils. Autrement, vous pouvez utiliser le menu contextuel ou l'entrée appropriée dans le menu "Edit". Cela copiera la sélection dans le presse-papiers et, après être revenu dans la fenêtre du code source, vous pourrez l'insérer avec "Coller" (en utilisant le menu contextuel, l'icône de la barre d'outils ou l'entrée adéquate du menu "Edition").

Enfin, ajoutez hors de la fonction `main()`> les fichiers d'en-tête suivants :

    #include <qapplication.h>
    #include <qpushbutton.h>

C'est tout ! Le code source de votre première application de tutoriel est terminé.

### Construction de Hello World!

Pour construire le premier tutoriel, sélectionnez "Construire" dans le menu "Build" ou cliquez sur l'icône correspondante dans la barre d'outils. Vous pourriez aussi bien choisir "Exécuter" qui provoque l'exécution après une construction correcte.

Si la construction s'arrête à cause d'une erreur, vous pouvez être sûr que la faute vient du programmeur et non du tutoriel ! Ca serait dommage de chercher une erreur alors que vous avez décidé de programmer pour KDE et/ou Qt mais vous pouvez utiliser cette occasion pour vous entraîner à utiliser KDevelop. Pour chercher une erreur, vous avez deux possibilités : soit en sélectionnant le message d'erreur correspondant dans la fênetre des messages, ce qui vous placera sur la ligne où l'erreur s'est produite, soit en appuyant sur la touche F4. Vous pourriez aussi utiliser l'entrée "Erreur suivante" du menu "Affichage".

### Exercices

Vous pourriez vous dire "Exercices ? C'était si simple que je n'ai pas besoin de m'exercer !" mais rassurez-vous, les choses vont devenir plus compliquées. Ceci était l'exemple le plus simple qui soit mais plus ce sera compliqué et plus cela demandera de réflexions de votre part pour assimiler et suivre les étapes du tutoriel.

Les exercices vous permettront aussi d'apprendre comment utiliser KDevelop et ses fonctionnalités.

Pour apprendre par vous-même plus de choses avec le premier tutoriel, vous pouvez essayer d'effectuer les modifications suivantes dans le code et voir l'influence sur le comportement de l'application :

1. changez le bouton (pushbutton) en QLabel

2. utilisez `setText()`> au lieu de définir directement le texte dans le constructeur du bouton (pushbutton)

3. utilisez `QPushButton::resize ( const QSize & s )`> au lieu de définir directement la taille par sa largeur et sa hauteur. Créez d'abord une instance de `QSize`> qui contiendra la taille

4. jouez avec les tailles pour voir laquelle est la largeur et laquelle est la hauteur

## Étapes 2 et 3 : Extensions

Les étapes 2 et 3 du tutoriel étendent les fonctionnalités du premier tutorial. Vous y découvrirez le mécanisme signal/slot ainsi que les relations parent-enfant entre les widgets.

À propos, pourquoi est-il important d'apprendre cela ? Eh bien, le mécanisme signal/slot est à la base de la technologie qui fait la différence entre la bibliothèque Qt et les autres bibliothèques de widgets. Lorsque vous rencontrerez un problème d'implantation où vous voulez communiquer entre objets, cela réduira considérablement vos efforts et rien de grave n'arrivera si quelque chose se passe mal, même les mauvaises connexions ne conduisent pas à des fautes de segmentation (NdT : segmentation fault). C'est la force de la bibliothèque Qt et beaucoup de développeurs KDE/Qt ne peuvent plus se passer de sa flexibilité. Comprendre le mécanisme signal/slot est donc essentiel pour créer des applications KDE/Qt.

Une autre chose à remarquer est le fait que le bouton termine l'instance de `QApplication`> en appelant `quit()`>. Vous rencontrerez `quit()`> à nouveau en travaillant avec `KApplication`>, l'équivalent de `QApplication`> pour KDE.

## Écrire vos propres widgets

Après avoir réussi à modifier et à étendre la fonction `main()`>, vous allez créer un nouveau widget - un widget particulier qui peut seulement être construit avec la classe que vous allez écrire à l'étape 4. En fait, la classe a été créée pour vous par l'assistant d'application donc il n'y a pas grand chose à ajouter - vous devez juste insérer le code que la leçon 4 place dans les fichiers d'en-tête et d'implantation de la classe `MyWidget`> du fichier `main.cpp`>. Par chance, il suffit d'ajouter l'implantation au code du constructeur.

Pour accéder au constructeur, sélectionnez-le dans le visualiseur de classes. Vous serez automatiquement placé dans l'implantation où vous pourrez ajouter le code.

Ici, vous devez uniquement faire attention à l'inclusion de `qfont.h`> - `QFont`> est uniquement utilisé dans le code du constructeur de `MyWidget`>. Ajoutez donc `&num;include> <qfont.h>` en haut du fichier `mywidget.cpp`>.

Pour exécuter la nouvelle application, cliquez juste sur "Exécuter". Après un enregistrement automatique, toutes les modifications seront compilées.

## Étendre la classe Widget

Dans la leçon 5, le but va maintenant être d'étendre la classe widget. Vous allez donc apprendre les fonctions virtuelles. Ici, l'événement `resizeEvent()`> est réimplanté. Ce qu'il est important d'apprendre ici (au-delà de l'extension de classe), c'est que Qt utilise des fonctions virtuelles ayant un événement en paramètre pour gérer les événements utilisateurs. Vous devriez donc vous familiariser avec les classes suivantes de la bibliothèque Qt :

- QEvent

- QChildEvent

- QCloseEvent

- QFocusEvent

- QKeyEvent

- QMouseEvent

- QMoveEvent

- QPaintEvent

- QResizeEvent

- QTimerEvent

Lorsque vous voulez écrire des widgets personnalisés, spécialement les zones d'affichage des applications, vous devez surcharger l'implantation par défaut des méthodes-événements du widget par les vôtres pour certains événements à traiter. Par exemple, cela peut être

`virtual> void mousePressEvent ( QMouseEvent * )` afin de traiter un événement de la souris pour afficher un menu contextuel. Dans l'implantation, vous devrez insérer un paramètre formel dans l'en-tête de la fonction, la plupart des développeurs utilise `event`> ou juste `e`> comme nom du paramètre.

Ensuite, vous pouvez traiter les paramètres de l'événement. Pour un `QMouseEvent`>, vous devez demander si c'est le bouton gauche, droit ou du milieu de la souris qui a provoqué cet événement.

## Ajouter une nouvelle Classe

Avec la leçon 6, vous allez devoir ajouter une classe à l'application du tutoriel. Logiquement, vous devriez penser "Je vais juste créer un fichier d'en-tête et un fichier d'implantation, et c'est tout" mais KDevelop va vous rendre cela encore plus simple. Pour ajouter une classe, vous devriez toujours utiliser le Générateur de classes. Il fera tout le boulot pour vous et vous aurez uniquement à rajouter le code spécifique.

Pour ajouter une classe avec le Générateur de classes, choisissez "Projet" - "Nouvelle Classe" qui ouvrira une boîte de dialogue afin de saisir toutes les valeurs nécessaires à la classe que vous voulez ajouter. La première chose à insérer est le nom de la classe. Le tutoriel la nomme `LCDRange`> donc ceci doit être inséré en premier. Ensuite, passons à la classe de base. La classe de base est celle dont hérite la nouvelle classe. D'après le tutoriel (Qt 1.42), il s'agit de `QWidget`>. Maintenant, comme la plupart des classes du GUI (Interface Graphique Utilisateur) à ajouter dérivent de QWidget, le Générateur de classes rend cela encore plus simple. Laissez vide la classe de base et cochez plutôt "Classe fille de QWidget" dans la section "Options supplémentaires". Cela ajoutera automatiquement dans le fichier d'en-tête la macro `Q&lowbar;OBJECT`> qui est nécessaire pour ajouter des signal/slot (requis pour le chapitre 7).

Comme les noms de fichiers sont automatiquement insérés, vous n'avez pas à vous en préoccuper. La seule chose que nous vous suggérons d'ajouter est la documentation. Il est toujours plus élégant d'ajouter une documentation descriptive à la classe, spécialement lorsque le nom de classe `LCDRange`> n'est pas très clair sur le but du widget.

## Étapes 7-14

Pour les dernières étapes du tutoriel, vous êtes prêt et vous savez tout ce que vous avez à savoir - ajouter les classes nécessaires et effectuer les modifications.

Après chaque modification, vous devriez reconstruire l'application et vérifier que votre code ne contient pas d'erreur. Lancez la et suivez son exécution ; vous pouvez aussi jouer avec les options de "Construction" de KDevelop, exécuter l'application avec une ligne de commande contenant des arguments tels que --geometry et la déboguer avec KDbg dans la fenêtre des Outils. Ensuite, vous devriez être capable de traiter les exemples de Qt qui seront présentés dans le chapitre suivant.

## Copyright

    KDevelop Copyright 1998,1999 The KDevelop Team.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    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.

    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.