ICommDlgBrowser::IncludeObject method (shobjidl_core.h)

Article
02/22/2024

Allows the common dialog box to filter objects that the view displays.

Syntax

HRESULT IncludeObject(
  IShellView      *ppshv,
  PCUITEMID_CHILD pidl
);

Parameters

ppshv

Type: IShellView*

A pointer to the view's IShellView interface.

pidl

Type: LPCITEMIDLIST

A PIDL, relative to the folder, that identifies the object.

Return value

Type: HRESULT

The browser should return S_OK to include the object in the view, or S_FALSE to hide it.

Remarks

This method is called by the IEnumIDList implementation when hosted in file dialog boxes. The enumerator calls this method to let the common dialog box filter out objects that should not be displayed. Typically, the file dialog boxes will get the display text of the item, and filter by the extension.

Note to Calling Applications

Call this method before returning an object in the Shell folder's IDLIST enumerator.

When dealing with data sources that have many items, such as libraries and searches, the callback to this method results in poor performance. To avoid that situation, implement GetViewFlags and return CDB2GVF_NOINCLUDEITEM. Doing so enables the view to skip calling ICommDlgBrowser::IncludeObject, thereby improving performance.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	shobjidl_core.h (include Shobjidl.h)
DLL	Shell32.dll (version 4.0 or later)