/****************************************************************************

**

** Copyright (C) 2008-2010 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (developer.feedback@nokia.com)

**

** This file is part of the HbCore module of the UI Extensions for Mobile.

**

** GNU Lesser General Public License Usage

** This file may be used under the terms of the GNU Lesser General Public

** License version 2.1 as published by the Free Software Foundation and

** appearing in the file LICENSE.LGPL included in the packaging of this file.

** Please review the following information to ensure the GNU Lesser General

** Public License version 2.1 requirements will be met:

** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

**

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

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

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

**

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

** Nokia at developer.feedback@nokia.com.

**

****************************************************************************/

#include "hbicon.h"

#include "hbicon_p.h"

#include "hbiconanimator.h"

#include "hbbadgeicon_p.h"

#include "hbiconloader_p.h"

#include <QObject>

#include <QPainter>

#include <QVariant>

/*!

    @stable

    @hbcore

    \class HbIcon

    \brief HbIcon is a paintable instance of an icon. The term icon means any piece of

    graphics that can be drawn. This class is not intended to be derived from.

    For more information on image and icon classes and general notes about

    graphics memory usage see \ref graph_mem_usage "this page".

    This class implements copy-on-write semantics, so copy constructor and assignment operator

    only perform shallow copy and are fast. A deep copy is done if the icon state is changed.

    Supported formats and file extensions are the following.

    - SVG-T (.svg)

    - Externalized QPicture (.qpic)

    - PNG (.png)

    - XPM (.xpm)

    - JPG (.jpg)

    - Frame animations (.axml)

    An icon is defined by its name. The filename should be same as the logical name of the icon,

    accompanied with the file extension.

    E.g. logical name of the icon is "frame". Assuming the icon file is in SVG-T format,

    the filename should be "frame.svg".

    The icon name can be either a logical icon name that is fetched from the theme

    or an absolute filename. Logical icon names should not include a filename extension.

    An absolute icon filename must include full path and filename extension.

    The icon can be resized with method HbIcon::setSize.

    When resizing, by default the aspect ratio of the icon is preserved.

    To change this, define the aspect ratio mode parameter in the method HbIcon::paint().

    An icon itself can be a combination of existing icons; in this case the main icon is

    "badged" with smaller icons to form a distinct icon. You can badge icons in this way

    with the HbIcon::addBadge method, specifying the location where the badge should be drawn

    and a second HbIcon to draw at the indicated location. To prevent possible recursion ,

    you can't badge an icon with a badge icon that is itself badged, however.

    Scaled instances of the icons are shared by the framework

    to decrease memory consumption.

    A brief example of how to create an icon and use it.

    \snippet{clock/clockworldview.cpp,1}

    This class provides built-in support for icon animations.

    Supported formats are the following.

    - GIF (.gif)

    - MNG (.mng)

    The formats mentioned above contain all the animation information inside a single file.

    They are pixel formats, so the quality of resizing the animations is not good.

    Icon animations can also be constructed from separate frame icons.

    The frames are defined in separate files, which can be in any format supported by HbIcon.

    The animation frame information for the icon is defined using class HbIconAnimationManager.

    The animated icon can be then constructed normally with its name.

    As default the icon animation is started automatically when the icon is painted for the first time.

    This can be disabled with flag HbIcon::NoAutoStartAnimation.

    An example of how to define a frame-by-frame animation and construct an icon using it.

    \dontinclude ultimatecodesnippet/ultimatecodesnippet.cpp

    \skip frame-by-frame

    \until }

*/

/*!

  \enum HbIcon::Flag

  \b DoNotCache \b (0x01) Icon pixmap is not cached in the system wide icon pixmap cache.

         Setting this flag improves cache performance for other icons, if this icon does

         not need to be cached for being able to load it faster next time.

  \b ResolutionCorrected \b (0x02) This flag is useful for making icon sizes automatically

         adapt to different screen resolutions (DPI values) and zoom factors used in the user

         interface. The current display resolution (DPI value) and zoom factor are taken

         in consideration when defining the default size of the icon. This affects on what default

         size is reported for the icon and also in which size the icon is rendered if its size is

         not set explicitly. The default DPI value is 144 and the default zoom factor 1.0.

         When this flag is set, the corrected default size of icon is defined as:

         Corrected default size = original default size * current DPI value / default DPI

         value * current zoom factor

         \note Currently this flag has an effect on vector icons only.

         \note If the icon size is set explicitly this flag has no effect.

  \b NoAutoStartAnimation \b (0x04) This flag disables automatic starting of the icon animation

         when the icon is painted for the first time. The client can then control the animation with

         startAnimation() and stopAnimation() methods in class HbIconAnimator.

         If the icon is not animated this flag has no effect.

  \b Colorized \b (0x08) This flag enables the usage of the color that is set via

         setColor(). If this flag is not set then the color that is set with setColor() is

         ignored, unless the icon refers some theme graphics. For icons coming from the

         theme this flag can be left unset because they will still be colorized properly

         if the logical icon name indicates that the icon is a mono icon. Therefore this

         flag is only relevant for icons loaded from regular files.

  \b NonThemeable \b (0x10) This flag indicates that the icon is not themeable and thus

         there is no need to handle theme and layout direction changes for this icon.

         This is merely an optimization flag and must be set directly after creating the

         HbIcon instance (before the first paint of the icon) to have any performance

         benefits.

*/

