IExplorerBrowser interface (shobjidl_core.h)

IExplorerBrowser is a browser object that can be either navigated or that can host a view of a data object. As a full-featured browser object, it also supports an automatic travel log.

The Shell provides a default implementation of IExplorerBrowser as CLSID_ExplorerBrowser. Typically, a developer does not need to provide a custom implementation of this interface.

The Windows Software Development Kit (SDK) provides full samples that demonstrate the use of and interaction with IExplorerBrowser. Download the Explorer Browser Search Sample and the Explorer Browser Custom Contents Sample.

Inheritance

The IExplorerBrowser interface inherits from the IUnknown interface. IExplorerBrowser also has these types of members:

Methods

The IExplorerBrowser interface has these methods.

 
IExplorerBrowser::Advise

Initiates a connection with IExplorerBrowser for event callbacks.
IExplorerBrowser::BrowseToIDList

Browses to a pointer to an item identifier list (PIDL)
IExplorerBrowser::BrowseToObject

Browses to an object.
IExplorerBrowser::Destroy

Destroys the browser.
IExplorerBrowser::FillFromObject

Creates a results folder and fills it with items.
IExplorerBrowser::GetCurrentView

Gets an interface for the current view of the browser.
IExplorerBrowser::GetOptions

Gets the current browser options.
IExplorerBrowser::Initialize

Prepares the browser to be navigated.
IExplorerBrowser::RemoveAll

Removes all items from the results folder.
IExplorerBrowser::SetEmptyText

Sets the default empty text.
IExplorerBrowser::SetFolderSettings

Sets the folder settings for the current view.
IExplorerBrowser::SetOptions

Sets the current browser options.
IExplorerBrowser::SetPropertyBag

Sets the name of the property bag.
IExplorerBrowser::SetRect

Sets the size and position of the view windows created by the browser.
IExplorerBrowser::Unadvise

Terminates an advisory connection. (IExplorerBrowser.Unadvise)

Remarks

For example code that shows typical use of IExplorerBrowser and its methods, see the Explorer Browser Custom Contents and Explorer Browser Custom Contents samples.

After calling this object's Initialize method, its Destroy method must be called to free any windowed resources that were generated in the call to Initialize.

The object that hosts the ExplorerBrowser object should derive from IServiceProvider and implement QueryService to respond to any queries for service. For example, the number of panes shown by the browser can be controlled by implementing IExplorerPaneVisibility and responding to any SID_ExplorerPaneVisibility service requests.

Frames are disabled by default. To enable frames and get the default set of panes, set the EBO_SHOWFRAMES flag using the IExplorerBrowser::SetOptions method. The default panes, listed as IExplorerPaneVisibility constants, are these:

  • EP_NavPane
  • EP_Commands
  • EP_Commands_Organize
  • EP_Commands_View
  • EP_DetailsPane
  • EP_PreviewPane
  • EP_QueryPane
  • EP_AdvQueryPane
  • EP_StatusBar
  • EP_Ribbon
See IExplorerPaneVisibility::GetPaneState for more information.

Clients of the ExplorerBrowser object can implement the ICommDlgBrowser, ICommDlgBrowser2, or ICommDlgBrowser3 interfaces and respond to an SID_SExplorerBrowserFrame service request in their QueryService implementations that are called when any ICommDlgBrowser interfaces are called on the browser (usually called from the view as a result of user actions). Note that the client does not receive a call to ICommDlgBrowser::IncludeObject if a folder filter has been set on the browser by a call to IFolderFilterSite::SetFilter.

To remain compatible with some older applications, the default Shell view (DefView) performs filtering operations (for example, searching operations executed by a search folder) on the UI thread. For new applications, this is typically not desired; the search should execute on a background thread. To stop the UI thread from filtering and instead run filtering on a background thread, provide ICommDlgBrowser2 through the SID_SExplorerBrowserFrame service request. When ICommDlgBrowser2::GetViewFlags is called, it should return CDB2GVF_NOINCLUDEITEM. For example, if you navigate to a search folder in ExplorerBrowser and you do not return CDB2GVF_NOINCLUDEITEM, the view can stop responding until the entire search is complete.

The Shell architecture has three main components: the browser, the views, and the data sources (for example, IShellFolder). The ExplorerBrowser object maintains the current location and navigation to other locations throughout the Shell namespace. It also keeps a travel log (forward and back history). The browser is notified when things happen in the view; for example, when the user double-clicks a folder. In response, the browser navigates to that location. The data sources are the objects that supply the items and folders in the namespace. They also have information about the location, such as the properties of the items and what to add to the context menu when the view requests it. Additionally, the data sources know what view should be created to represent their items at a location. In almost all instances, the folders create the Shell's default view (DefView). Therefore, as the browser navigates, it receives an IShellFolder object for the new location and asks it what view to create. The browser then creates that view and makes it visible, while hiding and then destroying the view that was showing the previous location. The view is responsible for communicating with IShellFolder for the current location and requesting it to enumerate the items, which allows the view to show these items to the user. As the user interacts with the items, the view communicates with the IShellFolder to get any additional information it needs, such as specific properties of the items or the context menu entries for the item.

If an application uses the default implementation provided by CLSID_ExplorerBrowser, inserting it into the window of an application and then browsing to a location, ExplorerBrowser creates the proper IShellView as specified by the location that it is browsing to. The application can then ask ExplorerBrowser to give it an interface on the current view, allowing the application to manipulate the view directly if required. The default implementation of the Windows Explorer view object, created by SHCreateShellFolderViewEx, supports the interface IShellView. You may verify that you have the default Shell folder view object by calling IExplorerBrowser::GetCurrentView and then calling QueryInterface on the object returned using the interface ID IID_CDefView.

Windows 7 and later. CExplorerBrowser can support in-place navigation by using IServiceProvider::QueryService with the Service ID SID_SlnPlaceBrowser. When using SID_SInPlaceBrowser, the CExplorerBrowser state cannot be set to EBO_NAVIGATEONCE.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header shobjidl_core.h (include Shobjidl.h)