Over the past month or so I’ve been working on a number of projects involving Windows Mobile Widgets. If you aren’t familiar with widgets they are essentially a mini-application published as a zip file containing html, js, css and images. They are similar to Windows Vista/7 gadgets; in fact so much so that you can use exactly the same code to produce both a widget and desktop gadget. In this post I’ll go through creating a basic widget, including a couple of tricks that can help you build and debug your widgets.
We will of course start off with the canonical Hello World widget and for the most part I’m going to be working in Visual Studio 2010. That’s right, you can build and debug* your widgets from within Visual Studio 2010, which makes it the only form of Windows Mobile development you can currently do with the beta.
Let’s start by building up the necessary project structure for your widget. From the File menu, select New –> Web Site, then select the Empty Web Site project template from under either the C# or VB node. Since you are going to be writing javascript it doesn’t matter what language you select. By default this will create a new project with just a web.config file – this file is not required for your Windows Mobile widget but does enable desktop debugging so leave it in the project. Next, add a new HTML document to your project (Add New Item –> C#/VB –> HTML Page). I typically call this Main.htm as you normally only have a single htm page within your widget that contains all the markup for your widget but the name isn’t important. Modify the html to include a title and some content between the body tags. For example:
<html >http://www.w3.org/1999/xhtml">
<head>
<title>Hello Widget</title>
</head>
<body>
Hello Widget World!
</body>
</html>
When you install your widget the installer needs to locate the main html page of your widget, along with other information about your widget such as the author, title and description of the widget. This is located in a config.xml file. Add a new xml file called config.xml to your project (Add New Item –> C#/VB –> XML File) – the name of this file is important. Add, and then modify to suit yourself, the following to the config.xml file.
<?xml version="1.0" encoding="utf-8" ?>
<widget >http://www.w3.org/ns/widgets"
id="http://www.builttoroam.com/hellowidgetworld"
version="0.1">
<name>Hello Widget World</name>
<description>This is a sample widget that says Hi to the world!</description>
<author href="http://www.builttoroam.com" email="[email protected]">
Built to Roam Widget Development Team
</author>
<content src="Main.htm" type="text/html"/>
</widget>
You now have the minimum requirements for a Windows Mobile widget. If you press F5 to run this project in Visual Studio you will see the Main.htm web page display (if not, you may have to navigate to this page, or Set [it] as Start Page. To run your widget on a device (or emulator) there are a few more steps involved.
The first thing you need to do is to actually zip up your widget project into a .widget file. This is essentially just a zip file, renamed with the .widget extension. As you don’t want to be doing this manually every time you make a change I created a simple batch file (yeh I know, super old school) that simply calls 7zip (free download) to zip up the relevant files.
—————–
Build.bat
—————–cd .HelloWorld
del ..helloworld.widget /Q
..7za.exe a -tzip ..helloworld.widget -r0 @..files.txt
copy ..helloworld.widget ..helloworld.widget.zip
pause
Place this batch file in the parent folder of your Hello World widget – you don’t want to mess up your project folder with build files. You need to download and copy the 7zip executable into this folder and you need to create a file called files.txt – this contains a list of files to include in your widget.
—————–
Files.txt
—————–config.xml
Main.htm
Running this batch file will create two output files: helloworld.widget and helloworld.widget.zip. The former is a .widget file that you can copy to your device and click on to install. The latter is created just in case you want to inspect the zip file to ensure all the right files are being packaged – there is nothing worse than trying to track down a javascript issue, only to discover one of the files isn’t being correctly added to the package.
Ok, so down to business, lets get this widget to run on the emulator/device. If you are using an emulator then you can simply cradle the emulator using WMDC, copy the file across to the device using File Explorer and then click on the copied file to run the widget installer. This will automatically run the widget when installation is complete. If you want to run your widget on a real device there are some additional steps. By default the widget installer is not associated with the .widget file extension. In order to get your widget to install by clicking on it, you need to create this association by modifying the registry on the device to include the following values:
[HKEY_CLASSES_ROOTriapp] "EditFlags"=dword:00010000
[HKEY_CLASSES_ROOTriappShellOpenCommand] @="wmwidgetinstaller.exe %1"
You can do this using either Remote Registry Editor (external tool that ships with Visual Studio 2008), Pocket Controller PC or another third party registry editing tool. Note that on most devices the HKEY_CLASSES_ROOTriapp key already exists but the HKEY_CLASSES_ROOTriappShellOpenCommand key will need to be created. Also note that the @ in the second line corresponds to the “default” value for the key – this means that depending on your editing tool you should either leave the name component empty or use the word Default.
Once you have added these registry keys to your device, clicking on the .widget file should run the installer – if not, it is likely that the registry keys are not correct, or that the wmwidgetinstaller.exe executable can’t be located. Again, once installation is complete your widget should automatically run displaying similar to the following:
Note that the Title in the Main.htm file is used to populate the widget title bar and that the default Exit button and menu has been created.
Creating your first widget is as simple as that. In fact you could submit this widget, in its current form to Windows Mobile Marketplace as it conforms to all the necessary requirements for certification.
*Build and Debug is limited to desktop debugging only. You still need to deploy to an emulator and/or a real device in order to ensure your widget is going to work correctly.