IShellBrowser::OnViewWindowActive
Interfaces

IShellBrowser::OnViewWindowActive


HRESULT OnViewWindowActive(
    IShellView *ppshv
   );	

Called by the shell view when the view window or one of its child windows gets the focus or becomes active.

ppshv
Address of the view object's IShellView pointer.

The view must pass its IShellView implementation to this routine, although the current version of Windows Explorer does not use this parameter.

Notes to Callers

The shell view object must call this method before calling the IShellBrowser::InsertMenusSB method. This method will insert a different set of menu items depending on whether the view has the focus.

Notes to Implementers

This method informs the browser that the view is getting the focus (when the mouse is clicked on the view, for example).

See also IShellBrowser

IShellBrowser::QueryActiveShellView

HRESULT QueryActiveShellView(
    IShellView **ppshv
   );	

Returns the currently active (displayed) shell view object.

ppshv
Address of the pointer to the currently active shell view object.

IShellBrowser::RemoveMenusSB

HRESULT RemoveMenusSB(
    HMENU hmenuShared
   );	

Permits the container to remove any of its menu elements from the in-place composite menu and to free all associated resources.

hmenuShared
Handle to the in-place composite menu that was constructed by calls to IShellBrowser::InsertMenusSB and the Microsoft® Win32® InsertMenu function.

This method is similar to the IOleInPlaceFrame::RemoveMenus method.

The object should always permit the container to remove its menu elements from the composite menu before deactivating the shared user interface.

Notes to Callers

The method is called by the object application while it is being UI-deactivated so the browser can remove its menus.

See also IShellBrowser

IShellBrowser::SendControlMsg

HRESULT SendControlMsg(
    UINT id,
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam,
    LRESULT *pret
   );	

Sends control messages to either the toolbar or the status bar in an Explorer window.

id
Identifier for either a toolbar (FCW_TOOLBAR) or for a status bar window (FCW_STATUS).
uMsg
Message to be sent to the control.
wParam
Value depends on the message specified in the uMsg parameter.
lParam
Value depends on the message specified in the uMsg parameter.
pret
Address of the return value of the SendMessage function.

Refer to the Common Controls documentation for more information on the messages that can be sent to the toolbar or status bar control.

Notes to Callers

Use of this call requires diligent attention, because leaving either the status bar or toolbar in an inappropriate state will affect the performance of Windows Explorer.

Notes to Implementers

If your Windows Explorer does not have these controls, you can return E_NOTIMPL.

See also IShellBrowser

IShellBrowser::SetMenuSB

RESULT SetMenuSB(
    HMENU hmenuShared,
    HOLEMENU holemenuReserved
   );	

Installs the composite menu in the view window.

hmenuShared
Handle to the composite menu constructed by calls to IShellBrowser::InsertMenusSB and the Win32 InsertMenu function.
holemenuReserved
Reserved for future use.

This method is similar to the IOleInPlaceFrame::SetMenu method. However, Windows Explorer performs menu dispatch based on the menu item identifier.

The availability of specific menu items depends on whether the view has the focus. Accordingly, it is necessary to call the IShellBrowser::OnViewWindowActive method whenever the view window (or one of its child windows) has the focus.

Notes to Callers

The object calls IShellBrowser_SetMenuSB to ask the container to install the composite menu structure set up by calls to IShellBrowser::InsertMenusSB.

Notes to Implementers

A container's implementation of this method should call the Windows SetMenu function.

See also IShellBrowser

IShellBrowser::SetStatusTextSB

HRESULT SetStatusTextSB(
    LPCOLESTR lpszStatusText
   );	

Sets and displays status text about the in-place object in the container's frame-window status bar.

lpszStatusText
Address of a null-terminated character string to contain the message to display.

It is also possible to send messages directly to the status window by using the IShellBrowser::SendControlMsg method.

Notes to Callers

Use this method to set the contents of the status bar.

See also IShellBrowser

IShellBrowser::SetToolbarItems

HRESULT SetToolbarItems(
    LPTBBUTTON lpButtons,
    UINT nButtons,
    UINT uFlags
   );	

Adds toolbar items to Windows Explorer's toolbar.

lpButtons
Address of an array of TBBUTTON structures.
nButtons
Number of TBBUTTON structures in the lpButtons array.
uFlags
Flags specifying where the toolbar buttons should go. This parameter can be one or more of the following values:
FCT_ADDTOEND Add at the right side of the toolbar.
FCT_CONFIGABLE Not implemented.
FCT_MERGE Merge the toolbar items instead of replacing all of the buttons with those provided by the view. This is the recommended choice.

