
This article contains information on the IActiveDesktop interface that is part of the Microsoft® Windows® Shell API. This interface and its method allow you to add, remove, and change items on the desktop.
Overview of the Active Desktop Interface
The Active Desktop is a feature of Microsoft Internet Explorer 4.0 that allows you to include HTML documents and items (such as ActiveX Controls and Java applets) directly to your desktop. The IActiveDesktop interface, which is part of the Windows Shell API, is used to programmatically add, remove, and modify the items on the desktop. Active Desktop items can also be added using a Channel Definition Format (CDF) file. For information about creating Active Desktop items and adding them with a CDF file, see Creating Active Desktop Items. For more information on CDF files, see Creating Active Channels for Internet Explorer 4.0.
To access the Active Desktop, a client application would need to create an instance of the Active Desktop object with the CoCreateInstance function and get a pointer to its IActiveDesktop interface.
The following sample shows how to get a pointer to the IActiveDesktop interface.
HRESULT hr; IActiveDesktop *pActiveDesktop; //Create an instance of the Active Desktop hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER, IID_IActiveDesktop (void**)&pActiveDesktop); //Insert code to call the IActiveDesktop methods // Call the Release method pActiveDesktop->Release();
There are three methods that can be used to add a desktop item: IActiveDesktop::AddDesktopItem, IActiveDesktop::AddDesktopItemWithUI, and IActiveDesktop::AddUrl. Each desktop item added to the Active Desktop must have a different source URL.
The IActiveDesktop::AddDesktopItemWithUI and IActiveDesktop::AddUrl both provide the option to display the various user interfaces that can be displayed before adding a desktop item to the Active Desktop. The interfaces will verify if the user really wants to add the desktop item to their Active Desktop, notify the user of any security risks that are warranted by the URL security zone settings, and ask the user if the user would like to create a subscription for this desktop item. Both methods also provide a way of suppressing the user interfaces. The IActiveDesktop::AddDesktopItem method requires a call to IActiveDesktop::ApplyChanges in order to update the registry. For the IActiveDesktop::AddDesktopItemWithUI, the client application must immediately release the IActiveDesktop interface and then use the CoCreateInstance function to get an interface to an instance of the Active Desktop object that includes the newly added desktop item.
The IActiveDesktop::AddDesktopItem method will add the specified desktop item to the Active Desktop without any user interface, unless the URL security zone settings prevent it. If the URL security zone settings do not allow the desktop item to be added without prompting the user, the method will fail. IActiveDesktop::AddDesktopItem also requires a call to IActiveDesktop::ApplyChanges in order to update the registry.
The following sample demonstrates how to add a desktop item with the IActiveDesktop::AddDesktopItem method.
HRESULT hr; IActiveDesktop pActiveDesktop; COMPONENT compDesktopItem; //Create an instance of the Active Desktop hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER, IID_IActiveDesktop (void**)&pActiveDesktop); // Initialize the COMPONENT structure compDesktopItem.dwSize = sizeof(COMPONENT); // Insert code that adds the information about the desktop item to the COMPONENT structure // Add the desktop item pActiveDesktop->AddDesktopItem(&compDesktopItem,0); // Save the changes to the registry pActiveDesktop->ApplyChanges(AD_APPLY_ALL);
To enumerate the desktop items currently installed on the Active Desktop, the client application needs to get the total number of desktop items installed using the IActiveDesktop::GetDesktopItemCount method and then creating a loop that retrieves the COMPONENT structure for each desktop item by calling the IActiveDesktop::GetDesktopItem method using the desktop item index.
The following sample demonstrates one way to enumerate the desktop items.
HRESULT hr;
IActiveDesktop pActiveDesktop;
COMPONENT compDesktopItem;
int intCount;
int intIndex = 0;
//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
IID_IActiveDesktop (void**)&pActiveDesktop);
pActiveDesktop->GetDesktopItemCount(&intCount,0);
compDesktopItem.dwSize = sizeof(COMPONENT);
while(intIndex<=(intCount-1))
{
//get the COMPONENT structure for the current desktop item
pActiveDesktop->GetDesktopItem(intIndex, &compDesktopItem,0);
//Insert code that processes the structure
//Increment the index
intIndex++;
//Insert code to clean-up structure for next component
}
// Call the Release method
pActiveDesktop->Release();
This section contains the reference information for the ActiveDesktop object.
CLSID_ActiveDesktop
Manages the Active Desktop. Has one interface, IActiveDesktop.
This section contains the reference information for the IActiveDesktop interface and its methods.
Allows a client program to manage the desktop items and wallpaper on a local computer.
| Methods | Description |
| AddDesktopItem | Adds a desktop item. |
| AddDesktopItemWithUI | Adds a desktop item to the Active Desktop using a user interface. |
| AddUrl | Adds the desktop item associated with the specified URL. |
| ApplyChanges | Applies changes to the Active Desktop. |
| GenerateDesktopItemHtml | Generates a generic HTML page containing the given desktop item. |
| GetDesktopItem | Retrieves the specified desktop item. |
| GetDesktopItemByID | Retrieves the desktop item that matches the given identification. |
| GetDesktopItemBySource | Retrieves a desktop item using its source URL. |
| GetDesktopItemCount | Retrieves a count of the desktop items. |
| GetDesktopItemOptions | Retrieves the desktop item's options. |
| GetPattern | Retrieves the pattern currently being used. |
| GetWallpaper | Retrieves the wallpaper currently being used. |
| GetWallpaperOptions | Retrieves the wallpaper options. |
| ModifyDesktopItem | Modifies the desktop item. |
| RemoveDesktopItem | Removes the specified desktop item from the desktop. |
| SetDesktopItemOptions | Sets the item's options. |
| SetPattern | Sets the ActiveDesktop pattern. |
| SetWallpaper | Sets the wallpaper for the Active Desktop. |
| SetWallpaperOptions | Sets the wallpaper options. |
This section describes the methods exposed by the IActiveDesktop interface.
HRESULT AddDesktopItem(
LPCOMPONENT pcomp,
DWORD dwReserved
);
Adds a desktop item.
If the source URL of the desktop item being added matches a desktop item already installed on the Active Desktop, this method will fail.
The desktop item is added to the desktop, but it does not save it to the registry. The client application must call IActiveDesktop::ApplyChanges separately to update the registry.
HRESULT AddDesktopItemWithUI(
HWND hwnd,
LPCOMPONENT pcomp,
DWORD dwReserved
);
Adds a desktop item to the Active Desktop after displaying user interfaces that confirm the addition of the desktop item, verify security zone permissions, and ask if the user wants to create a subscription.
If the source URL of the desktop item being added matches a desktop item already installed on the Active Desktop, this method will fail.
This method creates a second instance of the Active Desktop to add the desktop item, so the desktop item will not appear in the current instance. The application must call the IUnknown::Release method on this IActiveDesktop interface and the use the CoCreateInstance function to get the Active Desktop object with the newly added component.
HRESULT AddUrl(
HWND hwnd,
LPCWSTR pszSource,
LPCOMPONENT pcomp,
DWORD dwFlags
);
Adds the desktop item associated with the specified URL.
If the source URL of the desktop item being added matches a desktop item already installed on the Active Desktop, this method will fail.
By default, this method will display some user interface and then add the desktop item to the Active Desktop. Like IActiveDesktop::AddDesktopItem, the client application must call IActiveDesktop::ApplyChanges to have the changes saved to the registry.
HRESULT ApplyChanges(
DWORD dwFlags
);
Applies changes to the Active Desktop and saves them in the registry.
| AD_APPLY_SAVE |
| AD_APPLY_HTMLGEN |
| AD_APPLY_REFRESH |
| AD_APPLY_ALL |
| AD_APPLY_FORCE |
HRESULT GenerateDesktopItemHtml(
LPCWSTR pwszFileName,
LPCOMPONENT pcomp,
DWORD dwReserved
);
Generates a generic HTML page containing the given desktop item.
HRESULT GetDesktopItem(
int nComponent,
LPCOMPONENT pcomp,
DWORD dwReserved
);
Retrieves the specified desktop item.
The index values will change as desktop items are added and removed from the Active Desktop. Applications cannot assume that an index value will always be associated with a particular desktop item.
HRESULT GetComponentByID(
DWORD dwID,
LPCOMPONENT pcomp,
DWORD dwReserved
);
Retrieves the desktop item that matches the given identification.
The desktop item's identification is returned in the dwID member of the COMPONENT structure returned from the IActiveDesktop::GetDesktopItem method. This identification is only valid until the IActiveDesktop::ApplyChanges method is called. Applications that need to get the same desktop item consistently should enumerate the desktop items using the IActiveDesktop::GetDesktopItem and IActiveDesktop::GetDesktopItemCount methods.
HRESULT GetDesktopItemBySource (
LPCWSTR pszSource,
LPCOMPONENT pcomp,
DWORD dwReserved
);
Retrieves a desktop item using its source URL.
HRESULT GetDesktopItemCount(
LPINT lpiCount,
DWORD dwReserved
);
Retrieves a count of the desktop items.
The lpiCount value can be used to enumerate all desktop items. The index values start at 0 and go to lpiCount minus one.
HRESULT GetDesktopItemOptions(
LPCOMPONENTSOPT pco
DWORD dwReserved
);
Retrieves the desktop item's options.
HRESULT GetPattern(
LPWSTR pwszPattern,
UINT cchPattern,
DWORD dwReserved
);
Retrieves the pattern currently being used.
HRESULT GetWallpaper(
LPWSTR pwszWallpaper,
UINT cchWallpaper,
DWORD dwReserved
);
Retrieves the wallpaper currently being used.
HRESULT GetWallpaperOptions(
LPWALLPAPEROPT pwpo,
DWORD dwReserved
);
Retrieves the wallpaper options.
HRESULT ModifyDesktopItem(
LPCCOMPONENT pcomp,
DWORD dwFlags
);
Modifies the desktop item.
| AD_APPLY_SAVE |
| AD_APPLY_HTMLGEN |
| AD_APPLY_REFRESH |
| AD_APPLY_ALL |
| AD_APPLY_FORCE |
HRESULT RemoveDesktopItem(
LPCCOMPONENT pcomp,
DWORD dwReserved
);
Removes the specified desktop item from the desktop.
HRESULT SetDesktopItemOptions(
LPCCOMPONENTSOPT pcomp,
DWORD dwReserved
);
Sets the item's options.
HRESULT SetPattern(
LPCWSTR pwszPattern,
DWORD dwReserved
);
Sets the Active Desktop pattern.
HRESULT SetWallpaper(
LPCWSTR pwszWallpaper,
DWORD dwReserved
);
Sets the wallpaper for the Active Desktop.
HRESULT SetWallpaperOptions(
LPCWALLPAPEROPT pwpo,
DWORD dwReserved
);
Sets the wallpaper options.
This section describes the structures used by the methods of the IActiveDesktop interface.
| COMPONENT |
| COMPONENTSOPT |
| COMPPOS |
| WALLPAPEROPT |
typedef struct _tagCOMPONENT {
DWORD dwSize;
DWORD dwID;
int iComponentType;
BOOL fChecked;
BOOL fDirty;
BOOL fNoScroll;
COMPPOS cpPos;
WCHAR wszFriendlyName[MAX_PATH];
WCHAR wszSource[INTERNET_MAX_URL_LENGTH];
} COMPONENT;
Contains the information related to a desktop item.
| COMP_TYPE_CFHTML |
| COMP_TYPE_CONTROL |
| COMP_TYPE_HTMLDOC |
| COMP_TYPE_MAX |
| COMP_TYPE_PICTURE |
| COMP_TYPE_WEBSITE |
typedef struct _tagCOMPONENTSOPT {
DWORD dwSize;
BOOL fEnableComponents;
BOOL fActiveDesktop;
} COMPONENTSOPT;
Contains the desktop item options.
typedef _tagCOMPPOS {
DWORD dwSize;
int iLeft;
int iTop;
DWORD dwWidth;
DWORD dwHeight;
int izIndex;
BOOL fCanResize;
BOOL fCanResizeX;
BOOL fCanResizeY;
int iPreferredLeftPercent;
int iPreferredTopPercent;
} COMPPOS;
Contains the position information for a desktop item.
typedef struct _tagWALLPAPEROPT {
DWORD dwSize;
DWORD dwStyle;
} WALLPAPEROPT;
Contains the wallpaper options.
| WPSTYLE_CENTER |
| WPSTYLE_TILE |
| WPSTYLE_STRETCH |
| WPSTYLE_MAX |
This section contains the flags used by the methods of the IActiveDesktop interface.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.