/*

* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.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.