Collapse all Symbian^3 Application 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 void	publishHsWidget ( HsWidget &)
IMPORT_C void	removeHsWidget ( std::string , std::string , std::string )

Private Attributes
std::auto_ptr< HsWidgetPublisherImpl >	mImpl

Constructor & Destructor Documentation

HsWidgetPublisher(IHsDataObserver *)

IMPORT_C

HsWidgetPublisher

(

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

Callback 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::string	aTemplateName,
			std::string	aWidgetName,
			std::string	aIdentifier
		)

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 aTemplateName	Name of the Template.
std::string aWidgetName	Name of the Widget
std::string aIdentifier	Unique identification of the content.

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

IMPORT_C HsWidget &	createHsWidgetWithDesc	(	std::string	aTemplateName,
			std::string	aWidgetName,
			std::string	aIdentifier,
			std::string	aDescription,
			std::string	aIconLocation
		)

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 aTemplateName	Name of the Template.
std::string aWidgetName	Name of the Widget
std::string aIdentifier	Unique 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 aDescription	A short widget description (e.g. 'Displays latest news and wheather forecast.')
std::string aIconLocation	A 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::string	aTemplateName,
			std::string	aWidgetName,
			std::string	aIdentifier
		)

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 aTemplateName	Name of the Template.
std::string aWidgetName	Name of the Widget
std::string aIdentifier	Unique identification of the content.

publishHsWidget(HsWidget &)

IMPORT_C void

publishHsWidget

(

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 & aWidget

Reference to a widget object.

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

IMPORT_C void	removeHsWidget	(	std::string	aTemplateName,
			std::string	aWidgetName,
			std::string	aIdentifier
		)

Method removes a widget.

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

Exceptions

HsException

Parameters

std::string aTemplateName	Name of the Template.
std::string aWidgetName	Name of the Widget
std::string aIdentifier	Unique identification of the content.

Member Data Documentation

std::auto_ptr< HsWidgetPublisherImpl > mImpl

std::auto_ptr< HsWidgetPublisherImpl >

mImpl

[private]