Débuter avec Plasma

La fonction boundingRect() indique à Plasma la taille effective du plasmoïde. Elle est importante, car on a besoin de savoir quelle surface est occupée à l'écran.

En cas de problème avec le plasmoïde qui laisse des pixels derrière lui lorsqu'il est déplacé, ceci est habituellement dû à une implémentation incorrecte de boundingRect().

contentsRect() peut être considérée comme la fonction principale, puisqu'elle dessine le plasmoïde à l'écran. C'est ici que l'on définit l'apparence du plasmoïde. On ne devrait dessiner que dans les limites définies par contentsRect() et éviter d'utiliser geometry(). Lorsqu'un plasmoïde n'a pas d'arrière-plan standard, par exemple s'il a été désactivé par un appel à setBackgroundHints() ou s'il se trouve dans le panel, geometry() et boundingRect() se comportent de la même manière. Cependant, lorsque l'arrière-plan standard est activé (ce qui est habituellement le cas), l'applet sera dotée d'une bordure dans laquelle elle ne doit pas dessiner.

Cette simple ligne est très importante, car elle établit le lien entre le nom de la classe et le nom de l'applet dans le fichier .desktop. Si l'applet semble ne pas se charger, cela peut être dû à une différence entre cette déclaration et le fichier .desktop.

K_EXPORT_PLASMA_APPLET ajoute "plasma_applet_" devant le nom. Pensez-y lorsque vous remplissez votre fichier .desktop afin d'éviter une différence dans le nom.

Comme on peut le voir dans cet exemple, on utilise un objet Plasma::Svg. Quelques points importants sont à noter ici.

Tout d'abord, on utilise un chemin relatif, widgets/background, ce qui amène Plasma::Svg à utiliser Plasma::Theme pour localiser les données SVG. Bien que Plasma::Svg puisse charger n'importe quel fichier à partir d'un chemin absolu, utiliser des chemins relatifs au thème aussi souvent que possible permet de personnaliser l'apparence de Plasma. Chacun des plasmoïdes apparaît alors comme un ensemble homogène plutôt que comme un ensemble d'applications séparées et sans liens entre elles. On peut obtenir une liste des composants graphiques disponibles sur la page de thème Plasma (en anglais).

Dans les deux cas, Plasma::Svg peut être utilisée pour ne dessiner qu'un sous-ensemble du fichier SVG en lui passant l'identifiant d'un élément apparaissant dans le document SVG. Le fichier clock.svg en est un bon exemple. En l'ouvrant, on constate qu'il est constitué d'un arrière-plan, de trois aiguilles (heures, minutes et secondes) et d'un avant-plan (le verre). Grâce à sa capacité à placer tous les éléments dans un même fichier, le document SVG affiche une horloge. Ceci est bien plus pratique pour les artistes que de créer cinq fichiers séparés et de les imaginer superposés les uns aux autres et aussi bien plus performant, puisqu'un seul rendu SVG et une seule lecture de fichier sont nécessaires.

Comme le dessin de l'arrière-plan est une fonction courante, il existe un moyen plus simple pour le faire. En ajoutant setBackgroundHints(DefaultBackground) dans le code, l'arrière-plan par défaut de Plasma sera dessiné derrière le plasmoïde, ce qui économise et du temps et du code, mais ce qui permet également d'offrir à l'utilisateur une présentation plus homogène.

Dans le constructeur de l'exemple, le dialogue avec Plasma se cantonne à lui parler de l'arrière-plan et du fichier de configuration. Mais on peut également fixer la taille initiale du plasmoïde. Une fois cela fait, Plasma s'occupera de tout changement de taille et on n'aura plus à s'en soucier. Dans la méthode init(), il faut initialiser tout ce qui doit l'être, comme lire et appliquer des données de configuration.

Si, pour une raison quelconque, l'applet ne parvient pas à démarrer (la bibliothèque n'a pas pu être chargée, un pilote matériel nécessaire n'a pas été trouvé, etc.), cette méthode retourne true. L'utilisation de cette fonction donne une occasion à votre application de faire un peu de ménage avant de s'arrêter.

Lorsque l'applet ne parvient pas à démarrer, cette fonction permet d'informer Plasma en fournissant optionnellement une raison. Plasma affichera alors une interface d'erreur standard pour informer l'utilisateur de la situation et, à partir de ce moment, les méthodes dessinant votre applet à l'écran ne seront plus appelées. Si le plasmoïde devient plus complexe et dépend de facteurs multiples pour démarrer, cette fonction est la meilleure façon de faire le ménage en cas d'échec.

Si on souhaite se connecter aux DataEngines de Plasma, on peut implémenter la méthode dataUpdated() dans le plasmoïde. Lorsqu'un DataEngine est directement connecté à la sous-classe de l'applet, dataUpdated() sera appelée à chaque fois que le DataEngine enverra des données mises à jour.

Si l'applet a besoin de connaître quelles sont sa taille et sa géométrie, on utilise contentsRect() et contentsRect().size(). Il faut éviter d'appeler geometry() et size(), car ces deux fonctions ne prennent pas en compte la taille de la marge fixée par l'arrière-plan par défaut des applets, également éviter d'utiliser des coordonnées absolues pour positionner les éléments de l'applet, comme QPoint(0, 0) pour se référer au coin en haut à gauche de l'applet. À la place, il est préférable d'utiliser contentsRect().topLeft().