连接开发人员和帮助作者的 ComponentOne DynamicHelp™

 

引言

任何应用程序最重要的方面之一是为最终用户提供一种全面且易于使用的帮助访问方法，以了解应用程序的工作原理。对于那些创建 Windows Forms 应用程序的开发人员来说，不必再寻找了。借助 ComponentOne DynamicHelp for WinForms，您可以在短短几分钟内轻松地为项目添加上下文敏感的帮助。它还允许您在运行时轻松更改帮助源或单个主题。当帮助文件修改时，无需重新构建您的应用程序。本文演示了如何使用单个 .NET 控件 ComponentOne DynamicHelp 添加上下文敏感的帮助。

关于 ComponentOne DynamicHelp

C1DynamicHelp 是一个 Windows Forms 控件，它使开发人员能够轻松地为他们的应用程序添加强大、上下文敏感的帮助。这可以在设计时或运行时使用创作模式完成。C1DynamicHelp 的创作模式使开发人员能够将应用程序交给帮助文档编写者，以便他们可以为控件分配主题。

先决条件

对于本教程，您必须安装 Microsoft Visual Studio 2008 或 Visual Studio 2005 以及 ComponentOne Studio Enterprise。ComponentOne Studio Enterprise 的免费 30 天试用版和年度订阅可在 ComponentOne 网站上获取。

开发者：启用 ComponentOne DynamicHelp 的创作模式

嵌入帮助的 .NET 应用程序的初始设置步骤由开发人员完成。

您实际上只需要一行代码即可在 C1DynamicHelp 中启用创作模式，另一行代码用于获取主题映射，但在本示例中我们将做更多工作。将添加代码以使用 Ctrl+Shift+A 键组合切换创作模式，并添加其他代码以在关闭应用程序时提醒您保存主题映射（如果您尚未保存）。

步骤 1：创建 Windows Forms 应用程序

打开 Microsoft Visual Studio 2008 或 2005，然后从主菜单中选择“文件”|“新建项目”。

选择 Visual C# 或 VB.NET 作为您的语言。选择 Windows Forms Application 作为项目类型，然后输入项目名称和位置。单击“确定”按钮继续。

步骤 2：向 Windows 窗体添加控件

在本示例中，我们将需要 C1DynamicHelp 控件和几个 UI 控件来分配帮助主题。在将任何控件添加到窗体之前，我们需要调整窗体大小，以便添加的控件尺寸易于阅读。为此，右键单击 Form1 并选择“属性”。在“属性”窗口中，找到“大小”属性，并将其“宽度”和“高度”子属性分别设置为 400 和 300。

在 Visual Studio 工具箱中找到 C1DynamicHelp 图标，然后双击它以将其添加到您的窗体。

该控件将自动停靠在窗体右侧，并且“Help topic on c1DynamicHelp1”属性将自动添加到窗体属性中。注意：任何新添加的控件也将继承此扩展属性。

接下来，在 Visual Studio 工具箱中找到默认的 TextBox 控件，然后双击它以将其添加到窗体。

当 TextBox 控件仍被选中时，转到“属性”窗口并将“文本”属性设置为“在获得焦点时显示主题”。

最后，在 Visual Studio 工具箱中找到 TreeView 控件并双击以将其添加到窗体。

选中 TreeView 后，转到“属性”窗口并选择“节点”属性。单击省略号按钮以显示 TreeNode 编辑器。

在 TreeNode 编辑器中，通过单击“添加根”按钮添加两个根节点。选择第一个根节点并将“名称”和“文本”属性值更改为“概述”。然后选择第二个根节点并将“名称”和“文本”属性值更改为“如何使用”。

“如何使用”节点需要两个子节点，因此在仍然选中该节点时单击两次“添加子项”按钮。选择这两个子节点中的第一个，并将“名称”和“文本”属性设置为“设计时”。对于第二个子节点，将“名称”和“文本”属性设置为“运行时”。

默认情况下，TextBox 和 TreeView 控件的定位和大小可能不是最优的，因此请像下面的屏幕截图一样调整大小和重新排列控件。

步骤 3：将 C1DynamicHelp 连接到帮助源

将 C1Sample.chm 放在本地项目目录中的某个位置。默认情况下，您可以在 C:\Program Files\ComponentOne Studio.NET 2.0\C1DynamicHelp\Tutorials\Data 目录中找到 *.chm 文件。

选择 C1DynamicHelp 控件，然后单击 SmartTag 以打开 C1DynamicHelp 任务菜单。在任务菜单中，单击“HelpSource”属性旁边的省略号按钮。这将显示一个文件选择对话框。浏览到 C1Sample.chm 文件并将其添加为帮助源。

