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

**

** 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 "hbeffect.h"

#include "hbeffect_p.h"

#include "hbeffectinternal_p.h"

#include "hbeffectabstract_p.h"

#include "hbeffectgroup_p.h"

#include "hbinstance.h"

#include "hbinstance_p.h"

#include "hbimagetraces_p.h"

#include <hbglobal.h>

#include <QObject>

#include <QGraphicsItem>

#include <QGraphicsWidget>

// Uncomment next define in order to get warning prints.

//#define HBEFFECT_WARNING

// Effect definitions for effect item strings starting with this prefix cannot

// be added with this public API. This prevents overriding HB's effects by

// mistake in 3rd party software.

#define HB_EFFECT_ITEM_PREFIX "HB_"

// This itemType is used internally to manage object specific effects and should

// not be used by 3rd party software.

#define HB_EFFECT_INTERNAL_ITEM "HB_INTERNAL"

static HbEffectPrivate d;

// ===========================================================================

class EffectMapKey

{

public:

    EffectMapKey(QGraphicsItem *item, const QString &effectEvent);

public:

    QGraphicsItem *mItem;

    QString mEffectEvent;

};

EffectMapKey::EffectMapKey(QGraphicsItem *item, const QString &effectEvent) :

    mItem(item), mEffectEvent(effectEvent)

{

}

bool operator <(const EffectMapKey &key1, const EffectMapKey &key2)

{

    // First compare item pointer address

    int result = key1.mItem - key2.mItem;

    // If that is same, compare effect event string

    if (!result) {

        result = key1.mEffectEvent.compare(key2.mEffectEvent);

    }

    return result<0;

}

static void fixEffectGroupOrder(QList<HbEffectGroup *> *groupList)

{

    // If there is only one group, no need to change order

    if (groupList->count() > 1) {

        int last = groupList->count() - 1;

        int movedCount = 0; // number of groups moved last in the list

        for (int i = last; i >= 0; --i) {

            HbEffectGroup *group = groupList->at(i);

            // If the group has a translate effect, move it last

            if (group->hasTranslateEffect()) {

                groupList->takeAt(i);

                groupList->append(group);

                movedCount++;

            }

        }

        if (last - movedCount > 0 ) {

            for (int i = last - movedCount; i >= 0; --i) {

                HbEffectGroup *group = groupList->at(i);

                // If the group has a scale effect, move it second last before groups that had translate effects

                if (group->hasScaleEffect()) {

                    groupList->takeAt(i);

                    groupList->insert(last - movedCount, group);

                }

            }

        }

    }

}

static bool privateDestroyed = false;

HbEffectPrivate::HbEffectPrivate() :

    mController(),

    mFactory(mController),

    mEventEffectList(),

    mEnabled(true),

    mDisabledItems(),

    mViewChangeConnected(false),

    mEffectsEnabled(true)

{

    // Needed for notifying effect finish asynchronously

    qRegisterMetaType<HbEffect::EffectStatus>();

}

HbEffectPrivate::~HbEffectPrivate()

{   

    privateDestroyed = true;

    mDisabledItems.clear();

}

void HbEffectPrivate::connectViewChanges()

{

    // Connect to view change signals if not done yet

    if (!mViewChangeConnected) {

        mViewChangeConnected = true;

        QList<HbMainWindow *> windowList = hbInstance->allMainWindows();

        foreach (const HbMainWindow *window, windowList) {

            connect(window, SIGNAL(currentViewChanged(HbView*)), SLOT(handleViewChanged(HbView*)));

        }

        // Need a notification when a mainwindow is added in the future.

        connect(HbInstancePrivate::d_ptr(), SIGNAL(windowAdded(HbMainWindow*)), SLOT(handleWindowAdded(HbMainWindow*)));

    }

}

void HbEffectPrivate::handleWindowAdded(HbMainWindow *window)

{

    connect(window, SIGNAL(currentViewChanged(HbView*)), SLOT(handleViewChanged(HbView*)));

}

