IDockingWindow::CloseDW
Interfaces

IDockingWindow::CloseDW


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.

dwReserved
Reserved. This parameter should always be zero.

Version 4.71

See also IDockingWindow, IDockingWindowFrame, IDockingWindowSite

IDockingWindow::ResizeBorderDW

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.

prcBorder
Address of a RECT structure that contains the frame's available border space.
punkToolbarSite
Address of the site's IUnknown interface. The docking window object should call the QueryInterface method for this interface, requesting IID_IShellToolbarSite, and use that interface to negotiate its border space. It is the docking window object's responsibility to release this interface when it is no longer needed.
fReserved
Reserved for future use. This parameter should always be zero.

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

IDockingWindow::ShowDW

HRESULT ShowDW(
    BOOL bShow
);

Instructs the docking window object to show or hide itself.

bShow
Boolean value indicating whether the docking window object should show or hide itself. If this parameter is nonzero, the docking window object should show its window. If it is zero, the docking window object should hide its window and return its border space by calling IDockingWindowSite::SetBorderSpaceDW with all zeros.

Version 4.71

See also IDockingWindow, IDockingWindowFrame, IDockingWindowSite

IDockingWindowFrame

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.

IDockingWindowFrame::AddToolbar

HRESULT AddToolbar(
    IUnknown* punkSrc, 
    LPCWSTR pwszItem, 
    DWORD dwAddFlags
);

Adds the specified IDockingWindow object to the frame.

punkSrc
Address of the IDockingWindow object to be added.
pwszItem
Address of a null-terminated UNICODE string. This is an application-defined string used for identifying the docking window object.
dwAddFlags
Specifies the flags for the docking window object being added. This can be one or more of the following values:
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

IDockingWindowFrame::FindToolbar

HRESULT FindToolbar(
    LPCWSTR pwszItem, 
    REFIID riid, 
    LPVOID* ppvObj
);

Finds the specified IDockingWindow object in the toolbar frame and returns an interface pointer to it.

pwszItem
Address of a null-terminated UNICODE string. This is the same string that was passed to the AddToolbar method.
riid
Identifier of the desired COM interface.
ppvObj
Address to receive the interface pointer. If an error occurs, a NULL pointer is placed in this address.

Version 4.71

See also IDockingWindowFrame, IDockingWindowSite

IDockingWindowFrame::RemoveToolbar

HRESULT RemoveToolbar(
    IUnknown* punkSrc,
    DWORD dwRemoveFlags
);

Removes the specified IDockingWindow from the toolbar frame.

punkSrc
Address of the IDockingWindow object to be removed. The IDockingWindowFrame implementation will call the IDockingWindow::CloseDW and Release methods.
dwRemoveFlags
Option flags for removing the docking window object. This parameter can be one or more of the following values:
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

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.

IDockingWindowSite::GetBorderDW

HRESULT GetBorderDW(
    IUnknown* punkSrc, 
    LPRECT prcBorder
);

Retrieves the border space allocated for the specified IDockingWindow object.

punkSrc
Address of the IDockingWindow object for which the border space is being requested.
prcBorder
Address of a RECT structure to receive the entire available border space for the browser. The docking window object should use this information to determine where to place itself. See the IDockingWindow::ResizeBorderDW method for more information.

Version 4.71

See also IDockingWindowFrame, IDockingWindowSite

IDockingWindowSite::RequestBorderSpaceDW

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.

punkSrc
Address of the IDockingWindow object for which the border space is being requested.
pbw
Address of a BORDERWIDTHS structure. Before calling this method, the structure must be filled with the desired border space. After the method's successful completion, the structure will contain the approved border space. The IDockingWindowSite object may change these values. If border space is critical, it is the caller's responsibility to determine if the returned border space is sufficient.

Version 4.71

See also IDockingWindowFrame

IDockingWindowSite::SetBorderSpaceDW

HRESULT SetBorderSpaceDW(
    IUnknown* punkSrc, 
    LPCBORDERWIDTHS pbw
);

Allocates and reserves border space for an IDockingWindow object.

punkSrc
Address of the IDockingWindow object for which the border space is being set.
pbw
Address of a BORDERWIDTHS structure that contains the IDockingWindow object's border space. The border space should have been approved by IDockingWindowSite through a successful call to the RequestBorderSpaceDW method.

Version 4.71

See also IDockingWindowFrame

IEnumIDList

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.

IEnumIDList::Clone

HRESULT Clone(
    IEnumIDList **ppenum	
   );

Creates a new item enumeration object with the same contents and state as the current one.

ppenum
Address of a pointer to the new enumeration object. The calling application must eventually free the new object by calling its Release member function.

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

IEnumIDList::Next

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.

