screensaverplugin.h

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     EScreensaverIndicatorIndexAmPm
00045     };
00046 
00047 
00048 // Screensaver indicator payload types
00049 enum TScreensaverPayloadType
00050     {
00051     EPayloadTypeUnknown = 0,
00052     EPayloadTypeInteger,   // Icon and and number, or just icon (integer -1)
00053     EPayloadTypeText,      // E.g. profile, AM/PM
00054     EPayloadTypeIcon       // Icon only
00055     };
00056 
00057 
00058 // Enumerations for possible partial mode types.
00059 enum TScreensaverPartialModeType
00060     {
00061     EPartialModeTypeDefault = 0,         // Default partial mode (usually same as "most power saving"): 
00062     EPartialModeTypeFull,                // Partial mode with maximum number of colors.
00063     EPartialModeTypeReduced,
00064     EPartialModeTypeMostPowerSaving      // Most power saving partial mode (usually only limited number of color available).
00065     };
00066 
00067 
00068 // Events sent to plugin by Screensaver 
00069 enum TScreensaverEvent
00070     {
00071     // Null event
00072     EScreensaverEventNothing = 0x00,
00073     // Screensaver starting, plugin should get Draw() calls soon, or
00074     // disable Screensaver timer to do it's own draw timing
00075     EScreensaverEventStarting,
00076     // Screensaver stopping, plugin should stop drawing
00077     EScreensaverEventStopping,
00078     // Resolution, orientation, window etc has changed
00079     EScreensaverEventDisplayChanged,
00080     // Plugin-requested timeout has elapsed. Plugins
00081     // can use this for e.g. running a certain
00082     // amount of time and suspending to normal
00083     // screen saver after the timeout occurs
00084     EScreensaverEventTimeout,
00085     // Screensaver is about to enter preview mode. Next start and stop events
00086     // will indicate preview start and end 
00087     EScreensaverEventPreview
00088     };
00089 
00090 
00091 // In Rel 3.0 TScPluginCaps is moved to ScreensaverpluginIntDef.hrh
00092 #if 0
00093 // Screen saver plugin capabilities
00094 enum TScPluginCaps
00095     {
00096     // Plugin has no special capabilities
00097     EScpCapsNone = 0x00,
00098     // Plugin implements the configure function
00099     EScpCapsConfigure = 0x01,
00100     // Plugin wants to be notified when selected as the active screensaver
00101     EScpCapsSelectionNotification = 0x02, 
00102     // Plugin wants to be notified when preview command is selected
00103     EScpCapsPreviewNotification = 0x04
00104     };
00105 #endif
00106 
00107 const TInt KMaxPayloadTextLength = 30;
00108 const TInt KScreensaverMaxPartialModes = 6;
00109 
00110 // Maximum time (secs) lights can be requested to be on
00111 const TInt KMaxLightsOnTime = 30;
00112 
00113 // MACROS
00114 
00115 // DATA TYPES
00116 
00117 class TScreensaverPartialMode
00118     {
00119 public: 
00120     TScreensaverPartialModeType iType;   // Id of this partial mode level. 
00121     TInt iBpp;                           // How many bits per pixels is actually used
00122                                          // if this partial mode level is activated.
00123     };
00124 
00125 
00126 // More or less obsolete - may or may not work. As a rule displays
00127 // seem to support only a single partial mode
00128 class TScreensaverColorModel
00129     {
00130 public:
00131     TInt iNumberOfPartialModes;      // Number of partial mode levels supported
00132                                      // by current display hardware.
00133     TScreensaverPartialMode iPartialModes[KScreensaverMaxPartialModes];  // Array of
00134                                      // supported partial modes; 
00135     TScreensaverPartialMode iSystemPartialMode;  // Partial mode level that default
00136                                      // screensaver uses when drawing standard
00137                                      // screensaver bar.
00138     TInt16 iColors[8];               // Array of possible background colors
00139                                      // for standard screensaver bar in 
00140                                      // single background color mode.
00141     TRgb iDarkGradient[6];           // Darker shades for gradient effect 
00142                                      // in standard screensaver bar 
00143                                      // (these are used only if there is enough
00144                                      // colors to draw gradient effect). 
00145     TRgb iLightGradient[6];          // Lighter shades for gradient 
00146                                      // effect in standard screensaver bar.
00147     };  
00148 
00149 
00150 // Screensaver indicator payload. For integer types 
00151 class TIndicatorPayload
00152     {
00153 public:
00154     TScreensaverPayloadType iType;  
00155     TInt iInteger;
00156     TBuf16<KMaxPayloadTextLength> iText;
00157     TBool iIsDisplayed;   // Read-only, cannot be set externally
00158     CGulIcon* iIcon;      // Read-only, cannot be set externally
00159         
00160 public:
00161     TIndicatorPayload()
00162         : iType(EPayloadTypeUnknown),
00163           iInteger(-1),
00164           iIsDisplayed(EFalse),
00165           iIcon(NULL)
00166         {}
00167     };
00168 
00169 
00170 class TScreensaverDisplayInfo
00171     {
00172 public:
00173     TInt iSize;            // Size of struct, MUST be set by caller
00174     TRect iRect;           // Rect of display area, may not be whole screen
00175     CCoeControl* iParent;  // Parent control, has a window
00176     };
00177 
00178 
00179 // FUNCTION PROTOTYPES
00180 
00181 // FORWARD DECLARATIONS
00182 
00183 // CLASS DECLARATION
00184 
00191 class MScreensaverPluginHost 
00192     {
00193 public:
00198     virtual void UseStandardIndicators() = 0;
00199 
00208     virtual void OverrideStandardIndicators() = 0;
00209 
00217     virtual TBool StandardIndicatorsUsed() const = 0;
00218 
00225     virtual void SetRefreshTimerValue(TInt aValue) = 0;
00226 
00232     virtual TInt RefreshTimerValue() const = 0;
00233 
00244     virtual TInt GetIndicatorPayload(
00245         TScreensaverIndicatorIndex aIndex,
00246         TIndicatorPayload& aResult) const = 0;
00247 
00273     virtual TInt SetActiveDisplayArea(
00274         TInt aStartRow,
00275         TInt aEndRow,
00276         const TScreensaverPartialMode& aMode) = 0;
00277 
00282     virtual void ExitPartialMode() = 0;
00283 
00290     virtual const TScreensaverColorModel& GetColorModel() const = 0;
00291 
00300     virtual void Suspend(TInt aTime) = 0;
00301 
00313     virtual void RequestLights(TInt aSecs) = 0;
00314 
00324     virtual TInt DisplayInfo(TScreensaverDisplayInfo* aDisplayInfo) = 0;
00325     
00351     virtual TInt SetActiveDisplayArea(TRect& aRect, const TScreensaverPartialMode& aMode) = 0;
00352 
00361     virtual void UseRefreshTimer(TBool aOn = ETrue) = 0;
00362 
00379     virtual void RequestTimeout(TInt aSecs) = 0;
00380 
00391     virtual void RevertToDefaultSaver() = 0;
00392     };
00393 
00394 
00399 class MScreensaverPlugin 
00400     {
00401 public:         
00405     virtual ~MScreensaverPlugin() {}
00406 
00416     virtual TInt InitializeL(MScreensaverPluginHost *aHost) = 0;
00417 
00427     virtual TInt Draw(CWindowGc& aGc) = 0;
00428 
00437     virtual const TDesC16& Name() const = 0;
00438 
00448     virtual TInt HandleScreensaverEventL(
00449         TScreensaverEvent aEvent,
00450         TAny* aData) = 0;
00451 
00462     virtual TInt Capabilities() { return EScpCapsNone; }
00463 
00474     virtual TInt PluginFunction(
00475         TScPluginCaps /*aFunction*/,
00476         TAny* /*aParam*/)
00477         {
00478         return KErrNone;
00479         }
00480     };
00481 
00482 
00483 // SCREEN_SAVER_PLUGIN_H
00484 #endif
00485 
00486 // End of file.