williamr@2: /*
williamr@2: * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@2: * 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
williamr@2: * which accompanies this distribution, and is available
williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description:  Updates applications and icons in Operator Tile.
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: #ifndef __HSWIDGET_H__
williamr@2: #define __HSWIDGET_H__
williamr@2: 
williamr@2: //  Include Files
williamr@2: #include <cctype>
williamr@2: #include <string>
williamr@2: #include <memory>
williamr@2: #include <vector>
williamr@2: 
williamr@2: namespace Hs {
williamr@2: 
williamr@2: class HsWidgetItem;
williamr@2: 
williamr@2: /**
williamr@2:  * Class defining a Homescreen Widget. A widget is identified by
williamr@2:  * its templateName, widgetName, uniqueIdentifier.
williamr@2:  * 
williamr@2:  * @code
williamr@2:  * @code
williamr@2:  * class ObserverClass : public IHsDataObserver
williamr@2:  * {
williamr@2:  *      void handleEvent( std::string aWidgetName, 
williamr@2:  *			IHsDataObserver::EEvent aEvent)
williamr@2:  *      {
williamr@2:  *      }
williamr@2:  * 
williamr@2:  *      void handleItemEvent( std::string aWidgetName,
williamr@2:  *        	std::string aWidgetItemName,
williamr@2:  *       	IHsDataObserver::EItemEvent aEvent)
williamr@2:  *      {
williamr@2:  *      }
williamr@2:  * }
williamr@2:  * 
williamr@2:  * ObserverClass* dataObserver = new ObserverClass();
williamr@2:  * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
williamr@2:  * HsWidget& widget =  hsPublisher->createHsWidget( 
williamr@2:  *     "templateName", "widgetName", "uniqueIdentifier" );
williamr@2:  * hsPublisher->publishHsWidget( widget ); 
williamr@2:  * @endcode
williamr@2:  */
williamr@2: class HsWidget
williamr@2:     {
williamr@2: public:
williamr@2:     /**
williamr@2:      * Adds a new widget item to the widget if it wasn't created 
williamr@2:      * previously or set a new value to the existing one.
williamr@2:      * Widget item is identified by the name with the value provided. 
williamr@2:      * The value is a string.
williamr@2:      *
williamr@2:      * @code
williamr@2:      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
williamr@2:      * HsWidget& widget =  hsPublisher->createHsWidget( 
williamr@2:      *     "templateName", "widgetName", "uniqueIdentifier" );
williamr@2:      * // assuming count and values[] are defined
williamr@2:      * while ( count )
williamr@2:      * {
williamr@2:      *    widget->setItem("image", values[count] );
williamr@2:      *    count--;
williamr@2:      * }
williamr@2:      * @endcode
williamr@2:      * @param aItemName, Name of the widget item.
williamr@2:      * @param aValue Integer value of the widget item.
williamr@2:      * @exception HsException
williamr@2:      */
williamr@2:     IMPORT_C void setItem( std::string aItemName, std::string aValue);
williamr@2:     
williamr@2:     /**
williamr@2:      * Adds a new widget item to the widget if it wasn't created previously 
williamr@2:      * or set a new value to the existing one. Widget item is identified by 
williamr@2:      * the name with the value provided. The value is a int.
williamr@2:      *
williamr@2:      * @code
williamr@2:      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
williamr@2:      * HsWidget& widget =  hsPublisher->createHsWidget( 
williamr@2:      *     "templateName", "widgetName", "uniqueIdentifier" );
williamr@2:      * // assuming count and values[] are defined
williamr@2:      * while ( count )
williamr@2:      * {
williamr@2:      *    widget->setItem("image", values[count] );
williamr@2:      *    count--;
williamr@2:      * }
williamr@2:      * @endcode
williamr@2:      * @param aItemName, Name of the widget item.
williamr@2:      * @param aValue Integer value of the widget item.
williamr@2:      * @exception HsException
williamr@2:      */
williamr@2:     IMPORT_C void setItem( std::string aItemName, int aValue );
williamr@2:     
williamr@2:     /**
williamr@2:      * Method removes widget's item.
williamr@2:      * An attempt to remove not existing item causes exception with 
williamr@2:      * KErrNotFound reason;
williamr@2:      *
williamr@2:      * @code
williamr@2:      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
williamr@2:      * HsWidget& widget =  hsPublisher->createHsWidget( 
williamr@2:      *     "templateName", "widgetName", "uniqueIdentifier" );
williamr@2:      * widget.setItem( "myItem", "value" );
williamr@2:      * widget.removeItem( "myItem" );
williamr@2:      * hsPublisher->removeHsWidget(
williamr@2:      *     "templateName", "widgetName", "uniqueIdentifier" );
williamr@2:      * @endcode
williamr@2:      * @param aItemName Name of the Item.
williamr@2:      * @param aWidgetName Name of the Widget
williamr@2:      * @param aIdentifier Unique identification of the content.
williamr@2:      * @exception HsException
williamr@2:      */
williamr@2:     IMPORT_C void removeItem( std::string aItemName );
williamr@2:     
williamr@2: public: 
williamr@2:     
williamr@2:     /**
williamr@2:      */
williamr@2: 	HsWidget( std::string& aTemplateName, 
williamr@2:         std::string& aWidgetName,
williamr@2:         std::string& aIdentifier );
williamr@2: 
williamr@2:     /**
williamr@2:      */
williamr@2:     virtual ~HsWidget();
williamr@2:     
williamr@2:     /**
williamr@2:      */
williamr@2:     HsWidgetItem* getWidgetItem( std::string& aItemName );
williamr@2: 
williamr@2:     /**
williamr@2:      */
williamr@2:     const std::string& getWidgetName();
williamr@2:     
williamr@2:     /**
williamr@2:      */
williamr@2:     const std::string& getTemplateName();
williamr@2:     
williamr@2:     /**
williamr@2:      */
williamr@2:     const std::string& getIdentifier();
williamr@2:     
williamr@2:     /**
williamr@2:      */
williamr@2:     int itemsCount();
williamr@2:     
williamr@2:     /**
williamr@2:      */
williamr@2:     HsWidgetItem* getWidgetItem( int aIndex );
williamr@2:     
williamr@2:     /**
williamr@2:      */
williamr@2:     bool checkIfWidgetItemExist( std::string& aItemName );
williamr@2:     
williamr@2: private:
williamr@2:     std::string mWidgetName;
williamr@2:     std::string mTemplateName;
williamr@2:     std::string mIdentifier;
williamr@2:     std::vector<HsWidgetItem*> mItems;
williamr@2:     };
williamr@2: 
williamr@2: }
williamr@2: 
williamr@2: 
williamr@2: #endif /*__HSWIDGET_H__*/