How to: Provide Context for Editors or Designers
For an editor or designer, the context is active only when the editor or designer has focus or had focus immediately before the focus was moved to a tool window. You can provide context for an editor or designer by doing the following:
Create a context bag.
Publish the context bag to the selection element identifier (SEID).
Maintain the context in the bag.
These tasks are covered by the following procedures. For more information about providing context, see Robust Programming later in this topic.
To create a context bag for an editor or a designer
Call QueryService on your IServiceProvider interface for the SVsMonitorUserContext service.
A pointer to the IVsMonitorUserContext interface is returned.
Call the CreateEmptyContext method to create a new context or subcontext bag.
A pointer to the IVsUserContext interface is returned.
Call the AddAttribute method to add attributes, lookup keywords, or F1 keywords to the context or subcontext bag.
If you are creating a subcontext bag, call the AddSubcontext method to link the subcontext bag to the parent context bag.
Call AdviseUpdate to receive notification when the Dynamic Help window is about to update.
Having the Dynamic Help window call your editor when it is ready to update gives you the opportunity to delay changing the context until the update occurs. Doing this can improve performance because it allows you to delay running time-consuming algorithms until system idle time is available.
To publish the context bag to the SEID
Call QueryService on the SVsTrackSelectionEx service to return a pointer to the IVsTrackSelectionEx interface.
Call OnElementValueChange, specifying an element identifier (elementid parameter) value of SEID_UserContext to indicate that you are passing context to the global level.
When the editor or designer becomes active, the values in its IVsTrackSelectionEx object are propagated to the global selection. You only need to complete this process once per session, and then store the pointer to the global context created when you called OnElementValueChange.
To maintain the context bag
Implement IVsUserContext to ensure that the Dynamic Help window calls the editor or designer before it updates.
For each context bag that has called AdviseUpdate after the context bag is created and has implemented IVsUserContextUpdate, the IDE calls UpdateUserContext to notify the context provider that the context bag will be updated. You can use this call to change the attributes and keywords in the context bag, and in any subcontext bags, before the Dynamic Help window update occurs.
Call SetDirty on the context bag to indicate that the editor or designer has new context.
When the Dynamic Help window calls UpdateUserContext to indicate that it is updating, the editor or designer can update the context appropriately for both the parent context bag and any subcontext bags at that time.
Note
The SetDirty flag is automatically set to true whenever context is added or removed from the context bag. The Dynamic Help window only calls UpdateUserContext on the context bag if the SetDirty flag is set to true. It is reset to false after the update.
Call AddAttribute to add context to the active context collection or RemoveAttribute to remove context.
Robust Programming
If you decide to use a customized version of the Visual Studio core editor for your project, you do not need to create a context bag or publish that context bag to the SEID because the core editor already provides these features in its implementation. The core editor also includes a general keyword (keyword = "VS.TextEditor") in its context bag and pushes the keyword at the cursor, by default. To use the core editor to provide context, you only need to follow the procedure in this topic for maintaining the context bag. For more information about the Visual Studio core editor, see Core Editor.
If you are writing your own editor, then you must complete all three of the procedures in this topic to provide context for the editor. For more information, see Editor Design Decisions.
Note
To properly activate an editor or designer window and to ensure that command routing is updated properly, you must call Show on the component to make it the focus window.
The SEID is a collection of properties that change based on the selection. SEID information is available through the global selection. The global selection is wired into events triggered by the IVsTrackSelectionEx interface, and has a list of everything that is selected (current editor, current tool window, current hierarchy, and so on).
For editors and designers, in which context can change whenever the cursor moves within a word, it is inefficient to constantly update the context bag. To make updating more efficient any time you detect the cursor moving within the editor or designer window, you can call SetDirty. Doing this allows you to hold your context changes until there is idle time and the IDE's context service sends notification to the editor or designer that the Dynamic Help window is updating. This approach is used in the "To maintain the context bag" procedure in this topic.
After providing context for activities within your editor or designer, you should provide a specific F1 keyword to allow users to get help for the editor or designer itself. The Visual Studio core editor includes hookups for the language service. For more information about how to hook up a language service to an editor that you have created, see Language Service Context for the Core Editor.
See Also
Concepts
Context in the Selection Element Identifier