/*!

  \enum HbIcon::MirroringMode

  \b Default This is the default mirroring mode. The icon is mirrored in right-to-left

         layout if its name is listed in the icon framework's configuration list of mirrored icons.

  \b Forced Forces horizontal mirroring of the icon. As default, the system

         automatically mirrors the icon pixmap based on a predefined configuration,

         when required for the purpose of a mirrored layout.

         This mirroring mode explicitly forces the icon pixmap to be mirrored,

         regardless of the layout direction.

  \b Prevented Prevents horizontal mirroring of the icon. As default, the system

         automatically mirrors the icon pixmap based on a predefined configuration,

         when required for the purpose of a mirrored layout.

         This mirroring mode explicitly prevents the icon pixmap from being mirrored,

         regardless of the layout direction.

  \b LayoutDirection This mirroring mode automatically mirrors the icon pixmap

         in a right-to-left layout.

*/

// Must be initialized dynamically because QIcon cannot be constructed

// when static variables are constructed.

static HbIconPrivate *shared_null = 0;

static const int iconMetaType = qRegisterMetaType<HbIcon>();

/*!

This constructor is used for shared_null instance only

\internal

*/

HbIconPrivate::HbIconPrivate() :

    engine(new HbIconEngine(QString())),

    qicon(engine),

    badgeInfo(0)

{

    ref.ref(); // Need to do extra ref so the shared null does not get destructed

}

/*!

\internal

*/

HbIconPrivate::HbIconPrivate(const QIcon &qicon) :

    engine(0),

    qicon(qicon),

    badgeInfo(0)

{

}

/*!

\internal

*/

HbIconPrivate::HbIconPrivate(const QString &iconName) :

    engine(new HbIconEngine(iconName)),

    qicon(engine),

    badgeInfo(0)

{

}

/*!

\internal

*/

HbIconPrivate::HbIconPrivate(const HbIconPrivate &other) :

    QSharedData(other),

    size(other.size),

    engine(0),

    qicon(),

    badgeInfo(0)

{

    if (other.engine) {

        engine = new HbIconEngine(*other.engine);

        // Have to instantiate a temporary QIcon because

        // QIcon's copy constructor shares the engine.

        QIcon temp(engine);

        qicon = temp;

    } else {

        // Copy constructed from qicon - so just copy the qicon.

        qicon = other.qicon;

        if (other.badgeInfo) {

            badgeInfo = new HbBadgeIcon(*other.badgeInfo);

        }

    }

}

/*!

\internal

*/

HbIconPrivate::~HbIconPrivate()

{

    delete badgeInfo;

    if (engine) {

        engine->setAnimator(0);

    }

    // engine is deleted by QIcon destructor.

}

/*!

\internal

*/

void HbIconPrivate::clear()

{

    if (badgeInfo) {

        badgeInfo->removeAllBadges();

    }

    if (engine) {

        engine->clear();

        size = QSizeF();

    } else {

        qicon = QIcon();

    }

}

/*!

\internal

*/

void HbIconPrivate::removeAllBadges()

{

    if (engine) {

        engine->removeAllBadges();

    } else if (badgeInfo) {

        badgeInfo->removeAllBadges();

    }

}

/*!

\internal

*/

bool HbIconPrivate::isBadged() const

{

    if (engine) {

        return engine->isBadged();

    } else if (badgeInfo) {

        return badgeInfo->isBadged();

    }

    return false;

}

/*!

\internal

*/

void HbIconPrivate::setThemedColor(const QColor &color)

{

    if (engine && color != engine->themedColor()) {

        engine->setThemedColor(color);

    }

}

/*!

\internal

*/

QColor HbIconPrivate::themedColor() const

{

    return engine ? engine->themedColor() : QColor();

}

/*!

\internal

*/

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

{

    stream >> icon.size;

    int enginePtr = 0;

    stream >> enginePtr;

    if (enginePtr) {

        icon.engine = new HbIconEngine(stream);

    } else {

        stream >> icon.qicon;

    }

    return stream;

}

/*!

\internal

*/

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

{

    stream << icon.size;

    // Put the engine pointer in stream to see if it exists

    stream << (qptrdiff)(icon.engine);

    // If the icon has engine, externalize it in the stream

    if (icon.engine) {

        icon.engine->externalize(stream);

    } else {

        stream << icon.qicon;

    }

    return stream;

}

/*!

\internal

*/

