System.Gadget.onUndock Event

Event fired when the gadget is docked on the Windows Sidebar.

Note  For Windows 7, because there is no Sidebar associated with the Gadget Platform, the onDock and onUndock event listeners are linked to a new gadget icon ("Larger size" or "Smaller size"). Clicking this icon resizes the gadget and raises the dock ("Smaller size") or undock ("Larger size") event.


retVal = System.Gadget.onUndock(


  • handler
    The name of the function to call when the event is fired.


This event is fired through user interaction after initialization.

This event updates the gadget docked property.

Docked gadgets must be at least 60 pixels high (the height of the gadget toolbar including the Settings icon) and anywhere from 25 pixels to 130 pixels wide to fit within the maximum width of the Sidebar. Oversized gadgets are not clipped at the bounds of the Sidebar. Undocked gadgets have no maximum size constraints.


The following example demonstrates how to modify the appearance of a gadget based on its dock state.

// Gadget width and height.
var gadgetWidth = 130;
var gadgetHeight = 108;

// Amount to scale gadget when docked or undocked.
var scaleDocked = 1;
var scaleUndocked = 2;

// Amount of time desired to perform transition (in seconds).
var timeTransition = 2;

// Declare the dock and undock event handlers.
System.Gadget.onDock = CheckDockState;
System.Gadget.onUndock = CheckDockState;

// --------------------------------------------------------------------
// Check the gadget dock state; set the gadget style.
// imgBackground is the value of the 'id' attribute for the 
// g:background element.
// --------------------------------------------------------------------
function CheckDockState()
    var oBackground = document.getElementById("imgBackground");
    // Set the width of the background element to 0.
    // This forces the image to be refreshed appropriately. = 0;

    var oBody =;
    if (System.Gadget.docked)
        oBody.width = gadgetWidth*scaleDocked;
        oBody.height = gadgetHeight*scaleDocked;
        oBackground.src = "url(../images/bg_docked.png)";
        txtDocked.className = 'gadgetDocked';
        txtDocked.innerText = 'Docked';
        oBody.width = gadgetWidth*scaleUndocked;
        oBody.height = gadgetHeight*scaleUndocked;  
        oBackground.src = "url(../images/bg_undocked.png)";
        txtDocked.className = 'gadgetUndocked';
        txtDocked.innerText = 'Undocked';
    System.Gadget.endTransition(System.Gadget.TransitionType.morph, timeTransition);


Minimum supported client Windows Vista
Minimum supported server Windows Server 2008
IDL Sidebar.idl
DLL Sidebar.Exe version 1.00 or later

See Also




Send comments about this topic to Microsoft

Build date: 2/24/2010

Build type: SDK