Ioan Lazarciuc's Weblog » Beginnings

Creating a Windows Vista Sidebar Gadget

cretz — Wed, 31 Oct 2007 23:39:20 +0000

I think this post should begin with a few sayings: "Never say never", "When hell freezes over", "Once in a blue moon", "I would rather shoot myself", "Over my dead body", but the best suited one for this post comes from Ciprian Jichici, the Microsoft Regional Director from Romania: "In this line of business, there's no room for talibanisms".

I will be talking about developing Sidebar gadgets. These Sidebar gadgets are small applications that offer useful information, do frequent tasks more easily, or just offer a good laugh for the Windows Vista user. Until recently, I've been trying very hard to stay away from technologies like JavaScipt and PHP because it is my personal opinion that they fall miles away from a proper programming language (C#, VB.NET, C++). I won't go into the details of why I dislike these languages.

Microsoft launched a competition for Sidebar gadget developers with some very nice prizes. The competition takes place in several countries, including Romania. So, I decided to participate. The only problem is that the only fully supported programming model for developing Sidebar gadgets is HTML application + JavaScript.

I've spent several weeks trying to find another way to develop gadgets. I found out that by using XBAP(XAML Browser Application), one can obtain a gadget that can be programmed using WPF (Windows Presentation Foundation) - more information on that here. There are real drawbacks to this approach: no flyouts, no access to the gadget settings API, no access to the Gadget API, which are all accessible from JavaScript. Also, Silverlight can be used to create a Sidebar gadget. While this significantly improves access to the JavaScipt API's, there are still drawbacks. More on creating gadgets using Silverlight here and here. The decision was tough to make, but unavoidable: JavaScript won, due to the fact that my gadget needed settings, flyouts and a standard installation experience (no dependencies on Silverlight).

Now the phrase "there's no room for talibanisms" makes sense: you never know when you will be forced to do things you don't particularly enjoy (such as JavaScript). All these being said, I shall move on the the task at hand. The best place to start when learning to develop gadgets is the Overview Site from Microsoft. The ABCs of developing gadgets are covered there. Tim Heuer has made a project template for Visual Studio in order to help people getting started in gadget development. The template is available here.

From here, the purpose of the new gadget has to be formulated. It can be as simple as "Hello World", or as complicated as interfacing with your Windows Media Player. The first step is to go over to the Live Gallery dedicated to Vista Sidebar Gadgets and have a look at what's out there. I settled on creating a gadget that would display the postal code (ZIP) for a given address from Romania. I chose this because I had been searching too many times for postal codes on websites. The gadget is a very welcomed shortcut. The data is to be obtained from one of the many sites that offer Romanian ZIP search. The only requirement is to be able to pass the search string as a query string directly in the URL to keep things simple. I settled on http://coduri-postale.ro.

The next step is to get up to date with some basic JavaScript: HTML DOM, CSS, Regular Expressions, the Sidebar Gadget API. Now it's time to take a look at the structure generated by the Visual Studio template.

A Sidebar gadget has at least 2 files: a HTML file which defines the look of the gadget and an XML file which defines information about the gadget such as the name, version, author, description. However, usually, a gadget contains more files such as: HTML files for various flyouts, JS files for the JavaScript functions that are called and CSS files for defining styles in a civilized manner.

The main file of the gadget is called by default, gadget.html. It contains 2 div tags, one with the ID "docked" and one "undocked". As you can imagine, one holds the contents while docked, the other while undocked. In JavaScript, the events System.Gadget.onDock and System.Gadget.onUndock are defined in order to handle the switch between modes. The event handlers are set in the Init function found in the utils.js file.

<body onload="init();">

 <div id="docked">

 Gadget Docked

 <br/>

 <input type="button" value="Flyout" onclick="flyout();" />

 div>

 <div id="undocked">

 Gadget Undocked

 div>

body>

The gadget.xml file contains the name, author, description of the gadget, but also it specifies the main source file for the gadget in the node from . The file also contains the path to an icon which represents the gadget and an image to display (defaultImage in ) while dragging the gadget (only when dragging it from the "Add Gadgets" window).

xml version="1.0" encoding="utf-8" ?>

<gadget>

 <name>[ YOUR GADGET NAME ]name>

 <namespace>[YOUR CUSTOM NAMESPACE]namespace>

 <version>1.0.0.0version>

 <author name="[AUTHOR NAME]">

 <info url="[URL FOR INFO]" />

 <logo src="logo.png" />

 author>

 <copyright>© [COPYRIGHT INFO]copyright>

 <description>[YOUR DESCRIPTION]description>

 <icons>

 <icon height="48" width="48" src="icon.png" />

 icons>

 <hosts>

 <host name="sidebar">

 <base type="HTML" apiVersion="1.0.0" src="gadget.html" />

 <permissions>Fullpermissions>

 <platform minPlatformVersion="1.0" />

 <defaultImage src="drag.png" />

 host>

 hosts>

