Nokia N97 SDK
Example Applications Guide

CHsSMWidgetExample Class Reference

#include <HsSMWidgetExample.h>

Inheritance diagram for CHsSMWidgetExample:

MSignalObserver List of all members.

Detailed Description

CHsSMWidgetExample definition This class implements a wideimage template based on the home screen widget. It instantiates an active object derived network signal monitor (CGMSSignalMonitor) and receives callbacks from it when the network signal value changes through the MSignalObserver interface. When such callbacks are received the data is stored in an array which is then rendered as a graph on a bitmap. The bitmap will eventually be passed to the Home Screen Publishing API instance which will render it on the reserved space on the home screen application.

Definition at line 57 of file HsSMWidgetExample.h.


Public Member Functions

virtual void  handleEvent (std::string aWidgetName, IHsDataObserver::EEvent aEvent)
virtual void  handleItemEvent (std::string aWidgetName, std::string aWidgetItemName, IHsDataObserver::EItemEvent aEvent)
virtual  ~CHsSMWidgetExample ()
void  RegisterWidgetL ()
void  PublishWidgetL ()
void  ChangeWidgetValuesL ()
void  RemoveWidgetL ()
TBool  IsWidgetRegisteredL ()
void  SignalLevelChangedL (TInt aSignal, TInt aBars)

Static Public Member Functions

static CHsSMWidgetExample *  NewL ()
static CHsSMWidgetExample *  NewLC ()

Private Member Functions

void  RunAnimationTestL ()
  CHsSMWidgetExample ()
void  ConstructL ()
std::string  ToStringL (const TDesC &aText)

Private Attributes

Hs::HsWidgetPublisher *  iHsWidgetPublisher
std::string  templateType
std::string  widgetName
std::string  widgetId
CFbsBitmap *  iWideFrame
CFbsBitmapDevice *  iWideFrameDevice
CFbsBitGc *  iWideFrameContext
CGMSSignalMonitor *  iMonitor
TInt  iMeasurements [KNumberOfMeasurements]
TBool  iCanPublish
TBool  iNeedUpdate


Constructor & Destructor Documentation

CHsSMWidgetExample::~CHsSMWidgetExample (   )  [virtual]
 

C++ destructor.

Definition at line 57 of file HsSMWidgetExample.cpp.

References iHsWidgetPublisher, iMonitor, iWideFrame, iWideFrameContext, and iWideFrameDevice.

00058         {
00059         delete iMonitor;
00060         
00061         delete iWideFrameContext;
00062         delete iWideFrameDevice;
00063         delete iWideFrame;
00064         
00065         delete iHsWidgetPublisher;
00066         }

CHsSMWidgetExample::CHsSMWidgetExample (   )  [private]
 

C++ constructor, for performing the 1st stage construction

Definition at line 45 of file HsSMWidgetExample.cpp.

References iMeasurements.

Referenced by NewLC().

00046         {
00047         //initialize measurements array with random values
00048         for (TInt i=0; i<KNumberOfMeasurements; i++)
00049                 iMeasurements[i]= Math::Random()%8;
00050         }


Member Function Documentation

virtual void CHsSMWidgetExample::handleEvent (  std::string  aWidgetName,
IHsDataObserver::EEvent  aEvent
)  [virtual]
 

Intended to handle an event that occured on a widget. The template is being published when the received event is EActivate or EResume

Parameters:
aWidgetName  Name of the widget that event is envoked for.
aEvent  Event type that has taken place.

virtual void CHsSMWidgetExample::handleItemEvent (  std::string  aWidgetName,
std::string  aWidgetItemName,
IHsDataObserver::EItemEvent  aEvent
)  [virtual]
 

Intended to handle an event that occured on a widget's item. Run an animation test when the user taps the signal monitor widget

Parameters:
aWidgetName  Name of the widget that event is envoked for.
aWidgetItemName  Name of the item that event is envoked for.
aEvent  Event type that has taken place

