/*

 * 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__*/