1.1 --- a/epoc32/include/hswidgetpublisher.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,227 +0,0 @@
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 -