williamr@2: /* williamr@2: * Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@2: * 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 williamr@2: * which accompanies this distribution, and is available williamr@2: * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: Defines screensaver plugin interface. williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: #ifndef SCREEN_SAVER_PLUGIN_H williamr@2: #define SCREEN_SAVER_PLUGIN_H williamr@2: williamr@2: // INCLUDES williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: #include // For TScPluginCaps williamr@2: williamr@2: // CONSTANTS williamr@2: williamr@2: // williamr@2: // Enumerations for screensaver indicators. williamr@2: // williamr@2: enum TScreensaverIndicatorIndex williamr@2: { williamr@2: EScreensaverIndicatorIndexNewMessages, williamr@2: EScreensaverIndicatorIndexNewMissedCalls, williamr@2: EScreensaverIndicatorIndexKeyGuardState, williamr@2: EScreensaverIndicatorIndexProfileName, williamr@2: EScreensaverIndicatorIndexChatMessage, williamr@2: EScreensaverIndicatorIndexEmail, williamr@2: EScreensaverIndicatorIndexVoicemail, williamr@2: EScreensaverIndicatorIndexAmPm williamr@2: }; williamr@2: williamr@2: williamr@2: // Screensaver indicator payload types williamr@2: enum TScreensaverPayloadType williamr@2: { williamr@2: EPayloadTypeUnknown = 0, williamr@2: EPayloadTypeInteger, // Icon and and number, or just icon (integer -1) williamr@2: EPayloadTypeText, // E.g. profile, AM/PM williamr@2: EPayloadTypeIcon // Icon only williamr@2: }; williamr@2: williamr@2: williamr@2: // Enumerations for possible partial mode types. williamr@2: enum TScreensaverPartialModeType williamr@2: { williamr@2: EPartialModeTypeDefault = 0, // Default partial mode (usually same as "most power saving"): williamr@2: EPartialModeTypeFull, // Partial mode with maximum number of colors. williamr@2: EPartialModeTypeReduced, williamr@2: EPartialModeTypeMostPowerSaving // Most power saving partial mode (usually only limited number of color available). williamr@2: }; williamr@2: williamr@2: williamr@2: // Events sent to plugin by Screensaver williamr@2: enum TScreensaverEvent williamr@2: { williamr@2: // Null event williamr@2: EScreensaverEventNothing = 0x00, williamr@2: // Screensaver starting, plugin should get Draw() calls soon, or williamr@2: // disable Screensaver timer to do it's own draw timing williamr@2: EScreensaverEventStarting, williamr@2: // Screensaver stopping, plugin should stop drawing williamr@2: EScreensaverEventStopping, williamr@2: // Resolution, orientation, window etc has changed williamr@2: EScreensaverEventDisplayChanged, williamr@2: // Plugin-requested timeout has elapsed. Plugins williamr@2: // can use this for e.g. running a certain williamr@2: // amount of time and suspending to normal williamr@2: // screen saver after the timeout occurs williamr@2: EScreensaverEventTimeout, williamr@2: // Screensaver is about to enter preview mode. Next start and stop events williamr@2: // will indicate preview start and end williamr@2: EScreensaverEventPreview williamr@2: }; williamr@2: williamr@2: williamr@2: // In Rel 3.0 TScPluginCaps is moved to ScreensaverpluginIntDef.hrh williamr@2: #if 0 williamr@2: // Screen saver plugin capabilities williamr@2: enum TScPluginCaps williamr@2: { williamr@2: // Plugin has no special capabilities williamr@2: EScpCapsNone = 0x00, williamr@2: // Plugin implements the configure function williamr@2: EScpCapsConfigure = 0x01, williamr@2: // Plugin wants to be notified when selected as the active screensaver williamr@2: EScpCapsSelectionNotification = 0x02, williamr@2: // Plugin wants to be notified when preview command is selected williamr@2: EScpCapsPreviewNotification = 0x04 williamr@2: }; williamr@2: #endif williamr@2: williamr@2: const TInt KMaxPayloadTextLength = 30; williamr@2: const TInt KScreensaverMaxPartialModes = 6; williamr@2: williamr@2: // Maximum time (secs) lights can be requested to be on williamr@2: const TInt KMaxLightsOnTime = 30; williamr@2: williamr@2: // MACROS williamr@2: williamr@2: // DATA TYPES williamr@2: williamr@2: class TScreensaverPartialMode williamr@2: { williamr@2: public: williamr@2: TScreensaverPartialModeType iType; // Id of this partial mode level. williamr@2: TInt iBpp; // How many bits per pixels is actually used williamr@2: // if this partial mode level is activated. williamr@2: }; williamr@2: williamr@2: williamr@2: // More or less obsolete - may or may not work. As a rule displays williamr@2: // seem to support only a single partial mode williamr@2: class TScreensaverColorModel williamr@2: { williamr@2: public: williamr@2: TInt iNumberOfPartialModes; // Number of partial mode levels supported williamr@2: // by current display hardware. williamr@2: TScreensaverPartialMode iPartialModes[KScreensaverMaxPartialModes]; // Array of williamr@2: // supported partial modes; williamr@2: TScreensaverPartialMode iSystemPartialMode; // Partial mode level that default williamr@2: // screensaver uses when drawing standard williamr@2: // screensaver bar. williamr@2: TInt16 iColors[8]; // Array of possible background colors williamr@2: // for standard screensaver bar in williamr@2: // single background color mode. williamr@2: TRgb iDarkGradient[6]; // Darker shades for gradient effect williamr@2: // in standard screensaver bar williamr@2: // (these are used only if there is enough williamr@2: // colors to draw gradient effect). williamr@2: TRgb iLightGradient[6]; // Lighter shades for gradient williamr@2: // effect in standard screensaver bar. williamr@2: }; williamr@2: williamr@2: williamr@2: // Screensaver indicator payload. For integer types williamr@2: class TIndicatorPayload williamr@2: { williamr@2: public: williamr@2: TScreensaverPayloadType iType; williamr@2: TInt iInteger; williamr@2: TBuf16 iText; williamr@2: TBool iIsDisplayed; // Read-only, cannot be set externally williamr@2: CGulIcon* iIcon; // Read-only, cannot be set externally williamr@2: williamr@2: public: williamr@2: TIndicatorPayload() williamr@2: : iType(EPayloadTypeUnknown), williamr@2: iInteger(-1), williamr@2: iIsDisplayed(EFalse), williamr@2: iIcon(NULL) williamr@2: {} williamr@2: }; williamr@2: williamr@2: williamr@2: class TScreensaverDisplayInfo williamr@2: { williamr@2: public: williamr@2: TInt iSize; // Size of struct, MUST be set by caller williamr@2: TRect iRect; // Rect of display area, may not be whole screen williamr@2: CCoeControl* iParent; // Parent control, has a window williamr@2: }; williamr@2: williamr@2: williamr@2: // FUNCTION PROTOTYPES williamr@2: williamr@2: // FORWARD DECLARATIONS williamr@2: williamr@2: // CLASS DECLARATION williamr@2: williamr@2: /** williamr@2: * This class defines plugin host interface. Plugin module uses williamr@2: * this interface for communicating with its host application. An instance williamr@2: * of this interface is given as a parameter to plugin module when williamr@2: * it is created. williamr@2: */ williamr@2: class MScreensaverPluginHost williamr@2: { williamr@2: public: williamr@2: /** williamr@2: * Sets screensaver application to use standard indicator view. williamr@2: * This is default mode for indicator drawing. williamr@2: */ williamr@2: virtual void UseStandardIndicators() = 0; williamr@2: williamr@2: /** williamr@2: * Notifies plugin host that plugin module is going to take care williamr@2: * of drawing indicator view and host shouldn't display them anymore. williamr@2: * If not overridden, normal screensaver will display when there williamr@2: * are indicators to show. Overriding the indicators does not mean they williamr@2: * _have_ to be drawn by the plugin, but that screensaver will not try to williamr@2: * do it. williamr@2: */ williamr@2: virtual void OverrideStandardIndicators() = 0; williamr@2: williamr@2: /** williamr@2: * Returns boolean value indicating whether standard indicator williamr@2: * drawing is used or not. williamr@2: * williamr@2: * @return ETrue if standard indicator drawing is used williamr@2: * EFalse if plugin module takes care of drawing indicators williamr@2: */ williamr@2: virtual TBool StandardIndicatorsUsed() const = 0; williamr@2: williamr@2: /** williamr@2: * Sets timeout value for refresh timer. Plugin module's draw williamr@2: * method is called every time when refresh timer expires. williamr@2: * williamr@2: * @param aValue Timeout value for refresh timer in microseconds. williamr@2: */ williamr@2: virtual void SetRefreshTimerValue(TInt aValue) = 0; williamr@2: williamr@2: /** williamr@2: * Returns the current timeout value of refresh timer. williamr@2: * williamr@2: * @return The current timeout value of refresh timer in microseconds. williamr@2: */ williamr@2: virtual TInt RefreshTimerValue() const = 0; williamr@2: williamr@2: /** williamr@2: * Returns payload associated with given screensaver indicator. williamr@2: * For list of supported indcicator indices see definition of williamr@2: * TScreensaverIndicatorIndex. Also see definition of williamr@2: * TIndicatorPayload class. williamr@2: * williamr@2: * @param aIndex Index of requested indicator. williamr@2: * @param aResult Structure where query results will be stored. williamr@2: * @return KErrNone if query was succesful. williamr@2: */ williamr@2: virtual TInt GetIndicatorPayload( williamr@2: TScreensaverIndicatorIndex aIndex, williamr@2: TIndicatorPayload& aResult) const = 0; williamr@2: williamr@2: /** williamr@2: * This method is used for activating so called screensaver partial mode. williamr@2: * Partial mode area specifies an area on the screen where screensaver williamr@2: * plugin module is going to draw during next refresh period. When partial williamr@2: * mode is activated the screen segments outside given area are williamr@2: * physically turned off to decrease power consumption. Whether partial williamr@2: * mode is supported or not depends on actual display hardware. williamr@2: * It is also possible that some devices support only limited number of williamr@2: * colors in partial mode area. williamr@2: * The actual size of the partial mode area may be restricted by the williamr@2: * display hardware, and differ from the size requested. Note that both williamr@2: * minimum and/or maximum size may be restricted. williamr@2: * If partial mode is not supported this method does nothing (that's williamr@2: * always the case in WINS environment). williamr@2: * williamr@2: * @param aStartRow Specifies the topmost pixel row of active williamr@2: * display area on the screen. williamr@2: * @param aEndRow Specifies the bottom pixel row of active display area. williamr@2: * williamr@2: * @param aMode Partial mode to be set. williamr@2: * williamr@2: * @return KErrNone if partial mode was successfully activated. williamr@2: * otherwise system wide error code. williamr@2: * @deprecated Should use the rect-version from S60 v3.0 on williamr@2: */ williamr@2: virtual TInt SetActiveDisplayArea( williamr@2: TInt aStartRow, williamr@2: TInt aEndRow, williamr@2: const TScreensaverPartialMode& aMode) = 0; williamr@2: williamr@2: /** williamr@2: * Cancels the effect of SetActiveDisplayArea method. The whole display area williamr@2: * is activated. williamr@2: */ williamr@2: virtual void ExitPartialMode() = 0; williamr@2: williamr@2: /** williamr@2: * Queries screensaver color in current environment (includes williamr@2: * partial modes supported by display hardware). williamr@2: * williamr@2: * @param aResult A structure for storing the results of the query. williamr@2: */ williamr@2: virtual const TScreensaverColorModel& GetColorModel() const = 0; williamr@2: williamr@2: /** williamr@2: * This method suspends plugin module drawing for given time. williamr@2: * During that time standard screensaver view is drawn. williamr@2: * williamr@2: * @param aTime Suspension time in microseconds. Values below williamr@2: * 500000 are rounded up to 500000. A negative value williamr@2: * suspends the plugin indefinitely. williamr@2: */ williamr@2: virtual void Suspend(TInt aTime) = 0; williamr@2: williamr@2: /** williamr@2: * With this method the plugin may request screen backlight to be williamr@2: * turned on or off. williamr@2: * williamr@2: * @param aSecs Desired time in seconds the screen backlight should be williamr@2: * turned on (1 - 30). Less than 1 will turn the lights off, williamr@2: * more than 30 will be treated as 30. The plugin host has the williamr@2: * final control over the lights, so time may be less than williamr@2: * requested, or the lights may be switched off even without williamr@2: * request before the time is up. williamr@2: */ williamr@2: virtual void RequestLights(TInt aSecs) = 0; williamr@2: williamr@2: /** williamr@2: * Plugin may use this function to enquire display properties. Should williamr@2: * be called e.g. in response to EScreensaverEventDisplayChanged to williamr@2: * retrieve the new information. williamr@2: * williamr@2: * @param aDisplayInfo Struct to receive the display information. NOTE williamr@2: * that iSize must be set by the caller. williamr@2: * williamr@2: */ williamr@2: virtual TInt DisplayInfo(TScreensaverDisplayInfo* aDisplayInfo) = 0; williamr@2: williamr@2: /** williamr@2: * This method is used for activating so called screensaver partial mode. williamr@2: * Partial mode area specifies an area on the screen where screensaver williamr@2: * plugin module is going to draw during next refresh period. When partial williamr@2: * mode is activated the screen segments outside given area are williamr@2: * physically turned off to decrease power consumption. Whether partial williamr@2: * mode is supported or not depends on actual display hardware. williamr@2: * It is also possible that some devices support only limited number of williamr@2: * colors in partial mode area. williamr@2: * The actual size of the partial mode area may be restricted by the williamr@2: * display hardware, and differ from the size requested. Note that both williamr@2: * minimum and/or maximum size may be restricted. williamr@2: * If partial mode is not supported this method does nothing (that's williamr@2: * always the case in WINS environment). williamr@2: * williamr@2: * @param aRect Specifies the active area on the screen. Parts outside williamr@2: * this area will not be visible. Note that x-dimension williamr@2: * needs to be set, even if it's not currently used williamr@2: * williamr@2: * @param aMode Partial mode to be set. williamr@2: * williamr@2: * @return KErrNone if partial mode was successfully activated. williamr@2: * otherwise system wide error code. williamr@2: * @since S60 v3.0 williamr@2: */ williamr@2: virtual TInt SetActiveDisplayArea(TRect& aRect, const TScreensaverPartialMode& aMode) = 0; williamr@2: williamr@2: /** williamr@2: * With this method the plugin may request Draw() timer to be williamr@2: * turned on or off. When on (the default) the plugins Draw() function williamr@2: * is called in intervals specified in SetRefreshTimerValue(). williamr@2: * williamr@2: * @param aOn Specifies whether the refresh timer is used to initiate williamr@2: * Draw() calls. williamr@2: */ williamr@2: virtual void UseRefreshTimer(TBool aOn = ETrue) = 0; williamr@2: williamr@2: /** williamr@2: * With this method the plugin may request a one-shot timeout event williamr@2: * (EScreensaverEventTimeout) after the specified amount of seconds williamr@2: * has passed. williamr@2: * If the plugin only wants to be displayed for a certain time, this williamr@2: * can be used instead of defining a timer in the plugin. Note that the williamr@2: * maximum time is about 35 minutes (TTimeIntervalMicroSeconds32). williamr@2: * If the screensaver is stopped before the time has passed, the williamr@2: * timer will be canceled and callback not issued. The timer is also williamr@2: * cancelled after the timeout has occurred. New timeout requests also williamr@2: * cancel any pending timeouts before issuing a new one. A time value williamr@2: * of 0 just cancels a pending timeout. williamr@2: * williamr@2: * @param aSecs Desired time in seconds after which a timeout callback williamr@2: * event should be issued. williamr@2: */ williamr@2: virtual void RequestTimeout(TInt aSecs) = 0; williamr@2: williamr@2: /** williamr@2: * With this method the plugin can revert to the default screensaver. williamr@2: * The plugin will be unloaded, and not used any more until the williamr@2: * user re-selects the plugin to be the active screensaver. williamr@2: * Should be used when the plugin encounters an unrecoverable error, williamr@2: * such as a missing file or expired DRM, and will not be able to run williamr@2: * any more. williamr@2: * NOTE: A plugin should not expect any events after calling this williamr@2: * function. williamr@2: */ williamr@2: virtual void RevertToDefaultSaver() = 0; williamr@2: }; williamr@2: williamr@2: williamr@2: /** williamr@2: * The base class for screensaver plugin modules. Every plugin module williamr@2: * must inherit and implement this class. williamr@2: */ williamr@2: class MScreensaverPlugin williamr@2: { williamr@2: public: williamr@2: /** williamr@2: * Virtual desctructor. williamr@2: */ williamr@2: virtual ~MScreensaverPlugin() {} williamr@2: williamr@2: /** williamr@2: * Used to initialize the plugin module after creation. williamr@2: * Name() function may be called without the plugin being initialized, williamr@2: * to enable name query from modules that are not plugin hosts. williamr@2: * williamr@2: * @param aHost Screensaver plugin host. williamr@2: * @return KErrNone if everything went ok. Otherwise williamr@2: * system wide error code. williamr@2: */ williamr@2: virtual TInt InitializeL(MScreensaverPluginHost *aHost) = 0; williamr@2: williamr@2: /** williamr@2: * When a plugin module is active this method is called every time williamr@2: * when refresh timer expires in screensaver application. williamr@2: * williamr@2: * @param aGc Graphics context for plugin module to draw to. williamr@2: * @return KErrNone if everything went ok. Otherwise williamr@2: * system wide error code (doesn't have any effect in williamr@2: * current version). williamr@2: */ williamr@2: virtual TInt Draw(CWindowGc& aGc) = 0; williamr@2: williamr@2: /** williamr@2: * Returns the name of plugin module. Returned name is displayed in williamr@2: * the list of installed plugin modules in Themes application. williamr@2: * If this function returns an empty name (KNullDesC), displayed name is williamr@2: * taken from ECom registration resource. williamr@2: * williamr@2: * @return Descriptor containing the name of the plugin module. williamr@2: */ williamr@2: virtual const TDesC16& Name() const = 0; williamr@2: williamr@2: /** williamr@2: * Handler function for screensaver events. williamr@2: * williamr@2: * @param aEvent Event to be handled. williamr@2: * @param aData Data related to the event. To be decided on a case-by-case williamr@2: * basis. williamr@2: * williamr@2: * @return KErrNone if OK, otherwise an error code. williamr@2: */ williamr@2: virtual TInt HandleScreensaverEventL( williamr@2: TScreensaverEvent aEvent, williamr@2: TAny* aData) = 0; williamr@2: williamr@2: /** williamr@2: * Screensaver plugin capabilities query. The capabilitities williamr@2: * reveal which functions the plugin implements, that can be williamr@2: * used by calling PluginFunction(). williamr@2: * williamr@2: * @return Bit mask of plugin capabilities. williamr@2: * williamr@2: * @note Capabilites need to be defined as opaque_data in ECom plugin williamr@2: * registration file as well. williamr@2: */ williamr@2: virtual TInt Capabilities() { return EScpCapsNone; } williamr@2: williamr@2: /** williamr@2: * Screensaver plugin function method. Only the functions williamr@2: * returned by Capabilities() can be used, and only one williamr@2: * function at a time. williamr@2: * williamr@2: * @paran aFunction williamr@2: * @param aParam Parameters to the function. TBD function-by-function. williamr@2: * williamr@2: * @return System wide error code. KErrNone on success. williamr@2: */ williamr@2: virtual TInt PluginFunction( williamr@2: TScPluginCaps /*aFunction*/, williamr@2: TAny* /*aParam*/) williamr@2: { williamr@2: return KErrNone; williamr@2: } williamr@2: }; williamr@2: williamr@2: williamr@2: #endif // SCREEN_SAVER_PLUGIN_H williamr@2: williamr@2: // End of file.