Active Desktop Interface

Active Desktop Interface


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.

arrowy.gifOverview of the Active Desktop Interface

arrowy.gifActiveDesktop Object

arrowy.gifIActiveDesktop Interface

arrowy.gifMethods

arrowy.gifStructures

arrowy.gifFlags

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.

Accessing the Active Desktop

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();

Adding a Desktop Item

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);

Enumerating the Desktop Items

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();

ActiveDesktop Object

This section contains the reference information for the ActiveDesktop object.

Active Desktop

CLSID_ActiveDesktop

Manages the Active Desktop. Has one interface, IActiveDesktop.

IActiveDesktop Interface

This section contains the reference information for the IActiveDesktop interface and its methods.

IActiveDesktop

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.

Methods

This section describes the methods exposed by the IActiveDesktop interface.

IActiveDesktop::AddDesktopItem

HRESULT AddDesktopItem(
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Adds a desktop item.

pcomp
Address of the COMPONENT structure associated with the item to be added.
dwReserved
Reserved. Must be set to zero.

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.

IActiveDesktop::AddDesktopItemWithUI

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.

hwnd
Handle of the parent window. If NULL, the desktop item will be added without displaying any user interface.
pcomp
Address of the COMPONENT structure containing the details of the desktop item to be added.
dwReserved
Reserved. Must be set to zero.

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.

IActiveDesktop::AddUrl

HRESULT AddUrl(
    HWND hwnd,
    LPCWSTR pszSource,
    LPCOMPONENT pcomp,
    DWORD dwFlags
);

Adds the desktop item associated with the specified URL.

hwnd
Handle to the parent window for the user interface.
pszSource
String containing the URL of the desktop item.
pcomp
Address of the COMPONENT structure containing the details of the desktop item to be added.
dwFlags
Unsigned long integer value that controls this method. Can be set to ADDURL_SILENT to add a desktop item without displaying any user interfaces.

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.

IActiveDesktop::ApplyChanges

HRESULT ApplyChanges(
    DWORD dwFlags
);

Applies changes to the Active Desktop and saves them in the registry.

dwFlags
Unsigned long integer value that contains the changes to be applied. Can be one of the following values:
AD_APPLY_SAVE
AD_APPLY_HTMLGEN
AD_APPLY_REFRESH
AD_APPLY_ALL
AD_APPLY_FORCE

IActiveDesktop::GenerateDesktopItemHtml

HRESULT GenerateDesktopItemHtml(
    LPCWSTR pwszFileName,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Generates a generic HTML page containing the given desktop item.

pwszFileName
String value containing the name to store the HTML file under.
pcomp
Address of the COMPONENT structure of the desktop item to insert in the HTML page.
dwReserved
Reserved. Must be set to zero.

IActiveDesktop::GetDesktopItem

HRESULT GetDesktopItem(
    int nComponent,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Retrieves the specified desktop item.

nComponent
Unsigned long integer value that contains the desktop item's index. The index values start at zero. Use IActiveDesktop::GetDesktopItemCount to get a count on the total number of desktop items.
pcomp
Address of the COMPONENT structure of the retrieved desktop item.
dwReserved
Reserved. Must be set to zero.

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.

IActiveDesktop::GetDesktopItemByID

HRESULT GetComponentByID(
    DWORD dwID,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Retrieves the desktop item that matches the given identification.

dwID
Unsigned long integer value that contains the desktop item's identification.
pcomp
Address of the COMPONENT structure of the retrieved desktop item.
dwReserved
Reserved. Must be set to zero.

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.

IActiveDesktop::GetDesktopItemBySource

HRESULT GetDesktopItemBySource (
    LPCWSTR pszSource,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Retrieves a desktop item using its source URL.

pszSource
String value containing the source URL of the desktop item.
pcomp
Address of the COMPONENT structure that will be used to store the details about the desktop item. The size of the structure must be initialized in order for it to work properly.
dwReserved
Reserved. Must be set to zero.

IActiveDesktop::GetDesktopItemCount

HRESULT GetDesktopItemCount(
    LPINT lpiCount,
    DWORD dwReserved
);

Retrieves a count of the desktop items.

lpiCount
Address of an integer value that contains the count.
dwReserved
Reserved. Must be set to zero.

The lpiCount value can be used to enumerate all desktop items. The index values start at 0 and go to lpiCount minus one.

IActiveDesktop::GetDesktopItemOptions

HRESULT GetDesktopItemOptions(
    LPCOMPONENTSOPT pco
    DWORD dwReserved
);

Retrieves the desktop item's options.

pco
Address of the COMPONENTSOPT structure containing the options that are currently set.
dwReserved
Reserved. Must be set to zero.

IActiveDesktop::GetPattern

HRESULT GetPattern(
    LPWSTR pwszPattern,
    UINT cchPattern,
    DWORD dwReserved
);

Retrieves the pattern currently being used.

pwszPattern
String value that contains a string of decimals whose bit pattern represents a picture.
cchPattern
Unsigned long integer value that contains the size of the string.
dwReserved
Reserved. Must be set to zero.

IActiveDesktop::GetWallpaper

HRESULT GetWallpaper(
    LPWSTR pwszWallpaper,
    UINT cchWallpaper,
    DWORD dwReserved
);

Retrieves the wallpaper currently being used.

pwszWallpaper
String value that contains the filename of the wallpaper.
cchWallpaper
Unsigned integer value that contains size of the string.
dwReserved
Reserved. Must be set to zero.

IActiveDesktop::GetWallpaperOptions

HRESULT GetWallpaperOptions(
    LPWALLPAPEROPT pwpo,
    DWORD dwReserved
);

Retrieves the wallpaper options.

pwpo
Address of a WALLPAPEROPT structure containing the options currently set.
dwReserved
Reserved. Must be set to zero.

IActiveDesktop::ModifyDesktopItem

HRESULT ModifyDesktopItem(
    LPCCOMPONENT pcomp,
    DWORD dwFlags
);

Modifies the desktop item.

pcomp
Address of the COMPONENT structure containing the modifications. The desktop item associated with the wszSource member of the structure will be modified.
dwFlags
Unsigned long integer value containing the flags used for the modification. Can be one of the following values:
AD_APPLY_SAVE
AD_APPLY_HTMLGEN
AD_APPLY_REFRESH
AD_APPLY_ALL
AD_APPLY_FORCE

IActiveDesktop::RemoveDesktopItem

HRESULT RemoveDesktopItem(
    LPCCOMPONENT pcomp,
    DWORD dwReserved
);

Removes the specified desktop item from the desktop.

pcomp
Address of the COMPONENT structure that specifies the item to be removed. The desktop item associated with the wszSource member of the structure will be removed.
dwReserved
Reserved. Must be set to zero.

IActiveDesktop::SetDesktopItemOptions

HRESULT SetDesktopItemOptions(
    LPCCOMPONENTSOPT pcomp,
    DWORD dwReserved
);

Sets the item's options.

pcomp
Address of the COMPONENTSOPT structure that contains the options to set.
dwReserved
Reserved. Must be set to zero.

IActiveDesktop::SetPattern

HRESULT SetPattern(
    LPCWSTR pwszPattern,
    DWORD dwReserved
);

Sets the Active Desktop pattern.

pwszPattern
String value that contains a string of decimals whose bit patern represents a picture.
dwReserved
Reserved. Must be set to zero.

IActiveDesktop::SetWallpaper

HRESULT SetWallpaper(
    LPCWSTR pwszWallpaper,
    DWORD dwReserved
);

Sets the wallpaper for the Active Desktop.

pwszWallpaper
String value containing the filename of the wallpaper to be set.
dwReserved
Reserved. Must be set to zero.

IActiveDesktop::SetWallpaperOptions

HRESULT SetWallpaperOptions(
    LPCWALLPAPEROPT pwpo,
    DWORD dwReserved
);

Sets the wallpaper options.

pwpo
Address of the WALLPAPEROPT structure containing the options to be set.
dwReserved
Reserved. Must be set to zero.

Structures

This section describes the structures used by the methods of the IActiveDesktop interface.
COMPONENT
COMPONENTSOPT
COMPPOS
WALLPAPEROPT

COMPONENT

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.

dwSize
Unsigned long integer value that contains the size of the structure.
dwID
Reserved. Must be set to zero. Will contain the desktop item's identification number when returned from IActiveDesktop::GetDesktopItem.
iComponentType
Integer value that indicates the item type. Can be one of the following values:
COMP_TYPE_CFHTML
COMP_TYPE_CONTROL
COMP_TYPE_HTMLDOC
COMP_TYPE_MAX
COMP_TYPE_PICTURE
COMP_TYPE_WEBSITE
fChecked
Boolean value that indicates whether the component is enabled.
fDirty
Boolean value that indicates whether the component has been modified, but has not been saved yet.
fNoScroll
Boolean value that indicates whether the component is scrollable.
cpPos
COMPPOS structure that contains the position information of the item.
wszFriendlyName
Wide character string that contains the friendly name of the item.
wszSource
Wide character string that contains the URL of the item.

COMPONENTSOPT

typedef struct _tagCOMPONENTSOPT {
    DWORD dwSize;
    BOOL fEnableComponents;
    BOOL fActiveDesktop;
} COMPONENTSOPT;

Contains the desktop item options.

dwSize
Unsigned long integer value that contains the size of the structure.
fEnableComponents
Boolean value that determines if desktop items are enabled.
fActiveDesktop
Boolean value that determines if the Active Desktop is enabled.

COMPPOS

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.

dwSize
Unsigned long integer value that contains the size of the structure.
iLeft
Integer value that contains the horizontal location of the top-left corner of the item, in pixels.
iTop
Integer value that contains the vertical location of the top-left corner of the item, in pixels.
dwWidth
Unsigned long integer value that contains the width of the item, in pixels.
dwHeight
Unsigned long integer value that contains the height of the item, in pixels.
izIndex
Integer value that indicates the z-order of the item.
fCanResize
Boolean value that determines if the item can be resized.
fCanResizeX
Boolean value that determines if the width of the item is adjustable.
fCanResizeY
Boolean value that determines if the height of the item is adjustable.
iPreferredLeftPercent
Integer value that indicates the preferred horizontal distance between the top-left corner of the screen and the top-left corner of the item as a percentage of the screen.
iPreferredTopPercent
Integer value that indicates the preferred vertical distance between the top-left corner of the screen and the top-left corner of the item as a percentage of the screen.

WALLPAPEROPT

typedef struct _tagWALLPAPEROPT {
    DWORD dwSize;
    DWORD dwStyle;
} WALLPAPEROPT;

Contains the wallpaper options.

dwSize
Unsigned long integer value that contains the size of the WALLPAPEROPT structure.
dwStyle
Unsigned long integer value that contains the wallpaper style. Can be one of the following values:
WPSTYLE_CENTER
WPSTYLE_TILE
WPSTYLE_STRETCH
WPSTYLE_MAX

Flags

This section contains the flags used by the methods of the IActiveDesktop interface.

AD_APPLY_ALL
Aggregate of the AD_APPLY_SAVE, AD_APPLY_HTMLGEN, and AD_APPLY_REFRESH values.
AD_APPLY_BUFFERED_REFRESH
AD_APPLY_FORCE
Force an Active Desktop change.
AD_APPLY_HTMLGEN
Regenerate the desktop HTML file.
AD_APPLY_REFRESH
Refresh the desktop item.
AD_APPLY_SAVE
Save the desktop item.
COMP_ELEM_ALL
Aggregate of the COMP_ELEM_* values.
COMP_ELEM_CHECKED
The item has been checked.
COMP_ELEM_DIRTY
The item has been changed, but the changes have not been saved.
COMP_ELEM_FRIENDLYNAME
The friendly name of the item.
COMP_ELEM_NOSCROLL
The item is not scrollable.
COMP_ELEM_POS_LEFT
The horizontal position of the item.
COMP_ELEM_POS_TOP
The vertical position of the item.
COMP_ELEM_POS_ZINDEX
The z-index of the item.
COMP_ELEM_SIZE_HEIGHT
The height of the item.
COMP_ELEM_SIZE_WIDTH
The width of the item.
COMP_ELEM_SOURCE
The original source of the item.
COMP_ELEM_TYPE
The item type.
COMP_TYPE_CFHTML
Compressed format HTML.
COMP_TYPE_CONTROL
The item is a control.
COMP_TYPE_HTMLDOC
The item is an HTML document.
COMP_TYPE_MAX
The maximum value of a COMP_TYPE_* flag.
COMP_TYPE_PICTURE
The item is a picture.
COMP_TYPE_WEBSITE
The item is a Web site.
COMPONENT_TOP
An izOrder value meaning the item is at the top.
WPSTYLE_CENTER
The wallpaper is centered.
WPSTYLE_MAX
The maximum value of a WPSTYLE_* flag.
WPSTYLE_STRETCH
The wallpaper is stretched to fit the entire screen.
WPSTYLE_TILE
The wallpaper is tiled.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.