Nokia N97 SDK
Example Applications Guide

HsSMWidgetExample.h

00001 /*
00002  ============================================================================
00003  Name           : HsSMWidgetExample.h
00004  Author   : 
00005  Version         : 1.1
00006  Copyright   : This material, including documentation and any related computer
00007           programs, is protected by copyright controlled by Nokia Corporation.
00008  Description : CHsSMWidgetExample declaration
00009  ============================================================================
00010  */
00011 
00012 #ifndef __HSSMWIDGETEXAMPLE_H__
00013 #define __HSSMWIDGETEXAMPLE_H__
00014 
00015 // INCLUDES
00016 #include <e32std.h>
00017 #include <e32base.h>
00018 #include <string>
00019 #include <hsdataobserver.h>
00020 
00021 #include "msignalobserver.h"
00022 
00023 /**
00024  * A bit of a magic number here. This is the number of graph bars that fit into
00025  * the widget's width.
00026  * See the implementation of SignalLevelChangedL(TInt aSignal, TInt aBars) for
00027  * more info.
00028  */
00029 #define KNumberOfMeasurements 23
00030 
00031 // forward declaration
00032 class CFbsBitmap;
00033 class CFbsBitmapDevice;
00034 class CFbsBitGc;
00035 class CGMSSignalMonitor;
00036 
00037 
00038 // CLASS DECLARATION
00039 
00040 namespace Hs 
00041     {
00042     class HsWidgetPublisher;
00043     }
00044 
00045 
00046 /**
00047  * CHsSMWidgetExample definition
00048  * This class implements a wideimage template based on the home screen widget. It
00049  * instantiates an active object derived network signal monitor
00050  * (CGMSSignalMonitor) and receives callbacks from it when the network signal
00051  * value changes through the MSignalObserver interface. When such callbacks
00052  * are received the data is stored in an array which is then rendered as a
00053  * graph on a bitmap. The bitmap will eventually be passed to the Home Screen
00054  * Publishing API instance which will render it on the reserved space on
00055  * the home screen application. 
00056  */
00057 class CHsSMWidgetExample : 
00058         public CBase,
00059         public Hs::IHsDataObserver,
00060         public MSignalObserver 
00061         {
00062 public:
00063 
00064         /**
00065          * Intended to handle an event that occured on a widget.
00066          * The template is being published when the received event is
00067          * EActivate or EResume
00068          *
00069          * @param aWidgetName Name of the widget that event is envoked for.
00070          * @param aEvent Event type that has taken place.
00071          */
00072         virtual void handleEvent( std::string aWidgetName, 
00073                         IHsDataObserver::EEvent aEvent);
00074         
00075         /**
00076          * Intended to handle an event that occured on a widget's item.
00077          * Run an animation test when the user taps the signal monitor widget
00078          *
00079          * @param aWidgetName Name of the widget that event is envoked for.
00080          * @param aWidgetItemName Name of the item that event is envoked for.
00081          * @param aEvent Event type that has taken place
00082          */    
00083         virtual void handleItemEvent( std::string aWidgetName,
00084                         std::string aWidgetItemName,
00085                         IHsDataObserver::EItemEvent aEvent);
00086             
00087 public:
00088         // Constructors and destructor
00089 
00090         /**
00091          * C++ destructor.
00092          */
00093         virtual ~CHsSMWidgetExample();
00094 
00095         /**
00096          * Two-phased constructor.
00097          */
00098         static CHsSMWidgetExample* NewL();
00099 
00100         /**
00101          * Two-phased constructor. Leaves constructed object on the
00102          * cleanup stack
00103          */
00104         static CHsSMWidgetExample* NewLC();
00105 
00106         /**
00107          * Once registered the widget will become available to the user for
00108          * adding it to the home screen. If the widgetId is already registered
00109          * the iHsWidgetPublisher will now point to it. Also, note that the
00110          * Homescreen Publishing API will record this application's UID3/SID as
00111          * the publiser of this widget and based on this information the
00112          * application will be started in the background if at any given time an
00113          * event is due to be sent to it but the application is found not to be
00114          * running.
00115          */     
00116         void RegisterWidgetL();
00117         
00118         /**
00119          * Template is published by the Home Screen Publishing API.
00120          *  If the home screen gets template's data it obtains the actual information. 
00121          */     
00122         void PublishWidgetL();
00123         
00124         /**
00125          * Change items' values. They will only be commited (and updated on the
00126          * home screen) once you call CHsSMWidgetExample::PublishWidgetL()
00127          */
00128         void ChangeWidgetValuesL();
00129         
00130         /**
00131          * Remove widget's template from the Home Screen Publishing API. If the
00132          * widget is currently visible on the home screen it will be removed.
00133          * Once removed the widget is now not available for selection on
00134          * home screen and it doesn't report events 
00135          */
00136         void RemoveWidgetL();
00137 
00138         /**
00139          * Check whether the widget is already registered or not.
00140          */ 
00141         TBool IsWidgetRegisteredL();
00142         
00143         /*
00144          * Takes in the values measured by the network signal monitor
00145          * (CGMSSignalMonitor) and uses them to draw a graph on a bitmap.
00146          * This bitmap is then passed to the home screen widget to be displayed.
00147          * @param aSignal The current network signal value, see
00148          * TSignalStrengthV1::iSignalStrength
00149          * @param aBars The current network signal value, represented as the
00150          * number of bars in the signal indicator, see TSignalStrengthV1::iBar.
00151          * A negative value is intended to force the rendering of the data
00152          * rather than updating the measured values.
00153          */
00154         void SignalLevelChangedL(TInt aSignal, TInt aBars);
00155 
00156 private:
00157         
00158         /**
00159          * This method is intended to give a hint of the speed with which new
00160          * images can be published on the widget in order to create for example
00161          * a marquee animation.
00162          * Please note that this method will keep application's thread busy and
00163          * while in this loop the application cannot receive other events from
00164          * the home screen
00165          */
00166         void RunAnimationTestL();
00167         
00168         /**
00169          * C++ constructor, for performing the 1st stage construction
00170          */
00171         CHsSMWidgetExample();
00172 
00173         /**
00174          * EPOC default constructor for performing the 2nd stage construction
00175          * Creates an instance of the Home Screen Publishing API's HsWidgetPublisher and
00176          * loads widget's definition from the resource file
00177          */
00178         void ConstructL();
00179         
00180         /**
00181          * Conversion method. 
00182          * @param aText string to convert
00183          * @return converted string
00184          */
00185         std::string ToStringL(const TDesC& aText);
00186         
00187 private:
00188         /**
00189          * Homescreen Publisher API's main class
00190          */
00191         Hs::HsWidgetPublisher* iHsWidgetPublisher;
00192         
00193         /**
00194          * String indicating which template will be used for this widget.
00195          */
00196         std::string templateType;
00197         
00198         /**
00199          * Widget's name. Will be shown to the user when he/she selects a widget
00200          * to be added to the home screen.
00201          */
00202         std::string widgetName;
00203         
00204         /**
00205          * Unique UID identifiying the widget.
00206          */
00207         std::string widgetId;
00208 
00209         /**
00210         * This bitmap will be used to create a graphic context for drawning the
00211         * network signal graph. The handle of this bitmap will be passed to the
00212         * Homescreen application and the bitmap will be rendered on the widget item.
00213         */
00214         CFbsBitmap* iWideFrame;
00215         
00216         /**
00217          * Bitmap device used for creating the CFbsBitGc graphic context on
00218          * which the graph will be blit
00219          */
00220         CFbsBitmapDevice* iWideFrameDevice;
00221         
00222         /**
00223          * Bitmap based graphic context, allows drawing on the CFbsBitmap.
00224          */
00225         CFbsBitGc* iWideFrameContext;
00226 
00227         /**
00228         * Asynchronous network signal level monitor. Will send measured data
00229         * back to this widget for visualization.
00230         */
00231         CGMSSignalMonitor* iMonitor;
00232         
00233         /**
00234         * Array of KNumberOfMeasurements integers that will store the signal
00235         * measurements that will be visualized on this widget
00236         */
00237         TInt iMeasurements[KNumberOfMeasurements];
00238         
00239         /**
00240          * If set ETrue it indicates that the widget is currently selected on
00241          * the home screen and that the home screen is in the foreground, thus
00242          * the widget data can and should be updated.
00243          */
00244         TBool iCanPublish;
00245         
00246         /**
00247          * If set ETrue it signals that widget's data was changed since the
00248          * last publishing and the widget state did not allow the new data to be
00249          * publised.
00250          */
00251         TBool iNeedUpdate;
00252    
00253         };
00254 
00255 #endif

© Nokia 2009

Back to top