Symbian^3 Product Developer Library >

Hs::HsWidgetPublisher Class Reference

class Hs::HsWidgetPublisher

Class allowing access to the Homescreen Publishing Api. Allows creation, update and deletion of widgets, as well as reception of information for the occuring events.

 class ObserverClass : public IHsDataObserver
 {
      void handleEvent( std::string aWidgetName, 
			IHsDataObserver::EEvent aEvent)
      {
      }
 
      void handleItemEvent( std::string aWidgetName,
        	std::string aWidgetItemName,
       	IHsDataObserver::EItemEvent aEvent)
      {
      }
 }
 
 ObserverClass* dataObserver = new ObserverClass();
 HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
 HsWidget& widget =  publisher->createHsWidget(
     "templateName", "widgetName", "uniqueIdentifier" );
 // assuming count and values[] exists
 while (count)
 {
    widget->setItem( "image", values[count] );
    count--;
 }
 hsPublisher->publishHsWidget( widget );
Public Member Functions
HsWidgetPublisher(IHsDataObserver *)
~HsWidgetPublisher()
IMPORT_C HsWidget &createHsWidget(std::string, std::string, std::string)
IMPORT_C HsWidget &createHsWidgetWithDesc(std::string, std::string, std::string, std::string, std::string)
IMPORT_C HsWidget &getHsWidget(std::string, std::string, std::string)
IMPORT_C voidpublishHsWidget(HsWidget &)
IMPORT_C voidremoveHsWidget(std::string, std::string, std::string)
Private Attributes
std::auto_ptr< HsWidgetPublisherImpl >mImpl

Constructor & Destructor Documentation

HsWidgetPublisher(IHsDataObserver *)

IMPORT_CHsWidgetPublisher(IHsDataObserver *aDataObserver)

Constructor of the HsWidgetPublisher. Creates an instance of the publisher, which is used to manage Widgets and Widget's Items. Please note that attempt of usage, with aDataObserver = NULL is asserted.

 class ObserverClass : public IHsDataObserver
 {
      void handleEvent( std::string aWidgetName, 
			IHsDataObserver::EEvent aEvent)
      {
      }
 
      void handleItemEvent( std::string aWidgetName,
        	std::string aWidgetItemName,
       	IHsDataObserver::EItemEvent aEvent)
      {
      }
 }       
 
 ObserverClass* dataObserver = new ObserverClass();
 HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
Client should not completely rely on exceptions while creating the API. Except for exceptions thrown one should check if the memory was allocated properly. 
 ObserverClass* dataObserver = new ObserverClass();
 
 try 
 {
     HsWidgetPublisher* hsPublisher = new HsWidgetPublisher(dataObserver);
     if (hsPublisher)
     {
     // do the operations on the API here
     }
 }
 catch (HsException& exception)
 {
     int errReason = exception.getReason();
 }
Exceptions
HsPException

Parameters

IHsDataObserver * aDataObserverCallback interface for handling actions.

~HsWidgetPublisher()

IMPORT_C~HsWidgetPublisher()

Destructor of the HsWidgetPublisher.

 HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
 delete hsPublisher;
Exceptions
HsException

Member Functions Documentation

createHsWidget(std::string, std::string, std::string)

IMPORT_C HsWidget &createHsWidget(std::stringaTemplateName,
std::stringaWidgetName,
std::stringaIdentifier
)

DEPRECATED. This method is here only to maintain compatibility with legacy widgets. Please use createHsWidgetWithDesc instead of this method.

Method creates a new widget. Attempt to create already existing widget will cause exception with KErrAlreadyExists reason. Other exception reasons are possible and are caused by widget registration.

 HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
 HsWidget& widget =  hsPublisher->createHsWidget( 
     "templateName", "widgetName", "uniqueIdentifier" );
Exceptions
HsException

Exception is thrown when with code KErrAlreadyExists when attempting to create a widget that already exists. Other cases when excpetion is thrown include problems with widget registration.

