From: Jerome Pasion Date: Fri, 9 Nov 2012 16:49:40 +0000 (+0100) Subject: Assistant: Updated documentation configuration for Qt 5 X-Git-Tag: accepted/tizen/20131212.181521~168^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=022b31497b02e516ec35ac7652352d79f244cc16;p=platform%2Fupstream%2Fqttools.git Assistant: Updated documentation configuration for Qt 5 -moved content from qt5/qtdoc, including snippets, images, example doc -added QMAKE_DOCS to create a 'docs' target -modularized doc into doc/src, doc/images, doc/snippets -removed unneeded files Change-Id: I0f3774d51617c57a731aa54d7503e3d42a265747 Reviewed-by: Friedemann Kleint Reviewed-by: Karsten Heimrich Reviewed-by: Geir Vattekar --- diff --git a/examples/help/simpletextviewer/doc/images/simpletextviewer-example.png b/examples/help/simpletextviewer/doc/images/simpletextviewer-example.png new file mode 100644 index 0000000..95d2905 Binary files /dev/null and b/examples/help/simpletextviewer/doc/images/simpletextviewer-example.png differ diff --git a/examples/help/simpletextviewer/doc/images/simpletextviewer-findfiledialog.png b/examples/help/simpletextviewer/doc/images/simpletextviewer-findfiledialog.png new file mode 100644 index 0000000..f6e55f0 Binary files /dev/null and b/examples/help/simpletextviewer/doc/images/simpletextviewer-findfiledialog.png differ diff --git a/examples/help/simpletextviewer/doc/images/simpletextviewer-mainwindow.png b/examples/help/simpletextviewer/doc/images/simpletextviewer-mainwindow.png new file mode 100644 index 0000000..98c1c61 Binary files /dev/null and b/examples/help/simpletextviewer/doc/images/simpletextviewer-mainwindow.png differ diff --git a/examples/help/simpletextviewer/doc/src/simpletextviewer.qdoc b/examples/help/simpletextviewer/doc/src/simpletextviewer.qdoc new file mode 100644 index 0000000..072cc01 --- /dev/null +++ b/examples/help/simpletextviewer/doc/src/simpletextviewer.qdoc @@ -0,0 +1,447 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example help/simpletextviewer + \title Simple Text Viewer Example + + The Simple Text Viewer example shows how to use \QA as a customized + help viewer for your application. + + This is done in two stages. Firstly, documentation is created and \QA + is customized; secondly, the functionality to launch and control + \QA is added to the application. + + \image simpletextviewer-example.png + + The Simple Text Viewer application lets the user select and view + existing files. + + The application provides its own custom documentation that is + available from the \gui Help menu in the main window's menu bar + or by clicking the \gui Help button in the application's find file + dialog. + + The example consists of four classes: + + \list + \li \c Assistant provides functionality to launch \QA. + \li \c MainWindow is the main application window. + \li \c FindFileDialog allows the user to search for + files using wildcard matching. + \li \c TextEdit provides a rich text browser that makes + sure that images referenced in HTML documents are + displayed properly. + \endlist + + 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. + + \section1 Creating Documentation and Customizing \QA + + 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 \QA how to structure and display the + help information. + + \section2 Organizing Documentation for \QA + + 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. + + To organize the documentation and make it available for \QA, 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 \QA. + 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. + + \code + + + com.trolltech.examples.simpletextviewer + doc + \endcode + + 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 \QA, 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 \QA will hide the documentation. + + Again, since we'll only have one documentation set, we do not need + the filtering functionality of \QA and can therefore skip the + filter attributes. + + Now, we build up the table of contents. An item in the table is + defined by the \c section 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: + + \list + \li Simple Text Viewer + \list + \li Find File + \list + \li File Dialog + \li Wildcard Matching + \li Browse + \endlist + \li Open File + \endlist + \endlist + + In the help project file, the outline is represented by: + + \code + + +
+
+
+
+
+
+
+
+ + \endcode + + After the table of contents is defined, we will list all index keywords: + + \code + + + + + + + + + + + + + + + + + \endcode + + 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. + + \code + + browse.html + filedialog.html + findfile.html + index.html + intro.html + openfile.html + wildcardmatching.html + images/browse.png + images/*.png + + + + \endcode + + The help project file is now finished. If you want to see the resulting + documentation in \QA, you have to generate a Qt compressed help file + out of it and register it with the default help collection of \QA. + + \code + qhelpgenerator simpletextviewer.qhp -o simpletextviewer.qch + assistant -register simpletextviewer.qch + \endcode + + If you start \QA 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 \QA. + + \section2 Customizing \QA + + The easiest way to make \QA 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 \QA. + + At first, we change the window title and icon. Instead of showing "\QA" + it will show "Simple Text Viewer", so it is much clearer for the user + that the help viewer actually belongs to our application. + + \code + + + + Simple Text Viewer + images/handbook.png + Trolltech/SimpleTextViewer + \endcode + + The \c cacheDirectory tag specifies a subdirectory of the users + data directory (see the + \l{Using Qt Assistant as a Custom Help Viewer#Qt Help Collection Files}{Qt Help Collection Files}) + where the cache file for the full text search or the settings file will + be stored. + + After this, we set the page displayed by \QA 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. + + \code + qthelp://com.trolltech.examples.simpletextviewer/doc/index.html + \endcode + + Next, we alter the name of the "About" menu item to "About Simple + Text Viewer". The contents of the \gui{About} dialog are also changed + by specifying a file where the about text or icon is taken from. + + \code + + About Simple Text Viewer + + + about.txt + images/icon.png + + \endcode + + \QA offers the possibility to add or remove documentation via its + preferences dialog. This functionality is helpful when using \QA + 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. + + 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 \QA, which means that the filter page and the filter + toolbar will not be available. + + \code + false + false + false + + \endcode + + For testing purposes, we already generated the compressed help file + and registered it with \QA'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. + + \code + + + + simpletextviewer.qhp + simpletextviewer.qch + + + + simpletextviewer.qch + + + + \endcode + + 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 + \c qcollectiongenerator tool. + + \code + qcollectiongenerator simpletextviewer.qhcp -o simpletextviewer.qhc + \endcode + + To test all our customizations made to \QA, we add the collection + file name to the command line: + + \code + assistant -collectionFile simpletextviewer.qhc + \endcode + + \section1 Controlling \QA via the Assistant Class + + We will first take a look at how to start and operate \QA from a + remote application. For that purpose, we create a class called + \c Assistant. + + This class provides a public function that is used to show pages + of the documentation, and one private helper function to make sure + that \QA is up and running. + + Launching \QA is done in the function \c startAssistant() by simply + creating and starting a QProcess. If the process is already running, + the function returns immediately. Otherwise, the process has + to be set up and started. + + \snippet simpletextviewer/assistant.cpp 2 + + To start the process we need the executable name of \QA as well as the + command line arguments for running \QA 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. + + The displayed documentation can be altered using the \c -collectionFile + command line argument when launching \QA. When started without any options, + \QA displays a default set of documentation. When Qt is installed, + the default documentation set in \QA contains the Qt reference + documentation as well as the tools that come with Qt, such as Qt + Designer and \c qmake. + + 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. + + As the last argument, we add \c -enableRemoteControl, which makes \QA + listen to its \c stdin 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 \QA cannot be started, \c startAssistant() will return + false. + + The implementation for \c showDocumentation() is now straightforward. + Firstly, we ensure that \QA is running, then we send the request to + display the \a page via the \c stdin 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. + + \snippet simpletextviewer/assistant.cpp 1 + + Finally, we make sure that \QA is terminated properly in the case that + the application is shut down. The destructor of QProcess 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 \QA to terminate in the destructor of the + \c Assistant class. + + \snippet simpletextviewer/assistant.cpp 0 + + \section1 MainWindow Class + + \image simpletextviewer-mainwindow.png + + The \c MainWindow class provides the main application window with + two menus: the \gui File menu lets the user open and view an + existing file, while the \gui Help menu provides information about + the application and about Qt, and lets the user open \QA to + display the application's documentation. + + To be able to access the help functionality, we initialize the + \c Assistant object in the \c MainWindow's constructor. + + \snippet simpletextviewer/mainwindow.cpp 0 + \dots + \snippet simpletextviewer/mainwindow.cpp 1 + + Then we create all the actions for the Simple Text Viewer application. + Of special interest is the \c assistantAct action accessible + via the \key{F1} shortcut or the \menu{Help|Help Contents} menu item. + This action is connected to the \c showDocumentation() slot of + the \c MainWindow class. + + \snippet simpletextviewer/mainwindow.cpp 4 + \dots + \snippet simpletextviewer/mainwindow.cpp 5 + + In the \c showDocumentation() slot, we call the \c showDocumentation() + function of the \c Assistant class with the URL of home page of the + documentation. + + \snippet simpletextviewer/mainwindow.cpp 3 + + Finally, we must reimplement the protected QWidget::closeEvent() + event handler to ensure that the application's \QA instance is + properly closed before we terminate the application. + + \snippet simpletextviewer/mainwindow.cpp 2 + + \section1 FindFileDialog Class + + \image simpletextviewer-findfiledialog.png + + 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. + + In the constructor we save the references to the \c Assistant + and \c QTextEdit objects passed as arguments. The \c Assistant + object will be used in the \c FindFileDialog's \c help() slot, + as we will see shortly, while the QTextEdit will be used in the + dialog's \c openFile() slot to display the chosen file. + + \snippet simpletextviewer/findfiledialog.cpp 0 + \dots + \snippet simpletextviewer/findfiledialog.cpp 1 + + The most relevant member to observe in the \c FindFileDialog + class is the private \c help() slot. The slot is connected to the + dialog's \gui Help button, and brings the current \QA instance + to the foreground with the documentation for the dialog by + calling \c Assistant's \c showDocumentation() function. + + \snippet simpletextviewer/findfiledialog.cpp 2 + + \section1 Summary + + In order to make \QA act as a customized help tool for + your application, you must provide your application with a + process that controls \QA in addition to a custom help collection + file including Qt compressed help files. + + The \l{Using Qt Assistant as a Custom Help Viewer} document contains + more information about the options and settings available to + applications that use \QA as a custom help viewer. +*/ diff --git a/src/assistant/assistant/assistant.pro b/src/assistant/assistant/assistant.pro index 5eee8e6..82681f3 100644 --- a/src/assistant/assistant/assistant.pro +++ b/src/assistant/assistant/assistant.pro @@ -19,6 +19,8 @@ DEPENDPATH += ../shared include(../../shared/fontpanel/fontpanel.pri) +QMAKE_DOCS = $$PWD/doc/assistant.qdocconf + # ## Work around a qmake issue when statically linking to # ## not-yet-installed plugins QMAKE_LIBDIR += $$QT.core.plugins/sqldrivers diff --git a/src/assistant/assistant/doc/HOWTO b/src/assistant/assistant/doc/HOWTO deleted file mode 100644 index a014347..0000000 --- a/src/assistant/assistant/doc/HOWTO +++ /dev/null @@ -1,16 +0,0 @@ -How to build/ update a new assistant.qch for Assistant internal help - -- update: - - open assistant.qdocconf, update year and qt version - - - ..\..\..\..\qdoc3\debug\qdoc3.exe assistant.qdocconf - will generate an folder html containing all required stuff - - - cp assistant.qhp to generated html folder - - run qhelpgenerator html\assistant.qhp -o ..\assistant.qch - - - rebuild assistant - -- to test your changes: - - remove assistant.qch in your cache directory - - restart assistant diff --git a/src/assistant/assistant/doc/assistant.qdoc b/src/assistant/assistant/doc/assistant.qdoc deleted file mode 100644 index bd03854..0000000 --- a/src/assistant/assistant/doc/assistant.qdoc +++ /dev/null @@ -1,461 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page assistant.html - \title Qt Assistant - - \chapter Introduction - - This document introduces \e{Qt Assistant}, a tool for presenting on-line - documentation. It also introduces the Qt Reference Documentation which - is accessible using \e{Qt Assistant}, or with a web browser. The document is - divided into the following sections: - - Table of contents: - - \list - \li \l{Introduction} - \li \l{The One-Minute Guide to Using Qt Assistant} - \li \l{Introduction to the Qt Reference Documentation} - \li \l{Qt Assistant in More Detail} - \li \l{Full Text Searching} - \endlist - - \chapter The One-Minute Guide to Using Qt Assistant - - Once you have installed Qt, \QA should be ready to run: - - \list - \li On Windows, \QA is available as a menu option on the Qt menu. - \li On Mac OS X, \QA is installed in the /Developer/Applications/Qt directory. - \li On Unix/Linux, open a terminal, type \c{assistant} and press \key{Enter}. - \endlist - - When you start up \QA, you will be presented with a standard main window - application, with a menu bar and toolbar. Below these, on the left hand - side are navigation windows called \e{Contents}, \e{Index} and \e{Bookmarks}. - On the right, taking up most of the space, is the \e{Documentation} window. - By default, \QA loads the Qt reference documentation along with the manuals - of other Qt tools, like \QD or \QL. - - \QA works in a similar way to a Web browser. If you click hyperlinks - (cross-references), the \e{Documentation} window will present the relevant - page. You can bookmark pages of particular interest and you can click the - \gui{Previous} and \gui{Next} toolbar buttons to navigate within the pages - you have visited. - - Although \QA can be used just like a Web browser to navigate through - the documentation, \QA offers a powerful means of navigation that Web - browsers do not provide. \QA uses an advanced full text search engine - to index all the pages in each compressed help file so that you can - search for particular words and phrases. - - To perform an index search, click the \gui{Index} tab on the Sidebar - (or press \key{Alt+I}). In the \gui{'Look For'} line edit enter a word; - e.g., 'homedirpath'. As you type, words are found and highlighted in a list - beneath the line edit. If the highlighted text matches what you're - looking for, double click it, (or press \key{Enter}) and the - \e{Documentation} window will display the relevant page. You rarely have - to type in the whole word before \QA finds a match. Note that for some - words there may be more than one possible page that is relevant. - - \QA also provides full text searching for finding specific words in - the documentation. To activate the full text search, either press \key(Alt+S) - or click on the \gui{Search} tab in the \e{Documentation} window. Then - enter the term you're looking for and hit the \gui{Search} button. All - documents containing the specified term will then be listed in the list box - below. - - \chapter Introduction to the Qt Reference Documentation - - The documentation for the Qt library is written in-line in the \c - .cpp files by the developers themselves. The documentation team - revises the documentation to ensure that it is accurate and usable, - and to provide quality control. The documentation team also writes the - larger texts, such as the class descriptions that introduce a class - along with the concepts the class uses, as well as introducing the - functions and properties that the class provides. - - The documentation focuses on the API rather than the internals, since - we make great efforts to keep our API consistent and compatible with - each new version, but we may change the internals considerably to improve - performance and enhance functionality. - - The Qt Reference Documentation consists of almost 1,500 HTML pages - (over 2,500 printed pages). The overwhelming majority of pages - document Qt classes. Since developers differ in the way they - think and work we provide a variety of approaches to navigating the - documentation set: - - \list - \li The \menu{Qt's Classes} page lists every class - in Qt's public API, and consists of several hundred classes. - \li The \menu{Qt's Main Classes} page lists the - classes you're most likely to use most often, and provides a much - shorter and more managable list than the All Classes list. - \li The \menu{Grouped Classes} page presents a list - of groups, each of which leads to a list of related classes, for - example, the \menu{Advanced Widgets} list. - \li The \menu{Class Inheritance Hierarchy} page - presents a list of classes in terms of the hierarchy of Qt classes. - \li The \menu{Member Function Index} page lists all the - functions provided by Qt classes, each one with links to the class(es) - in which it appears. - \endlist - - No matter where you find yourself in the Qt documentation, you will - find extensive cross-referencing. Even snippets of example code - contain clickable links, so that for example, if you come across a - class declaration in a code example, the class name will be a - clickable link to the class's documentation. - - In addition to the class documentation some of Qt's modules have - extensive descriptions, and there are many overview documents which - describe various aspects of the Qt library; all these are linked from - the reference documentation home page. There are also two tutorials - and numerous example programs in the examples subdirectory of the Qt - distribution. - - \chapter Qt Assistant in More Detail - - \img assistant-assistant.png - - \section1 Command Line Options - - \QA handles the following command line options: - - \table - \header - \li Command Line Option - \li Brief Description - \row - \li -collectionFile - \li Uses the specified collection file instead of the default one. - \row - \li -showUrl URL - \li Shows the document referenced by URL. - \row - \li -enableRemoteControl - \li Enables \QA to be remotly controlled. - \row - \li -show - \li Shows the specified dockwidget which can be "contents", "index", - "bookmarks" or "search". - \row - \li -hide - \li Hides the specified dockwidget which can be "contents", "index", - "bookmarks" or "search. - \row - \li -activate - \li Activates the specified dockwidget which can be "contents", - "index", "bookmarks" or "search. - \row - \li -register - \li Registers the specified compressed help file in the given help - collection. - \row - \li -unregister - \li Unregisters the specified compressed help file from the given - collection file. - \row - \li -quiet - \li Doesn't show any error, warning or success messages. - \endtable - - \section1 Tool Windows - - \img assistant-dockwidgets.png - - The tool windows provide four ways to navigate the documentation: - - \list - \li The \gui{Contents} window presents a table of contents implemented as a - tree view for the documentation that is available. If you click an item, - its documentation will appear in the \e{Documentation} window. If you double - click an item or click on the control to the left of it, the item's sub-items - will appear. Click a sub-item to make its page appear in the \e{Documentation} - window. Click on the control next to an open item to hide its sub-items. - \li The \gui{Index} window is used to look up key words or phrases. - See \l{The One-Minute Guide to Using Qt Assistant} for how to use this - window. - \li The \gui{Bookmarks} window lists any bookmarks you have made. Double - click a bookmark to make its page appear in the \e{Documentation} window. - The \gui{Bookmarks} window provides a context menu with \gui{Show Item}, - \gui{Delete Item} as well as \gui{Rename Item}. Click in the main menu - \menu{Bookmark|Add Bookmark...} (or press \key{Ctrl+B}) to bookmark the - page that is currently showing in the \e{Documentation} window. Right click - a bookmark in the list to rename or delete the highlighted bookmark. - \endlist - - If you want the \gui{Documentation} window to use as much space as possible, - you can easily group, move or hide the tool windows. To group the windows, - drag one on top of the other and release the mouse. If one or all tool - windows are not shown, press \key{Alt+C}, \key{Alt+I} or \key{Alt+O} to show - the required window. - - The tool windows can be docked into the main window, so you can drag them - to the top, left, right or bottom of \e{Qt Assistant's} window, or you can - drag them outside \QA to float them as independent windows. - - \section1 Documentation Window - - \img assistant-docwindow.png - - The \gui{Documentation} window lets you create a tab for each - documentation page that you view. Click the \gui{Add Tab} button and a new - tab will appear with the page name as the tab's caption. This makes it - convenient to switch between pages when you are working with different - documentation. You can delete a tab by clicking the \gui{Close Tab} button - located on the right side of the \gui{Documentation} window. - - \section1 Toolbars - - \img assistant-toolbar.png - - The main toolbar provides fast access to the most common actions. - - \table - \header \li Action \li Description \li Menu Item \li Shortcut - \row \li \gui{Previous} \li Takes you to the previous page in the history. - \li \menu{Go|Previous} \li \key{Alt+Left Arrow} - \row \li \gui{Next} \li Takes you to the next page in the history. - \li \menu{Go|Next} \li \key{Alt+Right Arrow} - \row \li \gui{Home} - \li Takes you to the home page as specified in the Preferences Dialog. - \li \menu{Go|Home} \li \key{Ctrl+Home}. - \row \li \gui{Sync with Table of Contents} - \li Synchronizes the \gui{Contents} tool window with the page currently - shown in the \gui{Documentation} window. - \li \menu{Go|Sync with Table of Contents} \li - \row \li \gui{Copy} \li Copies any selected text to the clipboard. - \li \menu{Edit|Copy} \li \key{Ctrl+C} - \row \li \gui{Print} \li Opens the \gui{Print} dialog. - \li \menu{File|Print} \li \key{Ctrl+P} - \row \li \gui{Find in Text} \li Opens the \gui{Find Text} dialog. - \li \menu{Edit|Find in Text} \li \key{Ctrl+F} - \row \li \gui{Zoom in} - \li Increases the font size used to display text in the current tab. - \li \menu{View|Zoom in} \li \key{Ctrl++} - \row \li \gui{Zoom out} - \li Decreases the font size used to display text in the current tab. - \li \menu{View|Zoom out} \li \key{Ctrl+-} - \row \li \gui{Normal Size} - \li Resets the font size to its normal size in the current tab. - \li \menu{View|Normal Size} \li \key{Ctrl+0} - \endtable - - \img assistant-address-toolbar.png - - The address toolbar provides a fast way to enter a specific URL for a - documentation file. By default, the address toolbar is not shown, so it - has to be activated via \menu{View|Toolbars|Address Toolbar}. - - \img assistant-filter-toolbar.png - - The filter toolbar allows you to apply a filter to the currently installed - documentation. As with the address toolbar, the filter toolbar is not visible - by default and has to be activated via \menu{View|Toolbars|Filter Toolbar}. - - \section1 Menus - - \section2 File Menu - - \list - \li \menu{File|Page Setup...} invokes a dialog allowing you to define - page layout properties, such as margin sizes, page orientation and paper size. - \li \menu{File|Print Preview...} provides a preview of the printed pages. - \li \menu{File|Print...} opens the \l{#Print Dialog}{\gui{Print} dialog}. - \li \menu{File|New Tab} opens a new empty tab in the \gui{Documentation} - window. - \li \menu{File|Close Tab} closes the current tab of the - \gui{Documentation} window. - \li \menu{File|Exit} closes the \QA application. - \endlist - - \section2 Edit Menu - - \list - \li \menu{Edit|Copy} copies any selected text to the clipboard. - \li \menu{Edit|Find in Text} invokes the \l{#Find Text Control}{\gui{Find Text} - control} at the lower end of the \gui{Documentation} window. - \li \menu{Edit|Find Next} looks for the next occurance of the specified - text in the \gui{Find Text} control. - \li \menu{Edit|Find Previous} looks for the previous occurance of - the specified text in the \l{#Find Text Control}{\gui{Find Text} control}. - \li \menu{Edit|Preferences} invokes the \l{#Preferences Dialog}{\gui{Preferences} dialog}. - \endlist - - \section2 View Menu - - \list - \li \menu{View|Zoom in} increases the font size in the current tab. - \li \menu{View|Zoom out} decreases the font size in the current tab. - \li \menu{View|Normal Size} resets the font size in the current tab. - \li \menu{View|Contents} toggles the display of the \gui{Contents} tool window. - \li \menu{View|Index} toggles the display of the \gui{Index} tool window. - \li \menu{View|Bookmarks} toggles the display of the \gui{Bookmarks} tool window. - \li \menu{View|Search} toggles the display of the Search in the \gui{Documentation} window. - \endlist - - \section2 Go Menu - - \list - \li \menu{Go|Home} goes to the home page. - \li \menu{Go|Back} displays the previous page in the history. - \li \menu{Go|Forward} displays the next page in the history. - \li \menu{Go|Sync with Table of Contents} syncs the \gui{Contents} tool window to the currently shown page. - \li \menu{Go|Next Page} selects the next tab in the \gui{Documentation} window. - \li \menu{Go|Previous Page} selects the previous tab in the \gui{Documentation} window. - \endlist - - \section2 Bookmarks Menu - - \list - \li \menu{Bookmarks|Add} adds the current page to the list of bookmarks. - \endlist - - \section1 Dialogs - - \section2 Print Dialog - - This dialog is platform-specific. It gives access to various printer - options and can be used to print the document shown in the current tab. - - \section2 Preferences Dialog - - \img assistant-preferences-fonts.png - - The \menu{Fonts} page allows you to change the font family and font sizes of the - browser window displaying the documentation or the application itself. - - \img assistant-preferences-filters.png - - The \menu{Filters} page lets you create and remove documentation - filters. To add a new filter, click the \gui{Add} button, specify a - filter name in the pop-up dialog and click \gui{OK}, then select - the filter attributes in the list box on the right hand side. - You can delete a filter by selecting it and clicking the \gui{Remove} - button. - - \img assistant-preferences-documentation.png - - The \menu{Documentation} page lets you install and remove compressed help - files. Click the \gui{Install} button and choose the path of the compressed - help file (*.qch) you would like to install. - To delete a help file, select a documentation set in the list and click - \gui{Remove}. - - \img assistant-preferences-options.png - - The \menu{Options} page lets you specify the homepage \QA will display when - you click the \gui{Home} button in \QA's main user interface. You can specify - the hompage by typing it here or clicking on one of the buttons below the - textbox. \gui{Current Page} sets the currently displayed page as your home - page while \gui{Restore to default} will reset your home page to the default - home page. - - \section1 Find Text Control - - This control is used to find text in the current page. Enter the text you want - to find in the line edit. The search is incremental, meaning that the most - relevant result is shown as you enter characters into the line edit. - - If you check the \gui{Whole words only} checkbox, the search will only consider - whole words; for example, if you search for "spin" with this checkbox checked it will - not match "spinbox", but will match "spin". If you check the \gui{Case sensitive} - checkbox then, for example, "spin" will match "spin" but not "Spin". You can - search forwards or backwards from your current position in the page by clicking - the \gui{Previous} or \gui{Next} buttons. To hide the find control, either click the - \gui{Close} button or hit the \key{Esc} key. - - \section1 Filtering Help Contents - - \QA allows you to install any kind of documentation as long as it is organized - in Qt compressed help files (*.qch). For example, it is possible to install the - Qt reference documentation for Qt 4.4.0 and Qt 4.4.1 at the same time. In many - respects, this is very convenient since only one version of \QA is needed. - However, at the same time it becomes more complicated when performing tasks like - searching the index because nearly every keyword is defined in Qt 4.4.0 as well - as in Qt 4.4.1. This means that \QA will always ask the user to choose which one - should be displayed. - - We use documentation filters to solve this issue. A filter is identified by its - name, and contains a list of filter attributes. An attribute is just a string and - can be freely chosen. Attributes are defined by the documentation itself, this - means that every documentation set usually has one or more attributes. - - For example, the Qt 4.4.0 \QA documentation defines the attributes \c {assistant}, - \c{tools} and \c{4.4.0}, \QD defines \c{designer}, \c{tools} and \c{4.4.0}. - The filter to display all tools would then define only the attribute - \c{tools} since this attribute is part of both documentation sets. - Adding the attribute \c{assistant} to the filter would then only show \QA - documentation since the \QD documentation does not contain this - attribute. Having an empty list of attributes in a filter will match all - documentation; i.e., it is equivalent to requesting unfiltered documentation. - - \section1 Full Text Searching - - \img assistant-search.png - - \QA provides a powerful full text search engine. To search - for certain words or text, click the \gui{Search} tab in the \gui{Documentation} - window. Then enter the text you want to look for and press \key{Enter} - or click the \gui{Search} button. The search is not case sensitive, so, - for example, Foo, fOo and FOO are all treated as the same. The following are - examples of common search patterns: - - \list - \li \c deep -- lists all the documents that contain the word 'deep' - \li \c{deep*} -- lists all the documents that contain a word beginning - with 'deep' - \li \c{deep copy} -- lists all documents that contain both 'deep' \e - and 'copy' - \li \c{"deep copy"} -- list all documents that contain the phrase 'deep copy' - \endlist - - It is also possible to use the \gui{Advanced search} to get more flexibility. - You can specify some words so that hits containing these are excluded from the - result, or you can search for an exact phrase. Searching for similar words will - give results like these: - - \list - \li \c{QStin} -- lists all the documents with titles that are similar, such as \c{QString} - \li \c{QSting} -- lists all the documents with titles that are similar, such as \c{QString} - \li \c{QStrin} -- lists all the documents with titles that are similar, such as \c{QString} - \endlist - - Options can be combined to improve the search results. - - The list of documents found is ordered according to the number of - occurrences of the search text which they contain, with those containing - the highest number of occurrences appearing first. Simply click any - document in the list to display it in the \gui{Documentation} window. - - If the documentation has changed \mdash for example, if documents have been added - or removed \mdash \QA will index them again. -*/ diff --git a/src/assistant/assistant/doc/assistant.qdocconf b/src/assistant/assistant/doc/assistant.qdocconf index d0e2f5e..782e146 100644 --- a/src/assistant/assistant/doc/assistant.qdocconf +++ b/src/assistant/assistant/doc/assistant.qdocconf @@ -1,16 +1,37 @@ -include(../../../../qdoc3/test/qt.qdocconf) - -version = - -sourcedirs = $QTDIR/tools/assistant/tools/assistant/doc -imagedirs = $QTDIR/tools/assistant/tools/assistant/doc/images -outputdir = $QTDIR/tools/assistant/tools/assistant/doc/html -project = assistant -description = "Qt Assistant" -HTML.{postheader,address} = "" -HTML.footer = "

