1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/hswidgetpublisher.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -0,0 +1,227 @@
1.4 +/*
1.5 +* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* 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
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: Updates applications and icons in Operator Tile.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +// This file defines the API for hswidgetpublisher.dll
1.23 +
1.24 +#ifndef __HSWIDGETPUBLISHER_H__
1.25 +#define __HSWIDGETPUBLISHER_H__
1.26 +
1.27 +// Include Files
1.28 +#include <cctype>
1.29 +#include <memory>
1.30 +#include <string>
1.31 +
1.32 +namespace Hs {
1.33 +
1.34 +// Class Definitions
1.35 +class HsWidget;
1.36 +class IHsDataObserver;
1.37 +class HsWidgetPublisherImpl;
1.38 +
1.39 +/**
1.40 + * Class allowing access to the Homescreen Publishing Api.
1.41 + * Allows creation, update and deletion of widgets, as well as reception of
1.42 + * information for the occuring events.
1.43 + *
1.44 + * @code
1.45 + * class ObserverClass : public IHsDataObserver
1.46 + * {
1.47 + * void handleEvent( std::string aWidgetName,
1.48 + * IHsDataObserver::EEvent aEvent)
1.49 + * {
1.50 + * }
1.51 + *
1.52 + * void handleItemEvent( std::string aWidgetName,
1.53 + * std::string aWidgetItemName,
1.54 + * IHsDataObserver::EItemEvent aEvent)
1.55 + * {
1.56 + * }
1.57 + * }
1.58 + *
1.59 + * ObserverClass* dataObserver = new ObserverClass();
1.60 + * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
1.61 + * HsWidget& widget = publisher->createHsWidget(
1.62 + * "templateName", "widgetName", "uniqueIdentifier" );
1.63 + * // assuming count and values[] exists
1.64 + * while (count)
1.65 + * {
1.66 + * widget->setItem( "image", values[count] );
1.67 + * count--;
1.68 + * }
1.69 + * hsPublisher->publishHsWidget( widget );
1.70 + * @endcode
1.71 + */
1.72 +class HsWidgetPublisher
1.73 + {
1.74 +public:
1.75 + /**
1.76 + * Constructor of the HsWidgetPublisher. Creates an instance of the
1.77 + * publisher, which is used to manage Widgets and Widget's Items.
1.78 + * Please note that attempt of usage, with aDataObserver = NULL
1.79 + * is asserted.
1.80 + *
1.81 + * @code
1.82 + * class ObserverClass : public IHsDataObserver
1.83 + * {
1.84 + * void handleEvent( std::string aWidgetName,
1.85 + * IHsDataObserver::EEvent aEvent)
1.86 + * {
1.87 + * }
1.88 + *
1.89 + * void handleItemEvent( std::string aWidgetName,
1.90 + * std::string aWidgetItemName,
1.91 + * IHsDataObserver::EItemEvent aEvent)
1.92 + * {
1.93 + * }
1.94 + * }
1.95 + *
1.96 + * ObserverClass* dataObserver = new ObserverClass();
1.97 + * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
1.98 + * @endcode
1.99 + *
1.100 + * Client should not completely rely on exceptions while creating
1.101 + * the API. Except for exceptions thrown one should check if
1.102 + * the memory was allocated properly.
1.103 + * @code
1.104 + *
1.105 + * ObserverClass* dataObserver = new ObserverClass();
1.106 + *
1.107 + * try
1.108 + * {
1.109 + * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher(dataObserver);
1.110 + * if (hsPublisher)
1.111 + * {
1.112 + * // do the operations on the API here
1.113 + * }
1.114 + * }
1.115 + * catch (HsException& exception)
1.116 + * {
1.117 + * int errReason = exception.getReason();
1.118 + * }
1.119 + * @endcode
1.120 + *
1.121 + * @param aDataObserver Callback interface for handling actions.
1.122 + * @exception HsPException
1.123 + */
1.124 + IMPORT_C HsWidgetPublisher( IHsDataObserver* aDataObserver );
1.125 +
1.126 + /**
1.127 + * Destructor of the HsWidgetPublisher.
1.128 + *
1.129 + * @code
1.130 + * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
1.131 + * delete hsPublisher;
1.132 + * @endcode
1.133 + * @exception HsException
1.134 + */
1.135 + IMPORT_C ~HsWidgetPublisher();
1.136 +
1.137 + /**
1.138 + * Method creates a new widget.
1.139 + * Attempt to create already existing widget will cause exception
1.140 + * with KErrAlreadyExists reason.
1.141 + * Other exception reasons are possible and are caused by widget
1.142 + * registration.
1.143 + *
1.144 + * @code
1.145 + * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
1.146 + * HsWidget& widget = hsPublisher->createHsWidget(
1.147 + * "templateName", "widgetName", "uniqueIdentifier" );
1.148 + * @endcode
1.149 + * @param aTemplateName Name of the Template.
1.150 + * @param aWidgetName Name of the Widget
1.151 + * @param aIdentifier Unique identification of the content.
1.152 + * @return A widget is returned. If no such widget existed a newly
1.153 + * created one.
1.154 + * @exception HsException Exception is thrown when with code
1.155 + * KErrAlreadyExists
1.156 + * when attempting to create a widget that already exists. Other cases
1.157 + * when excpetion is thrown include problems with widget registration.
1.158 + */
1.159 + IMPORT_C HsWidget& createHsWidget( std::string aTemplateName,
1.160 + std::string aWidgetName,
1.161 + std::string aIdentifier );
1.162 +
1.163 + /**
1.164 + * Method publishes the provided widget.
1.165 + * Widget needs to be published in order for the content
1.166 + * to be seen by the HS.
1.167 + *
1.168 + * @code
1.169 + * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
1.170 + * HsWidget& widget = hsPublisher->createHsWidget(
1.171 + * "templateName", "widgetName", "uniqueIdentifier" );
1.172 + * hsPublisher->publishHsWidget( widget );
1.173 + * @endcode
1.174 + * @param aWidget Reference to a widget object.
1.175 + * @exception HsException
1.176 + */
1.177 + IMPORT_C void publishHsWidget( HsWidget& aWidget );
1.178 +
1.179 + /**
1.180 + * Method removes a widget.
1.181 + *
1.182 + * @code
1.183 + * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
1.184 + * hsPublisher->createHsWidget(
1.185 + * "templateName", "widgetName", "uniqueIdentifier" );
1.186 + * publisher->removeHsWidget(
1.187 + * "templateName", "widgetName", "uniqueIdentifier" );
1.188 + * @endcode
1.189 + * @param aTemplateName Name of the Template.
1.190 + * @param aWidgetName Name of the Widget
1.191 + * @param aIdentifier Unique identification of the content.
1.192 + * @exception HsException
1.193 + */
1.194 + IMPORT_C void removeHsWidget( std::string aTemplateName,
1.195 + std::string aWidgetName,
1.196 + std::string aIdentifier );
1.197 +
1.198 + /**
1.199 + * Obtains a Widget from Homescreen Publishing Api.
1.200 + * Attempt of obtaining Widget that was not created cause exception
1.201 + * with KErrNotFound rason.
1.202 + *
1.203 + *
1.204 + * @code
1.205 + * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
1.206 + * hsPublisher->createHsWidget(
1.207 + * "templateName", "widgetName", "uniqueIdentifier" );
1.208 + * HsWidget& widget = hsPublisher->getHsWidget(
1.209 + * "templateName", "widgetName", "uniqueIdentifier" );
1.210 + * @endcode
1.211 + * @param aTemplateName Name of the Template.
1.212 + * @param aWidgetName Name of the Widget
1.213 + * @param aIdentifier Unique identification of the content.
1.214 + * @return Error code.
1.215 + * @exception HsException
1.216 + */
1.217 + IMPORT_C HsWidget& getHsWidget( std::string aTemplateName,
1.218 + std::string aWidgetName,
1.219 + std::string aIdentifier );
1.220 +
1.221 +
1.222 +private: //members
1.223 +
1.224 + std::auto_ptr<HsWidgetPublisherImpl> mImpl;
1.225 +
1.226 + };
1.227 +}
1.228 +
1.229 +#endif // __HSWIDGETPUBLISHER_H__
1.230 +