<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qthelp.qdoc -->
<title>Qt 4.8: The Qt Help Framework</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>The Qt Help Framework</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#topics">Topics</a></li>
<li class="level1"><a href="#overview">Overview</a></li>
<li class="level1"><a href="#generating-qt-help">Generating Qt Help</a></li>
<li class="level2"><a href="#creating-a-qt-help-collection">Creating a Qt Help Collection</a></li>
<li class="level1"><a href="#using-qt-help">Using Qt Help</a></li>
<li class="level2"><a href="#using-qt-assistant">Using Qt Assistant</a></li>
<li class="level2"><a href="#using-qhelpengine-api">Using QHelpEngine API</a></li>
</ul>
</div>
<h1 class="title">The Qt Help Framework</h1>
<span class="subtitle"></span>
<!-- $$$qthelp-framework.html-description -->
<div class="descr"> <a name="details"></a>
<a name="topics"></a>
<h2>Topics</h2>
<a name="overview"></a>
<h2>Overview</h2>
<p>The Qt help system includes tools for generating and viewing Qt help files. In addition it provides classes for accessing help contents programatically to be able to integrate online help into Qt applications.</p>
<p>The actual help data, meaning the table of contents, index keywords or HTML documents, is contained in Qt compressed help files. So, one such a help file represents usually one manual or documentation set. Since most products are more comprehensive and consist of a number of tools, one manual is rarely enough. Instead, more manuals which should be accessible at the same time, exist. Ideally, it should also be possible to reference certain points of interest of one manual to another. Therefore, the Qt help system operates on help collection files which include any number of compressed help files.</p>
<p>However, having collection files to merge many documentation sets may lead to some problems. For example, one index keyword may be defined in different documentations. So, when only seeing it in the index and activating it, you cannot be sure that the expected documentation will be shown. Therefore, the Qt help system offers the possibiltiy to filter the help contents after certain attributes. This requires however, that the attributes have been assigned to the help contents before the generation of the compressed help file.</p>
<p>As already mentioned, the Qt compressed help file contains all data, so there is no need any longer to ship all single HTML files. Instead, only the compressed help file and optionally the collection file has to be distributed. The collection file is optional since any existing collection file, e.g. from an older release could be used.</p>
<p>So, in general, there are four files interacting with the help system, two used for generating Qt help and two meant for distribution:</p>
<table class="generic">
<thead><tr class="qt-style"><th >Name</th><th >Extension</th><th >Brief Description</th></tr></thead>
<tr valign="top" class="odd"><td ><a href="qthelpproject.html">Qt Help Project</a></td><td >.qhp</td><td >The input file for the help generator consisting of the table of contents, indices and references to the actual documentation files (*.html); it also defines a unique namespace for the documentation.</td></tr>
<tr valign="top" class="even"><td >Qt Compressed Help</td><td >.qch</td><td >The output file of the help generator. This binary file contains all information specified in the help project file along with all compressed documentation files.</td></tr>
<tr valign="top" class="odd"><td ><a href="#qt-help-collection-project">Qt Help Collection Project</a></td><td >.qhcp</td><td >The input file for the help collection generator. It contains references to compressed help files which should be included in the collection; it also may contain other information for customizing Qt Assistant.</td></tr>
<tr valign="top" class="even"><td >Qt Help Collection</td><td >.qhc</td><td >The output of the help collection generator. This is the file <a href="qhelpengine.html">QHelpEngine</a> operates on. It contains references to any number of compressed help files as well as additional information, such as custom filters.</td></tr>
</table>
<a name="generating-qt-help"></a>
<h2>Generating Qt Help</h2>
<p>Building help files for the Qt help system assumes that the HTML documentation files already exist.</p>
<p>Once the HTML documents are in place, a <a href="qthelpproject.html">Qt Help Project</a> file, with an extension of <tt>.qhp</tt> has to be created. After specifying all relevant information in this file, it needs to be compiled by calling:</p>
<pre class="cpp"> qhelpgenerator doc.qhp -o doc.qch</pre>
<p>The file 'doc.qch' contains then all HTML files in compressed form along with the table of contents and index keywords. To test if the generated file is correct, open Qt Assistant and install the file via the Settings|Documentation page.</p>
<p>For the standard Qt source build, the .qhp file is generated and placed in the same directory as the HTML pages.</p>
<a name="qt-help-collection-project"></a><a name="creating-a-qt-help-collection"></a>
<h3>Creating a Qt Help Collection</h3>
<p>The first step is to create a Qt Help Collection Project file. Since a Qt help collection stores primarily references to compressed help files, the project 'mycollection.qhcp' file looks unsurprisingly simple:</p>
<pre class="cpp"> <?xml version="1.0" encoding="utf-8" ?>
<QHelpCollectionProject version="1.0">
<docFiles>
<register>
<file>doc.qch</file>
</register>
</docFiles>
</QHelpCollectionProject></pre>
<p>For actually creating the collection file call:</p>
<pre class="cpp"> qcollectiongenerator mycollection.qhcp -o mycollection.qhc</pre>
<p>Instead of running two tools, one for generating the compressed help and one for generating the collection file, it is also possible to just run the qcollectiongenerator tool with a slightly modified project file instructing the generator to create the compressed help first.</p>
<pre class="cpp"> ...
<docFiles>
<generate>
<file>
<input>doc.qhp</input>
<output>doc.qch</output>
</file>
</generate>
<register>
<file>doc.qch</file>
</register>
</docFiles>
...</pre>
<p>Of course, it is possible to specify more than one file in the 'generate' or 'register' section, so any number of compressed help files can be generated and registered in one go.</p>
<a name="using-qt-help"></a>
<h2>Using Qt Help</h2>
<p>Accessing the help contents can be done in two ways: Using Qt Assistant as documentation browser or using the <a href="qhelpengine.html">QHelpEngine</a> API for embedding the help contents directly in an application.</p>
<a name="using-qt-assistant"></a>
<h3>Using Qt Assistant</h3>
<p><i>Qt Assistant</i> operates on a collection file which can be specified before start up. If no collection file is given, a default one will be created and used. In either case, it is possible to register any Qt compressed help file and access the help contents.</p>
<p>When using Assistant as the help browser for an application, it would be desirable that it can be customized to fit better to the application and doesn't look like an independent, standalone help browser. To achieve this, several additional properties can be set in an Qt help collection file, to change e.g. the title or application icon of Qt Assistant. For more information on this topic have a look at the <a href="assistant-manual.html">Qt Assistant manual</a>.</p>
<a name="using-qhelpengine-api"></a>
<h3>Using QHelpEngine API</h3>
<p>Instead of showing the help in an external application like the Qt Assistant, it is also possible to embed the online help in the application. The contents can then be retrieved via the <a href="qhelpengine.html">QHelpEngine</a> class and can be displayed in nearly any form. Showing it in a <a href="qtextbrowser.html">QTextBrowser</a> is probably the most common way, but embedding it in What's This help is also perfectly possible.</p>
<p>Retrieving help data from the file engine does not involve a lot of code. The first step is to create an instance of the help engine. Then we ask the engine for the links assigned to the identifier, in this case "MyDialog::ChangeButton". If a link was found, meaning at least one help document exists to this topic, we get the actual help contents by calling fileData() and display the document to the user.</p>
<pre class="cpp"> <span class="type"><a href="qhelpenginecore.html">QHelpEngineCore</a></span> helpEngine(<span class="string">"mycollection.qhc"</span>);
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="comment">// get all file references for the identifier</span>
<span class="type"><a href="qmap.html">QMap</a></span><span class="operator"><</span><span class="type"><a href="qstring.html">QString</a></span><span class="operator">,</span> <span class="type"><a href="qurl.html">QUrl</a></span><span class="operator">></span> links <span class="operator">=</span>
helpEngine<span class="operator">.</span>linksForIdentifier(QLatin1String(<span class="string">"MyDialog::ChangeButton"</span>));
<span class="comment">// If help is available for this keyword, get the help data</span>
<span class="comment">// of the first file reference.</span>
<span class="keyword">if</span> (links<span class="operator">.</span>count()) {
<span class="type"><a href="qbytearray.html">QByteArray</a></span> helpData <span class="operator">=</span> helpEngine<span class="operator">-</span><span class="operator">></span>fileData(links<span class="operator">.</span>constBegin()<span class="operator">.</span>value());
<span class="comment">// show the documentation to the user</span>
<span class="keyword">if</span> (<span class="operator">!</span>helpData<span class="operator">.</span>isEmpty())
displayHelp(helpData);
}</pre>
<p>For further information on how to use the API, have a look at the <a href="qhelpengine.html">QHelpEngine</a> class reference.</p>
</div>
<!-- @@@qthelp-framework.html -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Qt and respective logos are trademarks of The Qt Company Ltd
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