CHsSMWidgetExample * CHsSMWidgetExample::NewL (   )  [static]
 

Two-phased constructor.

Definition at line 86 of file HsSMWidgetExample.cpp.

References NewLC().

Referenced by CHsWidgetAppUi::ConstructL(), and CHsWidgetAppUi::HandleCommandL().

00087         {
00088         CHsSMWidgetExample* self=CHsSMWidgetExample::NewLC();
00089         CleanupStack::Pop(); // self;
00090         return self;
00091         }

CHsSMWidgetExample * CHsSMWidgetExample::NewLC (   )  [static]
 

Two-phased constructor. Leaves constructed object on the cleanup stack

Definition at line 73 of file HsSMWidgetExample.cpp.

References CHsSMWidgetExample().

Referenced by NewL().

00074         {
00075         CHsSMWidgetExample* self = new (ELeave)CHsSMWidgetExample();
00076         CleanupStack::PushL(self);
00077         self->ConstructL();
00078         return self;
00079         }

void CHsSMWidgetExample::RegisterWidgetL (   ) 
 

Once registered the widget will become available to the user for adding it to the home screen. If the widgetId is already registered the iHsWidgetPublisher will now point to it. Also, note that the Homescreen Publishing API will record this application's UID3/SID as the publiser of this widget and based on this information the application will be started in the background if at any given time an event is due to be sent to it but the application is found not to be running.

Definition at line 159 of file HsSMWidgetExample.cpp.

References iHsWidgetPublisher, templateType, widgetId, and widgetName.

Referenced by CHsWidgetAppUi::ConstructL(), and CHsWidgetAppUi::HandleCommandL().

00160         {
00161         __LOGSTR_TOFILE("Enter CHsSMWidgetExample::RegisterWidgetL");
00162         try
00163                 {
00164                 iHsWidgetPublisher->createHsWidget( templateType,
00165                                                         widgetName, widgetId );
00166                 }
00167         catch( Hs::HsException& e)
00168                 {
00169                 //catch error from Homescreen Publishing API
00170                 __LOGSTR_TOFILE1("[-] HSPAPI exception : %d", e.getReason());
00171                 User::Leave( e.getReason() );
00172                 }
00173         catch( ... )
00174                 {
00175                 //catch error from other libraries
00176                 __LOGSTR_TOFILE("[-] Generic exception");
00177                 User::Leave( KErrGeneral );
00178                 }
00179         __LOGSTR_TOFILE("Exit CHsSMWidgetExample::RegisterWidgetL");
00180         }

void CHsSMWidgetExample::PublishWidgetL (   ) 
 

Template is published by the Home Screen Publishing API. If the home screen gets template's data it obtains the actual information.

Definition at line 188 of file HsSMWidgetExample.cpp.

References iHsWidgetPublisher, templateType, widgetId, and widgetName.

00189         {
00190         __LOGSTR_TOFILE("Enter CHsSMWidgetExample::PublishWidgetL");
00191         try
00192                 {       
00193                 iHsWidgetPublisher->publishHsWidget( 
00194                         iHsWidgetPublisher->getHsWidget( templateType,
00195                                                 widgetName, widgetId ) );
00196                 }
00197         catch( Hs::HsException& e)
00198                 {
00199                 //catch error from Homescreen Publishing API
00200                 __LOGSTR_TOFILE1("[-] HSPAPI exception : %d", e.getReason());
00201                 User::Leave( e.getReason() );
00202                 }
00203         catch( ... )
00204                 {
00205                 //catch error from other libraries
00206                 __LOGSTR_TOFILE("[-] Generic exception");
00207                 User::Leave( KErrGeneral );
00208                 }
00209         __LOGSTR_TOFILE("Exit CHsSMWidgetExample::PublishWidgetL");
00210         }

void CHsSMWidgetExample::ChangeWidgetValuesL (   ) 
 

Change items' values. They will only be commited (and updated on the home screen) once you call CHsSMWidgetExample::PublishWidgetL()

