Inside Microsoft® Visual Studio® .NET 2003 [Electronic resources] نسخه متنی

Customizing the Dynamic Help Window

You can do a couple of things to customize the way the Dynamic Help Window presents data. First, you can control what data is presented through the Dynamic Help page of the Options dialog box (shown in Figure 14-6). All the options for the Dynamic Help window are turned on by default; you won't get extra information by setting options, but you can get more focused on what you want. Also, because the Dynamic Help window is small, you can make sure you can see the important information without having to scroll up or down. For example, deselecting the Samples option moves the Getting Started topic just below the Help topic (as shown in Figure 14-7).

The second way you can customize Dynamic Help is by adding your own custom links to the Dynamic Help window through the XML Help Provider service, which we'll discuss next.

Using the XML Help Provider Service

The dynamic links that you display can open any kind of help, including plain text, HTML, and even Microsoft Word documents, so this can be an effective alternative to creating the more complex help that we'll discuss later in the chapter.

To add your own links to the Dynamic Help window, you must create an XML file and place it in the appropriate folder. The next instance of Visual Studio .NET 2003 that you open will display your information when the specified context criteria are met. You have to meet just a few requirements to have your information displayed properly. Let's go over these one at a time.

Location

Your XML file can be named anything you want, but it must be placed in the folder C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\IDE\ HTML\XMLLinks\1033. If you install Visual Studio .NET to another folder or if you're using Visual Studio 2002, your path will be a little different, but the Common7\IDE\HTML\XMLLinks\1033 path is the one that's important. The file must have an .xml extension.

Note

In Windows, 1033 is the code for U.S. English. If your copy of Visual Studio .NET is localized for another region, the folder you copy your XML file to will have a different code number.

In the 1033 folder, you'll find at least one existing XML file. This file, Context.xml, contains the link groups that have been set up in advance for Visual Studio .NET. You can add your own link groups by editing this file or by specifying them in your own XML file.

Schema

The XML Help that you add to the Dynamic Help window requires a specific schema in order to work properly in the IDE. This schema looks like the following:

<DynamicHelp xmlns="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd" 
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" 
xsi:schemaLocation="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd">

Link Groups

Link groups are the groupings of topics in the Dynamic Help window. You can create your own link groups or you can add your help links to one or more of the existing help groups. You specify link groups using the LINKGROUP tag. In this example, we'll create a new link group with an ID of "InsideVSNET" and a Title value of "Inside Visual Studio .NET". The ID value will be used when we create a link to some information.

<LINKGROUP ID="InsideVSNET" Title="Inside Visual Studio .NET"
Priority="300">
<GLYPH Collapsed="1" Expanded="2" />
</LINKGROUP>

The Priority is a number that's added to other scored attributes to move a link higher or lower in the list of links in the Dynamic Help window. You can see these scores if you look at the debug output shown earlier in Figure 14-5.

The GLYPH tag lets you specify the icons that are displayed for your link group. You can specify one icon for the collapsed view and another for the expanded view of your group. Table 14-3 shows the built-in icons.

Context

The Context tag contains the body of the information you're adding to Dynamic Help. This tag contains all the other context-related tags for your information, so it's essentially the body of the information you want to present. The rest of the tags we'll discuss in this section are found in the Context tag.

Inside the Context tags are two tags that determine what gets shown in Dynamic Help. The Keywords and Attributes tags contain KItem and AItem subtags, respectively, which let you specify when a particular topic comes into context. The item tags in these sections are weighted based on factors such as the type of project currently open or the window that has focus. The online documentation has some information about these tags and how they're scored, but we suggest you use the debug output to determine what's going on.

We'll keep our example really simple. Because we want the information to be available to the user in all circumstances, we'll use the "VS.Ambient" KItem value. This value displays a topic at all times, as opposed to something like the "VS.SolutionExplorer" KItem, which displays a topic only when Solution Explorer gets the focus. You can see the code for this item here:

<Keywords>
<!-- KItems contain keywords for a topic.-->
<KItem Name="VS.Ambient" /> 
</Keywords>

The final thing we need to do is to create some links. These are held in the Links tag using LItem tags, as shown here:

<Links>
<!-- LItems contain links to the topics you wish to display.-->
<LItem URL="file:///C:\InsideVSNET\Info" 
LinkGroup="InsideVSNET">Macro Information</LItem>
<LItem URL="http://www.microsoft.com/mspress/books/6425.asp" 
LinkGroup="InsideVSNET">Web Page</LItem>
<LItem URL="http://www.microsoft.com/mspress/support/" 
LinkGroup="InsideVSNET">Support</LItem>       
</Links>

Each LItem contains a number of attributes. The URL attribute is the link to the help topic you want to display. The LinkGroup attribute contains the ID of the LinkGroup under which you want to display the link. In this case, we created three links. The first is a link to a file on the C: drive. The second and third links are to this book's Web page and to the Microsoft Press Support Web site.

Listing 14-1 shows the file InsideVSNET.xml, which is in the 1033 folder, as mentioned earlier.

Listing 14-1 Adding links to Dynamic Help

InsideVSNET.xml
<?xml version="1.0" encoding="utf-8" ?>
<!-- These schema are required for Dynamic Help.--> 
<DynamicHelp xmlns="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd" 
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" 
xsi:schemaLocation="http://msdn.microsoft.com/vsdata/xsd/vsdh.xsd"> 
<!-- Create a link group in which to display our information.--> 
<LINKGROUP ID="InsideVSNET" Title="Inside Visual Studio .NET" 
Priority="500">
<GLYPH Collapsed="1" Expanded="2" />
</LINKGROUP>
<Context>
<Keywords>
<!-- KItems contain keywords for a topic.--> 
<KItem Name="VS.Ambient" /> 
</Keywords>
<Links>
<!-- LItems contain links to the topics you wish to display.-->
<LItem URL="file:///C:\InsideVSNET\Info" 
LinkGroup="InsideVSNET">Macro Information</LItem>
<LItem URL="http://www.microsoft.com/mspress/books/6425.asp" 
LinkGroup="InsideVSNET">Web Page</LItem>
<LItem URL="http://www.microsoft.com/mspress/support/" 
LinkGroup="InsideVSNET">Support</LItem>       
</Links>       
</Context>
</DynamicHelp>

Figure 14-8 shows Visual Studio .NET after you link to the book's Web page from the Dynamic Help window.