See also IShellBrowser

IShellBrowser::TranslateAcceleratorSB

HRESULT TranslateAcceleratorSB(
    LPMSG lpmsg,
    WORD wID
   );	

Translates accelerator keystrokes intended for the browser's frame while the view is active.

lpmsg
Address of an MSG structure containing the keystroke message.
wID
Command identifier value corresponding to the keystroke in the container-provided accelerator table. Containers should use this value instead of translating again.

This method is similar to the IOleInPlaceFrame::TranslateAccelerator method.

See also IShellBrowser

IShellExecuteHook

The IShellExecuteHook interface extends the behavior of the ShellExecute or ShellExecuteEx function. It is typically implemented by subsystems that expose the names of objects that the user can specify in the Run dialog box after clicking the Windows Start button.

When to Implement

You should implement IShellExecuteHook when you have named objects that the user would expect to be able to run from the Run dialog box after clicking the Windows Start button.

When to Use

You do not use this interface directly. It is generally used by the ShellExecuteEx function's code.

IShellExecuteHook Method Description
Execute Called when ShellExecute or ShellExecuteEx is called for an object that is registered.

IShellExecuteHook::Execute

HRESULT Execute(
    LPSHELLEXECUTEINFO pei
   );	

Called when ShellExecute or ShellExecuteEx is called for an object that is registered.

pei
Address of a SHELLEXECUTEINFO structure that contains information about the object being executed. On successful completion of the hook, the hInstApp member will be filled in by the hook.

This method provides an opportunity for the application to hook the execution of an object and change the default execution or perform some other action before the object is executed.

See also IShellExecuteHook

IShellExtInit

The IShellExtInit interface is used to initialize shell extensions for property sheets, context menus, and drag-and-drop handlers (extensions that add items to context menus during nondefault drag-and-drop operations).

When to Implement

Implement IShellExtInit when you are writing a handler based on the IContextMenu or IShellPropSheetExt interface.

Note that shell extensions based on other interfaces do not use this method of initialization.

When to Use

You do not use this interface directly. The shell calls it to initialize the handler.

IShellExtInit Method Description
Initialize Initializes the shell extension.

IShellExtInit::Initialize

HRESULT Initialize(
    LPCITEMIDLIST pidlFolder,
    LPDATAOBJECT lpdobj,
    HKEY hkeyProgID
   );	

Initializes a property sheet extension, context menu extension, or drag-and-drop handler.

pidlFolder
Address of an ITEMIDLIST structure that uniquely identifies a folder. For property sheet extensions, this parameter is NULL. For context menu extensions, it is the item identifier list for the folder that contains the item whose context menu is being displayed. For nondefault drag-and-drop menu extensions, this parameter specifies the target folder.
lpdobj
Address of an IDataObject interface object that can be used to retrieve the objects being acted upon.
hkeyProgID
Registry key for the file object or folder type.

The meanings of some parameters depend on the extension type. For drag-and-drop handlers, the pidlFolder parameter specifies the destination folder (the drop target), the lpdobj parameter identifies the items being dropped, and the hkeyProgID parameter specifies the file class of the destination folder.

For context menu extensions, pidlFolder specifies the folder that contains the selected file objects, lpdobj identifies the selected file objects, and hkeyProgID specifies the file class of the file object that has the focus.

For property sheet extensions, pidlFolder is NULL, lpdobj identifies the selected file objects, and hkeyProgID specifies the file class of the file object that has the focus.

Notes to Implementers

This is the first method that the shell calls after it creates an instance of a property sheet extension, context menu extension, or drag-and-drop handler.

See also IShellExtInit

IShellFolder

The IShellFolder interface is used to manage folders.

When to Implement

Implement this interface for objects that extend the shell's namespace. For example, implement this interface to create a separate namespace that requires a rooted Windows Explorer or to install a new namespace directly within the hierarchy of the system namespace. You are most familiar with the contents of your namespace, so you are responsible for implementing everything needed to access your data.

When to Use

Use this interface when you need to display or perform an operation on the contents of the shell's namespace. Objects that support IShellFolder are usually created by other shell folder objects, with the root object (the Desktop shell folder) being returned from the SHGetDesktopFolder function.

IShellFolder Methods Description
BindToObject Retrieves the IShellFolder interface for the specified subfolder.
BindToStorage Returns the storage instance of a subfolder. Not currently implemented.
CompareIDs Determines the relative order of two file objects or folders, given their item identifier lists.
CreateViewObject Creates a view object of the folder itself.
EnumObjects Enumerates the objects in a folder.
GetAttributesOf Retrieves the attributes of the specified file object or subfolder.
GetDisplayNameOf Retrieves the display name of a file object or subfolder.
GetUIObjectOf Creates an OLE interface that can be used to carry out operations on a file object or subfolder.
ParseDisplayName Translates a display name into an item identifier list.
SetNameOf Sets the display name of the specified file object or subfolder and changes its identifier accordingly.

