QIcon

La classe QIcon fournit des icônes étirables dans différents modes et états. Plus d'informations...

#include <QIcon>

Description détaillée

La classe QIcon fournit des icônes étirables dans différents modes et états.

Un QIcon peut générer des pixmaps petits ou larges, actifs ou non, depuis l'ensemble des pixmaps qu'on lui donne. De tels pixmaps sont utilisés par les widgets de Qt pour afficher une icône représentant une action particulière.

L'utilisation la plus simple de QIcon est d'en créer une à partir d'un fichier ou d'une ressource QPixmap, puis de l'utiliser, autorisant Qt à établir tous les styles et dimensions d'icônes requises. Par exemple :

QToolButton *button = new QToolButton;
button->setIcon(QIcon("open.xpm"));

Pour défaire une QIcon, définissez simplement une icône nulle à la place :

button->setIcon(QIcon());

Utilisez les fonctions QImageReader::supportedImageFormats() et QImageWriter::supportedImageFormats() pour récupérer une liste complète des formats de fichiers supportés.

Lorsque vous récupérez un pixmap en utilisant pixmap(QSize, Mode, State) et qu'aucun pixmap n'a été ajouté avec addFile() ou addPixmap() pour les dimensions, le mode et l'état donnés, QIcon en générera un au vol. Cette génération de pixmap a lieu dans un QIconEngineV2. Le moteur par défaut réduit les pixmaps si demandé mais ne les étire jamais et utilise le style actuel pour calculer une apparence désactivée. Par l'utilisation de moteurs d'icônes personnalisés, vous pouvez personnaliser tout aspect des icônes générées. Avec QIconEnginePluginV2, il est possible d'enregistrer les différents moteurs d'icônes pour différents suffixes de fichier, rendant cela possible pour les tiers de fournir un moteur d'icônes additionnel à celui inclus avec Qt.

Note : depuis Qt 4.2, un moteur d'icônes supportant le SVG est inclus.

Création de classes qui utilisent QIcon

Si vous écrivez vos propres widgets qui ont une option pour choisir un pixmap de petite taille, étudiez la possibilité de mettre une QIcon pour ce pixmap. La classe QToolButton est un exemple d'un tel widget.

Fournissez une méthode pour mettre une QIcon et quand vous dessinez l'icône, choisissez quel pixmap est approprié pour l'état actuel du widget. Par exemple :

 void MyWidget::drawIcon(QPainter *painter, QPoint pos)
 {
     QPixmap pixmap = icon.pixmap(QSize(22, 22),
                                    isEnabled() ? QIcon::Normal
                                                : QIcon::Disabled,
                                    isOn() ? QIcon::On
                                           : QIcon::Off);
     painter->drawPixmap(pos, pixmap);
 }

Vous pourriez aussi utiliser le mode Active, en rendant peut-être votre widget actif quand la souris est sur celui-ci (voir QWidget::enterEvent()), pendant qu'un bouton de la souris est pressé jusqu'au relâchement qui activera le bouton ou bien quand il est l'item actuellement sélectionné. Si le widget peut être activé, le mode « On » devrait être utilisé pour afficher une autre icône.

Voir aussi Livre design d'interface graphique utilisateur : texte de l'icône et Exemple Icons.

Propriétés

enum QIcon::Mode

Ce type d'énumération décrit le mode pour lequel un pixmap sera utilisé. Les modes actuellement définis sont :

enum QIcon::State

Cette énumération décrit l'état pour lequel un pixmap sera utilisé. Le state peut être :

Fonctions membres

QIcon::QIcon ()

Construit une icône nulle.

QIcon::QIcon ( const QPixmap & pixmap )

Construit une icône à partir d'un pixmap pixmap.

QIcon::QIcon ( const QIcon & other )

Construit une copie de other. Cette opération est très rapide.

QIcon::QIcon ( const QString & fileName )

Construit une icône à partir du fichier fileName. Le fichier sera chargé sur demande.

Si fileName contient un chemin relatif (par exemple, juste le nom du fichier), le fichier adéquat doit se trouver relativement au répertoire de travail à l'exécution.

Le nom du fichier peut soit se référer à un fichier présent sur le disque dur ou à une ressource de l'application. Voir l'aperçu sur les ressources pour des détails sur la manière d'embarquer des images et d'autres fichiers dans l'exécutable de l'application.

