|
Nokia N97 SDK Example Applications Guide |
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 |