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 "qiconengine.h"

    43 #include "qpainter.h"

    44 

    45 QT_BEGIN_NAMESPACE

    46 

    47 /*!

    48   \class QIconEngine

    49 

    50   \brief The QIconEngine class provides an abstract base class for QIcon renderers.

    51 

    52   \ingroup painting

    53 

    54   \bold {Use QIconEngineV2 instead.}

    55 

    56   An icon engine provides the rendering functions for a QIcon. Each icon has a

    57   corresponding icon engine that is responsible for drawing the icon with a

    58   requested size, mode and state.

    59 

    60   The icon is rendered by the paint() function, and the icon can additionally be

    61   obtained as a pixmap with the pixmap() function (the default implementation

    62   simply uses paint() to achieve this). The addPixmap() function can be used to

    63   add new pixmaps to the icon engine, and is used by QIcon to add specialized

    64   custom pixmaps.

    65 

    66   The paint(), pixmap(), and addPixmap() functions are all virtual, and can

    67   therefore be reimplemented in subclasses of QIconEngine.

    68 

    69   \sa QIconEngineV2, QIconEnginePlugin

    70 

    71 */

    72 

    73 /*!

    74   \fn virtual void QIconEngine::paint(QPainter *painter, const QRect &rect, QIcon::Mode mode, QIcon::State state) = 0;

    75 

    76   Uses the given \a painter to paint the icon with the required \a mode and

    77   \a state into the rectangle \a rect.

    78 */

    79 

    80 /*!  Returns the actual size of the icon the engine provides for the

    81   requested \a size, \a mode and \a state. The default implementation

    82   returns the given \a size.

    83  */

    84 QSize QIconEngine::actualSize(const QSize &size, QIcon::Mode /*mode*/, QIcon::State /*state*/)

    85 {

    86     return size;

    87 }

    88 

    89 

    90 /*!

    91   Destroys the icon engine.

    92  */

    93 QIconEngine::~QIconEngine()

    94 {

    95 }

    96 

    97 

    98 /*!

    99   Returns the icon as a pixmap with the required \a size, \a mode,

   100   and \a state. The default implementation creates a new pixmap and

   101   calls paint() to fill it.

   102 */

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

   104 {

   105     QPixmap pm(size);

   106     {

   107         QPainter p(&pm);

   108         paint(&p, QRect(QPoint(0,0),size), mode, state);

   109     }

   110     return pm;

   111 }

   112 

   113 /*!

   114   Called by QIcon::addPixmap(). Adds a specialized \a pixmap for the given

   115   \a mode and \a state. The default pixmap-based engine stores any supplied

   116   pixmaps, and it uses them instead of scaled pixmaps if the size of a pixmap

   117   matches the size of icon requested. Custom icon engines that implement

   118   scalable vector formats are free to ignores any extra pixmaps.

   119  */

   120 void QIconEngine::addPixmap(const QPixmap &/*pixmap*/, QIcon::Mode /*mode*/, QIcon::State /*state*/)

   121 {

   122 }

   123 

   124 

   125 /*!  Called by QIcon::addFile(). Adds a specialized pixmap from the

   126   file with the given \a fileName, \a size, \a mode and \a state. The

   127   default pixmap-based engine stores any supplied file names, and it

   128   loads the pixmaps on demand instead of using scaled pixmaps if the

   129   size of a pixmap matches the size of icon requested. Custom icon

   130   engines that implement scalable vector formats are free to ignores

   131   any extra files.

   132  */

   133 void QIconEngine::addFile(const QString &/*fileName*/, const QSize &/*size*/, QIcon::Mode /*mode*/, QIcon::State /*state*/)

   134 {

   135 }

   136 

   137 

   138 

   139 // version 2 functions

   140 

   141 

   142 /*!

   143     \class QIconEngineV2

   144 

   145     \brief The QIconEngineV2 class provides an abstract base class for QIcon renderers.

   146 

   147     \ingroup painting

   148     \since 4.3

   149 

   150     An icon engine renders \l{QIcon}s. With icon engines, you can

   151     customize icons. Qt provides a default engine that makes icons

   152     adhere to the current style by scaling the icons and providing a

   153     disabled appearance.

   154 

   155     An engine is installed on an icon either through a QIcon

   156     constructor or through a QIconEnginePluginV2. The plugins are used

   157     by Qt if a specific engine is not given when the icon is created.

   158     See the QIconEngineV2 class description to learn how to create

   159     icon engine plugins.

   160 

   161     An icon engine provides the rendering functions for a QIcon. Each

   162     icon has a corresponding icon engine that is responsible for drawing

   163     the icon with a requested size, mode and state.

   164 

   165     QIconEngineV2 extends the API of QIconEngine to allow streaming of

   166     the icon engine contents, and should be used instead of QIconEngine

   167     for implementing new icon engines.

   168 

   169     \sa QIconEnginePluginV2

   170 

   171 */

   172 

   173 /*!

   174     \enum QIconEngineV2::IconEngineHook

   175     \since 4.5

   176 

   177     These enum values are used for virtual_hook() to allow additional

   178     queries to icon engine without breaking binary compatibility.

   179 

   180     \value AvailableSizesHook Allows to query the sizes of the

   181     contained pixmaps for pixmap-based engines. The \a data argument

   182     of the virtual_hook() function is a AvailableSizesArgument pointer

   183     that should be filled with icon sizes. Engines that work in terms

   184     of a scalable, vectorial format normally return an empty list.

   185 

   186     \sa virtual_hook()

   187  */

   188 

   189 /*!

   190     \class QIconEngineV2::AvailableSizesArgument

   191     \since 4.5

   192 

   193     This struct represents arguments to virtual_hook() function when

   194     \a id parameter is QIconEngineV2::AvailableSizesHook.

   195 

   196     \sa virtual_hook(), QIconEngineV2::IconEngineHook

   197  */

   198 

   199 /*!

   200     \variable QIconEngineV2::AvailableSizesArgument::mode

   201     \brief the requested mode of an image.

   202 

   203     \sa QIcon::Mode

   204 */

   205 

   206 /*!

   207     \variable QIconEngineV2::AvailableSizesArgument::state

   208     \brief the requested state of an image.

   209 

   210     \sa QIcon::State

   211 */

   212 

   213 /*!

   214     \variable QIconEngineV2::AvailableSizesArgument::sizes

   215 

   216     \brief image sizes that are available with specified \a mode and

   217     \a state. This is an output parameter and is filled after call to

   218     virtual_hook(). Engines that work in terms of a scalable,

   219     vectorial format normally return an empty list.

   220 */

   221 

   222 

   223 /*!

   224     Returns a key that identifies this icon engine.

   225  */

   226 QString QIconEngineV2::key() const

   227 {

   228     return QString();

   229 }

   230 

   231 /*!

   232     Returns a clone of this icon engine.

   233  */

   234 QIconEngineV2 *QIconEngineV2::clone() const

   235 {

   236     return 0;

   237 }

   238 

   239 /*!

   240     Reads icon engine contents from the QDataStream \a in. Returns

   241     true if the contents were read; otherwise returns false.

   242 

   243     QIconEngineV2's default implementation always return false.

   244  */

   245 bool QIconEngineV2::read(QDataStream &)

   246 {

   247     return false;

   248 }

   249 

   250 /*!

   251     Writes the contents of this engine to the QDataStream \a out.

   252     Returns true if the contents were written; otherwise returns false.

   253 

   254     QIconEngineV2's default implementation always return false.

   255  */

   256 bool QIconEngineV2::write(QDataStream &) const

   257 {

   258     return false;

   259 }

   260 

   261 /*!

   262     \since 4.5

   263 

   264     Additional method to allow extending QIconEngineV2 without

   265     adding new virtual methods (and without breaking binary compatibility).

   266     The actual action and format of \a data depends on \a id argument

   267     which is in fact a constant from IconEngineHook enum.

   268 

   269     \sa IconEngineHook

   270 */

   271 void QIconEngineV2::virtual_hook(int id, void *data)

   272 {

   273     switch (id) {

   274     case QIconEngineV2::AvailableSizesHook: {

   275         QIconEngineV2::AvailableSizesArgument &arg =

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

   277         arg.sizes.clear();

   278         break;

   279     }

   280     default:

   281         break;

   282     }

   283 }

   284 

   285 /*!

   286     \since 4.5

   287 

   288     Returns sizes of all images that are contained in the engine for the

   289     specific \a mode and \a state.

   290 

   291     \note This is a helper method and the actual work is done by

   292     virtual_hook() method, hence this method depends on icon engine support

   293     and may not work with all icon engines.

   294  */

   295 QList<QSize> QIconEngineV2::availableSizes(QIcon::Mode mode, QIcon::State state)

   296 {

   297     AvailableSizesArgument arg;

   298     arg.mode = mode;

   299     arg.state = state;

   300     virtual_hook(QIconEngineV2::AvailableSizesHook, reinterpret_cast<void*>(&arg));

   301     return arg.sizes;

   302 }

   303 

   304 QT_END_NAMESPACE