\n" \ - "\n" \ - "\n" \ - "\n" \ - "\n" \ - "
Copyright © 2012 Digia Plc and/or its subsidiary(-ies)Trademarks
Qt 5.0.0
" +include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) + +project = Qt Assistant +description = Qt Assistant Manual +url = http://qt-project.org/doc/qtassistant + +qhp.projects = Assistant + +qhp.Assistant.file = assistant.qhp +qhp.Assistant.namespace = com.qt-project.assistant.500 +qhp.Assistant.virtualFolder = assistant +qhp.Assistant.indexTitle = Qt Assistant Manual + +qhp.Assistant.filterAttributes = qt 5.0.0 tools assistant +qhp.Assistant.customFilters.Assistant.name = Qt Assistant Manual +qhp.Assistant.customFilters.Assistant.filterAttributes = qt tools assistant +qhp.Assistant.subprojects = manual examples +qhp.Assistant.subprojects.manual.title = Manual +qhp.Assistant.subprojects.manual.indexTitle = Qt Assistant Manual +qhp.Assistant.subprojects.manual.selectors = fake:page +qhp.Assistant.subprojects.examples.title = Examples +qhp.Assistant.subprojects.examples.indexTitle = Qt Examples +qhp.Assistant.subprojects.examples.selectors = fake:example +qhp.Assistant.subprojects.examples.sortPages = true + +language = Cpp + +sourcedirs = .. + +exampledirs = ../../../../examples \ + snippets + +imagedirs = images + +outputdir = $QT_INSTALL_DOCS/assistant + +depends += qtdoc diff --git a/src/assistant/assistant/doc/assistant.qhp b/src/assistant/assistant/doc/assistant.qhp deleted file mode 100644 index 7ea4cdd..0000000 --- a/src/assistant/assistant/doc/assistant.qhp +++ /dev/null @@ -1,22 +0,0 @@ - - - assistant - com.trolltech.com.assistantinternal-1.0.0 - - - assistant.html - classic.css - images/assistant-address-toolbar.png - images/assistant-assistant.png - images/assistant-dockwidgets.png - images/assistant-docwindow.png - images/assistant-filter-toolbar.png - images/assistant-preferences-documentation.png - images/assistant-preferences-filters.png - images/assistant-preferences-fonts.png - images/assistant-preferences-options.png - images/assistant-search.png - images/assistant-toolbar.png - - - diff --git a/src/assistant/assistant/doc/classic.css b/src/assistant/assistant/doc/classic.css deleted file mode 100644 index 9113540..0000000 --- a/src/assistant/assistant/doc/classic.css +++ /dev/null @@ -1,92 +0,0 @@ -h3.fn,span.fn -{ - margin-left: 1cm; - text-indent: -1cm; -} - -a:link -{ - color: #004faf; - text-decoration: none -} - -a:visited -{ - color: #672967; - text-decoration: none -} - -td.postheader -{ - font-family: sans-serif -} - -tr.address -{ - font-family: sans-serif -} - -body -{ - background: #ffffff; - color: black -} - -table tr.odd { - background: #f0f0f0; - color: black; -} - -table tr.even { - background: #e4e4e4; - color: black; -} - -table.annotated th { - padding: 3px; - text-align: left -} - -table.annotated td { - padding: 3px; -} - -table tr pre -{ - padding-top: none; - padding-bottom: none; - padding-left: none; - padding-right: none; - border: none; - background: none -} - -tr.qt-style -{ - background: #a2c511; - color: black -} - -body pre -{ - padding: 0.2em; - border: #e7e7e7 1px solid; - background: #f1f1f1; - color: black -} - -span.preprocessor, span.preprocessor a -{ - color: darkblue; -} - -span.comment -{ - color: darkred; - font-style: italic -} - -span.string,span.char -{ - color: darkgreen; -} diff --git a/src/assistant/assistant/doc/snippets/doc_src_assistant-manual.qdoc b/src/assistant/assistant/doc/snippets/doc_src_assistant-manual.qdoc new file mode 100644 index 0000000..730373c --- /dev/null +++ b/src/assistant/assistant/doc/snippets/doc_src_assistant-manual.qdoc @@ -0,0 +1,148 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +assistant -collectionFile file +//! [0] + + +//! [1] + + + + My Application Help + qthelp://com.mycompany.1_0_0/doc/index.html + myfilter + application.png + false + false + true + mycompany/myapplication + + About My Application + Über meine Applikation... + + + about.txt + ueber.txt + about.png + + + + + + myapplication-manual.qhp + myapplication-manual.qch + + + + myapplication-manual.qch + + + +//! [1] + + +//! [2] +QProcess *process = new QProcess; +QStringList args; +args << QLatin1String("-collectionFile") + << QLatin1String("mycollection.qhc") + << QLatin1String("-enableRemoteControl"); +process->start(QLatin1String("assistant"), args); +if (!process->waitForStarted()) + return; +//! [2] + + +//! [3] +QByteArray ba; +ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n"); +process->write(ba); +//! [3] + + +//! [4] +QByteArray ba; +ba.append("hide bookmarks;"); +ba.append("hide index;"); +ba.append("setSource qthelp://com.mycompany.1_0_0/doc/index.html\n"); +process->write(ba); +//! [4] + +//! [5] + + + ... + + + myapplication-manual.qch + another-manual.qch + + + +//! [5] + +//! [6] +assistant -collectionFile mycollection.qhc -register myapplication-manual.qch +//! [6] + +//! [7] + + + + My Application Help + mycompany/myapplication + ... + + +//! [7] + +//! [8] +assistant -collectionFile mycollection.qhc +//! [8] + +//! [9] +%QDesktopServices::DataLocation%/mycompany/myapplication/mycollection.qhc +//! [9] + +//! [10] +qcollectiongenerator mycollection.qhcp -o mycollection.qhc +//! [10] diff --git a/src/assistant/assistant/doc/snippets/simpletextviewer/assistant.cpp b/src/assistant/assistant/doc/snippets/simpletextviewer/assistant.cpp new file mode 100644 index 0000000..57588f8 --- /dev/null +++ b/src/assistant/assistant/doc/snippets/simpletextviewer/assistant.cpp @@ -0,0 +1,109 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include +#include +#include +#include + +#include + +#include "assistant.h" + +Assistant::Assistant() + : proc(0) +{ +} + +//! [0] +Assistant::~Assistant() +{ + if (proc && proc->state() == QProcess::Running) { + proc->terminate(); + proc->waitForFinished(3000); + } + delete proc; +} +//! [0] + +//! [1] +void Assistant::showDocumentation(const QString &page) +{ + if (!startAssistant()) + return; + + QByteArray ba("SetSource "); + ba.append("qthelp://com.trolltech.examples.simpletextviewer/doc/"); + + proc->write(ba + page.toLocal8Bit() + '\n'); +} +//! [1] + +//! [2] +bool Assistant::startAssistant() +{ + if (!proc) + proc = new QProcess(); + + if (proc->state() != QProcess::Running) { + QString app = QLibraryInfo::location(QLibraryInfo::BinariesPath) + QDir::separator(); +#if !defined(Q_OS_MAC) + app += QLatin1String("assistant"); +#else + app += QLatin1String("Assistant.app/Contents/MacOS/Assistant"); +#endif + + QStringList args; + args << QLatin1String("-collectionFile") + << QLibraryInfo::location(QLibraryInfo::ExamplesPath) + + QLatin1String("/help/simpletextviewer/documentation/simpletextviewer.qhc") + << QLatin1String("-enableRemoteControl"); + + proc->start(app, args); + + if (!proc->waitForStarted()) { + QMessageBox::critical(0, QObject::tr("Simple Text Viewer"), + QObject::tr("Unable to launch Qt Assistant (%1)").arg(app)); + return false; + } + } + return true; +} +//! [2] diff --git a/src/assistant/assistant/doc/snippets/simpletextviewer/findfiledialog.cpp b/src/assistant/assistant/doc/snippets/simpletextviewer/findfiledialog.cpp new file mode 100644 index 0000000..e423c13 --- /dev/null +++ b/src/assistant/assistant/doc/snippets/simpletextviewer/findfiledialog.cpp @@ -0,0 +1,221 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#include "findfiledialog.h" +#include "assistant.h" +#include "textedit.h" + +//! [0] +FindFileDialog::FindFileDialog(TextEdit *editor, Assistant *assistant) + : QDialog(editor) +{ + currentAssistant = assistant; + currentEditor = editor; +//! [0] + + createButtons(); + createComboBoxes(); + createFilesTree(); + createLabels(); + createLayout(); + + directoryComboBox->addItem(QDir::toNativeSeparators(QDir::currentPath())); + fileNameComboBox->addItem("*"); + findFiles(); + + setWindowTitle(tr("Find File")); +//! [1] +} +//! [1] + +void FindFileDialog::browse() +{ + QString currentDirectory = directoryComboBox->currentText(); + QString newDirectory = QFileDialog::getExistingDirectory(this, + tr("Select Directory"), currentDirectory); + if (!newDirectory.isEmpty()) { + directoryComboBox->addItem(QDir::toNativeSeparators(newDirectory)); + directoryComboBox->setCurrentIndex(directoryComboBox->count() - 1); + update(); + } +} + +//! [2] +void FindFileDialog::help() +{ + currentAssistant->showDocumentation("filedialog.html"); +} +//! [2] + +void FindFileDialog::openFile(QTreeWidgetItem *item) +{ + if (!item) { + item = foundFilesTree->currentItem(); + if (!item) + return; + } + + QString fileName = item->text(0); + QString path = directoryComboBox->currentText() + QDir::separator(); + + currentEditor->setContents(path + fileName); + close(); +} + +void FindFileDialog::update() +{ + findFiles(); + buttonBox->button(QDialogButtonBox::Open)->setEnabled( + foundFilesTree->topLevelItemCount() > 0); +} + +void FindFileDialog::findFiles() +{ + QRegExp filePattern(fileNameComboBox->currentText() + "*"); + filePattern.setPatternSyntax(QRegExp::Wildcard); + + QDir directory(directoryComboBox->currentText()); + + QStringList allFiles = directory.entryList(QDir::Files | QDir::NoSymLinks); + QStringList matchingFiles; + + foreach (QString file, allFiles) { + if (filePattern.exactMatch(file)) + matchingFiles << file; + } + showFiles(matchingFiles); +} + +void FindFileDialog::showFiles(const QStringList &files) +{ + foundFilesTree->clear(); + + for (int i = 0; i < files.count(); ++i) { + QTreeWidgetItem *item = new QTreeWidgetItem(foundFilesTree); + item->setText(0, files[i]); + } + + if (files.count() > 0) + foundFilesTree->setCurrentItem(foundFilesTree->topLevelItem(0)); +} + +void FindFileDialog::createButtons() +{ + browseButton = new QToolButton; + browseButton->setText(tr("...")); + connect(browseButton, SIGNAL(clicked()), this, SLOT(browse())); + + buttonBox = new QDialogButtonBox(QDialogButtonBox::Open + | QDialogButtonBox::Cancel + | QDialogButtonBox::Help); + connect(buttonBox, SIGNAL(accepted()), this, SLOT(openFile())); + connect(buttonBox, SIGNAL(rejected()), this, SLOT(reject())); + connect(buttonBox, SIGNAL(helpRequested()), this, SLOT(help())); +} + +void FindFileDialog::createComboBoxes() +{ + directoryComboBox = new QComboBox; + fileNameComboBox = new QComboBox; + + fileNameComboBox->setEditable(true); + fileNameComboBox->setSizePolicy(QSizePolicy::Expanding, + QSizePolicy::Preferred); + + directoryComboBox->setMinimumContentsLength(30); + directoryComboBox->setSizeAdjustPolicy( + QComboBox::AdjustToMinimumContentsLength); + directoryComboBox->setSizePolicy(QSizePolicy::Expanding, + QSizePolicy::Preferred); + + connect(fileNameComboBox, SIGNAL(editTextChanged(QString)), + this, SLOT(update())); + connect(directoryComboBox, SIGNAL(currentIndexChanged(QString)), + this, SLOT(update())); +} + +void FindFileDialog::createFilesTree() +{ + foundFilesTree = new QTreeWidget; + foundFilesTree->setColumnCount(1); + foundFilesTree->setHeaderLabels(QStringList(tr("Matching Files"))); + foundFilesTree->setRootIsDecorated(false); + foundFilesTree->setSelectionMode(QAbstractItemView::SingleSelection); + + connect(foundFilesTree, SIGNAL(itemActivated(QTreeWidgetItem*,int)), + this, SLOT(openFile(QTreeWidgetItem*))); +} + +void FindFileDialog::createLabels() +{ + directoryLabel = new QLabel(tr("Search in:")); + fileNameLabel = new QLabel(tr("File name (including wildcards):")); +} + +void FindFileDialog::createLayout() +{ + QHBoxLayout *fileLayout = new QHBoxLayout; + fileLayout->addWidget(fileNameLabel); + fileLayout->addWidget(fileNameComboBox); + + QHBoxLayout *directoryLayout = new QHBoxLayout; + directoryLayout->addWidget(directoryLabel); + directoryLayout->addWidget(directoryComboBox); + directoryLayout->addWidget(browseButton); + + QVBoxLayout *mainLayout = new QVBoxLayout; + mainLayout->addLayout(fileLayout); + mainLayout->addLayout(directoryLayout); + mainLayout->addWidget(foundFilesTree); + mainLayout->addStretch(); + mainLayout->addWidget(buttonBox); + setLayout(mainLayout); +} diff --git a/src/assistant/assistant/doc/snippets/simpletextviewer/mainwindow.cpp b/src/assistant/assistant/doc/snippets/simpletextviewer/mainwindow.cpp new file mode 100644 index 0000000..c460915 --- /dev/null +++ b/src/assistant/assistant/doc/snippets/simpletextviewer/mainwindow.cpp @@ -0,0 +1,146 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the examples of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Digia Plc and its Subsidiary(-ies) nor the names +** of its contributors may be used to endorse or promote products derived +** from this software without specific prior written permission. +** +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include +#include +#include +#include +#include +#include + +#include "mainwindow.h" +#include "findfiledialog.h" +#include "assistant.h" +#include "textedit.h" + +// ![0] +MainWindow::MainWindow() +{ + assistant = new Assistant; +// ![0] + textViewer = new TextEdit; + textViewer->setContents(QLibraryInfo::location(QLibraryInfo::ExamplesPath) + + QLatin1String("/help/simpletextviewer/documentation/intro.html")); + setCentralWidget(textViewer); + + createActions(); + createMenus(); + + setWindowTitle(tr("Simple Text Viewer")); + resize(750, 400); +// ![1] +} +//! [1] + +//! [2] +void MainWindow::closeEvent(QCloseEvent *) +{ + delete assistant; +} +//! [2] + +void MainWindow::about() +{ + QMessageBox::about(this, tr("About Simple Text Viewer"), + tr("This example demonstrates how to use\n" + "Qt Assistant as help system for your\n" + "own application.")); +} + +//! [3] +void MainWindow::showDocumentation() +{ + assistant->showDocumentation("index.html"); +} +//! [3] + +void MainWindow::open() +{ + FindFileDialog dialog(textViewer, assistant); + dialog.exec(); +} + +//! [4] +void MainWindow::createActions() +{ + assistantAct = new QAction(tr("Help Contents"), this); + assistantAct->setShortcut(QKeySequence::HelpContents); + connect(assistantAct, SIGNAL(triggered()), this, SLOT(showDocumentation())); +//! [4] + + openAct = new QAction(tr("&Open..."), this); + openAct->setShortcut(QKeySequence::Open); + connect(openAct, SIGNAL(triggered()), this, SLOT(open())); + + clearAct = new QAction(tr("&Clear"), this); + clearAct->setShortcut(tr("Ctrl+C")); + connect(clearAct, SIGNAL(triggered()), textViewer, SLOT(clear())); + + exitAct = new QAction(tr("E&xit"), this); + exitAct->setShortcuts(QKeySequence::Quit); + connect(exitAct, SIGNAL(triggered()), this, SLOT(close())); + + aboutAct = new QAction(tr("&About"), this); + connect(aboutAct, SIGNAL(triggered()), this, SLOT(about())); + + aboutQtAct = new QAction(tr("About &Qt"), this); + connect(aboutQtAct, SIGNAL(triggered()), qApp, SLOT(aboutQt())); +//! [5] +} +//! [5] + +void MainWindow::createMenus() +{ + fileMenu = new QMenu(tr("&File"), this); + fileMenu->addAction(openAct); + fileMenu->addAction(clearAct); + fileMenu->addSeparator(); + fileMenu->addAction(exitAct); + + helpMenu = new QMenu(tr("&Help"), this); + helpMenu->addAction(assistantAct); + helpMenu->addSeparator(); + helpMenu->addAction(aboutAct); + helpMenu->addAction(aboutQtAct); + + + menuBar()->addMenu(fileMenu); + menuBar()->addMenu(helpMenu); +} diff --git a/src/assistant/assistant/doc/src/assistant-manual.qdoc b/src/assistant/assistant/doc/src/assistant-manual.qdoc new file mode 100644 index 0000000..806ce4f --- /dev/null +++ b/src/assistant/assistant/doc/src/assistant-manual.qdoc @@ -0,0 +1,823 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page assistant-manual.html + \title Qt Assistant Manual + \ingroup qttools + + \startpage {Qt Reference Documentation} + \nextpage Qt Assistant in More Detail + + \keyword Qt Assistant + + This document introduces \QA, a tool for presenting on-line + documentation. The document is divided into the following sections: + + Table of contents: + + \list + \li \l{The One-Minute Guide to Using Qt Assistant} + \li \l{Qt Assistant in More Detail} + \li \l{Using Qt Assistant as a Custom Help Viewer} + \endlist + + \chapter The One-Minute Guide to Using Qt Assistant + + Once you have installed Qt, \QA should be ready to run: + + \list + \li On Windows, \QA is available as a menu option on the Qt menu. + \li On Mac OS X, \QA is installed in the /Developer/Applications/Qt directory. + \li On Unix/Linux, open a terminal, type \c{assistant} and press \key{Enter}. + \endlist + + When you start up \QA, you will be presented with a standard main window + application, with a menu bar and toolbar. Below these, on the left hand + side are navigation windows called \e{Contents}, \e{Index} and \e{Bookmarks}. + On the right, taking up most of the space, is the \e{Documentation} window. + By default, \QA loads the Qt reference documentation along with the manuals + of other Qt tools, like \QD or \QL. + + \QA works in a similar way to a Web browser. If you click hyperlinks + (cross-references), the \e{Documentation} window will present the relevant + page. You can bookmark pages of particular interest and you can click the + \gui{Previous} and \gui{Next} toolbar buttons to navigate within the pages + you have visited. + + Although \QA can be used just like a Web browser to navigate through + the documentation, \QA offers a powerful means of navigation that Web + browsers do not provide. \QA uses an advanced full text search engine + to index all the pages in each compressed help file so that you can + search for particular words and phrases. + + To perform an index search, click the \gui{Index} tab on the Sidebar + (or press \key{Alt+I}). In the \gui{'Look For'} line edit enter a word; + e.g., 'homedirpath'. As you type, words are found and highlighted in a list + beneath the line edit. If the highlighted text matches what you're + looking for, double click it, (or press \key{Enter}) and the + \e{Documentation} window will display the relevant page. You rarely have + to type in the whole word before \QA finds a match. Note that for some + words there may be more than one possible page that is relevant. + + \QA also provides full text searching for finding specific words in + the documentation. To activate the full text search, either press \key(Alt+S) + or click on the \gui{Search} tab in the \e{Documentation} window. Then + enter the term you're looking for and hit the \gui{Search} button. All + documents containing the specified term will then be listed in the list box + below. +*/ + +/*! + \page assistant-details.html + \title Qt Assistant in More Detail + + \contentspage {Qt Assistant Manual}{Contents} + \previouspage Qt Assistant Manual + \nextpage Using Qt Assistant as a Custom Help Viewer + + \tableofcontents + + \img assistant-assistant.png + + \section1 Command Line Options + + \QA handles the following command line options: + + \table + \header + \li Command Line Option + \li Brief Description + \row + \li -collectionFile + \li Uses the specified collection file instead of the default one. + \row + \li -showUrl + \li Shows the document referenced by URL. + \row + \li -enableRemoteControl + \li Enables \QA to be remotly controlled. + \row + \li -show + \li Shows the specified dockwidget which can be "contents", "index", + "bookmarks" or "search". + \row + \li -hide + \li Hides the specified dockwidget which can be "contents", "index", + "bookmarks" or "search. + \row + \li -activate + \li Activates the specified dockwidget which can be "contents", + "index", "bookmarks" or "search. + \row + \li -register + \li Registers the specified compressed help file in the given help + collection. + \row + \li -unregister + \li Unregisters the specified compressed help file from the given + collection file. + \row + \li -remove-search-index + \li Purges the help search engine's index. This option is + useful in case the associated index files get corrupted. + \QA will re-index the documentation at the next start-up. + \row + \li -rebuild-search-index + \li Rebuilds the help search engine's index. + Note that this operation may take a while to finish. + \row + \li -setCurrentFilter + \li Sets the given filter as the active filter. + \row + \li -quiet + \li Doesn't show any error, warning or success messages. + \endtable + + \section1 Tool Windows + + \img assistant-dockwidgets.png + + The tool windows provide four ways to navigate the documentation: + + \list + \li The \gui{Contents} window presents a table of contents implemented as a + tree view for the documentation that is available. If you click an item, + its documentation will appear in the \e{Documentation} window. If you double + click an item or click on the control to the left of it, the item's sub-items + will appear. Click a sub-item to make its page appear in the \e{Documentation} + window. Click on the control next to an open item to hide its sub-items. + \li The \gui{Index} window is used to look up key words or phrases. + See \l{Qt Assistant Manual#The One-Minute Guide to Using Qt Assistant}{The One-Minute Guide to Using Qt Assistant} for how to use this + window. + \li The \gui{Bookmarks} window lists any bookmarks you have made. Double + click a bookmark to make its page appear in the \e{Documentation} window. + The \gui{Bookmarks} window provides a context menu with \gui{Show Item}, + \gui{Delete Item} as well as \gui{Rename Item}. Click in the main menu + \menu{Bookmark|Add Bookmark...} (or press \key{Ctrl+B}) to bookmark the + page that is currently showing in the \e{Documentation} window. Right click + a bookmark in the list to rename or delete the highlighted bookmark. + \endlist + + If you want the \gui{Documentation} window to use as much space as possible, + you can easily group, move or hide the tool windows. To group the windows, + drag one on top of the other and release the mouse. If one or all tool + windows are not shown, press \key{Alt+C}, \key{Alt+I} or \key{Alt+O} to show + the required window. + + The tool windows can be docked into the main window, so you can drag them + to the top, left, right or bottom of \e{Qt Assistant's} window, or you can + drag them outside \QA to float them as independent windows. + + \section1 Documentation Window + + \img assistant-docwindow.png + + The \gui{Documentation} window lets you create a tab for each + documentation page that you view. Click the \gui{Add Tab} button and a new + tab will appear with the page name as the tab's caption. This makes it + convenient to switch between pages when you are working with different + documentation. You can delete a tab by clicking the \gui{Close Tab} button + located on the right side of the \gui{Documentation} window. + + \section1 Toolbars + + \img assistant-toolbar.png + + The main toolbar provides fast access to the most common actions. + + \table + \header \li Action \li Description \li Menu Item \li Shortcut + \row \li \gui{Previous} \li Takes you to the previous page in the history. + \li \menu{Go|Previous} \li \key{Alt+Left Arrow} + \row \li \gui{Next} \li Takes you to the next page in the history. + \li \menu{Go|Next} \li \key{Alt+Right Arrow} + \row \li \gui{Home} + \li Takes you to the home page as specified in the Preferences Dialog. + \li \menu{Go|Home} \li \key{Ctrl+Home}. + \row \li \gui{Sync with Table of Contents} + \li Synchronizes the \gui{Contents} tool window with the page currently + shown in the \gui{Documentation} window. + \li \menu{Go|Sync with Table of Contents} \li + \row \li \gui{Copy} \li Copies any selected text to the clipboard. + \li \menu{Edit|Copy} \li \key{Ctrl+C} + \row \li \gui{Print} \li Opens the \gui{Print} dialog. + \li \menu{File|Print} \li \key{Ctrl+P} + \row \li \gui{Find in Text} \li Opens the \gui{Find Text} dialog. + \li \menu{Edit|Find in Text} \li \key{Ctrl+F} + \row \li \gui{Zoom in} + \li Increases the font size used to display text in the current tab. + \li \menu{View|Zoom in} \li \key{Ctrl++} + \row \li \gui{Zoom out} + \li Decreases the font size used to display text in the current tab. + \li \menu{View|Zoom out} \li \key{Ctrl+-} + \row \li \gui{Normal Size} + \li Resets the font size to its normal size in the current tab. + \li \menu{View|Normal Size} \li \key{Ctrl+0} + \endtable + + \img assistant-address-toolbar.png + + The address toolbar provides a fast way to enter a specific URL for a + documentation file. By default, the address toolbar is not shown, so it + has to be activated via \menu{View|Toolbars|Address Toolbar}. + + \img assistant-filter-toolbar.png + + The filter toolbar allows you to apply a filter to the currently installed + documentation. As with the address toolbar, the filter toolbar is not visible + by default and has to be activated via \menu{View|Toolbars|Filter Toolbar}. + + \section1 Menus + + \section2 File Menu + + \list + \li \menu{File|Page Setup...} invokes a dialog allowing you to define + page layout properties, such as margin sizes, page orientation and paper size. + \li \menu{File|Print Preview...} provides a preview of the printed pages. + \li \menu{File|Print...} opens the \l{#Print Dialog}{\gui{Print} dialog}. + \li \menu{File|New Tab} opens a new empty tab in the \gui{Documentation} + window. + \li \menu{File|Close Tab} closes the current tab of the + \gui{Documentation} window. + \li \menu{File|Exit} closes the \QA application. + \endlist + + \section2 Edit Menu + + \list + \li \menu{Edit|Copy} copies any selected text to the clipboard. + \li \menu{Edit|Find in Text} invokes the \l{#Find Text Control}{\gui{Find Text} + control} at the lower end of the \gui{Documentation} window. + \li \menu{Edit|Find Next} looks for the next occurance of the specified + text in the \gui{Find Text} control. + \li \menu{Edit|Find Previous} looks for the previous occurance of + the specified text in the \l{#Find Text Control}{\gui{Find Text} control}. + \li \menu{Edit|Preferences} invokes the \l{#Preferences Dialog}{\gui{Preferences} dialog}. + \endlist + + \section2 View Menu + + \list + \li \menu{View|Zoom in} increases the font size in the current tab. + \li \menu{View|Zoom out} decreases the font size in the current tab. + \li \menu{View|Normal Size} resets the font size in the current tab. + \li \menu{View|Contents} toggles the display of the \gui{Contents} tool window. + \li \menu{View|Index} toggles the display of the \gui{Index} tool window. + \li \menu{View|Bookmarks} toggles the display of the \gui{Bookmarks} tool window. + \li \menu{View|Search} toggles the display of the Search in the \gui{Documentation} window. + \endlist + + \section2 Go Menu + + \list + \li \menu{Go|Home} goes to the home page. + \li \menu{Go|Back} displays the previous page in the history. + \li \menu{Go|Forward} displays the next page in the history. + \li \menu{Go|Sync with Table of Contents} syncs the \gui{Contents} tool window to the currently shown page. + \li \menu{Go|Next Page} selects the next tab in the \gui{Documentation} window. + \li \menu{Go|Previous Page} selects the previous tab in the \gui{Documentation} window. + \endlist + + \section2 Bookmarks Menu + + \list + \li \menu{Bookmarks|Add} adds the current page to the list of bookmarks. + \endlist + + \section1 Dialogs + + \section2 Print Dialog + + This dialog is platform-specific. It gives access to various printer + options and can be used to print the document shown in the current tab. + + \section2 Preferences Dialog + + \img assistant-preferences-fonts.png + + The \menu{Fonts} page allows you to change the font family and font sizes of the + browser window displaying the documentation or the application itself. + + \img assistant-preferences-filters.png + + The \menu{Filters} page lets you create and remove documentation + filters. To add a new filter, click the \gui{Add} button, specify a + filter name in the pop-up dialog and click \gui{OK}, then select + the filter attributes in the list box on the right hand side. + You can delete a filter by selecting it and clicking the \gui{Remove} + button. + + \img assistant-preferences-documentation.png + + The \menu{Documentation} page lets you install and remove compressed help + files. Click the \gui{Install} button and choose the path of the compressed + help file (*.qch) you would like to install. + To delete a help file, select a documentation set in the list and click + \gui{Remove}. + + \img assistant-preferences-options.png + + The \menu{Options} page lets you specify the homepage \QA will display when + you click the \gui{Home} button in \QA's main user interface. You can specify + the homepage by typing it here or clicking on one of the buttons below the + textbox. \gui{Current Page} sets the currently displayed page as your home + page while \gui{Restore to default} will reset your home page to the default + home page. + + \section1 Find Text Control + + This control is used to find text in the current page. Enter the text you want + to find in the line edit. The search is incremental, meaning that the most + relevant result is shown as you enter characters into the line edit. + + If you check the \gui{Whole words only} checkbox, the search will only consider + whole words; for example, if you search for "spin" with this checkbox checked it will + not match "spinbox", but will match "spin". If you check the \gui{Case sensitive} + checkbox then, for example, "spin" will match "spin" but not "Spin". You can + search forwards or backwards from your current position in the page by clicking + the \gui{Previous} or \gui{Next} buttons. To hide the find control, either click the + \gui{Close} button or hit the \key{Esc} key. + + \section1 Filtering Help Contents + + \QA allows you to install any kind of documentation as long as it is organized + in Qt compressed help files (*.qch). For example, it is possible to install the + Qt reference documentation for Qt 4.4.0 and Qt 4.4.1 at the same time. In many + respects, this is very convenient since only one version of \QA is needed. + However, at the same time it becomes more complicated when performing tasks like + searching the index because nearly every keyword is defined in Qt 4.4.0 as well + as in Qt 4.4.1. This means that \QA will always ask the user to choose which one + should be displayed. + + We use documentation filters to solve this issue. A filter is identified by its + name, and contains a list of filter attributes. An attribute is just a string and + can be freely chosen. Attributes are defined by the documentation itself, this + means that every documentation set usually has one or more attributes. + + For example, the Qt 4.4.0 \QA documentation defines the attributes \c {assistant}, + \c{tools} and \c{4.4.0}, \QD defines \c{designer}, \c{tools} and \c{4.4.0}. + The filter to display all tools would then define only the attribute + \c{tools} since this attribute is part of both documentation sets. + Adding the attribute \c{assistant} to the filter would then only show \QA + documentation since the \QD documentation does not contain this + attribute. Having an empty list of attributes in a filter will match all + documentation; i.e., it is equivalent to requesting unfiltered documentation. + + \section1 Full Text Searching + + \img assistant-search.png + + \QA provides a powerful full text search engine. To search + for certain words or text, click the \gui{Search} tab in the \gui{Documentation} + window. Then enter the text you want to look for and press \key{Enter} + or click the \gui{Search} button. The search is not case sensitive, so, + for example, Foo, fOo and FOO are all treated as the same. The following are + examples of common search patterns: + + \list + \li \c deep -- lists all the documents that contain the word 'deep' + \li \c{deep*} -- lists all the documents that contain a word beginning + with 'deep' + \li \c{deep copy} -- lists all documents that contain both 'deep' \e + and 'copy' + \li \c{"deep copy"} -- list all documents that contain the phrase 'deep copy' + \endlist + + It is also possible to use the \gui{Advanced search} to get more flexibility. + You can specify some words so that hits containing these are excluded from the + result, or you can search for an exact phrase. Searching for similar words will + give results like these: + + \list + \li \c{QStin} -- lists all the documents with titles that are similar, such as \c{QString} + \li \c{QSting} -- lists all the documents with titles that are similar, such as \c{QString} + \li \c{QStrin} -- lists all the documents with titles that are similar, such as \c{QString} + \endlist + + Options can be combined to improve the search results. + + The list of documents found is ordered according to the number of + occurrences of the search text which they contain, with those containing + the highest number of occurrences appearing first. Simply click any + document in the list to display it in the \gui{Documentation} window. + + If the documentation has changed \mdash for example, if documents have been added + or removed \mdash \QA will index them again. + +*/ + +/*! + \page assistant-custom-help-viewer.html + \title Using Qt Assistant as a Custom Help Viewer + + \contentspage {Qt Assistant Manual}{Contents} + \previouspage Qt Assistant in More Detail + + Using \QA as custom help viewer requires more than just being able to + display custom documentation. It is equally important that the + appearance of \QA can be customized so that it is seen as a + application-specific help viewer rather than \QA. This is achieved by + changing the window title or icon, as well as some application-specific + menu texts and actions. The complete list of possible customizations + can be found in the \l{Creating a Custom Help Collection File} section. + + Another requirement of a custom help viewer is the ability to receive + actions or commands from the application it provides help for. This is + especially important when the application offers context sensitive help. + When used in this way, the help viewer may need to change its contents + depending on the state the application is currently in. This means that + the application has to communicate the current state to the help viewer. + The section about \l{Using Qt Assistant Remotely} explains how this can + be done. + + \tableofcontents + + The \l{Simple Text Viewer Example}{Simple Text Viewer} example uses the + techniques described in this document to show how to use \QA as a custom + help viewer for an application. + + \warning In order to ship Qt Assistant in your application, it is crucial + that you include the sqlite plugin. For more information on how to include + plugins in your application, refer to the \l{Deploying Qt Applications} + {deployment documentation}. + + \section1 Qt Help Collection Files + + The first important point to know about \QA is that it stores all + settings related to its appearance \e and a list of installed + documentation in a help collection file. This means, when starting \QA + with different collection files, \QA may look totally different. This + complete separation of settings makes it possible to deploy \QA as a + custom help viewer for more than one application on one machine + without risk of interference between different instances of \QA. + + To apply a certain help collection to \QA, specify the respective + collection file on the command line when starting it. For example: + + \snippet doc_src_assistant-manual.qdoc 8 + + However, storing all settings in one collection file raises some problems. + The collection file is usually installed in the same directory as the + application itself, or one of its subdirectories. Depending on the + directory and the operating system, the user may not have any permissions + to modify this file which would happen when the user settings are stored. + Also, it may not even be possible to give the user write permissions; + e.g., when the file is located on a read-only medium like a CD-ROM. + + Even if it is possible to give everybody the right to store their settings + in a globally available collection file, the settings from one user would + be overwritten by another user when exiting \QA. + + To solve this dilemma, \QA creates user specific collection files which + are more or less copied from the original collection file. The user-specific + collection file will be saved in a subdirectory of the path returned by + QDesktopServices::DataLocation. The subdirectory, or \e{cache directory} + within this user-specific location, can be defined in the help collection + project file. For example: + + \snippet doc_src_assistant-manual.qdoc 7 + + So, when calling + + \snippet doc_src_assistant-manual.qdoc 8 + + \QA actually uses the collection file: + + \snippet doc_src_assistant-manual.qdoc 9 + + There is no need ever to start \QA with the user specific collection + file. Instead, the collection file shipped with the application should + always be used. Also, when adding or removing documentation from the + collection file (see next section) always use the normal collection file. + \QA will take care of synchronizing the user collection files when the + list of installed documentation has changed. + + \section1 Displaying Custom Documentation + + Before \QA is able to show documentation, it has to know where it can + find the actual documentation files, meaning that it has to know the + location of the Qt compressed help file (*.qch). As already mentioned, + \QA stores references to the compressed help files in the currently used + collection file. So, when creating a new collection file you can list + all compressed help files \QA should display. + + \snippet doc_src_assistant-manual.qdoc 5 + + Sometimes, depending on the application for which \QA acts as a + help viewer, more documentation needs to be added over time; for + example, when installing more application components or plugins. + This can be done manually by starting \QA, opening the \gui{Edit|Preferences} + dialog and navigating to the \gui{Documentation} tab page. Then click + the \gui{Add...} button, select a Qt compressed help file (*.qch) + and press \gui{Open}. However, this approach has the disadvantage + that every user has to do it manually to get access to the new + documentation. + + The prefered way of adding documentation to an already existing collection + file is to use the \c{-register} command line flag of \QA. When starting + \QA with this flag, the documentation will be added and \QA will + exit right away displaying a message if the registration was successful + or not. + + \snippet doc_src_assistant-manual.qdoc 6 + + The \c{-quiet} flag can be passed on to \QA to prevent it from writing + out the status message. + + \b{Note:} \QA will show the documentation in the contents view in the same + order as it was registered. + + + \section1 Changing the Appearance of Qt Assistant + + The appearance of \QA can be changed by passing different command line options + on startup. However, these command line options only allow to show or hide + specific widgets, like the contents or index view. Other customizations, such + as changing the application title or icon, or disabling the filter functionality, + can be done by creating a custom help collection file. + + \section2 Creating a Custom Help Collection File + + The help collection file (*.qhc) used by \QA is created when running the + \c qcollectiongenerator tool on a help collection project file (*.qhcp). + The project file format is XML and supports the following tags: + + \table + \header + \li Tag + \li Brief Description + \row + \li \c{} + \li This property is used to specify a window title for \QA. + \row + \li \c{<homePage>} + \li This tag specifies which page should be display when + pressing the home button in \QA's main user interface. + \row + \li \c{<startPage>} + \li This tag specifies which page \QA should initially + display when the help collection is used. + \row + \li \c{<currentFilter>} + \li This tag specifies the \l{Qt Assistant in More Detail#Preferences Dialog}{filter} + that is initially used. + If this filter is not specified, the documentation will not be filtered. This has + no impact if only one documentation set is installed. + \row + \li \c{<applicationIcon>} + \li This tag describes an icon that will be used instead of the normal \QA + application icon. This is specified as a relative path from the directory + containing the collection file. + \row + \li \c{<enableFilterFunctionality>} + \li This tag is used to enable or disable user accessible filter functionality, + making it possible to prevent the user from changing any filter when running \QA. + It does not mean that the internal filter functionality is completely disabled. + Set the value to \c{false} if you want to disable the filtering. If the filter + toolbar should be shown by default, set the attribute \c{visible} to \c{true}. + \row + \li \c{<enableDocumentationManager>} + \li This tag is used to specify whether the documentation manager should be shown + in the preferences dialog. Disabling the Documentation Manager allows you to limit + \QA to display a specific documentation set or make it impossible for the end user + to accidentally remove or install documentation. To hide the documentation manager, + set the tag value to \c{false}. + \row + \li \c{<enableAddressBar>} + \li This tag describes if the address bar can be shown. By default it is + enabled; if you want to disable it set the tag value to \c{false}. If the + address bar functionality is enabled, the address bar can be shown by setting the + tag attribute \c{visible} to \c{true}. + \row + \li \c{<aboutMenuText>, <text>} + \li The \c{aboutMenuText} tag lists texts for different languages which will + later appear in the \menu{Help} menu; e.g., "About Application". A text is + specified within the \c{text} tags; the \c{language} attribute takes the two + letter language name. The text is used as the default text if no language + attribute is specified. + \row + \li \c{<aboutDialog>, <file>, <icon>} + \li The \c{aboutDialog} tag can be used to specify the text for the \gui{About} + dialog that can be opened from the \menu{Help} menu. The text is taken from the + file in the \c{file} tags. It is possible to specify a different file or any + language. The icon defined by the \c{icon} tags is applied to any language. + \row + \li \c{<cacheDirectory base="collection|default">} + \li The cache directory is used to store index files + needed for the full text search and a copy of the collection file. + The copy is needed because \QA stores all its settings in the collection file; i.e., it must be writable for the user. + The directory is specified as a relative path. + If the \c{base} attribute is set to "collection", the path is + relative to the directory the collection file resides in. + If the attribute is set to "default" or if it is missing, + the path is relative to the directory given by + QDesktopServices::DataLocation. The first form is useful for + collections that are used in a "mobile" way, e.g. carried around + on a USB stick. + \row + \li \c{<enableFullTextSearchFallback>} + \li This tag describes the ability to fallback and use the full text + search if a keyword can't be found in the index. This functionality + can be used while remote controlling \QA. To make it available for + remote control set the tag value to \c{true}. + \endtable + + In addition to those \QA specific tags, the tags for generating and registering + documentation can be used. See \l{Qt Help Collection Project} documentation for more information. + + An example of a help collection file that uses all the available tags is shown below: + + \snippet doc_src_assistant-manual.qdoc 1 + + To create the binary collection file, run the \c qcollectiongenerator tool: + + \snippet doc_src_assistant-manual.qdoc 10 + + To test the generated collection file, start \QA in the following way: + + \snippet doc_src_assistant-manual.qdoc 8 + + \section1 Using Qt Assistant Remotely + + Even though the help viewer is a standalone application, it will mostly + be launched by the application it provides help for. This approach + gives the application the possibility to ask for specific help contents + to be displayed as soon as the help viewer is started. Another advantage + with this approach is that the application can communicate with the + help viewer process and can therefore request other help contents to be + shown depending on the current state of the application. + + So, to use \QA as the custom help viewer of your application, simply + create a QProcess and specify the path to the Assistant executable. In order + to make Assistant listen to your application, turn on its remote control + functionality by passing the \c{-enableRemoteControl} command line option. + + The following example shows how this can be done: + + \snippet doc_src_assistant-manual.qdoc 2 + + Once \QA is running, you can send commands by using the stdin channel of + the process. The code snippet below shows how to tell \QA to show a certain + page in the documentation. + + \snippet doc_src_assistant-manual.qdoc 3 + + Note that the trailing newline character is required to mark the end + of the input. + + The following commands can be used to control \QA: + + \table + \header + \li Command + \li Brief Description + \row + \li \c{show <Widget>} + \li Shows the dock widget specified by <Widget>. If the widget + is already shown and this command is sent again, the widget will be + activated, meaning that it will be raised and given the input focus. + Possible values for <Widget> are "contents", "index", "bookmarks" or "search". + \row + \li \c{hide <Widget>} + \li Hides the dock widget specified by <Widget>. Possible values for + <Widget> are "contents", "index", "bookmarks" and "search". + \row + \li \c{setSource <Url>} + \li Displays the given <Url>. The URL can be absolute or relative + to the currently displayed page. If the URL is absolute, it has to + be a valid Qt help system URL; i.e., starting with "qthelp://". + \row + \li \c{activateKeyword <Keyword>} + \li Inserts the specified <Keyword> into the line edit of the + index dock widget and activates the corresponding item in the + index list. If such an item has more than one link associated + with it, a topic chooser will be shown. + \row + \li \c{activateIdentifier <Id>} + \li Displays the help contents for the given <Id>. An ID is unique + in each namespace and has only one link associated to it, so the + topic chooser will never pop up. + \row + \li \c{syncContents} + \li Selects the item in the contents widget which corresponds to + the currently displayed page. + \row + \li \c{setCurrentFilter <filter>} + \li Selects the specified filter and updates the visual representation + accordingly. + \row + \li \c{expandToc <Depth>} + \li Expands the table of contents tree to the given depth. If depth + is 0, the tree will be collapsed completely. If depth is -1, + the tree will be expanded completely. + \row + \li \c{register <help file>} + \li Adds the given Qt compressed help file to the collection. + \row + \li \c{unregister <help file>} + \li Removes the given Qt compressed help file from the collection. + \endtable + + If you want to send several commands within a short period of time, it is + recommended that you write only a single line to the stdin of the process + instead of one line for every command. The commands have to be separated by + a semicolon, as shown in the following example: + + \snippet doc_src_assistant-manual.qdoc 4 + + \section1 Compatibility with Old Formats + + In older versions of Qt, the help system was based on Document Content File + (DCF) and Qt Assistant Documentation Profile (ADP) formats. In contrast, + Qt Assistant and the help system used in Qt 4.4 use the formats described + earlier in this manual. + + Unfortunately, the old file formats are not compatible with the new ones. + In general, the differences are not that big \mdash in most cases is the old + format is just a subset of the new one. One example is the \c namespace tag in + the Qt Help Project format, which was not part of the old format, but plays a vital + role in the new one. To help you to move to the new file format, we have created + a conversion wizard. + + The wizard is started by executing \c qhelpconverter. It guides you through the + conversion of different parts of the file and generates a new \c qch or \c qhcp + file. + + Once the wizard is finished and the files created, run the \c qhelpgenerator + or the \c qcollectiongenerator tool to generate the binary help files used by \QA. +*/ + +/* +\section2 Modifying \QA with Command Line Options + + Different help collections can be shown by simply passing the help collection + path to \QA. For example: + + \snippet doc_src_assistant-manual.qdoc 0 + + Other available options the can be passed on the command line. + + \table + \header + \li Command Line Option + \li Brief Description + \row + \li -collectionFile <file.qhc> + \li Uses the specified collection file instead of the default one. + \row + \li -showUrl URL + \li Shows the document referenced by URL. + \row + \li -enableRemoteControl + \li Enables \QA to be remotly controlled. + \row + \li -show <widget> + \li Shows the specified dockwidget which can be "contents", "index", + "bookmarks" or "search". + \row + \li -hide <widget> + \li Hides the specified dockwidget which can be "contents", "index", + "bookmarks" or "search. + \row + \li -activate <widget> + \li Activates the specified dockwidget which can be "contents", + "index", "bookmarks" or "search. + \row + \li -register <doc.qch> + \li Registers the specified compressed help file in the given help + collection. + \row + \li -unregister <doc.qch> + \li Unregisters the specified compressed help file from the given + collection file. + \row + \li -quiet + \li Doesn't show any error, warning or success messages. + \endtable + */