DExplore COM Interface

Interfacing to MS Help 2 DExplore Viewer using its undocumented COM Interface.

by Rob Chandler, MS Help MVP

Last Update: 24-May-2003

*** This API is Not Support by Microsoft ***

Dexplore is the document viewer that ships with VS and MSDN and is essentially MS's standard viewer for Help 2.x content. If you have ever looked at DExplore's limited set of command line parameters with disappointment then be disappointed no more. DExplore does have a rich (undocumented) COM interface. This document introduces you to that COM interface. And if this still does not satisfy then consider the two MVP H2 viewers that are available: Helpware viewer & HelpCenter viewer.

Most of the interface is obvious (if you are familiar with MS Help 2). Some corners of the interface are not so obvious and I invite anyone who wants to contribute to this document to please Contact me.

Demo source code is in Borland Delphi, however VB, C++, C# programmers who are familiar with COM should have no problems following and translating the code.

Download Demo: DExploreTest_exe.zip

Download Demo Delphi Source: DExploreTest_src.zip

1. Import the type library for vshelp.tlb "VsHelp(Version 1.0)" from the following folder:
2. c:\Program Files\Common Files\Microsoft Shared\MsEnv\
3. Delphi 6: The import command is "Project > Import Type Library".
4. After clicking "Create Unit" we now have vshelp_tlb.pas
6. Where did vshelp.tlb come from? Search the registry for DExplore.exe:

1. So vshelp.tlb is the Type Library file for DExplore. Note the COM Program ID = DExplore.AppObj.
2. (note above is the VS 7.x DExplore GUID. VS 8.x has a different GUID)
1. If you have .Net Framework SDK (.Net SDK) installed search the HTML files for DExplore.AppObj. This will show us some code and get us going. It's the only obvious code MS have left lying around that shows us how to use the interface.

1. This script simply loads the .NET SDK Collection into DExplore and displays and syncs a URL.
2. helpHost = viewer.Help; This line is not clear since viewer.help normally contains the same thing as HelpHost anyway.
3. Notice that DExplore is not marked Safe For Scripting (see 2. above) so opening DExplore via IE will cause a warning message to appear before executing the command.

As stated there is no MS documentation so here's what we have found so far.

Special Note: Each call should be wrapped in a Try/Except block to trap errors (which occur if say a URL or collection parameter is not valid).

3.1 Base Commands

Getting the Help interface (Delphi example).

After creating your main COM object (in this case "_Help"), the SetCollection() and DisplayTopicFromURL() methods are normally all you need to open a collection and display a URL while showing the DExplore window.

3.2 TOC Control

3.3 Context Help Commands (F Index)

VS .NET tend to keep its help context mapping table in the "F" Index table of the help collection. The alternative is to keep your help context mappings in say an INI file that the main application can read and then calls DisplayTopicFromURL().

3.4 Keyword Commands (K Index)

Visible keywords, displayed in the Index Navigation pane of DExplore, live in the "K" Index.

3.5 Navigation and Result Pane Select Commands

3.6 Filter Commands

Note there is no method to applying a filterquery string. Applying a filter by its filtername works but these predefined filters can be edited by the user. Note: Our H2Viewer can apply filterquery strings.

3.7 Other ?

These commands have not part of the Delphi Demo.

Topics in Bold show the methods or properties successfully exercised in the accompanying Delphi demo and documentation above.

Topics prefixed with ? I have no idea about.

procedure Contents; safecall;

procedure Index; safecall;

procedure Search; safecall;

procedure IndexResults; safecall;

procedure SearchResults; safecall;

procedure DisplayTopicFromId(const bstrFile: WideString; Id: LongWord); safecall;

procedure DisplayTopicFromURL(const pszURL: WideString); safecall;

? procedure DisplayTopicFromURLEx(const pszURL: WideString; const pIVsHelpTopicShowEvents: IVsHelpTopicShowEvents); safecall;

procedure DisplayTopicFromKeyword(const pszKeyword: WideString); safecall;

procedure DisplayTopicFromF1Keyword(const pszKeyword: WideString); safecall;

procedure DisplayTopicFrom_OLD_Help(const bstrFile: WideString; Id: LongWord); safecall;

procedure SyncContents(const bstrURL: WideString); safecall;