步骤 4：设置创作模式

现在设置 C1DynamicHelp，以便可以在创作模式下使用它。选择 Form1，然后在“属性”窗口中找到 KeyPreview 属性。将 KeyPreview 属性设置为“True”。

双击 Form1，这将用于添加 Form1_Load 事件并显示代码视图。当显示代码视图时，我们将添加此示例所需的所有代码，首先是 OnKeyDown 事件的重写。我们重写 OnKeyDown 事件是为了让简单的组合键 Ctrl+Shift+A 能够切换创作模式。将以下代码添加到我们刚刚添加的 Form1_Load 事件之外的某个位置

C#

// toggle authoring mode when the user hits Ctrl+Shift+A
override protected void OnKeyDown(KeyEventArgs e)
{
   if (e.KeyCode == Keys.A && e.Control && e.Shift)
   {
      c1DynamicHelp1.AuthoringMode = !c1DynamicHelp1.AuthoringMode;
   }
   base.OnKeyDown(e);
}

VB.NET

‘ toggle authoring mode when the user hits Ctrl+Shift+A
Protected Overrides Sub OnKeyDown(ByVal e As System.Windows.Forms.KeyEventArgs)
   If (e.KeyCode = Keys.A And e.Control And e.Shift) Then
      C1DynamicHelp1.AuthoringMode = Not C1DynamicHelp1.AuthoringMode
   End If
   MyBase.OnKeyDown(e)
End Sub

现在，返回 Form1_Load 事件，并添加一行代码来指示 C1DynamicHelp 获取稍后将创建的主题映射

C#

private void Form1_Load(object sender, EventArgs e)
{
   c1DynamicHelp1.TopicMap.Refresh();
}

VB.NET

