/****************************************************************************

**

** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the documentation of the Qt Toolkit.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

** This file contains pre-release code and may not be distributed.

** You may use this file in accordance with the terms and conditions

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 2.1 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL included in the

** packaging of this file.  Please review the following information to

** ensure the GNU Lesser General Public License version 2.1 requirements

** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

** In addition, as a special exception, Nokia gives you certain additional

** rights.  These rights are described in the Nokia Qt LGPL Exception

** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \page tutorials-addressbook-fr.html

    \startpage {index.html}{Qt Reference Documentation}

    \contentspage Tutorials

    \nextpage {tutorials/addressbook-fr/part1}{Chapitre 1}

    \title Tutoriel "Carnet d'adresses"

    \brief Une introduction à la programation d'interface graphique montrant comment construire une application simple avec Qt.

    Ce tutoriel est une introduction à la programmation de GUI (interface utilisateur)

    à l'aide des outils fournis par la plateforme multiplate-forme Qt.

    \image addressbook-tutorial-screenshot.png

    Ce tutoriel va nous amener à découvrir quelques technologies fondamentales fournies 

    par Qt, tel que:

    \list

    \o Les Widgets et leur mise en page à l'aide des layouts

    \o Les signaux et slots

    \o Les structures de données de collections

    \o Les entrées/sorties

    \endlist

    Si c'est votre premier contact avec Qt, lisez \l{How to Learn Qt}{Comment apprendre Qt}

    si ce n'est déjà fait.

    Le code source du tutoriel est distribué avec Qt dans le dossier \c examples/tutorials/addressbook

    Les chapitres du tutoriel:

    \list 1

    \o \l{tutorials/addressbook-fr/part1}{Conception de l'interface utilisateur}

    \o \l{tutorials/addressbook-fr/part2}{Ajouter des adresses}

    \o \l{tutorials/addressbook-fr/part3}{Navigation entre les éléments}

    \o \l{tutorials/addressbook-fr/part4}{éditer et supprimer des adresses}

    \o \l{tutorials/addressbook-fr/part5}{Ajout d'une fonction de recherche}

    \o \l{tutorials/addressbook-fr/part6}{Sauvegarde et chargement}

    \o \l{tutorials/addressbook-fr/part7}{Fonctionnalités avancées}

    \endlist

    La petite application que nous développerons ici ne possède pas tous les éléments

    des interfaces dernier cri, elle va nous permettre d'utiliser les techniques de base

    utilisées dans les applications plus complexes.

    Lorsque vous aurez terminé ce tutoriel, nous vous recommandons de poursuivre avec l'exemple

    "\l{mainwindows/application}{Application}", qui présente une interface simple utilisant

    les menus et barres d'outils, la barre d'état, etc.

*/

