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 selon la complexité de la classe. Vous pouvez donc retrouver tout ce dont vous avez besoin de savoir sur une classe en lisant une seule page.
Bon, j'ai dit qu'on allait prendre une classe de Qt au hasard. Alors, voyons voir... sur qui ça va tomber... ah ! Je sais :
Lorsque vous connaissez le nom de la classe et que vous voulez lire sa documentation, utilisez le champ de recherche en haut du menu. Vous pouvez aussi passer par le lien "All Classes" depuis le sommaire.
Vous devriez avoir une longue page qui s'affiche sous vos yeux ébahis, et qui commence par quelque chose comme ça :
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 !
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, comme le montre la capture d'écran ci-contre.
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 à utiliser la classe. Je vous recommande de toujours lire cette introduction quand vous travaillez avec une classe que vous ne connaissiez pas jusqu'alors.
Ça 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 :
Code : C++
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 que QWidget est le parent de QLineEdit. Donc QLineEdit récupère toutes les propriétés de QWidget. Ça a son importance comme nous allons le voir...
Voilà pour l'intro !
Maintenant, voyons voir les sections qui suivent...
Les classes définissent parfois des types de données personnalisés, sous la forme de ce qu'on appelle des énumérations (j'en ai parlé dans mon cours de C pour ceux qui auraient un trou de mémoire !).
Ici, QLineEdit définit l'énumération EchoMode qui propose plusieurs valeurs : Normal, NoEcho, Password, etc.
Une énumération ne s'utilise pas "telle quelle". C'est juste une liste de valeurs, que vous pouvez renvoyer à une méthode spécifique qui en a besoin. Dans le cas de QLineEdit, c'est la méthode setEchoMode(EchoMode) qui en a besoin, car elle n'accepte que des données de type EchoMode..
Pour envoyer la valeur "Password", il faudra écrire : setEchoMode(QLineEdit::Password).
Vous avez là toutes les propriétés d'une classe que vous pouvez lire et modifier.
Euh, ce ne sont pas des attributs ça par hasard ?
Si. Mais la doc ne vous affiche que les attributs pour lesquels Qt définit des accesseurs. Il y a de nombreux attributs "internes" à chaque classe que la doc 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 texte QLineEdit.
Comme indiqué dans la doc, text est 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 :
Code : C++ | QLineEdit monChamp("Contenu du champ");
QString contenu = monChamp.text();
|
Pour modifier le texte présent dans le champ, on écrira :
Code : C++ | QLineEdit monChamp;
monChamp.setText("Entrez votre nom ici");
|
Vous remarquerez que dans la doc, la propriété text est un lien.
Cliquez dessus. Cela vous amènera plus bas sur la même page vers une description de la propriété (que fait-elle ? à quoi sert-elle ?).
On vous y donne aussi le prototype des accesseurs :
- QString text () const
- void setText ( const QString & )
Et enfin, parfois vous verrez comme là une mention "See also" (voir aussi) qui vous invite à aller voir d'autres propriétés ou méthodes de la classe qui ont un rapport avec celle que vous êtes en train de lire. Ici, on vous dit que les méthodes insert() et clear() 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 lire.
TRES IMPORTANT : dans la liste des propriétés en haut de la page, notez les mentions "
56 properties inherited from QWidget", et "
1 property inherited from QObject". Comme QLineEdit hérite de QWidget, qui lui-même hérite de QObject, il possède du coup toutes les propriétés et toutes les méthodes de ses classes parentes !
En clair, les propriétés que vous voyez là ne sont qu'un tout petit bout des possibilités offertes par QLineEdit. Si vous cliquez sur le lien QWidget, on vous amène vers la
liste des propriétés de QWidget.
Vous disposez aussi de toutes ces propriétés dans un QLineEdit !
Vous pouvez donc utiliser la propriété width (largeur) qui est définie dans QWidget pour modifier la largeur de votre QLineEdit. Toute la puissance de l'héritage est là ! Tous les widgets possèdent donc ces propriétés "de base", ils n'ont plus qu'à définir des propriétés qui leur sont spécifiques.
J'insiste bien dessus car au début je me disais souvent : "
Mais pourquoi il y a aussi peu de choses dans cette classe ?". En fait, il ne faut pas s'y fier et toujours regarder les classes parentes dont hérite la classe qui vous intéresse. Tout ce que les classes parentes possèdent, vous y avez accès aussi.
C'est bien souvent la section la plus importante. Vous y trouverez toutes les méthodes publiques (parce que les 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éressant pour savoir comment créer un objet à partir de cette classe ;
- les accesseurs de la classe (comme text() et setText() 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
A 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 2 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 que parent est un pointeur vers le widget qui "contiendra" notre QLineEdit (par exemple une fenêtre), et que contents est le texte qui doit être écrit dans le QLineEdit par défaut.
Cela veut dire, si on prend en compte que le paramètre parent est facultatif, qu'on peut créer un objet de type QLineEdit de 4 façons différentes :
Code : C++ | 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éthode
setAlignment(), mais elle demande un paramètre de type Qt::Alignment. Comment je lui donne ça moi, je connais pas les Qt::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 de Qt::Alignment. Qu'est-ce que c'est que ce type ?
La solution pour savoir
comment envoyer un paramètre de type Qt::Alignment consiste à cliquer dans la doc sur le lien
Qt::Alignment (eh oui, ce n'est pas un lien par hasard !).
Ce lien vous amènera vers une page qui vous explique ce qu'est le type Qt::Alignment.
Il peut y avoir 2 types différents :
- Les énumérations : Qt::Alignment en 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 de Qt::Alignment, par exemple Qt::AlignCenter. La méthode pourra donc être appelée comme ceci :
Code : C++ | 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.
Prenons par exemple setValidator, qui attend un pointeur vers un QValidator. La méthode setValidator vous dit qu'elle permet de vérifier si l'utilisateur a rentré un texte valide, ce qui peut être utile si vous voulez vérifier que l'utilisateur a bien rentré un nombre entier et non pas "Bonjour ça va ?" quand vous lui demandez son âge...
Si vous cliquez sur le lien QValidator, on vous emmène vers la page qui explique comment utiliser la classe QValidator. 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. QValidator est une classe abstraite (c'est ce que vous dit l'intro de sa doc), ce qui signifie qu'on ne peut pas créer d'objet de type QValidator et qu'il faut utiliser une de ses classes filles 
Au tout début, la page de la doc de QValidator vous dit "Inherited by QDoubleValidator, QIntValidator, and QRegExpValidator". Cela signifie que ces classes héritent de QValidator et 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 dans le chapitre sur l'héritage.
Nous, nous voulons autoriser uniquement la personne à rentrer un nombre entier, nous allons donc utiliser QIntValidator. 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 faire comme ceci :
Code : C++ | QValidator *validator = new QIntValidator(0, 150, this);
monChamp.setValidator(validator);
|
... pour s'assurer que la personne ne rentrera qu'un nombre compris entre 0 et 150 ans (ça 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, et même des fois là d'aller voir les classes filles.
Ça 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 doc pour arriver enfin à envoyer à cette $%@#$#% de méthode un objet du type qu'elle attend !
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
slot undo() annule la dernière opération de l'utilisateur.
Vous pouvez l'appeler comme une bête méthode :
Code : C++
... mais la particularité du fait que undo() soit un slot, c'est que vous pouvez aussi le connecter à un autre widget. Par exemple, on peut imaginer un menu Edition / Annuler dont le signal "cliqué" sera connecté au slot "undo" du champ de texte
Tous les slots offerts par QLineEdit ne sont pas dans cette liste. Je me permets de vous rappeler une fois de plus qu'il faut penser à regarder les mentions comme "19 public slots inherited from QWidget", qui vous invitent à aller voir les slots de QWidget auxquels vous avez aussi accès.
C'est ainsi que vous découvrez que vous disposez du slot hide() qui permet de masquer votre QLineEdit.
C'est la liste des signaux que peut envoyer un QLineEdit.
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 du QLineEdit. 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 QWidget et QObject, car ils appartiennent aussi à la classe QLineEdit. Je sais que je suis lourd à force de répéter ça, inutile de me le dire, je le fais exprès pour que ça rentre
Ce sont des méthodes protégées. Elles ne sont ni public, ni private, mais protected.
Comme on l'a vu dans le 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 sur QLineEdit.
Il est très fréquent d'hériter des classes de Qt, on l'a d'ailleurs déjà fait avec QWidget pour créer une fenêtre personnalisée. Si vous héritez de QLineEdit, 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 QLineEdit ne définit pas de méthodes statiques, mais elle en possède quelques-unes héritées de QWidget et QObject.
Je vous rappelle qu'une méthode statique est une méthode qui peut être appelée sans avoir eu à créer d'objet. C'est un peu comme une fonction.
Il n'y a rien de bien intéressant avec QLineEdit, mais sachez par exemple que la classe QString possède de nombreuses méthodes statiques, comme number() qui convertit le nombre donné en une chaîne de caractères de type QString.
Code : C++ | QString maChaine = QString::number(12);
|
Une méthode statique s'appelle comme ceci :
NomDeLaClasse::nomDeLaMethode().
On a déjà vu tout ça 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.
Apprendre à lire la documentation de Qt
zagaba
Trouvez une formation
Suggestions
Flux RSS News
Twitter
Facebook
Google+