11.1 Help文件的建立
Help文件是Micosoft Windows3.0以上的版本提供的超文本帮助文件。利用这种超文本,用户可非常方便地使用帮助文件系统。帮助文件是以主题为主线进行编写的,一个主题可以跳转至相关的主题,也可按关键字进行主题查询。帮助文件与软件开发工具相结合,可实现应用程序的'上下文敏感',而且帮助系统自动装入。“上下文敏感”是指根据程序当前执行代码来显示Help文件的相应部分。
Windows提供的很多应用程序都有帮助系统,读者可以从这些系统中了解应用程序的许多信息。
11.1.1 建立Help文件所需的工具和文件
程序员可为自己的应用程序建立帮助文件系统。但建立最基本的帮助系统, 必须有以下文件
1. WinHelp 应用程序 ( WinHelp.exe) 。运行帮助系统实际上是运行用帮助源文件的
WindHelp程序。帮助文件只有通过WinHelp文件才能运行。
2. 能创建主题的字处理器。这种处理器能以RTF格式保存文件, 能创建$,#,K,+脚标。RTF(Rich Text Format)格式是一个能记录各种文本特征的文件格式。这些特征包括字体大小、线型风格等。Microsoft Word 6.0处理器能满足以上要求。
3. 一个能以ASCII格式保存文件的字处理器或编辑器,这是为了创建Help工程文件(.HPJ文件)。
4. 帮助文件编译器(HCP.EXE或HC31.EXE),两种编译器均能编译在Windows3.1 环境中使用的帮助文件,但不能编译Windows3.0环境下的帮助文件。HCP.EXE是保护模式的编译器,能更好地使用内存空间。要在Windows的Dos窗口中使用HCP.EXE编译器。
5. 帮助编译器所需的错误信息源文件(HCP.ERR或HC31.ERR)。如果帮助文件在编译过程中出现错误,WinHelp运行时将提示有关的错误信息,而这些信息保存在HCP.ERR或HC31.ERR文件中。
以下工具能实现帮助系统的高级特征:
1. 热点(Hotspot)编辑器(SHED.EXE);
热点编辑器能创建分段超图像文件(.SHG)。这种文件包括一些分成多个热点的图像,当用户单击图像,将弹出一个窗口或跳转至另一主题。
2. 多分辨率位图编译器(MRBE.EXE);
这种编译器能将具备多种分辨率的位图结合到一个文件中,以供WinHelp 使用。WinHelp检查显示器的分辨率, 然后以相应的分辨率加以显示。
3. 图像编辑器,它能以位图形式保存图像文件。 使用图像编辑器创建说明和自定义按钮。
4. 绘图软件。用以创建除了位图之外的元文件(WMF);
程序员可以直接把图像插入文本中,也可以用Windows剪贴板把图像粘贴至文本中。
11.1.2 Help文件的创建
下面介绍最简单、最直接的创建Help文件的方法,假设在Word中创建主题。
创建Help文件分以下4个步骤:
1. 建立组成帮助文件的主题,并以RTF格式保存;
2. 建立内容主题(Content Topic),并以RTF格式保存;
3. 建立帮助工程文件(.HPJ)以文本格式保存;
4. 将工程文件编译成帮助源文件(.HLP)。
11.1.2.1 建立主题
一个简单的帮助主题包括主题题目(Title),主题文本(Text),脚标,主题内容,全局查询、打印。主题最好是带有题目,题目写在主题的第一行。用不同的字体大小、颜色以示区别
写完题目后,可输入主题的文本。输入时不用担心每行的宽度。 编译好的帮助文件会根据窗口大小自动确定行宽。在主题的最后插入一个分页符,WinHelp把每页视为一个单独主题。
书写主题文本时应注意尽可能地把文本写成小段落列表,这样能方便阅读; 同时要控制主题长度,这样用户不需要使用滚动条来阅读文本。
在主题中应加入一些脚标, WinHelp 使用这些脚标辨识主题并提供一些导向控制 (Novigation Control),四种典型脚标如表11.1所示。
表11.1 脚标以及用途
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
符号 适用于 用 途
──────────────────────────────────
# 内容字符串 唯一辨识主题
$ 标题 在搜询对话框和搜询历史列表框中显示主题
K 关键字(段) 出在搜询对话框中
+ 浏览顺序 用户使用时的浏览顺序
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
以下分别介绍四种脚标的插入方法:
1. 插入#脚标。把光标移至主题的最前端插入#脚标。这时主题文本下端也会出现#,在此后键入内容字符串。WinHelp使用内容字符串作为唯一的辨识主题。用户永远也看不见这些字符串,但设计人员用它们定义跳转主题。
2. 插入$脚标,把光标移至#脚标后,插入$脚标。在文本下端的$脚标处,输入主题的标题,该标题与第一行出现的标题一致,标题将会出现在搜询对话框和搜询历史对话框中
3. 插入K脚标。在主题第一行的脚标之后插入K脚标,在主题文本中的K 脚标后键入字段,这些字段将出现在搜询列表框中,见11.3图。
4.插入+脚标。在主题第一行的K脚标之后插入+脚标。在主题文本以下的+ 脚标处键入浏览顺序标识符。标识符可以是一个数(如005),或一组名字加上冒号和数(如 CAL C:005)一个主题只能有一个浏览顺序。
热点是用户可以激发某种动作的文本或图像。一个热点可跳转至另一个主题。在其它窗口中显示主题或执行宏。多数情况下,重要字段被设计成热点以实现主题跳转。
以下是实现主题跳转的步骤:
1. 输入要跳转的字段或插入图像;
2. 高亮度选择字段,用双下划线格式化。在MicroSoft Word中,按ALT +T 键弹出字符格式对话框,在列表中选择双下划线;
3. 在紧挨在这些字段或图像之后,键入指定主题的字符串。 并对内容字符串进行隐藏格式化。这个内容字符串是跳转主题的内容字符串;
根据以上步骤能实现主题之间的跳转。
最后要把编辑的文件以RTF格式保存下来,WinHelp只能编译RTF文件。以下是典型的RTF文件:
#$+ Help Example Indexindex_info 1 of 2index_2
Commands
Edit Menumenu_edit
File Menumenu_file
Glossary
Defined Termsglossary
Procedures
Copying Textproc_copying_text
Deleting Textproc_deleting_text
Exitingproc_exiting
Available From Your Application
Context Sensitive Topics
cs_topics
# main_index
$ Help Index
+ index:0005
11.1.2.2 建立内容主题
内容主题列出了帮助系统的主要部分。用图标启动帮助系统或按Content按钮均出现内容主题。内容主题的每个项目都可跳转。
建立内容主题与建立一般主题类似,WinHelp默认第一个主题为内容主题。其建立步骤如下:
1. 移至第一个源文件的开始处;
2. 键入希望出现的主题标题,这些标题处于不同的行;
3. 将每个主题设置成热点。
11.1.2.3 建立帮助工程文件
帮助工程文件是一个文本文件。包含了有关帮助文件的许多信息。 编译器对工程文件进行编译。工程文件的扩展名必须是HPJ,编译后的扩展名是HLP:
下面是一个简单的帮助工程文件:
[OPTIONS]
CONTENTS=context_string
TITLE=title
COMPRESS=compress_level
ERRORLOG=log_filename
[CONFIG]
BrowseButtons()
[FILES]
RTF_filename_1
RTF_filename_2
RTF_filename_3
[OPTIONS]
Context_String是内容主题的内容字符串。这一行并不是必须有的。 如果没有第一行,WinHelp把第一个帮助文件的第一个主题作为内容主题。
TITLE = title
title是帮助窗口的标题。不要将标题用引号括住。这一行也不是必需要有的。如果没有,缺省的标题是Windows Help.
CoMPRESS = Compress level
Compress_level决定工程文件在编译时是否被压缩, 压缩后的文件编译时要花较长的时间。
表11.2 为Compress_level的取值:
表11.2 Compress_leve的取值及含义
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
取值 编译时间 文件大小
─────────────────────────────
FALSE 快 大(无压缩)
MEDIUM 中等 中等(高度压缩)
HIGH 慢 小(无压缩)
0 快 大(无压缩)
1 慢 小(高度压缩)
No 快 大(无压缩)
TRUE 慢 小(高度压缩)
YES 慢 小(高度压缩)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ERROR(LOG = log_filename)
log_filename是WinHelp运行时的错误输出文件。如果编译时工程文件出错,需要一个记录错误的文件。如果工程文件有这一行,WinHelp在运行时自动创建的文件,如果没有,错误将显示在屏幕上,但不存入任何文件中。
BrowseButton()
如果有这一行,帮助按钮条中将出现>>和<<键,要实现顺序浏览, 还需在帮助文件中定义。详见11.1.2.1节中的插入+脚标。
[FILEs]
RTF_filename是.RTF源文件名。所有的RTF文件构成整个帮助系统。每个RTF 应处在
不同的行。
以下是工程文件的实例
; This help project requires hc 3.1
[OPTIONS]
errorlog = iconwrks.err
title = IconWorks Help
contents = CONTENTS
compress = false
oldkeyphrase = false
warning = 3
[FILES]
iconwrks.rtf
[MAP]
CONTENTS 1
EDITOR_KEYBOARD 2
EDITOR_COMMANDS 3
VIEWER_KEYBOARD 5
VIEWER_COMMANDS 6
DEFINING_COLORS 1000
EDITOR_FILE_MENU 1100
EDITOR_FILE_MENU 1101
EDITOR_FILE_MENU 1102
EDITOR_FILE_MENU 1103
EDITOR_FILE_MENU 1104
EDITOR_FILE_MENU 1105
EDITOR_EDIT_MENU 1200
EDITOR_EDIT_MENU 1201
EDITOR_EDIT_MENU 1202
EDITOR_EDIT_MENU 1203
EDITOR_EDIT_MENU 1210
EDITOR_EDIT_MENU 1211
EDITOR_EDIT_MENU 1212
EDITOR_VIEW_MENU 1108
EDITOR_VIEW_MENU 1109
EDITOR_VIEW_MENU 1110
EDITOR_VIEW_MENU 1111
EDITOR_VIEW_MENU 1112
EDITOR_VIEW_MENU 1111
EDITOR_TOOLS_MENU 1400
SELECT_TOOL 1401
PAINT_TOOL 1402
FILL_TOOL 1403
LINE_TOOL 1404
[WINDOWS]
main = "IconWorks Help", (0,0,1023,1023 ),,, (192,192,192 )
glossary = "IconWorks Help", (222,206,725,486 ),,, (192,192,192 ), 1
[CONFIG]
CB("glossary", "&Glossary", "JI(`iconwrks.hlp>glossary', `GLOSSARY')")
BrowseButtons()
11.1.2.4 编译帮助工程文件
有两种编译器可以编译帮助工程文件:HCP.EXE ,H31.EXE。两种编译器编译的文件不能在Winddow3.0中使用,但能在Windows 3.1中使用。其中HCP.EXE是保护模式“编译器”,它能更好的使用内存。必须在Windows的Dos窗口中使用HCP.EXE。
编译前要注意两个问题:
1. 所有源文件必须以RTF格式保存;
2. 下面的文件必须在同一个目录下
● 所有的.RTF文件
● 帮助编译器(HCP.EXE,HC31.EXE)
● 编译器错误信息源文件(HCD.ERR,HC1.ERR)
● 帮助工程文件(.HPF)
● 任何引用位图或SHED的文件(.BMP.SHG)
如果以上文件不在同一目录中,必须在工程文件中定义相应的路径。
编译要在Dos环境中进行,命令格式:
Help_Compiler_rootname project_File_rootname
Help_Compiler_rootname是不带扩展名的编译器名字。project_file_rootname是不
带扩展名的帮助工程文件名,如:
HCP MYHELP
11.2 Delphi应用程序的Help编程
Delphi应用程序能够方便地应用帮助系统。程序可以动态地运行帮助系统。 对话框可以与帮助系统相联。
11.2.1 定义应用程序的帮助文件
要在应用程序中使用帮助系统,必须有相应的帮助文件。程序可以编写自己的帮助文件, 也可以使用已有的帮助文件。 另外,要为应用程序定义帮助文件以便在用户需要帮助时应用程序能打开相应的帮助文件。
在 Delphi 集成开发环境中选择“Options | Project” 菜单项, 系统弹出工程选择对话框, 再选择Application Options页面,在辅助文件中输入帮助文件名。
所有的应用程序都是TApplication的派生类。TApplication有三种方法调用在线帮助系统。
HelpContext方法可调用WinHelp(关于Winhelp的内容见上节)。它把HelpFile 中的文件名和一个文本代码传递给WinHelp。HelpFile是TApplication的字符串类型的属性,专门用来存放Help文件的。如果HelpFile属性是空字符,HelpContext返回假值,其它情况均返回真值。
下面的例子使用窗体上的一个按钮,当用户单击按钮,屏幕出现DATA.HLP文件中714号主题内容。
procedure TForm2.Bin1Click(Snder : TObject)
begin
Application.HelpFile := DATAHLP;
Application.HelpContext(714);
end;
HelpJump方法可调用WinHelp。它传递HelpFile属性中的文件名和帮助文件的内容字符串(详见11.1节)。内容字符串是帮助文件中唯一辨识帮助主题的字符串。如果HelpFile 属性是空字符,HelpFJump返回假值,其它情况均返回真值。
下面的例子使用了窗体上的一个按钮。当用户单击按钮, 帮助系统调出了 DELPH2.HLP文件中的Default属性。因为Default属性的内容字符串是VclDefaultProperty。
procedure TForm1.Tbn|Click(Sender : TObject)
begin
Application.HelpFile := 'DELPHI.HLP';
Application.HelpJump ('VclDefaultProperty');
end
HelpCommand方法能快速访问WinHelp函数中的各种命令。根据这些命令WinHelp执行不同的动作。表11.2是WinHelp函数的有关信息。
BOOL WinHelp(hwd,LpszHelpFile,fuCommand,dwData)
表11.2 WinHelp的参数及含义
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
参数 类型 描 述
───────────────────────────────
hwnd HWND 请求帮助的窗口
LpszHelpFile LPSTK 待显示的帮助文件的文件名
fuCommand UNIT 请求的帮助类型
dwData DWORD 帮助所需的描述表或关键字
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
HelpCOmmand向WinHelp传递fuCommand和dwData,fuCommand 是帮助类型可为表11.3中的列值之一。
表11.3 fuCommand的取值及含义
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
值 含 义
───────────────────────────────
HELP_LONTEXT 显示dwData指定描述长的帮助信息
HELP_CONTENTS 显示帮助的内容主题
HELP_SET_LONTENTS 如果dwData是Orol04则在一个弹出
式窗口中显示Help主题
HELP_HELP PONHELP 显示Help应用程序的自身帮助,函
数忽略lpszHelpFile和dwData参数
HELP_INDEX 显示帮助文件的索引
HELP_KEY 显示dwData指定的关键字的帮助
HELP_MULTIKEY 显示一个关键字的帮助,该关键字
在一个可变关键字表中
HELP_QUIT 向Help应用程序报告文件不再使用
HELP_SETNDEX 把dwData指定的描述符作为帮助文
件的当前索引
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
dwData参数的含义依赖于fuCommand的设置,如果fuCommand为HELP_CONTEXT,dwData为一个32 位的无符号整数,它包含一个描述表标识号:如果 fuCommand 为 HELP_KEY,dwData 则为一个指定长指针,所指的字符串是帮助的关键字。 如果 fuCommand 为HELPMULLTIKEY,dwData则指向一个MULTIKEYHELP数据结构的长指针。
下面的例子使用了窗体中的按钮。当用户单击按钮帮助系统将显示指定文件的帮助内容主题。
procedure TForm1.Bin1Click(Sender : TObject)
begin
Application.HelpFile := 'MyHlep.HLP'
Application.HelpCommand(HELP_CONTENTS,0);
end;
TApplication部件的OnHelp事件响应帮助事件。 当应用程序接收到一个所需的帮助
时,发生OnHelp事件。使用OnHelp事件可以在需要帮助时定义一些特殊过程。 以下的例子改变了应用程序的帮助文件,AppHelp函数用来处理OnCreate事件。
function TForm1.AppHelp(Command.Word;Data : lontint) : Boolean
begin
if OpenDialog1.Exeeute then
Application HelpFile := OpenDialog1.FileName;
end;
11.2.2 通用对话框中使用帮助系统
Delphi通用对话框中都能显示一个帮助按钮。如果程序显示了对话框中的帮助按钮,应该确保应用程序的帮助文件中有相应的主题。
在通用对话框中使用帮助系统,要做到以下三点:
1. 把对话框的Option|SHOWHelp属性设置成true,这样在程序运行时将出现帮助按钮。 ShowHelp 属性与其部件的名字相关, 例如字体对话框的 ShowHelp 属性称为fdShowHelp。
2. 为对话框部件定义帮助文件。
3. 定义应用程序的文件名。
11.3 Delphi帮助提示(Hint)的应用
使用Delphi集成开发环境时,用户常把鼠标置于程序部件上,如加速按钮,对齐按钮等。鼠标在部件上停留超过一定时间后,Delphi将会显示一个弹出窗口, 里面有部件名称和概述。
这就是Delphi的帮助提示。Delphi的应用程序可通过定义ShowHint 属性实现帮助提示。
11.3.1 帮助提示的显示
ShowHint属性可应用于所有的控件和应用程序部件,控件的ShowHint 属性含义与程序的稍有不同。控件的ShowHint属性决定某一控件是否显示帮助提示,如果ShowHint 是真值,当用户把鼠标置于控件之上超过一定时间后,控件将出现帮助提示。如果是假值,则不出现提示。控件是否显示还决定于控件的ParentShowHind属性。如果 ParentShowHint是真值,控件的父类的ShowHint属性将决定控件是否显示帮助提示。 假如有一个分组框和一个检查框,分组框是检查框的父件。表11.3说明了子件与父件的 ShowHint,ParentShowHint属性设置对子件帮助提示的影响。
表11.3 Hint属性设置对帮助提示的影响
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
分组框ShowHint 检查框ParentShowHint 检查框ShowHint 帮助提示
─────────────────────────────────────
T或F F T 显示
T T F 显示
F T T 不显示
T或F F F 不显示
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
T表示真值,F表示假值
把控件的ShowHint属性设置成真值,系统自动将ParentShowHint设置成假值。应用程序部件的ShowHint属性可以决定整个程序的帮助提示是否有效。如果应用程序的ShowHint 属性为真,程序中各部件的帮助提示才有效, 但是否显示还要取决于部件的SHowHint, ParentShowHint及其父件的ShowHint属性,如果应用程序的ShowHint属性为假值,无论程序部件的属性如何设置,程序中所有帮助提示都无效。
Hint属性是显示在帮助提示框中的文本字符。Hint属性应用于所有控件,包括应用程序部件菜单部件。因为应用程序部件不是可视部件,因此不能在Object Inspector 窗口中定义Hint属性。但可以在定义部件的Hint属性时同时定义应用程序部件的Hint 属性,定义时只需用“|"字符会分开,例如:
Edit.Hint := 'Name |Enter Name in the edit box'
等价于
Edit.Hint := Name;
Application.Hint := Enter Name in the edit box
应用程序的Hint属性可用在OnHint事件。
如果只定义了一个值,Delphi把这个值同时赋给部件和应用程序部件的Hint属性。 如果应用程序的ShowHint属性为假值,所有的帮助提示将不显示, 但可以利用程序部件的Hint属性显示其它提示,如状态条等。
当某一部件的SHowHint属性为真, 但又没有定义Hint 属性, 如果此时文件定义了Hint属性,则此部件将使用文件的Hint值。
11.3.2 OnHint事件
当用户把鼠标放在某一部件,而该部件的Hint 值不为空值,此时发生OnHint事件。利用OnHint事件可以执行一些特殊的操作。
最常用是利用OnHint事件显示状态条的标题,状态条是用面板来实现的。下面举例说明。
这个例子使用了面板部件,菜单,一个编辑框。菜单可随意设计, 但需记住每个菜单项的Hint 值。 另外, 定义编辑框的Hint 值, 把面板置于窗体底部( 将Align 属性置于dBotton)把面板标题置于左端(将Alignment属性置于taleftJustify)。
OnHint 事件是应用程序部件的事件,而应用程序部件是非可视部件,不能使用Object Inspector窗体定义事件,必须编写自己的OnHint事件。
首先,在TForm1对象中宣称DisplayHint方法,并在单元的implementation部分编写实现代码。在DisplayHint方法中,把应用程序的Hint属性赋给面板的标题。另一个重要问题是必须把DisplayHint方法作为处理OnHint事件的方法。窗体的OnCreate事件的代码解决了这个问题。
下面列出了程序的完整代码。当用户运行程序, 把鼠标置于菜单或部件之上,在窗体的状态条中将出现定义的提示。
Type
TForm1 = class(TForm)
Button1: TButton;
Panel1: TPanel;
Edit1: TEdit;
procedure FormCreate(Sender: TObject);
private
{ Private declarations }
public
procedure DisplayHint(Sender: TObject);
end;
var
Form1: TForm1;
implementation
{$R *.FRM}
procedure TForm1.DisplayHint(Sender: TObject);
begin
Panel1.Caption := Application.Hint;
end;
procedure TForm1.FormCreate(Sender: TObject);
begin
Application.OnHint := DisplayHint;
end;
11.4 自定义部件的帮助安装
Delphi有一个功能强大的帮助搜询引擎,叫做多层帮助,能为自定义的部件提供“上下文敏感”帮助。多层帮助允许把自定义部件的多个帮助文件安装成Delphi 的帮助序列,以提供给用户一种内层访问帮助文件的方式,用户有三种方法访问帮助文件:
1. 设计状态选中部件,然后按F1;
2. 在自定义部件的Object Inspector窗口中按F1;
3. 在Delphi帮助系统选择搜询主题。
Delphi 在提供这种帮助机制时, 不需要编写额外的代码。 有些文件是自定义部件帮助系统所必须的, 以下介绍安装的具体步骤。
安装所需的文件
STEREO.PAS 自定义部件的源代码
STEREO.RES 自定义部件的资源文件
STEREO.DCR 工具调色板图标0
STEREO.HRJ 帮助工程文件
STEREO.RTF 帮助源文件
STEREO.HLP 自定义部件的帮助文件
STEREO.KUF 关键字文件
安装步骤
11.4.1 安装关键字文件
1. 退出Delphi集成开发环境
2. 备份\delphi\bin\delphi.hdx
3. 运行HelpInst应用程序
4. 打开\delphi\bin\delphi.hdx
5. 选择keywords |Add菜单项并选择Sberee.buf
6. 选择File|Source菜单项
7. 退出HelpInst
8. 因为WinHelp需要知道STEREO.HLP的位置所以要做以下其中之一:
a. 把STEREO.Hlp复制到\delphi:\bin\目录下;
b. 在WinHELP.INI文件中加上stereo.hlp=\usehelp;
11.4.2 安装自定义部件
1. 进入Delphi集成开发环境
2. 选择Option|Install Components菜单项
3. 选择Add
4. 选择Browse
5. 输入\stereo
6. 选择OK
11.4.3 激活自定义部件帮助系统
1. TstereoButton和TStereeSpeaker部件从部件调色板上的Sample页拖至窗口;
2. 选择TStereoButton部件并按F1,屏幕上出现关于TStereoButton的帮助信息;
3. 在Object Inspector窗体口选择IsOn属性并按F1,屏幕显示IsOn属性;
4. 在主菜单中选择Help|Topic菜单项,并搜询Stereo 主题, 屏幕将出现STEREO
.HLP的帮助内容。