Apply the New Vista APIs to Sidebar Gadgets, Part 2

Apply the New Vista APIs to Sidebar Gadgets, Part 2

eveloping Windows Vista Sidebar gadgets generally involves a lot of JavaScript programming. To make it possible for Sidebar gadgets to access the various systems’ information, Microsoft has provided a set of APIs that Sidebar gadget developers can use within their Sidebar gadgets, which are callable from JavaScript. This series explores the various gadget objects and how they can be used enhance the functionality of your gadget. They’re grouped based on their functionalities:

  • Contacts
  • Debugging and diagnostics
  • Sidebar gadgets UI
  • Machine information
  • Emails
  • Network
  • Sounds
  • Time and time zones

Part 1 covered the first four functionalities, and Part 2 will cover the last four.

Using Sidebar, you can access the email content of your Windows Mail (formerly known as Outlook Express) account using the following gadget objects:

  • System.MessageStore
  • System.MessageStoreFolder
  • System.MessageStoreMessage

The System.MessageStore object returns a collection of System.MessageStoreFolders objects. The following code prints out the various folders in Windows Mail (default email account):

         var result = document.getElementById("result");                 //---get all the different folders in the mailbox---         var folders = System.MessageStore.Folders;         for (i=0; i";         }

Here’s an example of the output:

Name: InboxName: OutboxName: Sent ItemsName: Deleted ItemsName: DraftsName: Junk E-mail

Add the following code and you can print out the total number of messages contained within the folders?in addition to printing the folder names:

     result.innerHTML += "Name: " + + "
"; result.innerHTML += "Unread Messages: " + folder.unreadMessageCount + "
"; result.innerHTML += "Messages: " + folder.messageCount + "

System.MessageStoreFolder and System.MessageStoreMessage
The System.MessageStoreFolder object returns a collection of System.MessageStoreMessage objects.

The code in Listing 1 prints out the content of all the messages contained in each folder.

To obtain detailed information about your network connection, use the System.Network.Wireless object. This object returns detailed networking information about the computer hosting the gadget.

The gadget in Listing 2 shows the detailed network status of your computer. When the page is loaded, you first print out the current status of your wireless network. Then, you set the connectionChanged and signalStrengthChanged events to the WirelessChanged event handler. This event handler will be called whenever there is a change in the wireless connection and signal strength.

System Shell
To manipulate files and folders on Windows from within your Sidebar gadget, use the following objects:

  • System.Shell
  • System.Shell.Folder
  • System.Shell.Item
  • System.Shell.RecycleBin
  • System.Shell.Drive

The System.Shell object enables you to use the command shell of Windows to perform file operations.

This code shows you how to allow users to choose a file from within a gadget:

         //---choose a file---         var item = System.Shell.chooseFile(            true, "Text File:*.txt:Png File:*.png", ".", "");          //---if the user clicks Open---         if (item!=null) {            result.innerHTML = "File selected: " + +             "
"; }

The chooseFile() method invokes the Open dialog, and the user selects a file for opening. The user then selects clicks the Open button, and the file name is displayed.

The chooseFolder() method allows users to select a folder to open, as the following code illustrates:

      //---choose a folder---      item = System.Shell.chooseFolder("Please select a folder", 0);      if (item!=null) {            result.innerHTML += "Folder selected: " + +          "
"; }

The drive() method retrieves detailed information about a specific drive. It returns a System.Shell.Drive object:

         //---choose a drive---         var drive ="c:");
Author’s Note: See the section “System.Shell.Drive” for more information about the System.Shell.Drive object.

The execute() method specifies a command to be executed by the Windows shell. For example, you can launch Notepad from within your Sidebar gadget, like this:

         System.Shell.execute ("notepad.exe");

You can also allow users to drag and drop files onto your Sidebar gadgets. After files are dropped onto your gadget, you can ask the user to specify a folder in which to copy the dropped files, as shown in Listing 3. Notice that you need to add the ondragenter, ondragover, and ondrop attributes to the element so that users can drag and drop files onto your gadget. When a file is dropped onto your gadget, it calls the onDropped function.

You can call the chooseFolder() method to allow the user to choose a folder in which to copy the dropped files. The itemFromFileDrop() method enables you to obtain the files that are dropped (as a collection of System.Shell.Item objects). The files are then copied to the destination folder using the copyHere() method. If you want to move the files instead of copying them, use the moveHere() method:

           folder.moveHere(System.Shell.itemFromFileDrop(event.dataTransfer, i));

The itemFromPath() method returns a collection of System.Shell.Item objects associated with a specified path. For example, the following code copies all the files stored in C:folder1 into C:folder2:

   var destFolder = System.Shell.itemFromPath("C:\folder2");   var sourceFolder = System.Shell.itemFromPath("C:\folder1");   //---copies all the files in folder1 into folder2---   for (var i = 0; i

