Add Help to Your Application/zh CN

From Lazarus wiki
Revision as of 03:07, 4 February 2021 by Robsean (talk | contribs) (帮助基础)

Deutsch (de) English (en) español (es) français (fr) 中文(中国大陆)‎ (zh_CN)

LCL带来一个帮助系统,允许你 为你自己的应用程序来创建帮助

快速开始

在 examples/helphtml/中打开示例。

演示如何使用HTML帮助控件。只需要拖拽它们到你的项目中。并设置并创建HTML文件。就可以给程序提供HelpKeyword。

如果要使用CHM帮助,请参照CHM帮助部分。

这里是一个非常好的演示 (chmdemo.zip): http://forum.lazarus.freepascal.org/index.php/topic,38487.msg261731.html#msg261731

帮助基础

LCL帮助包含两部分: 帮助数据库和查看器. 帮助数据库包含关键字(ID, node, message, pascal, ...)到帮助页面(或者帮助网页网站,或者...)。 帮助查看器援引帮助数据库来向用户显示帮助信息。

  • THelpDatabase管理内容。它可以是HTML页面、或fpdoc XML文、或一个CHM文件、或一个数据库、或任何东西的一个集合。
  • THelpViewer是一个显示帮助内容的组件。例如,一个mime类型的text/html查看器可以启动一个网页浏览器。

当请求帮助时,LCL询问每个注册的THelpDatabase,并且每个数据库都会返回一个条目列表。 如果返回数个条目,LCL会要求用户来选择一个条目。 接下来LCL或要求数据库来显示条目的帮助。数据库提取帮助内容,并向LCL请求支持mime类型内容的查看器。 最后,查看器显示帮助内容。

CHM

上下文相关的CHM应用程序帮助自lazarus1.0和更高版本开始能够使用。

一个演示程序,包含演示如何使用CHM和lhelpCHM查看器(默认情况下与IDE帮助使用同一个查看器)来包含上下文相关的帮助。 请查看${lazarusdir}/components/chmhelp/democontrol/.

你可以写你自己的CHM文件,例如,使用古老的Microsoft HTML Workshop,或者使用新的Lazarus chmmaker 工具(位于$(lazarusdir)/tools/chmmaker)。 你可以使用一个TCHMHelpDatabase控件,像下面描述的THTMLHelpDatabase控件。

使用CHM系统的优点是一个较小的、独立的帮助文件,而不是多个文件。另一方面,并不是每个系统都默认安装了CHM查看器,因此您可能希望包含lhelp,一个用Pascal编写的CHM查看器,包含在Lazarus源代码(components/chmhelp/lhelp/lhelp.lpi)中。

使用LHelp

  • 在你的窗体上放置一个TLHelpConnector
  • 使用LHelp可执行文件的名称和位置来设置LHelpPath。(路径可以是绝对的,也可以是相对于应用程序的目录)
  • 设置AutoRegister为true
// Example with both chm file and LHelp.exe in Application folder.
Procedure TForm1.FormCreate(Sender: TObject);
Begin
  If FileExists(ChangeFileExt(Application.ExeName, '.chm')) Then
  Begin
    CHMHelpDatabase1.Filename := ChangeFileExt(Application.ExeName, '.chm');
    CHMHelpDatabase1.Keyword := 'test';
    CHMHelpDatabase1.AutoRegister:=True;

    LHelpConnector1.LHelpPath := IncludeTrailingBackSlash(ExtractFileDir(Application.ExeName)) + 'lhelp.exe';
    LHelpConnector1.AutoRegister:=True;
  end
  Else
    mnuHelpMain.Enabled := False;
End; 

Procedure TForm1.Button1Click(Sender: TObject);
Begin
  If mnuHelpMain.Enabled Then  
    ShowHelpOrErrorForKeyword('','test/Main.html');
    //ShowTableOfContents;  (Not implemented for TCHMHelpDatabase)
End;

HTML

LCL提供两个组件来使用HTML文件获取帮助:THTMLHelpDatabaseTHTMLBrowserHelpViewer。 为查看HTML帮助,查看lazarus示例:examples/helphtml/htmlhelp1.lpi。

为你的应用程序设置HTML帮助

Lazarus help items

添加HTML帮助到你的应用程序是很容易的:

  • 在一个窗体上放置一个THTMLHelpDatabase
  • 设置AutoRegister为 true 。
  • 设置KeywordPrefixhtml/ 。它意味着所有关键字都必须以字符串html/为开头。
  • 设置BaseURLfile://yourhelp/。这将在子文件夹yourhelp中搜索HTML文件。你可以具体指定完整的路径(像:file:///usr/lib/yourhelp/)或者一个URL(像:http://www.yoursite.com/)。
  • 在窗体上放置一个THTMLBrowserHelpViewer。这个组件可以启动用户的默认浏览器。
  • 设置AutoRegister为 true 。

创建一个帮助条目

  • 现在创建子文件夹yourhelp,并创建一个html页面 yourhelp/edit1.html。如果是网站,帮助页应该是可使用的:http://www.yoursite.com/edit1.html
  • 在一个窗体上放置一个TEdit。
  • 设置HelpTypehtKeyword
  • 设置HelpKeywordhtml/edit1.html

当运行程序时,你可以聚焦于编辑并按F1键援引助。在macOS下帮助按键是Cmd-?(或者Cmd+Shift+?,取决于你的键盘布局)。 注意: 一些窗口管理器、小部件集组合不会将F1传递给LCL。

INF (使用fpGUI的DocView帮助查看器)

查看Lazarus论坛中包含的消息和示例项目。[1]

It shows a fully working example of an LCL application using fpGUI's DocView help viewer. It shows context sensitive help and general help.

例如:

  • Set focus to a specific control and press F1. It will show the help topic for that specific control.
  • Click the Help button and it will show the help topic for the dialog/form.
  • Select the "Help -> Show Help" menu item and it will show the general application help and display the first topic in the help file.

请参阅