Utiliser les fonctions QImageReader::supportedImageFormats() et QImageWriter::supportedImageFormats() pour récupérer une liste complète des formats de fichiers supportés.

QIcon::QIcon ( QIconEngine * engine )

Crée une icône avec le moteur engine. L'icône devient propriétaire du moteur.

QIcon::QIcon ( QIconEngineV2 * engine )

Crée une icône avec le moteur engine. L'icône devient propriétaire du moteur.

QIcon::~QIcon ()

Détruit l'icône.

QSize QIcon::actualSize ( const QSize & size, Mode mode = Normal, State state = Off ) const

Retourne la taille effective de l'icône pour la taille size, le mode mode et l'état state demandés. La taille retournée sera peut-être plus petite que celle demandée mais jamais plus grande.

Voir aussi pixmap() et paint().

void QIcon::addFile ( const QString & fileName, const QSize & size = QSize(), Mode mode = Normal, State state = Off )

Ajoute une image du fichier fileName à l'icône, avec une spécialisation pour la taille, le mode et l'état. Le fichier sera chargé à la demande. Note : les moteurs personnalisés d'icônes sont libres d'ignorer les pixmaps additionnels ajoutés.

Si fileName contient un chemin relatif (comme le nom du fichier), le fichier adéquat doit se trouver relativement au répertoire de travail à l'exécution.

Le nom du fichier peut se référer soit à un fichier réellement présent sur le disque, soit à une ressource de l'application. Voir l'aperçu sur les ressources pour des détails sur la manière d'embarquer des images et d'autres fichiers dans l'exécutable de l'application.

Utilisez les fonction QImageReader::supportedImageFormats() et QImageWriter::supportedImageFormats() pour récupérer une liste complète des formats de fichiers supportés.

Note : quand vous ajoutez un nom de fichier non vide à un QIcon, l'icône devient non nulle, même si le fichier n'existe pas ou est corrompu.

Voir aussi addPixmap().

void QIcon::addPixmap ( const QPixmap & pixmap, Mode mode = Normal, State state = Off )

Ajoute pixmap à l'icône, en tant que spécialisation pour le mode mode et l'état state.

Les moteurs personnalisés sont libres d'ignorer les pixmaps additionnels ajoutés.

Voir aussi addFile().

QList<QSize> QIcon::availableSizes ( Mode mode = Normal, State state = Off ) const

Retourne une liste des tailles d'icônes disponibles pour le mode mode et l'état state spécifiés.

Cette fonction a été introduite dans Qt 4.5.

qint64 QIcon::cacheKey () const

Retourne un nombre qui identifie le contenu de cet objet QIcon. Des objets QIcon distincts peuvent avoir la même clé s'ils font référence au même contenu.

La cacheKey() change quand l'icône est altérée via addPixmap() ou addFile().

Les clés de cache sont principalement utiles en conjonction avec un cache.

Cette fonction a été introduite dans Qt 4.3.

Voir aussi QPixmap::cacheKey().

QIcon QIcon::fromTheme ( const QString & name, const QIcon & fallback = QIcon() ) [static]

Retourne le QIcon correspondant au nom name dans le thème d'icônes actuel. S'il n'y a pas de telle icône trouvée dans le thème actuel, fallback est retourné à la place.

La dernière spécification des icônes freedesktop et les spécifications de nommage peuvent être obtenues ici : http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html

Pour récupérer une icône du thème d'icônes actuel :

QIcon undoicon = QIcon::fromTheme("edit-undo");}

Si vous voulez fournir un retrait garanti pour les plateformes qui ne supportent pas les thèmes d'icônes, vous pouvez utiliser le second argument :

QIcon undoicon = QIcon::fromTheme("edit-undo", QIcon(":/undo.png"));

Note : par défaut, seul X11 supporte les thèmes d'icônes. Pour utiliser ces thèmes sur Mac OS X et Windows, vous devez fournir un thème compatible dans votre themeSearchPaths() et utiliser le themeName() approprié.

Cette fonction a été introduite dans Qt 4.6.

Voir aussi themeName(), setThemeName() et themeSearchPaths().

bool QIcon::hasThemeIcon ( const QString & name ) [static]

Retourne true s'il y a une icône disponible du nom name dans le thème d'icônes actuel, sinon retourne false.

Cette fonction a été introduite dans Qt 4.6.

Voir aussi themeSearchPaths(), fromTheme() et setThemeName().

bool QIcon::isNull () const

Retourne true si l'icône est vide ; sinon retourne false.