The knownFolder() method takes in a string representing a well-known folder and returns a System.Shell.Folder object. The following code displays the total number of items on the Desktop:

         var result = document.getElementById("result");         var folder = System.Shell.knownFolder("Desktop")         result.innerHTML = folder.Items.count;

Some well-known folders are:

  • Desktop
  • Startup
  • StartMenu
  • Documents
  • Programs
  • CommonPrograms
  • PublicDesktop
  • PublicFavorites
  • PublicDocuments
  • System
  • Windows
  • Videos
  • ProgramFiles
  • Downloads
  • RecycleBinFolder

If you want to know the path of a well-known folder, use the knownFolderPath() method:

var result = document.getElementById("result");result.innerHTML = System.Shell.knownFolderPath("Desktop")

The refreshDesktop() method refreshes the desktop after you have added or removed some files:


The saveFileDialog() method shows the standard Save As dialog to allow a user to specify a file for saving:

         var result = document.getElementById("result");         var strPath = System.Shell.saveFileDialog(            "C:\", "Text File*.txtPng File*.png");         result.innerHTML = "File name and path: " + strPath;
Author's Note: There is a bug in the current version of the saveFileDialog() method. Instead of specifying the file filter in the format of Description:Extension:Description:Extension, it should be specified as DescriptionExtensionDescriptionExtension.

The System.Shell.Folder object enables you to perform file operation such as copying and moving files and creating new folders. It exposes a collection of System.Shell.Item objects.

Here's an example that shows you how to copy files from C:folder1 into C:folder2 using the copyHere() method:

   var destFolder = System.Shell.itemFromPath("C:\folder2");   var sourceFolder = System.Shell.itemFromPath("C:\folder1");   //---copies all the files in folder1 into folder2---   for (var i = 0; i

The second parameter of the copyHere() method takes an optional flag argument, which can be a combination of the following values:




Do not display a progress dialog box.


Give the file being operated on a new name in a move, copy, or rename operation if a file with the target name already exists.


Respond with "Yes to All" for any dialog box that is displayed.


Preserve undo information, if possible.


Perform the operation on files only if a wildcard file name (*.*) is specified.


Display a progress dialog box but do not show the file names.


Do not confirm the creation of a new directory if the operation requires one to be created.


Do not display a user interface if an error occurs.


Only operate in the local directory. Don't operate recursively into subdirectories.


Do not copy connected files as a group. Copy only the specified files.

To move files instead of copying them, use the moveFile() method, like in the following example, which moves all the files in folder1 to folder2:

   var destFolder = System.Shell.itemFromPath("C:\folder2");   var sourceFolder = System.Shell.itemFromPath("C:\folder1");   //---moves all the files in folder1 into folder2---   while (sourceFolder.SHFolder.Items.count>0) {      var item = sourceFolder.SHFolder.Items.item(0);      destFolder.SHFolder.moveHere( item, 16 + 256 + 512 );   }

You can also create a new folder; here's a code snippet that does so in C:folder1:

   var sourceFolder = System.Shell.itemFromPath("C:\folder1");   sourceFolder.SHFolder.newFolder("New Documents",0);

The following code displays the number of items contained within the C:folder1 folder:

   var sourceFolder = System.Shell.itemFromPath("C:\folder1");   var result = document.getElementById("result");   //---get info about itself---   var folder = sourceFolder.SHFolder.Self;   //--displays how many items in the folder---   result.innerHTML = folder.SHFolder.Items.count;
Author's Note: The Parent property is not working in the current version of the Sidebar.

The System.Shell.Item object returns detailed information about an item in the shell (such as files, folders, and shortcuts).

The code in Listing 4 shows you how to display the attributes of each file located in folder1.

The invokeVerb() method performs a specified action on a file. For example, the verb Open opens a file with its associated program. The following code first checks to see if an item's name ends with the .txt extension and opens it if it does (Notepad launches by default):

      if (".txt") != -1) {         item.invokeVerb("Open");      }

Some commonly used verbs are Open, Edit, New, Print, and Show. You can find out which verbs are applicable for a file type by right-clicking on a file type in Windows Explorer and then viewing its list of applicable actions (see Figure 1).

Figure 1. View the Verbs: Find which verbs are applicable for a file type by right-clicking on a file type in Windows Explorer.
Figure 2. Metadata: The keys are listed in the Description section of the Details tab.

The metadata() method returns the metadata of an item based on the key (such as Title, Subject, Tags, Categories, Comments, and so on) specified. For example, the following code shows the Title metadata for a PowerPoint file:

      if (".pptx") != -1) {         var metaData = item.metadata("Title");         result.innerHTML += metaData;      }

