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
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 here.)
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.
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.
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:
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 SearchBox Gadget is available free for
download here.
The source code for the gadget is also freely available for
download here.
The original version of this
article was published in the June 2007 issue of
ASP.NET Pro Magazine.