Definition at line 218 of file HsSMWidgetExample.cpp.

References iHsWidgetPublisher, iWideFrame, templateType, widgetId, and widgetName.

00219         {
00220         __LOGSTR_TOFILE("Enter CHsSMWidgetExample::ChangeWidgetValuesL");
00221         try
00222                 {
00223                 // passing the bitmap handle to the Homescreen Publishing API   
00224                 iHsWidgetPublisher->getHsWidget( templateType, widgetName,
00225                         widgetId ).setItem(wideimageitem, iWideFrame->Handle());
00226                 }
00227         catch( Hs::HsException& e)
00228                 {
00229                 //catch error from Homescreen Publishing API
00230                 __LOGSTR_TOFILE1("HSPAPI exception : %d", e.getReason());
00231                 User::Leave( e.getReason() );
00232                 }
00233         catch( ... )
00234                 {
00235                 //catch error from other libraries
00236                 __LOGSTR_TOFILE("Generic exception");
00237                 User::Leave( KErrGeneral );
00238                 }
00239         __LOGSTR_TOFILE("Exit CHsSMWidgetExample::ChangeWidgetValuesL");
00240         }

void CHsSMWidgetExample::RemoveWidgetL (   ) 
 

Remove widget's template from the Home Screen Publishing API. If the widget is currently visible on the home screen it will be removed. Once removed the widget is now not available for selection on home screen and it doesn't report events

Definition at line 249 of file HsSMWidgetExample.cpp.

References iHsWidgetPublisher, templateType, widgetId, and widgetName.

Referenced by CHsWidgetAppUi::ConstructL(), and CHsWidgetAppUi::~CHsWidgetAppUi().

00250         {
00251         __LOGSTR_TOFILE("Enter CHsSMWidgetExample::RemoveWidgetL");
00252         try
00253                 {       
00254                 iHsWidgetPublisher->removeHsWidget( templateType,
00255                                                         widgetName, widgetId);
00256                 }
00257         catch( Hs::HsException& e)
00258                 {
00259                 //catch error from Homescreen Publishing API
00260                 __LOGSTR_TOFILE1("HSPAPI exception : %d", e.getReason());
00261                 User::Leave( e.getReason() );
00262                 }
00263         catch( ... )
00264                 {
00265                 //catch error from other libraries
00266                 __LOGSTR_TOFILE("Generic exception");
00267                 User::Leave( KErrGeneral );
00268                 }
00269         __LOGSTR_TOFILE("Exit CHsSMWidgetExample::RemoveWidgetL");
00270         }

TBool CHsSMWidgetExample::IsWidgetRegisteredL (   ) 
 

Check whether the widget is already registered or not.

Definition at line 315 of file HsSMWidgetExample.cpp.

References iHsWidgetPublisher, templateType, widgetId, and widgetName.

00316         {
00317         __LOGSTR_TOFILE("Enter CHsSMWidgetExample::IsWidgetRegisteredL");
00318         
00319         TBool result = ETrue;
00320         try
00321                 {       
00322                 iHsWidgetPublisher->getHsWidget( templateType,
00323                                                         widgetName, widgetId);
00324                 }
00325         catch( Hs::HsException& e)
00326                 {
00327                 __LOGSTR_TOFILE1("[-] HSPAPI exception : %d", e.getReason());
00328                 if(e.getReason()==KErrNotFound)
00329                         result = EFalse;
00330                 }
00331         catch( ... )
00332                 {
00333                 //catch error from other libraries
00334                 __LOGSTR_TOFILE("[-] Generic exception");
00335                 User::Leave( KErrGeneral );
00336                 }
00337         __LOGSTR_TOFILE("Exit CHsSMWidgetExample::IsWidgetRegisteredL");
00338         
00339         return result;
00340         }

void CHsSMWidgetExample::RunAnimationTestL (   )  [private]
 

