Screen Saver API: API description

Screensaver plug-in architecture is based on two main classes. The Screensaver application (and all underlying services) is represented by the abstract interface MScreensaverPluginHost. Screensaver plug-in objects are ECom-plug-ins, implementing the MScreensaverPlugin interface. The plug-in only need to provide code for drawing the custom graphical object. MScreensaverPluginHost provides the default screensaver behavior and data.

There is a two-way communication between the Screensaver plug-in module and the host. The host knows when to activate Screensaver and update the screen. It calls the Draw() function of the plug-in module with graphics context as a parameter. The plug-in module can adjust certain attributes through its host interface such as timeout value of the refresh timer.

Plug-in host (MScreensaverPluginHost)

The plug-in host is represented by interface MScreensaverPluginHost. Plug-ins receive a pointer to the host during initialization. The host has the following responsibilities:

• creating, initializing, owning and deleting the plug-in
• providing data for Screensaver indicators (new messages, missed calls, etc.)
• providing display information
• activating partial display mode (power saving)
• redrawing the plug-in object on a regular basis
• sending Screensaver events to the currently active plug-in

Plug-in (MScreensaverPlugin)

Screensaver plug-ins implement the MScreensaverPlugin interface.

Plug-ins are installed as ECom plug-ins, implementing the KCScreensaverPluginInterfaceDefinitionUid (0x101F87F8) interface. For convenience reasons, the class CScreensaverPluginInterfaceDefinition is provided. CScreensaverPluginInterfaceDefinition derives from MScreenSaverPlugin and implements ECom plug-in instantiation. Concrete plug-in implementations should derive from CScreensaverPluginInterfaceDefinition.

Plug-ins implement specific functions in the method PluginFunction(). The host invokes a given function if the plug-in capabilities indicate the support for that particular function. Plug-ins advertise their capabilities by implementing Capabilities(). The same capabilities also need to be defined in the ECom registration file as well.

Preview mode

Screensavers may be run in preview mode. Preview displays the screensaver shortly, for 10 seconds or until the first user activity. The Themes application calls the plug-in function EScpCapsPreviewNotification before activating preview. The plug-in must have the EScpCapsPreviewNotification capability to receive this notification.

Partial display mode

For power saving purposes, partial display mode may be available. Availability of this mode depends on the display hardware.

It is possible that the display hardware supports only a limited number of colors when the partial mode is activated. The host provides a method for the plug-in modules to query a color model supported by the display hardware.

The maximum amount of lines active in partial display mode is display specific. There is no function to query the supported value. See Limitations of the API for limitations.

Plug-ins should always use partial display mode. See Section Power saving considerations.

Use cases

1. Implementing custom plug-in
2. Overriding standard indicators
3. Getting indicator data
4. Setting refresh timer
5. Disabling refresh
6. Querying display info
7. Configuring the plug-in
8. Suspending drawing
9. Entering partial display mode
10. Exiting partial display mode

API class structure

Figure 2 shows the main classes of Screen Saver API. Minor data structures are omitted for clarity.

The main classes are MScreenSaverPluginHost and MScreenSaverPlugin, representing the host application and the screensaver plug-in, respectively.

The class CScreenSaverPluginInterfaceDefinition is the convenience class, to be used as a base to the actual screen saver plug-in. It uses REcomSession to load the plug-in.

CExampleScreenSaverPlugin is included for clarity. It is not part of Screen Saver API.