1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Updates applications and icons in Operator Tile.

    15 *

    16 */

    17 

    18 

    19 #ifndef __HSWIDGET_H__

    20 #define __HSWIDGET_H__

    21 

    22 //  Include Files

    23 #include <cctype>

    24 #include <string>

    25 #include <memory>

    26 #include <vector>

    27 

    28 namespace Hs {

    29 

    30 class HsWidgetItem;

    31 

    32 /**

    33  * Class defining a Homescreen Widget. A widget is identified by

    34  * its templateName, widgetName, uniqueIdentifier.

    35  * 

    36  * @code

    37  * @code

    38  * class ObserverClass : public IHsDataObserver

    39  * {

    40  *      void handleEvent( std::string aWidgetName, 

    41  *			IHsDataObserver::EEvent aEvent)

    42  *      {

    43  *      }

    44  * 

    45  *      void handleItemEvent( std::string aWidgetName,

    46  *        	std::string aWidgetItemName,

    47  *       	IHsDataObserver::EItemEvent aEvent)

    48  *      {

    49  *      }

    50  * }

    51  * 

    52  * ObserverClass* dataObserver = new ObserverClass();

    53  * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

    54  * HsWidget& widget =  hsPublisher->createHsWidget( 

    55  *     "templateName", "widgetName", "uniqueIdentifier" );

    56  * hsPublisher->publishHsWidget( widget ); 

    57  * @endcode

    58  */

    59 class HsWidget

    60     {

    61 public:

    62     /**

    63      * Adds a new widget item to the widget if it wasn't created 

    64      * previously or set a new value to the existing one.

    65      * Widget item is identified by the name with the value provided. 

    66      * The value is a string.

    67      *

    68      * @code

    69      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

    70      * HsWidget& widget =  hsPublisher->createHsWidget( 

    71      *     "templateName", "widgetName", "uniqueIdentifier" );

    72      * // assuming count and values[] are defined

    73      * while ( count )

    74      * {

    75      *    widget->setItem("image", values[count] );

    76      *    count--;

    77      * }

    78      * @endcode

    79      * @param aItemName, Name of the widget item.

    80      * @param aValue Integer value of the widget item.

    81      * @exception HsException

    82      */

    83     IMPORT_C void setItem( std::string aItemName, std::string aValue);

    84     

    85     /**

    86      * Adds a new widget item to the widget if it wasn't created previously 

    87      * or set a new value to the existing one. Widget item is identified by 

    88      * the name with the value provided. The value is a int.

    89      *

    90      * @code

    91      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

    92      * HsWidget& widget =  hsPublisher->createHsWidget( 

    93      *     "templateName", "widgetName", "uniqueIdentifier" );

    94      * // assuming count and values[] are defined

    95      * while ( count )

    96      * {

    97      *    widget->setItem("image", values[count] );

    98      *    count--;

    99      * }

   100      * @endcode

   101      * @param aItemName, Name of the widget item.

   102      * @param aValue Integer value of the widget item.

   103      * @exception HsException

   104      */

   105     IMPORT_C void setItem( std::string aItemName, int aValue );

   106     

   107     /**

   108      * Method removes widget's item.

   109      * An attempt to remove not existing item causes exception with 

   110      * KErrNotFound reason;

   111      *

   112      * @code

   113      * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );

   114      * HsWidget& widget =  hsPublisher->createHsWidget( 

   115      *     "templateName", "widgetName", "uniqueIdentifier" );

   116      * widget.setItem( "myItem", "value" );

   117      * widget.removeItem( "myItem" );

   118      * hsPublisher->removeHsWidget(

   119      *     "templateName", "widgetName", "uniqueIdentifier" );

   120      * @endcode

   121      * @param aItemName Name of the Item.

   122      * @param aWidgetName Name of the Widget

   123      * @param aIdentifier Unique identification of the content.

   124      * @exception HsException

   125      */

   126     IMPORT_C void removeItem( std::string aItemName );

   127     

   128 public: 

   129     

   130     /**

   131      */

   132 	HsWidget( std::string& aTemplateName, 

   133         std::string& aWidgetName,

   134         std::string& aIdentifier );

   135 

   136     /**

   137      */

   138     virtual ~HsWidget();

   139     

   140     /**

   141      */

   142     HsWidgetItem* getWidgetItem( std::string& aItemName );

   143 

   144     /**

   145      */

   146     const std::string& getWidgetName();

   147     

   148     /**

   149      */

   150     const std::string& getTemplateName();

   151     

   152     /**

   153      */

   154     const std::string& getIdentifier();

   155     

   156     /**

   157      */

   158     int itemsCount();

   159     

   160     /**

   161      */

   162     HsWidgetItem* getWidgetItem( int aIndex );

   163     

   164     /**

   165      */

   166     bool checkIfWidgetItemExist( std::string& aItemName );

   167     

   168 private:

   169     std::string mWidgetName;

   170     std::string mTemplateName;

   171     std::string mIdentifier;

   172     std::vector<HsWidgetItem*> mItems;

   173     };

   174 

   175 }

   176 

   177 

   178 #endif /*__HSWIDGET_H__*/