gadget>

The size of the gadget (or the flyout) can be changed by changing the size of the body of the html, either from CSS, HTML or JavaScript. If the gadget has two different size when docked or undocked, then one should change the size of the html body using JavaScript in the event handlers for the Dock and Undock events. The utils.js file contains a function ShowOrHide that takes an HTML element and a boolean and hides(or shows) the element, along with any of its children. The function flyout() from utils.js creates a new flyout by specifying the file property of System.Gadget.Flyout, and then setting show to true.

One can specify a settings HTML page by setting the settingsUI property of System.Gadget. The settings page cannot be opened programmatically, only by the user's action (the settings button that the runtime creates for each gadget that supports settings automatically). The event onSettingsClosed is raised whenever the settings page closes, either by pressing ok or cancel. The onSettingsClosing event can be handled in order to save settings. It's handlers have a parameter which has a property closeAction. If this property is event.Action.commit, where event is the parameter passed to the handler, then the ok button was pressed. In order to write settings, one calls the write method and for reading, the read method of System.Gadget.Settings.

SystemGadget.Settings.write("settingname",settingvalue);

System.Gadget.Settings.read("settingname");

When loading the settings page, it is the responsibility of the page (through JavaScript) to read its settings and update the fields in the settings html in order to reflect the current values of the settings. This is the purpose of the loadSettings function available in the settings.html file from the template.

This covers all the main aspects in the template for Sidebar gadgets. Another very useful thing to master is the XMLHttpRequest object in JavaScript. This is used in order to obtain the contents of another page (any webpage) asynchronously. This object is part of the AJAX web programming paradigm. Unfortunately, like CSS, HTML and JavaScript, each browser has its own way of looking at this object. There are at least 3 methods of constructing the XMLHttpRequest object, the bad news being that only one will work for a browser. So you have to try each method, catching exceptions along the way, until the object creation does not throw an exception or all the methods are exhausted, in the worst case. The good news is that for Sidebar gadgets, only Internet Explorer has to be taken into account. Sample code for creating the request object can be found below.

var xmlhttp = false;

try

 xmlhttp = new ActiveXObject("Msxml2.XMLHTTP");

 catch (e)

 xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");

The simplest usage scenario involves using the GET http verb in order to simply retrieve a page.

var ret;

xmlhttp.open("GET", url, true);

xmlhttp.onreadystatechange=function()

 if (xmlhttp.readyState==4)

 if (xmlhttp.status==200)

 ret=xmlhttp.responseText;

 //do something with ret;

 else

 //anything other than success can

 //be treated as an error

xmlhttp.send(null);

The open method takes as parameters the HTTP verb (GET, POST, etc.), the URL for the page to fetch and a boolean that when set to true allows JavaScript to launch the request asynchronously, meaning it keeps on processing the code. If set to false, the execution of JavaScript code stops until the data is fetched or an error occurs. The send method sends the request to the specified web server. If working asynchronously, you can define an event handler for the onreadystatechange event defined by the XMLHttpRequest object to monitor progress. The readyState property indicates the state of the object (4 mean request completed, response available). The status property holds the HTTP status of the response, 200 meaning OK. The actual response can be accessed using the responseText property. When fetching an ordinary webpage, this string will contain the actual HTML of the page.

Sometimes it's useful to do a POST request in order to get to a page that cannot be accessed through an URL. For example for filling out a form in order to obtain some search results (that are not accessible through URL query string parameters). Besides changing the GET into POST, you must also specify the form parameters just as you would query string parameters,only without "?" ('par1=val1&par2=val2') and pass the resulted string to the send method of the request object. Also, some HTTP header have to be set: Content-Type to "application/x-www-form-urlencoded" in order to pass the parameters of the form, Content-length to the length of the string of parameters and Connection to "close" in order to specify that the connection is to be closed once the response is obtained.

xmlhttp.open("POST", url, false);

xmlhttp.setRequestHeader("Content-type", "application/x-www-form-urlencoded");

xmlhttp.setRequestHeader("Content-length", parameters.length);

xmlhttp.setRequestHeader("Connection", "close");

var ret;

xmlhttp.onreadystatechange=function()

 if (xmlhttp.readyState==4)

 if (xmlhttp.status==200)

 ret=xmlhttp.responseText;

 //do something with ret

 else

 // error occurred

xmlhttp.send(parameters);

This concludes a basic, but comprehensive article on developing Sidebar gadgets. Even though I was not very specific, I hope you will have no problem stating your own gadget after reading this post.

Currently I have developed 2 gadgets: one to display postal codes from Romania and one to search for schedule and route information for urban transportation in a few major cities from Romania. The source code for these gadget can be obtained by installing them, then by getting the contents of the "C:\Users\%YourUser%\AppData\Local\Microsoft\Windows Sidebar\Gadgets\GadgetName" folder. Also, these two gadgets are competing in the Romanian edition of Gadget Competition. You can download and vote for my gadgets by clicking the two screenshots below.

