1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtGui module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qicon.h"

    43 #include "qicon_p.h"

    44 #include "qiconengine.h"

    45 #include "qiconengineplugin.h"

    46 #include "private/qfactoryloader_p.h"

    47 #include "private/qiconloader_p.h"

    48 #include "qapplication.h"

    49 #include "qstyleoption.h"

    50 #include "qpainter.h"

    51 #include "qfileinfo.h"

    52 #include "qstyle.h"

    53 #include "qpixmapcache.h"

    54 #include "qvariant.h"

    55 #include "qcache.h"

    56 #include "qdebug.h"

    57 #include "private/qguiplatformplugin_p.h"

    58 

    59 #ifdef Q_WS_MAC

    60 #include <private/qt_mac_p.h>

    61 #include <private/qt_cocoa_helpers_mac_p.h>

    62 #endif

    63 

    64 #ifdef Q_WS_X11

    65 #include "private/qt_x11_p.h"

    66 #include "private/qkde_p.h"

    67 #endif

    68 

    69 QT_BEGIN_NAMESPACE

    70 

    71 /*!

    72     \enum QIcon::Mode

    73 

    74     This enum type describes the mode for which a pixmap is intended

    75     to be used. The currently defined modes are:

    76 

    77     \value Normal

    78          Display the pixmap when the user is

    79         not interacting with the icon, but the

    80         functionality represented by the icon is available.

    81     \value Disabled

    82          Display the pixmap when the

    83         functionality represented by the icon is not available.

    84     \value Active

    85          Display the pixmap when the

    86         functionality represented by the icon is available and

    87         the user is interacting with the icon, for example, moving the

    88         mouse over it or clicking it.

    89    \value Selected

    90         Display the pixmap when the item represented by the icon is

    91         selected.

    92 */

    93 

    94 /*!

    95   \enum QIcon::State

    96 

    97   This enum describes the state for which a pixmap is intended to be

    98   used. The \e state can be:

    99 

   100   \value Off  Display the pixmap when the widget is in an "off" state

   101   \value On  Display the pixmap when the widget is in an "on" state

   102 */

   103 

   104 static QBasicAtomicInt serialNumCounter = Q_BASIC_ATOMIC_INITIALIZER(1);

   105 

   106 QIconPrivate::QIconPrivate()

   107     : engine(0), ref(1),

   108     serialNum(serialNumCounter.fetchAndAddRelaxed(1)),

   109     detach_no(0),

   110     engine_version(2),

   111     v1RefCount(0)

   112 {

   113 }

   114 

   115 QPixmapIconEngine::QPixmapIconEngine()

   116 {

   117 }

   118 

   119 QPixmapIconEngine::QPixmapIconEngine(const QPixmapIconEngine &other)

   120     : QIconEngineV2(other), pixmaps(other.pixmaps)

   121 {

   122 }

   123 

   124 QPixmapIconEngine::~QPixmapIconEngine()

   125 {

   126 }

   127 

   128 void QPixmapIconEngine::paint(QPainter *painter, const QRect &rect, QIcon::Mode mode, QIcon::State state)

   129 {

   130     QSize pixmapSize = rect.size();

   131 #if defined(Q_WS_MAC)

   132     pixmapSize *= qt_mac_get_scalefactor();

   133 #endif

   134     painter->drawPixmap(rect, pixmap(pixmapSize, mode, state));

   135 }

   136 

   137 static inline int area(const QSize &s) { return s.width() * s.height(); }

   138 

   139 // returns the smallest of the two that is still larger than or equal to size.

   140 static QPixmapIconEngineEntry *bestSizeMatch( const QSize &size, QPixmapIconEngineEntry *pa, QPixmapIconEngineEntry *pb)

   141 {

   142     int s = area(size);

   143     if (pa->size == QSize() && pa->pixmap.isNull()) {

   144         pa->pixmap = QPixmap(pa->fileName);

   145         pa->size = pa->pixmap.size();

   146     }

   147     int a = area(pa->size);

   148     if (pb->size == QSize() && pb->pixmap.isNull()) {

   149         pb->pixmap = QPixmap(pb->fileName);

   150         pb->size = pb->pixmap.size();

   151     }

   152     int b = area(pb->size);

   153     int res = a;

   154     if (qMin(a,b) >= s)

   155         res = qMin(a,b);

   156     else

   157         res = qMax(a,b);

   158     if (res == a)

   159         return pa;

   160     return pb;

   161 }

   162 

   163 QPixmapIconEngineEntry *QPixmapIconEngine::tryMatch(const QSize &size, QIcon::Mode mode, QIcon::State state)

   164 {

   165     QPixmapIconEngineEntry *pe = 0;

   166     for (int i = 0; i < pixmaps.count(); ++i)

   167         if (pixmaps.at(i).mode == mode && pixmaps.at(i).state == state) {

   168             if (pe)

   169                 pe = bestSizeMatch(size, &pixmaps[i], pe);

   170             else

   171                 pe = &pixmaps[i];

   172         }

   173     return pe;

   174 }

   175 

   176 

   177 QPixmapIconEngineEntry *QPixmapIconEngine::bestMatch(const QSize &size, QIcon::Mode mode, QIcon::State state, bool sizeOnly)

   178 {

   179     QPixmapIconEngineEntry *pe = tryMatch(size, mode, state);

   180     while (!pe){

   181         QIcon::State oppositeState = (state == QIcon::On) ? QIcon::Off : QIcon::On;

   182         if (mode == QIcon::Disabled || mode == QIcon::Selected) {

   183             QIcon::Mode oppositeMode = (mode == QIcon::Disabled) ? QIcon::Selected : QIcon::Disabled;

   184             if ((pe = tryMatch(size, QIcon::Normal, state)))

   185                 break;

   186             if ((pe = tryMatch(size, QIcon::Active, state)))

   187                 break;

   188             if ((pe = tryMatch(size, mode, oppositeState)))

   189                 break;

   190             if ((pe = tryMatch(size, QIcon::Normal, oppositeState)))

   191                 break;

   192             if ((pe = tryMatch(size, QIcon::Active, oppositeState)))

   193                 break;

   194             if ((pe = tryMatch(size, oppositeMode, state)))

   195                 break;

   196             if ((pe = tryMatch(size, oppositeMode, oppositeState)))

   197                 break;

   198         } else {

   199             QIcon::Mode oppositeMode = (mode == QIcon::Normal) ? QIcon::Active : QIcon::Normal;

   200             if ((pe = tryMatch(size, oppositeMode, state)))

   201                 break;

   202             if ((pe = tryMatch(size, mode, oppositeState)))

   203                 break;

   204             if ((pe = tryMatch(size, oppositeMode, oppositeState)))

   205                 break;

   206             if ((pe = tryMatch(size, QIcon::Disabled, state)))

   207                 break;

   208             if ((pe = tryMatch(size, QIcon::Selected, state)))

   209                 break;

   210             if ((pe = tryMatch(size, QIcon::Disabled, oppositeState)))

   211                 break;

   212             if ((pe = tryMatch(size, QIcon::Selected, oppositeState)))

   213                 break;

   214         }

   215 

   216         if (!pe)

   217             return pe;

   218     }

   219 

   220     if (sizeOnly ? (pe->size.isNull() || !pe->size.isValid()) : pe->pixmap.isNull()) {

   221         pe->pixmap = QPixmap(pe->fileName);

   222         if (!pe->pixmap.isNull())

   223             pe->size = pe->pixmap.size();

   224     }

   225 

   226     return pe;

   227 }

   228 

   229 QPixmap QPixmapIconEngine::pixmap(const QSize &size, QIcon::Mode mode, QIcon::State state)

   230 {

   231     QPixmap pm;

   232     QPixmapIconEngineEntry *pe = bestMatch(size, mode, state, false);

   233     if (pe)

   234         pm = pe->pixmap;

   235 

   236     if (pm.isNull()) {

   237         int idx = pixmaps.count();

   238         while (--idx >= 0) {

   239             if (pe == &pixmaps[idx]) {

   240                 pixmaps.remove(idx);

   241                 break;

   242             }

   243         }

   244         if (pixmaps.isEmpty())

   245             return pm;

   246         else

   247             return pixmap(size, mode, state);

   248     }

   249 

   250     QSize actualSize = pm.size();

   251     if (!actualSize.isNull() && (actualSize.width() > size.width() || actualSize.height() > size.height()))

   252         actualSize.scale(size, Qt::KeepAspectRatio);

   253 

   254     QString key = QLatin1String("$qt_icon_")

   255                   + QString::number(pm.cacheKey())

   256                   + QString::number(pe->mode)

   257                   + QString::number(QApplication::palette().cacheKey())

   258                   + QLatin1Char('_')

   259                   + QString::number(actualSize.width())

   260                   + QLatin1Char('_')

   261                   + QString::number(actualSize.height())

   262                   + QLatin1Char('_');

   263 

   264 

   265     if (mode == QIcon::Active) {

   266         if (QPixmapCache::find(key + QString::number(mode), pm))

   267             return pm; // horray

   268         if (QPixmapCache::find(key + QString::number(QIcon::Normal), pm)) {

   269             QStyleOption opt(0);

   270             opt.palette = QApplication::palette();

   271             QPixmap active = QApplication::style()->generatedIconPixmap(QIcon::Active, pm, &opt);

   272             if (pm.cacheKey() == active.cacheKey())

   273                 return pm;

   274         }

   275     }

   276 

   277     if (!QPixmapCache::find(key + QString::number(mode), pm)) {

   278         if (pm.size() != actualSize)

   279             pm = pm.scaled(actualSize, Qt::IgnoreAspectRatio, Qt::SmoothTransformation);

   280         if (pe->mode != mode && mode != QIcon::Normal) {

   281             QStyleOption opt(0);

   282             opt.palette = QApplication::palette();

   283             QPixmap generated = QApplication::style()->generatedIconPixmap(mode, pm, &opt);

   284             if (!generated.isNull())

   285                 pm = generated;

   286         }

   287         QPixmapCache::insert(key + QString::number(mode), pm);

   288     }

   289     return pm;

   290 }

   291 

   292 QSize QPixmapIconEngine::actualSize(const QSize &size, QIcon::Mode mode, QIcon::State state)

   293 {

   294     QSize actualSize;

   295     if (QPixmapIconEngineEntry *pe = bestMatch(size, mode, state, true))

   296         actualSize = pe->size;

   297 

   298     if (actualSize.isNull())

   299         return actualSize;

   300 

   301     if (!actualSize.isNull() && (actualSize.width() > size.width() || actualSize.height() > size.height()))

   302         actualSize.scale(size, Qt::KeepAspectRatio);

   303     return actualSize;

   304 }

   305 

   306 void QPixmapIconEngine::addPixmap(const QPixmap &pixmap, QIcon::Mode mode, QIcon::State state)

   307 {

   308     if (!pixmap.isNull()) {

   309         QPixmapIconEngineEntry *pe = tryMatch(pixmap.size(), mode, state);

   310         if(pe && pe->size == pixmap.size()) {

   311             pe->pixmap = pixmap;

   312             pe->fileName.clear();

   313         } else {

   314             pixmaps += QPixmapIconEngineEntry(pixmap, mode, state);

   315         }

   316     }

   317 }

   318 

   319 void QPixmapIconEngine::addFile(const QString &fileName, const QSize &_size, QIcon::Mode mode, QIcon::State state)

   320 {

   321     if (!fileName.isEmpty()) {

   322         QSize size = _size;

   323         QPixmap pixmap;

   324 

   325         QString abs = fileName;

   326         if (fileName.at(0) != QLatin1Char(':'))

   327             abs = QFileInfo(fileName).absoluteFilePath();

   328 

   329         for (int i = 0; i < pixmaps.count(); ++i) {

   330             if (pixmaps.at(i).mode == mode && pixmaps.at(i).state == state) {

   331                 QPixmapIconEngineEntry *pe = &pixmaps[i];

   332                 if(size == QSize()) {

   333                     pixmap = QPixmap(abs);

   334                     size = pixmap.size();

   335                 }

   336                 if (pe->size == QSize() && pe->pixmap.isNull()) {

   337                     pe->pixmap = QPixmap(pe->fileName);

   338                     pe->size = pe->pixmap.size();

   339                 }

   340                 if(pe->size == size) {

   341                     pe->pixmap = pixmap;

   342                     pe->fileName = abs;

   343                     return;

   344                 }

   345             }

   346         }

   347         QPixmapIconEngineEntry e(abs, size, mode, state);

   348         e.pixmap = pixmap;

   349         pixmaps += e;

   350     }

   351 }

   352 

   353 QString QPixmapIconEngine::key() const

   354 {

   355     return QLatin1String("QPixmapIconEngine");

   356 }

   357 

   358 QIconEngineV2 *QPixmapIconEngine::clone() const

   359 {

   360     return new QPixmapIconEngine(*this);

   361 }

   362 

   363 bool QPixmapIconEngine::read(QDataStream &in)

   364 {

   365     int num_entries;

   366     QPixmap pm;

   367     QString fileName;

   368     QSize sz;

   369     uint mode;

   370     uint state;

   371 

   372     in >> num_entries;

   373     for (int i=0; i < num_entries; ++i) {

   374         if (in.atEnd()) {

   375             pixmaps.clear();

   376             return false;

   377         }

   378         in >> pm;

   379         in >> fileName;

   380         in >> sz;

   381         in >> mode;

   382         in >> state;

   383         if (pm.isNull()) {

   384             addFile(fileName, sz, QIcon::Mode(mode), QIcon::State(state));

   385         } else {

   386             QPixmapIconEngineEntry pe(fileName, sz, QIcon::Mode(mode), QIcon::State(state));

   387             pe.pixmap = pm;

   388             pixmaps += pe;

   389         }

   390     }

   391     return true;

   392 }

   393 

   394 bool QPixmapIconEngine::write(QDataStream &out) const

   395 {

   396     int num_entries = pixmaps.size();

   397     out << num_entries;

   398     for (int i=0; i < num_entries; ++i) {

   399         if (pixmaps.at(i).pixmap.isNull())

   400             out << QPixmap(pixmaps.at(i).fileName);

   401         else

   402             out << pixmaps.at(i).pixmap;

   403         out << pixmaps.at(i).fileName;

   404         out << pixmaps.at(i).size;

   405         out << (uint) pixmaps.at(i).mode;

   406         out << (uint) pixmaps.at(i).state;

   407     }

   408     return true;

   409 }

   410 

   411 void QPixmapIconEngine::virtual_hook(int id, void *data)

   412 {

   413     switch (id) {

   414     case QIconEngineV2::AvailableSizesHook: {

   415         QIconEngineV2::AvailableSizesArgument &arg =

   416             *reinterpret_cast<QIconEngineV2::AvailableSizesArgument*>(data);

   417         arg.sizes.clear();

   418         for (int i = 0; i < pixmaps.size(); ++i) {

   419             QPixmapIconEngineEntry &pe = pixmaps[i];

   420             if (pe.size == QSize() && pe.pixmap.isNull()) {

   421                 pe.pixmap = QPixmap(pe.fileName);

   422                 pe.size = pe.pixmap.size();

   423             }

   424             if (pe.mode == arg.mode && pe.state == arg.state && !pe.size.isEmpty())

   425                 arg.sizes.push_back(pe.size);

   426         }

   427         break;

   428     }

   429     default:

   430         QIconEngineV2::virtual_hook(id, data);

   431     }

   432 }

   433 

   434 #if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)

   435 Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader,

   436     (QIconEngineFactoryInterface_iid, QLatin1String("/iconengines"), Qt::CaseInsensitive))

   437 Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loaderV2,

   438     (QIconEngineFactoryInterfaceV2_iid, QLatin1String("/iconengines"), Qt::CaseInsensitive))

   439 #endif

   440 

   441 

   442 

   443 /*!

   444   \class QIcon

   445 

   446   \brief The QIcon class provides scalable icons in different modes

   447   and states.

   448 

   449   \ingroup painting

   450   \ingroup shared

   451 

   452 

   453   A QIcon can generate smaller, larger, active, and disabled pixmaps

   454   from the set of pixmaps it is given. Such pixmaps are used by Qt

   455   widgets to show an icon representing a particular action.

   456 

   457   The simplest use of QIcon is to create one from a QPixmap file or

   458   resource, and then use it, allowing Qt to work out all the required

   459   icon styles and sizes. For example:

   460 

   461   \snippet doc/src/snippets/code/src_gui_image_qicon.cpp 0

   462 

   463   To undo a QIcon, simply set a null icon in its place:

   464 

   465   \snippet doc/src/snippets/code/src_gui_image_qicon.cpp 1

   466 

   467   Use the QImageReader::supportedImageFormats() and

   468   QImageWriter::supportedImageFormats() functions to retrieve a

   469   complete list of the supported file formats.

   470 

   471   When you retrieve a pixmap using pixmap(QSize, Mode, State), and no

   472   pixmap for this given size, mode and state has been added with

   473   addFile() or addPixmap(), then QIcon will generate one on the

   474   fly. This pixmap generation happens in a QIconEngineV2. The default

   475   engine scales pixmaps down if required, but never up, and it uses

   476   the current style to calculate a disabled appearance. By using

   477   custom icon engines, you can customize every aspect of generated

   478   icons. With QIconEnginePluginV2 it is possible to register different

   479   icon engines for different file suffixes, making it possible for

   480   third parties to provide additional icon engines to those included

   481   with Qt.

   482 

   483   \note Since Qt 4.2, an icon engine that supports SVG is included.

   484 

   485   \section1 Making Classes that Use QIcon

   486 

   487   If you write your own widgets that have an option to set a small

   488   pixmap, consider allowing a QIcon to be set for that pixmap.  The

   489   Qt class QToolButton is an example of such a widget.

   490 

   491   Provide a method to set a QIcon, and when you draw the icon, choose

   492   whichever pixmap is appropriate for the current state of your widget.

   493   For example:

   494   \snippet doc/src/snippets/code/src_gui_image_qicon.cpp 2

   495 

   496   You might also make use of the \c Active mode, perhaps making your

   497   widget \c Active when the mouse is over the widget (see \l

   498   QWidget::enterEvent()), while the mouse is pressed pending the

   499   release that will activate the function, or when it is the currently

   500   selected item. If the widget can be toggled, the "On" mode might be

   501   used to draw a different icon.

   502 

   503   \img icon.png QIcon

   504 

   505   \sa {fowler}{GUI Design Handbook: Iconic Label}, {Icons Example}

   506 */

   507 

   508 

   509 /*!

   510   Constructs a null icon.

   511 */

   512 QIcon::QIcon()

   513     : d(0)

   514 {

   515 }

   516 

   517 /*!

   518   Constructs an icon from a \a pixmap.

   519  */

   520 QIcon::QIcon(const QPixmap &pixmap)

   521     :d(0)

   522 {

   523     addPixmap(pixmap);

   524 }

   525 

   526 /*!

   527   Constructs a copy of \a other. This is very fast.

   528 */

   529 QIcon::QIcon(const QIcon &other)

   530     :d(other.d)

   531 {

   532     if (d)

   533         d->ref.ref();

   534 }

   535 

   536 /*!

   537     Constructs an icon from the file with the given \a fileName. The

   538     file will be loaded on demand.

   539 

   540     If \a fileName contains a relative path (e.g. the filename only)

   541     the relevant file must be found relative to the runtime working

   542     directory.

   543 

   544     The file name can be either refer to an actual file on disk or to

   545     one of the application's embedded resources.  See the

   546     \l{resources.html}{Resource System} overview for details on how to

   547     embed images and other resource files in the application's

   548     executable.

   549 

   550     Use the QImageReader::supportedImageFormats() and

   551     QImageWriter::supportedImageFormats() functions to retrieve a

   552     complete list of the supported file formats.

   553 */

   554 QIcon::QIcon(const QString &fileName)

   555     : d(0)

   556 {

   557     addFile(fileName);

   558 }

   559 

   560 

   561 /*!

   562     Creates an icon with a specific icon \a engine. The icon takes

   563     ownership of the engine.

   564 */

   565 QIcon::QIcon(QIconEngine *engine)

   566     :d(new QIconPrivate)

   567 {

   568     d->engine_version = 1;

   569     d->engine = engine;

   570     d->v1RefCount = new QAtomicInt(1);

   571 }

   572 

   573 /*!

   574     Creates an icon with a specific icon \a engine. The icon takes

   575     ownership of the engine.

   576 */

   577 QIcon::QIcon(QIconEngineV2 *engine)

   578     :d(new QIconPrivate)

   579 {

   580     d->engine_version = 2;

   581     d->engine = engine;

   582 }

   583 

   584 /*!

   585     Destroys the icon.

   586 */

   587 QIcon::~QIcon()

   588 {

   589     if (d && !d->ref.deref())

   590         delete d;

   591 }

   592 

   593 /*!

   594     Assigns the \a other icon to this icon and returns a reference to

   595     this icon.

   596 */

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

   598 {

   599     if (other.d)

   600         other.d->ref.ref();

   601     if (d && !d->ref.deref())

   602         delete d;

   603     d = other.d;

   604     return *this;

   605 }

   606 

   607 /*!

   608    Returns the icon as a QVariant.

   609 */

   610 QIcon::operator QVariant() const

   611 {

   612     return QVariant(QVariant::Icon, this);

   613 }

   614 

   615 /*! \obsolete

   616 

   617     Returns a number that identifies the contents of this

   618     QIcon object. Distinct QIcon objects can have

   619     the same serial number if they refer to the same contents

   620     (but they don't have to). Also, the serial number of

   621     a QIcon object may change during its lifetime.

   622 

   623     Use cacheKey() instead.

   624 

   625     A null icon always has a serial number of 0.

   626 

   627     Serial numbers are mostly useful in conjunction with caching.

   628 

   629     \sa QPixmap::serialNumber()

   630 */

   631 

   632 int QIcon::serialNumber() const

   633 {

   634     return d ? d->serialNum : 0;

   635 }

   636 

   637 /*!

   638     Returns a number that identifies the contents of this QIcon

   639     object. Distinct QIcon objects can have the same key if

   640     they refer to the same contents.

   641     \since 4.3

   642 

   643     The cacheKey() will change when the icon is altered via

   644     addPixmap() or addFile().

   645 

   646     Cache keys are mostly useful in conjunction with caching.

   647 

   648     \sa QPixmap::cacheKey()

   649 */

   650 qint64 QIcon::cacheKey() const

   651 {

   652     if (!d)

   653         return 0;

   654     return (((qint64) d->serialNum) << 32) | ((qint64) (d->detach_no));

   655 }

   656 

   657 /*!

   658   Returns a pixmap with the requested \a size, \a mode, and \a

   659   state, generating one if necessary. The pixmap might be smaller than

   660   requested, but never larger.

   661 

   662   \sa actualSize(), paint()

   663 */

   664 QPixmap QIcon::pixmap(const QSize &size, Mode mode, State state) const

   665 {

   666     if (!d)

   667         return QPixmap();

   668     return d->engine->pixmap(size, mode, state);

   669 }

   670 

   671 /*!

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

   673 

   674     \overload

   675 

   676     Returns a pixmap of size QSize(\a w, \a h). The pixmap might be smaller than

   677     requested, but never larger.

   678 */

   679 

   680 /*!

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

   682 

   683     \overload

   684 

   685     Returns a pixmap of size QSize(\a extent, \a extent). The pixmap might be smaller

   686     than requested, but never larger.

   687 */

   688 

   689 /*!  Returns the actual size of the icon for the requested \a size, \a

   690   mode, and \a state. The result might be smaller than requested, but

   691   never larger.

   692 

   693   \sa pixmap(), paint()

   694 */

   695 QSize QIcon::actualSize(const QSize &size, Mode mode, State state) const

   696 {

   697     if (!d)

   698         return QSize();

   699     return d->engine->actualSize(size, mode, state);

   700 }

   701 

   702 

   703 /*!

   704     Uses the \a painter to paint the icon with specified \a alignment,

   705     required \a mode, and \a state into the rectangle \a rect.

   706 

   707     \sa actualSize(), pixmap()

   708 */

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

   710 {

   711     if (!d || !painter)

   712         return;

   713     QRect alignedRect = QStyle::alignedRect(painter->layoutDirection(), alignment, d->engine->actualSize(rect.size(), mode, state), rect);

   714     d->engine->paint(painter, alignedRect, mode, state);

   715 }

   716 

   717 /*!

   718     \fn void QIcon::paint(QPainter *painter, int x, int y, int w, int h, Qt::Alignment alignment,

   719                           Mode mode, State state) const

   720 

   721     \overload

   722 

   723     Paints the icon into the rectangle QRect(\a x, \a y, \a w, \a h).

   724 */

   725 

   726 /*!

   727     Returns true if the icon is empty; otherwise returns false.

   728 

   729     An icon is empty if it has neither a pixmap nor a filename.

   730 

   731     Note: Even a non-null icon might not be able to create valid

   732     pixmaps, eg. if the file does not exist or cannot be read.

   733 */

   734 bool QIcon::isNull() const

   735 {

   736     return !d;

   737 }

   738 

   739 /*!\internal

   740  */

   741 bool QIcon::isDetached() const

   742 {

   743     return !d || d->ref == 1;

   744 }

   745 

   746 /*! \internal

   747  */

   748 void QIcon::detach()

   749 {

   750     if (d) {

   751         if (d->ref != 1) {

   752             QIconPrivate *x = new QIconPrivate;

   753             if (d->engine_version > 1) {

   754                 QIconEngineV2 *engine = static_cast<QIconEngineV2 *>(d->engine);

   755                 x->engine = engine->clone();

   756             } else {

   757                 x->engine = d->engine;

   758                 x->v1RefCount = d->v1RefCount;

   759                 x->v1RefCount->ref();

   760             }

   761             x->engine_version = d->engine_version;

   762             if (!d->ref.deref())

   763                 delete d;

   764             d = x;

   765         }

   766         ++d->detach_no;

   767     }

   768 }

   769 

   770 /*!

   771     Adds \a pixmap to the icon, as a specialization for \a mode and

   772     \a state.

   773 

   774     Custom icon engines are free to ignore additionally added

   775     pixmaps.

   776 

   777     \sa addFile()

   778 */

   779 void QIcon::addPixmap(const QPixmap &pixmap, Mode mode, State state)

   780 {

   781     if (pixmap.isNull())

   782         return;

   783     if (!d) {

   784         d = new QIconPrivate;

   785         d->engine = new QPixmapIconEngine;

   786     } else {

   787         detach();

   788     }

   789     d->engine->addPixmap(pixmap, mode, state);

   790 }

   791 

   792 

   793 /*!  Adds an image from the file with the given \a fileName to the

   794      icon, as a specialization for \a size, \a mode and \a state. The

   795      file will be loaded on demand. Note: custom icon engines are free

   796      to ignore additionally added pixmaps.

   797 

   798      If \a fileName contains a relative path (e.g. the filename only)

   799      the relevant file must be found relative to the runtime working

   800      directory.

   801 

   802     The file name can be either refer to an actual file on disk or to

   803     one of the application's embedded resources. See the

   804     \l{resources.html}{Resource System} overview for details on how to

   805     embed images and other resource files in the application's

   806     executable.

   807 

   808     Use the QImageReader::supportedImageFormats() and

   809     QImageWriter::supportedImageFormats() functions to retrieve a

   810     complete list of the supported file formats.

   811 

   812     Note: When you add a non-empty filename to a QIcon, the icon becomes

   813     non-null, even if the file doesn't exist or points to a corrupt file.

   814 

   815     \sa addPixmap()

   816  */

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

   818 {

   819     if (fileName.isEmpty())

   820         return;

   821     if (!d) {

   822 #if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)

   823         QFileInfo info(fileName);

   824         QString suffix = info.suffix();

   825         if (!suffix.isEmpty()) {

   826             // first try version 2 engines..

   827             if (QIconEngineFactoryInterfaceV2 *factory = qobject_cast<QIconEngineFactoryInterfaceV2*>(loaderV2()->instance(suffix))) {

   828                 if (QIconEngine *engine = factory->create(fileName)) {

   829                     d = new QIconPrivate;

   830                     d->engine = engine;

   831                 }

   832             }

   833             // ..then fall back and try to load version 1 engines

   834             if (!d) {

   835                 if (QIconEngineFactoryInterface *factory = qobject_cast<QIconEngineFactoryInterface*>(loader()->instance(suffix))) {

   836                     if (QIconEngine *engine = factory->create(fileName)) {

   837                         d = new QIconPrivate;

   838                         d->engine = engine;

   839                         d->engine_version = 1;

   840                         d->v1RefCount = new QAtomicInt(1);

   841                     }

   842                 }

   843             }

   844         }

   845 #endif

   846         // ...then fall back to the default engine

   847         if (!d) {

   848             d = new QIconPrivate;

   849             d->engine = new QPixmapIconEngine;

   850         }

   851     } else {

   852         detach();

   853     }

   854     d->engine->addFile(fileName, size, mode, state);

   855 }

   856 

   857 /*!

   858     \since 4.5

   859 

   860     Returns a list of available icon sizes for the specified \a mode and

   861     \a state.

   862 */

   863 QList<QSize> QIcon::availableSizes(Mode mode, State state) const

   864 {

   865     if (!d || !d->engine || d->engine_version < 2)

   866         return QList<QSize>();

   867     QIconEngineV2 *engine = static_cast<QIconEngineV2*>(d->engine);

   868     return engine->availableSizes(mode, state);

   869 }

   870 

   871 /*!

   872     \since 4.6

   873 

   874     Sets the search paths for icon themes to \a paths.

   875     \sa themeSearchPaths(), fromTheme(), setThemeName()

   876 */

   877 void QIcon::setThemeSearchPaths(const QStringList &paths)

   878 {

   879     QIconLoader::instance()->setThemeSearchPath(paths);

   880 }

   881 

   882 /*!

   883   \since 4.6

   884 

   885   Returns the search paths for icon themes.

   886 

   887   The default value will depend on the platform:

   888 

   889   On X11, the search path will use the XDG_DATA_DIRS environment

   890   variable if available.

   891 

   892   By default all platforms will have the resource directory

   893   \c{:\icons} as a fallback. You can use "rcc -project" to generate a

   894   resource file from your icon theme.

   895 

   896   \sa setThemeSearchPaths(), fromTheme(), setThemeName()

   897 */

   898 QStringList QIcon::themeSearchPaths()

   899 {

   900     return QIconLoader::instance()->themeSearchPaths();

   901 }

   902 

   903 /*!

   904     \since 4.6

   905 

   906     Sets the current icon theme to \a name.

   907 

   908     The \a name should correspond to a directory name in the

   909     themeSearchPath() containing an index.theme

   910     file describing it's contents.

   911 

   912     \sa themeSearchPaths(), themeName()

   913 */

   914 void QIcon::setThemeName(const QString &name)

   915 {

   916     QIconLoader::instance()->setThemeName(name);

   917 }

   918 

   919 /*!

   920     \since 4.6

   921 

   922     Returns the name of the current icon theme.

   923 

   924     On X11, the current icon theme depends on your desktop

   925     settings. On other platforms it is not set by default.

   926 

   927     \sa setThemeName(), themeSearchPaths(), fromTheme(),

   928     hasThemeIcon()

   929 */

   930 QString QIcon::themeName()

   931 {

   932     return QIconLoader::instance()->themeName();

   933 }

   934 

   935 /*!

   936     \since 4.6

   937 

   938     Returns the QIcon corresponding to \a name in the current

   939     icon theme. If no such icon is found in the current theme

   940     \a fallback is return instead.

   941 

   942     The lastest version of the freedesktop icon specification and naming

   943     spesification can be obtained here:

   944     http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html

   945     http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html

   946 

   947     To fetch an icon from the current icon theme:

   948 

   949     \snippet doc/src/snippets/code/src_gui_image_qicon.cpp 3

   950 

   951     Or if you want to provide a guaranteed fallback for platforms that

   952     do not support theme icons, you can use the second argument:

   953 

   954     \snippet doc/src/snippets/code/src_gui_image_qicon.cpp 4

   955 

   956     \note By default, only X11 will support themed icons. In order to

   957     use themed icons on Mac and Windows, you will have to bundle a

   958     compliant theme in one of your themeSearchPaths() and set the

   959     appropriate themeName().

   960 

   961     \sa themeName(), setThemeName(), themeSearchPaths()

   962 */

   963 QIcon QIcon::fromTheme(const QString &name, const QIcon &fallback)

   964 {

   965     static QCache <QString, QIcon> iconCache;

   966 

   967     QIcon icon;

   968 

   969     if (iconCache.contains(name)) {

   970         icon = *iconCache.object(name);

   971     } else {

   972         QIcon *cachedIcon  = new QIcon(new QIconLoaderEngine(name));

   973         iconCache.insert(name, cachedIcon);

   974         icon = *cachedIcon;

   975     }

   976 

   977     if (icon.availableSizes().isEmpty())

   978         return fallback;

   979 

   980     return icon;

   981 }

   982 

   983 /*!

   984     \since 4.6

   985 

   986     Returns true if there is an icon available for \a name in the

   987     current icon theme, otherwise returns false.

   988 

   989     \sa themeSearchPaths(), fromTheme(), setThemeName()

   990 */

   991 bool QIcon::hasThemeIcon(const QString &name)

   992 {

   993     QIcon icon = fromTheme(name);

   994 

   995     return !icon.isNull();

   996 }

   997 

   998 

   999 /*****************************************************************************

  1000   QIcon stream functions

  1001  *****************************************************************************/

  1002 #if !defined(QT_NO_DATASTREAM)

  1003 /*!

  1004     \fn QDataStream &operator<<(QDataStream &stream, const QIcon &icon)

  1005     \relates QIcon

  1006     \since 4.2

  1007 

  1008     Writes the given \a icon to the given \a stream as a PNG

  1009     image. If the icon contains more than one image, all images will

  1010     be written to the stream. Note that writing the stream to a file

  1011     will not produce a valid image file.

  1012 */

  1013 

  1014 QDataStream &operator<<(QDataStream &s, const QIcon &icon)

  1015 {

  1016     if (s.version() >= QDataStream::Qt_4_3) {

  1017         if (icon.isNull()) {

  1018             s << QString();

  1019         } else {

  1020             if (icon.d->engine_version > 1) {

  1021                 QIconEngineV2 *engine = static_cast<QIconEngineV2 *>(icon.d->engine);

  1022                 s << engine->key();

  1023                 engine->write(s);

  1024             } else {

  1025                 // not really supported

  1026                 qWarning("QIcon: Cannot stream QIconEngine. Use QIconEngineV2 instead.");

  1027             }

  1028         }

  1029     } else if (s.version() == QDataStream::Qt_4_2) {

  1030         if (icon.isNull()) {

  1031             s << 0;

  1032         } else {

  1033             QPixmapIconEngine *engine = static_cast<QPixmapIconEngine *>(icon.d->engine);

  1034             int num_entries = engine->pixmaps.size();

  1035             s << num_entries;

  1036             for (int i=0; i < num_entries; ++i) {

  1037                 s << engine->pixmaps.at(i).pixmap;

  1038                 s << engine->pixmaps.at(i).fileName;

  1039                 s << engine->pixmaps.at(i).size;

  1040                 s << (uint) engine->pixmaps.at(i).mode;

  1041                 s << (uint) engine->pixmaps.at(i).state;

  1042             }

  1043         }

  1044     } else {

  1045         s << QPixmap(icon.pixmap(22,22));

  1046     }

  1047     return s;

  1048 }

  1049 

  1050 /*!

  1051     \fn QDataStream &operator>>(QDataStream &stream, QIcon &icon)

  1052     \relates QIcon

  1053     \since 4.2

  1054 

  1055     Reads an image, or a set of images, from the given \a stream into

  1056     the given \a icon.

  1057 */

  1058 

  1059 QDataStream &operator>>(QDataStream &s, QIcon &icon)

  1060 {

  1061     if (s.version() >= QDataStream::Qt_4_3) {

  1062         icon = QIcon();

  1063         QString key;

  1064         s >> key;

  1065         if (key == QLatin1String("QPixmapIconEngine")) {

  1066             icon.d = new QIconPrivate;

  1067             QIconEngineV2 *engine = new QPixmapIconEngine;

  1068             icon.d->engine = engine;

  1069             engine->read(s);

  1070         } else if (key == QLatin1String("QIconLoaderEngine")) {

  1071             icon.d = new QIconPrivate;

  1072             QIconEngineV2 *engine = new QIconLoaderEngine();

  1073             icon.d->engine = engine;

  1074             engine->read(s);

  1075 #if !defined (QT_NO_LIBRARY) && !defined(QT_NO_SETTINGS)

  1076         } else if (QIconEngineFactoryInterfaceV2 *factory = qobject_cast<QIconEngineFactoryInterfaceV2*>(loaderV2()->instance(key))) {

  1077             if (QIconEngineV2 *engine= factory->create()) {

  1078                 icon.d = new QIconPrivate;

  1079                 icon.d->engine = engine;

  1080                 engine->read(s);

  1081             }

  1082 #endif

  1083         }

  1084     } else if (s.version() == QDataStream::Qt_4_2) {

  1085         icon = QIcon();

  1086         int num_entries;

  1087         QPixmap pm;

  1088         QString fileName;

  1089         QSize sz;

  1090         uint mode;

  1091         uint state;

  1092 

  1093         s >> num_entries;

  1094         for (int i=0; i < num_entries; ++i) {

  1095             s >> pm;

  1096             s >> fileName;

  1097             s >> sz;

  1098             s >> mode;

  1099             s >> state;

  1100             if (pm.isNull())

  1101                 icon.addFile(fileName, sz, QIcon::Mode(mode), QIcon::State(state));

  1102             else

  1103                 icon.addPixmap(pm, QIcon::Mode(mode), QIcon::State(state));

  1104         }

  1105     } else {

  1106         QPixmap pm;

  1107         s >> pm;

  1108         icon.addPixmap(pm);

  1109     }

  1110     return s;

  1111 }

  1112 

  1113 #endif //QT_NO_DATASTREAM

  1114 

  1115 

  1116 #ifdef QT3_SUPPORT

  1117 

  1118 static int widths[2] = { 22, 32 };

  1119 static int heights[2] = { 22, 32 };

  1120 

  1121 static QSize pixmapSizeHelper(QIcon::Size which)

  1122 {

  1123     int i = 0;

  1124     if (which == QIcon::Large)

  1125         i = 1;

  1126     return QSize(widths[i], heights[i]);

  1127 }

  1128 

  1129 /*!

  1130     \enum QIcon::Size

  1131     \compat

  1132 

  1133     \value Small  Use QStyle::pixelMetric(QStyle::PM_SmallIconSize) instead.

  1134     \value Large  Use QStyle::pixelMetric(QStyle::PM_LargeIconSize) instead.