This method is intended to give a hint of the speed with which new images can be published on the widget in order to create for example a marquee animation. Please note that this method will keep application's thread busy and while in this loop the application cannot receive other events from the home screen

Definition at line 525 of file HsSMWidgetExample.cpp.

References SignalLevelChangedL().

00526         {
00527         __LOGSTR_TOFILE("Enter CHsSMWidgetExample::RunAnimationTestL");
00528         for(TInt i=0; i<100; i++)
00529                 {
00530                 SignalLevelChangedL(0,i%8);
00531                 }
00532         __LOGSTR_TOFILE("Exit CHsSMWidgetExample::RunAnimationTestL");
00533         }

void CHsSMWidgetExample::ConstructL (   )  [private]
 

EPOC default constructor for performing the 2nd stage construction Creates an instance of the Home Screen Publishing API's HsWidgetPublisher and loads widget's definition from the resource file

Definition at line 100 of file HsSMWidgetExample.cpp.

References iHsWidgetPublisher, iMonitor, iWideFrame, iWideFrameContext, iWideFrameDevice, CGMSSignalMonitor::NewL(), templateType, ToStringL(), widgetId, and widgetName.

00101         {
00102         __LOGSTR_TOFILE("Enter CHsSMWidgetExample::ConstructL");
00103         
00104         try
00105                 {
00106                 iHsWidgetPublisher = new Hs::HsWidgetPublisher( this );
00107                 }
00108         catch( Hs::HsException& e)
00109                 {
00110                 //catch error from Homescreen Publishing API
00111                 __LOGSTR_TOFILE1("[-] HSPAPI exception : %d", e.getReason());
00112                 User::Leave( e.getReason() );
00113                 }
00114         catch( ... )
00115                 {
00116                 //catch error from other libraries
00117                 __LOGSTR_TOFILE("[-] Generic exception");
00118                 User::Leave( KErrGeneral );
00119                 }
00120         
00121         // instantiate the network signal monitor and assign this object as the
00122         // observer of network signal value changes
00123         iMonitor = CGMSSignalMonitor::NewL(*this);
00124 
00125         // create a buffer bitmap on which a graph will be drawn
00126         iWideFrame = new (ELeave) CFbsBitmap;
00127         User::LeaveIfError( iWideFrame->Create(TSize(312,82),
00128                                 CEikonEnv::Static()->DefaultDisplayMode()));
00129         
00130         // Create a frame buffer graphics context
00131         iWideFrameDevice = CFbsBitmapDevice::NewL(iWideFrame);
00132         User::LeaveIfError(iWideFrameDevice->CreateContext(iWideFrameContext));
00133 
00134         //converitng string from UNICODE to UTF-8 std::string
00135         HBufC* buf1 = StringLoader::LoadLC(R_SM_TEMPLATE_TYPE);
00136         templateType = ToStringL( *buf1 );
00137         CleanupStack::PopAndDestroy(buf1); // delete buf1
00138         buf1 = StringLoader::LoadLC( R_SM_WIDGET_NAME );
00139         widgetName = ToStringL( *buf1 );
00140         CleanupStack::PopAndDestroy(buf1); // delete buf1
00141         buf1 = StringLoader::LoadLC( R_SM_WIDGET_ID );
00142         widgetId = ToStringL( *buf1 );
00143         CleanupStack::PopAndDestroy(buf1); // delete buf1
00144         
00145         __LOGSTR_TOFILE("Exit CHsSMWidgetExample::ConstructL");
00146         }

std::string CHsSMWidgetExample::ToStringL (  const TDesC &  aText  )  [private]
 

Conversion method.

Parameters:
aText  string to convert
Returns:
converted string

Definition at line 413 of file HsSMWidgetExample.cpp.

Referenced by ConstructL().

00414     {
00415     HBufC8* text = HBufC8::NewLC( aText.Length() + 4 /*for ending zero*/ );
00416     TPtr8 dest( text->Des() );
00417     CnvUtfConverter::ConvertFromUnicodeToUtf8( dest, aText );    
00418     std::string ret((const char*)dest.PtrZ());
00419     CleanupStack::PopAndDestroy(text); // delete text
00420     return ret;
00421     }


