ControlFreak

LANGUAGES: HTML | JavaScript

 

Vista Sidebar Gadgets:
A Developer SearchBox

Create Sidebar Gadgets for Windows Vista and End Up with a Convenient Tool for Finding Software Development Answers on the Web

 

By Steve C. Orr

 

This article will introduce you to the Windows Vista Sidebar and show you how to create your own Sidebar gadgets. We ll discuss the components that make up a Sidebar gadget, discuss capabilities and security limitations, and explain packaging and deployment. This will all be done by walking through the creation of a useful Developer SearchBox gadget that lets you search the Web (or specific software development Web sites) for the content of your choosing. You ll be able to use this gadget from the convenience of your own Vista desktop to ease future development tasks.

 

What Is the Windows Vista Sidebar?

The Windows Vista Sidebar can host a variety of fun and useful little gadgets, right on your desktop. This configurable area can contain clocks, calendars, resource meters, RSS feeds, stock quotes, weather and traffic reports, and virtually anything else you can think of. Windows Vista comes with more than a dozen such gadgets built-in, and hundreds more are available for download on the Internet and most of them are free.

 

After downloading a gadget file, simply double click it to install it. Once installed, it will then be visible in your list of available gadgets. To view the list of available gadgets and pick which ones you want to appear in your Sidebar, simply click the plus sign at the top of your Sidebar (as shown in Figure 1) and choose the gadgets you find to be most useful or interesting. If you choose more gadgets than can fit on your screen at one time, they will span across multiple columns. Only one column of gadgets can appear on screen at a time, although you can scroll through each column by clicking the arrow buttons at the top of the Sidebar next to the plus sign, as shown in Figure 1. To remove a gadget from your Sidebar, hover the mouse over it and click the X that appears next to it.

 

Figure 1: The Windows Vista Sidebar can be configured via the buttons at the top of the Sidebar to add gadgets and scroll through multiple columns of gadgets.

 

Some people may liken the Sidebar to the old Active Desktop feature that was available in the Windows 98 days. While there are some similarities, I d have to say that the Vista Sidebar is far more stable and far less intrusive. You should have a decent amount of RAM in your system if you plan to use many gadgets; I d suggest 2 gigabytes. Of course, if you re using Visual Studio on Windows Vista then you ve probably already found you need that much RAM to run at a good speed anyway gadgets or not.

 

How to Use the Developer SearchBox Gadget

Once added to your Sidebar, the Developer SearchBox gadget is never more than a click away. (Simply click on the Windows Sidebar icon in the notification section on the right side of your Taskbar.)

 

Start by entering a search phrase into the textbox shown at the top of Figure 2. From the dropdown list below that you can choose to search the entire Web for the phrase you ve entered, or you can choose to search a specific Web site. This list is pre-populated with 30 of the best software development sites available on the Web, including MSDN and http://www.aspnetPRO.com.

 

You can also choose which search engine to use, such as Google or Microsoft. Once you ve made your selections, simply hit the Enter key or click the Search button and a browser window will open displaying the results of your search.

 

Figure 2: The Developer SearchBox gadget allows you to search a specific site or the entire Web for software development answers.

 

Like many Sidebar gadgets, the Developer SearchBox can have its options configured by clicking on the little magnifying glass icon that appears on the right when the mouse is hovering over the gadget (as highlighted in Figure 2). In the case of the Developer SearchBox, this allows you to choose a color scheme that aesthetically matches your personal taste.

 

Sidebar Capabilities and Limitations

While Sidebar gadgets are primarily HTML and JavaScript based, they do not run with the same security restrictions as Web sites. In fact, gadgets have many additional capabilities, including access to many local system resources. While Sidebar gadgets are installed on the local machine s hard drive (similar to a Windows application), they do not run with the same security restrictions as a Windows application, either. Instead, Sidebar gadgets have somewhat unique capabilities and restrictions.

 

