/*
* Copyright (c) 2009 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:  Homescreen widget preference service.
*
*/


#ifndef HSIWIDGETPREFERENCESERVICE_H
#define HSIWIDGETPREFERENCESERVICE_H

class QString;
class HsWidget;

/**
 * @ingroup group_hswidgetmodel group_widget_api_candidates
 * @brief Preference store for widget.
 *
 * The preference service is a key/value store with both the key and
 * the value being strings. The widget may store data to be reused
 * at a later date, such as a username, settings for the widget, persistent data,
 * and so on. The data is stored on the device, for example on its hard drive,
 * and can be read back at any time.
 *
 * @lib ?library
 * @since S60 ?S60_version
 */
class IHsWidgetPreferenceService
{
public:

	/**
     * Save a widget preference.
	 * This method will store the given value in the widget
	 * in the widget preference store for the given key.
	 *
	 * The preference store is unique to this widget and any values
	 * stored in it are persisted if the widget is reloaded or closed
	 * and started again.
	 *
	 * If a value for the given key already exists, it is silently
	 * overwritten. Storing an empty string for the given key will
	 * create an entry for the given key with an empty string as its value.
	 *
	 * @param widget HsWidget instance.
     * @param key The preference to get from the preference store.
     * @param value The value of the preference.
	 * @return True on success, false otherwise.
	 */
	virtual bool setPreferenceForKey(HsWidget *widget, const QString &key, const QString &value)=0;

	/**
	 * Get a preference from the widget preference store.
	 * Get the value stored for the given key in the widget preference store.
	 * If there is no value for the given key, an empty string is returned.
	 *
	 * @param widget HsWidget instance.
     * @param key The preference to get from the preference store.
     * @param value The value of the preference.
	 * @return True on success, false otherwise.
	 */
	virtual bool preferenceForKey(HsWidget *widget, const QString &key, QString &value)=0;

};

Q_DECLARE_METATYPE(IHsWidgetPreferenceService*)
#endif