Programmation Qt/Utiliser la documentation Qt

Voici un chapitre important sur l'apprentissage de Qt : celui qui vous aidera à comprendre la documentation (“la doc”) de Qt. Celui-ci explique toutes les possibilités de la bibliothèque. La documentation de Qt contient la liste des fonctionnalités de Qt. Toutefois la documentation Qt est en anglais comme quasiment toutes les documentations en programmation.

Qt Designer

Distribuer son programme

Les bases

Une documentation est mise à disposition par le site de Qt. Elle est complète et permet de trouver tout pour faire son programme. Il y a 2 moyens d'accéder à la documentation :

Internet : sur le site du projet Qt
Hors-Ligne : le programme Qt Assistant permet d'accéder à la documentation.

Avec Internet

Vous pouvez consulter la documentation en ligne du projet Qt disponible sur http://doc.qt.io

En allant sur la documentation en ligne, cela vous permet d'accéder à la documentation la plus à jour sur les nouveautés ou les bugs corrigés et limitations.

Hors-ligne

Si vous n'avez pas accès à l'Internet, vous pouvez quand même consulter la documentation qui a été installée sur votre ordinateur avec Qt. Pour cela, sous Windows, il vous suffit d'aller dans Démarrer puis dans le répertoire où se trouve Qt et de lancer l'application Qt Assistant. Celle-ci comporte plusieurs fonctionnalités comme ouvrir plusieurs onglets, mettre en favoris des pages et plusieurs autres.

Sous GNU/Linux, allez dans le menu programmation et choisissez Qt Assistant.

Les différentes sections

Sur cette page (ou celle correspondant à la version de Qt que vous utilisez), il y a différentes sections dont certaines sont détaillées ci-dessous.

`Getting Started`

Getting Started contient des informations importantes pour débuter. On trouve dans cette section :

What's new in Qt x.y : qu'est-ce qu'il y a de nouveau dans cette version de Qt par rapport aux précédentes ? Cette page servira plutôt aux programmeurs utilisant une version précédente et voulant savoir ce qu'il y a de nouveau dans celle-ci. Vous pouvez tout de même y jeter un coup d’œil.
How to Learn Qt : comment apprendre Qt ? Cette page vous donne certains conseils pour apprendre Qt dans les meilleures conditions. toutefois, toute la documentation est en anglais donc cette section aussi.
Installation : comment installer Qt.
Tutorial and Examples : le tutoriel de Qt et des programmes d'exemple avec leur code source.

`Advanced Topics`

Qt Reference Documentation : la documentation complète de tous les modules, toutes les classes, toutes les propriétés, etc... de Qt.
Development Topics : c'est en quelque sorte une liste de leçons pour rendre meilleur son programme (Accessibilité, etc...).
Supported Platforms : la liste des systèmes d'exploitations qui supportent Qt.
Qt Tools : les outils pour développer un projet Qt ; nous avons vu Qt Creator, Qt Designer, Qt Linguist, etc...

`Highlighted features`

C'est la liste de certaines choses disponibles sous Qt.

`Qt Versions`

On trouve la liste des dernières versions de Qt.

`Tools Manuals`

Ce titre peut être traduit littéralement, ce sont les manuels des outils. On trouve par exemple le manuel d'utilisation de Qt Creator.

`Archives and Snapshots`

Ce sont des archives de la documentation de Qt.

Lire la documentation d'une classe

Durant ce chapitre, nous allons nous exercer à lire la documentation d'une classe avec celle de QLabel.

Les sections de la documentation de la classe

`QLabel Class`

Comme notre classe s'appelle QLabel, la première section s'appelle ainsi.

On y trouve tout d'abord une petite phrase qui résume l'utilité de la classe.

Ensuite, il y a un tableau, composé des lignes suivantes :

Header : c'est le code à insérer pour pouvoir utiliser la classe (mais importer le module de la classe marche très bien). Dans ce cas : #include <QLabel>.
qmake : dans le fichier .pro, on peut voir après les commentaires des lignes qui permettent d'utiliser le widget. En l’occurrence : QT += widgets.
Inherits : cette case indique la classe mère du widget. Ici, c'est QFrame.
Inherits by : cette ligne n'y est pas tout le temps, comme dans ce cas. Elle indique les classes filles de celle-ci. Si nous étions dans la classe QFrame, il y aurait entre autres marqué QLabel.

À la fin, il y a deux lignes :

List of all members, including inherited members : c'est la liste de toutes les propriétés, variables, etc... de la classe, y compris ceux dont la classe hérite.
Obsolete members : c'est la liste des membres obsolètes de la classe.

`Properties`

On trouve ici la liste des propriétés de la classe. On peut voir par exemple : alignment, hasSelectedText, indent, etc... Si nous décortiquons une de ces propriétés, par exemple alignment, il y est ensuite marqué Qt::Alignment. C'est le type de valeur qu'accepte la variable, dont en l'occurrence, c'est un namespace.