IShellFolder::BindToObject

HRESULT BindToObject(
    LPCITEMIDLIST pidl,
    LPBC pbcReserved,
    REFIID riid,
    LPVOID *ppvOut
   );	

Retrieves an IShellFolder object for a subfolder.

pidl
Address of an ITEMIDLIST structure that identifies the subfolder relative to its parent folder.
pbcReserved
Reserved. Callers should specify NULL for this parameter; those called should ignore it.
riid
Identifier of the interface to return. This parameter must point to the IID_IShellFolder interface identifier.
ppvOut
Address that receives the interface pointer. If an error occurs, a NULL pointer is returned in this address.

Use this method to access the COM interface to the subfolder or subobject.

See also SHGetDesktopFolder

IShellFolder::BindToStorage

Reserved for future use. This method should return E_NOTIMPL.

IShellFolder::CompareIDs

HRESULT CompareIDs(
    LPARAM lParam,
    LPCITEMIDLIST pidl1,
    LPCITEMIDLIST pidl2
   );	

Determines the relative order of two file objects or folders, given their item identifier lists.

lParam
Value specifying the type of comparison to perform. The calling application should always specify zero, indicating that the two items should be sorted by name.
pidl1 and pidl2
Addresses of ITEMIDLIST structures that uniquely identify the items to compare. Both item identifier lists are relative to this folder. These ITEMIDLIST structures may contain more than one element; therefore, the entire ITEMIDLIST must be compared and not just the first element.

Passing zero for lParam indicates a sort by name. Values ranging from 0x00000001 to 0x7fffffff are for folder-specific sorting rules, while values ranging from 0x80000000 to 0xfffffff are used for system-specific rules.

See also IShellFolder

IShellFolder::CreateViewObject

HRESULT CreateViewObject(
    HWND hwndOwner,
    REFIID riid,
    LPVOID *ppvOut
   );	

Creates a view object of a folder.

hwndOwner
Handle to the owner window from which to create the view object.
riid
Identifier of the interface to return.
ppvOut
Address of a pointer to the view object.

It is important to remember that the COM object created by CreateViewObject must be a different object than the shell folder object. Windows Explorer may call this method more than once to create multiple view objects, and each of these must behave as independent objects. A new view object must be created for each call.

See also IShellFolder

IShellFolder::EnumObjects

HRESULT EnumObjects(
    HWND hwndOwner,
    DWORD grfFlags,
    LPENUMIDLIST *ppenumIDList
   );	

Determines the contents of a folder by creating an item enumeration object (a set of item identifiers) that can be retrieved using the IEnumIDList interface.

hwndOwner
Handle to the owner window that the client should specify if it displays a dialog box or message box.
grfFlags
Flags indicating which items to include in the enumeration. For a list of possible values, see the SHCONTF enumerated type.
ppenumIDList
Address that receives a pointer to the IEnumIDList interface created by this method. If an error occurs, a NULL pointer is returned in this address.

The calling application must free the returned IEnumIDList object by calling its Release method.

See also IShellFolder, SHGetDesktopFolder

IShellFolder::GetAttributesOf

HRESULT GetAttributesOf(
    UINT cidl,
    LPCITEMIDLIST *apidl,
    ULONG *rgfInOut
   );	

Retrieves the attributes of one or more file objects or subfolders.

cidl
Number of file objects from which to retrieve attributes.
apidl
Address of an array of pointers to ITEMIDLIST structures, each of which uniquely identifies a file object relative to the parent folder. Each ITEMIDLIST structure must contain exactly one SHITEMID structure followed by a terminating zero.
rgfInOut
Address of a single ULONG value that, on entry, contains the attributes that the caller is requesting. On exit, this value contains the requested attributes that are common to all of the specified objects. Note that this is the address of a single ULONG value, not an array of ULONG values. The lists below describe the possible flags for this parameter.

A file object's capability flags may be zero or a combination of the following values:
SFGAO_CANCOPY The specified file objects or folders can be copied (same value as the DROPEFFECT_COPY flag).
SFGAO_CANDELETE The specified file objects or folders can be deleted.
SFGAO_CANLINK It is possible to create shortcuts for the specified file objects or folders (same value as the DROPEFFECT_LINK flag).
SFGAO_CANMOVE The specified file objects or folders can be moved (same value as the DROPEFFECT_MOVE flag).
SFGAO_CANRENAME The specified file objects or folders can be renamed.
SFGAO_CAPABILITYMASK Mask for the capability flags.
SFGAO_DROPTARGET The specified file objects or folders are drop targets.
SFGAO_HASPROPSHEET The specified file objects or folders have property sheets.

