MScreensaverPluginHost Class Reference

#include <mw/screensaverplugin.h>

class MScreensaverPluginHost
Public Member Functions
pure virtual TInt DisplayInfo(TScreensaverDisplayInfo *)
pure virtual voidExitPartialMode()
pure virtual const TScreensaverColorModel &GetColorModel()
pure virtual TInt GetIndicatorPayload(TScreensaverIndicatorIndex, TIndicatorPayload &)
pure virtual voidOverrideStandardIndicators()
pure virtual TInt RefreshTimerValue()
pure virtual voidRequestLights(TInt)
pure virtual voidRequestTimeout(TInt)
pure virtual voidRevertToDefaultSaver()
pure virtual TInt SetActiveDisplayArea(TInt, TInt, const TScreensaverPartialMode &)
pure virtual TInt SetActiveDisplayArea(TRect &, const TScreensaverPartialMode &)
pure virtual voidSetRefreshTimerValue(TInt)
pure virtual TBool StandardIndicatorsUsed()
pure virtual voidSuspend(TInt)
pure virtual voidUseRefreshTimer(TBool)
pure virtual voidUseStandardIndicators()

Detailed Description

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.

Member Function Documentation

DisplayInfo ( TScreensaverDisplayInfo * )

TInt DisplayInfo(TScreensaverDisplayInfo *aDisplayInfo)[pure virtual]

Plugin may use this function to enquire display properties. Should be called e.g. in response to EScreensaverEventDisplayChanged to retrieve the new information.

ParameterDescription
aDisplayInfoStruct to receive the display information. NOTE that iSize must be set by the caller.

ExitPartialMode ( )

voidExitPartialMode()[pure virtual]

Cancels the effect of SetActiveDisplayArea method. The whole display area is activated.

GetColorModel ( )

const TScreensaverColorModel &GetColorModel()const [pure virtual]

Queries screensaver color in current environment (includes partial modes supported by display hardware).

GetIndicatorPayload ( TScreensaverIndicatorIndex, TIndicatorPayload & )

TInt GetIndicatorPayload(TScreensaverIndicatorIndexaIndex,
TIndicatorPayload &aResult
)const [pure virtual]

Returns payload associated with given screensaver indicator. For list of supported indcicator indices see definition of TScreensaverIndicatorIndex. Also see definition of TIndicatorPayload class.

ParameterDescription
aIndexIndex of requested indicator.
aResultStructure where query results will be stored.

Returns: KErrNone if query was succesful.

OverrideStandardIndicators ( )

voidOverrideStandardIndicators()[pure virtual]

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.

RefreshTimerValue ( )

TInt RefreshTimerValue()const [pure virtual]

Returns the current timeout value of refresh timer.

Returns: The current timeout value of refresh timer in microseconds.

RequestLights ( TInt )

voidRequestLights(TIntaSecs)[pure virtual]

With this method the plugin may request screen backlight to be turned on or off.

ParameterDescription
aSecsDesired 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.

RequestTimeout ( TInt )

voidRequestTimeout(TIntaSecs)[pure virtual]

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.

ParameterDescription
aSecsDesired time in seconds after which a timeout callback event should be issued.

RevertToDefaultSaver ( )

voidRevertToDefaultSaver()[pure virtual]

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.

SetActiveDisplayArea ( TInt, TInt, const TScreensaverPartialMode & )

TInt SetActiveDisplayArea(TIntaStartRow,
TIntaEndRow,
const TScreensaverPartialMode &aMode
)[pure virtual]

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).

DeprecatedShould use the rect-version from S60 v3.0 on

ParameterDescription
aStartRowSpecifies the topmost pixel row of active display area on the screen.
aEndRowSpecifies the bottom pixel row of active display area.
aModePartial mode to be set.

Returns: KErrNone if partial mode was successfully activated. otherwise system wide error code.

SetActiveDisplayArea ( TRect &, const TScreensaverPartialMode & )

TInt SetActiveDisplayArea(TRect &aRect,
const TScreensaverPartialMode &aMode
)[pure virtual]

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).

Since
S60 v3.0
ParameterDescription
aRectSpecifies 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
aModePartial mode to be set.

Returns: KErrNone if partial mode was successfully activated. otherwise system wide error code.

SetRefreshTimerValue ( TInt )

voidSetRefreshTimerValue(TIntaValue)[pure virtual]

Sets timeout value for refresh timer. Plugin module's draw method is called every time when refresh timer expires.

ParameterDescription
aValueTimeout value for refresh timer in microseconds.

StandardIndicatorsUsed ( )

TBool StandardIndicatorsUsed()const [pure virtual]

Returns boolean value indicating whether standard indicator drawing is used or not.

Returns: ETrue if standard indicator drawing is used EFalse if plugin module takes care of drawing indicators

Suspend ( TInt )

voidSuspend(TIntaTime)[pure virtual]

This method suspends plugin module drawing for given time. During that time standard screensaver view is drawn.

ParameterDescription
aTimeSuspension time in microseconds. Values below 500000 are rounded up to 500000. A negative value suspends the plugin indefinitely.

UseRefreshTimer ( TBool )

voidUseRefreshTimer(TBoolaOn = ETrue)[pure virtual]

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().

ParameterDescription
aOnSpecifies whether the refresh timer is used to initiate Draw() calls.

UseStandardIndicators ( )

voidUseStandardIndicators()[pure virtual]

Sets screensaver application to use standard indicator view. This is default mode for indicator drawing.