Parameters

std::string aTemplateNameName of the Template.
std::string aWidgetNameName of the Widget
std::string aIdentifierUnique identification of the content.

createHsWidgetWithDesc(std::string, std::string, std::string, std::string, std::string)

IMPORT_C HsWidget &createHsWidgetWithDesc(std::stringaTemplateName,
std::stringaWidgetName,
std::stringaIdentifier,
std::stringaDescription,
std::stringaIconLocation
)

Creates a new widget.

If widget already created, fails and throws a HsException containing KErrAlreadyExists error code. May throw HsException with different system-wide error codes if error occurs during registration.

 HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
 HsWidget& widget =  hsPublisher->createHsWidgetWithDesc( 
     "templateName", "widgetName", "uniqueIdentifier",
     "A short widget description.", "c:\\data\\Installs\\an_icon.jpg" );
Exceptions
HsException

Parameters

std::string aTemplateNameName of the Template.
std::string aWidgetNameName of the Widget
std::string aIdentifierUnique widget indentifier. It is recommended to use your application's UID3 as the identifier. If your application creates two different HsWidgets, their identifiers must be unique too, in such case consider using UID3 with an extra suffix, e.g. 0xE2DA0574_1 for the first widget and 0xE2DA0574_2 for the second one.
std::string aDescriptionA short widget description (e.g. 'Displays latest news and wheather forecast.')
std::string aIconLocationA location of a logo icon that will be displayed alongside the short description. There are 4 ways in which icon location can be specified: 1. system path (e.g. c:\data\Installs\icon1.jpg) 2. MIF file (e.g. c:\data\Installs\templateIcons.mif 16384 16385) 3. skin with MIF file fallback (e.g. skin(major_id minor_id):mif(c:\data\icons.mif 16386 16387) 4.icon from AppArc (e.g. uid(0x12345678))

getHsWidget(std::string, std::string, std::string)

IMPORT_C HsWidget &getHsWidget(std::stringaTemplateName,
std::stringaWidgetName,
std::stringaIdentifier
)

Obtains a Widget from Homescreen Publishing Api. Attempt of obtaining Widget that was not created cause exception with KErrNotFound rason.

 HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
 hsPublisher->createHsWidget( 
     "templateName", "widgetName", "uniqueIdentifier" );
 HsWidget& widget = hsPublisher->getHsWidget(
     "templateName", "widgetName", "uniqueIdentifier" );
Exceptions
HsException

Parameters

std::string aTemplateNameName of the Template.
std::string aWidgetNameName of the Widget
std::string aIdentifierUnique identification of the content.

publishHsWidget(HsWidget &)

IMPORT_C voidpublishHsWidget(HsWidget &aWidget)

Method publishes the provided widget. Widget needs to be published in order for the content to be seen by the HS. For correct behaviour during publishing, events received from HS must be handled appropriately.

 HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
 HsWidget& widget =  hsPublisher->createHsWidget( 
     "templateName", "widgetName", "uniqueIdentifier" );
 hsPublisher->publishHsWidget( widget );
Exceptions
HsException

Parameters

HsWidget & aWidgetReference to a widget object.

removeHsWidget(std::string, std::string, std::string)

IMPORT_C voidremoveHsWidget(std::stringaTemplateName,
std::stringaWidgetName,
std::stringaIdentifier
)

Method removes a widget.

 HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
 hsPublisher->createHsWidget( 
     "templateName", "widgetName", "uniqueIdentifier" );
 publisher->removeHsWidget(
     "templateName", "widgetName", "uniqueIdentifier" );
Exceptions
HsException

Parameters

std::string aTemplateNameName of the Template.
std::string aWidgetNameName of the Widget
std::string aIdentifierUnique identification of the content.

Member Data Documentation

std::auto_ptr< HsWidgetPublisherImpl > mImpl

std::auto_ptr< HsWidgetPublisherImpl >mImpl[private]

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.