/*

 * Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies).

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of "Eclipse Public License v1.0"

 * which accompanies this distribution, and is available

 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  Defines screensaver plugin interface.

 *

 */

 #ifndef SCREEN_SAVER_PLUGIN_H

 #define SCREEN_SAVER_PLUGIN_H

 //  INCLUDES

 #include <e32base.h>

 #include <gulicon.h>

 #include <coecntrl.h>

 #include <ScreensaverpluginIntDef.hrh> // For TScPluginCaps

 // CONSTANTS

 //

 // Enumerations for screensaver indicators.

 //

 enum TScreensaverIndicatorIndex

     {      

     EScreensaverIndicatorIndexNewMessages,

     EScreensaverIndicatorIndexNewMissedCalls,

     EScreensaverIndicatorIndexKeyGuardState,

     EScreensaverIndicatorIndexProfileName,

     EScreensaverIndicatorIndexChatMessage,

     EScreensaverIndicatorIndexEmail,

     EScreensaverIndicatorIndexVoicemail,

     EScreensaverIndicatorIndexAmPm

     };

 // Screensaver indicator payload types

 enum TScreensaverPayloadType

     {

     EPayloadTypeUnknown = 0,

     EPayloadTypeInteger,   // Icon and and number, or just icon (integer -1)

     EPayloadTypeText,      // E.g. profile, AM/PM

     EPayloadTypeIcon       // Icon only

     };

 // Enumerations for possible partial mode types.

 enum TScreensaverPartialModeType

     {

     EPartialModeTypeDefault = 0,         // Default partial mode (usually same as "most power saving"): 

     EPartialModeTypeFull,                // Partial mode with maximum number of colors.

     EPartialModeTypeReduced,

     EPartialModeTypeMostPowerSaving      // Most power saving partial mode (usually only limited number of color available).

     };

 // Events sent to plugin by Screensaver 

 enum TScreensaverEvent

     {

     // Null event

     EScreensaverEventNothing = 0x00,

     // Screensaver starting, plugin should get Draw() calls soon, or

     // disable Screensaver timer to do it's own draw timing

     EScreensaverEventStarting,

     // Screensaver stopping, plugin should stop drawing

     EScreensaverEventStopping,

     // Resolution, orientation, window etc has changed

     EScreensaverEventDisplayChanged,

     // Plugin-requested timeout has elapsed. Plugins

     // can use this for e.g. running a certain

     // amount of time and suspending to normal

     // screen saver after the timeout occurs

     EScreensaverEventTimeout,

     // Screensaver is about to enter preview mode. Next start and stop events

     // will indicate preview start and end 

     EScreensaverEventPreview

     };

 // In Rel 3.0 TScPluginCaps is moved to ScreensaverpluginIntDef.hrh

 #if 0

 // Screen saver plugin capabilities

 enum TScPluginCaps

     {

     // Plugin has no special capabilities

     EScpCapsNone = 0x00,

     // Plugin implements the configure function

     EScpCapsConfigure = 0x01,

     // Plugin wants to be notified when selected as the active screensaver

     EScpCapsSelectionNotification = 0x02, 

     // Plugin wants to be notified when preview command is selected

     EScpCapsPreviewNotification = 0x04

     };

 #endif

 const TInt KMaxPayloadTextLength = 30;

 const TInt KScreensaverMaxPartialModes = 6;

 // Maximum time (secs) lights can be requested to be on

 const TInt KMaxLightsOnTime = 30;

 // MACROS

 // DATA TYPES

 class TScreensaverPartialMode

     {

 public: 

     TScreensaverPartialModeType iType;   // Id of this partial mode level. 

     TInt iBpp;                           // How many bits per pixels is actually used

                                          // if this partial mode level is activated.

     };

 // More or less obsolete - may or may not work. As a rule displays

 // seem to support only a single partial mode

 class TScreensaverColorModel

     {

 public:

     TInt iNumberOfPartialModes;      // Number of partial mode levels supported

                                      // by current display hardware.

     TScreensaverPartialMode iPartialModes[KScreensaverMaxPartialModes];  // Array of

                                      // supported partial modes; 

     TScreensaverPartialMode iSystemPartialMode;  // Partial mode level that default

                                      // screensaver uses when drawing standard

                                      // screensaver bar.

     TInt16 iColors[8];               // Array of possible background colors

                                      // for standard screensaver bar in 

                                      // single background color mode.

     TRgb iDarkGradient[6];           // Darker shades for gradient effect 

                                      // in standard screensaver bar 

                                      // (these are used only if there is enough

                                      // colors to draw gradient effect). 

     TRgb iLightGradient[6];          // Lighter shades for gradient 

                                      // effect in standard screensaver bar.

     };  

 // Screensaver indicator payload. For integer types 

 class TIndicatorPayload

     {

 public:

     TScreensaverPayloadType iType;  

     TInt iInteger;

     TBuf16<KMaxPayloadTextLength> iText;

     TBool iIsDisplayed;   // Read-only, cannot be set externally

     CGulIcon* iIcon;      // Read-only, cannot be set externally

 public:

     TIndicatorPayload()

         : iType(EPayloadTypeUnknown),

           iInteger(-1),

           iIsDisplayed(EFalse),

           iIcon(NULL)

         {}

     };

 class TScreensaverDisplayInfo

     {

 public:

     TInt iSize;            // Size of struct, MUST be set by caller

     TRect iRect;           // Rect of display area, may not be whole screen

     CCoeControl* iParent;  // Parent control, has a window

     };

 // FUNCTION PROTOTYPES

 // FORWARD DECLARATIONS

 // CLASS DECLARATION

 /**

 * This class defines plugin host interface. Plugin module uses

 * this interface for communicating with its host application. An instance

 * of this interface is given as a parameter to plugin module when

 * it is created.

 */

 class MScreensaverPluginHost 

     {

 public:

     /**

      * Sets screensaver application to use standard indicator view.

      * This is default mode for indicator drawing.

      */

     virtual void UseStandardIndicators() = 0;

     /**

      * Notifies plugin host that plugin module is going to take care

      * of drawing indicator view and host shouldn't display them anymore.

      * If not overridden, normal screensaver will display when there

      * are indicators to show. Overriding the indicators does not mean they

      * _have_ to be drawn by the plugin, but that screensaver will not try to

      * do it.

      */

     virtual void OverrideStandardIndicators() = 0;

     /**

      * Returns boolean value indicating whether standard indicator

      * drawing is used or not.

      *

      * @return ETrue  if standard indicator drawing is used

      *         EFalse if plugin module takes care of drawing indicators 

      */

     virtual TBool StandardIndicatorsUsed() const = 0;

     /**

      * Sets timeout value for refresh timer. Plugin module's draw

      * method is called every time when refresh timer expires.

      *

      * @param aValue  Timeout value for refresh timer in microseconds.

      */

     virtual void SetRefreshTimerValue(TInt aValue) = 0;

     /**

      * Returns the current timeout value of refresh timer.

      *

      * @return The current timeout value of refresh timer in microseconds.

      */

     virtual TInt RefreshTimerValue() const = 0;

     /**

      * Returns payload associated with given screensaver indicator.

      * For list of supported indcicator indices see definition of 

      * TScreensaverIndicatorIndex. Also see definition of

      * TIndicatorPayload class.

      *

      * @param aIndex  Index of requested indicator.

      * @param aResult Structure where query results will be stored.

      * @return KErrNone if query was succesful.

      */

     virtual TInt GetIndicatorPayload(

         TScreensaverIndicatorIndex aIndex,

         TIndicatorPayload& aResult) const = 0;

     /**

      * This method is used for activating so called screensaver partial mode.

      * Partial mode area specifies an area on the screen where screensaver

      * plugin module is going to draw during next refresh period. When partial

      * mode is activated the screen segments outside given area are 

      * physically turned off to decrease power consumption. Whether partial

      * mode is supported or not depends on actual display hardware.

      * It is also possible that some devices support only limited number of

      * colors in partial mode area.

      * The actual size of the partial mode area may be restricted by the

      * display hardware, and differ from the size requested. Note that both

      * minimum and/or maximum size may be restricted.

      * If partial mode is not supported this method does nothing (that's

      * always the case in WINS environment). 

      *

      * @param aStartRow  Specifies the topmost pixel row of active 

      *                   display area on the screen.

      * @param aEndRow    Specifies the bottom pixel row of active display area.

      *

      * @param aMode      Partial mode to be set.

      * 

      * @return KErrNone  if partial mode was successfully activated.

      *                   otherwise system wide error code.

      * @deprecated       Should use the rect-version from S60 v3.0 on

      */

     virtual TInt SetActiveDisplayArea(

         TInt aStartRow,

         TInt aEndRow,

         const TScreensaverPartialMode& aMode) = 0;

     /**

      * Cancels the effect of SetActiveDisplayArea method. The whole display area 

      * is activated.

      */

     virtual void ExitPartialMode() = 0;

     /**

      * Queries screensaver color in current environment (includes

      * partial modes supported by display hardware).

      *

      * @param aResult  A structure for storing the results of the query.

      */

     virtual const TScreensaverColorModel& GetColorModel() const = 0;

     /**

      * This method suspends plugin module drawing for given time.

      * During that time standard screensaver view is drawn. 

      *

      * @param aTime Suspension time in microseconds. Values below

      *        500000 are rounded up to 500000. A negative value

      *        suspends the plugin indefinitely.

      */

     virtual void Suspend(TInt aTime) = 0;

     /**

      * With this method the plugin may request screen backlight to be

      * turned on or off. 

      *

      * @param aSecs Desired time in seconds the screen backlight should be

      *        turned on (1 - 30). Less than 1 will turn the lights off,

      *        more than 30 will be treated as 30. The plugin host has the

      *        final control over the lights, so time may be less than

      *        requested, or the lights may be switched off even without

      *        request before the time is up.

      */

     virtual void RequestLights(TInt aSecs) = 0;

     /**

      * Plugin may use this function to enquire display properties. Should

      * be called e.g. in response to EScreensaverEventDisplayChanged to

      * retrieve the new information.

      *

      * @param aDisplayInfo Struct to receive the display information. NOTE

      *        that iSize must be set by the caller.

      *

      */

     virtual TInt DisplayInfo(TScreensaverDisplayInfo* aDisplayInfo) = 0;

     /**

      * This method is used for activating so called screensaver partial mode.

      * Partial mode area specifies an area on the screen where screensaver

      * plugin module is going to draw during next refresh period. When partial

      * mode is activated the screen segments outside given area are 

      * physically turned off to decrease power consumption. Whether partial

      * mode is supported or not depends on actual display hardware.

      * It is also possible that some devices support only limited number of

      * colors in partial mode area.

      * The actual size of the partial mode area may be restricted by the

      * display hardware, and differ from the size requested. Note that both

      * minimum and/or maximum size may be restricted.

      * If partial mode is not supported this method does nothing (that's

      * always the case in WINS environment). 

      *

      * @param aRect      Specifies the active area on the screen. Parts outside

      *                   this area will not be visible. Note that x-dimension

      *                   needs to be set, even if it's not currently used

      *

      * @param aMode      Partial mode to be set.

      * 

      * @return KErrNone  if partial mode was successfully activated.

      *                   otherwise system wide error code.

      * @since            S60 v3.0

      */

     virtual TInt SetActiveDisplayArea(TRect& aRect, const TScreensaverPartialMode& aMode) = 0;

     /**

      * With this method the plugin may request Draw() timer to be

      * turned on or off. When on (the default) the plugins Draw() function

      * is called in intervals specified in SetRefreshTimerValue().

      *

      * @param aOn  Specifies whether the refresh timer is used to initiate

      *             Draw() calls.

      */

     virtual void UseRefreshTimer(TBool aOn = ETrue) = 0;

     /**

      * With this method the plugin may request a one-shot timeout event

      * (EScreensaverEventTimeout) after the specified amount of seconds

      * has passed.

      * If the plugin only wants to be displayed for a certain time, this

      * can be used instead of defining a timer in the plugin. Note that the

      * maximum time is about 35 minutes (TTimeIntervalMicroSeconds32).

      * If the screensaver is stopped before the time has passed, the

      * timer will be canceled and callback not issued. The timer is also

      * cancelled after the timeout has occurred. New timeout requests also

      * cancel any pending timeouts before issuing a new one. A time value

      * of 0 just cancels a pending timeout.

      *

      * @param aSecs Desired time in seconds after which a timeout callback

      *              event should be issued. 

      */

     virtual void RequestTimeout(TInt aSecs) = 0;

     /**

      * With this method the plugin can revert to the default screensaver.

      * The plugin will be unloaded, and not used any more until the

      * user re-selects the plugin to be the active screensaver.

      * Should be used when the plugin encounters an unrecoverable error,

      * such as a missing file or expired DRM, and will not be able to run

      * any more.

      * NOTE: A plugin should not expect any events after calling this

      * function.

      */

     virtual void RevertToDefaultSaver() = 0;

     };

 /**

 * The base class for screensaver plugin modules. Every plugin module

 * must inherit and implement this class.

 */

 class MScreensaverPlugin 

     {

 public:         

     /**

      *  Virtual desctructor.

      */

     virtual ~MScreensaverPlugin() {}

     /**

      * Used to initialize the plugin module after creation.

      * Name() function may be called without the plugin being initialized,

      * to enable name query from modules that are not plugin hosts.

      *

      * @param aHost Screensaver plugin host.

      * @return KErrNone if everything went ok. Otherwise 

      *         system wide error code.

      */

     virtual TInt InitializeL(MScreensaverPluginHost *aHost) = 0;

     /**

      * When a plugin module is active this method is called every time 

      * when refresh timer expires in screensaver application.

      *

      * @param aGc  Graphics context for plugin module to draw to.

      * @return KErrNone if everything went ok. Otherwise 

      *         system wide error code (doesn't have any effect in

      *         current version).

      */

     virtual TInt Draw(CWindowGc& aGc) = 0;

     /**

      * Returns the name of plugin module. Returned name is displayed in

      * the list of installed plugin modules in Themes application.

      * If this function returns an empty name (KNullDesC), displayed name is 

      * taken from ECom registration resource.

      *

      * @return Descriptor containing the name of the plugin module.

      */

     virtual const TDesC16& Name() const = 0;

     /**

      * Handler function for screensaver events.

      *

      * @param aEvent Event to be handled.

      * @param aData  Data related to the event. To be decided on a case-by-case

      * basis.

      *

      * @return KErrNone if OK, otherwise an error code.

      */

     virtual TInt HandleScreensaverEventL(

         TScreensaverEvent aEvent,

         TAny* aData) = 0;

     /**

      * Screensaver plugin capabilities query. The capabilitities

      * reveal which functions the plugin implements, that can be

      * used by calling PluginFunction().

      *

      * @return Bit mask of plugin capabilities.

      *

      * @note Capabilites need to be defined as opaque_data in ECom plugin

      *       registration file as well.

      */

     virtual TInt Capabilities() { return EScpCapsNone; }

     /**

      * Screensaver plugin function method. Only the functions

      * returned by Capabilities() can be used, and only one

      * function at a time.

      *

      * @paran aFunction

      * @param aParam Parameters to the function. TBD function-by-function.

      * 

      * @return System wide error code. KErrNone on success.

      */

     virtual TInt PluginFunction(

         TScPluginCaps /*aFunction*/,

         TAny* /*aParam*/)

         {

         return KErrNone;

         }

     };

 #endif   // SCREEN_SAVER_PLUGIN_H

 // End of file.