A file object's display attributes may be zero or a combination of the following values:
SFGAO_DISPLAYATTRMASK Mask for the display attributes.
SFGAO_GHOSTED The specified file objects or folders should be displayed using a ghosted icon.
SFGAO_LINK The specified file objects are shortcuts.
SFGAO_READONLY The specified file objects or folders are read-only.
SFGAO_SHARE The specified folders are shared.

A file object's contents flags may be zero or a combination of the following values:
SFGAO_CONTENTSMASK Mask for the contents attributes.
SFGAO_HASSUBFOLDER The specified folders have subfolders (and are, therefore, expandable in the left pane of Windows Explorer).

A file object's miscellaneous attributes may be zero or a combination of the following values:
SFGAO_BROWSABLE The specified items can be browsed in place.
SFGAO_COMPRESSED The specified items are compressed.
SFGAO_FILESYSTEM The specified folders or file objects are part of the file system (that is, they are files, directories, or root directories).
SFGAO_FILESYSANCESTOR The specified folders contain one or more file system folders.
SFGAO_FOLDER The specified items are folders.
SFGAO_NEWCONTENT The objects contain new content.
SFGAO_NONENUMERATED The items are nonenumerated items.
SFGAO_REMOVABLE The specified file objects or folders are on removable media.
SFGAO_VALIDATE Validate cached information. The shell will validate that the objects specified in apidl still exist and will not used cached information when retrieving the attributes. If one or more of the items specified in apidl no longer exist, this method will return an error code. If cidl is zero, the shell will discard all cached information for the shell folder. This is similar to doing a refresh of the folder.

You can optimize this operation by not returning unspecified flags.

See also IShellFolder

IShellFolder::GetDisplayNameOf

HRESULT GetDisplayNameOf(
    LPCITEMIDLIST pidl,
    DWORD uFlags,
    LPSTRRET lpName
   );

Retrieves the display name for the specified file object or subfolder, returning it in a STRRET structure.

pidl
Address of an ITEMIDLIST structure that uniquely identifies the file object or subfolder relative to the parent folder.
uFlags
Flags indicating the type of display name to return. For a list of possible values, see the SHGNO enumerated type.
lpName
Address of a STRRET structure in which to return the display name. The string returned in this structure depends on the type of display name requested.

If the identifier contains the display name (in the local character set), it returns the offset to the name. If not, it returns a pointer to the display name string (UNICODE) allocated by the task allocator, or it fills in a buffer. The type of string returned depends on the type of display specified. Values identifying different types of display names are contained in the SHGNO enumerated type.

See also IShellFolder

IShellFolder::GetUIObjectOf

HRESULT GetUIObjectOf(
    HWND hwndOwner,
    UINT cidl,
    LPCITEMIDLIST *apidl,
    REFIID riid,
    UINT *prgfInOut,
    LPVOID *ppvOut
   );	

Retrieves an OLE interface that can be used to carry out actions on the specified file objects or folders.

hwndOwner
Handle to the owner window that the client should specify if it displays a dialog box or message box.
cidl
Number of file objects or subfolders specified in the apidl parameter.
apidl
Address of an array of pointers to ITEMIDLIST structures, each of which uniquely identifies a file object or subfolder relative to the parent folder. Each item identifier list must contain exactly one SHITEMID structure followed by a terminating zero.
riid
Identifier of the COM interface object to return. This can be any valid interface identifier that can be created for an item. The most common identifiers used by the shell are listed in the comments at the end of this reference.
prgfInOut
Reserved.
ppvOut
Address that receives the interface pointer. If an error occurs, a NULL pointer is returned in this address.

If cidl is greater than one, the GetUIObjectOf implementation should only succeed if it can create one object for all items specified in apidl. If the implementation cannot create one object for all items, this method should fail.

The following are the most common interface identifiers the shell uses when requesting an interface from this method. The list also indicates if cidl can be greater than one for the requested interface.

Interface Identifier Allowed cidl Value
IContextMenu The cidl parameter can be greater than or equal to one.
IContextMenu2 The cidl parameter can be greater than or equal to one.
IDataObject The cidl parameter can be greater than or equal to one.
IDropTarget The cidl parameter can only be one.
IExtractIcon The cidl parameter can only be one.
IQueryInfo The cidl parameter can only be one.

