S60 3rd Edition API Reference: screensaverplugin.h Source File

00001 /*
00002 * ============================================================================
00003 *  Name       : Screensaverplugin.h
00004 *  Part of    : Screensaver
00005 *  Description: Defines screensaver plugin interface.
00006 *  Version:
00007 *
00008 *  Copyright � 2005 Nokia Corporation.
00009 *  This material, including documentation and any related 
00010 *  computer programs, is protected by copyright controlled by 
00011 *  Nokia Corporation. All rights are reserved. Copying, 
00012 *  including reproducing, storing,  adapting or translating, any 
00013 *  or all of this material requires the prior written consent of 
00014 *  Nokia Corporation. This material also contains confidential 
00015 *  information which may not be disclosed to others without the 
00016 *  prior written consent of Nokia Corporation.
00017 * ============================================================================
00018 */
00019 
00020 #ifndef SCREEN_SAVER_PLUGIN_H
00021 #define SCREEN_SAVER_PLUGIN_H
00022 
00023 //  INCLUDES
00024 #include <e32base.h>
00025 #include <gulicon.h>
00026 #include <coecntrl.h>
00027 
00028 #include <ScreensaverpluginIntDef.hrh> // For TScPluginCaps
00029 
00030 // CONSTANTS
00031 
00032 //
00033 // Enumerations for screensaver indicators.
00034 //
00035 enum TScreensaverIndicatorIndex
00036     {      
00037     EScreensaverIndicatorIndexNewMessages,
00038     EScreensaverIndicatorIndexNewMissedCalls,
00039     EScreensaverIndicatorIndexKeyGuardState,
00040     EScreensaverIndicatorIndexProfileName,
00041     EScreensaverIndicatorIndexChatMessage,
00042     EScreensaverIndicatorIndexEmail,
00043     EScreensaverIndicatorIndexVoicemail
00044 #start_since SINCE_3_1_SDK
00045     ,EScreensaverIndicatorIndexAmPm
00046 #end_since SINCE_3_1_SDK
00047     };
00048 
00049 
00050 // Screensaver indicator payload types
00051 enum TScreensaverPayloadType
00052     {
00053     EPayloadTypeUnknown = 0,
00054     EPayloadTypeInteger,   // Icon and and number, or just icon (integer -1)
00055     EPayloadTypeText,      // E.g. profile, AM/PM
00056     EPayloadTypeIcon       // Icon only
00057     };
00058 
00059 
00060 // Enumerations for possible partial mode types.
00061 enum TScreensaverPartialModeType
00062     {
00063     EPartialModeTypeDefault = 0,         // Default partial mode (usually same as "most power saving"): 
00064     EPartialModeTypeFull,                // Partial mode with maximum number of colors.
00065     EPartialModeTypeReduced,
00066     EPartialModeTypeMostPowerSaving      // Most power saving partial mode (usually only limited number of color available).
00067     };
00068 
00069 
00070 // Events sent to plugin by Screensaver 
00071 enum TScreensaverEvent
00072     {
00073     // Null event
00074     EScreensaverEventNothing = 0x00,
00075     // Screensaver starting, plugin should get Draw() calls soon, or
00076     // disable Screensaver timer to do it's own draw timing
00077     EScreensaverEventStarting,
00078     // Screensaver stopping, plugin should stop drawing
00079     EScreensaverEventStopping,
00080     // Resolution, orientation, window etc has changed
00081     EScreensaverEventDisplayChanged,
00082     // Plugin-requested timeout has elapsed. Plugins
00083     // can use this for e.g. running a certain
00084     // amount of time and suspending to normal
00085     // screen saver after the timeout occurs
00086     EScreensaverEventTimeout
00087 #start_since SINCE_3_1_SDK
00088     // Screensaver is about to enter preview mode. Next start and stop events
00089     // will indicate preview start and end 
00090     ,EScreensaverEventPreview
00091 #end_since SINCE_3_1_SDK
00092     };
00093 
00094 
00095 // In Rel 3.0 TScPluginCaps is moved to ScreensaverpluginIntDef.hrh
00096 #if 0
00097 // Screen saver plugin capabilities
00098 enum TScPluginCaps
00099     {
00100     // Plugin has no special capabilities
00101     EScpCapsNone = 0x00,
00102     // Plugin implements the configure function
00103     EScpCapsConfigure = 0x01,
00104     // Plugin wants to be notified when selected as the active screensaver
00105     EScpCapsSelectionNotification = 0x02 
00106 #start_since SINCE_3_1_SDK
00107     // Plugin wants to be notified when preview command is selected
00108     ,EScpCapsPreviewNotification = 0x04
00109 #end_since SINCE_3_1_SDK
00110     };
00111 #endif
00112 
00113 const TInt KMaxPayloadTextLength = 30;
00114 const TInt KScreensaverMaxPartialModes = 6;
00115 
00116 // Maximum time (secs) lights can be requested to be on
00117 const TInt KMaxLightsOnTime = 30;
00118 
00119 // MACROS
00120 
00121 // DATA TYPES
00122 
00123 class TScreensaverPartialMode
00124     {
00125 public: 
00126     TScreensaverPartialModeType iType;   // Id of this partial mode level. 
00127     TInt iBpp;                           // How many bits per pixels is actually used
00128                                          // if this partial mode level is activated.
00129     };
00130 
00131 
00132 // More or less obsolete - may or may not work. As a rule displays
00133 // seem to support only a single partial mode
00134 class TScreensaverColorModel
00135     {
00136 public:
00137     TInt iNumberOfPartialModes;      // Number of partial mode levels supported
00138                                      // by current display hardware.
00139     TScreensaverPartialMode iPartialModes[KScreensaverMaxPartialModes];  // Array of
00140                                      // supported partial modes; 
00141     TScreensaverPartialMode iSystemPartialMode;  // Partial mode level that default
00142                                      // screensaver uses when drawing standard
00143                                      // screensaver bar.
00144     TInt16 iColors[8];               // Array of possible background colors
00145                                      // for standard screensaver bar in 
00146                                      // single background color mode.
00147     TRgb iDarkGradient[6];           // Darker shades for gradient effect 
00148                                      // in standard screensaver bar 
00149                                      // (these are used only if there is enough
00150                                      // colors to draw gradient effect). 
00151     TRgb iLightGradient[6];          // Lighter shades for gradient 
00152                                      // effect in standard screensaver bar.
00153     };  
00154 
00155 
00156 // Screensaver indicator payload. For integer types 
00157 class TIndicatorPayload
00158     {
00159 public:
00160     TScreensaverPayloadType iType;  
00161     TInt iInteger;
00162     TBuf16<KMaxPayloadTextLength> iText;
00163     TBool iIsDisplayed;   // Read-only, cannot be set externally
00164     CGulIcon* iIcon;      // Read-only, cannot be set externally
00165         
00166 public:
00167     TIndicatorPayload()
00168         : iType(EPayloadTypeUnknown),
00169           iInteger(-1),
00170           iIsDisplayed(EFalse),
00171           iIcon(NULL)
00172         {}
00173     };
00174 
00175 
00176 class TScreensaverDisplayInfo
00177     {
00178 public:
00179     TInt iSize;            // Size of struct, MUST be set by caller
00180     TRect iRect;           // Rect of display area, may not be whole screen
00181     CCoeControl* iParent;  // Parent control, has a window
00182     };
00183 
00184 
00185 // FUNCTION PROTOTYPES
00186 
00187 // FORWARD DECLARATIONS
00188 
00189 // CLASS DECLARATION
00190 
00197 class MScreensaverPluginHost 
00198     {
00199 public:
00204     virtual void UseStandardIndicators() = 0;
00205 
00214     virtual void OverrideStandardIndicators() = 0;
00215 
00223     virtual TBool StandardIndicatorsUsed() const = 0;
00224 
00231     virtual void SetRefreshTimerValue(TInt aValue) = 0;
00232 
00238     virtual TInt RefreshTimerValue() const = 0;
00239 
00250     virtual TInt GetIndicatorPayload(
00251         TScreensaverIndicatorIndex aIndex,
00252         TIndicatorPayload& aResult) const = 0;
00253 
00279     virtual TInt SetActiveDisplayArea(
00280         TInt aStartRow,
00281         TInt aEndRow,
00282         const TScreensaverPartialMode& aMode) = 0;
00283 
00288     virtual void ExitPartialMode() = 0;
00289 
00296     virtual const TScreensaverColorModel& GetColorModel() const = 0;
00297 
00306     virtual void Suspend(TInt aTime) = 0;
00307 
00319     virtual void RequestLights(TInt aSecs) = 0;
00320 
00330     virtual TInt DisplayInfo(TScreensaverDisplayInfo* aDisplayInfo) = 0;
00331     
00357     virtual TInt SetActiveDisplayArea(TRect& aRect, const TScreensaverPartialMode& aMode) = 0;
00358 
00367     virtual void UseRefreshTimer(TBool aOn = ETrue) = 0;
00368 
00385     virtual void RequestTimeout(TInt aSecs) = 0;
00386 
00397     virtual void RevertToDefaultSaver() = 0;
00398     };
00399 
00400 
00405 class MScreensaverPlugin 
00406     {
00407 public:         
00411     virtual ~MScreensaverPlugin() {}
00412 
00422     virtual TInt InitializeL(MScreensaverPluginHost *aHost) = 0;
00423 
00433     virtual TInt Draw(CWindowGc& aGc) = 0;
00434 
00443     virtual const TDesC16& Name() const = 0;
00444 
00454     virtual TInt HandleScreensaverEventL(
00455         TScreensaverEvent aEvent,
00456         TAny* aData) = 0;
00457 
00468     virtual TInt Capabilities() { return EScpCapsNone; }
00469 
00480     virtual TInt PluginFunction(
00481         TScPluginCaps /*aFunction*/,
00482         TAny* /*aParam*/)
00483         {
00484         return KErrNone;
00485         }
00486     };
00487 
00488 
00489 // SCREEN_SAVER_PLUGIN_H
00490 #endif
00491 
00492 // End of file.