IDesktopGadget::RunGadget method
Adds an installed gadget to the desktop.
Syntax
HRESULT RunGadget(
[in] LPCWSTR gadgetPath
);
Parameters
- gadgetPath [in]
-
Type: LPCWSTR
Pointer to the full (absolute) path of a .gadget folder. A gadget that is not packaged with Windows can only be run from one of the two following locations. Installation of the gadget in any other location will cause this method to fail with an access denied error.
Note This path should not contain environment variables; the fully expanded path must be provided. ExpandEnvironmentStrings can be used to expand the path to the form required in this parameter.
Return value
Type: HRESULT
Returns S_OK if successful, or an error value otherwise, including the following:
| Return code | Description |
|---|---|
|
The gadget is already running. |
|
An error occurred involving the path of the gadget folder pointed to by gadgetPath. |
Remarks
"Running" a gadget here means that the gadget is added to the desktop.
RunGadget can only be called on a gadget that has already been installed to the system. It cannot be called on a gadget that is already running—only one instance of a gadget can be run at any given time through this method.
Because gadget installation has no UI of its own, this method is often run as the last step in the installation process or as part of the first launch of an application that the gadget is associated with. Installation of the gadget to %ProgramFiles%\Windows Sidebar\Shared Gadgets requires administrative privileges. Therefore it is recommended that the installation of the gadget be performed as part of a Microsoft Installer (MSI) installation.
The gadget is added to the desktop at a position determined by the system. The caller cannot specify location.
Per-user applications should install their gadgets per-user. Per-machine applications should install their gadgets per-machine. This ensures a unified experience to the user.
Examples
The following example shows IDesktopGadget::RunGadget in use.
HRESULT RunMyGadget(PCWSTR pszGadgetPath)
{
IDesktopGadget *pDG;
HRESULT hr = CoCreateInstance(CLSID_DesktopGadget,
NULL,
CLSCTX_INPROC_SERVER,
IID_PPV_ARGS(&pDG));
if (SUCCEEDED(hr))
{
hr = pDG->RunGadget(pszGadgetPath);
pDG->Release();
}
return hr;
}
Requirements
|
Minimum supported client |
Windows 7 [desktop apps only] |
|---|---|
|
Minimum supported server |
Windows Server 2008 R2 [desktop apps only] |
|
Header |
|
|
IDL |
|