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: // This file defines the API for hswidgetpublisher.dll williamr@2: williamr@2: #ifndef __HSWIDGETPUBLISHER_H__ williamr@2: #define __HSWIDGETPUBLISHER_H__ williamr@2: williamr@2: // Include Files williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: namespace Hs { williamr@2: williamr@2: // Class Definitions williamr@2: class HsWidget; williamr@2: class IHsDataObserver; williamr@2: class HsWidgetPublisherImpl; williamr@2: williamr@2: /** williamr@2: * Class allowing access to the Homescreen Publishing Api. williamr@2: * Allows creation, update and deletion of widgets, as well as reception of williamr@2: * information for the occuring events. williamr@2: * 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 = publisher->createHsWidget( williamr@2: * "templateName", "widgetName", "uniqueIdentifier" ); williamr@2: * // assuming count and values[] exists williamr@2: * while (count) williamr@2: * { williamr@2: * widget->setItem( "image", values[count] ); williamr@2: * count--; williamr@2: * } williamr@2: * hsPublisher->publishHsWidget( widget ); williamr@2: * @endcode williamr@2: */ williamr@2: class HsWidgetPublisher williamr@2: { williamr@2: public: williamr@2: /** williamr@2: * Constructor of the HsWidgetPublisher. Creates an instance of the williamr@2: * publisher, which is used to manage Widgets and Widget's Items. williamr@2: * Please note that attempt of usage, with aDataObserver = NULL williamr@2: * is asserted. williamr@2: * 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: * @endcode williamr@2: * williamr@2: * Client should not completely rely on exceptions while creating williamr@2: * the API. Except for exceptions thrown one should check if williamr@2: * the memory was allocated properly. williamr@2: * @code williamr@2: * williamr@2: * ObserverClass* dataObserver = new ObserverClass(); williamr@2: * williamr@2: * try williamr@2: * { williamr@2: * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher(dataObserver); williamr@2: * if (hsPublisher) williamr@2: * { williamr@2: * // do the operations on the API here williamr@2: * } williamr@2: * } williamr@2: * catch (HsException& exception) williamr@2: * { williamr@2: * int errReason = exception.getReason(); williamr@2: * } williamr@2: * @endcode williamr@2: * williamr@2: * @param aDataObserver Callback interface for handling actions. williamr@2: * @exception HsPException williamr@2: */ williamr@2: IMPORT_C HsWidgetPublisher( IHsDataObserver* aDataObserver ); williamr@2: williamr@2: /** williamr@2: * Destructor of the HsWidgetPublisher. williamr@2: * williamr@2: * @code williamr@2: * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver ); williamr@2: * delete hsPublisher; williamr@2: * @endcode williamr@2: * @exception HsException williamr@2: */ williamr@2: IMPORT_C ~HsWidgetPublisher(); williamr@2: williamr@2: /** williamr@2: * Method creates a new widget. williamr@2: * Attempt to create already existing widget will cause exception williamr@2: * with KErrAlreadyExists reason. williamr@2: * Other exception reasons are possible and are caused by widget williamr@2: * registration. 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: * @endcode williamr@2: * @param aTemplateName Name of the Template. williamr@2: * @param aWidgetName Name of the Widget williamr@2: * @param aIdentifier Unique identification of the content. williamr@2: * @return A widget is returned. If no such widget existed a newly williamr@2: * created one. williamr@2: * @exception HsException Exception is thrown when with code williamr@2: * KErrAlreadyExists williamr@2: * when attempting to create a widget that already exists. Other cases williamr@2: * when excpetion is thrown include problems with widget registration. williamr@2: */ williamr@2: IMPORT_C HsWidget& createHsWidget( std::string aTemplateName, williamr@2: std::string aWidgetName, williamr@2: std::string aIdentifier ); williamr@2: williamr@2: /** williamr@2: * Method publishes the provided widget. williamr@2: * Widget needs to be published in order for the content williamr@2: * to be seen by the HS. 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: * hsPublisher->publishHsWidget( widget ); williamr@2: * @endcode williamr@2: * @param aWidget Reference to a widget object. williamr@2: * @exception HsException williamr@2: */ williamr@2: IMPORT_C void publishHsWidget( HsWidget& aWidget ); williamr@2: williamr@2: /** williamr@2: * Method removes a widget. williamr@2: * williamr@2: * @code williamr@2: * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver ); williamr@2: * hsPublisher->createHsWidget( williamr@2: * "templateName", "widgetName", "uniqueIdentifier" ); williamr@2: * publisher->removeHsWidget( williamr@2: * "templateName", "widgetName", "uniqueIdentifier" ); williamr@2: * @endcode williamr@2: * @param aTemplateName Name of the Template. 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 removeHsWidget( std::string aTemplateName, williamr@2: std::string aWidgetName, williamr@2: std::string aIdentifier ); williamr@2: williamr@2: /** williamr@2: * Obtains a Widget from Homescreen Publishing Api. williamr@2: * Attempt of obtaining Widget that was not created cause exception williamr@2: * with KErrNotFound rason. williamr@2: * williamr@2: * williamr@2: * @code williamr@2: * HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver ); williamr@2: * hsPublisher->createHsWidget( williamr@2: * "templateName", "widgetName", "uniqueIdentifier" ); williamr@2: * HsWidget& widget = hsPublisher->getHsWidget( williamr@2: * "templateName", "widgetName", "uniqueIdentifier" ); williamr@2: * @endcode williamr@2: * @param aTemplateName Name of the Template. williamr@2: * @param aWidgetName Name of the Widget williamr@2: * @param aIdentifier Unique identification of the content. williamr@2: * @return Error code. williamr@2: * @exception HsException williamr@2: */ williamr@2: IMPORT_C HsWidget& getHsWidget( std::string aTemplateName, williamr@2: std::string aWidgetName, williamr@2: std::string aIdentifier ); williamr@2: williamr@2: williamr@2: private: //members williamr@2: williamr@2: std::auto_ptr mImpl; williamr@2: williamr@2: }; williamr@2: } williamr@2: williamr@2: #endif // __HSWIDGETPUBLISHER_H__ williamr@2: