QIcon

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

#include <QIcon>

Voir la position dans l'arbre des classes.

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,
                                    isChecked() ? 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.

QString QIcon::name () const

Retourne le nom utilis� pour cr�er l'ic�ne, s'il est disponible.

En fonction de la mani�re dont l'ic�ne a �t� cr��e, elle peut avoir un nom associ�. C'est le cas pour des ic�nes cr�er avec fromTheme() ou des ic�nes utilisant un QIconEngine qui supporte le QIconEngineV2::IconNameHook.

Cette fonction a �t� introduite dans Qt 4.7.

Voir aussi fromTheme() et QIconEngine.

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 !