1 /* |
|
2 * Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: Defines screensaver plugin interface. |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 #ifndef SCREEN_SAVER_PLUGIN_H |
|
20 #define SCREEN_SAVER_PLUGIN_H |
|
21 |
|
22 // INCLUDES |
|
23 #include <e32base.h> |
|
24 #include <gulicon.h> |
|
25 #include <coecntrl.h> |
|
26 |
|
27 #include <ScreensaverpluginIntDef.hrh> // For TScPluginCaps |
|
28 |
|
29 // CONSTANTS |
|
30 |
|
31 // |
|
32 // Enumerations for screensaver indicators. |
|
33 // |
|
34 enum TScreensaverIndicatorIndex |
|
35 { |
|
36 EScreensaverIndicatorIndexNewMessages, |
|
37 EScreensaverIndicatorIndexNewMissedCalls, |
|
38 EScreensaverIndicatorIndexKeyGuardState, |
|
39 EScreensaverIndicatorIndexProfileName, |
|
40 EScreensaverIndicatorIndexChatMessage, |
|
41 EScreensaverIndicatorIndexEmail, |
|
42 EScreensaverIndicatorIndexVoicemail, |
|
43 EScreensaverIndicatorIndexAmPm |
|
44 }; |
|
45 |
|
46 |
|
47 // Screensaver indicator payload types |
|
48 enum TScreensaverPayloadType |
|
49 { |
|
50 EPayloadTypeUnknown = 0, |
|
51 EPayloadTypeInteger, // Icon and and number, or just icon (integer -1) |
|
52 EPayloadTypeText, // E.g. profile, AM/PM |
|
53 EPayloadTypeIcon // Icon only |
|
54 }; |
|
55 |
|
56 |
|
57 // Enumerations for possible partial mode types. |
|
58 enum TScreensaverPartialModeType |
|
59 { |
|
60 EPartialModeTypeDefault = 0, // Default partial mode (usually same as "most power saving"): |
|
61 EPartialModeTypeFull, // Partial mode with maximum number of colors. |
|
62 EPartialModeTypeReduced, |
|
63 EPartialModeTypeMostPowerSaving // Most power saving partial mode (usually only limited number of color available). |
|
64 }; |
|
65 |
|
66 |
|
67 // Events sent to plugin by Screensaver |
|
68 enum TScreensaverEvent |
|
69 { |
|
70 // Null event |
|
71 EScreensaverEventNothing = 0x00, |
|
72 // Screensaver starting, plugin should get Draw() calls soon, or |
|
73 // disable Screensaver timer to do it's own draw timing |
|
74 EScreensaverEventStarting, |
|
75 // Screensaver stopping, plugin should stop drawing |
|
76 EScreensaverEventStopping, |
|
77 // Resolution, orientation, window etc has changed |
|
78 EScreensaverEventDisplayChanged, |
|
79 // Plugin-requested timeout has elapsed. Plugins |
|
80 // can use this for e.g. running a certain |
|
81 // amount of time and suspending to normal |
|
82 // screen saver after the timeout occurs |
|
83 EScreensaverEventTimeout, |
|
84 // Screensaver is about to enter preview mode. Next start and stop events |
|
85 // will indicate preview start and end |
|
86 EScreensaverEventPreview |
|
87 }; |
|
88 |
|
89 |
|
90 // In Rel 3.0 TScPluginCaps is moved to ScreensaverpluginIntDef.hrh |
|
91 #if 0 |
|
92 // Screen saver plugin capabilities |
|
93 enum TScPluginCaps |
|
94 { |
|
95 // Plugin has no special capabilities |
|
96 EScpCapsNone = 0x00, |
|
97 // Plugin implements the configure function |
|
98 EScpCapsConfigure = 0x01, |
|
99 // Plugin wants to be notified when selected as the active screensaver |
|
100 EScpCapsSelectionNotification = 0x02, |
|
101 // Plugin wants to be notified when preview command is selected |
|
102 EScpCapsPreviewNotification = 0x04 |
|
103 }; |
|
104 #endif |
|
105 |
|
106 const TInt KMaxPayloadTextLength = 30; |
|
107 const TInt KScreensaverMaxPartialModes = 6; |
|
108 |
|
109 // Maximum time (secs) lights can be requested to be on |
|
110 const TInt KMaxLightsOnTime = 30; |
|
111 |
|
112 // MACROS |
|
113 |
|
114 // DATA TYPES |
|
115 |
|
116 class TScreensaverPartialMode |
|
117 { |
|
118 public: |
|
119 TScreensaverPartialModeType iType; // Id of this partial mode level. |
|
120 TInt iBpp; // How many bits per pixels is actually used |
|
121 // if this partial mode level is activated. |
|
122 }; |
|
123 |
|
124 |
|
125 // More or less obsolete - may or may not work. As a rule displays |
|
126 // seem to support only a single partial mode |
|
127 class TScreensaverColorModel |
|
128 { |
|
129 public: |
|
130 TInt iNumberOfPartialModes; // Number of partial mode levels supported |
|
131 // by current display hardware. |
|
132 TScreensaverPartialMode iPartialModes[KScreensaverMaxPartialModes]; // Array of |
|
133 // supported partial modes; |
|
134 TScreensaverPartialMode iSystemPartialMode; // Partial mode level that default |
|
135 // screensaver uses when drawing standard |
|
136 // screensaver bar. |
|
137 TInt16 iColors[8]; // Array of possible background colors |
|
138 // for standard screensaver bar in |
|
139 // single background color mode. |
|
140 TRgb iDarkGradient[6]; // Darker shades for gradient effect |
|
141 // in standard screensaver bar |
|
142 // (these are used only if there is enough |
|
143 // colors to draw gradient effect). |
|
144 TRgb iLightGradient[6]; // Lighter shades for gradient |
|
145 // effect in standard screensaver bar. |
|
146 }; |
|
147 |
|
148 |
|
149 // Screensaver indicator payload. For integer types |
|
150 class TIndicatorPayload |
|
151 { |
|
152 public: |
|
153 TScreensaverPayloadType iType; |
|
154 TInt iInteger; |
|
155 TBuf16<KMaxPayloadTextLength> iText; |
|
156 TBool iIsDisplayed; // Read-only, cannot be set externally |
|
157 CGulIcon* iIcon; // Read-only, cannot be set externally |
|
158 |
|
159 public: |
|
160 TIndicatorPayload() |
|
161 : iType(EPayloadTypeUnknown), |
|
162 iInteger(-1), |
|
163 iIsDisplayed(EFalse), |
|
164 iIcon(NULL) |
|
165 {} |
|
166 }; |
|
167 |
|
168 |
|
169 class TScreensaverDisplayInfo |
|
170 { |
|
171 public: |
|
172 TInt iSize; // Size of struct, MUST be set by caller |
|
173 TRect iRect; // Rect of display area, may not be whole screen |
|
174 CCoeControl* iParent; // Parent control, has a window |
|
175 }; |
|
176 |
|
177 |
|
178 // FUNCTION PROTOTYPES |
|
179 |
|
180 // FORWARD DECLARATIONS |
|
181 |
|
182 // CLASS DECLARATION |
|
183 |
|
184 /** |
|
185 * This class defines plugin host interface. Plugin module uses |
|
186 * this interface for communicating with its host application. An instance |
|
187 * of this interface is given as a parameter to plugin module when |
|
188 * it is created. |
|
189 */ |
|
190 class MScreensaverPluginHost |
|
191 { |
|
192 public: |
|
193 /** |
|
194 * Sets screensaver application to use standard indicator view. |
|
195 * This is default mode for indicator drawing. |
|
196 */ |
|
197 virtual void UseStandardIndicators() = 0; |
|
198 |
|
199 /** |
|
200 * Notifies plugin host that plugin module is going to take care |
|
201 * of drawing indicator view and host shouldn't display them anymore. |
|
202 * If not overridden, normal screensaver will display when there |
|
203 * are indicators to show. Overriding the indicators does not mean they |
|
204 * _have_ to be drawn by the plugin, but that screensaver will not try to |
|
205 * do it. |
|
206 */ |
|
207 virtual void OverrideStandardIndicators() = 0; |
|
208 |
|
209 /** |
|
210 * Returns boolean value indicating whether standard indicator |
|
211 * drawing is used or not. |
|
212 * |
|
213 * @return ETrue if standard indicator drawing is used |
|
214 * EFalse if plugin module takes care of drawing indicators |
|
215 */ |
|
216 virtual TBool StandardIndicatorsUsed() const = 0; |
|
217 |
|
218 /** |
|
219 * Sets timeout value for refresh timer. Plugin module's draw |
|
220 * method is called every time when refresh timer expires. |
|
221 * |
|
222 * @param aValue Timeout value for refresh timer in microseconds. |
|
223 */ |
|
224 virtual void SetRefreshTimerValue(TInt aValue) = 0; |
|
225 |
|
226 /** |
|
227 * Returns the current timeout value of refresh timer. |
|
228 * |
|
229 * @return The current timeout value of refresh timer in microseconds. |
|
230 */ |
|
231 virtual TInt RefreshTimerValue() const = 0; |
|
232 |
|
233 /** |
|
234 * Returns payload associated with given screensaver indicator. |
|
235 * For list of supported indcicator indices see definition of |
|
236 * TScreensaverIndicatorIndex. Also see definition of |
|
237 * TIndicatorPayload class. |
|
238 * |
|
239 * @param aIndex Index of requested indicator. |
|
240 * @param aResult Structure where query results will be stored. |
|
241 * @return KErrNone if query was succesful. |
|
242 */ |
|
243 virtual TInt GetIndicatorPayload( |
|
244 TScreensaverIndicatorIndex aIndex, |
|
245 TIndicatorPayload& aResult) const = 0; |
|
246 |
|
247 /** |
|
248 * This method is used for activating so called screensaver partial mode. |
|
249 * Partial mode area specifies an area on the screen where screensaver |
|
250 * plugin module is going to draw during next refresh period. When partial |
|
251 * mode is activated the screen segments outside given area are |
|
252 * physically turned off to decrease power consumption. Whether partial |
|
253 * mode is supported or not depends on actual display hardware. |
|
254 * It is also possible that some devices support only limited number of |
|
255 * colors in partial mode area. |
|
256 * The actual size of the partial mode area may be restricted by the |
|
257 * display hardware, and differ from the size requested. Note that both |
|
258 * minimum and/or maximum size may be restricted. |
|
259 * If partial mode is not supported this method does nothing (that's |
|
260 * always the case in WINS environment). |
|
261 * |
|
262 * @param aStartRow Specifies the topmost pixel row of active |
|
263 * display area on the screen. |
|
264 * @param aEndRow Specifies the bottom pixel row of active display area. |
|
265 * |
|
266 * @param aMode Partial mode to be set. |
|
267 * |
|
268 * @return KErrNone if partial mode was successfully activated. |
|
269 * otherwise system wide error code. |
|
270 * @deprecated Should use the rect-version from S60 v3.0 on |
|
271 */ |
|
272 virtual TInt SetActiveDisplayArea( |
|
273 TInt aStartRow, |
|
274 TInt aEndRow, |
|
275 const TScreensaverPartialMode& aMode) = 0; |
|
276 |
|
277 /** |
|
278 * Cancels the effect of SetActiveDisplayArea method. The whole display area |
|
279 * is activated. |
|
280 */ |
|
281 virtual void ExitPartialMode() = 0; |
|
282 |
|
283 /** |
|
284 * Queries screensaver color in current environment (includes |
|
285 * partial modes supported by display hardware). |
|
286 * |
|
287 * @param aResult A structure for storing the results of the query. |
|
288 */ |
|
289 virtual const TScreensaverColorModel& GetColorModel() const = 0; |
|
290 |
|
291 /** |
|
292 * This method suspends plugin module drawing for given time. |
|
293 * During that time standard screensaver view is drawn. |
|
294 * |
|
295 * @param aTime Suspension time in microseconds. Values below |
|
296 * 500000 are rounded up to 500000. A negative value |
|
297 * suspends the plugin indefinitely. |
|
298 */ |
|
299 virtual void Suspend(TInt aTime) = 0; |
|
300 |
|
301 /** |
|
302 * With this method the plugin may request screen backlight to be |
|
303 * turned on or off. |
|
304 * |
|
305 * @param aSecs Desired time in seconds the screen backlight should be |
|
306 * turned on (1 - 30). Less than 1 will turn the lights off, |
|
307 * more than 30 will be treated as 30. The plugin host has the |
|
308 * final control over the lights, so time may be less than |
|
309 * requested, or the lights may be switched off even without |
|
310 * request before the time is up. |
|
311 */ |
|
312 virtual void RequestLights(TInt aSecs) = 0; |
|
313 |
|
314 /** |
|
315 * Plugin may use this function to enquire display properties. Should |
|
316 * be called e.g. in response to EScreensaverEventDisplayChanged to |
|
317 * retrieve the new information. |
|
318 * |
|
319 * @param aDisplayInfo Struct to receive the display information. NOTE |
|
320 * that iSize must be set by the caller. |
|
321 * |
|
322 */ |
|
323 virtual TInt DisplayInfo(TScreensaverDisplayInfo* aDisplayInfo) = 0; |
|
324 |
|
325 /** |
|
326 * This method is used for activating so called screensaver partial mode. |
|
327 * Partial mode area specifies an area on the screen where screensaver |
|
328 * plugin module is going to draw during next refresh period. When partial |
|
329 * mode is activated the screen segments outside given area are |
|
330 * physically turned off to decrease power consumption. Whether partial |
|
331 * mode is supported or not depends on actual display hardware. |
|
332 * It is also possible that some devices support only limited number of |
|
333 * colors in partial mode area. |
|
334 * The actual size of the partial mode area may be restricted by the |
|
335 * display hardware, and differ from the size requested. Note that both |
|
336 * minimum and/or maximum size may be restricted. |
|
337 * If partial mode is not supported this method does nothing (that's |
|
338 * always the case in WINS environment). |
|
339 * |
|
340 * @param aRect Specifies the active area on the screen. Parts outside |
|
341 * this area will not be visible. Note that x-dimension |
|
342 * needs to be set, even if it's not currently used |
|
343 * |
|
344 * @param aMode Partial mode to be set. |
|
345 * |
|
346 * @return KErrNone if partial mode was successfully activated. |
|
347 * otherwise system wide error code. |
|
348 * @since S60 v3.0 |
|
349 */ |
|
350 virtual TInt SetActiveDisplayArea(TRect& aRect, const TScreensaverPartialMode& aMode) = 0; |
|
351 |
|
352 /** |
|
353 * With this method the plugin may request Draw() timer to be |
|
354 * turned on or off. When on (the default) the plugins Draw() function |
|
355 * is called in intervals specified in SetRefreshTimerValue(). |
|
356 * |
|
357 * @param aOn Specifies whether the refresh timer is used to initiate |
|
358 * Draw() calls. |
|
359 */ |
|
360 virtual void UseRefreshTimer(TBool aOn = ETrue) = 0; |
|
361 |
|
362 /** |
|
363 * With this method the plugin may request a one-shot timeout event |
|
364 * (EScreensaverEventTimeout) after the specified amount of seconds |
|
365 * has passed. |
|
366 * If the plugin only wants to be displayed for a certain time, this |
|
367 * can be used instead of defining a timer in the plugin. Note that the |
|
368 * maximum time is about 35 minutes (TTimeIntervalMicroSeconds32). |
|
369 * If the screensaver is stopped before the time has passed, the |
|
370 * timer will be canceled and callback not issued. The timer is also |
|
371 * cancelled after the timeout has occurred. New timeout requests also |
|
372 * cancel any pending timeouts before issuing a new one. A time value |
|
373 * of 0 just cancels a pending timeout. |
|
374 * |
|
375 * @param aSecs Desired time in seconds after which a timeout callback |
|
376 * event should be issued. |
|
377 */ |
|
378 virtual void RequestTimeout(TInt aSecs) = 0; |
|
379 |
|
380 /** |
|
381 * With this method the plugin can revert to the default screensaver. |
|
382 * The plugin will be unloaded, and not used any more until the |
|
383 * user re-selects the plugin to be the active screensaver. |
|
384 * Should be used when the plugin encounters an unrecoverable error, |
|
385 * such as a missing file or expired DRM, and will not be able to run |
|
386 * any more. |
|
387 * NOTE: A plugin should not expect any events after calling this |
|
388 * function. |
|
389 */ |
|
390 virtual void RevertToDefaultSaver() = 0; |
|
391 }; |
|
392 |
|
393 |
|
394 /** |
|
395 * The base class for screensaver plugin modules. Every plugin module |
|
396 * must inherit and implement this class. |
|
397 */ |
|
398 class MScreensaverPlugin |
|
399 { |
|
400 public: |
|
401 /** |
|
402 * Virtual desctructor. |
|
403 */ |
|
404 virtual ~MScreensaverPlugin() {} |
|
405 |
|
406 /** |
|
407 * Used to initialize the plugin module after creation. |
|
408 * Name() function may be called without the plugin being initialized, |
|
409 * to enable name query from modules that are not plugin hosts. |
|
410 * |
|
411 * @param aHost Screensaver plugin host. |
|
412 * @return KErrNone if everything went ok. Otherwise |
|
413 * system wide error code. |
|
414 */ |
|
415 virtual TInt InitializeL(MScreensaverPluginHost *aHost) = 0; |
|
416 |
|
417 /** |
|
418 * When a plugin module is active this method is called every time |
|
419 * when refresh timer expires in screensaver application. |
|
420 * |
|
421 * @param aGc Graphics context for plugin module to draw to. |
|
422 * @return KErrNone if everything went ok. Otherwise |
|
423 * system wide error code (doesn't have any effect in |
|
424 * current version). |
|
425 */ |
|
426 virtual TInt Draw(CWindowGc& aGc) = 0; |
|
427 |
|
428 /** |
|
429 * Returns the name of plugin module. Returned name is displayed in |
|
430 * the list of installed plugin modules in Themes application. |
|
431 * If this function returns an empty name (KNullDesC), displayed name is |
|
432 * taken from ECom registration resource. |
|
433 * |
|
434 * @return Descriptor containing the name of the plugin module. |
|
435 */ |
|
436 virtual const TDesC16& Name() const = 0; |
|
437 |
|
438 /** |
|
439 * Handler function for screensaver events. |
|
440 * |
|
441 * @param aEvent Event to be handled. |
|
442 * @param aData Data related to the event. To be decided on a case-by-case |
|
443 * basis. |
|
444 * |
|
445 * @return KErrNone if OK, otherwise an error code. |
|
446 */ |
|
447 virtual TInt HandleScreensaverEventL( |
|
448 TScreensaverEvent aEvent, |
|
449 TAny* aData) = 0; |
|
450 |
|
451 /** |
|
452 * Screensaver plugin capabilities query. The capabilitities |
|
453 * reveal which functions the plugin implements, that can be |
|
454 * used by calling PluginFunction(). |
|
455 * |
|
456 * @return Bit mask of plugin capabilities. |
|
457 * |
|
458 * @note Capabilites need to be defined as opaque_data in ECom plugin |
|
459 * registration file as well. |
|
460 */ |
|
461 virtual TInt Capabilities() { return EScpCapsNone; } |
|
462 |
|
463 /** |
|
464 * Screensaver plugin function method. Only the functions |
|
465 * returned by Capabilities() can be used, and only one |
|
466 * function at a time. |
|
467 * |
|
468 * @paran aFunction |
|
469 * @param aParam Parameters to the function. TBD function-by-function. |
|
470 * |
|
471 * @return System wide error code. KErrNone on success. |
|
472 */ |
|
473 virtual TInt PluginFunction( |
|
474 TScPluginCaps /*aFunction*/, |
|
475 TAny* /*aParam*/) |
|
476 { |
|
477 return KErrNone; |
|
478 } |
|
479 }; |
|
480 |
|
481 |
|
482 #endif // SCREEN_SAVER_PLUGIN_H |
|
483 |
|
484 // End of file. |
|