Applicability

This article examines how to build screensavers for S60 3rd Edition devices; if you want to create a screensaver for S60 2nd Edition, there's a good example here: Series 60 Platform 2nd Edition: Screen Saver Example, from Forum Nokia.

Creating the project

The first thing you need to do is create .mmp and bld.inf files for the project. In our example code, we have:

bld.inf file

It's important to specify the DEFAULT GCCE directive: it instructs the build system to use the free GCC compiler instead of the commercial RCVT 2.2. As you're probably building this with CodeWarrior Personal or Carbide.c++ Express/Developer, you'll what to use GCC because it's the only compiler available.

ExampleScreenServer.mmp file

Some points worth noting are:

• Setting the TARGETTYPE directive to PLUGIN: this is new for S60 3rd Edition and specifies that you're building an ECom plug-in.
• 0x10009D8D is the ECom dll Recognition UID, while 0x01EF299A is our unique dll UID.
• The CAPABILITY is also new to S60 3rd Edition, due to the Platform Security feature. Unfortunately, due to the ReadDeviceData and WriteDeviceData capabilities requirement, you won't be able to write a screensaver without having a Developer Certificate bound to an ACS Publisher ID, because only those DevCerts have the extended capability set required by the screensaver plugin framework.

Plug-in registration resource file

As screensavers are now ECom plug-ins, you'll need to create a registration resource file, called ExampleScreenSaver.rss, that looks like this:

ExampleScreenSaver.rss file

Important points in this file:

• dll_uid and implementation_uid are our dll UID. interface_uid comes straight from the screensaverpluginintdef.hrh file and identifies this plugin as a plugin to the screensaver engine.
• display_name is the friendly name which will be displayed in the device's Themes application when you configure the current theme to use your screensaver (see more details below).

The source code

You need to inherit your screensaver class from CScreensaverPluginInterfaceDefinition, which implements some ECom construction/destruction code and in turn inherits from MScreensaverPlugin, which defines the actual interface you will implement in order to make your screensaver to perform the actual job of, well, saving the screen :)

Here's like the header file will look like:

ExampleScreenSaver.h file

The important functions you need to implement in order to have real funcionality in your plugin are:

• InitializeL(MScreensaverPluginHost *aHost): This is will be called once, when the plugin is initialized for the first time, and it will pass you a pointer to the plugin host (MScreensaverPluginHost class), that you can use for important things like: requesting the backlight to be turn on or off, setting the timer refresh value, setting the active display area (so you save power only activating screen areas where you're actually drawing something), among others.
• Draw(CWindowGc& aGc);: This will be called each time the refresh timer expires, passing you a CWindowGc graphics context that you'll use to perform the actual drawing of your fancy animations.
• HandleScreensaverEventL(TScreensaverEvent aEvent, TAny* aData);: Here you can handle some screensaver events that interest you. See the TScreensaverEvent class documentation in the S60 3rd Edition SDK for more information.

Here are the implementations of these functions in our example:

ExampleScreenSaver.cpp excerpt

The last thing you need to do is to export a function that provides the mapping between the UID of the implementation and its respective creation function. This is pretty standard ECom code and it's documented in our ImplementationProxy.cpp.

Building, packaging and installing the example

That's the easy part: if you're in Carbide.c++ or CodeWarrior, just perform a full rebuild of the project. If you're building it from the command line, just cd to the group folder and type the command:

abld build gcce urel

This will build ExampleScreenSaver.rsc and ExampleScreenSaver.dll files, which will be copied to \resource\plugins and \sys\bin\ folders in the device, respectively.

Now we're going to create the .sis file that will be installed on the phone. Again, if you're using an Symbian aware IDE, the .sis file will be built (and signed, depending on your configuration) for you automatically. Otherwise, you must cd to the sis folder and build the package, by typing

makesis ExampleScreenSaver.pkg

which will build a ExampleScreenSaver.sis. Prior installing, you need to sign it by using the following command

signsis ExampleScreenSaver.sis ExampleScreenSaver.sisx your_cert_file.cer your_key_file.key

where your_cert_file.cer is your Developer Certificate, see the "Downloads and additional information" section for more information, and your_key_file.key is the private key file for this certificate.

Installing your screensaver on the device is easy: just transfer it via Bluetooth, USB (using Nokia PC Suite) or downloading it over the Internet.

Your screensaver in action

The following series of screenshots shows you how to activate your screen phone within the Themes application on a Nokia 3250 device:

Go to "My own"

Click on "Themes"

Select the current theme and choose "Edit" from the "Options" menu.

Configure your screensaver as the default for the current theme

Here you can see our little screensaver running on a Nokia 3250 device:

Well, that's pretty much it. All you need to do is: build your screensaver as an ECom plugin, derive from CScreensaverPluginInterfaceDefinition class and implement the virtual methods from MScreensaverPlugin, build the whole thing, copy generated files to the right locations on the device, and you're done.

If you have any questions to ask or corrections to make, just post a comment here on Daniels blog Rawsocket.org

Downloads and additional information

• Download the Example screensaver source code here
• Download the Example screensaver source code as a Carbide.C++ project here
• Carbide.c++ project may not work at the first try, because there are some hardcoded paths in the project properties, but these should be easy to fix to fit your own paths
• The .sis and .sisx files are signed with my own Developer Certificate, so they won't install in your test device. If you need to know how to obtain a Developer Certificate for your screensaver, you must check the Symbian Developer Certificate web site

Daniel Rocha
Forum Nokia Technology Expert
Rawsocket.org