In addition to the capabilities of Internet Explorer and JavaScript, Sidebar gadgets have a special object model all their own. This scripting object model includes access to local machine information, such as CPU details, environment variables, recycle bin properties, time-zone information, wireless status, and laptop battery status. It also includes access to local data stores, such as messages, contacts, and access to the local hard drive. Additionally, sounds can be played, such as system sounds and other custom sound files. Functions also exist for setting background images, rotating images, blurring, shadows, and other special effects. There are also quite a few functions that are helpful for debugging, such as write-only access to the event log and console output. Finally, there is the ability to launch URLs, open local files, and launch local executables. (The full Windows Sidebar object model documentation reference is located at http://msdn2.microsoft.com/en-us/library/aa965853.aspx.)

 

Aside from this rather liberal list of capabilities, Sidebar gadgets are not permitted access to many other significant functions except one: The ability to use locally installed ActiveX controls, which allows access to media player and Microsoft Office components, and access to Web services (via the XmlHttp ActiveX object), just to name a few. In fact, multiple Web services may even be called across multiple domains, thus opening many creative mash-up possibilities.

 

In case those aren t enough, you could always instantiate your own custom ActiveX controls if you can figure out a way to deploy them. Gadgets won t be any help in downloading, deploying, or registering ActiveX controls as they don t have permission for such functions. On the bright side, if you can mitigate that matter, you can easily use your favorite .NET language to develop such ActiveX controls without issue by exposing a COM wrapper around your custom .NET component. Using such a .NET-based ActiveX control within a standard Web application would likely raise concerns about browser support and .NET Framework deployment, but there is no need to worry about those issues as Sidebar components are targeted to Windows Vista and above, which has modern versions of Internet Explorer and the .NET Framework installed by default.

 

Microsoft recommends Sidebar gadgets be no wider than 130 pixels (so each fits nicely within the Vista Sidebar), although this restriction is not currently enforced. If you need extra space, flyout areas can be used and Sidebar gadgets can be dragged onto the main desktop where size is really no longer an issue. However, don t even think about trying to open new windows; I m happy to say that focus-stealing popup annoyances such as the JavaScript alert function are squelched.

 

Sidebar Gadget Ingredients

What exactly makes up a Sidebar gadget? A minimal sidebar gadget requires at least two files. The Sidebar Gadget manifest file must be named gadget.xml. This XML file contains information about the gadget, such as its name, version number, description, etc.

 

The other required file is an HTML file that acts as the main user interface for the gadget. The name of this file is configurable, and must be specified inside the gadget.xml file.

 

Other common, optional files may include an icon file, CSS files, JavaScript files, VBScript files, media files, and other helper HTML files.

 

Creating the Developer SearchBox Sidebar Gadget

The Developer SearchBox manifest file (gadget.xml) is listed in Figure 3. The contents should be mostly self explanatory, and most items are not very critical. Be sure to fill in the name element with the gadget title that you d like to appear to your users when they re choosing which gadgets they want in their Sidebar using the standard dialog box (shown in Figure 4). Also, be sure to fill in the src element with the name of the main HTML file that will act as the user interface for your gadget.

 

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

<gadget>

   <name>Search Box</name>

   <namespace>whatever</namespace>

   <version>1.0.0.0</version>

   <author name="Steve Orr">

       <info url="SteveOrr.net" />

   </author>

   <copyright>&#169; 2007</copyright>

   <description>Developer Search Box</description>

   <hosts>

       <host name="sidebar">

           <base type="HTML" apiVersion="1.0.0"

                 src="SearchBox.html" />

           <permissions>Full</permissions>

           <platform minPlatformVersion="1.0" />

       </host>

   </hosts>

</gadget>

Figure 3: Every Sidebar gadget requires a manifest file named gadget.xml, as shown here for the Developer SearchBox gadget.

 

Figure 4: The manifest file (gadget.xml) is used to specify many of the details that show up in the standard Windows Vista gadget selection dialog box shown here.

 

The main HTML file for the Developer SearchBox gadget is named SearchBox.html. This standard HTML file contains a textbox, two dropdown lists, and a button, as shown in Figure 5. It also contains a JavaScript file reference, which holds the business logic, and a CSS file reference to pretty things up.

 

<html>

<head>

   <title>Search!</title>

   <link href="SearchBox.css"

   rel="stylesheet" type="text/css" />

   <script src="SearchBox.js" type="text/javascript"

   language="javascript"></script>

</head>

<body onload="setTheme();">

   <div id="gadgetContent" class="gadget_red">

       <div class="searchsection">

           Search For:

            <br />       

           <input name="q" id="q" type="text"

           size="16" style="color: Blue;"

           onkeyup="KeyCheck(event.keyCode);" />

       </div>

       <div class="searchsection">

           Search Site:<br />

           <select id="ddlSite" name="ddlSite"

           onkeyup="KeyCheck(event.keyCode);">

               <option>The Web</option>

               <option>Adobe.com</option>

               <option>ASP.NET AJAX</option>

               <option>AspAlliance</option>

               <option>aspnetPRO.com</option>

     ...

           </select>

       </div>

       <div class="searchsection">

           Search Engine:<br />

           <select id="ddlEngine" name="ddlEngine"

               onkeyup="KeyCheck(event.keyCode);">

               <option>Microsoft</option>

               <option>Google</option>

           </select>

       </div>

       <div style="padding-bottom: 2px; margin-top: -3px;">

           <input type="submit"

               name="btnSearch" id="btnSearch"

               onclick="DoSearch();" value="Search!"

               disabled="disabled" class="searchbutton"

           />

       </div>

   </div>

</body>

</html>

Figure 5: The Developer SearchBox gadget s user interface is defined by this fairly simple and standard HTML file.

 

When the user clicks on the Search button to execute their search, the custom DoSearch JavaScript function listed in Figure 6 is invoked, as specified by the button s onclick event.

 

function DoSearch()

{

 var URL = "";

 var SiteName = ddlSite.options[ddlSite.selectedIndex].text;

 SiteName = SiteName.toLowerCase();

 var Eng = ddlEngine.options[ddlEngine.selectedIndex].text;

 if (Eng == "Microsoft")

 {

     //Do Microsoft Search

     URL = "http://search.msn.com/results.aspx?q=";

 }

 else

 {

     //Do Google Search

     URL = "http://www.google.com/search?hl=en&q=";

 }

 URL = URL + escape(q.value);

  

 if (SiteName != "the web")

 {

      //Search a specific web site

     URL = URL + " site:";

     URL = URL + GetSiteURL(SiteName);

 }

 System.Shell.execute(URL); //execute the search

}

Figure 6: This DoSearch JavaScript function contains the Developer SearchBox s primary business logic. It concatenates a custom URL based on the user s input, which executes a search on either Google s or Microsoft s search engine.

 

The DoSearch function contains the Developer SearchBox s main business logic. It collects the user s input and uses it to construct a URL that s compatible with either Microsoft s or Google s search engine. The final line launches that URL using the special gadget object model s System.Shell.execute method.

 

Displaying, Configuring, and Storing Custom User Settings

Gadgets that have configurable options can allow users to change those options by clicking on the little magnifying glass that appears on the right side of the gadget when the mouse hovers overhead, as shown in Figure 7.

 

Figure 7: The Developer SearchBox gadget allows users to adjust its color scheme by clicking on the standard magnifying glass icon located on the right side of the gadget when the mouse hovers overhead.

 

If you d like to provide a user interface that allows the user to change custom options for your Sidebar gadget, the HTML file that contains this user interface should be specified using a line of JavaScript such as this:

 

System.Gadget.settingsUI = "settings.html";

 

You should also specify the JavaScript function you want to be called when the user has completed their adjustments (so you can apply their changes immediately). That is done with a line of JavaScript such as this:

 

System.Gadget.onSettingsClosed = settingsClosed;

 

It only takes a single line of code to load or save a single custom setting. To load and save custom settings, respectively, use JavaScript lines such as these:

 

var Color = System.Gadget.Settings.read("CustomColor1");

System.Gadget.Settings.write("CustomColor1", Color);

 

Normally you d want to read in any custom settings from the onload event of your HTML files. For example, you d probably want to do this both for the onload event of the main gadget HTML file and also the custom settings HTML file, so they can each display the user s custom settings appropriately. If the read method returns an empty string then the custom setting hasn t been specified by the user yet (as is essentially null), so you should probably use a default value of some kind under this condition.

 

A custom settings HTML file should generally contain code such as this to ensure an OK button appears on the form and that the user s custom selections are saved when it is clicked:

 

//Wire up the event

System.Gadget.onSettingsClosing = settingsClosing;

function settingsClosing(event)

{

 if (event.closeAction == event.Action.commit)

 {

   var clr = ddlColor.options[ddlColor.selectedIndex].text;

   System.Gadget.Settings.write("CustomColor", clr);

 }

}

 

The first line ensures an OK button will appear and that the settingsClosing function is called in response to its click event. The settingsClosing event (not to be confused with the settingsClosed event in the main HTML file) then stores the user s customizations only if the OK button was clicked and not if the Cancel button was clicked. Once all this finishes executing, the settingsClosed function in the main HTML file is called (if it s been wired up as previously instructed) so that the user s customizations can be immediately applied from there.

 

Multiple occurrences of a gadget can be placed in a user s Sidebar. For example, a frequent traveler might choose to place several clocks in their Sidebar, each configured to a different time zone. Custom settings are automatically associated with each specific occurrence of a gadget, so you don t need to worry about naming conflicts with other gadget occurrences when saving settings. Whenever Windows restarts, each gadget occurrence automatically loads its stored settings just as they were before Windows was shut down. However, if a user deletes a gadget occurrence from their sidebar, its settings will be lost. A user may add a new occurrence of the gadget back to their Sidebar, but it will start with default settings. This could be confusing and frustrating to novice users, especially if they spent a lot of time configuring custom settings that now might seem to have vanished. For this reason I suggest keeping custom settings few and simple and easy for users to reset.

 

Packaging/Deploying a Gadget

Packaging a gadget to prepare it for deployment could hardly be any easier. Simply zip up the manifest file (gadget.xml) along with all HTML files and any other support files the gadget may need. Then change the file s extension from zip to gadget . That s it. Optional steps are available, such as signing the gadget file, but this is not required. When a user downloads the gadget file and double clicks it, it will be immediately installed and available for placement into their Sidebar. Conversely, if you download a gadget file, you can change its file extension from gadget to zip and then unzip it like any other compressed file to examine its contents. In case you re curious, downloaded Sidebar gadgets are installed in the following folder by default:

 

%userprofile%\AppData\Local\Microsoft\Windows Sidebar\Gadgets

 

It can be convenient to develop sidebar gadgets directly in this folder, so you don t have to reinstall between each edit.

 

The gadgets that come with Windows Vista are stored here:

 

%programfiles%\Windows Sidebar\Gadgets

 

Examining their source code can be a great way to learn advanced gadget creation tricks.

 

Conclusion

Windows Vista Sidebar gadgets can be fun to play with and productive to use. They re also rather fun to develop as they essentially are an entirely new kind of software application, yet they re based on familiar technologies that are easy to grasp for any experienced Web developer.

 

I encourage you to play with the gadgets that come with Windows Vista and explore the many novel gadgets available on the Web. I also encourage you to dissect them to help you learn techniques for your own gadget development. And don t forget to download the Developer SearchBox gadget that accompanies this article so you can dissect it and use it to quickly find answers to your future development questions.

 

The full source code for the Developer SearchBox gadget is available for download.

 

Steve C. Orr is an ASPInsider, MCSD, Certified ScrumMaster, Microsoft MVP in ASP.NET, and author of the book Beginning ASP.NET 2.0 AJAX by Wrox. He s been developing software solutions for leading companies in the Seattle area for more than a decade. When he s not busy designing software systems or writing about them, he can often be found loitering at local user groups and habitually lurking in the ASP.NET newsgroup. Find out more about him at http://SteveOrr.net or e-mail him at mailto:Steve@Orr.net.