How to: Control the Dynamic Help Window

Article
11/16/2012

Visual Studio has a Dynamic Help window that provides links to related Help topics based on a user's context. For example, if you begin editing in the code editor, a topic on how to use the code editor displays in the Dynamic Help window. It does this by comparing keywords related to the current context to a list of keywords associated with Help topics.

The ContextAttributes collection and the ContextAttribute object enable you to list the collection of keywords that apply to a specified window in Visual Studio. They also enable you to add and prioritize attributes. Consequently, automation clients can display topics of their choice in the Dynamic Help window when that window — or an element of the window, such as a tab or link — is selected.

A ContextAttribute object represents the context for a particular window or window element. ContextAttributes is a collection of all ContextAttribute objects for a given window. Context is comprised of three context types: Filter, Lookup, and LookupF1:

Filter	An attribute is added to the context collection. Attributes are name/value pairs that are used to either filter the F1 and lookup keyword topics that display in the Dynamic Help window, or filter the topic that appears when a user presses F1.
Lookup	A keyword is added to the context collection. The topic corresponding to this keyword displays in the Dynamic Help window. Lookup keywords provide a list of background or related topics that are shown in the Dynamic Help window. The list of keyword topics in the Dynamic Help window updates when the user changes the current selection. Lookup keywords are derived from the same source as the keywords show in the index of a compiled Help file.
LookupF1	The topic corresponding to this keyword displays in the Dynamic Help window and is used to find F1 Help topics. F1 keywords provide a Help topic when a context element such as a tool window, editor, or modal dialog box is selected and F1 is pressed. F1 keyword topics are also listed in the Dynamic Help window. An F1 keyword is added to the context collection.

There are three types of context attributes indicating where the ContextAttributes object originated:

Global	The global integrated development environment (IDE) context.
High Priority	The High Priority context collection. The High Priority context attribute means that the topic link displays at the top of its link group in the Dynamic Help window.
Window	A window context.

The ContextAttributes collection is available from the following objects:

ContextAttributes	Affects the global context collection, which has the lowest precedence for sorting topics.
ContextAttributes	Affects the context collection of a window. For tool windows, the attributes are in effect only when the window is selected. For editors and designers, the attributes are in effect as long as the editor is the last active MDI child window. If the value of the HighPriorityAttributes property is True, then the attributes are always in effect and highest in precedence.

After you associate a keyword with a window or window element, you can then use it to display a Help topic. By using the XML Help Provider, you can display a custom Help topic or URL. For more information, search the Visual Studio Industry Partner (VSIP) SDK Help for "The XML Help Provider and Dynamic Help".

In addition to controlling the contents of the Dynamic Help window, you can also control its characteristics such as width and height. For more information, see How to: Change Window Characteristics.

Using ContextAttributes and ContextAttribute you can:

Add or remove a keyword name, value, and type.
Obtain the name and value of a keyword.
Obtain a list of High Priority attributes as a ContextAttributes collection from DTE.ContextAttributes.

Note

The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. These procedures were developed with the General Development Settings active. To change your settings, choose Import and ExportSettings on the Tools menu. For more information, see Visual Studio Settings.

Example

This Add-in example demonstrates how to reference and use the various members of the Dynamic Help automation model. This example lists the names and number of keywords associated with Solution Explorer. It also adds a new F1 keyword to it and then removes it. For more information about how to run the example either as an Add-in or as a Visual Studio macro, see How to: Compile and Run the Automation Object Model Code Examples.

Public Sub OnConnection(ByVal application As Object, ByVal _
connectMode As ext_ConnectMode, ByVal addInInst As Object, _
ByRef custom As Array) Implements IDTExtensibility2.OnConnection
    _applicationObject = CType(application, DTE2)
    _addInInstance = CType(addInInst, AddIn)
    ' Pass the applicationObject member variable to the code example.
    CATest(_applicationObject)
End Sub

Sub CATest(ByVal dte As DTE2)
    ' Get a reference to Solution Explorer.
    Dim SolnEx As Window = _applicationObject.Windows.Item(Constants. _
    vsWindowKindSolutionExplorer)
    Dim CA As ContextAttribute

    ' List the current attributes associated with Solution Explorer.
    ListAttr(SolnEx, CA)

    ' Associate a new F1 keyword to Solution Explorer.
    SolnEx.ContextAttributes.Add("ANewKeyword", "900", _
    vsContextAttributeType.vsContextAttributeLookupF1)
    ListAttr(SolnEx, CA)

    ' Delete the new F1 keyword from Solution Explorer.
    SolnEx.ContextAttributes.Item(3).Remove()
    ListAttr(SolnEx, CA)
End Sub

Sub ListAttr(ByVal SolnEx As Object, ByVal CA As ContextAttribute)
    ' Support function for CATest(). Lists the current attributes 
    ' associated with Solution Explorer.
    Dim msg As String
    msg = ""

    MsgBox("Number of context attributes in Solution Explorer: "  _
    & SolnEx.ContextAttributes.Count)
    For Each CA In SolnEx.ContextAttributes
        msg = msg & CA.Name & Chr(13)
    Next
    MsgBox(msg)
    msg = ""
End Sub

public void OnConnection(object application,
 Extensibility.ext_ConnectMode connectMode, object addInInst, ref
 System.Array custom)
{
    _applicationObject = (DTE2)application;
    _addInInstance = (AddIn)addInInst;
    //  Pass the applicationObject member variable to the code example.
    CATest(_applicationObject); 
}

public void CATest( DTE2 dte ) 
{ 
    // Add-in code.
    // Get a reference to Solution Explorer.
    Window SolnEx = dte.Windows.Item
( Constants.vsWindowKindSolutionExplorer ); 
    ContextAttribute CA = null; 

    // List the current attributes associated with Solution Explorer.
    ListAttr( SolnEx, CA ); 

    // Associate a new F1 keyword to Solution Explorer.
    SolnEx.ContextAttributes.Add( "ANewKeyword",
 System.Convert.ToString(900),
 vsContextAttributeType.vsContextAttributeLookupF1 ); 
    ListAttr( SolnEx, CA ); 

    // Delete the new F1 keyword from Solution Explorer.
    SolnEx.ContextAttributes.Item( 2 ).Remove(); 
    ListAttr( SolnEx, CA ); 
} 

public void ListAttr( EnvDTE.Window SolnEx, ContextAttribute CA ) 
{ 
    // Support function for CATest(). Lists the current attributes 
    // associated with Solution Explorer.
    string msg = null; 

    MessageBox.Show
( "Number of context attributes in Solution Explorer: " 
+ SolnEx.ContextAttributes.Count); 
    foreach ( EnvDTE.ContextAttribute temp in 
SolnEx.ContextAttributes ) 
    { 
        CA = temp; 
        msg = msg + CA.Name + "\n"; 
    }
    MessageBox.Show( msg); 
    msg = ""; 
}

How to: Control the Dynamic Help Window

Example

See Also

Tasks

Concepts

Other Resources

Additional resources