void HbEffectPrivate::handleViewChanged(HbView *view)

{

     // Observers may be notified during cancellations which may result in starting a new

    // effect during which groups may be deleted and removed from

    // mEventEffectList. Therefore we cannot directly iterate on mEventEffectList.

    QList<HbEffectGroup *> groupsToBeHandled;

    foreach (HbEffectGroup *group, d.mEventEffectList) {

        groupsToBeHandled.append(group);

    }

    foreach (HbEffectGroup *group, groupsToBeHandled) {

    // Check if the real list still contains the group. If not then it may have been

    // deleted and removed meanwhile so do nothing.

    if (d.mEventEffectList.values().contains(group)) {

        if (group->isRunning()) {

            // Looping effect

            if (group->isLooping()) {

                if (group->view() == view) {    

                    group->resume(); // Effect's view activated, resume effect

                } else {

                    group->pause(); // Effect's view deactivated, pause effect

                }

            } else { // Non-looping effect

                if (group->view() != view) { // Effect's view deactivated, cancel the effect

                    group->cancelAll(true);

                    // remove group from eventEffectsList

                    QMap<EffectMapKey, HbEffectGroup *>::iterator e = d.mEventEffectList.begin();

                     while (e != d.mEventEffectList.end()) {

                         if (e.value() == group) { // found, erase from event effect list

                             d.mEventEffectList.erase(e);

                             e = d.mEventEffectList.end();

                         }

                         else

                            e++;  // try next one

                     }

                     delete group; // once removed from list, delete group

                }

            }

        }

    }    

}

}

HbAnimatedItemGroup::HbAnimatedItemGroup(

    const QList<QGraphicsItem *> &items,

    QObject *receiver,

    const char *member,

    const QVariant &userData) :

    QObject(),

    mItems(items),

    mFinishedCount(0),

    mReceiver(receiver),

    mFunction(member ? QString(member) : QString()),

    mUserData(userData)

{

    // Need information of receiver destroyed because this class gets

    // the notifications asynchronously so it must not invoke the

    // receiver if it has been destroyed meanwhile.

    connect(mReceiver, SIGNAL(destroyed()), this, SLOT(receiverDestroyed())); 

}

void HbAnimatedItemGroup::finished(const HbEffect::EffectStatus &status)

{

    if (++mFinishedCount == mItems.count()) {

        if (mReceiver && !mFunction.isEmpty()) {

            QMetaObject::invokeMethod(

                mReceiver,

                mFunction.toAscii().data(),

                Qt::AutoConnection,

                QGenericReturnArgument(),

                Q_ARG(HbEffect::EffectStatus, status));

        }

        // We are done, delete self.

        deleteLater();

    }

}

void HbAnimatedItemGroup::receiverDestroyed()

{

    // Receiver object was destroyed, set pointer to NULL so it is not invoked any more.

    mReceiver = 0;

}

// ===========================================================================

/*!

  @stable

  @hbcore

  \class HbEffect

  \brief HbEffect is used to control effects on graphics components.

  HbEffect has functions to start or cancel effects (like scaling, fading,

  rotation, various filter effects). The effects are usually trigerred by

  various events and are themable.  The effect definition is read from FXML

  files. All the widgets which want to show an effect should have their effects

  defined in an FXML file.  For example, view can have an effect animation

  defined in albumitem_anim.fxml with the following content:

  \code

  <layers>

  <visual>

  <param name="scale_x" type="anim">

  <duration>0.1</duration>

  <style>inoutback</style>

  <keyframe at="0.0">1.0</keyframe>

  <keyframe at="1.0">2.0</keyframe>

  </param>

  <param name="scale_y" type="anim">

  <keyframe at="0.0">1.0</keyframe>

  <keyframe at="1.0">2.0</keyframe>

  </param>

  <param name="scale_origin_x" ref="visual.width">0.5</param>

  <param name="scale_origin_y" ref="visual.height">0.5</param>

  <param name="opacity" type="anim">

  <duration>0.1</duration>

  <style>linear</style>

  <keyframe at="0.0">1.0</keyframe>

  <keyframe at="1.0">0.5</keyframe>

  </param>

  </visual>

  </layers>

  \endcode

  Example of how to use HbEffect

  \snippet{HbShow/hbsalbumsview.cpp,1}

*/