/*!

    \page tutorials-addressbook-fr-part1.html

    \contentspage {Tutoriel "Carnet d'adresses"}{Sommaire}

    \nextpage {tutorials/addressbook-fr/part2}{Chapitre 2}

    \example tutorials/addressbook-fr/part1

    \title Carnet d'adresses 1 - Conception de l'interface utilisateur

    La première partie de ce tutoriel traite de la conception d'une interface graphique

    (GUI) basique, que l'on utilisera pour l'application Carnet d'adresses.

    La première étape dans la création d'applications graphiques est la conception de

    l'interface utilisateur. Dans ce chapitre, nous verrons comment créer les labels

    et champs de saisie nécessaires à l'implementation d'un carnet d'adresses de base.

    Le résultat attendu est illustré par la capture d'écran ci-dessous.

    \image addressbook-tutorial-part1-screenshot.png

    Nous allons avoir besoin de deux objets QLabel, \c nameLabel et \c addressLabel,

    ainsi que deux champs de saisie: un objet QLineEdit, \c nameLine, et un objet

    QTextEdit, \c addressText, afin de permettre à l'utilisateur d'entrer le nom d'un

    contact et son adresse. Les widgets utilisés ainsi que leur placement sont visibles ci-dessous.

    \image addressbook-tutorial-part1-labeled-screenshot.png

    Trois fichiers sont nécessaires à l'implémentation de ce carnet d'adresses:

    \list

        \o \c{addressbook.h} - le fichier de définition (header) pour la classe \c AddressBook,

        \o \c{addressbook.cpp} - le fichier source, qui comprend l'implémentation de la classe

            \c AddressBook

        \o \c{main.cpp} - le fichier qui contient la méthode \c main() , et

        une instance de la classe \c AddressBook.

    \endlist

    \section1 Programmation en Qt - héritage

    Lorsque l'on écrit des programmes avec Qt, on a généralement recours à

    l'héritage depuis des objets Qt, afin d'y ajouter des fonctionnalités.

    C'est l'un des concepts fondamentaux de la création de widgets personnalisés

    ou de collections de widgets. Utiliser l'héritage afin de compléter

    ou modifier le comportement d'un widget présente les avantages suivants:

    \list

    \o La possibilité d'implémenter des méthodes virtuelles et des méthodes 

    virtuelles pures pour obtenir exactement ce que l'on souhaite, avec la possibilité

    d'utiliser l'implémentation de la classe mère si besoin est.

    \o Cela permet l'encapsulation partielle de l'interface utilisateur dans une classe,

    afin que les autres parties de l'application n'aient pas à se soucier de chacun des

    widgets qui forment l'interface utilisateur.

    \o La classe fille peut être utilisée pour créer de nombreux widgets personnalisés

    dans une même application ou bibliothèque, et le code de la classe fille peut être

    réutilisé dans d'autres projets

    \endlist

    Comme Qt ne fournit pas de widget standard pour un carnet d'adresses, nous 

    partirons d'une classe de widget Qt standard et y ajouterons des fonctionnalités.

    La classe \c AddressBook crée dans ce tutoriel peut être réutilisée si on a besoin d'un

    widget carnet d'adresses basique.

    \section1 La classe AddressBook

    Le fichier \l{tutorials/addressbook-fr/part1/addressbook.h}{\c addressbook.h} permet de

    définir la classe \c AddressBook.

    On commence par définir \c AddressBook comme une classe fille de QWidget et déclarer

    un constructeur. On utilise également la macro Q_OBJECT pour indiquer que la classe

    exploite les fonctionnalités de signaux et slots offertes par Qt ainsi que

    l'internationalisation, bien que nous ne les utilisions pas à ce stade.

    \snippet tutorials/addressbook-fr/part1/addressbook.h class definition

    La classe contient les déclarations de \c nameLine et \c addressText,

    les instances privées de QLineEdit et QTextEdit mentionnées précédemment.

    Vous verrez, dans les chapitres à venir que les informations contenues

    dans \c nameLine et \c addressText sont nécessaires à de nombreuses méthodes

    du carnet d'adresses.

    Il n'est pas nécessaire de déclarer les objets QLabel que nous allons utiliser 

    puisque nous n'aurons pas besoin d'y faire référence après leur création.

    La façon dont Qt gère la parenté des objets est traitée dans la section suivante.

    La macro Q_OBJECT implémente des fonctionnalités parmi les plus avancées de Qt.

    Pour le moment, il est bon de voir la macro Q_OBJECT comme un raccourci nous 

    permettant d'utiliser les méthodes \l{QObject::}{tr()} et \l{QObject::}{connect()}.

    Nous en avons maintenant terminé avec le fichier \c addressbook.h et allons

    passer à l'implémentation du fichier \c addressbook.cpp.

    \section1 Implémentation de la classe AddressBook

    Le constructeur de la classe \c{AddressBook} prend en paramètre un QWidget, \e parent.

    Par convention, on passe ce paramètre au constructeur de la classe mère.

    Ce concept de parenté, où un parent peut avoir un ou plusieurs enfants, est utile

    pour regrouper les Widgets avec Qt. Par exemple, si vous détruisez le parent,

    tous ses enfants seront détruits égalament.

    \snippet tutorials/addressbook/part1/addressbook.cpp constructor and input fields

    à l'intérieur de ce constructeur, on déclare et instancie deux objets locaux

    QLabel, \c nameLabel et \c addressLabel, de même on instancie \c nameLine et

    \c addressText. La méthode \l{QObject::tr()}{tr()} renvoie une version traduite

    de la chaîne de caractères, si elle existe; dans le cas contraire, elle renvoie

    la chaîne elle même. On peut voir cette méthode comme un marqueur \tt{<insérer

    la traduction ici>}, permettant de repérer les objets QString à considérer

    pour traduire une application. Vous remarquerez, dans les chapitres à venir

    comme dans les \l{Qt Examples}{exemples Qt}, qu'elle est utilisée chaque fois

    que l'on utilise une chaîne susceptible d'être traduite.

    Lorsque l'on programme avec Qt, il est utile de savoir comment fonctionnent les

    agencements ou layouts. Qt fournit trois classes principales de layouts pour

    contrôler le placement des widgets: QHBoxLayout, QVBoxLayout et QGridLayout.

    \image addressbook-tutorial-part1-labeled-layout.png

    On utilise un QGridLayout pour positionner nos labels et champs de saisie de manière

    structurée. QGridLayout divise l'espace disponible en une grille, et place les

    widgets dans les cellules que l'on spécifie par les numéros de ligne et de colonne.

    Le diagramme ci-dessus présente les cellules et la position des widgets, et cette

    organisation est obtenue à l'aide du code suivant:

    \snippet tutorials/addressbook/part1/addressbook.cpp layout

    On remarque que le label \c AddressLabel est positionné en utilisant Qt::AlignTop

    comme argument optionnel. Ceci est destiné à assurer qu'il ne sera pas centré

    verticalement dans la cellule (1,0). Pour un aperçu rapide des layouts de Qt,

    consultez la section \l{Layout Management}.

    Afin d'installer l'objet layout dans un widget, il faut appeler la méthode

    \l{QWidget::setLayout()}{setLayout()} du widget en question:

    \snippet tutorials/addressbook/part1/addressbook.cpp setting the layout

    Enfin, on initialise le titre du widget à "Simple Address Book"

    \section1 Exécution de l'application

    Un fichier séparé, \c main.cpp, est utilisé pour la méthode \c main(). Dans cette

    fonction, on crée une instance de QApplication, \c app. QApplication se charge de

    des ressources communes à l'ensemble de l'application, tel que les polices de

    caractères et le curseur par défaut, ainsi que de l'exécution de la boucle d'évènements.

    De ce fait, il y a toujours un objet QApplication dans toute application graphique en Qt.

    \snippet tutorials/addressbook/part1/main.cpp main function

    On construit un nouveau widget \c AddressBook sur la pile et on invoque

    sa méthode \l{QWidget::show()}{show()} pour l'afficher.

    Cependant, le widget ne sera pas visible tant que la boucle d'évènements

    n'aura pas été lancée. On démarre la boucle d'évènements en appelant la

    méthode \l{QApplication::}{exec()} de l'application; le résultat renvoyé

    par cette méthode est lui même utilisé comme valeur de retour pour la méthode

    \c main().

    On comprend maintenant pourquoi \c AddressBook a été créé sur la pile: à la fin

    du programme, l'objet sort du scope de la fonction \c main() et tous ses widgets enfants

    sont supprimés, assurant ainsi qu'il n'y aura pas de fuites de mémoire.

*/