celt
Specifies the number of elements in the array pointed to by the rgelt parameter.
rgelt
Address of an array of ITEMIDLIST pointers that receives the item identifiers. The implementation must allocate these item identifiers using the shell's allocator (retrieved by the SHGetMalloc function). The calling application is responsible for freeing the item identifiers using the shell's allocator.
pceltFetched
Address of a value that receives a count of the item identifiers actually returned in rgelt. The count can be smaller than the value specified in the celt parameter. This parameter can be NULL only if celt is one.

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

IEnumIDList::Reset

HRESULT Reset(void);

Returns to the beginning of the enumeration sequence.

See also IEnumIDList

IEnumIDList::Skip

HRESULT Skip(
    ULONG celt	
   );	

Skips over the specified number of elements in the enumeration sequence.

celt
Number of item identifiers to skip.

See also IEnumIDList

IExtractIcon

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.

IExtractIcon::Extract

HRESULT Extract(
    LPCSTR pszFile,
    UINT nIconIndex,
    HICON *phiconLarge,
    HICON *phiconSmall,
    UINT nIconSize
   );		

Extracts an icon image from the specified location.

pszFile
Address of a null-terminated string specifying the icon location.
nIconIndex
Icon index.
phiconLarge
Address of the variable that receives the handle to the large icon.
phiconSmall
Address of the variable that receives the handle to the small icon.
nIconSize
Desired size, in pixels, of the icon. The low word contains the size of the large icon, and the high word contains the size of the small icon. The size specified can be the width or height. The width of an icon always equals its height.

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

IExtractIcon::GetIconLocation

HRESULT GetIconLocation(
    UINT uFlags,
    LPSTR szIconFile,
    INT cchMax,
    LPINT piIndex,
    UINT *pwFlags
   );		

Retrieves the location and index of an icon.

uFlags
Flags. This parameter can be zero or one or more of the following values:
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.
szIconFile
Address of the buffer that receives the icon location. The icon location is a null-terminated string that identifies the file that contains the icon.
cchMax
Size of the buffer that receives the icon location.
piIndex
Address of an INT that receives the icon index, which further describes the icon location.
pwFlags
Address of a UINT value that receives zero or a combination of the following values:
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

IFileViewer

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.

IFileViewer::PrintTo

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.

pszDriver
Address of a buffer that contains the name of the printer device driver that should print the file. If this parameter is NULL, the file viewer determines which device driver to use.
fSuppressUI
User interface suppression flag. If this parameter is TRUE, the file viewer should not display any user interface, including error messages, during the print operation. If this parameter is FALSE, the file viewer can show dialog boxes, as needed.

See also IFileViewer

IFileViewer::Show

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.

pvsi
Address of an FVSHOWINFO structure to contain information that the file viewer uses to display the file. A file viewer can return information to the shell by modifying the members of the structure.

See also IFileViewer

IFileViewer::ShowInitialize

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.

lpfsi
Address of an IFileViewerSite interface. A file viewer uses this interface to retrieve the handle to the current pinned window or to specify a new pinned window.

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

IFileViewerSite

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.

IFileViewerSite::GetPinnedWindow

HRESULT GetPinnedWindow(
    HWND *phwnd		
   );		

Retrieves the handle to the current pinned window, if one exists.

phwnd
Address of the handle to the current pinned window or NULL if no pinned window exists.

See also IFileViewerSite

IFileViewerSite::SetPinnedWindow

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.

hwnd
Handle to the new pinned window or NULL if there is to be no pinned window.

See also IFileViewerSite

IInputObject

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.

IInputObject::HasFocusIO

HRESULT HasFocusIO(void);

Determines if one of the object's windows has the keyboard focus.

Version 4.71

IInputObject::TranslateAcceleratorIO

HRESULT TranslateAcceleratorIO(
    LPMSG lpMsg
);

Allows the object to process keyboard accelerators.

lpMsg
Address of an MSG structure that contains the keyboard message that is being translated.

Version 4.71

IInputObject::UIActivateIO

HRESULT UIActivateIO(
    BOOL fActivate, 
    LPMSG lpMsg
);

UI-activates or deactivates the object.

fActivate
Indicates if the object is being activated or deactivated. If this value is nonzero, the object is being activated. If this value is zero, the object is being deactivated.
lpMsg
Address of an MSG structure that contains the message that caused the activation change. This value may be NULL.

Version 4.71

IInputObjectSite

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.

IInputObjectSite::OnFocusChangeIS

HRESULT OnFocusChangeIS(
    IUnknown *punkObj, 
    BOOL fSetFocus
);

Informs the browser that the focus has changed.

punkObj
Address of the IUnknown interface of the object gaining or losing the focus.
fSetFocus
Indicates if the object has gained or lost the focus. If this value is nonzero, the object has gained the focus. If this value is zero, the object has lost the focus.

The calling object should call this method whenever one of its windows gains or loses the input focus.

Version 4.71

INewShortcutHook

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.