bool HbIconPrivate::addBadge(Qt::Alignment align,

                             const HbIcon &icon,

                             int z,

                             const QSizeF &sizeFactor,

                             Qt::AspectRatioMode aspectRatio)

{

    if (icon.isBadged()) {

        return false;

    } else if (engine) {

        engine->addBadge(align, icon, z, sizeFactor, aspectRatio);

    } else {

        if (!badgeInfo) {

            badgeInfo = new HbBadgeIcon();

        }

        badgeInfo->addBadge(align, icon, z, sizeFactor, aspectRatio);

    }

    return true;

}

/*!

\internal

 */

bool HbIconPrivate::removeBadge(const HbIcon &badge)

{

    bool result = false;

    if (engine) {

        result = engine->removeBadge(badge);

    } else if (badgeInfo) {

        result = badgeInfo->removeBadge(badge);

    }

    return result;

}

/*! Default constructor. If this constructor is used, the icon name needs to be set

* by calling HbIcon::setIconName.

*/

HbIcon::HbIcon()

{

    // Construct shared_null if not done yet.

    if (!shared_null) {

        shared_null = new HbIconPrivate;

    }

    d = shared_null;

}

/*! Constructs a new icon with the icon name \a iconName.

*/

HbIcon::HbIcon(const QString &iconName)

{

    d = new HbIconPrivate(iconName);

}

/*! Constructs a new icon to be a copy of the given QIcon.

* Due to the limitations listed below, this constructor should be used only for

* compatibility reasons if a QIcon instance needs to be passed as a parameter

* to a method taking a HbIcon parameter.

* \note If this constructor is used, there are the following limitations in the HbIcon methods.

* - HbIcon::defaultSize() may return QSizeF().

* - HbIcon::paint() ignores the parameter aspectRatioMode and converts the given QRectF to QRect.

* - HbIcon::iconName() returns empty string by default.

* - HbIcon::pixmap() returns null pixmap.

* - Colorization and mirroring support are not available.

* This method should only be used if absolute necessary, as this is not ideal for hardware accelerated environment

* and there may be huge differences in painting performance when compared to a native HbIcon.

*/

HbIcon::HbIcon(const QIcon &icon)

{

    d = new HbIconPrivate(icon);

}

/*!

* Copy constructs a new icon using the \a other icon.

* Copy-on-write semantics is used, so this only does a shallow copy.

*/

HbIcon::HbIcon(const HbIcon &other) :

    d(other.d)

{

}

/*!

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

* this icon. Copy-on-write semantics is used, so this only does a shallow copy.

*/

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

{

    if (&other != this) {

        d = other.d;

    }

    return *this;

}

/*!

* Destroys the icon.

*/

HbIcon::~HbIcon()

{

}

/*!

* Returns true if either

* - Icon was not copy constructed from QIcon and it does not have the any icon names set.

* - Icon was copy constructed from QIcon and QIcon::isNull returns true.

* \note Even a non-null icon might not be able to create valid pixmaps,

* e.g. if the file does not exist or cannot be read.

*/

bool HbIcon::isNull() const

{

    if (d->engine) {

        return d->engine->isNull();

    } else {

        return d->qicon.isNull();

    }

}

/*!

* Clears the icon. After this it is same as a default constructed HbIcon.

* Calling this method is faster than assigning a default constructed HbIcon to this icon.

*/

void HbIcon::clear()

{

    // A NULL icon is always cleared - save some time not detaching from it

    if (d.constData() != shared_null) {

        d.detach();

        d->clear();

    }

}

/*!

* Indicates whether or not the icon is badged.

* returns true if this icon is bearing a badge.

*/

bool HbIcon::isBadged() const

{

    return d->isBadged();

}

/*!

* Returns the the default icon pixmap in state QIcon::Normal and mode QIcon::Off.

*

* \note This method should be used only if it is necessary to get hold of the pixel data

* of the pixmap. It slows down hardware accelerated rendering. In normal use cases, this

* method is not needed. HbIcon::size() can be used to retrieve the size of the icon

* and HbIcon::paint() to paint the icon.

*/

QPixmap HbIcon::pixmap()

{

    if (d->engine) {

        return d->engine->pixmap(d->size.toSize(), QIcon::Normal, QIcon::Off);

    }

    return QPixmap();

}

/*!

* Sets the new color that is used to colorize mono icons.

*

* \param  color to be set

*

* This setting will be ignored for regular files when the HbIcon::Colorized flag

* is not set.  This does not apply to theme elements, for them the color is

* always taken into account when the logical graphics name indicates that it is

* a mono icon.

*

* Note that if a widget defines a color for its icon primitive (as most standard

* widgets do) then the style will take care of colorizing with the correct color

* from the theme whenever the theme changes. Therefore mono icons shown in such

* widgets will automatically be colorized with a theme-specific color if the

* icon is either a mono icon coming from the theme or the icon has the

* HbIcon::Colorized flag set.