Help Integration Essentials
Context sensitivity is a Help feature that enables Help authors and VSPackage developers to create a one-to-one relationships between objects in the Visual Studio integrated development environment (IDE) and Help topics. At run time, whenever a context-sensitive object is selected, a user can access the related Help topic by pressing F1 or by clicking a button on the object. If the user presses F1 or clicks the button, the local Help browser (Microsoft Document Explorer, for example) is opened if it is not already open, and the topic is displayed.
Context-sensitive Help can be provided for editors, designers, tool windows, project hierarchies, hierarchy items, dialog boxes, language services, or designers.
Help authors and VSPackage developers work together to create context-sensitive Help. The Help author creates a compiled Help collection that contains Help topics and associated keywords and attributes. By using the keywords, the VSPackage developer connects relevant IDE objects to the Help collection so that the correct topic is displayed whenever a user requests Help on a selected object. For more information, see Connecting Context-Sensitive Help.
Help Integration Overview
This section lists some important concepts about Help integration. For more information, follow the links or see "Where To Go Next" at the end of this topic.
Help collections (a collection of related help topics) can be authored, built, and deployed by using HelpStudio Lite. For more information, see Help Authoring.
You can use the Help Integration Wizard to make a Help collection into a Visual Studio deployment project. For more information, see Help Integration Wizard Overview.
Components that provide context-sensitive Help are called context providers.
A context provider creates or adds F1 keywords, lookup keywords, and filterattributes to a collection of context items, which is named context bag.
In a typical configuration, an F1 keyword is a high-priority keyword that is linked to a Help topic. For example, a tool window usually pushes one F1 keyword into its context bag to provide Help for the tool window.
A lookup keyword is a lower-priority keyword that is linked to a Help topic for a selectable object, such as a selected object in a tool window.
An attribute is a name-value pair that can be used to filter out keywords from matching topics.
Context bags can have subcontext bags. For example, selection of an an object in a tool window usually creates a subcontext bag of keywords for that object.
Several context bags may be available at the same time. For example, if a tool window is active, the tool window and the active project hierarchy can both have context bags.
The union of the context bags and subcontext bags for all context providers in the active selection provides the overall context for the IDE. For more information, see Active Context.
When the user opens Help, the active context bag is passed to the Help browser. If the keyword at the top of the context bag exactly matches a keyword in the index of the Help collection, that keyword will be selected in the Index pane, and the corresponding Help topic will appear in the Help window.
If no match is found, the Help browser then tries the next topmost keyword in the context bag.
If no exact matches are found in the context bag, the Help browser selects the nearest match in the Index pane to the topmost lookup keyword. No Help topic is displayed.
The format of the keywords is arbitrary, and the comparison to the Help collection index is accomplished by using simple string matching. The recommended format for a keyword is namespace.topic.subtopic.
Where to Go Next
The following table lists samples, Help topics, and tutorials that can help you start to use the Help Integration features of the Visual Studio SDK:
If you want to: |
Go to: |
|---|---|
Learn more about context-sensitive Help |
|
Learn more about active context |
|
Provide context for editors or designers |
|
Provide context for a tool window |
|
Provide F1 Help for a toolbox item |
|
Provide F1 Help for a dialog box |
See Also
Other Resources
Change History
Date |
History |
Reason |
|---|---|---|
December 2010 |
Removed non-functional link. |
Customer feedback. |