/*!

  \struct HbEffect::EffectStatus

  \brief Stores status information of the effect that has finished.

  It is passed as an argument to the receiver slot provided by the user of the API.

*/

/*!

  \var QGraphicsItem* HbEffect::EffectStatus::item

  The graphics item that has completed its effect.

*/

/*!

  \var QString HbEffect::EffectStatus::effectEvent

  The effect event that was passed in the HbEffect::start when the effect was started.

*/

/*!

  \var Hb::EffectEvent HbEffect::EffectStatus::reason

  The reason why the effect finished.

*/

/*!

  \var QVariant HbEffect::EffectStatus::userData

  Optional user data that was passed in the HbEffect::start when the effect was started.

*/

/*!  This function can be used to register an FXML file for a particular type of

  component (so that the effect is not tied to any particular widget or graphics

  item instance).

  \param itemType Type of the item effect is targeted to. The same type

  identifier should be used when HbEffect::start is called.  Avoid

  over-simplified item type strings like "item" if there is any risk that it

  will clash with other effect definitions.  Item type strings starting with

  prefix "HB_" are reserved for effects defined internally in HB library.  Such

  definitions cannot be added with this API.

  \param filePath The path of effect definition XML file or the logical name rather than the whole path.

  The logical name corresponds to the XML filename without the extension).

  \param effectEvent Effect event identifier that the effect is targeted to.

  The same type identifier should be used when HbEffect::start is called.

*/

bool HbEffect::add(

    const QString &itemType,

    const QString &filePath,

    const QString &effectEvent)

{

#ifdef HB_EFFECT_API_OFF

    Q_UNUSED(itemType);

    Q_UNUSED(filePath);

    Q_UNUSED(effectEvent);

    return false;

#else

    // This API cannot be used to add HB library's effect definitions.

    // There is internal API in class HbEffectInternal for that.

    if (itemType.startsWith(HB_EFFECT_ITEM_PREFIX)) 

    {

        return false;

    }

    return HbEffectInternal::add(itemType, filePath, effectEvent);

#endif //HB_EFFECT_API_OFF

}

/*!  Registers multiple FXML files at the same time and guarantees that either

  all or none of them are registered. This means that if one of the files cannot

  be found or parsed then none of the others will be registered.

  \param itemType A list of types. The number of elements in all three

  lists must be the same or else the function will fail and return \i

  false. As a special exception \a effectEvent is allowed to be empty

  even when the other lists are not.

  \param filePath A list of file names.

  \param effectEvent A list of effect event identifiers.

  \return True if all the files were registered, false if none. Also returns

  false if the lists' element counts do not match.

  \sa HbEffect::add(const QString &, const QString &, const QString &)

 */

bool HbEffect::add(

    const QStringList &itemType,

    const QStringList &filePath,

    const QStringList &effectEvent)

{

#ifdef HB_EFFECT_API_OFF

    Q_UNUSED(itemType);

    Q_UNUSED(filePath);

    Q_UNUSED(effectEvent);

    return false;

#else

    foreach (const QString &type, itemType) {

        if (type.startsWith(HB_EFFECT_ITEM_PREFIX))

            return false;

    }

    return HbEffectInternal::add(itemType, filePath, effectEvent);

#endif // HB_EFFECT_API_OFF

}

/*!  This function can be used to register an FXML file for a particular object

  instance.  The registered effect will be used when HbEffect::start() is called

  with the matching graphics item and effect event parameters.

  The function takes the following parameters:

  \param item Item which the effect in bound to.

  \param filePath The path of effect definition XML file or the logical name rather than the whole path.

  The logical name corresponds to the XML filename without the extension).

  \param effectEvent Effect event identifier.

*/

