System.Gadget.onDock 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.

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.


iRetVal = System.Gadget.onDock(



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


This event is fired either when the gadget is initialized or 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




Community Additions