--- a/epoc32/include/mw/screensaverplugin.h Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/mw/screensaverplugin.h Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,484 @@
-screensaverplugin.h
+/*
+* 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.