RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Apply the New Vista APIs to Sidebar Gadgets, Part 1  : Page 4

Explore the various Windows Vista Sidebar gadget objects and how they can be used to enhance the functionality of your gadget.

Sidebar Gadgets UI
To manipulate the various UI features (flyout, options page, docking and undocking, and so forth) of your Sidebar gadget, use the following objects:
  • System.Gadget
  • System.Gadget.Settings.ClosingEvent
  • System.Gadget.Flyout
  • System.Gadget.Settings
The System.Gadget object contains various events, methods, and properties that allow you to control the behavior of your Sidebar gadgets.

The code in Listing 1 shows a simple gadget that utilizes all the events and properties of the System.Gadget object. It also has an options page named Settings.html. First, when the gadget is loaded, you print out the various properties of the gadget and set the location of the options page (through the settingsUI property). Next, you assign the event handlers for the onUndock, onDock, onSettingsClosed, and onShowSettings events. Finally, you define the event handlers for these events. And in each of these event handlers, you print a message when each event is fired.

Listing 2 defines the Settings.html page. When the options page is closed, the SettingsClosing() function (as set in the onSetttingsClosing event) will be called to determine the button that was clicked (OK or Cancel).

When the gadget is first loaded (on the left in Figure 2), it displays information about itself, such as name, opacity, path, platform version, and version. When it is undocked (on the right in Figure 2), it displays its docking status.

Figure 2. System.Gadget: The gadget in docked and undocked state.

The System.Gadget.onSettingsClosing event is used in the options page, while the System.Gadget.onSettingsClosed event is used in the main gadget page. By servicing these two events, you can know whether the user has clicked the OK or Cancel button.

When the user clicks the OK or Cancel button on the options page, the SettingsClosing() function is called. You know which button has been clicked though the event parameter. If the user has clicked the OK button, the event.CloseAction property returns 0 (you can also check using the event.Action.commit constant). For example, if the user clicked the Cancel button, you may want to check that certain required fields are entered before the options page can be closed. Likewise, if the OK button is clicked, you may want to validate the input fields before closing the options page.

When the options page is closed, the SettingsClosed() function (in APIs-Gadgets.html) is called, and likewise you can check whether the user has clicked the OK or Cancel button.

The close() method enables you to programmatically close the gadget and remove it from the Sidebar pane. The following example shows that a gadget will be closed five seconds after it has been loaded:

function load()
         setTimeout(close, 5000);

      function close()
If your gadget's UI is constantly updated, you might want to use beginTransition() and endTransition() methods to temporarily suspend all visual updates until all the changes are made:

        //---perform all your UI updates here---                  
           System.Gadget.TransitionType.none, 2);
The first argument of the endTransition() method can be one of the following:
  • System.Gadget.TransitionType.morph
  • System.Gadget.TransitionType.none
The second parameter is the amount of time in seconds to perform the transition.

The System.Gadget.Settings.ClosingEvent object provides the status of the options page and gives you the capability to prevent an options page from closing. In the previous section, you saw that the System.Gadget.onSettingsClosing event is fired on the options page when the options page is closing, while the System.Gadget.onSettingsClosed event is fired on the main gadget page when the options page has closed. The event handlers for these two events have an event parameter of type System.Gadget.Settings.ClosingEvent. Using this parameter, you can know whether the user has clicked OK or Cancel:

      //---in the gadget's main page---
      //---when the settings page has closed---
      function SettingsClosed(event)
         if (event.closeAction == event.Action.commit) {
            DisplayValue("User clicked OK");       
         else {
            DisplayValue("User clicked Cancel");        
The Action property has two enumerations: commit and cancel.

To make sure that the options page does not close until some criteria are satisfied, you can use the System.Gadget.Settings.ClosingEvent.cancel property in the System.Gadget.onSettingsClosing event handler (in the options page), like this:

      //---in the options page---
      function SettingsClosing(event)
         if ((some_condition) && (!event.cancellable)) {
            //---prevent the options page from closing---
The cancel property gives you the capability to cancel the closing of the options page (that is, to prevent the options page from closing). This capability is useful if some criteria are not met, such as users not supplying the expected inputs. In that case, they won't be able to close the options page until they have given the required input.

The cancellable property (read-only) returns a value indicating if the user can successfully close the options page.

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date