Nokia N97 SDK Example Applications Guide |
1. An example application HsWidget.
1.1 Homescreen Publishing Api - C++ SDK API.
2. Prerequisites
2.1 Include Library.
2.2 Header files
2.3 Capabilities
3. Use cases
3.1 Creation of the Homescreen Publisher and observer.
3.2 Creation of widget.
3.3 Add items to widget.
3.4 Publish the widget.
3.5 Update the data in the widget.
3.6 Observe widget's and items' events.
4. Architecture
4.1 Class diagram.
LIBRARY hswidgetpublisher.lib //homescreen publishing api LIBRARY libstdcpp.lib //std library LIBRARY libc.lib //std library LIBRARY charconv.lib //string conversion
OS_LAYER_LIBC_SYSTEMINCLUDE OS_LAYER_STDCPP_SYSTEMINCLUDE
HsPApi necessary headers files:
#include <hswidgetpublisher.h> #include <hswidget.h> #include <hsexception.h> #include <hsdataobserver.h>
HsPApi uses C++ standard string data in format UTF-8. The .rls file needs entry like below:
// .rls file //... CHARACTER_SET UTF8 //...
To ensure use of C++ standard string client needs to include:
#include <string> #include <utf.h>
Example code that converts UNICODE to UTF-8 std::string data:
string toString(const TDesC& aText) { HBufC8* text = HBufC8::NewL( aText.Length() + 4 /*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 HsPApi User::Leave( e.getReason() ); } catch( ... ) { //catch error from other libraries User::Leave( KErrGeneral ); } ...
... if( iHsWidgetPublisher ) { // memory allocate properly, use iHsWidgetPublisher } else { // memory not allocated ) ...
... iHsWidgetPublisher->createHsWidget( "onerow", "HSWidget", "0xA0007E04" ); ...
Once widget is created, it is available in list shown to the HS user. Widget can be added as content to HS and it will display current values. Because items were not added to widget, content doesn't contain valuable information.
const char* image = "image1"; const char* text = "text1"; ... iHsWidgetPublisher->getHsWidget( "onerow", "HSWidget", "0xA0007E04" ). setItem( image, "mif(c:\\resource\\apps\\HSPWidget.mif 16388 16389)" ); iHsWidgetPublisher->getHsWidget( "onerow", "HSWidget", "0xA0007E04" ). setItem( text, "First text: good morning" ); ...
... iHsWidgetPublisher->publishHsWidget( iHsWidgetPublisher->getHsWidget( "onerow", "HSWidget", "0xA0007E04" ) ); ...
Items added to widget 3.3 Add items to widget. are displayed in HS. Widget contains image and localized string.
... iHsWidgetPublisher->getHsWidget( "onerow", "HSWidget", "0xA0007E04" ). setItem( image, "c:\\data\\Images\\Pictures\\Sunny.JPG ); iHsWidgetPublisher->getHsWidget( "onerow", "HSWidget", "0xA0007E04" ). setItem( text, "Second text: hyvää päivää" ); ...
To update widget's data in HS, entire widget should be published and it happens during event handling 3.4 Publish the widget.. The result with visible widget below.
enum EEvent
{
EUnknown = 0,
EActivate = 1,
EDeactivate = 2,
ESuspend = 3,
EResume = 4
};
enum EItemEvent
{
EUnknownItemAction = 0,
ESelection = 1
};
Select is evoked per each widget's item as result of user's pointer on content area in HS.
... iHsWidgetPublisher->removeHsWidget( "onerow", "HsWidget", "0xA0007E04" ); ...
© Nokia 2009 |