Private Sub Form1_Load(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles MyBase.Load
   C1DynamicHelp1.TopicMap.Refresh()
End Sub

最后，添加一个 Form1_Closing 事件，以友好地提醒用户保存创作模式下生成的主题映射

C#

private void Form1_FormClosing(object sender, FormClosingEventArgs e)
{
   if (c1DynamicHelp1.TopicMap.HasChanges)
   {
      DialogResult result = MessageBox.Show(
         "Would you like to save the changes you made to control/topic map?",
         "C1DynamicHelp Tutorial", MessageBoxButtons.YesNoCancel , 
         MessageBoxIcon.Question);
      if (result == DialogResult.Yes)
         c1DynamicHelp1.TopicMap.Save();
      else if (result == DialogResult.Cancel)
         e.Cancel = true;
   }
}

仅限 C#：在添加上述代码后，返回设计视图，并通过“属性”窗口为 FormClosing 事件添加事件处理程序。在“属性”窗口中，单击闪电图标，这将显示窗体事件列表。在列表中找到 FormClosing，然后从下拉列表中选择 Form1_FormClosing 以添加事件处理程序。

VB.NET

Private Sub Form1_FormClosing(ByVal sender As System.Object, 
    ByVal e As System.Windows.Forms.FormClosingEventArgs)_
 Handles MyBase.FormClosing
   If (C1DynamicHelp1.TopicMap.HasChanges) Then
      Dim dr As DialogResult
      dr = MessageBox.Show(_
          "Would you like to save the changes you made to control/topic map?",_
          "C1DynamicHelp Tutorial", MessageBoxButtons.YesNoCancel, _
          MessageBoxIcon.Question)
      If (dr = DialogResult.Yes) Then
         C1DynamicHelp1.TopicMap.Save()
      ElseIf (dr = DialogResult.Cancel) Then
         e.Cancel = True
      End If
   End If
End Sub

对于 VB.NET，事件处理程序包含在上面的事件代码中。

此时，我们还没有将控件与帮助文件关联起来，也没有帮助文件的上下文信息。下一部分将向您展示如何创建主题映射并将其与我们刚刚添加到应用程序的 TextBox 和 TreeView 节点关联起来。这是帮助文档编写者介入的地方。

帮助文档编写者：使用 C1DynamicHelp 的创作模式

将帮助主题链接到控件的最后几个步骤由帮助文档编写者完成。

使用创作模式，帮助文档编写者可以直观地将控件与其在帮助文件中的相应主题链接起来，然后将生成的 XML 文件传递给开发人员。

步骤 1：运行应用程序

运行应用程序，然后按下 Ctrl+Shift+A 键激活创作模式。您将看到创作面板出现在 DynamicHelp 窗口的顶部。

步骤 2：将主题映射到 TextBox 控件

要将主题映射到 TextBox 控件，请从工具栏中单击“选择控件”按钮，然后选择 TextBox 控件。您会看到创作面板“控件”字段中的文本更改为 textBox1 : TextBox。

接下来，单击工具栏中的“附加主题到控件”按钮，将显示“选择帮助主题”对话框。

在“目录”选项卡的列表中，选择“术语表”主题。在对话框右上角找到标记为“事件”的复选框组，并确保“使用默认事件”和“鼠标悬停”复选框未选中。只有“获得焦点”应被选中。单击“确定”。

当 TextBox 获得焦点时，将显示“术语表”主题。

步骤 3：将主题映射到 TreeView 控件

现在我们将为 TreeView 的每个节点映射主题。请注意，在 Visual Studio 中，我们可以使用“HelpTopic on C1DynamicHelp1”属性为 TextBox 分配帮助主题，并且我们使用相同的属性为整个 TreeView 设置帮助主题，但您必须使用创作模式来直观地设置每个 TreeView 节点帮助主题。任何继承自 .NET 基类 Control 的控件在将 C1DyanmicHelp 添加到窗体时都会收到“HelpTopic on C1DynamicHelp1”属性。但是，由于 TreeView 的每个节点不继承 Control 类，因此创作模式是直观地为节点分配帮助主题的唯一方法。

单击“选择控件”按钮，然后选择 TreeView 中的“概述”节点。

然后单击“附加主题到控件”按钮。

再次，您将看到“选择帮助主题”对话框，并预选了“目录”选项卡。从目录中，选择“概述”主题，取消选中“使用默认事件”和“鼠标悬停”，然后单击“确定”按钮。

重复上面段落中描述的步骤，只是这次选择“如何使用”节点并将其映射到“如何使用 C1DynamicHelp”主题。

继续以上两个步骤，将“设计时”节点分配给“设计时支持”主题，并将“运行时”节点分配给“运行时支持”主题。每个节点现在都已链接到帮助主题。保存主题映射。

单击软盘图标以保存主题映射。

您的主题映射现在应该已保存到与我们链接到 C1DynamicHelp 的源帮助文件 C1Sample.chm 相同的位置。主题映射将命名为 C1Sample.chm.xml，看起来像这样

<Dictionary>
  <item>
    <key>Form1\c1DynamicHelp1\ControlCapture\groupBox1\controlTree</key>
    <value>WordDocuments/overview.htm</value>
    <events useDefaultEvents="False">1</events>
  </item>
  <item>
    <key>Form1\treeView1\Overview</key>
    <value>WordDocuments/overview.htm</value>
    <events useDefaultEvents="False">1</events>
  </item>
  <item>
    <key>Form1\treeView1\How to use\Design time</key>
    <value>WordDocuments/designtimesupport.htm</value>
    <events useDefaultEvents="False">1</events>
  </item>
  <item>
    <key>Form1\treeView1\How to use\Runtime</key>
    <value>WordDocuments/runtimesupport.htm</value>
    <events useDefaultEvents="False">1</events>
  </item>
  <item>
    <key>Form1\textBox1</key>
    <value>WordDocuments/glossaryofterms.htm</value>
    <events useDefaultEvents="False">1</events>
    <onload>True</onload>
  </item>
  <item>
    <key>Form1\treeView1\How to use</key>
    <value>WordDocuments/howtousec1dynamichelp.htm</value>
    <events useDefaultEvents="False">1</events>
  </item>
</Dictionary>

步骤 4：查看最终产品

首先，在使用 C1DynamicHelp 的自己的应用程序时，有几点需要注意。源 *.chm 和 *.xml 主题映射应保存在同一目录中。当您准备好向客户发布应用程序时，应禁用创作模式。对于示例应用程序，这将涉及注释掉我们添加的所有代码，除了 Form1_Load 事件中的那一行。

现在，在不激活创作模式的情况下运行示例应用程序。选择 TextBox 控件和 TreeView 的各种节点，然后注意我们在创作模式下映射的主题已显示。

摘要

ComponentOne DynamicHelp 通过简化应用程序中主题/控件映射的创建过程，在开发人员和帮助文档编写者之间架起了桥梁。开发人员可以专注于创建优秀的应用程序，而帮助文档编写者可以专注于编写优秀的文档，而无需担心上下文 ID，而无需在每次项目开发发生微小变化后反复传递主题/控件映射。

• 立即为您的 .NET 应用程序添加上下文敏感帮助： 免费下载