/*

* Copyright (c) 2009-2010 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:

*

*/

/*

 * cxesettings.h

 *

 *  Created on: Dec 30, 2008

 *      

 */

#ifndef CXESETTINGS_H_

#define CXESETTINGS_H_

#include <QObject>

#include <QString>

#include <QVariant>

#include "cxeerror.h"

#include "cxenamespace.h"

#include "cxeexception.h"

/*!

* Class to access all kind of Camera Settings

*

* There are templated get() and set() methods for accessing and modifying settings.

* Supported types are int, qreal, QString, QVariantMap and enums.

*

* It is possible to monitor changes in settings, either by connecting to settingValueChanged() signal

* or registering a slot as listener to a specific setting using listenForSetting(). With the latter

* method you will only be notified of the change in the requested setting, as opposed to the settingValueChanged()

* which will be emitted for any setting change.

*/

class CxeSettings : public QObject

{

    Q_OBJECT

public:

    /*!

    * Returns value of external setting item which is not owned by camera

    */

    virtual void get(long int uid,

                     unsigned long int key,

                     Cxe::SettingKeyType type,

                     QVariant &value) const = 0;

    /*!

     * Get a value of a certain setting. Template method that can be used

     * with any enumeration (well actually, anything that can be cast to from int),

     * int, QString and QVariantMap. Will throw CxeException in case of error.

     *

     * An example:

     * \code

     *  try {

     *      Cxe::Whitebalance wb = settings.get<Cxe::Whitebalance>(CxeSettingIds::WHITE_BALANCE);

     *  catch (CxeException &e) {

     *      CX_DEBUG(("Error getting white balance"));

     *  }

     * \endcode

     * @param settingId  Setting key

     * @return           Setting value

     */

    template<typename T>

    inline T get(const QString &key) const {

        QVariant v;

        getValue(key, v);

        return (T)v.value<int>();

    }

    /*!

     * Same as above but with default value in case of error. No exceptions are thrown.

     *

     *An example:

     * \code

     *

     *  Cxe::Whitebalance wb = settings.get<Cxe::Whitebalance>(CxeSettingIds::WHITE_BALANCE, Cxe::WhitebalanceAutomatic);

     *

     * \endcode

     * @param key           Setting key

     * @param defaultValue  Default value returned in case of error

     * @return              Value of the setting

     */

    template<typename T>

    inline T get(const QString &key, const T &defaultValue) const {

        try {

            return get<T>(key);

        } catch (CxeException &e) {

            return defaultValue;

        }

    }

    /*!

    * Set a value of a certain setting. Template method that can be used

    * with any enumeration (well actually, anything that can be cast to from int),

    * int, QString and QVariantMap.

    *

    * An example:

    * \code

    *  try {

    *      Cxe::Whitebalance wb = Cxe::WhiteBalanceAutomatic;

    *      settings.get<Cxe::Whitebalance>(CxeSettingIds::WHITE_BALANCE, wb);

    *  catch (CxeException &e) {

    *      CX_DEBUG(("Error setting white balance"));

    *  }

    * \endcode

    * @param settingId  Setting key

    * @param value     Setting value

    */

    template<typename T>

    inline void set(const QString &key, const T &value) {

       QVariant v;

       v.setValue((int)value);

       setValue(key, v);

    }

    /*!

    * Resets settings to default values.

    */

    virtual void reset() = 0;

    /*!

     * Get value of variation setting.

     */

    virtual CxeError::Id getVariationValue(const QString &key, QVariant &value) = 0;

    /*!

     * Add listener for changes in one setting. When the value of the setting changes, the given

     * slot is invoked on given object.

     *

     * @param settingKey Setting to listen to

     * @param target Object that the slot will be invoked for

     * @param slot Slot that will be invoked. The slot can have either of these two signatures:

     *   slotName(const QVariant&)    only new value of setting is passed as parameter

     *   slotName(const QString&, const QVariant&) both setting key and new value are passed as parameter

     * @return boolean to indicate success

     */

    virtual bool listenForSetting(const QString &settingKey, QObject *target, const char *slot) = 0;

protected:

    /*!

     * returns the setting as QVariant

     */

    virtual void getValue(const QString &key, QVariant &value) const = 0;

    /*!

    * Set new value for the given key

    */

    virtual void setValue(const QString &key, const QVariant &newValue) = 0;

signals:

    /*!

    * to notify engine and ui components for a change in a setting value

    */

    void settingValueChanged(const QString &key, QVariant newValue);

    /*!

    * to notify engine and ui components for a change in a setting value

    */

    void settingValueChanged(long int uid, unsigned long int key, QVariant value);

protected:

    CxeSettings() {}

private:

    Q_DISABLE_COPY( CxeSettings )

};

// include set/get function specializations

#include "cxesettings.inl"

#endif /*CXESETTINGS_H_*/

// end  of file