Home | All Classes | Main Classes | Annotated | Grouped Classes | Functions

[Prev: Full Text Searching] [Home]

Customizing Qt Assistant

Qt Assistant can be customized by adding and removing documentation from its documentation set. In addition, Qt Assistant introduces the profiles option, which enables its properties to change, for example, the default startup page, and application icon.

Modifying the Default Documentation Set

When it is started without any options, Qt Assistant displays a default set of documentation. When Qt is installed, the default documentation set in Qt Assistant contains the Qt reference documentation as well as the tools that come with Qt, such as Qt Designer and qmake.

Documentation can be added or removed from Qt Assistant by adding and removing the content files. The format of the content files are specified below. To add a content file, type the following command line option: -addContentFile docfile. To remove a content file from the default set, type the following command line option: -removeContentFile docfile. For example:

1: > assistant -addContentFile file.dcf
2: > assistant
3: > assistant -removeContentFile file.dcf

In line one, we add the content file file.dcf. In line two, we start Qt Assistant. The default set will now be extended with the doc file file.dcf. In line three we remove the file file.dcf from the default documentation set so that subsequent use of Qt Assistant will not contain this file.

Documentation Content File Format

The Documentation Content File must contain the documentation's table of contents and all important keywords for the index. In addition, it may inherit an icon for the documentation which is displayed in the Qt Assistant toolbar. You can also specify an extra directory path for additional images used in the documentation.

An example of a content file that uses all the available tags and attributes is shown below:

<assistantconfig version="3.2.0">
    <DCF ref="demo.html" icon="handbook.png" imagedir="../img/"
         title="Development Demo Handbook">
        <section ref="./chap1/chap1.html" title="Chapter1">
            <section ref="./chap1/section1.html" title="Section1">
                <keyword ref="./chap1/section1.html#foo">foo</keyword>
                <keyword ref="./chap1/section1.html#bla">bla</keyword>
                <section ref="./chap1/section1.html#subsection1" title="Subsection 1"/>
                <section ref="./chap1/section1.html#subsection2" title="Subsection 2"/>
                <section ref="./chap1/section1.html#subsection3" title="Subsection 3"/>
            </section>
            <section ref="./chap1/section2" title="Section2">
                <section ref="./chap1/section2.html#subsection1" title="Subsection 1"/>
                <section ref="./chap1/section2.html#subsection2" title="Subsection 2"/>
                <section ref="./chap1/section2.html#subsection3" title="Subsection 3"/>
            </section>
        </section>
        <section ref="./chap2/chap2.html" title="Chapter2">
            <keyword ref="./chap2/chap2.html#foo">foo</keyword>
            <section ref="./chap2/section1.html" title="Section1"/>
        </section>
    </DCF>
</assistantconfig>

Sections may be nested as deeply as necessary. All references should be related.

Note that any keyword tags for a given section must appear before any sections nested within the given section.

The paths in the refs attribute are always written Unix-style (forward slashes) and are relative to the location of the documentation content file itself.

Since the introduction of the new root tag assistantconfig in the fileformat from Qt version 3.2.0, it is possible to specify multiple DCF tags in one file. Note that the old document contents file format, used up to Qt 3.2 is still valid.

Profiles

Profiles enable Qt Assistant to act as a specialized help tool for displaying documentation for applications. With profiles, the documentation writer can change properties such as Qt Assistant's title, application icons, and 'about' dialogs. In addition, profiles can be used to run specialized documentation sets that are separate from the Qt docs. Qt Assistant can be customized by changing the following properties:

To define a profile, one needs to specify a Qt Assistant Document Profile, usually abbreviated .adp. The profile is an extension of the Documentation Content File described above. We add a profile tag containing property tags to the format.

An example of a document profile file is shown below:

helpdemo.adp

<assistantconfig version="3.2.0">

    <profile>
        <property name="name">HelpExample</property>
        <property name="title">Help Example</property>
        <property name="applicationicon">logo.png</property>
        <property name="startpage">index.html</property>
        <property name="aboutmenutext">About Help</property>
        <property name="abouturl">../about.txt</property>
        <property name="assistantdocs">../../../doc/html</property>
    </profile>

    <DCF ref="index.html" icon="handbook.png" title="Help example">
        <section ref="./manual.html" title="How to use this Example">
            <keyword ref="./manual.html#installdocs">Install Docs</keyword>
            <keyword ref="./manual.html#onlydoc">Example Profile</keyword>
            <keyword ref="./manual.html#hide">Hide Sidebar</keyword>
            <keyword ref="./manual.html#openqabutton">Open</keyword>
            <keyword ref="./manual.html#closeqabutton">Close</keyword>
            <keyword ref="./manual.html#display">Display</keyword>
        </section>
   </DCF>

</assistantconfig>

These files are XML files. Characters such as <, >, and & must be written as entities (e.g., &lt;, &gt;, &amp;).

Using Profiles

To use a profile, run Qt Assistant with the option -profile filename. This will load the profile specified in the file and will customize Qt Assistant accordingly. For example, to run Qt Assistant with the example file above, helpdemo.adp, we would run the command as follows:

 
> assistant -profile helpdemo.adp

See the HelpDemo example in the Qt distribution for a demonstration on how to use Qt Assistant with profiles for your own applications.

When distributing Qt Assistant with your application, you will also need to copy the icon files from the QTDIR/tools/assistant/images directory so that Qt Assistant finds its icons.


Copyright © 2007 TrolltechTrademarks
Qt 3.3.8