Nokia N97 SDK
Example Applications Guide

Homescreen Publishing API example

1. Homescreen Publishing API example
1.1 Homescreen Publishing API
2. Prerequisites
2.1 Including libraries
2.2 Including header files
2.3 Capabilities
3. Use cases
3.1 Creating the homescreen publisher and data observer
3.2 Creating a widget
3.3 Adding items to the widget
3.4 Publishing the widget
3.5 Updating the data in the widget
3.6 Observing widget and widget item events and executing necessary actions
4. Architecture
4.1 Class CHsWidgetExample (HsWidgetExample.cpp, HsWidgetExample.h)
4.2 Class CHsSMWidgetExample (HsSMWidgetExample.cpp, HsSMWidgetExample.h)
4.3 Other classes & utilities


1. Homescreen Publishing API example

HsWidget is a Symbian OS based example application that publishes its content to the Homescreen application by using the Homescreen Publishing API.

1.1 Homescreen Publishing API

Homescreen Publishing API is a C++ based framework that allows C++ and Symbian based applications to publish their content in the homescreen. All methods of the interface use standard C++ data types.


2. Prerequisites

2.1 Including libraries

To use the hswidgetpublisher.dll, include following lines in the .mmp file:

 LIBRARY    hswidgetpublisher.lib //Homescreen Publishing API
 LIBRARY    libstdcpp.lib         //standard library
 LIBRARY    libc.lib              //standard library
 LIBRARY    charconv.lib          //string conversion

2.2 Including header files

To make standard C++ headers available by include paths, include the following lines in the .mmp file:

 SYSTEMINCLUDE \epoc32\include\stdapis
 SYSTEMINCLUDE \epoc32\include\stdapis\stlport
 OPTION CW -wchar_t on
 MACRO  _WCHAR_T_DECLARED

To use Homescreen Publishing API, include following lines to your source code:

 #include <hswidgetpublisher.h>
 #include <hswidget.h>
 #include <hsexception.h>
 #include <hsdataobserver.h>

Homescreen Publishing API uses standard C++ string data in the UTF-8 format, so add the following entry to the .rls file:

 // .rls file
 //...
 CHARACTER_SET UTF8
 //...

On the subject of the string resource files, please also note that the strings referenced in these texts, such as "onerow", "[Ex] HS Widget" and "0xA0007E04" are in fact defined in the resource files and read from there. They are only hardcoded in these code snippets for clarity.

To ensure the use of standard C++ strings, add the following lines:

 #include <string>
 #include <utf.h>

To convert UNICODE to UTF-8 std::string data, do according to the following example code:

  string toString(const TDesC& aText)
     {
     HBufC8* text = HBufC8::NewL( 4 * aText.Length() + 1 /*for ending zero*/ );
     TPtr8 dest( text->Des() );
     CnvUtfConverter::ConvertFromUnicodeToUtf8( dest, aText );    
     string ret((const char*)dest.PtrZ());
     delete text;
     return ret;
     }

2.3 Capabilities

No capabilities are required.


3. Use cases

3.1 Creating the homescreen publisher and data observer

3.1.1 Data observer

To create HsWidgetPublisher, implement interface’s IHsDataObserver.

 void CHsWidgetExample::handleEvent( std::string aWidgetName, 
   Hs::IHsDataObserver::EEvent aEvent)    
   {
   }
 void CHsWidgetExample::handleItemEvent( std::string aWidgetName,
   std::string aWidgetItemName,
   Hs::IHsDataObserver::EItemEvent aEvent)
   {
   }

3.1.2 Homescreen Publisher

Take care of 3.1.3 Exception handling and 3.1.4 Memory allocation handling.

 void CHsWidgetExample::ConstructL()
    {
    try
        {
        iHsWidgetPublisher = new Hs::HsWidgetPublisher( this );
        }
    ...
    }

3.1.3 Exception handling

The Homescreen Publishing API is a C++ component and it doesn't use Symbian Leave mechanism. Instead, it uses the C++ exception (HsException that is a std::exception derivation) mechanism. The HsException object contains information about exception reason and is compatible with Symbian errors. Moreover, the Homescreen Publishing API uses standard libraries so other exceptions may also be thrown as an error handling result.

 ... 
 try
     {
     // HSP method call   
     }
 catch( Hs::HsException& e)
     {
     //catch error from Homescreen Publishing API
     User::Leave( e.getReason() );
     }
 catch( ... )
     {
     //catch error from other libraries
     User::Leave( KErrGeneral );
     }
 ...

3.1.4 Memory allocation handling

Take care of the memory allocation handling because Symbian new operator returns a NULL pointer in case of failed memory allocation.

 ...
 if( iHsWidgetPublisher )
     {
     // memory allocated properly, so use iHsWidgetPublisher          
     }
 else
     {
     // memory not allocated
     )
 ... 

3.2 Creating a widget

hsp_widget_register_widget.bmp

Creating a homescreen widget.

 ...    
 iHsWidgetPublisher->createHsWidget( "onerow", "[Ex] HS Widget", "0xA0007E04" );
 ...

hsp_widget_registry.bmp

The procedure for creating a homescreen widget.