/*!

    \page tutorials-addressbook-fr-part2.html

    \previouspage {tutorials/addressbook-fr/part1}{Chapitre 1}

    \contentspage {Tutoriel "Carnet d'adresses"}{Sommaire}

    \nextpage {tutorials/addressbook-fr/part3}{Chapitre 3}

    \example tutorials/addressbook-fr/part2

    \title Carnet d'adresses 2 - Ajouter des adresses

    La prochaine étape pour créer notre carnet d'adresses est d'ajouter un soupçon

    d'interactivité.

    \image addressbook-tutorial-part2-add-contact.png

    Nous allons fournir un bouton que l'utilisateur peut

    cliquer pour ajouter un nouveau contact. Une structure de données est aussi

    nécessaire afin de pouvoir stocker les contacts en mémoire.

    \section1 Définition de la classe AddressBook

    Maintenant que nous avons mis en place les labels et les champs de saisie,

    nous ajoutons les boutons pour compléter le processus d'ajout d'un contact.

    Cela veut dire que notre fichier \c addressbook.h a maintenant trois

    objets QPushButton et trois slots publics correspondant.

    \snippet tutorials/addressbook/part2/addressbook.h slots

    Un slot est une méthode qui répond à un signal. Nous allons

    voir ce concept en détail lorsque nous implémenterons la classe \c{AddressBook}.

    Pour une explication détaillée du concept de signal et slot, vous pouvez

    vous référer au document \l{Signals and Slots}.

    Les trois objets QPushButton \c addButton, \c submitButton et \c cancelButton

    sont maintenant inclus dans la déclaration des variables privées, avec

    \c nameLine et \c addressText du chapitre précédent.

    \snippet tutorials/addressbook/part2/addressbook.h pushbutton declaration

    Nous avons besoin d'un conteneur pour stocker les contacts du carnet

    d'adresses, de façon à pouvoir les énumérer et les afficher.

    Un objet QMap, \c contacts, est utilisé pour ça, car il permet de stocker

    des paires clé-valeur: le nom du contact est la \e{clé} et l'adresse du contact

    est la \e{valeur}.

    \snippet tutorials/addressbook/part2/addressbook.h remaining private variables

    Nous déclarons aussi deux objects QString privés: \c oldName et \c oldAddress.

    Ces objets sont nécessaires pour conserver le nom et l'adresse du dernier contact

    affiché avant que l'utilisateur ne clique sur le bouton "Add". Grâce à ces variables

    si l'utilisateur clique sur "Cancel", il est possible de revenir

    à l'affichage du dernier contact.

    \section1 Implémentation de la classe AddressBook

    Dans le constructeur de \c AddressBook, \c nameLine et

    \c addressText sont mis en mode lecture seule, de façon à autoriser l'affichage

    mais pas la modification du contact courant.

    \dots

    \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 1

    \dots

    \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 2

    Ensuite, nous instancions les boutons \c addButton, \c submitButton, et

    \c cancelButton.

    \snippet tutorials/addressbook/part2/addressbook.cpp pushbutton declaration

    Le bouton \c addButton est affiché en invoquant la méthode \l{QPushButton::show()}

    {show()}, tandis que \c submitButton et \c cancelButton sont cachés en invoquant

    \l{QPushButton::hide()}{hide()}. Ces deux boutons ne seront affichés que lorsque 

    l'utilisateur cliquera sur "Add", et ceci est géré par la méthode \c addContact()

    décrite plus loin.

    \snippet tutorials/addressbook/part2/addressbook.cpp connecting signals and slots

    Nous connectons le signal \l{QPushButton::clicked()}{clicked()} de chaque bouton 

    au slot qui gèrera l'action.

    L'image ci-dessous illustre ceci:

    \image addressbook-tutorial-part2-signals-and-slots.png

    Ensuite, nous arrangeons proprement les boutons sur la droite du widget

    AddressBook, et nous utilisons un QVBoxLayout pour les aligner verticalement.

    \snippet tutorials/addressbook/part2/addressbook.cpp vertical layout

    La methode \l{QBoxLayout::addStretch()}{addStretch()} est utilisée pour

    assurer que les boutons ne sont pas répartis uniformément, mais regroupés

    dans la partie supperieure du widget. La figure ci-dessous montre la différence

    si \l{QBoxLayout::addStretch()}{addStretch()} est utilisé ou pas.

    \image addressbook-tutorial-part2-stretch-effects.png

    Ensuite nous ajoutons \c buttonLayout1 à \c mainLayout, en utilisant

    \l{QGridLayout::addLayout()}{addLayout()}. Ceci nous permet d'imbriquer les

    mises en page puisque \c buttonLayout1 est maintenant un enfant de \c mainLayout.

    \snippet tutorials/addressbook/part2/addressbook.cpp grid layout

    Les coordonnées du layout global ressemblent maintenant à ça:

    \image addressbook-tutorial-part2-labeled-layout.png

    Dans la méthode \c addContact(), nous stockons les détails du dernier

    contact affiché dans \c oldName et \c oldAddress. Ensuite, nous

    vidons ces champs de saisie et nous désactivons le mode

    lecture seule. Le focus est placé sur \c nameLine et on affiche

    \c submitButton et \c cancelButton.

    \snippet tutorials/addressbook/part2/addressbook.cpp addContact

    La méthode \c submitContact() peut être divisée en trois parties:

    \list 1

    \o Nous extrayons les détails du contact depuis \c nameLine et \c addressText

    et les stockons dans des objets QString. Nous les validons pour s'assurer

    que l'utilisateur n'a pas cliqué sur "Add" avec des champs de saisie

    vides; sinon un message est affiché avec QMessageBox pour rappeller à

    l'utilisateur que les deux champs doivent être complétés.

    \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part1

    \o Ensuite, nous vérifions si le contact existe déjà. Si aucun contacts

    existant n'entre en conflit avec le nouveau, nous l'ajoutons à

    \c contacts et nous affichons un QMessageBox pour informer l'utilisateur

    que le contact a été ajouté.

    \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part2

    Si le contact existe déjà, nous affichons un QMessageBox pour informer

    l'utilisateur du problème.

    Notre objet \c contacts est basé sur des paires clé-valeur formés par

    le nom et l'adresse, nous voulons nous assurer que la \e clé est unique.

    \o Une fois que les deux vérifications précédentes ont été traitées,

    nous restaurons les boutons à leur état normal à l'aide du code

    suivant:

    \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part3

    \endlist

    La capture d'écran ci-dessous montre l'affichage fournit par un objet

    QMessageBox, utilisé ici pour afficher un message d'information

    à l'utilisateur:

    \image addressbook-tutorial-part2-add-successful.png

    La méthode \c cancel() restaure les détails du dernier contact, active

    \c addButton, et cache \c submitButton et \c cancelButton.

    \snippet tutorials/addressbook/part2/addressbook.cpp cancel

    L'idée générale pour augmenter la flexibilité lors de l'ajout d'un 

    contact est de donner la possiblité de cliquer sur "Add" 

    ou "Cancel" à n'importe quel moment.

    L'organigramme ci-dessous reprend l'ensemble des interactions dévelopées

    jusqu'ici:

    \image addressbook-tutorial-part2-add-flowchart.png

*/

