|
Nokia N97 SDK Example Applications Guide |
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
LIBRARY hswidgetpublisher.lib //Homescreen Publishing API LIBRARY libstdcpp.lib //standard library LIBRARY libc.lib //standard library LIBRARY charconv.lib //string conversion
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; }
void CHsWidgetExample::handleEvent( std::string aWidgetName, Hs::IHsDataObserver::EEvent aEvent) { } void CHsWidgetExample::handleItemEvent( std::string aWidgetName, std::string aWidgetItemName, Hs::IHsDataObserver::EItemEvent aEvent) { }
void CHsWidgetExample::ConstructL() { try { iHsWidgetPublisher = new Hs::HsWidgetPublisher( this ); } ... }
... 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 ); } ...
... if( iHsWidgetPublisher ) { // memory allocated properly, so use iHsWidgetPublisher } else { // memory not allocated ) ...
Creating a homescreen widget.
... iHsWidgetPublisher->createHsWidget( "onerow", "[Ex] HS Widget", "0xA0007E04" ); ...
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.
A widget without any information in the homescreen.
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" ); ...
Adding items to the widget.
...
iHsWidgetPublisher->publishHsWidget(
iHsWidgetPublisher->getHsWidget( "onerow", "[Ex] HS Widget", "0xA0007E04" ) );
...
The procedure for publishing the widget.
Widget contains an image and a string.
Published widget in the homescreen.
... 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" ); ...
Updating data in the widget.
Updated data in the widget
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.
enum EItemEvent
{
EUnknownItemAction = 0,
ESelection = 1
};
EItemEvent event is invoked when the mobile device user points a widget's item in the homescreen.
The procedure for handling the widget item.
... iHsWidgetPublisher->removeHsWidget( "onerow", "[Ex] HS Widget", "0xA0007E04" ); ...
The procedure for removing the widget.
Class diagram of HsWidget application.
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 |