Document! X 2017
In This Topic
    Implementing Context Sensitive Help
    In This Topic

    Document! X provides rich support for linking to the generated help system from your application or from Visual Studio and other development environments.

    Supporting F1 help from your application

    Development tools that use topic names 

    Recent development tools use topic file names instead of Help Context Ids to support F1 help. In that scenario you can use the help file name and the topic name, with a .html suffix, as the help target.

    Adding F1 support to a Visual Studio .NET Winforms project 

    Setting up the project

    1. The first step is to add a HelpProvider control to your form for design time support.
    2. The HelpNamespace property can be set at either design time or runtime, but must be set with the name of the CHM file generated by Document! X.
    3. If you wish to support "what's this" help, set the HelpButton property of the parent form to True.

    Setting What's This Help for controls

    1. Select the control you wish to have help available for. Scroll down the list of properties until you reach the Misc section. Here you will find a number of new properties added by the HelpProvider control. They will have the suffix "on <name>", where <name> is the name of your HelpProvider control.
      • Set the HelpKeyword property to the name of your Document! X topic, with a .html suffix. For example, if you had a topic named default, you would enter default.html as the property value.
      • The HelpNavigator property defines the view displayed. By default this is AssociateIndex,  you must change it to use Topic instead.
    2. Repeat for any other controls you wish to display what's this help for.
    3. At runtime, help can be invoked by either selecting the control and pressing F1, or by clicking the help button on the window title bar and then clicking a control which has help assigned to it.

     

    Displaying a help topic in code

    The shared Help class offered by the System.Windows.Forms name space allows you to display your help Topics. You can use the ShowHelp method to display a topic. The Url parameter of this method should be filled with your CHM filename, and the param parameter with the name of your topic and the .html suffix.

    For example, assuming you had a HelpProvider control already initialized named ContextHelp, and you wished to display a topic named default, you could call the following code:

    Visual Basic .NET
    Copy Code 
    ' display the how to topic
Help.ShowHelp(Me, ContextHelp.HelpNamespace, HelpNavigator.Topic, "default.html")
    C#
    Copy Code 
    // display the how to topic
Help.ShowHelp(this, ContextHelp.HelpNamespace, HelpNavigator.Topic, "default.html");

     

    Development tools that use Context Ids

    Development environments such as unmanaged Visual C++, Visual Basic 6 and older versions of Delphi using numbers to associate elements of an application to topics in the help system. If that is your situation you can use tools within Document! X to assist with the mapping of context ids to topics.

    Depending on your development approach you might already have context ids assigned in your application and want to map those to topics, or you might want to generate a set of context ids from your topics so that the developers can assign those to user interface elements. 

    To map existing context ids to Topics

    Follow this procedure to map existing context ids that the application development team have already assigned to user interface elements.

    1. Open the Context Id Mapper from the Tools Ribbon Tab;
    2. If you have not already done so, you will be prompted to identify the location of the .h file containing the context ids to map. If you don't already have this file, you will need to obtain it from the development team;
    3. The Context Id Mapper will show a list of assigned and un-assigned context ids;
    4. You can associate a Context Id with a Topic using Drag and Drop.

     

    To assign context ids to Topics and generate a context id .h file

    Follow this procedure if the application development team have not already assigned help context ids to user interface elements and wish to have you provide a .h file containing a context id for each Topic in the project which they can then assign to user interface elements.

    1. Click Create Context Id Header File from the Tools Ribbon Tab;
    2. On the displayed file dialog, identify where you would like the .h file saved;
    3. Provide the generated .h file to the development team.

     

    Once you have established the mapping between help context ids in the application and the Topics in your help system, all that remains is to set the help file name in your application. You should therefore liase with your development team to agree the output .chm filename to use for the help system so that when F1 is pressed in the application it is looking for the correct .chm file name. 

    F1 help using Context Ids is limited to Microsoft Html Help 1.x output. You must therefore generate your help as a Html Help 1.x CHM file in order to support F1 help using Context Ids.

    Supporting F1 help from Visual Studio

    Reference Documentation

    .NET reference documentation topics generated by Document! X automatically contain the necessary information to support F1 help. Once your help system has been deployed to the users of your .NET assembly, they can simply press F1 with the edit cursor over a type or member in your assembly to show the related documentation page.

    F1 support is automatically generated for Help 2.x outputs (if you are targetting Visual Studio 2002-2008) and Microsoft Help Viewer outputs (for Visual Studio 2010, 2012, 2013, 2015 or 2017 RC ).

    Conceptual Topics

    If you are producing an AddIn or Tool that integrates with Visual Studio and you want to provide links to your help system, you will need to define F1 keywords. You can find more background information on Help Integration with Visual Studio in the MSDN Library.

    To add an F1 keyword to a Topic:

    1. Open the Topic for edit;
    2. Switch to the Index Keywords view;
    3. Click the New toolbar button;
    4. Type the desired keyword prefixed with the ! character - this indicates a hidden F1 keyword rather than a keyword in the visible index.

    Once the F1 keyword has been defined for the Topic and the generated help system is deployed, F1 requests for that keyword from your Visual Studio integrated Tool or AddIn will display the Topic against which you defined the F1 keyword.

    See Also
    Html Help 1.x Text Popups

     

     

    © 2018 Innovasys. All Rights Reserved.

    Send Feedback