/*!

    \page tutorials-addressbook-fr-part3.html

    \previouspage {tutorials/addressbook-fr/part2}{Chapitre 2}

    \contentspage {Tutoriel "Carnet d'adresses"}{Sommaire}

    \nextpage {tutorials/addressbook-fr/part4}{Chapitre 4}

    \example tutorials/addressbook-fr/part3

    \title Carnet d'adresses 3 - Navigation entre les éléments

    L'application "Carnet d'adresses" est maintenant à moitié terminée. Il

    nous faut maintenant ajouter quelques fonctions pour naviguer entre

    les contacts. Avant de commencer, il faut se décider sur le type de structure de

    données le plus approprié pour stocker les contacts.

    Dans le chapitre 2, nous avons utilisé un QMap utilisant des paires clé-valeur,

    avec le nom du contact comme \e clé, et l'adresse du contact comme \e valeur.

    Cela fonctionnait bien jusqu'ici, mais pour ajouter la navigation entre les

    entrées, quelques améliorations sont nécessaires.

    Nous améliorerons le QMap en le faisant ressembler à une structure de données

    similaire à une liste liée, où tous les éléments sont connectés, y compris

    le premier et le dernier élément. La figure ci-dessous illustre cette structure

    de donnée.

    \image addressbook-tutorial-part3-linkedlist.png

    \section1 Définition de la classe AddressBook

    Pour ajouter les fonctions de navigation au carnet d'adresses, nous avons

    besoin de deux slots supplémentaires dans notre classe \c AddressBook:

    \c next() et \c previous(). Ceux-ci sont ajoutés au fichier addressbook.h:

    \snippet tutorials/addressbook/part3/addressbook.h navigation functions

    Nous avons aussi besoin de deux nouveaux objets QPushButton, nous ajoutons

    donc les variables privées \c nextButton et \c previousButton.

    \snippet tutorials/addressbook/part3/addressbook.h navigation pushbuttons

    \section1 Implémentation de la classe AddressBook

    A l'intérieur du constructeur de \c AddressBook, dans \c addressbook.cpp, nous

    instancions \c nextButton et \c previousButton et nous les désactivons

    par défaut. Nous faisons ceci car la navigation ne doit être activée

    que lorsqu'il y a plus d'un contact dans le carnet d'adresses.

    \snippet tutorials/addressbook/part3/addressbook.cpp navigation pushbuttons

    Nous connectons alors ces boutons à leur slots respectifs:

    \snippet tutorials/addressbook/part3/addressbook.cpp connecting navigation signals

    L'image ci-dessous montre l'interface utilisateur que nous allons créer.

    Remarquez que cela ressemble de plus en plus à l'interface du programme

    complet.

    \image addressbook-tutorial-part3-screenshot.png

    Nous suivons les conventions pour les fonctions \c next() et \c previous()

    en plaçant \c nextButton à droite et \c previousButton à gauche. Pour

    faire cette mise en page intuitive, nous utilisons un QHBoxLayout pour

    placer les widgets côte à côte:

    \snippet tutorials/addressbook/part3/addressbook.cpp navigation layout

    L'objet QHBoxLayout, \c buttonLayout2, est ensuite ajouté à \c mainLayout.

    \snippet tutorials/addressbook/part3/addressbook.cpp adding navigation layout

    La figure ci-dessous montre les systèmes de coordonnées pour les widgets du

    \c mainLayout.

    \image addressbook-tutorial-part3-labeled-layout.png

    Dans notre méthode \c addContact(), nous avons desactivé ces boutons 

    pour être sûr que l'utilisateur n'utilise pas la navigation lors de 

    l'ajout d'un contact.

    \snippet tutorials/addressbook/part3/addressbook.cpp disabling navigation

    Dans notre méthode \c submitContact(), nous activons les boutons de

    navigation, \c nextButton et \c previousButton, en fonction de la

    taille de \c contacts. Commen mentionné plus tôt, la navigation n'est 

    activée que si il y a plus d'un contact dans le carnet d'adresses.

    Les lignes suivantes montrent comment faire cela:

    \snippet tutorials/addressbook/part3/addressbook.cpp enabling navigation

    Nous incluons aussi ces lignes de code dans le bouton \c cancel().

    Souvenez vous que nous voulons émuler une liste-liée ciruculaire à

    l'aide de l'objet QMap, \c contacts. Pour faire cela, nous obtenons un itérateur 

    sur \c contact dans la méthode \c next(), et ensuite:

    \list

        \o Si l'itérateur n'est pas à la fin de \c contacts, nous l'incrémentons

        \o Si l'itérateur est à la fin de \c contacts, nous changeons sa position

        jusqu'au début de \c contacts. Cela donne l'illusion que notre QMap 

        fonctionne comme une liste circulaire.

    \endlist

    \snippet tutorials/addressbook/part3/addressbook.cpp next() function

    Une fois que nous avons itéré jusqu'à l'objet recherché dans \c contacts,

    nous affichons son contenu sur \c nameLine et \c addressText.

    De la même façon, pour la méthode \c previous(), nous obtenons un 

    itérateur sur \c contacts et ensuite:

    \list

        \o Si l'itérateur est à la fin de \c contacts, on réinitialise

           l'affichage et on retourne.

        \o Si l'itérateur est au début de \c contacts, on change sa 

           position jusqu'à la fin

        \o Ensuite, on décrémente l'itérateur

    \endlist