
HRESULT CloseDW(
DWORD dwReserved
);
Notifies the docking window object that it is about to be removed from the frame. The docking window object should save any persistent information at this time.
Version 4.71
See also IDockingWindow, IDockingWindowFrame, IDockingWindowSite
HRESULT ResizeBorderDW(
LPCRECT prcBorder,
IUnknown* punkToolbarSite,
BOOL fReserved
);
Notifies the docking window object that the frame's border space has changed. In response to this method, the IDockingWindow implementation must call IDockingWindowSite::SetBorderSpaceDW, even if no border space is required or a change is not necessary.
The prcBorder parameter will contain the frame's entire available border space. The docking window object should negotiate its border space and then use this information to position itself.
For example, if the docking window object requires 25 pixels at the top of the border space, it should negotiate for this by allocating a BORDERWIDTHS structure, setting the top member to 25, calling IDockingWindowSite::RequestBorderSpaceDW, and then calling IDockingWindowSite::SetBorderSpaceDW. The docking window object can then position its window at prcBorder->left and prcBorder->top. The width of the docking window object's window is determined from prcBorder->right - prcBorder->left, and its height is contained in the top member of the BORDERWIDTHS structure.
Version 4.71
See also IDockingWindow, IDockingWindowFrame, IDockingWindowSite
HRESULT ShowDW(
BOOL bShow
);
Instructs the docking window object to show or hide itself.
Version 4.71
See also IDockingWindow, IDockingWindowFrame, IDockingWindowSite
The IDockingWindowFrame interface is implemented by the browser to support adding IDockingWindow objects to a frame.
When to Implement
You do not normally implement the IDockingWindowFrame interface. The shell browser implements this interface to support docked windows inside the browser frame.
When to Use
You use IDockingWindowFrame to add, find, and remove docking window objects in a browser frame.
IDockingWindowFrame is derived from IOleWindow. The following are the methods specific to IDockingWindowFrame.
| IDockingWindowFrame Methods | Description |
| AddToolbar | Adds an IDockingWindow object to a frame. |
| FindToolbar | Finds an IDockingWindow object in a frame. |
| RemoveToolbar | Removes an IDockingWindow object from a frame. |
Note This interface is only supported in shell versions 4.71 and later.
HRESULT AddToolbar(
IUnknown* punkSrc,
LPCWSTR pwszItem,
DWORD dwAddFlags
);
Adds the specified IDockingWindow object to the frame.
| 0 | The docking window is a regular, visible docking window. |
| DWFAF_HIDDEN | The docking window is added but is not shown. To show it at a later time, call its IDockingWindow::ShowDW method. |
Version 4.71
See also IDockingWindowFrame, IDockingWindowSite
HRESULT FindToolbar(
LPCWSTR pwszItem,
REFIID riid,
LPVOID* ppvObj
);
Finds the specified IDockingWindow object in the toolbar frame and returns an interface pointer to it.
Version 4.71
See also IDockingWindowFrame, IDockingWindowSite
HRESULT RemoveToolbar(
IUnknown* punkSrc,
DWORD dwRemoveFlags
);
Removes the specified IDockingWindow from the toolbar frame.
| DWFRF_NORMAL | The default delete processing is performed. |
| DWFRF_DELETECONFIGDATA | In addition to deleting the toolbar, any configuration data is removed as well. |
Version 4.71
See also IDockingWindowSite
The IDockingWindowSite interface is implemented by the browser to manage the border space for one or more IDockingWindow objects. This interface is similar to the IOleInPlaceUIWindow interface.
When to Implement
You do not normally implement the IDockingWindowSite interface. The shell browser implements this interface to support docked windows inside the browser frame.
When to Use
You use IDockingWindowSite to negotiate the space for a docking window object in a browser frame.
IDockingWindowSite is derived from IOleWindow. The following are the methods specific to IDockingWindowSite.
| IDockingWindowSite Methods | Description |
| GetBorderDW | Retrieves the allocated border space for a particular IDockingWindow object. |
| RequestBorderSpaceDW | Processes border space requests for an IDockingWindow object. |
| SetBorderSpaceDW | Allocates border space for an IDockingWindow object. |
Note This interface is only supported in shell versions 4.71 and later.
HRESULT GetBorderDW(
IUnknown* punkSrc,
LPRECT prcBorder
);
Retrieves the border space allocated for the specified IDockingWindow object.
Version 4.71
See also IDockingWindowFrame, IDockingWindowSite
HRESULT RequestBorderSpaceDW(
IUnknown* punkSrc,
LPCBORDERWIDTHS pbw
);
Approves, modifies, or refuses a request for an IDockingWindow object's border space. The border space is not allocated until the SetBorderSpaceDW method is called.
Version 4.71
See also IDockingWindowFrame
HRESULT SetBorderSpaceDW(
IUnknown* punkSrc,
LPCBORDERWIDTHS pbw
);
Allocates and reserves border space for an IDockingWindow object.
Version 4.71
See also IDockingWindowFrame
The IEnumIDList interface enumerates item identifiers associated with shell folder objects. First, use the IShellFolder::EnumObjects method to create an item enumeration object, and then use IEnumIDList to iterate through the item identifiers in the enumeration object.
When to Implement
You can implement this interface when you want a caller to be able to enumerate the item identifiers contained in a folder object. You get a pointer to IEnumIDList through IShellFolder::EnumObjects.
When to Use
You do not use this interface directly. The IShellFolder::EnumObjects method creates an enumeration object of this kind. In this case, the enumeration is a set of item identifiers. The shell calls the IEnumIDList methods to enumerate the items contained in an enumeration object.
| IEnumIDList Methods | Description |
| Clone | Creates a new item enumeration object identical to the current one. |
| Next | Retrieves the specified number of item identifiers. |
| Reset | Returns to the beginning of the enumeration. |
| Skip | Skips over the specified number of items. |
HRESULT Clone(
IEnumIDList **ppenum
);
Creates a new item enumeration object with the same contents and state as the current one.
This method makes it possible to record a particular point in the enumeration sequence and then return to that point at a later time.
See also IEnumIDList
HRESULT Next(
ULONG celt,
LPITEMIDLIST *rgelt,
ULONG *pceltFetched
);
Retrieves the specified number of item identifiers in the enumeration sequence and advances the current position by the number of items retrieved.
If this method returns any value other than NOERROR, no entries in the rgelt array are valid on exit. They are all in an indeterminate state.
See also IEnumIDList
HRESULT Reset(void);
Returns to the beginning of the enumeration sequence.
See also IEnumIDList
HRESULT Skip(
ULONG celt
);
Skips over the specified number of elements in the enumeration sequence.
See also IEnumIDList
The shell uses the IExtractIcon interface to retrieve icons for objects it displays.
The operating system provides default icons for file objects, but you can specify custom icons by making appropriate registry entries and, in some cases, by using IExtractIcon.
When to Implement
You implement IExtractIcon to provide either instance-specific icons for objects in a particular class or icons for subfolders that extend Windows Explorer's namespace. These implementations are accomplished by writing handler code in an OLE in-process server COM DLL.
Also, if you implement IShellFolder, you will need to provide an implementation of IExtractIcon that callers can obtain by using the IShellFolder::GetUIObjectOf method.
Shell extensions based on IExtractIcon must be initialized by using the IPersistFile::Load method. You should also note that shell extensions do not work unless all appropriate registry entries are made.
When to Use
In most cases, you do not call this interface directly. It is usually called by the shell when an icon has been made available by a properly registered handler. However, you can call IExtractIcon directly if you want to delegate icon extraction to another object.
| IExtractIcon Methods | Description |
| Extract | Extracts an icon from the specified location. |
| GetIconLocation | Retrieves the icon location for an object. |
HRESULT Extract(
LPCSTR pszFile,
UINT nIconIndex,
HICON *phiconLarge,
HICON *phiconSmall,
UINT nIconSize
);
Extracts an icon image from the specified location.
The icon location and index are the same values returned by the GetIconLocation method. If this function returns S_FALSE, these values must specify an icon file name and index that form legal parameters for a call to Extract. If Extract does not return S_FALSE, no assumptions should be made about the meanings of the pszFile and nIconIndex parameters.
See also IExtractIcon
HRESULT GetIconLocation(
UINT uFlags,
LPSTR szIconFile,
INT cchMax,
LPINT piIndex,
UINT *pwFlags
);
Retrieves the location and index of an icon.
| GIL_ASYNC | The calling application supports asynchronous retrieval of icons. If the icon is cached by the receiving application, it should supply the icon and return S_OK. If the icon is not cached and must be retrieved, the receiving application should start an asynchronous icon retrieval operation, supply a default icon, and return E_PENDING. This method will be called again at a later time to attempt to retrieve the icon again. |
| 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. |
| GIL_DONTCACHE | The physical image bits for this icon should not be cached by the caller. This distinction is important to consider because a GIL_DONTCACHELOCATION flag may be introduced in future versions of the shell. |
| GIL_NOTFILENAME | The location is not a file name/index pair. Callers that decide to extract the icon from the location must call this object's IExtractIcon::Extract method to obtain the desired icon images. |
| GIL_PERCLASS | All objects of this class have the same icon. This flag is used internally by the shell. Typical implementations of IExtractIcon do not require this flag because the flag implies that an icon handler is not required to resolve the icon on a per-object basis. The recommended method for implementing per-class icons is to register a DefaultIcon for the class. |
| GIL_PERINSTANCE | Each object of this class has its own icon. This flag is used internally by the shell to handle cases like Setup.exe, where objects with identical names can have different icons. Typical implementations of IExtractIcon do not require this flag. |
| GIL_SIMULATEDOC | The caller should create a document icon using the specified icon. |
See also IExtractIcon::Extract
The IFileViewer interface designates an interface that allows a registered file viewer to be notified when it must show or print a file.
When to Implement
You implement this interface to provide a means for your registered file types to be viewed and/or printed.
When to Use
You do not normally use this interface. The shell calls the interface when the user chooses the Quick View command from a file's context menu and the file is a type that the file viewer recognizes.
| IFileViewer Methods | Description |
| PrintTo | Prints a file. |
| Show | Displays a file. |
| ShowInitialize | Prepares to display a file. |
HRESULT PrintTo(
LPSTR pszDriver,
BOOL fSuppressUI
);
Prints a file. The shell specifies the name of the file to print by calling the file viewer's IPersistFile::Load method.
See also IFileViewer
HRESULT Show(
LPFVSHOWINFO pvsi
);
Displays a file. The shell specifies the name of the file to display by calling the file viewer's IPersistFile::Load method.
See also IFileViewer
HRESULT ShowInitialize(
LPFILEVIEWERSITE lpfsi
);
Allows a file viewer to determine whether it can display a file and, if it can, to perform initialization operations before showing the file.
The shell calls this method before the IFileViewer::Show method. The shell specifies the name of the file to display by calling the file viewer's IPersistFile::Load method.
ShowInitialize must perform all operations that are prone to failure so that if it succeeds, IFileViewer::Show will not fail.
See also IFileViewer
The IFileViewerSite interface designates an interface that allows a file viewer to retrieve the handle to the current pinned window or to set a new pinned window. The pinned window is the window in which the current file viewer displays a file. When the user selects a new file to view, the shell directs the file viewer to display the new file in the pinned window rather than create a new window.
When to Implement
You do not normally implement this interface. The shell implements this interface to provide a pinned window for the file viewer.
When to Use
You use this interface to obtain or set the window for a file viewer.
| IFileViewerSite Methods | Description |
| GetPinnedWindow | Retrieves the handle to the current pinned window. |
| SetPinnedWindow | Sets a new pinned window. |
HRESULT GetPinnedWindow(
HWND *phwnd
);
Retrieves the handle to the current pinned window, if one exists.
See also IFileViewerSite
HRESULT SetPinnedWindow(
HWND *hwnd
);
Sets the pinned window. When the user selects a new file to view, the shell directs the file viewer to display the new file in the pinned window instead of creating a new window.
See also IFileViewerSite
The IInputObject interface is used to change UI activation and process accelerators for a user input object contained in the shell.
When to Implement
Implement IInputObject if you are implementing a shell object that takes user input.
When to Use
You do not call this interface directly. IInputObject is used by the shell or the browser to notify the object of UI activation changes and to translate keyboard accelerators.
IInputObject is derived from IUnknown. The following methods are specific to IInputObject.
| IInputObject Methods | Description |
| HasFocusIO | Determines if one of the object's windows has the keyboard focus. |
| TranslateAcceleratorIO | Passes keyboard accelerators to the object. |
| UIActivateIO | Activates or deactivates the object. |
Note This interface is only supported in shell versions 4.71 and later.
HRESULT HasFocusIO(void);
Determines if one of the object's windows has the keyboard focus.
Version 4.71
HRESULT TranslateAcceleratorIO(
LPMSG lpMsg
);
Allows the object to process keyboard accelerators.
Version 4.71
HRESULT UIActivateIO(
BOOL fActivate,
LPMSG lpMsg
);
UI-activates or deactivates the object.
Version 4.71
The IInputObjectSite interface is used to communicate focus changes for a user input object contained in the shell.
When to Implement
You do not normally implement this interface. IInputObjectSite is implemented by the shell or the browser to properly maintain the input focus.
When to Use
You use IInputObjectSite if you are implementing a shell object that takes user input.
IInputObjectSite is derived from IUnknown. The following method is specific to IInputObjectSite.
| IInputObjectSite Method | Description |
| OnFocusChangeIS | Informs the browser that the focus has changed. |
Note This interface is only supported in shell versions 4.71 and later.
HRESULT OnFocusChangeIS(
IUnknown *punkObj,
BOOL fSetFocus
);
Informs the browser that the focus has changed.
The calling object should call this method whenever one of its windows gains or loses the input focus.
Version 4.71
The INewShortcutHook interface is used when creating a new Internet shortcut.
When to Implement
You do not normally implement INewShortcutHook. It is implemented by the shell for Internet shortcuts.
When to Use
You use INewShortcutHook when creating a new Internet shortcut. The methods provided by this interface are supplied as a convenience.
INewShortcutHook is derived from IUnknown. The following methods are specific to INewShortcutHook.
| INewShortcutHook Methods | Description |
| GetExtension | Retrieves the file extension for the shortcut object. |
| GetFolder | Retrieves the folder name for the shortcut object. |
| GetName | Retrieves the file name of the shortcut object, without the extension. |
| GetReferent | Retrieves the referent of the shortcut object. |
| SetFolder | Sets the folder name for the shortcut object. |
| SetReferent | Sets the referent of the shortcut object. |
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.