Une icône est vide si elle n'a ni pixmap ni nom de fichier.

Note : même une icône non nulle peut créer des pixmaps valides, par exemple si le fichier n'existe pas ou ne peut pas être lu.

void QIcon::paint ( QPainter * painter, const QRect & rect, Qt::Alignment alignment = Qt::AlignCenter, Mode mode = Normal, State state = Off ) const

Utilise le peintre pour peindre l'icône avec l'alignement alignment spécifié, le mode mode et l'état state requis dans le rectangle rect.

Voir aussi actualSize() et pixmap().

void QIcon::paint ( QPainter * painter, int x, int y, int w, int h, Qt::Alignment alignment = Qt::AlignCenter, Mode mode = Normal, State state = Off ) const

Il s'agit d'une fonction surchargée.

Peint l'icône dans le rectangle QRect(x, y, w, h).

QPixmap QIcon::pixmap ( const QSize & size, Mode mode = Normal, State state = Off ) const

Retourne un pixmap avec la taille size, le mode mode et l'état state demandés, en en générant une au besoin. Le pixmap pourrait être plus petit que demandé mais jamais plus grand.

Voir aussi setPixmap(), actualSize() et paint().

QPixmap QIcon::pixmap ( int w, int h, Mode mode = Normal, State state = Off ) const

Il s'agit d'une fonction surchargée.

Retourne un pixmap de taille QSize(w, h). Sa taille peut être inférieure à la demande mais jamais supérieure.

QPixmap QIcon::pixmap ( int extent, Mode mode = Normal, State state = Off ) const

Il s'agit d'une fonction surchargée.

Retourne un pixmap de taille QSize(extent, extent). Sa taille peut être inférieure à la demande mais jamais supérieure.

void QIcon::setThemeName ( const QString & name ) [static]

Met le thème d'icônes actuel à name.

Le nom devrait correspondre à un nom de répertoire dans le themeSearchPath(), contenant un fichier index.theme décrivant son contenu.

Cette fonction a été introduite dans Qt 4.6.

Voir aussi themeSearchPaths() et themeName().

void QIcon::setThemeSearchPaths ( const QStringList & paths ) [static]

Définit les chemins de recherche pour les thèmes d'icônes à paths.

Cette fonction a été introduite dans Qt 4.6.

Voir aussi themeSearchPaths(), fromTheme() et setThemeName().

QString QIcon::themeName () [static]

Retourne le nom du thème d'icônes actuel.

Sur X11, le thème d'icônes actuel dépend des paramètres du bureau. Sur d'autres plateformes, il n'est pas mis par défaut.

Cette fonction a été introduite dans Qt 4.6.

Voir aussi setThemeName(), themeSearchPaths(), fromTheme() et hasThemeIcon().

QStringList QIcon::themeSearchPaths () [static]

Retourne les chemins de recherche pour des thèmes d'icônes.

La valeur par défaut dépend de la plateforme :

Sous X11, le chemin va utiliser la variable d'environnement XDG_DATA_DIRS, si disponible .

Par défaut, toutes les plateformes se rabattent sur le répertoire :\icons ; vous pouvez utiliser rcc -project pour générer un fichier de ressources pour votre thème d'icônes.

Cette fonction a été introduite dans Qt 4.6.

Voir aussi setThemeSearchPaths(), fromTheme() et setThemeName().

QIcon::operator QVariant () const

Retourne l'icône comme un QVariant.

QIcon & QIcon::operator= ( const QIcon & other )

Affecte l'icône other à cette icône et en retourne une référence.

En relation mais non membres de la classe

QDataStream & operator<< ( QDataStream & stream, const QIcon & icon )

Écrit l'icône icon donnée dans le flux stream donné comme une image PNG. Si l'icône contient plus d'une image, toutes seront écrites sur le flux. Notez que diriger ce flux vers un fichier ne produira pas un fichier d'image valide.

Cette fonction a été introduite dans Qt 4.2.

QDataStream & operator>> ( QDataStream & stream, QIcon & icon )

Lit une image ou un ensemble d'images d'un flux stream donné dans une icône icone donnée.

Cette fonction a été introduite dans Qt 4.2.

Remerciements

Merci à Louis du Verdier et à Abdelhafid Hafidi pour la traduction, à Thibaut Cuvelier pour l'effort de traduction et de relecture ainsi qu'à Jonathan Courtois et Jacques Thery pour la relecture !