Hs::HsWidgetPublisher Class Reference

Link against: hswidgetpublisher.lib

#include <hswidgetpublisher.h>

Detailed Description

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

IMPORT_C HsWidgetPublisher (IHsDataObserver *aDataObserver)
 Constructor of the HsWidgetPublisher.
IMPORT_C ~HsWidgetPublisher ()
 Destructor of the HsWidgetPublisher.
IMPORT_C HsWidget & createHsWidget (std::string aTemplateName, std::string aWidgetName, std::string aIdentifier)
 Method creates a new widget.
IMPORT_C void publishHsWidget (HsWidget &aWidget)
 Method publishes the provided widget.
IMPORT_C void removeHsWidget (std::string aTemplateName, std::string aWidgetName, std::string aIdentifier)
 Method removes a widget.
IMPORT_C HsWidget & getHsWidget (std::string aTemplateName, std::string aWidgetName, std::string aIdentifier)
 Obtains a Widget from Homescreen Publishing Api.

Constructor & Destructor Documentation

IMPORT_C Hs::HsWidgetPublisher::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();
 }
Parameters:
aDataObserver Callback interface for handling actions.
Exceptions:
HsPException 
IMPORT_C Hs::HsWidgetPublisher::~HsWidgetPublisher (   ) 
 

Destructor of the HsWidgetPublisher. 

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

Member Function Documentation

IMPORT_C HsWidget& Hs::HsWidgetPublisher::createHsWidget ( std::string  aTemplateName,
std::string  aWidgetName,
std::string  aIdentifier
) 
 

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" );
Parameters:
aTemplateName Name of the Template.
aWidgetName Name of the Widget
aIdentifier Unique identification of the content.
Returns:
A widget is returned. If no such widget existed a newly created one.
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.
IMPORT_C HsWidget& Hs::HsWidgetPublisher::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" );
Parameters:
aTemplateName Name of the Template.
aWidgetName Name of the Widget
aIdentifier Unique identification of the content.
Returns:
Error code.
Exceptions:
HsException 
IMPORT_C void Hs::HsWidgetPublisher::publishHsWidget ( HsWidget &  aWidget  ) 
 

Method publishes the provided widget.

Widget needs to be published in order for the content to be seen by the HS.

 HsWidgetPublisher* hsPublisher = new HsWidgetPublisher( dataObserver );
 HsWidget& widget =  hsPublisher->createHsWidget( 
     "templateName", "widgetName", "uniqueIdentifier" );
 hsPublisher->publishHsWidget( widget );
Parameters:
aWidget Reference to a widget object.
Exceptions:
HsException 
IMPORT_C void Hs::HsWidgetPublisher::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" );
Parameters:
aTemplateName Name of the Template.
aWidgetName Name of the Widget
aIdentifier Unique identification of the content.
Exceptions:
HsException 
The documentation for this class was generated from the following file:
Copyright © Nokia Corporation 2001-2007
Back to top