? procedure CanSyncContents(const bstrURL: WideString); safecall;

function GetNextTopic(const bstrURL: WideString): WideString; safecall;

function GetPrevTopic(const bstrURL: WideString): WideString; safecall;

procedure FilterUI; safecall;

? procedure CanShowFilterUI; safecall;

procedure Close; safecall;

procedure SyncIndex(const bstrKeyword: WideString; fShow: Integer); safecall;

procedure SetCollection(const bstrCollection: WideString; const bstrFilter: WideString); safecall;

function Get_Collection: WideString; safecall;

function Get_Filter: WideString; safecall;

procedure Set_Filter(const pbstrFilter: WideString); safecall;

function Get_FilterQuery: WideString; safecall;

? function Get_HelpOwner: IVsHelpOwner; safecall;

? procedure Set_HelpOwner(const ppObj: IVsHelpOwner); safecall;

function Get_HxSession: IDispatch; safecall;

function Get_Help_: IDispatch; safecall;

? function GetObject(const bstrMoniker: WideString; const bstrOptions: WideString): IDispatch; safecall;

property Collection: WideString read Get_Collection;

property Filter: WideString read Get_Filter write Set_Filter;

property FilterQuery: WideString read Get_FilterQuery;

? property HelpOwner: IVsHelpOwner read Get_HelpOwner write Set_HelpOwner;

property HxSession: IDispatch read Get_HxSession;

property Help_: IDispatch read Get_Help_;

Subject: VS .NET 2003 - Using VsHelp.tlb with C#.

From: by Michael Waltuch from ESRI

Date: 24-May-2003

VS .NET 2003 - Using VsHelp.tlb with C#.

1. Create a new Windows Application project.
2. In the Project menu, select Add Reference.
3. In the Add Reference dialog, select the COM tab.
4. Click the Browse button and locate vshelp.tlb.
5. Click the Component Name VsHelp and then click Select. Click OK.

View code for the form (Form1.cs).

Add a using directive for VsHelp:

using VsHelp; //remember to be aware of case-sensitivity. First and third characters are upper case

Create a method to display the help, for example:

private void DispHelp(String url) { //Help interface must be fully qualified because its ambiguous otherwise VsHelp.Help h = new VsHelp.DExploreAppObjClass(); h.SetCollection("ms-help://ms.vscc.2003",""); h.DisplayTopicFromURL(url); h.SyncContents(url); }

Add a button to the form. Double-click it to view its Click event. Call the method you created earlier, for example:

private void button1_Click(object sender, System.EventArgs e)

{

DispHelp("ms-help://MS.VSCC.2003/MS.MSDNQTR.2003APR.1033/vsintro7/html/vxori WhatsNewInVisualStudio.htm");

}

Subject: Call MSHelp2 topic from C# via DTE

From: Charles Lloyd <...@epicor.com>

Date: 5-March-2004

Rob: As Charles suggests you can also access VS .NET IDE via the DTE Object. For more info see VS: Referencing the DTE Object

Just in case anybody is interested in comparing examples of the Dexplore COM interface and referencing the DTE to do the same thing (call a Help2 topic via an "F" keyword from a custom C# form inside of Visual Studio).

Dexplore way (see Helpware site for details):

private void displaySDKF1(string F1Keyword) { VsHelp.Help h = new VsHelp.DExploreAppObjClass(); h.SetCollection("ms-help://MS.VSCC.2003",""); h.DisplayTopicFromF1Keyword(F1Keyword); }

Cons: not officially supported. Error handling tougher. Pro: probably will

continue to work between changing versions of VS.

DTE way (add reference to envdte .NET dll):

private void displayViaDTE(string F1Keyword) { EnvDTE.DTE dte; dte = (EnvDTE.DTE)System.Runtime.InteropServices.Marshal.GetActiveObject("VisualSt udio.DTE.7.1"); dte.ExecuteCommand("Help.F1Help",F1Keyword); }

Cons: must have an instance of VS running.

VS 2005 API

MVP Rob Cavicchio posts that VS 2005 now has its own Help 2 API which MS have published in MSDN.

http://msdn2.microsoft.com/en-us/library/microsoft.visualstudio.vshelp80.help2(vs.80).aspx