Once your application has created a widget it is available in the Add Content list of the mobile device. Now the mobile device user can add the widget to the homescreen and the widget will display current widget values. Because items were not added to widget the content doesn't contain any information.

hsp_widget_empty_value.bmp

A widget without any information in the homescreen.

3.3 Adding items to the widget

While adding new items to the widget the you must take care of widget's predefined structure. Example widget's type is "onerow" and it contains image and text items. The sequence of adding values does not matter.

 const char* image = "image1";
 const char* text = "text1";

 ...
 HsWidget& widget = iHsWidgetPublisher->getHsWidget( "onerow", "[Ex] HS Widget", "0xA0007E04" );
 widget.setItem( image, "mif(c:\\resource\\apps\\HSPWidget_0xA0007E04.mif 16388 16389)" );
 widget.setItem( text, "First text: good morning" );
 ...
hsp_widget_change_values.bmp

Adding items to the widget.

3.4 Publishing the widget

Publishing the widget may occur in the event handling process and it keeps the homescreen data up to date. All items of the widget are published in the publishing process.

 ...
 iHsWidgetPublisher->publishHsWidget( 
    iHsWidgetPublisher->getHsWidget( "onerow", "[Ex] HS Widget", "0xA0007E04" ) );
 ...

hsp_widget_event_resume.bmp

The procedure for publishing the widget.

Items added to widget in the 3.3 Adding items to the widget are displayed in the homescreen.

Widget contains an image and a string.

hsp_widget_first_value.bmp

Published widget in the homescreen.

Note: After rebooting the mobile device the widget is not on the home screen nor on the content list. To get the widget up and running again the same operations as on the first time must be performed.

3.5 Updating the data in the widget

Once the widget items have been added to widget in 3.3 Adding items to the widget you can update them with the same methods.

 ...
 HsWidget& widget = iHsWidgetPublisher->getHsWidget( "onerow", "[Ex] HS Widget", "0xA0007E04" );
 widget.setItem( image, "c:\\data\\Images\\Pictures\\Sunny.JPG" );
 widget.setItem( text, "Second text: Good afternoon" );
 ...

hsp_widget_change_values.bmp

Updating data in the widget.

To update the widget's data in the homescreen publish the widget as described in 3.4 Publishing the widget. The picture below shows the updated widget which contains an updated image and string (Second text: Good afternoon).

hsp_widget_second_value.bmp

Updated data in the widget

3.6 Observing widget and widget item events and executing necessary actions

To observe widget and widget item events, you must implement the data observer IHsDataObserver as described in 3.1.1 Data observer.

3.6.1 IHsDataObserver::handleEvent(...)

Widget events are the following:

 enum EEvent
     {
      EUnknown    = 0,
      EActivate   = 1,
      EDeactivate = 2,
      ESuspend    = 3,
      EResume     = 4     
      };

Each EEvent value represents the widget status from the homescreen's point of view. To perform the event handling, see 3.4 Publishing the widget.

3.6.2 IHSPDataObserver::handleItemEvent(...)

Widget item events are the following:

 enum EItemEvent
     {
     EUnknownItemAction = 0,
     ESelection         = 1
     };

EItemEvent event is invoked when the mobile device user points a widget's item in the homescreen.

hsp_widget_event_select.bmp

The procedure for handling the widget item.

3.7 Removing the widget

To remove the widget, perform the removeHsWidget method. Removing the widget deletes all its data from the Homescreen Publishing API. The widget is also removed from the mobile device's "Add content" list.

 ...    
 iHsWidgetPublisher->removeHsWidget( "onerow", "[Ex] HS Widget", "0xA0007E04" );
 ...

hsp_widget_remove.bmp

The procedure for removing the widget.


4. Architecture

The HsWidget example is based on a standard S60 GUI application that contains the following additions:

4.1 Class CHsWidgetExample (HsWidgetExample.cpp, HsWidgetExample.h)

It implements an abstract class IHsDataObserver and contains Homescreen Publishing API interface. CHsWidgetExample class is a representation of simple widget ("onerow" template) but it contains complex widget functionality described in the section 3. Use cases.

hsp_widget_class_diagram.bmp

Class diagram of HsWidget application.

4.2 Class CHsSMWidgetExample (HsSMWidgetExample.cpp, HsSMWidgetExample.h)

This class is similar with CHsWidgetExample in its implementation of the IHsDataObserver and of the Home Screen Publishing API. This widget is however different than the one implemented in CHsWidgetExample through its use of the "wideimage" template, used to display information drawn at runtime on an bitmap graphic context (offscreen bitmap).

4.3 Other classes & utilities

For the purpose of this example the following classes should be seen as black boxes that are meant only to collect and help deliver some live content for the CHsSMWidgetExample widget to render and display.

This class implements an active object that uses the ETel 3rd Party API (CTelephony) to monitor the network signal level. This info is then passed to the CHsSMWidgetExample class which will render it on the home screen with the help of the Home Screen Publishing API.

This class is a mixin interface implemented by the CHsSMWidgetExample which will receive through it network signal change notifications from CGMSSignalMonitor.

Macros used to collect debug information at runtime.


© Nokia 2009

Back to top