Après cette liste, il y a encore trois lignes. On peut lire 6 properties inherited from QFrame. Cela veut dire que 6 attributs de la classe proviennent de QFrame.

`Public Functions`

Deux mots transparents pas bien compliqués, la liste des fonctions publiques. Au début, on trouve bien évidemment le constructeur (ou plusieurs constructeurs). Ensuite apparaissent différentes fonctions. La première colonne indique ce que renvoie la fonction (si elle ne renvoie rien, c'est void), et la seconde la fonction et ses arguments.

`Reimplemented Public Functions`

Ce sont les fonctions ré-implémentées. La plupart sont des fonctions dont la classe hérite, mais d'autres sont directement écrites dans la classe.

`Public Slots`

Ce sont les slots de la classe. Le tableau est écrit de la même façon que pour les fonctions. Sont aussi inscrites celles dont la classe hérite.

`Signals`

Ce sont les signaux que peut envoyer la classe. De la même manière, ce tableau ressemble beaucoup à celui des slots.

`Static Public Members`

Ce sont les membres qui restent fixes dans la classe.

`Reimplement Protected Functions`

Ici, on peut voir la liste des fonctions protected.

`Detailed Description`

Cette section est la première de la non-présentation. Ici on a un résumé très long de la classe, en expliquant les fonctionnalités.

`Property Documentation`

Dans cette section, on peut voir les explications des propriétés (variables) de la classe, qui ont chacune leur section.

`Member Function Documentation`

Exactement comme la section précédente, à l'exception qu'on explique cette fois-ci des fonctions et non des propriétés.

Lire la documentation d'une fonction

Maintenant, nous allons apprendre à lire la documentation d'une fonction. Pour cela, j'ai choisi une fonction (toujours de QLabel) ni trop facile, ni trop difficile. Nous allons étudier setBuddy(QWidget * buddy), qui pourra peut-être vous servir plus tard dans vos projets.

Tout d'abord, il faut lire la documentation en anglais pour savoir de quoi on parle. Parfois, juste une phrase peut faire l'affaire :

Sets this label's buddy to buddy.

Nous lisons ici, car le mot le plus important est transparent, que cela sert pour créer un label d'un autre widget. Le code nous explique le principal. On peut voir qu'on doit créer un widget (la documentation utilise des champs, utilisation la plus courante), et notre QLabel, puis que nous devons utiliser la méthode setBuddy(), qui accepte en paramètre notre widget.

QLineEdit *prenom = new QLineEdit();
QLabel *labelPrenom = new QLabel("Prénom");
labelPrenom->setBuddy(prenom);

Vous pouvez compiler, et hop, nous avons un magnifique champ de texte avec son label où on peut lire “Prénom”.

Lire la documentation d'un signal

Toujours dans la classe QLabel, nous allons cette fois-ci apprendre à lire la documentation d'un signal. Voici donc le signal que nous allons étudier : linkHovered(const QString &link). Vous l'avez compris, nous allons donc tout d'abord lire le texte de présentation du signal.

This signal is emitted when the user hovers over a link. The URL referred to by the anchor is passed in link.

This function was introduced in Qt 4.2.

On peut donc lire (l'anglais n'est pas très difficile) que le signal est émis quand l'utilisateur passe la souris sur un lien du texte, et que le signal envoie l'URL de ce lien. Nous lisons la suite de cette section.

See also linkActivated().

La documentation nous invite à regarder cet autre signal, semblant à celui-ci. Je vous laisse donc le faire. Mais pour ce signal, on peut espérer quelque chose comme ceci, qui peut être intéressant :

QLabel *monTexte = new QLabel("Apprenez Qt avec <a href='https://fr.wikibooks.org'>Wikilivres</a>.");
QLabel *lienSurvole = new QLabel("Vous ne survolez aucun lien.");
connect(monTexte, SIGNAL(linkHovered(QString)), lienSurvole, SLOT(setText("Le dernier lien survolé est" + QString + ".")))

Lire la documentation d'un slot

Vous avez vu, dans le dernier bout de code, nous avons utiliser le slot setText(const QString &). Eh oui, vous l'avez deviné, nous allons étudier ce slot.

Tout d'abord, on peut voir que le slot n'a pas sa section, mais c'est bien dans la propriété que modifie le slot qu'il y a sa documentation.

Première chose, comme tout le temps, lire le texte. Comme pour la fonction, juste un phrase suffit pour comprendre le principe de cette propriété (et donc du slot) :

This property holds the label's text.

La première phrase nous dit que la propriété contient le texte que le label affiche. Et notre slot, alors ? Eh bien, dans le tableau à la fin de la section, on a le prototype du slot, et il ne reste plus qu'à l'utiliser. Vous pouvez tout simplement regarder plus haut au lieu de réécrire le code, mais sachez que ce slot, comme beaucoup d'autres, peut être utilisé comme fonction sans avoir besoin d'un signal.