System.Gadget.onUndock event

[The Windows Gadget Platform/Sidebar is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions. ]

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


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.


iRetVal = System.Gadget.onUndock(



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 [desktop apps only]
Minimum supported server
Windows Server 2008 [desktop apps only]
End of client support
Windows 7
End of server support
Windows Server 2008
Sidebar.Exe (version 1.00 or later)

See also