You can obtain the list of keys for a particular file type by right-clicking a file and selecting Properties. On the Details tab, the keys are listed in the Description section (see Figure 2). Common metadata keys are Title, Subject, Tags, Categories, and Comments.

The System.Shell.RecycleBin object enables you to programmatically manipulate the Recycle Bin on your computer.

Here's a code example that shows you how to display the number of files and folders in the Recycle Bin, as well as the current size of the Recycle Bin:

         var result = document.getElementById("result");         result.innerHTML = "fileCount: " +            System.Shell.RecycleBin.fileCount + "
" + "folderCount: " + System.Shell.RecycleBin.folderCount + "
" + "sizeUsed: " + System.Shell.RecycleBin.sizeUsed + "KB";
Figure 3. The Recycle Bin Properties Dialog: The inline code example displays the Recycle Bin Properties dialog.

The following code example first displays the Recycle Bin Properties dialog (see Figure 3), followed by deleting an item (by moving it into the Recycle Bin). Finally, it asks the user if he wants to empty the Recycle Bin:

         //---shows the recycle bin status---         System.Shell.RecycleBin.showRecycleSettings();         //---delete a particular file (move to recycle bin)---         System.Shell.RecycleBin.deleteItem("c:\folder1\pic1.bmp")         //---empties the recycle bin---         System.Shell.RecycleBin.emptyAll();

The System.Shell.RecycleBin object has one event, onRecycleBinChanged, which allows script commands within a gadget to be run when the contents of the Recycle Bin are modified, such as when files, folders, or links being added or deleted from the set of items currently stored in the Recycle Bin.

The onRecycleBinChanged event fires whenever the content in the Recycle Bin is modified. The following code shows you how to wire an event handler to handle the onRecycleBinChanged event:

      System.Shell.RecycleBin.onRecycleBinChanged = RecycleBinChanged;      function RecycleBinChanged()      {         var result = document.getElementById("result");         result.innerHTML = "Recycle Bin Changed";      }

The System.Shell.Drive object enables you to obtain detailed information about a drive.

The code in Listing 5 shows you how you to retrieve detailed information about the C: drive.

The driveType property returns one of the following values:




The specified drive is invalid.


The drive is a floppy drive.


The drive is a removable drive, such as a USB or cartridge drive.


The drive is a fixed drive.


The drive is a remote (network) drive.


The drive is a CD-ROM drive.


The drive is a RAM disk.

If your gadget needs to play system sounds or sound files, use the System.Sound object.

The beep() method generates a simple beep tone on the system's speakers, while the playSound() method plays a specified sound file:

    System.Sound.beep();    System.Sound.playSound(       "\windows\media\Windows Critical Stop.wav");

Time and Time Zones
You can obtain information about the different time zones using the following objects:

  • System.Time
  • System.Time.TimeZone

The System.Time object enables you to obtain time information for the current system. It exposes a System.Time.timezones collection of System.Time.TimeZone objects.

Here's how you can obtain the collection of System.Time.TimeZone objects:

         var timeZones = System.Time.timeZones;

The System.Time object has only one method, getLocalTime(), which returns the local time based on the specified time zone. It also has only one property, currentTimeZone, which returns the current time zone as a System.Time.TimeZone object.

The following example shows you how you can display the current time in the current time zone:

         var result = document.getElementById("result");         var timeZone = System.Time.currentTimeZone;         result.innerHTML = "Local Time: " +                System.Time.getLocalTime(timeZone);
Figure 4. Time Zones: Retrieving all the details of the various time zones available.

The System.Time.TimeZone object contains detailed information about a specific time zone. The following example shows you how to retrieve all the details of the various time zones available (see Figure 4 for the output):

var result = document.getElementById("result");         var timeZones = System.Time.timeZones;         for (var i=0; i" +                     "Bias: " + oTimeZone.bias + "
" + "Display Name: " + oTimeZone.displayName + "
" + "DST Bias: " + oTimeZone.DSTBias + "
" + "DST Date: " + oTimeZone.DSTDate + "
" + "Standard Bias: " + oTimeZone.standardBias + "
" + "Standard Date: " + oTimeZone.standardDate + "
" + "Standard Display Name: " + oTimeZone.standardDisplayName + "
"; }

Vista's Potential
Now that you've examined the various objects exposed by Windows Sidebar, your gadget should be capable of harnessing all the additional functionalities available in Windows Vista.


About Our Editorial Process

At DevX, we’re dedicated to tech entrepreneurship. Our team closely follows industry shifts, new products, AI breakthroughs, technology trends, and funding announcements. Articles undergo thorough editing to ensure accuracy and clarity, reflecting DevX’s style and supporting entrepreneurs in the tech sphere.

See our full editorial policy.

About Our Journalist