1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/tools/assistant/book/assistant.leaf:369 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Customizing TQt Assistant</title>
<style type="text/css"><!--
fn { margin-left: 1cm; text-indent: -1cm; }
a:link { color: #004faf; text-decoration: none }
a:visited { color: #672967; text-decoration: none }
body { background: #ffffff; color: black; }
--></style>
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr bgcolor="#E5E5E5">
<td valign=center>
<a href="index.html">
<font color="#004faf">Home</font></a>
| <a href="classes.html">
<font color="#004faf">All Classes</font></a>
| <a href="mainclasses.html">
<font color="#004faf">Main Classes</font></a>
| <a href="annotated.html">
<font color="#004faf">Annotated</font></a>
| <a href="groups.html">
<font color="#004faf">Grouped Classes</font></a>
| <a href="functions.html">
<font color="#004faf">Functions</font></a>
</td>
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><p align="right">[<a href="assistant-5.html">Prev: Full Text Searching</a>] [<a href="assistant.html">Home</a>]</p>
<h2 align="center">Customizing TQt Assistant</h2>
<p><em>TQt Assistant</em> can be customized by adding and removing documentation from its documentation set. In addition, <em>TQt Assistant</em> introduces the profiles option, which enables its properties to change, for example, the default startup page, and application icon.</p>
<h3><a name="1"></a>Modifying the Default Documentation Set</h3>
<p>When it is started without any options, <em>TQt Assistant</em> displays a default set of documentation. When TQt is installed, the default documentation set in <em>TQt Assistant</em> contains the TQt reference documentation as well as the tools that come with TQt, such as <em>TQt Designer</em> and qmake.</p>
<p>Documentation can be added or removed from <em>TQt Assistant</em> 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: <tt>-addContentFile docfile</tt>. To remove a content file from the default set, type the following command line option: <tt>-removeContentFile docfile</tt>. For example:</p>
<pre>
1: > assistant -addContentFile file.dcf
2: > assistant
3: > assistant -removeContentFile file.dcf
</pre>
<p>In line one, we add the content file <tt>file.dcf</tt>. In line two, we start <em>TQt Assistant</em>. The default set will now be extended with the doc file <tt>file.dcf</tt>. In line three we remove the file <tt>file.dcf</tt> from the default documentation set so that subsequent use of <em>TQt Assistant</em> will not contain this file.</p>
<h4><a name="1-1"></a>Documentation Content File Format</h4>
<p>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 <em>TQt Assistant</em> toolbar. You can also specify an extra directory path for additional images used in the documentation.</p>
<p>An example of a content file that uses all the available tags and attributes is shown below:</p>
<pre>
<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>
</pre>
<p>Sections may be nested as deeply as necessary. All references should be related.</p>
<p>Note that any <tt>keyword</tt> tags for a given section must appear <em>before</em> any sections nested within the given section.</p>
<p>The paths in the <tt>refs</tt> attribute are always written Unix-style (forward slashes) and are relative to the location of the documentation content file itself.</p>
<p>Since the introduction of the new root tag <tt>assistantconfig</tt> in the fileformat from TQt 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 TQt 3.2 is still valid.</p>
<h3><a name="2"></a>Profiles</h3>
<p>Profiles enable <em>TQt Assistant</em> to act as a specialized help tool for displaying documentation for applications. With profiles, the documentation writer can change properties such as <em>TQt Assistant</em>'s title, application icons, and 'about' dialogs. In addition, profiles can be used to run specialized documentation sets that are separate from the TQt docs. <em>TQt Assistant</em> can be customized by changing the following properties:</p>
<ul><li><p>Name- This property is used to name the profile. If multiple profiles are used for the same installation of <em>TQt Assistant</em>, this parameter is crucial to keep their profile specific settings apart. The property name is <tt>name</tt></p>
<li><p>Title- This property is used to specify a caption for <em>TQt Assistant</em>. The property name is <tt>title</tt></p>
<li><p>Application Icon- This property describes an icon that will be used as <em>TQt Assistant</em> application icon. The location of the icon is relative to the location of the profile. The property name is <tt>applicationicon</tt></p>
<li><p>Start Page- This property specifies which page <em>TQt Assistant</em> should initially display when the profile is used. Usually, this is the HTML file which contains the documentation's table of contents. This property also describes the default location to go to when pressing the home button in <em>TQt Assistant</em>'s main user interface. The start page is specified relative to the location of the profile. The property name is <tt>startpage</tt></p>
<li><p>About Menu Text- This property describes the text that appears in the <b>Help</b> menu, e.g. About Application. The property name is <tt>aboutmenutext</tt></p>
<li><p>About URL- This property can be used to point to an HTML file that describes the contents in the About dialog that is opened for the <b>Help</b> menu, e.g. About Application. The url is specified relative to the location of the profile. The property name is <tt>abouturl</tt></p>
<li><p><em>TQt Assistant</em> Documentation- This property describes the location of the <em>TQt Assistant</em> documentation. This is required since <em>TQt Assistant</em> provides self help, such as the full text search help and the <em>TQt Assistant</em> Manual option in the <b>Help</b> menu. The location is a directory relative to the location of the profile. The property name is <tt>assistantdocs</tt>.</p>
</ul><p>To define a profile, one needs to specify a <em>TQt Assistant</em> Document Profile, usually abbreviated <tt>.adp</tt>. The profile is an extension of the Documentation Content File described above. We add a <tt>profile</tt> tag containing <tt>property</tt> tags to the format.</p>
<p>An example of a document profile file is shown below:</p>
<p><tt>helpdemo.adp</tt></p>
<pre>
<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>
</pre>
<p>These files are XML files. Characters such as <tt><</tt>, <tt>></tt>, and <tt>&</tt> must be written as entities (e.g., <tt>&lt;</tt>, <tt>&gt;</tt>, <tt>&amp;</tt>).</p>
<h4><a name="2-1"></a>Using Profiles</h4>
<p>To use a profile, run <em>TQt Assistant</em> with the option <tt>-profile filename</tt>. This will load the profile specified in the file and will customize <em>TQt Assistant</em> accordingly. For example, to run <em>TQt Assistant</em> with the example file above, <tt>helpdemo.adp</tt>, we would run the command as follows:</p>
<pre>
> assistant -profile helpdemo.adp
</pre>
<p>See the HelpDemo example in the TQt distribution for a demonstration on how to use <em>TQt Assistant</em> with profiles for your own applications.</p>
<p>When distributing <em>TQt Assistant</em> with your application, you will also need to copy the icon files from the <tt>QTDIR/tools/assistant/images</tt> directory so that <em>TQt Assistant</em> finds its icons.</p>
<!-- eof -->
<p><address><hr><div align=center>
<table width=100% cellspacing=0 border=0><tr>
<td>Copyright © 2007
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
<td align=right><div align=right>TQt 3.3.8</div>
</table></div></address></body>
</html>
|
