Qt帮助系统

Qt帮助系统

sf2gis@163.com

2015年1月30日

 

目标：在部件上显示简要的帮助信息文件。

原理：Qt的Widget包含一个属性whatsThis，可以显示指定的内容。

方法：

1.1 设置帮助信息

1)   编程指定帮助信息：setWhatsThis()。

2)   设计时指定帮助信息：在部件上右击-》改变 这是什么-》添加指定信息。

1.2 显示帮助信息

1)   shift+F1:部件获取焦点，shift+F1显示。

2)   帮助按钮显示帮助信息：

在菜单和工具栏上添加显示简要帮助按钮：QWhatsThis

    QAction*pAction = QWhatsThis::createAction (this);

   ui->mainToolBar->addAction(pAction);

   ui->menuBar->addAction(pAction);

点击后鼠标显示帮助图标：

点击部件显示帮助

1.3 QWhatsThis

目标：控制简要信息。

方法：全部使用静态方法。

生成QAction，用于显示帮助按钮:

    QAction*pAction = QWhatsThis::createAction (this);

目标：程序中直接调用的帮助程序。帮助类似chm，可以显示文档结构、搜索、索引、书签等。

原理：

帮助功能：使用QAssistant程序，向其传递一个xml的关于帮助中所有属性的设置文档作为参数，来初始化程序的功能和外观。

帮助内容：使用qch文件来定义，也是一个xml，其中包含所有要显示的内容及对内容的相关使用参数设置。

方法：

2.1 设置帮助内容:QtHelp Project

原理：Qt的帮助内容通过QtHelpProject设置帮助程序中的内容（toc）和索引（keywords）。通过后缀为qhp的xml文件指定。

方法：

1)   生成帮助源数据：默认支持html文件，其它类型文件将调用外部程序打开。建议使用word文档编辑（里面可以加入任意类型的文件），然后生成html文件。

2)   生成帮助组织文件qhp：先copy帮助QtHelp中Qt Help Project示例文件，再进行编辑。

3)   生成二进制帮助文件qch：qt compressed help，二进制形式，所有帮助文件的压缩格式。使用qhelpgenerator生成。发布程序时可以使用此种类型文件。

格式：qhelpgeneratorqhp文件 –o qch文件

qhelpgeneratorhelp.qhp -o help.qch

4)   注册帮助文件：可以在qassistant程序中查看到帮助文件，否则无法查看。

格式：assistant–register qch文件

可以使用-unregister取消注册。或在assistant程序-》编辑-》首先项-》文档中查看。

assistant-register help.qch

5)   查看帮助文件：打开assistant程序。

2.1.1QtHelpPrject：帮助工程

目标：帮助内容组织文件。

原理：QtHelpPrject通过Url来定位每一个帮助文件。为每一个文件生成一个唯一url。通过xml结构指定帮助的内容。

方法：

url协议头：qthelp。

url根目录：namespace标签指定url的根目录。

url虚拟子目录：可以设置多个虚拟子目录，标签virturalforlder。

qthelp://geprocess_mapframe_v0.0.1.0/geprocess/QT帮助系统.html

过滤器：指定只显示指定的section，标签customFilter。在其中添加要显示的filterattribute。

帮助内容toc：指定要显示的toc，标签filtersection。

设置过滤属性：filterAttribute，其中的toc表示所有要显示的内容section。section可以表示帮助的组织结构和实际文件。

设置每一个section的page属性：在每个帮助文件html中指定title标签。

示例：

<?xml version="1.0" encoding="GB2312"?>

 <QtHelpProjectversion="1.0">

    <namespace>geprocess_mapframe_v0.0.1.0</namespace>

    <virtualFolder>geprocess</virtualFolder>

     <customFiltername="My Application 1.0">

        <filterAttribute>myapp</filterAttribute>

        <filterAttribute>1.0</filterAttribute>

     </customFilter>

     <filterSection>

        <filterAttribute>myapp</filterAttribute>

         <filterAttribute>1.0</filterAttribute>

         <toc>

             <sectiontitle="My Application Manual" ref="QT帮助系统.html">

                 <sectiontitle="Chapter 1" ref="QT帮助系统.html#1.1"/>

                 <sectiontitle="Chapter 2" ref="QT帮助系统.html#1.2"/>

                 <sectiontitle="Chapter 3" ref="QT帮助系统.html#1.3"/>

             </section>

             <sectiontitle="my jpg" ref="h.jpg">

             </section>

             <sectiontitle="my points" ref="213.txt">

             </section>

             <sectiontitle="project" ref="lamb.docx">

             </section>

         </toc>

         <keywords>

             <keywordname="jpg" id="MyApplication::foo"ref="h.jpg"/>

             <keywordname="proj" ref="lamb.docx"/>

             <keywordid="MyApplication::foobar" ref="213.txt"/>

         </keywords>

         <files>

            <file>*.html</file>

            <file>*.jpg</file>

            <file>*.txt</file>

            <file>*.docx</file>

         </files>

     </filterSection>

 </QtHelpProject>