Microsoft Student Partner

cretz — Mon, 10 Sep 2007 22:15:09 +0000

Yesterday I received the invitation email to create an account on the MSP website. This means I got accepted in the program It also means I have to keep up working on making Microsoft more accessible and easier to understand to students at my university and to anyone else who is willing to listen.

Wish me luck!

Microsoft Community Bootcamp

cretz — Wed, 05 Sep 2007 21:39:20 +0000

During 30.08.2007 and 02.09.2007 I attended the 4th edition of Microsoft's Comunity Bootcamp as a MSP wannabe. All members of the MSP and MVP programs from Microsoft were invited. In addition, several employees from Microsoft Romania were present there. The location for the event was the Fantanita Haiducului Inn (The Outlaw's Fountain) near Sibiu. Myself, Cornel and Adi shared a car (Cornel's) to get there.

We arrived 15 minutes before dinner, just enough time to check-in. The first thing we noticed was the excellent service from the hotel. At check-in, each of us received a gift bag from Microsoft containing a bootcamp T-shirt, a pc game from Microsoft Game Studios(Halo 2, Rise of Nations or Age of Empires 3), the Microsoft Academic Resource Kit, and the schedule for the 4 days spent there. During dinner we met some of the many people there(less than 5 out of about 80). We already knew the MSP's from MAP (Microsoft Academic Program) center of our university and spent most of the time talking to them.

Friday from 08:00 to 13:00 I attended presentations held by members of Developer & Platform Evangelism team from MS Romania on marketing and strategy and a presentation on the status of the MSP program in Romania held by Todi.

Todi's presentation really touched me. He showed that MSP members are just a big family that is passionate about technology, pursues its goals and has a lot of fun along the way. I then realized that I would not regret choosing to be a member of this family.

After lunch, the fun part of the day began. Paintball, bow and arrow and paintball gun target practice awaited us not too far from the hotel. Because there were many of us, we split into 2 big groups of people. Each group had about 2 hours for these activities.
Paintball was played in a death-match championship mode between the 3 teams created. I ended up in the blue team. You can probably guess how the championship ended... Long story short, I got owned by a head-shot in the first round, and shot ridiculously in the leg the second. Not to complain or anything, but I think the blue suits we wore had something to do with the outcome...

Paintball was heaps of fun for all: Ciprian Jichici got blasted by several rounds after making a screaming kamikaze run towards the enemy when he ran out of bullets, a member of the brown team got a real taste of the paint balls through the mask (guess I was lucky I only got hit in the visor).

Immediately after returning to the hotel I had to continue work on the demo for Saturday. This night was the longest I've had in many months. The project involved using LINQ to query .NET assemblies. I was responsible for the flashy WPF user interface, but just kept hitting walls in reaching my objective. After finally giving up for the night at 4:30 in the morning, I had 2 hours of sleep and then skipped the morning presentations on MS's technology focus for 2007-2008 in order to continue the demo. I managed to finish the code 15 minutes before we were up for DemoThis!, short demos that got graded by the public to win the grand prize: an XBOX 360. I am proud to say that our project, RLINQ, got 3rd place out of 5. Second place was awarded to a demo on Microsoft Robotics Studio and first place went to a showcase of an Imagine Cup project on alternative user input using a motion sensor on the wrist. There were two more demo's on .NET Framework internals and a dependency explorer for dlls. I will write a post about my project once I'm satisfied with the outcome (UI still not finished).

After lunch and a couple of hours of much needed R&R, we visited the city of Sibiu. I missed the Bruckenthal Museum, but got to visit the Astra Museum. We also had dinner at the museum's restaurant.

Sunday morning was the time for presentations on business opportunities. A few members of the MSP program presented their businesses and the Microsoft's Global Technical Support Center presented its offer.

All in all the bootcamp was an unforgettable experience. I've met a lot of people that share my interests and had a lot of fun.

Hello world! (V2)

Cretz — Tue, 21 Aug 2007 18:00:39 +0000

I guess I am just starting to become a person since I just started my first blog. I created this blog at the recommendation of Tudor Salomie and Tudor Vlad. My main topics on this blog will be technology and programming.

Here are a few things to know about me: MANY people call me Cretz (all my friends, professors I have research projects with, my boss, etc.) even though my name is Ioan (John in English). I am a student in Computer Science at the Technical University of Cluj Napoca, Romania, expecting to graduate in 2009. I currently work at a company that develops solutions for securities firms based on Microsoft technology. My main interests are technology, 3D art and music (more on what kind of music I enjoy you will find in the about page).

This concludes my introductory statement and I hope to come back soon with another post.

PS. The post is in V2 because I previously had a blog on www.wordpress.com but I switched to a hosted blog, but could not manage to import the old blog.