Figure 5: The procedure for creating a home screen widget.
This API specification document uses HsWidget example
application to illustrate features and functionality of the Home Screen Publishing
API. The example application is published in the N97 SDK and it's default
location is the C:\S60\devices\<SDK_version>\S60CppExamples\HSPWidget folder.
To enable the home screen support in your application with the Home Screen Publishing API, follow the steps below:
To use hswidgetpublisher.dll, include following lines in the .mmp file:
LIBRARY hswidgetpublisher.lib //Home Screen Publishing API LIBRARY libstdcpp.lib //std library LIBRARY libc.lib //std library LIBRARY charconv.lib //string conversion
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 Home Screen Publishing API, include following lines to your source code:
#include <hswidgetpublisher.h> #include <hswidget.h> #include <hsexception.h> #include <hsdataobserver.h>
Home Screen 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 //...
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:
std::string CHsWidgetExample::ToStringL(const TDesC& aText)
{
HBufC8* text = HBufC8::NewLC( 4 * aText.Length() + 1 /*for ending zero*/ );
TPtr8 dest( text->Des() );
CnvUtfConverter::ConvertFromUnicodeToUtf8( dest, aText );
std::string ret((const char*)dest.PtrZ());
CleanupStack::PopAndDestroy(text); // delete text
return ret;
}
The example application's CHsWidgetExample class definition is as follows:
class CHsWidgetExample :
public CBase,
public Hs::IHsDataObserver
To implement the interface's data observer (IHsDataObserver),
create the widget publisher (HsWidgetPublisher), and handle exeptions and
memory allocation, do as follows:Implement the interface's data observer.
void CHsWidgetExample::handleEvent( std::string aWidgetName,
Hs::IHsDataObserver::EEvent aEvent)
{
}
void CHsWidgetExample::handleItemEvent( std::string aWidgetName,
std::string aWidgetItemName,
Hs::IHsDataObserver::EItemEvent aEvent)
{
}
Create the widget publisher.
void CHsWidgetExample::ConstructL()
{
try
{
iHsWidgetPublisher = new Hs::HsWidgetPublisher( this );
}
...
}Handle exceptions. The Home Screen Publishing API is a C++ component and it doesn't use Symbian Leave system. 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 erros. Moreover, the Home Screen 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 HsPApi
User::Leave( e.getReason() );
}
catch( ... )
{
//catch error from other libraries
User::Leave( KErrGeneral );
}
...
Take care of the memory allocation handling because Symbian new operator
returns a NULL pointer in case of failed memory allocation.
...
if( iHsWidgetPublisher )
{
// memory was allocated, use iHsWidgetPublisher
}
else
{
// memory was not allocated
)
...
Create a widget from a widget template with the createHsWidget method.
... iHsWidgetPublisher->createHsWidget( "onerow", "[Ex] HS Widget", "0xA0007E04" ); ...
The widget name ("HSWidget" in this example) must be unique.
Figure 5: The procedure for creating a home screen widget.
At the registration the API also stores the UID3 of the publisher application and uses it later if the publisher application must be started (e.g. if the user interacts with the widget but the publisher application is not running, so it cannot receive events)
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 home screen and the widget will display current widget
values. Because items were not added to widget the content doesn't contain
any information.
Figure 6: A widget without any information in the home screen.
In the example application a widget is created after the mobile device
user selects the Create widget operation.
While adding new items to the widget you must take care about widget's
predefined structure. Items can be added in any order to the widget. Example
widget's type is "onerow" and it contains image and text items.
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.mif 16388 16389)" ); widget.setItem( text, "First text: good morning" ); ...
For more information, see publishing images
In the example application the new items are added to the widget after
the mobile device user has selected the Change widget values operation.
Publishing the widget may occur in the event handling process and it keeps the home screen data up to date. All items of the widget are published in the publishing process.
...
iHsWidgetPublisher->publishHsWidget(
iHsWidgetPublisher->getHsWidget( "onerow", "[Ex] HS Widget", "0xA0007E04" );
...
Figure 7: The procedure for publishing the widget.
After publishing the widget the added items are displayed in the home screen. The widget contains an image and a string.
Figure 8: Published widget in the home screen.
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.
Once the widget items have been added 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" ); ...
To update the widget's data in the home screen publish the widget. The picture below shows the updated widget which contains an updated image and string (Second text: Good afternoon).
Figure 9: Updated data in the widget
In the example application the data is updated in the widget after the
mobile device user has selected the Change widget values operation.
To observe widget and widget item events you must implement data observer.
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
home screen's point of view.
To perform the event handling, see Publishing the widget.
Widget item events are the following:
enum EItemEvent
{
EUnknownItemEvent = 0,
ESelect = 1
};
EItemEvent event is invoked when the mobile device user points a widget's item in the home screen.
Figure 10: The procedure for handling the widget item.
Note the following issues regarding the widget item (image or text)
To remove the widget, perform the removeHsWidget method. Removing the widget deletes all its data from the Home Screen Publishing API. The widget is also removed from the mobile device's "Add content" list.
... iHsWidgetPublisher->removeHsWidget( "onerow", "[Ex] HS Widget", "0xA0007E04" ); ...
Figure 11: The procedure for removing the widget.
If the iHsWidgetPublisher object is destroyed without removing the widget with the removeHsWidget method, the widget will remain registered with the API and the user can add it to the home screen (if it's not already added).
Potential errors encountered while working with the Home Screen Publishing API are indicated with the help of exceptions. HsException object is thrown every time a faulty situation occurs. For more information about exception handling in Symbian C++ applications, see Interleaving Symbian and Standard C++ Code (in the Open C and Open C++ section of the S60 5th Edition C++ Developer's Library).
When using the Home Screen Publishing API, the memory overhead is dependent on the number of instantiated classes.
The Home Screen Publishing API has no extensions.
The Home Screen Publishing API has no limitations.
