<?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" />
<!-- simpletextviewer.qdoc -->
<title>Qt 4.8: Simple Text Viewer Example</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><a href="all-examples.html">Examples</a></li>
<li>Simple Text Viewer Example</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="#creating-documentation-and-customizing-qt-assistant">Creating Documentation and Customizing <i>Qt Assistant</i></a></li>
<li class="level2"><a href="#organizing-documentation-for-qt-assistant">Organizing Documentation for <i>Qt Assistant</i></a></li>
<li class="level2"><a href="#customizing-qt-assistant">Customizing <i>Qt Assistant</i></a></li>
<li class="level1"><a href="#controlling-qt-assistant-via-the-assistant-class">Controlling <i>Qt Assistant</i> via the Assistant Class</a></li>
<li class="level1"><a href="#mainwindow-class">MainWindow Class</a></li>
<li class="level1"><a href="#findfiledialog-class">FindFileDialog Class</a></li>
<li class="level1"><a href="#summary">Summary</a></li>
</ul>
</div>
<h1 class="title">Simple Text Viewer Example</h1>
<span class="subtitle"></span>
<!-- $$$help/simpletextviewer-description -->
<div class="descr"> <a name="details"></a>
<p>Files:</p>
<ul>
<li><a href="help-simpletextviewer-assistant-cpp.html">help/simpletextviewer/assistant.cpp</a></li>
<li><a href="help-simpletextviewer-assistant-h.html">help/simpletextviewer/assistant.h</a></li>
<li><a href="help-simpletextviewer-findfiledialog-cpp.html">help/simpletextviewer/findfiledialog.cpp</a></li>
<li><a href="help-simpletextviewer-findfiledialog-h.html">help/simpletextviewer/findfiledialog.h</a></li>
<li><a href="help-simpletextviewer-mainwindow-cpp.html">help/simpletextviewer/mainwindow.cpp</a></li>
<li><a href="help-simpletextviewer-mainwindow-h.html">help/simpletextviewer/mainwindow.h</a></li>
<li><a href="help-simpletextviewer-textedit-cpp.html">help/simpletextviewer/textedit.cpp</a></li>
<li><a href="help-simpletextviewer-textedit-h.html">help/simpletextviewer/textedit.h</a></li>
<li><a href="help-simpletextviewer-documentation-simpletextviewer-qhcp.html">help/simpletextviewer/documentation/simpletextviewer.qhcp</a></li>
<li><a href="help-simpletextviewer-documentation-simpletextviewer-qhp.html">help/simpletextviewer/documentation/simpletextviewer.qhp</a></li>
<li><a href="help-simpletextviewer-main-cpp.html">help/simpletextviewer/main.cpp</a></li>
<li><a href="help-simpletextviewer-simpletextviewer-pro.html">help/simpletextviewer/simpletextviewer.pro</a></li>
</ul>
<p>The Simple Text Viewer example shows how to use <i>Qt Assistant</i> as a customized help viewer for your application.<p>This is done in two stages. Firstly, documentation is created and <i>Qt Assistant</i> is customized; secondly, the functionality to launch and control <i>Qt Assistant</i> is added to the application.</p>
<p class="centerAlign"><img src="images/simpletextviewer-example.png" alt="" /></p><p>The Simple Text Viewer application lets the user select and view existing files.</p>
<p>The application provides its own custom documentation that is available from the <b>Help</b> menu in the main window's menu bar or by clicking the <b>Help</b> button in the application's find file dialog.</p>
<p>The example consists of four classes:</p>
<ul>
<li><tt>Assistant</tt> provides functionality to launch <i>Qt Assistant</i>.</li>
<li><tt>MainWindow</tt> is the main application window.</li>
<li><tt>FindFileDialog</tt> allows the user to search for files using wildcard matching.</li>
<li><tt>TextEdit</tt> provides a rich text browser that makes sure that images referenced in HTML documents are displayed properly.</li>
</ul>
<p>Note that we will only comment on the parts of the implementation that are relevant to the main issue, that is making Qt Assistant act as a customized help viewer for our Simple Text Viewer application.</p>
<a name="creating-documentation-and-customizing-qt-assistant"></a>
<h2>Creating Documentation and Customizing <i>Qt Assistant</i></h2>
<p>How to create the actual documentation in the form of HTML pages is not in the scope of this example. In general, HTML pages can either be written by hand or generated with the help of documentation tools like qdoc or Doxygen. For the purposes of this example we assume that the HTML files have already been created. So, the only thing that remains to be done is to tell <i>Qt Assistant</i> how to structure and display the help information.</p>
<a name="organizing-documentation-for-qt-assistant"></a>
<h3>Organizing Documentation for <i>Qt Assistant</i></h3>
<p>Plain HTML files only contain text or documentation about specific topics, but they usually include no information about how several HTML documents relate to each other or in which order they are supposed to be read. What is missing is a table of contents along with an index to access certain help contents quickly, without having to browse through a lot of documents in order to find a piece of information.</p>
<p>To organize the documentation and make it available for <i>Qt Assistant</i>, we have to create a Qt help project (.qhp) file. The first and most important part of the project file is the definition of the namespace. The namespace has to be unique and will be the first part of the page URL in <i>Qt Assistant</i>. In addition, we have to set a virtual folder which acts as a common folder for documentation sets. This means, that two documentation sets identified by two different namespaces can cross reference HTML files since those files are in one big virtual folder. However, for this example, we'll only have one documentation set available, so the virtual folder name and functionality are not important.</p>
<pre class="cpp"> <span class="operator"><</span><span class="operator">?</span>xml version<span class="operator">=</span><span class="string">"1.0"</span> encoding<span class="operator">=</span><span class="string">"UTF-8"</span><span class="operator">?</span><span class="operator">></span>
<span class="operator"><</span><span class="type">QtHelpProject</span> version<span class="operator">=</span><span class="string">"1.0"</span><span class="operator">></span>
<span class="operator"><</span><span class="keyword">namespace</span><span class="operator">></span>com<span class="operator">.</span>trolltech<span class="operator">.</span>examples<span class="operator">.</span>simpletextviewer<span class="operator"><</span><span class="operator">/</span><span class="keyword">namespace</span><span class="operator">></span>
<span class="operator"><</span>virtualFolder<span class="operator">></span>doc<span class="operator"><</span><span class="operator">/</span>virtualFolder<span class="operator">></span></pre>
<p>The next step is to define the filter section. A filter section contains the table of contents, indices and a complete list of all documentation files, and can have any number of filter attributes assigned to it. A filter attribute is an ordinary string which can be freely chosen. Later in <i>Qt Assistant</i>, users can then define a custom filter referencing those attributes. If the attributes of a filter section match the attributes of the custom filter the documentation will be shown, otherwise <i>Qt Assistant</i> will hide the documentation.</p>
<p>Again, since we'll only have one documentation set, we do not need the filtering functionality of <i>Qt Assistant</i> and can therefore skip the filter attributes.</p>
<p>Now, we build up the table of contents. An item in the table is defined by the <tt>section</tt> tag which contains the attributes for the item title as well as link to the actual page. Section tags can be nested infinitely, but for practical reasons it is not recommended to nest them deeper than three or four levels. For our example we want to use the following outline for the table of contents:</p>
<ul>
<li>Simple Text Viewer<ul>
<li>Find File<ul>
<li>File Dialog</li>
<li>Wildcard Matching</li>
<li>Browse</li>
</ul>
</li>
<li>Open File</li>
</ul>
</li>
</ul>
<p>In the help project file, the outline is represented by:</p>
<pre class="cpp"> <span class="operator"><</span>filterSection<span class="operator">></span>
<span class="operator"><</span>toc<span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"Simple Text Viewer"</span> ref<span class="operator">=</span><span class="string">"index.html"</span><span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"Find File"</span> ref<span class="operator">=</span><span class="string">"./findfile.html"</span><span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"File Dialog"</span> ref<span class="operator">=</span><span class="string">"./filedialog.html"</span><span class="operator">></span><span class="operator"><</span><span class="operator">/</span>section<span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"Wildcard Matching"</span> ref<span class="operator">=</span><span class="string">"./wildcardmatching.html"</span><span class="operator">></span><span class="operator"><</span><span class="operator">/</span>section<span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"Browse"</span> ref<span class="operator">=</span><span class="string">"./browse.html"</span><span class="operator">></span><span class="operator"><</span><span class="operator">/</span>section<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>section<span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"Open File"</span> ref<span class="operator">=</span><span class="string">"./openfile.html"</span><span class="operator">></span><span class="operator"><</span><span class="operator">/</span>section<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>section<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>toc<span class="operator">></span></pre>
<p>After the table of contents is defined, we will list all index keywords:</p>
<pre class="cpp"> <span class="operator"><</span>keywords<span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"Display"</span> ref<span class="operator">=</span><span class="string">"./index.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"Rich text"</span> ref<span class="operator">=</span><span class="string">"./index.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"Plain text"</span> ref<span class="operator">=</span><span class="string">"./index.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"Find"</span> ref<span class="operator">=</span><span class="string">"./findfile.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"File menu"</span> ref<span class="operator">=</span><span class="string">"./findfile.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"File name"</span> ref<span class="operator">=</span><span class="string">"./filedialog.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"File dialog"</span> ref<span class="operator">=</span><span class="string">"./filedialog.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"File globbing"</span> ref<span class="operator">=</span><span class="string">"./wildcardmatching.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"Wildcard matching"</span> ref<span class="operator">=</span><span class="string">"./wildcardmatching.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"Wildcard syntax"</span> ref<span class="operator">=</span><span class="string">"./wildcardmatching.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"Browse"</span> ref<span class="operator">=</span><span class="string">"./browse.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"Directory"</span> ref<span class="operator">=</span><span class="string">"./browse.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"Open"</span> ref<span class="operator">=</span><span class="string">"./openfile.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"Select"</span> ref<span class="operator">=</span><span class="string">"./openfile.html"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>keywords<span class="operator">></span></pre>
<p>As the last step, we have to list all files making up the documentation. An important point to note here is that all files have to listed, including image files, and even stylesheets if they are used.</p>
<pre class="cpp"> <span class="operator"><</span>files<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>browse<span class="operator">.</span>html<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>filedialog<span class="operator">.</span>html<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>findfile<span class="operator">.</span>html<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>index<span class="operator">.</span>html<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>intro<span class="operator">.</span>html<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>openfile<span class="operator">.</span>html<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>wildcardmatching<span class="operator">.</span>html<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>images<span class="operator">/</span>browse<span class="operator">.</span>png<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>images<span class="comment">/*.png</file>
</files>
</filterSection>
</QtHelpProject>
</span></pre>
<p>The help project file is now finished. If you want to see the resulting documentation in <i>Qt Assistant</i>, you have to generate a Qt compressed help file out of it and register it with the default help collection of <i>Qt Assistant</i>.</p>
<pre class="cpp"> qhelpgenerator simpletextviewer<span class="operator">.</span>qhp <span class="operator">-</span>o simpletextviewer<span class="operator">.</span>qch
assistant <span class="operator">-</span><span class="keyword">register</span> simpletextviewer<span class="operator">.</span>qch</pre>
<p>If you start <i>Qt Assistant</i> now, you'll see the Simple Text Viewer documentation beside the Qt documentation. This is OK for testing purposes, but for the final version we want to only have the Simple Text Viewer documentation in <i>Qt Assistant</i>.</p>
<a name="customizing-qt-assistant"></a>
<h3>Customizing <i>Qt Assistant</i></h3>
<p>The easiest way to make <i>Qt Assistant</i> only display the Simple Text Viewer documentation is to create our own help collection file. A collection file is stored in a binary format, similar to the compressed help file, and generated from a help collection project file (*.qhcp). With the help of a collection file, we can customize the appearance and even some functionality offered by <i>Qt Assistant</i>.</p>
<p>At first, we change the window title and icon. Instead of showing "<i>Qt Assistant</i>" it will show "Simple Text Viewer", so it is much clearer for the user that the help viewer actually belongs to our application.</p>
<pre class="cpp"> <span class="operator"><</span><span class="operator">?</span>xml version<span class="operator">=</span><span class="string">"1.0"</span> encoding<span class="operator">=</span><span class="string">"UTF-8"</span><span class="operator">?</span><span class="operator">></span>
<span class="operator"><</span><span class="type">QHelpCollectionProject</span> version<span class="operator">=</span><span class="string">"1.0"</span><span class="operator">></span>
<span class="operator"><</span>assistant<span class="operator">></span>
<span class="operator"><</span>title<span class="operator">></span>Simple Text Viewer<span class="operator"><</span><span class="operator">/</span>title<span class="operator">></span>
<span class="operator"><</span>applicationIcon<span class="operator">></span>images<span class="operator">/</span>handbook<span class="operator">.</span>png<span class="operator"><</span><span class="operator">/</span>applicationIcon<span class="operator">></span>
<span class="operator"><</span>cacheDirectory<span class="operator">></span>Trolltech<span class="operator">/</span>SimpleTextViewer<span class="operator"><</span><span class="operator">/</span>cacheDirectory<span class="operator">></span></pre>
<p>The <tt>cacheDirectory</tt> tag specifies a subdirectory of the users data directory (see the <a href="assistant-custom-help-viewer.html#qt-help-collection-files">Qt Help Collection Files</a>) where the cache file for the full text search or the settings file will be stored.</p>
<p>After this, we set the page displayed by <i>Qt Assistant</i> when launched for the very first time in its new configuration. The URL consists of the namespace and virtual folder defined in the Qt help project file, followed by the actual page file name.</p>
<pre class="cpp"> <span class="operator"><</span>startPage<span class="operator">></span>qthelp:<span class="comment">//com.trolltech.examples.simpletextviewer/doc/index.html</startPage></span></pre>
<p>Next, we alter the name of the "About" menu item to "About Simple Text Viewer". The contents of the <b>About</b> dialog are also changed by specifying a file where the about text or icon is taken from.</p>
<pre class="cpp"> <span class="operator"><</span>aboutMenuText<span class="operator">></span>
<span class="operator"><</span>text<span class="operator">></span>About Simple Text Viewer<span class="operator"><</span><span class="operator">/</span>text<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>aboutMenuText<span class="operator">></span>
<span class="operator"><</span>aboutDialog<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>about<span class="operator">.</span>txt<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span>icon<span class="operator">></span>images<span class="operator">/</span>icon<span class="operator">.</span>png<span class="operator"><</span><span class="operator">/</span>icon<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>aboutDialog<span class="operator">></span></pre>
<p><i>Qt Assistant</i> offers the possibility to add or remove documentation via its preferences dialog. This functionality is helpful when using <i>Qt Assistant</i> as the central help viewer for more applications, but in our case we want to actually prevent the user from removing the documentation. So, we disable the documentation manager.</p>
<p>Since the address bar is not really relevant in such a small documentation set we switch it off as well. By having just one filter section, without any filter attributes, we can also disable the filter functionality of <i>Qt Assistant</i>, which means that the filter page and the filter toolbar will not be available.</p>
<pre class="cpp"> <span class="operator"><</span>enableDocumentationManager<span class="operator">></span><span class="keyword">false</span><span class="operator"><</span><span class="operator">/</span>enableDocumentationManager<span class="operator">></span>
<span class="operator"><</span>enableAddressBar<span class="operator">></span><span class="keyword">false</span><span class="operator"><</span><span class="operator">/</span>enableAddressBar<span class="operator">></span>
<span class="operator"><</span>enableFilterFunctionality<span class="operator">></span><span class="keyword">false</span><span class="operator"><</span><span class="operator">/</span>enableFilterFunctionality<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>assistant<span class="operator">></span></pre>
<p>For testing purposes, we already generated the compressed help file and registered it with <i>Qt Assistant</i>'s default help collection. With the following lines we achieve the same result. The only and important difference is that we register the compressed help file, not in the default collection, but in our own collection file.</p>
<pre class="cpp"> <span class="operator"><</span>docFiles<span class="operator">></span>
<span class="operator"><</span>generate<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>
<span class="operator"><</span>input<span class="operator">></span>simpletextviewer<span class="operator">.</span>qhp<span class="operator"><</span><span class="operator">/</span>input<span class="operator">></span>
<span class="operator"><</span>output<span class="operator">></span>simpletextviewer<span class="operator">.</span>qch<span class="operator"><</span><span class="operator">/</span>output<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>generate<span class="operator">></span>
<span class="operator"><</span><span class="keyword">register</span><span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>simpletextviewer<span class="operator">.</span>qch<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span><span class="keyword">register</span><span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>docFiles<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span><span class="type">QHelpCollectionProject</span><span class="operator">></span></pre>
<p>As the last step, we have to generate the binary collection file out of the help collection project file. This is done by running the <tt>qcollectiongenerator</tt> tool.</p>
<pre class="cpp"> qcollectiongenerator simpletextviewer<span class="operator">.</span>qhcp <span class="operator">-</span>o simpletextviewer<span class="operator">.</span>qhc</pre>
<p>To test all our customizations made to <i>Qt Assistant</i>, we add the collection file name to the command line:</p>
<pre class="cpp"> assistant <span class="operator">-</span>collectionFile simpletextviewer<span class="operator">.</span>qhc</pre>
<a name="controlling-qt-assistant-via-the-assistant-class"></a>
<h2>Controlling <i>Qt Assistant</i> via the Assistant Class</h2>
<p>We will first take a look at how to start and operate <i>Qt Assistant</i> from a remote application. For that purpose, we create a class called <tt>Assistant</tt>.</p>
<p>This class provides a public function that is used to show pages of the documentation, and one private helper function to make sure that <i>Qt Assistant</i> is up and running.</p>
<p>Launching <i>Qt Assistant</i> is done in the function <tt>startAssistant()</tt> by simply creating and starting a <a href="qprocess.html">QProcess</a>. If the process is already running, the function returns immediately. Otherwise, the process has to be set up and started.</p>
<pre class="cpp"> <span class="type">bool</span> Assistant<span class="operator">::</span>startAssistant()
{
<span class="keyword">if</span> (<span class="operator">!</span>proc)
proc <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qprocess.html">QProcess</a></span>();
<span class="keyword">if</span> (proc<span class="operator">-</span><span class="operator">></span>state() <span class="operator">!</span><span class="operator">=</span> <span class="type"><a href="qprocess.html">QProcess</a></span><span class="operator">::</span>Running) {
<span class="type"><a href="qstring.html">QString</a></span> app <span class="operator">=</span> <span class="type"><a href="qlibraryinfo.html">QLibraryInfo</a></span><span class="operator">::</span>location(<span class="type"><a href="qlibraryinfo.html">QLibraryInfo</a></span><span class="operator">::</span>BinariesPath) <span class="operator">+</span> <span class="type"><a href="qdir.html">QDir</a></span><span class="operator">::</span>separator();
<span class="preprocessor">#if !defined(Q_OS_MAC)</span>
app <span class="operator">+</span><span class="operator">=</span> QLatin1String(<span class="string">"assistant"</span>);
<span class="preprocessor">#else</span>
app <span class="operator">+</span><span class="operator">=</span> QLatin1String(<span class="string">"Assistant.app/Contents/MacOS/Assistant"</span>);
<span class="preprocessor">#endif</span>
<span class="type"><a href="qstringlist.html">QStringList</a></span> args;
args <span class="operator"><</span><span class="operator"><</span> QLatin1String(<span class="string">"-collectionFile"</span>)
<span class="operator"><</span><span class="operator"><</span> <span class="type"><a href="qlibraryinfo.html">QLibraryInfo</a></span><span class="operator">::</span>location(<span class="type"><a href="qlibraryinfo.html">QLibraryInfo</a></span><span class="operator">::</span>ExamplesPath)
<span class="operator">+</span> QLatin1String(<span class="string">"/help/simpletextviewer/documentation/simpletextviewer.qhc"</span>)
<span class="operator"><</span><span class="operator"><</span> QLatin1String(<span class="string">"-enableRemoteControl"</span>);
proc<span class="operator">-</span><span class="operator">></span>start(app<span class="operator">,</span> args);
<span class="keyword">if</span> (<span class="operator">!</span>proc<span class="operator">-</span><span class="operator">></span>waitForStarted()) {
<span class="type"><a href="qmessagebox.html">QMessageBox</a></span><span class="operator">::</span>critical(<span class="number">0</span><span class="operator">,</span> <span class="type"><a href="qobject.html">QObject</a></span><span class="operator">::</span>tr(<span class="string">"Simple Text Viewer"</span>)<span class="operator">,</span>
<span class="type"><a href="qobject.html">QObject</a></span><span class="operator">::</span>tr(<span class="string">"Unable to launch Qt Assistant (%1)"</span>)<span class="operator">.</span>arg(app));
<span class="keyword">return</span> <span class="keyword">false</span>;
}
}
<span class="keyword">return</span> <span class="keyword">true</span>;
}</pre>
<p>To start the process we need the executable name of <i>Qt Assistant</i> as well as the command line arguments for running <i>Qt Assistant</i> in a customized mode. The executable name is a little bit tricky since it depends on the platform, but fortunately it is only different on Mac OS X.</p>
<p>The displayed documentation can be altered using the <tt>-collectionFile</tt> command line argument when launching <i>Qt Assistant</i>. When started without any options, <i>Qt Assistant</i> displays a default set of documentation. When Qt is installed, the default documentation set in <i>Qt Assistant</i> contains the Qt reference documentation as well as the tools that come with Qt, such as Qt Designer and <tt>qmake</tt>.</p>
<p>In our example, we replace the default documentation set with our custom documentation by passing our application-specific collection file to the process's command line options.</p>
<p>As the last argument, we add <tt>-enableRemoteControl</tt>, which makes <i>Qt Assistant</i> listen to its <tt>stdin</tt> channel for commands, such as those to display a certain page in the documentation. Then we start the process and wait until it is actually running. If, for some reason <i>Qt Assistant</i> cannot be started, <tt>startAssistant()</tt> will return false.</p>
<p>The implementation for <tt>showDocumentation()</tt> is now straightforward. Firstly, we ensure that <i>Qt Assistant</i> is running, then we send the request to display the <i>page</i> via the <tt>stdin</tt> channel of the process. It is very important here that the command is terminated by the '\0' character followed by an end of line token to flush the channel.</p>
<pre class="cpp"> <span class="type">void</span> Assistant<span class="operator">::</span>showDocumentation(<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">&</span>page)
{
<span class="keyword">if</span> (<span class="operator">!</span>startAssistant())
<span class="keyword">return</span>;
<span class="type"><a href="qbytearray.html">QByteArray</a></span> ba(<span class="string">"SetSource "</span>);
ba<span class="operator">.</span>append(<span class="string">"qthelp://com.trolltech.examples.simpletextviewer/doc/"</span>);
proc<span class="operator">-</span><span class="operator">></span>write(ba <span class="operator">+</span> page<span class="operator">.</span>toLocal8Bit() <span class="operator">+</span> <span class="char">'\n'</span>);
}</pre>
<p>Finally, we make sure that <i>Qt Assistant</i> is terminated properly in the case that the application is shut down. The destructor of <a href="qprocess.html">QProcess</a> kills the process, meaning that the application has no possibility to do things like save user settings, which would result in corrupted settings files. To avoid this, we ask <i>Qt Assistant</i> to terminate in the destructor of the <tt>Assistant</tt> class.</p>
<pre class="cpp"> Assistant<span class="operator">::</span><span class="operator">~</span>Assistant()
{
<span class="keyword">if</span> (proc <span class="operator">&</span><span class="operator">&</span> proc<span class="operator">-</span><span class="operator">></span>state() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qprocess.html">QProcess</a></span><span class="operator">::</span>Running) {
proc<span class="operator">-</span><span class="operator">></span>terminate();
proc<span class="operator">-</span><span class="operator">></span>waitForFinished(<span class="number">3000</span>);
}
<span class="keyword">delete</span> proc;
}</pre>
<a name="mainwindow-class"></a>
<h2>MainWindow Class</h2>
<p class="centerAlign"><img src="images/simpletextviewer-mainwindow.png" alt="" /></p><p>The <tt>MainWindow</tt> class provides the main application window with two menus: the <b>File</b> menu lets the user open and view an existing file, while the <b>Help</b> menu provides information about the application and about Qt, and lets the user open <i>Qt Assistant</i> to display the application's documentation.</p>
<p>To be able to access the help functionality, we initialize the <tt>Assistant</tt> object in the <tt>MainWindow</tt>'s constructor.</p>
<pre class="cpp"> MainWindow<span class="operator">::</span>MainWindow()
{
assistant <span class="operator">=</span> <span class="keyword">new</span> Assistant;
...
}</pre>
<p>Then we create all the actions for the Simple Text Viewer application. Of special interest is the <tt>assistantAct</tt> action accessible via the <b>F1</b> shortcut or the <b>Help|Help Contents</b> menu item. This action is connected to the <tt>showDocumentation()</tt> slot of the <tt>MainWindow</tt> class.</p>
<pre class="cpp"> <span class="type">void</span> MainWindow<span class="operator">::</span>createActions()
{
assistantAct <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qaction.html">QAction</a></span>(tr(<span class="string">"Help Contents"</span>)<span class="operator">,</span> <span class="keyword">this</span>);
assistantAct<span class="operator">-</span><span class="operator">></span>setShortcut(<span class="type"><a href="qkeysequence.html">QKeySequence</a></span><span class="operator">::</span>HelpContents);
connect(assistantAct<span class="operator">,</span> SIGNAL(triggered())<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> SLOT(showDocumentation()));
...
}</pre>
<p>In the <tt>showDocumentation()</tt> slot, we call the <tt>showDocumentation()</tt> function of the <tt>Assistant</tt> class with the URL of home page of the documentation.</p>
<pre class="cpp"> <span class="type">void</span> MainWindow<span class="operator">::</span>showDocumentation()
{
assistant<span class="operator">-</span><span class="operator">></span>showDocumentation(<span class="string">"index.html"</span>);
}</pre>
<p>Finally, we must reimplement the protected <a href="qwidget.html#closeEvent">QWidget::closeEvent</a>() event handler to ensure that the application's <i>Qt Assistant</i> instance is properly closed before we terminate the application.</p>
<pre class="cpp"> <span class="type">void</span> MainWindow<span class="operator">::</span>closeEvent(<span class="type"><a href="qcloseevent.html">QCloseEvent</a></span> <span class="operator">*</span>)
{
<span class="keyword">delete</span> assistant;
}</pre>
<a name="findfiledialog-class"></a>
<h2>FindFileDialog Class</h2>
<p class="centerAlign"><img src="images/simpletextviewer-findfiledialog.png" alt="" /></p><p>The Simple Text Viewer application provides a find file dialog allowing the user to search for files using wildcard matching. The search is performed within the specified directory, and the user is given an option to browse the existing file system to find the relevant directory.</p>
<p>In the constructor we save the references to the <tt>Assistant</tt> and <tt>QTextEdit</tt> objects passed as arguments. The <tt>Assistant</tt> object will be used in the <tt>FindFileDialog</tt>'s <tt>help()</tt> slot, as we will see shortly, while the <a href="qtextedit.html">QTextEdit</a> will be used in the dialog's <tt>openFile()</tt> slot to display the chosen file.</p>
<pre class="cpp"> FindFileDialog<span class="operator">::</span>FindFileDialog(TextEdit <span class="operator">*</span>editor<span class="operator">,</span> Assistant <span class="operator">*</span>assistant)
: <span class="type"><a href="qdialog.html">QDialog</a></span>(editor)
{
currentAssistant <span class="operator">=</span> assistant;
currentEditor <span class="operator">=</span> editor;
...
}</pre>
<p>The most relevant member to observe in the <tt>FindFileDialog</tt> class is the private <tt>help()</tt> slot. The slot is connected to the dialog's <b>Help</b> button, and brings the current <i>Qt Assistant</i> instance to the foreground with the documentation for the dialog by calling <tt>Assistant</tt>'s <tt>showDocumentation()</tt> function.</p>
<pre class="cpp"> <span class="type">void</span> FindFileDialog<span class="operator">::</span>help()
{
currentAssistant<span class="operator">-</span><span class="operator">></span>showDocumentation(<span class="string">"filedialog.html"</span>);
}</pre>
<a name="summary"></a>
<h2>Summary</h2>
<p>In order to make <i>Qt Assistant</i> act as a customized help tool for your application, you must provide your application with a process that controls <i>Qt Assistant</i> in addition to a custom help collection file including Qt compressed help files.</p>
<p>The <a href="assistant-custom-help-viewer.html">Using Qt Assistant as a Custom Help Viewer</a> document contains more information about the options and settings available to applications that use <i>Qt Assistant</i> as a custom help viewer.</p>
</div>
<!-- @@@help/simpletextviewer -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2013 Digia Plc and/or its
subsidiaries. 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>
Digia, Qt and their respective logos are trademarks of Digia Plc
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>
