
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.
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
HRESULT QueryActiveShellView(
IShellView **ppshv
);
Returns the currently active (displayed) shell view object.
Notes to Callers
Because the IShellBrowser interface can host several shell views simultaneously, this method provides an easy way to determine the active shell view object.
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.
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
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.
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
RESULT SetMenuSB(
HMENU hmenuShared,
HOLEMENU holemenuReserved
);
Installs the composite menu in the view window.
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
HRESULT SetStatusTextSB(
LPCOLESTR lpszStatusText
);
Sets and displays status text about the in-place object in the container's frame-window status bar.
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
HRESULT SetToolbarItems(
LPTBBUTTON lpButtons,
UINT nButtons,
UINT uFlags
);
Adds toolbar items to Windows Explorer's toolbar.
| 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
HRESULT TranslateAcceleratorSB(
LPMSG lpmsg,
WORD wID
);
Translates accelerator keystrokes intended for the browser's frame while the view is active.
This method is similar to the IOleInPlaceFrame::TranslateAccelerator method.
See also IShellBrowser
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. |
HRESULT Execute(
LPSHELLEXECUTEINFO pei
);
Called when ShellExecute or ShellExecuteEx is called for an object that is registered.
| S_OK | The hook processed the execution. ShellExecute or ShellExecuteEx should not perform any other processing. |
| S_FALSE | The hook is installed but did not process the execution. ShellExecute or ShellExecuteEx should perform the default processing. |
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
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. |
HRESULT Initialize(
LPCITEMIDLIST pidlFolder,
LPDATAOBJECT lpdobj,
HKEY hkeyProgID
);
Initializes a property sheet extension, context menu extension, or drag-and-drop handler.
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
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. |
HRESULT BindToObject(
LPCITEMIDLIST pidl,
LPBC pbcReserved,
REFIID riid,
LPVOID *ppvOut
);
Retrieves an IShellFolder object for a subfolder.
Use this method to access the COM interface to the subfolder or subobject.
See also SHGetDesktopFolder
Reserved for future use. This method should return E_NOTIMPL.
HRESULT CompareIDs(
LPARAM lParam,
LPCITEMIDLIST pidl1,
LPCITEMIDLIST pidl2
);
Determines the relative order of two file objects or folders, given their item identifier lists.
| Less than zero | The first item should precede the second (pidl1 < pidl2). |
| Greater than zero | The first item should follow the second (pidl1 > pidl2). |
| Zero | The two items are the same (pidl1 = pidl2). |
If this method is unsuccessful, it returns an OLE-defined error code.
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
HRESULT CreateViewObject(
HWND hwndOwner,
REFIID riid,
LPVOID *ppvOut
);
Creates a view object of a folder.
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
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.
The calling application must free the returned IEnumIDList object by calling its Release method.
See also IShellFolder, SHGetDesktopFolder
HRESULT GetAttributesOf(
UINT cidl,
LPCITEMIDLIST *apidl,
ULONG *rgfInOut
);
Retrieves the attributes of one or more file objects or subfolders.
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
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.
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
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.
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
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.
This method is similar to the IParseDisplayName::ParseDisplayName method defined by OLE.
See also IShellFolder, IShellLink
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.
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
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. |
HRESULT GetIconOf(
LPCITEMIDLIST pidl,
UINT flags,
LPINT lpIconIndex
);
Retrieves an icon for an object inside a specific folder.
| 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. |
| 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.