2.2 设置帮助程序功能

目标：订制QtAssistant程序的功能，设置显示内容、功能、相关信息。

原理：Qt Assistant接受qhcp后缀的参数文件，用于订制其相关功能。

方法：

2.2.1生成参数文件qhcp

设置assistant的功能参数和内容参数的xml文本文件，后缀qhcp。

参见：QtHelpCollectionPrject：帮助工程集合

2.2.2生成二进制参数文件qhc

使用qcollectiongenerator 生成qhc文件。

格式：qcollectiongenerator qhcp文件 –o qhc文件

qcollectiongenerator myhelp.qhcp -o myhelp.qhc

2.2.3应用参数启动assistant

assistant的-collectionfile参数接受qhc文件。

格式 assistant –collectionfile qhc文件

assistant -collectionfile myhelp.qhc

2.2.4QtHelpCollectionPrject：帮助工程集合

目标：组织所有的帮助工程。订制Assistant程序功能和外观。

原理：使用xml设置参数。

方法：

qhcp的格式参考：QtHelp-Using QtAssistant as a Custom Help Viewer。

注意：其中的标签都是区分大小写的。

建议copy示例文件，然后修改。

1)   设置QtAssistant参数：

程序标题：标签title。

首页：home按钮地址，标签homePage。

起始页：程序启动时页面，标签startPage。

当前过滤器：标签currentFilter。

程序图标：标签applicationIcon。

允许编辑过滤器：标签enableFilterFunctionality。

允许编辑文档：标签enableDocumentManager。

显示地址栏：标签enableAddressBar。

缓存目录：生成临时文件，qhc等。标签cacheDirectory。

关于菜单：标签aboutMenu。可以设置多语言。

关于对话框：标签aboutDialog。可以设置icon和显示文件，但是显示文件不支持汉语？？

2)   设置QtAssistant内容

设置qhp为内容的文件：标签generate,其中添加file,file包括输入输出两个文件。生成的临时文件在cache目录中。如果使用qhc文件，则可以不用设置此项。

设置注册文件：标签register。项目file标签用于注册的qhc文件。

示例：

<?xmlversion="1.0" encoding="GB2312"?>

 <QHelpCollectionProjectversion="1.0">

     <assistant>

         <title>GE Help</title>

        <homePage>qthelp://geprocess_mapframe_v0.0.1.0/geprocess/QT帮助系统.html</homePage>

        <startPage>qthelp://geprocess_mapframe_v0.0.1.0/geprocess/QT帮助系统.html</startPage>

        <currentFilter>myapp</currentFilter>

         <applicationIcon>h.jpg</applicationIcon>

        <enableFilterFunctionality>true</enableFilterFunctionality>

        <enableDocumentationManager>true</enableDocumentationManager>

         <enableAddressBarvisible="true">true</enableAddressBar>

         <cacheDirectorybase="collection">cache/xxx</cacheDirectory>

         <aboutMenuText>

             <text>aboutmenu12xx</text>

             <textlanguage="zh">这是关于文件123xx</text>

         </aboutMenuText>

         <aboutDialog>

             <file>about.txt</file>

             <filelanguage="zh">关于.txt</file>

            <icon>utmzones.jpg</icon>

         </aboutDialog>

     </assistant>

     <docFiles>

         <generate>

             <file>

                <input>help.qhp</input>

                 <output>help.qch</output>

             </file>

         </generate>

         <register>

             <file>help.qch</file>

         </register>

     </docFiles>

 </QHelpCollectionProject>

 

 

2.3 在程序中启动assistant程序

目标：在程序中启动assistant程序，并显示指定的帮助系统文件。

方法：使用QProcess启动assistant进程，并输入帮助系统文件作为参数。

注意：在发布时不要在qhcp文件中生成文件，只使用二进制文件，方便生成。

示例：

#include<QProcess>

voidMainWindow::on_pushButton_4_clicked()

{

    QProcess *pProcess = new QProcess(this);

    QStringList lst;

   lst<<"-collectionFile"<<"myhelp.qhc";

    pProcess->start("assistant",lst);

}