See also IShellFolder

IShellFolder::ParseDisplayName

HRESULT ParseDisplayName(
    HWND hwndOwner,
    LPBC pbcReserved,
    LPOLESTR lpszDisplayName,
    ULONG *pchEaten,
    LPITEMIDLIST *ppidl,
    ULONG *pdwAttributes
   );	

Translates a file object's or folder's display name into an item identifier list.

hwndOwner
Handle to the owner window that the client should specify if it displays a dialog box or message box.
pbcReserved
Reserved; this parameter is always NULL.
lpszDisplayName
Address of a null-terminated UNICODE string specifying the display name. This parameter must be a display name for parsing—that is, a display name retrieved using the SHGDN_FORPARSING value.
pchEaten
Address of a ULONG value that receives the number of characters of the display name that was parsed.
ppidl
Address of a pointer to the new item identifier list for the object. If an error occurs, NULL is returned in this address.
The returned item identifier list specifies the relative path (from the parent folder) that corresponds to the specified display name. It contains only one SHITEMID structure followed by a terminating zero.
pdwAttributes
Address of the attributes of the file object. Can be NULL if the caller does not need attribute data.

This method is similar to the IParseDisplayName::ParseDisplayName method defined by OLE.

See also IShellFolder, IShellLink

IShellFolder::SetNameOf

HRESULT SetNameOf(
    HWND hwndOwner,
    LPCITEMIDLIST pidl,
    LPCOLESTR lpszName,
    DWORD uFlags,
    LPITEMIDLIST *ppidlOut
   );	

Sets the display name of a file object or subfolder, changing the item identifier in the process.

hwndOwner
Handle to the owner window of any dialog or message boxes that the client displays.
pidl
Address of an ITEMIDLIST structure that uniquely identifies the file object or subfolder relative to the parent folder.
lpszName
Address of a null-terminated string that specifies the new display name.
uFlags
Flags indicating the type of name specified by the lpszName parameter. For a list of possible values, see the description of the SHGNO enumerated type.
ppidlOut
Address of a pointer to the new ITEMIDLIST structure. This parameter can be NULL, and in that case, the method does not return the new ITEMIDLIST for the object.

If this parameter is not NULL, this method frees the specified ITEMIDLIST structure and allocates a new one using the task allocator. The calling application is responsible for freeing the new ITEMIDLIST structure. If an error occurs, the method returns NULL in this address.

Changing the display name of a file system object, or a folder within it, renames the file or directory.

See also IShellFolder

IShellIcon

The IShellIcon interface is used to obtain an icon index for an IShellFolder object. IShellIcon allows an application to obtain the icon for any object within a folder by using only one instance of the interface. IExtractIcon, on the other hand, requires that a separate instance of the interface be created for each object.

When to Implement

Implement IShellIcon when creating an IShellFolder implementation to provide a quick way to obtain the icon for an object in the folder.

If IShellIcon is not implemented by an IShellFolder object, IShellFolder::GetUIObjectOf is used to get an icon for all objects.

When to Use

Use IShellIcon when retrieving the icon index for an item in a shell folder.

IShellIcon Method Description
GetIconOf Retrieves an icon for an object in a folder.

IShellIcon::GetIconOf

HRESULT GetIconOf(
    LPCITEMIDLIST pidl,
    UINT flags,
    LPINT lpIconIndex
   );	

Retrieves an icon for an object inside a specific folder.

pidl
Address of the ITEMIDLIST structure that specifies the relative location of the folder.
flags
Flags specifying how the icon is to display. This parameter can be zero or one of the following values:
GIL_FORSHELL The icon is to be displayed in a shell folder.
GIL_OPENICON The icon should be in the open state if both open- and closed-state images are available. If this flag is not specified, the icon should be in the normal or closed state. This flag is typically used for folder objects.
lpIconIndex
Address of the index of the icon in the system image list. The following standard image list indexes can be returned:
0 Document (blank page, not associated)
1 Document (with data on the page)
2 Application (file extension must be .exe, .com, or .bat)
3 Folder (plain)
4 Folder (open)

If you are unable to get an icon for this object using GetIconOf, use the IShellFolder::GetUIObjectOf method to get an object that supports the IExtractIcon::Extract method.

Notes to Callers

The index returned is from the system image list.

Notes to Implementers

If the icon index used is not one of the standard images listed, it is the implementer's responsibility to add the image to the system image list and then place the index into the lpIconIndex parameter. To prevent the system image list from growing too large, each image should only be added once.

See also IShellIcon

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