Member Data Documentation

Hs::HsWidgetPublisher* CHsSMWidgetExample::iHsWidgetPublisher [private]
 

Homescreen Publisher API's main class

Definition at line 191 of file HsSMWidgetExample.h.

Referenced by ChangeWidgetValuesL(), ConstructL(), IsWidgetRegisteredL(), PublishWidgetL(), RegisterWidgetL(), RemoveWidgetL(), and ~CHsSMWidgetExample().

std::string CHsSMWidgetExample::templateType [private]
 

String indicating which template will be used for this widget.

Definition at line 196 of file HsSMWidgetExample.h.

Referenced by ChangeWidgetValuesL(), ConstructL(), IsWidgetRegisteredL(), PublishWidgetL(), RegisterWidgetL(), and RemoveWidgetL().

std::string CHsSMWidgetExample::widgetName [private]
 

Widget's name. Will be shown to the user when he/she selects a widget to be added to the home screen.

Definition at line 202 of file HsSMWidgetExample.h.

Referenced by ChangeWidgetValuesL(), ConstructL(), IsWidgetRegisteredL(), PublishWidgetL(), RegisterWidgetL(), and RemoveWidgetL().

std::string CHsSMWidgetExample::widgetId [private]
 

Unique UID identifiying the widget.

Definition at line 207 of file HsSMWidgetExample.h.

Referenced by ChangeWidgetValuesL(), ConstructL(), IsWidgetRegisteredL(), PublishWidgetL(), RegisterWidgetL(), and RemoveWidgetL().

CFbsBitmap* CHsSMWidgetExample::iWideFrame [private]
 

This bitmap will be used to create a graphic context for drawning the network signal graph. The handle of this bitmap will be passed to the Homescreen application and the bitmap will be rendered on the widget item.

Definition at line 214 of file HsSMWidgetExample.h.

Referenced by ChangeWidgetValuesL(), ConstructL(), and ~CHsSMWidgetExample().

CFbsBitmapDevice* CHsSMWidgetExample::iWideFrameDevice [private]
 

Bitmap device used for creating the CFbsBitGc graphic context on which the graph will be blit

Definition at line 220 of file HsSMWidgetExample.h.

Referenced by ConstructL(), and ~CHsSMWidgetExample().

CFbsBitGc* CHsSMWidgetExample::iWideFrameContext [private]
 

Bitmap based graphic context, allows drawing on the CFbsBitmap.

Definition at line 225 of file HsSMWidgetExample.h.

Referenced by ConstructL(), and ~CHsSMWidgetExample().

CGMSSignalMonitor* CHsSMWidgetExample::iMonitor [private]
 

Asynchronous network signal level monitor. Will send measured data back to this widget for visualization.

Definition at line 231 of file HsSMWidgetExample.h.

Referenced by ConstructL(), and ~CHsSMWidgetExample().

TInt CHsSMWidgetExample::iMeasurements[KNumberOfMeasurements] [private]
 

Array of KNumberOfMeasurements integers that will store the signal measurements that will be visualized on this widget

Definition at line 237 of file HsSMWidgetExample.h.

Referenced by CHsSMWidgetExample(), and SignalLevelChangedL().

TBool CHsSMWidgetExample::iCanPublish [private]
 

If set ETrue it indicates that the widget is currently selected on the home screen and that the home screen is in the foreground, thus the widget data can and should be updated.

Definition at line 244 of file HsSMWidgetExample.h.

TBool CHsSMWidgetExample::iNeedUpdate [private]
 

If set ETrue it signals that widget's data was changed since the last publishing and the widget state did not allow the new data to be publised.

Definition at line 251 of file HsSMWidgetExample.h.


The documentation for this class was generated from the following files:

© Nokia 2009

Back to top