Mis à jour le 04/12/2018
  • 50 heures
  • Difficile

Ce cours est visible gratuitement en ligne.

Ce cours existe en livre papier.

Vous pouvez obtenir un certificat de réussite à l'issue de ce cours.

Vous pouvez être accompagné et mentoré par un professeur particulier par visioconférence sur ce cours.

J'ai tout compris !

Apprennez à lire la documentation de Qt

Connectez-vous ou inscrivez-vous gratuitement pour bénéficier de toutes les fonctionnalités de ce cours !

Voilà le chapitre le plus important de toute la partie sur Qt : celui qui va vous apprendre à lire la documentation de Qt.

Pourquoi est-ce que c'est si important de savoir lire la documentation ? Parce que la documentation, c'est la bible du programmeur. Elle explique toutes les possibilités d'un langage ou d'une bibliothèque.
La documentation de Qt contient la liste des fonctionnalités de Qt. Toute la liste.

La documentation est ce qu'on peut trouver de plus complet mais… son contenu est rédigé très différemment de ce livre.

Déjà, il faudra vous y faire : la documentation n'est disponible qu'en anglais (c'est valable pour Qt et pour la quasi-totalité des autres documentations, notez bien). Il faudra donc faire l'effort de lire de l'anglais, même si vous y êtes allergiques. En programmation, on peut rarement s'en sortir si on ne lit pas un minimum d'anglais technique.

D'autre part, la documentation est construite de manière assez déroutante quand on débute. Il faut être capable de « lire » la documentation et d'y naviguer.
C'est précisément ce que ce chapitre va vous apprendre à faire. :)

Où trouver la documentation ?

On vous dit que Qt propose une superbe documentation très complète qui vous explique tout son fonctionnement.
Oui mais où peut-on trouver cette documentation au juste ?

Il y a en fait deux moyens d'accéder à la documentation :

  • si vous avez accès à Internet : vous pouvez aller sur le site de Digia (l'entreprise qui édite Qt) ;

  • si vous n'avez pas d'accès à Internet : vous pouvez utiliser le programme Qt Creator qui contient toute la documentation.

Personnellement, si j'ai accès à Internet, j'ai tendance à préférer utiliser cette méthode pour lire la documentation. Il suffit d'aller sur le site web de Digia, section documentation. L'adresse est simple à retenir : http://qt-project.org/doc.

Un des principaux avantages à aller chercher la documentation sur Internet, c'est que l'on est assuré d'avoir la documentation la plus à jour. En effet, s'il y a des nouveautés ou des erreurs, on est certain en allant sur le Net d'en avoir la dernière version.

Lorsque vous arrivez sur la documentation, la page de la figure suivante s'affiche :

Accueil de la documentation
Accueil de la documentation

Nous allons détailler les différentes sections de cette page par la suite. :)

Les différentes sections de la documentation

Lorsque vous arrivez à l'accueil de la documentation en ligne, vous pouvez voir 3 sections :

  • Getting Started ;

  • Development Topics ;

  • Reference.

Les deux qui vont nous intéresser le plus sont Development Topics et Reference. Vous pouvez aussi regarder la section "Getting Started" qui contient des exemples et des tutoriels (en anglais) parfois bien pratiques.

Voyons ensemble ces 2 dernières sections…

Reference

Cette section décrit dans le détail toutes les fonctionnalités de Qt. Ce n'est pas la plus lisible pour un débutant mais c'est pourtant là qu'est le cœur de la documentation :

  • C++ Classes : la liste de toutes les classes proposées par Qt. Il y en a beaucoup ! C'est une des sections que vous consulterez le plus souvent.

  • Qt Modules : très intéressante, cette section répertorie les classes de Qt en fonction des modules. Qt étant découpé en plusieurs modules (Qt Core, Qt Widgets…), cela vous donne une vision de l'architecture globale de Qt. Je vous invite à jeter un coup d'œil en premier à cette section, c'est celle qui vous donnera le meilleur recul.

  • QML APIs by Module : la documentation du langage QML de Qt dont nous ne parlerons pas dans ce cours. Il permet de créer des fenêtres rapidement et facilement.

  • Qt Creator : une documentation détaillée sur Qt Creator qui vous permet d'aller plus loin avec ce logiciel.

Ceci étant, l'élément que vous utiliserez vraiment le plus souvent est le champ de recherche, en haut du menu. Lorsque vous aurez une question sur le fonctionnement d'une classe ou d'une méthode, il vous suffira de saisir son nom dans le champ de recherche pour être redirigé immédiatement vers la page qui présente son fonctionnement.

Development Topics

Ce sont des pages de guide qui servent non seulement d'introduction à Qt, mais aussi de conseils pour ceux qui veulent utiliser Qt le mieux possible, thématique par thématique. Bien sûr, tout est en anglais.

La lecture de cette section peut être très intéressante et enrichissante pour vous. Vous n'avez pas besoin de la lire dans l'immédiat car ce cours va vous donner une bonne introduction globale à Qt… mais si plus tard vous souhaitez approfondir, vous trouverez dans cette section des articles très utiles !

Comprennez la documentation d'une classe

Voilà la section la plus importante et la plus intéressante de ce chapitre : nous allons étudier la documentation d'une classe de Qt au hasard.
Chaque classe possède sa propre page, plus ou moins longue suivant la complexité de la classe. Vous pouvez donc retrouver tout ce que vous avez besoin de savoir sur une classe en consultant cette seule page.

Bon, j'ai dit qu'on allait prendre une classe de Qt au hasard. Alors, voyons voir… sur qui cela va-t-il tomber… ah ! Je sais :QLineEdit.

QLineEdit

Vous devriez voir une longue page s'afficher sous vos yeux ébahis :

Documentation de QLineEdit
Documentation de QLineEdit

Chaque documentation de classe suit exactement la même structure. Vous retrouverez donc les mêmes sections, les mêmes titres, etc.

Analysons à quoi correspond chacune de ces sections !

Introduction

Au tout début, vous pouvez lire une très courte introduction qui explique en quelques mots à quoi sert la classe.

Ici, nous avons : « The QLineEdit widget is a one-line text editor. », ce qui signifie, si vous avez bien révisé votre anglais, que ce widget est un éditeur de texte sur une ligne :

Un QLineEdit

Le lien « More… » vous amène vers une description plus détaillée de la classe. En général, il s'agit d'un mini-tutoriel pour apprendre à l'utiliser. Je vous recommande de toujours lire cette introduction quand vous travaillez avec une classe que vous ne connaissiez pas jusqu'alors.
Cela vous fera gagner beaucoup de temps car vous saurez « par où commencer » et « quelles sont les principales méthodes de la classe ».

Ensuite, on vous donne le header à inclure pour pouvoir utiliser la classe dans votre code. En l'occurrence il s'agit de :

#include <QLineEdit>

Puis vous avez une information très importante à côté de laquelle on passe souvent : la classe dont hérite votre classe. Ici, on voit queQWidgetest le parent deQLineEdit. DoncQLineEditrécupère toutes les propriétés deQWidget. Cela a son importance comme nous allons le voir…

Voilà pour l'intro !
Maintenant, voyons voir les sections qui suivent…

Public Types

Les classes définissent parfois des types de données personnalisés, sous la forme de ce qu'on appelle des énumérations.

Ici, QLineEditdéfinit l'énumération EchoModequi propose plusieurs valeurs :Normal,NoEcho,Password, etc.

Properties

Vous avez là toutes les propriétés d'une classe que vous pouvez lire et modifier.

Euh, ce ne sont pas des attributs par hasard ?

Si. Mais la documentation ne vous affiche que les attributs pour lesquels Qt définit des accesseurs. Il y a de nombreux attributs « internes » à chaque classe, que la documentation ne vous montre pas car ils ne vous concernent pas.

Toutes les propriétés sont donc des attributs intéressants de la classe que vous pouvez lire et modifier. Comme je vous l'avais dit dans un chapitre précédent, Qt suit cette convention pour le nom des accesseurs :

  • propriete(): c'est la méthode accesseur qui vous permet de lire la propriété ;

  • setPropriete(): c'est la méthode accesseur qui vous permet de modifier la propriété.

Prenons par exemple la propriété text. C'est la propriété qui stocke le texte rentré par l'utilisateur dans le champ de texteQLineEdit.

Comme indiqué dans la documentation, textest de type QString. Vous devez donc récupérer la valeur dans un QString.
Pour récupérer le texte entré par l'utilisateur dans une variable contenu, on fera donc :

QLineEdit monChamp("Contenu du champ");
QString contenu = monChamp.text();

Pour modifier le texte présent dans le champ, on écrira :

QLineEdit monChamp;
monChamp.setText("Entrez votre nom ici");

Vous remarquerez que dans la documentation, la propriété textest un lien. Cliquez dessus. Cela vous amènera plus bas sur la même page vers une description de la propriété.
On vous y donne aussi le prototype des accesseurs :

  • QString text () const

  • void setText ( const QString & )

Enfin, parfois vous verrez comme ici une mention See also (voir aussi) qui vous invite à aller voir d'autres propriétés ou méthodes de la classe ayant un rapport avec celle que vous êtes en train de consulter. Ici, on vous dit que les méthodes insert()etclear()pourraient vous intéresser. En effet, par exemple clear()vide le contenu du champ de texte, c'est donc une méthode intéressante en rapport avec la propriété qu'on était en train de consulter.

Public Functions

C'est bien souvent la section la plus importante. Vous y trouverez toutes les méthodes publiques (parce que les méthodes privées ne vous concernent pas) de la classe. On trouve dans le lot :

  • le (ou les) constructeur(s) de la classe, très intéressants pour savoir comment créer un objet à partir de cette classe ;

  • les accesseurs de la classe (comme text()etsetText()qu'on vient de voir), basés sur les attributs ;

  • et enfin d'autres méthodes publiques qui ne sont ni des constructeurs ni des accesseurs et qui effectuent diverses opérations sur l'objet (par exemple home(), qui ramène le curseur au début du champ de texte).

Cliquez sur le nom d'une méthode pour en savoir plus sur son rôle et son fonctionnement.

Lire et comprendre le prototype

À chaque fois, il faut que vous lisiez attentivement le prototype de la méthode, c'est très important ! Le prototype à lui seul vous donne une grosse quantité d'informations sur la méthode.

Prenons l'exemple du constructeur. On voit qu'on a deux prototypes :

  • QLineEdit ( QWidget * parent = 0 )

  • QLineEdit ( const QString & contents, QWidget * parent = 0 )

Vous noterez que certains paramètres sont facultatifs.
Si vous cliquez sur un de ces constructeurs, par exemple le second, on vous explique la signification de chacun de ces paramètres.

On apprend queparentest un pointeur vers le widget qui « contiendra » notreQLineEdit(par exemple une fenêtre) et quecontentsest le texte qui doit être écrit dans leQLineEditpar défaut.

Cela veut dire que, si on prend en compte le fait que le paramètreparentest facultatif, on peut créer un objet de typeQLineEditde quatre façons différentes :

QLineEdit monChamp(); // Appel du premier constructeur
QLineEdit monChamp(fenetre); // Appel du premier constructeur
QLineEdit monChamp("Entrez un texte"); // Appel du second constructeur
QLineEdit monChamp("Entrez un texte", fenetre); // Appel du second constructeur

C'est fou tout ce qu'un prototype peut raconter hein ?

Quand la méthode attend un paramètre d'un type que vous ne connaissez pas…

Je viens de voir la méthodesetAlignment()mais elle demande un paramètre de typeQt::Alignment. Comment je lui donne cela moi, je ne connais pas lesQt::Alignment!

Pas de panique. Il vous arrivera très souvent de tomber sur une méthode qui attend un paramètre d'un type qui vous est inconnu. Par exemple, vous n'avez jamais entendu parler deQt::Alignment. Qu'est-ce que c'est que ce type ?

La solution pour savoir comment envoyer un paramètre de typeQt::Alignmentconsiste à cliquer dans la documentation sur le lienQt::Alignment(eh oui, ce n'est pas un lien par hasard !).
Ce lien vous amène vers une page qui vous explique ce qu'est le typeQt::Alignment.

Il peut y avoir deux types différents :

  • Les énumérations :Qt::Alignmenten est une. Les énumérations sont très simples à utiliser, c'est une série de valeurs. Il suffit d'écrire la valeur que l'on veut, comme le donne la documentation deQt::Alignment, par exempleQt::AlignCenter. La méthode pourra donc être appelée comme ceci :

monChamp.setAlignment(Qt::AlignCenter);
  • Les classes : parfois, la méthode attend un objet issu d'une classe précise pour travailler. Là c'est un peu plus compliqué : il va falloir créer un objet de cette classe et l'envoyer à la méthode.

Pour étudier le second cas, prenons par exemple setValidator, qui attend un pointeur vers unQValidator. La méthode setValidatorvous dit qu'elle permet de vérifier si l'utilisateur a saisi un texte valide. Cela peut être utile si vous voulez vérifier que l'utilisateur a bien entré un nombre entier et non « Bonjour ça va ? » quand vous lui demandez son âge…
Si vous cliquez sur le lien QValidator, vous êtes conduit à la page qui explique comment utiliser la classeQValidator. Lisez le texte d'introduction pour comprendre ce que cette classe est censée faire puis regardez les constructeurs afin de savoir comment créer un objet de type QValidator.

Parfois, comme là, c'est même un peu plus délicat. QValidatorest une classe abstraite (c'est ce que vous dit l'introduction de sa documentation), ce qui signifie qu'on ne peut pas créer d'objet de type QValidatoret qu'il faut utiliser une de ses classes filles.
Au tout début, la page de la documentation de QValidatorvous dit Inherited by QDoubleValidator,QIntValidator, and QRegExpValidator. Cela signifie que ces classes héritent de QValidatoret que vous pouvez les utiliser aussi. En effet, une classe fille est compatible avec la classe mère, comme nous l'avons déjà vu au chapitre sur l'héritage.

Nous, nous voulons autoriser la personne à saisir uniquement un nombre entier, nous allons donc utiliserQIntValidator. Il faut créer un objet de type QIntValidator. Regardez ses constructeurs et choisissez celui qui vous convient.

Au final (ouf !), pour utiliser setValidator, on peut procéder ainsi :

QValidator *validator = new QIntValidator(0, 150, this);
monChamp.setValidator(validator);

… pour s'assurer que la personne ne saisira qu'un nombre compris entre 0 et 150 ans (cela laisse de la marge !).

La morale de l'histoire, c'est qu'il ne faut pas avoir peur d'aller lire la documentation d'une classe dont a besoin la classe sur laquelle vous travaillez. Parfois, il faut même aller jusqu'à consulter les classes filles.

Cela peut faire un peu peur au début, mais c'est une gymnastique de l'esprit à acquérir. N'hésitez donc pas à sauter de lien en lien dans la documentation pour arriver enfin à envoyer à cette $%@#$#% de méthode un objet du type qu'elle attend !

Public Slots

Les slots sont des méthodes comme les autres, à la différence près qu'on peut aussi les connecter à un signal comme on l'a vu dans le chapitre sur les signaux et les slots.
Notez que rien ne vous interdit d'appeler un slot directement, comme si c'était une méthode comme une autre.

Par exemple, le slotundo()annule la dernière opération de l'utilisateur.

Vous pouvez l'appeler comme une bête méthode :

monChamp.undo();

… mais, du fait queundo()est un slot, vous pouvez aussi le connecter à un autre widget. Par exemple, on peut imaginer un menuEdition > Annulerdont le signal « cliqué » sera connecté au slotundodu champ de texte.

Signals

C'est la liste des signaux que peut envoyer unQLineEdit.
Un signal est un évènement qui s'est produit et que l'on peut connecter à un slot (le slot pouvant appartenir à cet objet ou à un autre).

Par exemple, le signal textChanged()est émis à chaque fois que l'utilisateur modifie le texte à l'intérieur duQLineEdit. Si vous le voulez, vous pouvez connecter ce signal à un slot pour qu'une action soit effectuée chaque fois que le texte est modifié.

Attention encore une fois à bien regarder les signaux hérités de QWidgetetQObject, car ils appartiennent aussi à la classeQLineEdit. Je sais que je suis lourd à force de répéter cela, inutile de me le dire, je le fais exprès pour que cela rentre. ;-)

Protected Functions

Ce sont des méthodes protégées. Elles ne sont ni public, ni private, mais protected.
Comme on l'a vu au chapitre sur l'héritage, ce sont des méthodes privées (auxquelles vous ne pouvez pas accéder directement en tant qu'utilisateur de la classe) mais qui seront héritées et donc réutilisables si vous créez une classe basée surQLineEdit.

Il est très fréquent d'hériter des classes de Qt, on l'a d'ailleurs déjà fait avecQWidgetpour créer une fenêtre personnalisée. Si vous héritez deQLineEdit, sachez donc que vous disposerez aussi de ces méthodes.

Additional Inherited Members

Si des éléments hérités n'ont pas été listés jusqu'ici, on les retrouvera dans cette section à la fin.
Par exemple, la classe QLineEditne définit pas de méthode statique, mais elle en possède quelques-unes héritées de QWidgetet QObject. Je vous rappelle qu'une méthode statique est une méthode que l'on peut appeler sans avoir eu à créer d'objet. C'est un peu comme une fonction.

Il n'y a rien de bien intéressant avec QLineEditmais sachez par exemple que la classe QStringpossède de nombreuses méthodes statiques, comme number()qui convertit le nombre donné en une chaîne de caractères de type QString.

QString maChaine = QString::number(12);

Une méthode statique s'appelle comme ceci :NomDeLaClasse::nomDeLaMethode().
On a déjà vu tout cela dans les chapitres précédents, je ne fais ici que des rappels.

Detailed description

C'est une description détaillée du fonctionnement de la classe. On y accède notamment en cliquant sur le lien « More… » après la très courte introduction du début.
C'est une section très intéressante que je vous invite à lire la première fois que vous découvrez une classe, car elle vous permet de comprendre avec du recul comment la classe est censée fonctionner.

En résumé

  • La documentation de Qt est indispensable. Vous devez garder son adresse dans vos favoris et la consulter régulièrement.

  • Contrairement à ce cours, la documentation est exhaustive : elle indique toutes les possibilités offertes par Qt dans les moindres détails.

  • La documentation peut rebuter au premier abord (termes techniques, anglais, etc.) mais une fois qu'on a appris à la lire, on s'aperçoit qu'elle est moins complexe qu'il y paraît.

  • N'oubliez pas que la plupart des classes de Qt héritent d'une autre classe. Consultez aussi les propriétés des classes mères pour connaître toutes les possibilités de la classe que vous utilisez.

  • N'hésitez pas à naviguer de lien en lien pour découvrir de nouvelles classes et leur mode de fonctionnement. Souvent, une classe a besoin d'une autre classe pour fonctionner.

  • J'insiste : apprenez à lire la documentation. Vous passerez à côté de l'essentiel si vous n'avez pas le réflexe de l'ouvrir régulièrement.

Exemple de certificat de réussite
Exemple de certificat de réussite