bool HbEffect::add(

    QGraphicsItem *item,

    const QString &filePath,

    const QString &effectEvent)

{

#ifdef HB_EFFECT_API_OFF

    Q_UNUSED(item);

    Q_UNUSED(filePath);

    Q_UNUSED(effectEvent);

    return false;

#else

    return HbEffectInternal::add(item, filePath, effectEvent);

#endif //HB_EFFECT_API_OFF

}

/*! Registers multiple FXML files for a particular graphics item and guarantees

 *  that either all or none of them are registered. This means that if one of

 *  the files cannot be found or parsed then none of the others will be

 *  registered.

 *

 * \param item Item to which the effect is bound.

 *

 * \param filePath Name of the FXML file.

 *

 * \param effectEvent Effect event identifier. The number of elements

 * in \a filePath and \a effectEvent must match, unless effectEvent is

 * empty.

 */

bool HbEffect::add(QGraphicsItem *item, const QStringList &filePath, const QStringList &effectEvent)

{

#ifdef HB_EFFECT_API_OFF

    Q_UNUSED(item);

    Q_UNUSED(filePath);

    Q_UNUSED(effectEvent);

#else

    return HbEffectInternal::add(item, filePath, effectEvent);

#endif //HB_EFFECT_API_OFF

}

/*! This function can be used to unregister an FXML file for a particular

  component. Note that you have to have the effect registered with a matching

  itemType identifier to remove it with this method.

  This will not stop any on-going effects (even if the effect is the one being unregistered),

  for that call also cancel() before remove().

  The function takes following parameters:

  \param itemType Type of the item, for example "menu", "button" or "listitem"

  \param filePath The path of effect definition XML file.

  \param effectEvent Effect event identifier.

*/

bool HbEffect::remove(

    const QString &itemType,

    const QString &filePath,

    const QString &effectEvent)

{

#ifdef HB_EFFECT_API_OFF

    Q_UNUSED(itemType);

    Q_UNUSED(filePath);

    Q_UNUSED(effectEvent);

    return false;

#else

    // This API cannot be used to remove HB library's effect definitions.

    // There is internal API in class HbEffectInternal for that.

    if (itemType.startsWith(HB_EFFECT_ITEM_PREFIX)) 

    {

        return false;

    }

    HbEffectInternal::remove(itemType, filePath, effectEvent);

    return true;

#endif //HB_EFFECT_API_OFF

}

/*! This function can be used to unregister an FXML file for a particular item.

  This will not stop any on-going effects (even if the effect is the one being unregistered),

  for that call also cancel() before remove().

  The function takes following parameters:

  \param item The widget or graphics item

  \param filePath The path of effect definition XML file.

  \param effectEvent Effect event identifier.

*/

bool HbEffect::remove(

    QGraphicsItem *item,

    const QString &filePath,

    const QString &effectEvent)

{

#ifdef HB_EFFECT_API_OFF

    Q_UNUSED(item);

    Q_UNUSED(filePath);

    Q_UNUSED(effectEvent);

    return false;

#else

    HbEffectInternal::remove(item, filePath, effectEvent);

    return true;

#endif //HB_EFFECT_API_OFF

}

/*! This function can be used to unregister all FXML files for a particular item.

  This will not stop any on-going effects (even if the effect is the one being unregistered),

  for that call also cancel() before remove().

  The function takes following parameters:

  \param item The instance for which all FXML files must be unregistered

*/

bool HbEffect::remove(QGraphicsItem *item)

{

#ifdef HB_EFFECT_API_OFF

    Q_UNUSED(item);

    return false;

#else

    HbEffectInternal::remove(item);

    return true;

#endif //HB_EFFECT_API_OFF

}

/*! \brief This function is used to start an effect on a graphics item. 

  The effect definition is taken from the FXML file registered for the graphics

  item with matching itemType and effectEvent.