
This section describes the Microsoft® Windows® shell interfaces.
| ICommDlgBrowser |
| IContextMenu |
| IContextMenu2 |
| IContextMenu3 |
| ICopyHook |
| IDeskBand |
| IDockingWindow |
| IDockingWindowFrame |
| IDockingWindowSite |
| IEnumIDList |
| IExtractIcon |
| IFileViewer |
| IFileViewerSite |
| IInputObject |
| IInputObjectSite |
| INewShortcutHook |
| INotifyReplica |
| IPersistFolder |
| IQueryInfo |
| IReconcilableObject |
| IReconcileInitiator |
| IShellBrowser |
| IShellChangeNotify (No documentation available at this time) |
| IShellExecuteHook |
| IShellExtInit |
| IShellFolder |
| IShellIcon |
| IShellIconOverlay (No documentation available at this time) |
| IShellIconOverlayIdentifier (No documentation available at this time) |
| IShellLink |
| IShellPropSheetExt |
| IShellView |
| IShellView2 (No documentation available at this time) |
| ITaskbarList |
| IURLSearchHook |
The ICommDlgBrowser interface is used by the common file dialog boxes to extend the behavior of the shell browser. This interface is obtained by calling QueryInterface on the IShellBrowser object.
When to Implement
This interface is implemented only by the common file dialog boxes.
When to Use
Use ICommDlgBrowser when you need to provide special behavior while hosted inside the common dialog boxes.
| ICommDlgBrowser Methods | Description |
| IncludeObject | Allows the common dialog to filter objects that the view displays. |
| OnDefaultCommand | Called when a user double-clicks in the view or presses the ENTER key. |
| OnStateChange | Called after a change of state has occurred in a common dialog box. |
HRESULT IncludeObject(
IShellView * ppshv,
LPCITEMIDLIST pidl
);
Allows the common dialog to filter objects that the view displays.
This method is called by the IEnumIDList implementation when hosted in the file dialogs. The enumerator should call this method to let the common dialog filter out objects that should not be displayed. Typically, the file dialogs will get the display text of the item, and filter by the extension.
Notes to Callers
Call before returning an object in the shell folder's IDLIST enumerator.
See also ICommDlgBrowser
HRESULT OnDefaultCommand(
IShellView * ppshv
);
Called when a user double-clicks in the view or presses the ENTER key.
The browser should return S_OK if it has processed the action or S_FALSE to let the view perform the default action.
Note to Callers
This method allows the default command to be handled by the common dialog box instead of the view.
See also ICommDlgBrowser
HRESULT OnStateChange(
IShellView * ppshv,
ULONG uChange
);
Called after a state, identified by the uChange parameter, has changed in the IShellView interface.
| CDBOSC_SETFOCUS | The focus has been set to the view. |
| CDBOSC_KILLFOCUS | The view has lost the focus. |
| CDBOSC_SELCHANGE | The selection has changed. |
| CDBOSC_RENAME | An item has been renamed. |
This method is used to let the common file dialogs track the state of the view and change its user interface as needed.
Notes to Callers
When items in the view are selected, or when the view loses the focus, it needs to call this method to notify the common dialog that either the view state or selection state is changing.
See also ICommDlgBrowser
The IContextMenu interface is used to either create or merge a context menu associated with a certain object.
Default context menus are available for most objects that are visible within Windows Explorer's namespace, such as files, folders, and printer objects. System-provided context menus are adaptable to file objects of any type, provided you have made the appropriate registry entries.
When to Implement
Implement IContextMenu in the following situations:
Shell extensions based on this interface must be initialized by using the IShellExtInit interface.
Also note that shell extensions do not work unless all appropriate registry entries are made.
When to Use
You do not call this interface directly. It is called by the shell when a user chooses a context menu item that has been added by a handler registered under the appropriate registry keys or when an application includes it as the riid parameter in a call to IShellFolder::GetUIObjectOf.
| IContextMenu Methods | Description |
| GetCommandString | Retrieves the language-independent name of a menu command or the Help text for a menu command. |
| InvokeCommand | Carries out a menu command. For an example, see the IExtractIcon interface. |
| QueryContextMenu | Adds commands to a context menu. |
HRESULT GetCommandString(
UINT idCmd,
UINT uFlags,
UINT *pwReserved,
LPSTR pszName,
UINT cchMax
);
Retrieves the language-independent command string or the Help text for a context menu item.
| GCS_HELPTEXT | Returns the Help text for the menu item. |
| GCS_VALIDATE | Validates that the menu item exists. |
| GCS_VERB | Returns the language-independent command name for the menu item. |
The language-independent command name can be passed to the IContextMenu::InvokeCommand method to activate a command by an application. The Help text is a description that Windows Explorer displays in its status bar; it should be reasonably short (under 40 characters).
See also IContextMenu
HRESULT InvokeCommand(
LPCMINVOKECOMMANDINFO lpici
);
Carries out the command associated with a context menu item.
The shell calls this method when the user chooses a command that the handler added to a context menu. This method may also be called by an application without any corresponding user action.
See also IContextMenu
HRESULT QueryContextMenu(
HMENU hmenu,
UINT indexMenu,
UINT idCmdFirst,
UINT idCmdLast,
UINT uFlags
);
Adds menu items to the specified menu. The menu items should be inserted in the menu at the position specified by indexMenu, and their menu item identifiers must be between the idCmdFirst and idCmdLast parameter values.
| CMF_CANRENAME | This flag is set if the calling application supports renaming of items. A context menu extension or drag-and-drop handler should ignore this flag. A namespace extension should add a rename item to the menu if applicable. |
| CMF_DEFAULTONLY | This flag is set when the user is activating the default action, typically by double-clicking. This flag provides a hint for the context menu extension to add nothing if it does not modify the default item in the menu. A context menu extension or drag-and-drop handler should not add any menu items if this value is specified. A namespace extension should add only the default item (if any). |
| CMF_EXPLORE | This flag is set when Windows Explorer's tree window is present. Context menu handlers should ignore this value. |
| CMF_INCLUDESTATIC | This flag is set when a static menu is being constructed. Only the browser should use this flag. All other context menu extensions should ignore this flag. |
| CMF_NODEFAULT | This flag is set if no item in the menu should be the default item. A context menu extension or drag-and-drop handler should ignore this flag. A namespace extension should not set any of the menu items to the default. |
| CMF_NORMAL | Indicates normal operation. A context menu extension, namespace extension, or drag-and-drop handler can add all menu items. |
| CMF_NOVERBS | This flag is set for items displayed in the "Send To:" menu. Context menu handlers should ignore this value. |
| CMF_VERBSONLY | This flag is set if the context menu is for a shortcut object. Context menu handlers should ignore this value. |
The remaining bits of the low-order word are reserved by the system. The high-order word may be used for context-specific communications. The CMF_RESERVED value can be used to mask out the low-order word.
The actual identifier of each menu item should be idCmdFirst plus a menu identifier offset in the range zero through (idCmdLast idCmdFirst).
See also IContextMenu
The IContextMenu2 interface is used to either create or merge a context menu associated with a certain object when the menu involves owner-drawn menu items.
When to Implement
Implement IContextMenu2 if your context menu extension needs to process one or more of the following messages:
| WM_INITMENUPOPUP |
| WM_DRAWITEM |
| WM_MEASUREITEM |
These messages are forwarded to IContextMenu2through the HandleMenuMsg methodonly if a QueryInterface call for an IContextMenu2 interface pointer is successful, indicating that the object supports this interface.
When to Use
You do not call this interface directly. IContextMenu2 is used by the operating system only when it has confirmed that your application is aware of this interface.
IContextMenu2 is derived from IUnknown. The following methods are specific to IContextMenu2.
| IContextMenu2 Methods | Description |
| GetCommandString | Retrieves the language-independent name of a menu command or the Help text for a menu command. |
| HandleMenuMsg | Handles messages related to drawing owner-drawn menu items. |
| InvokeCommand | Carries out a menu command. For an example, see the IExtractIcon interface. |
| QueryContextMenu | Adds commands to a context menu. |
HRESULT GetCommandString(
UINT idCmd,
UINT uFlags,
UINT *pwReserved,
LPSTR pszName,
UINT cchMax
);
Retrieves the language-independent command string or the Help text for a context menu item.
| GCS_HELPTEXT | Returns the Help text for the menu item. |
| GCS_VALIDATE | Validates that the menu item exists. |
| GCS_VERB | Returns the language-independent command name for the menu item. |
The language-independent command name is a name that can be passed to the IContextMenu::InvokeCommand method to activate a command by an application. The Help text is a description that Windows Explorer displays in its status bar; it should be reasonably short (under 40 characters).
See also IContextMenu2, IContextMenu
HRESULT HandleMenuMsg(
UINT uMsg,
WPARAM wParam,
LPARAM lParam
);
Allows client objects of the IContextMenu interface to handle messages associated with owner-drawn menu items.
HandleMenuMsg is called when a client of IContextMenu determines that the IContextMenu2 interface is supported and receives one of the messages specified in the description of the uMsg parameter.
HRESULT InvokeCommand(
LPCMINVOKECOMMANDINFO lpici
);
Carries out the command associated with a context menu item.
The shell calls this method when the user chooses a command added to a context menu by the handler. This method may also be called by an application without any corresponding user action.
See also IContextMenu2, IContextMenu
HRESULT QueryContextMenu(
HMENU hmenu,
UINT indexMenu,
UINT idCmdFirst,
UINT idCmdLast,
UINT uFlags
);
Adds menu items to the specified menu. The menu items should be inserted at a specified position in the menu, and their menu item identifiers must be in a given range.
| CMF_DEFAULTONLY | The user activates the default action, typically by double-clicking. This value provides a hint for the context menu to add nothing if it does not modify the default item in the menu. A context menu extension or drag-and-drop handler should not add any menu items if this value is specified. A namespace extension should add only the default item (if any). |
| CMF_EXPLORE | Context menu handlers should ignore this value. It is specified when the context menu is for an object in Windows Explorer. |
| CMF_NORMAL | Indicates normal operation. A context menu extension, namespace extension, or drag-and-drop handler can add any menu items. |
| CMF_VERBSONLY | Context menu handlers should ignore this value. This value is specified if the context menu is for a shortcut object. |
The remaining bits of the low-order word are reserved by the system. The high-order word may be used for context-specific communications.
The actual identifier of each menu item should be idCmdFirst plus a menu identifier offset in the range zero through (idCmdLast idCmdFirst).
See also IContextMenu2, IContextMenu
The IContextMenu3 interface is used to create or merge a context menu associated with a certain object when the menu implementation needs to process the WM_MENUCHAR message.
When to Implement
Implement IContextMenu3 if your context menu extension needs to process the WM_MENUCHAR message.
These messages are forwarded to IContextMenu3through the HandleMenuMsg2 methodonly if a QueryInterface call for an IContextMenu3 interface pointer is successful, indicating that the object supports this interface.
When to Use
You do not call this interface directly. IContextMenu3 is used by the operating system only when it has confirmed that your application is aware of this interface.
IContextMenu3 is derived from IContextMenu2. The following method is specific to IContextMenu3:
| IContextMenu3 Method | Description |
| HandleMenuMsg2 | Called when the window that owns the menu receives a WM_MENUCHAR message. |
Note This interface is only supported in shell versions 4.71 and later.
HRESULT HandleMenuMsg2(
UINT uMsg,
WPARAM wParam,
LPARAM lParam,
LRESULT *plResult
);
Allows context menu handlers to process the WM_MENUCHAR message.
HandleMenuMsg2 is called when a client of IContextMenu determines that the IContextMenu3 interface is supported and receives one of the messages specified in the description of the uMsg parameter.
Version 4.71
See also IContextMenu2
ICopyHook is a COM-based interface used to create a copy hook handler. A copy hook handler is a shell extension that determines if a shell folder or printer object can be moved, copied, renamed, or deleted. The shell calls the ICopyHook::CopyCallback method prior to performing one of these operations.
The copy hook handler, which is an OLE in-process server (a DLL), does not perform the task itself, but it does approve or disapprove the action. If the shell receives approval from the copy hook handler, it performs the file system operation. Copy hook handlers are not informed about the success of an operation, so they cannot monitor actions taken on folder objects unless FindFirstChangeNotification is used.
A folder object can have multiple copy hook handlers. For example, even if the shell already has a copy hook handler registered for a particular folder object, you can still register one of your own. If two or more copy hook handlers are registered for an object, the shell simply calls each of them before performing one of the specified file system operations.
The shell initializes ICopyHook directly, without using the IShellExtInit interface first.
CopyCallback returns an integer value that indicates whether or not the shell should perform the operation. The shell will call each copy hook handler registered for a folder object until all the handlers have been called or until one of them has returned a value other than IDYES. The handler returns IDYES to specify that the operation should be performed, or IDNO or IDCANCEL to specify that the operation should be discontinued.
When to Implement
Implement a copy hook handler when you want to be able to control when, or if, these file system operations are performed on a given object. You might want to use a copy hook handler on shared folders, for example.
When to Use
You do not call this shell extension directly. ICopyHook::CopyCallback is called by the shell prior to moving, copying, deleting, or renaming a shell folder object.
| ICopyHook Method | Description |
| CopyCallback | Determines whether a move, copy, delete, or rename operation on a folder object should be allowed or disallowed. |
UINT CopyCallback(
HWND hwnd,
UINT wFunc,
UINT wFlags,
LPCSTR pszSrcFile,
DWORD dwSrcAttribs,
LPCSTR pszDestFile,
DWORD dwDestAttribs
);
Determines whether the shell will be allowed to move, copy, delete, or rename a folder or printer object. The shell calls each copy hook handler registered (see comments below) for a folder or printer object until all the handlers have been called or until one of them returns IDNO or IDCANCEL.
| IDYES | Allows the operation.
IDNO |
| Prevents the operation on this file but continues with any other operations that have been approved (for example, a batch copy operation). | |
| IDCANCEL | Prevents the current operation and cancels any pending operations. |
You need to register your copy hook handler. For example, directory copy hook handlers are registered under HKEY_CLASSES_ROOT\directory\shellex\CopyHookHandlers\your_copyhook\{copyhook CLSID value}. Other registry keys associated with shell extensions are: *, Folder, Drives, Printers, Unknown, and AudioCD.
When this method is called, the shell initializes the ICopyHook interface directly without using an IShellExtInit interface first.
See also SHFileOperation
IDeskBand is used to obtain information about a band object. See Band Objects for more information about band objects.
When to Implement
Implement IDeskBand if you are implementing a band object.
When to Use
You do not call this interface directly. IDeskBand is used by the shell or the browser to obtain display information for a band object.
IDeskBand is derived from IDockingWindow. The following method is specific to IDeskBand.
| IDeskBand Method | Description |
| GetBandInfo | Retrieves the information for a band object. |
Note This interface is only supported in shell versions 4.71 and later.
HRESULT GetBandInfo(
DWORD dwBandID,
DWORD dwViewMode,
DESKBANDINFO* pdbi
);
Retrieves the information for a band object.
| DBIF_VIEWMODE_NORMAL | The band object is being displayed in a horizontal band. |
| DBIF_VIEWMODE_VERTICAL | The band object is being displayed in a vertical band. |
| DBIF_VIEWMODE_FLOATING | The band object is being displayed in a floating band. |
| DBIF_VIEWMODE_TRANSPARENT | The band object is being displayed in a transparent band. |
Version 4.71
The IDockingWindow interface is implemented by window objects that can be docked within the border space of a Windows Explorer window.
When to Implement
You implement IDockingWindow when you want to display a window inside a browser frame. This is normally used for user interface windows, such as toolbars.
When to Use
You do not normally use the IDockingWindow interface. The shell browser uses this interface to support docked windows inside the browser frame.
IDockingWindow is derived from IOleWindow. The following are the methods specific to IDockingWindow.
| IDockingWindow Method | Description |
| CloseDW | Notifies the docking window object that it is about to be removed. |
| ResizeBorderDW | Notifies the docking window object that the frame's border space has changed. |
| ShowDW | Instructs the docking window object to show or hide itself. |
Note This interface is only supported in shell versions 4.71 and later.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.