/*
* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
* which accompanies this distribution, and is available
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  Updates applications and icons in Operator Tile.
*
*/


#ifndef __HSWIDGET_H__
#define __HSWIDGET_H__

//  Include Files
#include <cctype>
#include <string>
#include <memory>
#include <vector>

namespace Hs {

class HsWidgetItem;

/**
 * Class defining a Homescreen Widget. A widget is identified by
 * its templateName, widgetName, uniqueIdentifier.
 * 
 * @code
 * @code
 * class ObserverClass : public IHsDataObserver
 * {
 *      void handleEvent( std::string aWidgetName, 
 *			IHsDataObserver::EEvent aEvent)
 *      {
 *      }
 * 
 *      void handleItemEvent( std::string aWidgetName,
 *        	std::string aWidgetItemName,
 *       	IHsDataObserver::EItemEvent aEvent)
 *      {
 *      }
 * }
 * 
 * ObserverClass* dataObserver = new ObserverClass();
 * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
 * HsWidget& widget =  hsPublisher->createHsWidget( 
 *     "templateName", "widgetName", "uniqueIdentifier" );
 * hsPublisher->publishHsWidget( widget ); 
 * @endcode
 */
class HsWidget
    {
public:
    /**
     * Adds a new widget item to the widget if it wasn't created 
     * previously or set a new value to the existing one.
     * Widget item is identified by the name with the value provided. 
     * The value is a string.
     *
     * @code
     * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
     * HsWidget& widget =  hsPublisher->createHsWidget( 
     *     "templateName", "widgetName", "uniqueIdentifier" );
     * // assuming count and values[] are defined
     * while ( count )
     * {
     *    widget->setItem("image", values[count] );
     *    count--;
     * }
     * @endcode
     * @param aItemName, Name of the widget item.
     * @param aValue Integer value of the widget item.
     * @exception HsException
     */
    IMPORT_C void setItem( std::string aItemName, std::string aValue);
    
    /**
     * Adds a new widget item to the widget if it wasn't created previously 
     * or set a new value to the existing one. Widget item is identified by 
     * the name with the value provided. The value is a int.
     *
     * @code
     * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
     * HsWidget& widget =  hsPublisher->createHsWidget( 
     *     "templateName", "widgetName", "uniqueIdentifier" );
     * // assuming count and values[] are defined
     * while ( count )
     * {
     *    widget->setItem("image", values[count] );
     *    count--;
     * }
     * @endcode
     * @param aItemName, Name of the widget item.
     * @param aValue Integer value of the widget item.
     * @exception HsException
     */
    IMPORT_C void setItem( std::string aItemName, int aValue );
    
    /**
     * Method removes widget's item.
     * An attempt to remove not existing item causes exception with 
     * KErrNotFound reason;
     *
     * @code
     * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
     * HsWidget& widget =  hsPublisher->createHsWidget( 
     *     "templateName", "widgetName", "uniqueIdentifier" );
     * widget.setItem( "myItem", "value" );
     * widget.removeItem( "myItem" );
     * hsPublisher->removeHsWidget(
     *     "templateName", "widgetName", "uniqueIdentifier" );
     * @endcode
     * @param aItemName Name of the Item.
     * @param aWidgetName Name of the Widget
     * @param aIdentifier Unique identification of the content.
     * @exception HsException
     */
    IMPORT_C void removeItem( std::string aItemName );
    
public: 
    
    /**
     */
	HsWidget( std::string& aTemplateName, 
        std::string& aWidgetName,
        std::string& aIdentifier );

    /**
     */
    virtual ~HsWidget();
    
    /**
     */
    HsWidgetItem* getWidgetItem( std::string& aItemName );

    /**
     */
    const std::string& getWidgetName();
    
    /**
     */
    const std::string& getTemplateName();
    
    /**
     */
    const std::string& getIdentifier();
    
    /**
     */
    int itemsCount();
    
    /**
     */
    HsWidgetItem* getWidgetItem( int aIndex );
    
    /**
     */
    bool checkIfWidgetItemExist( std::string& aItemName );
    
private:
    std::string mWidgetName;
    std::string mTemplateName;
    std::string mIdentifier;
    std::vector<HsWidgetItem*> mItems;
    };

}


#endif /*__HSWIDGET_H__*/