|
|
|
|
\chapter Introduction
|
|
|
|
|
|
|
|
|
|
This document introduces \QA, a tool for presenting on-line
|
|
|
|
|
documentation. It also introduces the Qt Reference Documentation which
|
|
|
|
|
is accessible using \QA, or with a web browser. The document is
|
|
|
|
|
divided into the following sections:
|
|
|
|
|
|
|
|
|
|
\list
|
|
|
|
|
\i Introduction to the Qt Reference Documentation
|
|
|
|
|
\i The 1 Minute Guide to using Qt Assistant
|
|
|
|
|
\i Qt Assistant in More Detail
|
|
|
|
|
\i Full Text Searching
|
|
|
|
|
\i Customizing Qt Assistant
|
|
|
|
|
\endlist
|
|
|
|
|
|
|
|
|
|
\chapter Introduction to the Qt Reference Documentation
|
|
|
|
|
|
|
|
|
|
The documentation for the Qt library is written in-line in the \File
|
|
|
|
|
.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
|
|
|
|
|
|
|
|
|
|
\i The \link classes.html All Classes\endlink page lists every class
|
|
|
|
|
in Qt's public API, and consists of several hundred classes.
|
|
|
|
|
|
|
|
|
|
\i The \link mainclasses.html Main Classes\endlink 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.
|
|
|
|
|
|
|
|
|
|
\i The \link groups.html Grouped Classes\endlink page presents a list
|
|
|
|
|
of groups, each of which leads to a list of related classes, for
|
|
|
|
|
example, the \link advanced.html Advanced Widgets\endlink list.
|
|
|
|
|
|
|
|
|
|
\i The \link hierarchy.html Inheritance Hierarchy\endlink page
|
|
|
|
|
presents a list of classes in terms of the hierarchy of Qt classes.
|
|
|
|
|
|
|
|
|
|
\i The \link functions.html All Functions\endlink 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 The 1 Minute Guide to Using Qt Assistant
|
|
|
|
|
|
|
|
|
|
Under Windows, \QA is available as a menu option on the Qt menu. On
|
|
|
|
|
Unix, run \c{assistant} from an xterm.
|
|
|
|
|
|
|
|
|
|
When you start up \QA, you will be presented with a standard
|
|
|
|
|
main-window style application, with a menu bar and toolbar. Below
|
|
|
|
|
these, on the left hand side is a navigation window called the \e
|
|
|
|
|
Sidebar, and on the right, taking up most of the space, is the
|
|
|
|
|
documentation window. By default, the Qt Reference Documentation's home
|
|
|
|
|
page is shown in the documentation window.
|
|
|
|
|
|
|
|
|
|
\QA works in a similar way to a web browser. If you click underlined
|
|
|
|
|
text (which signifies a cross-reference), the documentation window will
|
|
|
|
|
present the relevant page. You can bookmark pages of particular
|
|
|
|
|
interest and you can click the \Toolbutton Previous and \Toolbutton
|
|
|
|
|
Next toolbar buttons to navigate within the pages you've visited.
|
|
|
|
|
|
|
|
|
|
Although \QA can be used just like a web browser to navigate through
|
|
|
|
|
the Qt documentation set, \QA offers a powerful means of navigation
|
|
|
|
|
that web browsers don't provide. \QA uses an intelligent algorithm to
|
|
|
|
|
index all the pages in the documentation sets that it presents so that
|
|
|
|
|
you can search for particular words and phrases.
|
|
|
|
|
|
|
|
|
|
To perform an index search, click the \Toolbutton Index tab on the Sidebar
|
|
|
|
|
(or click \Key Ctrl+I). In the '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
|
|
|
|
|
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. Documents with the highest occurrences of the word
|
|
|
|
|
that you are looking for appear first, and every occurrence of the
|
|
|
|
|
word within the documentation is highlighted.
|
|
|
|
|
|
|
|
|
|
\omit
|
|
|
|
|
For example, enter 'setenabled' in the 'Look For' line edit.
|
|
|
|
|
As you type, words are found and highlighted in the list beneath the
|
|
|
|
|
line edit, as before. Once the highlighted text matches what you're
|
|
|
|
|
looking for, double click it, (or press \Key Enter). In the case of
|
|
|
|
|
setEnabled, it is a function name which occurs in several classes, so
|
|
|
|
|
a dialog pops up listing the possible choices. Click the choice you're
|
|
|
|
|
interested in (or move to it using the \Key Up and \Key Down arrow
|
|
|
|
|
keys and press \Key Enter). The relevant page will display in the
|
|
|
|
|
documentation window.
|
|
|
|
|
\endomit
|
|
|
|
|
|
|
|
|
|
\QA can be customized by creating profiles, a collection of
|
|
|
|
|
documentation. Profiles can be created for your own use, or for an
|
|
|
|
|
application you will distribute. With profiles, you can select which
|
|
|
|
|
documentation you want the end user of your application to be able to
|
|
|
|
|
view.
|
|
|
|
|
|
|
|
|
|
\chapter Qt Assistant in More Detail
|
|
|
|
|
|
|
|
|
|
\img assistant.png
|
|
|
|
|
\caption Qt Assistant
|
|
|
|
|
|
|
|
|
|
\section1 The Sidebar
|
|
|
|
|
|
|
|
|
|
\img sidebar.png
|
|
|
|
|
|
|
|
|
|
The sidebar provides four ways of navigating documentation:
|
|
|
|
|
\list 1
|
|
|
|
|
\i The \Toolbutton Contents tab presents a tree view of the
|
|
|
|
|
documentation sets that are available. If you click an item, its
|
|
|
|
|
documentation will appear in the documentation window. If you double
|
|
|
|
|
click an item or click a '+' sign to the left of an item, the item's
|
|
|
|
|
sub-items will appear. Click a sub-item to make its page appear in the
|
|
|
|
|
documentation window. Click a '-' sign to the left of an item to hide
|
|
|
|
|
its sub-items.
|
|
|
|
|
\i The \Toolbutton Index tab is used to look up key words or phrases.
|
|
|
|
|
See \l{The 1 Minute Guide to using Qt Assistant} for how to use this
|
|
|
|
|
tab.
|
|
|
|
|
\i The \Toolbutton Bookmarks tab lists any bookmarks you've made.
|
|
|
|
|
Double click a bookmark to make its page appear in the documentation
|
|
|
|
|
window. The \Toolbutton Bookmarks tab has a \Button{New Bookmark}
|
|
|
|
|
button and a \Button{Delete Bookmark} button at the bottom. Click
|
|
|
|
|
\Button{New Bookmark} to bookmark the page that is showing in the
|
|
|
|
|
documentation window. Click a bookmark in the list, then click
|
|
|
|
|
\Button{Delete Bookmark} to delete the highlighted bookmark.
|
|
|
|
|
\i The \Toolbutton Search tab provides full text search of \e all
|
|
|
|
|
the documents. See \l{Full Text Searching} for more information about
|
|
|
|
|
this feature.
|
|
|
|
|
\endlist
|
|
|
|
|
|
|
|
|
|
If you want the documentation window to use as much space as possible,
|
|
|
|
|
you can easily hide or show the Sidebar. If the Sidebar is showing,
|
|
|
|
|
press \Key Ctrl+T, \Key Ctrl+I, \Key Ctrl+B or \Key Ctrl+S to hide it.
|
|
|
|
|
If the Sidebar is hidden, press \Key Ctrl+T to show it on the Contents
|
|
|
|
|
tab, or press \Key Ctrl+I to show it on the Index tab (with the focus
|
|
|
|
|
in the 'Look For' line edit box), or press \Key Ctrl+B to show it on
|
|
|
|
|
the Bookmarks tab, or press \Key Ctrl+S to show it on the (full text)
|
|
|
|
|
Search tab.
|
|
|
|
|
|
|
|
|
|
The Sidebar is a dock window, so you can drag it to the top, left,
|
|
|
|
|
right or bottom of \QA's window, or you can drag it outside \QA to
|
|
|
|
|
float it.
|
|
|
|
|
|
|
|
|
|
\section1 The Documentation Window
|
|
|
|
|
|
|
|
|
|
\img docwindow.png
|
|
|
|
|
|
|
|
|
|
The documentation window offers a feature for viewing documentation by
|
|
|
|
|
enabling you to create tabs for each documentation page that you view.
|
|
|
|
|
Click the \Button {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 \Button {Close Tab} button located
|
|
|
|
|
on the right side of the documentation window.
|
|
|
|
|
|
|
|
|
|
\section1 The Toolbar
|
|
|
|
|
|
|
|
|
|
\img toolbar1.png
|
|
|
|
|
|
|
|
|
|
The toolbar provides fast access to the most common actions.
|
|
|
|
|
\list
|
|
|
|
|
\i \Toolbutton Previous takes you to the previous page. The menu
|
|
|
|
|
option is \Menu Go|Previous and the keyboard shortcut is \Key{Alt+Left
|
|
|
|
|
Arrow}.
|
|
|
|
|
\i \Toolbutton Next takes you to the next page. The menu
|
|
|
|
|
option is \Menu Go|Next and the keyboard shortcut is \Key{Alt+Right
|
|
|
|
|
Arrow}.
|
|
|
|
|
\i \Toolbutton Home takes you to the home page (normally the home page
|
|
|
|
|
of the Qt Reference Documentation). The menu
|
|
|
|
|
option is \Menu Go|Home and the keyboard shortcut is \Key{Ctrl+Home}.
|
|
|
|
|
\i \Toolbutton Copy copies any selected text to the clipboard. The menu
|
|
|
|
|
option is \Menu Edit|Copy and the keyboard shortcut is \Key{Ctrl+C}.
|
|
|
|
|
\i \Toolbutton{Find in Text} invokes the \Dialog{Find Text} dialog. The menu
|
|
|
|
|
option is \Menu{Edit|Find in Text} and the keyboard shortcut is \Key{Ctrl+F}.
|
|
|
|
|
\i \Toolbutton{Print} invokes the \Dialog{Print} dialog. The menu
|
|
|
|
|
option is \Menu{File|Print} and the keyboard shortcut is \Key{Ctrl+P}.
|
|
|
|
|
\i \Toolbutton{Zoom in} increases the font size. The menu
|
|
|
|
|
option is \Menu{View|Zoom in} and the keyboard shortcut is \Key{Ctrl++}.
|
|
|
|
|
\i \Toolbutton{Zoom out} decreases the font size. The menu
|
|
|
|
|
option is \Menu{View|Zoom out} and the keyboard shortcut is \Key{Ctrl+-}.
|
|
|
|
|
\i \Toolbutton{What's This?} provides a description of a \QA feature.
|
|
|
|
|
The menu option is \Menu{Help|What's This?} and the keyboard shortcut
|
|
|
|
|
is \Key{Shift+F1}.
|
|
|
|
|
\endlist
|
|
|
|
|
|
|
|
|
|
The remaining toolbar buttons are bookmarks and will vary depending on
|
|
|
|
|
your configuration.
|
|
|
|
|
|
|
|
|
|
\section1 The Menus
|
|
|
|
|
|
|
|
|
|
\section2 The File Menu
|
|
|
|
|
|
|
|
|
|
\list
|
|
|
|
|
\i \Menu{File|Print} invokes the \Dialog{Print} dialog.
|
|
|
|
|
\i \Menu{File|Exit} terminates \QA.
|
|
|
|
|
\endlist
|
|
|
|
|
|
|
|
|
|
\section2 The Edit Menu
|
|
|
|
|
|
|
|
|
|
\list
|
|
|
|
|
\i \Menu{Edit|Copy} copies any selected text to the clipboard.
|
|
|
|
|
\i \Menu{Edit|Find in Text} invokes the \Dialog{Find Text} dialog.
|
|
|
|
|
\i \Menu{Edit|Settings} invokes the \Dialog{Settings} dialog.
|
|
|
|
|
\endlist
|
|
|
|
|
|
|
|
|
|
\section2 The View Menu
|
|
|
|
|
|
|
|
|
|
\list
|
|
|
|
|
\i \Menu{View|Zoom in} increases the font size.
|
|
|
|
|
\i \Menu{View|Zoom out} decreases the font size.
|
|
|
|
|
\i \Menu{View|Views|Sidebar} toggles the display of the Sidebar.
|
|
|
|
|
\i \Menu{View|Views|Toolbar} toggles the display of the Toolbar.
|
|
|
|
|
\i \Menu{View|Views|Line up} lines up the toolbar buttons in the
|
|
|
|
|
Toolbar.
|
|
|
|
|
\endlist
|
|
|
|
|
|
|
|
|
|
\section2 The Go Menu
|
|
|
|
|
|
|
|
|
|
\list
|
|
|
|
|
\i \Menu{Go|Previous} displays the previous page.
|
|
|
|
|
\i \Menu{Go|Next} displays the next page.
|
|
|
|
|
\i \Menu{Go|home} goes to the home page.
|
|
|
|
|
\endlist
|
|
|
|
|
This menu also has additional items; these are pre-defined bookmarks
|
|
|
|
|
that vary depending on your configuration.
|
|
|
|
|
|
|
|
|
|
\section2 The Bookmarks Menu
|
|
|
|
|
|
|
|
|
|
\list
|
|
|
|
|
\i \Menu{Bookmarks|Add} adds the current page to the list of bookmarks.
|
|
|
|
|
\endlist
|
|
|
|
|
This menu may have additional items, i.e. any bookmarks that you have
|
|
|
|
|
already made. If you want to delete a bookmark go to the Bookmarks tab
|
|
|
|
|
on the Sidebar.
|
|
|
|
|
|
|
|
|
|
\section1 The Dialogs
|
|
|
|
|
|
|
|
|
|
\section2 The Print Dialog
|
|
|
|
|
|
|
|
|
|
This dialog is platform-specific. It gives access to various printer
|
|
|
|
|
options and can be used to print the current page.
|
|
|
|
|
|
|
|
|
|
\section2 The Find Text Dialog
|
|
|
|
|
|
|
|
|
|
This dialog is used to find text in the current page. Enter the text
|
|
|
|
|
you want to find in the Find line edit. If you check the 'Whole words
|
|
|
|
|
only' checkbox, the search will only consider whole words, i.e. if you
|
|
|
|
|
search for 'spin' with this checkbox checked it will not match
|
|
|
|
|
'spinbox', but will match 'spin'. If you check the 'Case sensitive'
|
|
|
|
|
check box then, for example, 'spin' will match 'spin' but not 'Spin'.
|
|
|
|
|
You can search Forward or Backward from your current position in the
|
|
|
|
|
page by clicking one of the Direction radio buttons. Click the \Button
|
|
|
|
|
Find button to search (or search again), and click the \Button Close
|
|
|
|
|
button to finish.
|
|
|
|
|
|
|
|
|
|
\section2 The Settings Dialog
|
|
|
|
|
|
|
|
|
|
The Settings dialog is used to set your preferences for \QA. The
|
|
|
|
|
dialog has four tabs: General Settings, Web Settings, PDF Settings,
|
|
|
|
|
and Profiles. \QA will remember your settings between sessions,
|
|
|
|
|
including window sizes and positions, and which pages you have open.
|
|
|
|
|
Each of the tabs is discussed as follows:
|
|
|
|
|
|
|
|
|
|
\list
|
|
|
|
|
\i General Settings
|
|
|
|
|
|
|
|
|
|
\img general.png
|
|
|
|
|
|
|
|
|
|
To change the base font used throughout \QA, select a
|
|
|
|
|
font type from the Font combobox. To choose a new fixed-width
|
|
|
|
|
font, for example, to show code snippets, choose a font type from
|
|
|
|
|
the 'Fixed font' combobox. To change the color of hypertext
|
|
|
|
|
links, click the 'Link color' color button. Uncheck the
|
|
|
|
|
'Underline links' checkbox if you don't want underlined links.
|
|
|
|
|
|
|
|
|
|
\i Web Settings
|
|
|
|
|
|
|
|
|
|
\img web.png
|
|
|
|
|
|
|
|
|
|
Some pages contain links to external web pages. In order to display
|
|
|
|
|
these links, you must specify a web browser. Type the name of your
|
|
|
|
|
browser's executable in the Web Browser Application line edit.
|
|
|
|
|
Alternatively, click the \Button {(ellipsis)} button to invoke the
|
|
|
|
|
\Widget {Set Web Browser} dialog and navigate until you find the web
|
|
|
|
|
browser you want to use. Click \Button {Save} to accept the selection.
|
|
|
|
|
|
|
|
|
|
To change \QA's default home page, enter the file name in the Home
|
|
|
|
|
Page line edit. Alternatively, click the \Button {(ellipsis)} button
|
|
|
|
|
to invoke the \Widget {Set Homepage} dialog. Navigate until you find
|
|
|
|
|
the home page file you want to use and then click \Button {Save} to
|
|
|
|
|
accept the selection.
|
|
|
|
|
|
|
|
|
|
\i PDF Settings
|
|
|
|
|
|
|
|
|
|
\img pdf1.png
|
|
|
|
|
|
|
|
|
|
Some pages contain links to PDF documents. In order to display these
|
|
|
|
|
links, you must specify a PDF viewer. Type in the name of your PDF viewer's
|
|
|
|
|
executable in the line edit. Alternatively, click the \Button {(ellipsis)}
|
|
|
|
|
button to invoke the \Widget {Set PDF Browser} dialog and navigate
|
|
|
|
|
until you find the PDF viewer you want to use. Click \Button Save to
|
|
|
|
|
accept the selection.
|
|
|
|
|
|
|
|
|
|
\chapter Full Text Searching
|
|
|
|
|
|
|
|
|
|
\img search.png
|
|
|
|
|
|
|
|
|
|
\QA provides a powerful full text search engine. To search
|
|
|
|
|
for certain words or text, click the 'Search' tab in the sidebar. Then
|
|
|
|
|
enter the text you want to look for and press \Key Enter or click
|
|
|
|
|
\Button Search. The search is not case sensitive, so Foo, fOo and
|
|
|
|
|
FOO are all treated as the same. The following are examples of common search
|
|
|
|
|
patterns:
|
|
|
|
|
|
|
|
|
|
\list
|
|
|
|
|
\i \c deep -- lists all the documents that contain the word 'deep'
|
|
|
|
|
|
|
|
|
|
\i \c{deep*} -- lists all the documents that contain a word beginning
|
|
|
|
|
with 'deep'
|
|
|
|
|
|
|
|
|
|
\i \c{deep copy} -- lists all documents that contain both 'deep' \e
|
|
|
|
|
and 'copy'
|
|
|
|
|
|
|
|
|
|
\i \c{"deep copy"} -- list all documents that contain the phrase 'deep copy'
|
|
|
|
|
\endlist
|
|
|
|
|
|
|
|
|
|
The wildcard (*) character cannot be used within quotes.
|
|
|
|
|
|
|
|
|
|
The list of documents found is ordered according to the number of
|
|
|
|
|
occurrences of the search text they contain, therefore those with the
|
|
|
|
|
highest number of occurrences appearing first. Simply click any
|
|
|
|
|
document in the list to display it in the document window.
|
|
|
|
|
|
|
|
|
|
If the documentation has changed, i.e. if documents have been added or
|
|
|
|
|
removed, \QA will reindex.
|
|
|
|
|
|
|
|
|
|
\chapter Customizing Qt Assistant
|
|
|
|
|
|
|
|
|
|
\QA can be customized by adding and removing documentation from its
|
|
|
|
|
documentation set. In addition, \QA introduces the profiles option,
|
|
|
|
|
which enables its properties to change, for example, the default
|
|
|
|
|
startup page, and application icon.
|
|
|
|
|
|
|
|
|
|
\section1 Modifying the Default Documentation Set
|
|
|
|
|
|
|
|
|
|
When it is 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 \QD and qmake.
|
|
|
|
|
|
|
|
|
|
Documentation can be added or removed from \QA by
|
|
|
|
|
adding and removing the content files. The format of the content files are
|
|
|
|
|
specified below. To add a content file, type the following command line
|
|
|
|
|
option: \c{-addContentFile docfile}. To remove a content file from the
|
|
|
|
|
default set, type the following command line option:
|
|
|
|
|
\c{-removeContentFile docfile}. For example:
|
|
|
|
|
|
|
|
|
|
\code
|
|
|
|
|
1: > assistant -addContentFile file.dcf
|
|
|
|
|
2: > assistant
|
|
|
|
|
3: > assistant -removeContentFile file.dcf
|
|
|
|
|
\endcode
|
|
|
|
|
|
|
|
|
|
In line one, we add the content file \c file.dcf. In line two, we start
|
|
|
|
|
\QA. The default set will now be extended with the doc file
|
|
|
|
|
\c file.dcf. In line three we remove the file \c file.dcf from the default
|
|
|
|
|
documentation set so that subsequent use of \QA will not contain this
|
|
|
|
|
file.
|
|
|
|
|
|
|
|
|
|
\section2 Documentation Content File Format
|
|
|
|
|
|
|
|
|
|
The Documentation Content File must contain the documentation's table
|
|
|
|
|
of contents and all important keywords for the index. In addition, it
|
|
|
|
|
may inherit an icon for the documentation which is displayed in the
|
|
|
|
|
\QA toolbar. You can also specify an extra directory path for
|
|
|
|
|
additional images used in the documentation.
|
|
|
|
|
|
|
|
|
|
An example of a content file that uses all the available tags and
|
|
|
|
|
attributes is shown below:
|
|
|
|
|
\code
|
|
|
|
|
<assistantconfig version="3.2.0">
|
|
|
|
|
<DCF ref="demo.html" icon="handbook.png" imagedir="../img/"
|
|
|
|
|
title="Development Demo Handbook">
|
|
|
|
|
<section ref="./chap1/chap1.html" title="Chapter1">
|
|
|
|
|
<section ref="./chap1/section1.html" title="Section1">
|
|
|
|
|
<keyword ref="./chap1/section1.html#foo">foo</keyword>
|
|
|
|
|
<keyword ref="./chap1/section1.html#bla">bla</keyword>
|
|
|
|
|
<section ref="./chap1/section1.html#subsection1" title="Subsection 1"/>
|
|
|
|
|
<section ref="./chap1/section1.html#subsection2" title="Subsection 2"/>
|
|
|
|
|
<section ref="./chap1/section1.html#subsection3" title="Subsection 3"/>
|
|
|
|
|
</section>
|
|
|
|
|
<section ref="./chap1/section2" title="Section2">
|
|
|
|
|
<section ref="./chap1/section2.html#subsection1" title="Subsection 1"/>
|
|
|
|
|
<section ref="./chap1/section2.html#subsection2" title="Subsection 2"/>
|
|
|
|
|
<section ref="./chap1/section2.html#subsection3" title="Subsection 3"/>
|
|
|
|
|
</section>
|
|
|
|
|
</section>
|
|
|
|
|
<section ref="./chap2/chap2.html" title="Chapter2">
|
|
|
|
|
<keyword ref="./chap2/chap2.html#foo">foo</keyword>
|
|
|
|
|
<section ref="./chap2/section1.html" title="Section1"/>
|
|
|
|
|
</section>
|
|
|
|
|
</DCF>
|
|
|
|
|
</assistantconfig>
|
|
|
|
|
\endcode
|
|
|
|
|
|
|
|
|
|
Sections may be nested as deeply as necessary. All references should
|
|
|
|
|
be related.
|
|
|
|
|
|
|
|
|
|
Note that any \c keyword tags for a given section must appear \e
|
|
|
|
|
before any sections nested within the given section.
|
|
|
|
|
|
|
|
|
|
The paths in the \c refs attribute are always written Unix-style
|
|
|
|
|
(forward slashes) and are relative to the location of the
|
|
|
|
|
documentation content file itself.
|
|
|
|
|
|
|
|
|
|
Since the introduction of the new root tag \c assistantconfig in the
|
|
|
|
|
fileformat from Qt version 3.2.0, it is possible to specify multiple DCF tags in
|
|
|
|
|
one file. Note that the old document contents file format, used up to
|
|
|
|
|
Qt 3.2 is still valid.
|
|
|
|
|
|
|
|
|
|
\section1 Profiles
|
|
|
|
|
|
|
|
|
|
Profiles enable \QA to act as a specialized help tool for displaying
|
|
|
|
|
documentation for applications. With profiles, the documentation
|
|
|
|
|
writer can change properties such as \QA's title, application icons, and
|
|
|
|
|
'about' dialogs. In addition, profiles can be used to run specialized
|
|
|
|
|
documentation sets that are separate from the Qt docs. \QA can be
|
|
|
|
|
customized by changing the following properties:
|
|
|
|
|
|
|
|
|
|
\list
|
|
|
|
|
|
|
|
|
|
\i Name- This property is used to name the profile. If multiple
|
|
|
|
|
profiles are used for the same installation of \QA, this
|
|
|
|
|
parameter is crucial to keep their profile specific settings
|
|
|
|
|
apart. The property name is \c name
|
|
|
|
|
|
|
|
|
|
\i Title- This property is used to specify a caption for \QA. The
|
|
|
|
|
property name is \c title
|
|
|
|
|
|
|
|
|
|
\i Application Icon- This property describes an icon that will be used
|
|
|
|
|
as \QA application icon. The location of the icon is relative to the
|
|
|
|
|
location of the profile. The property name is \c applicationicon
|
|
|
|
|
|
|
|
|
|
\i Start Page- This property specifies which page \QA should initially
|
|
|
|
|
display when the profile is used. Usually, this is the HTML file which
|
|
|
|
|
contains the documentation's table of contents. This property also
|
|
|
|
|
describes the default location to go to when pressing the home button
|
|
|
|
|
in \QA's main user interface. The start page is specified relative to
|
|
|
|
|
the location of the profile. The property name is \c startpage
|
|
|
|
|
|
|
|
|
|
\i About Menu Text- This property describes the text that appears in
|
|
|
|
|
the \Menu Help menu, e.g. About Application. The property name is \c
|
|
|
|
|
aboutmenutext
|
|
|
|
|
|
|
|
|
|
\i About URL- This property can be used to point to an HTML file that
|
|
|
|
|
describes the contents in the About dialog that is opened for the
|
|
|
|
|
\Menu Help menu, e.g. About Application. The url is specified relative
|
|
|
|
|
to the location of the profile. The property name is \c abouturl
|
|
|
|
|
|
|
|
|
|
\i \QA Documentation- This property describes the location of
|
|
|
|
|
the \QA documentation. This is required since \QA provides
|
|
|
|
|
self help, such as the full text search help and the \QA
|
|
|
|
|
Manual option in the \Menu Help menu. The location is a directory
|
|
|
|
|
relative to the location of the profile. The property name is \c
|
|
|
|
|
assistantdocs.
|
|
|
|
|
|
|
|
|
|
\endlist
|
|
|
|
|
|
|
|
|
|
To define a profile, one needs to specify a \QA Document
|
|
|
|
|
Profile, usually abbreviated \c{.adp}. The profile is an extension of
|
|
|
|
|
the Documentation Content File described above. We add a \c profile
|
|
|
|
|
tag containing \c property tags to the format.
|
|
|
|
|
|
|
|
|
|
An example of a document profile file is shown below:
|
|
|
|
|
|
|
|
|
|
\c helpdemo.adp
|
|
|
|
|
|
|
|
|
|
\code
|
|
|
|
|
<assistantconfig version="3.2.0">
|
|
|
|
|
|
|
|
|
|
<profile>
|
|
|
|
|
<property name="name">HelpExample</property>
|
|
|
|
|
<property name="title">Help Example</property>
|
|
|
|
|
<property name="applicationicon">logo.png</property>
|
|
|
|
|
<property name="startpage">index.html</property>
|
|
|
|
|
<property name="aboutmenutext">About Help</property>
|
|
|
|
|
<property name="abouturl">../about.txt</property>
|
|
|
|
|
<property name="assistantdocs">../../../doc/html</property>
|
|
|
|
|
</profile>
|
|
|
|
|
|
|
|
|
|
<DCF ref="index.html" icon="handbook.png" title="Help example">
|
|
|
|
|
<section ref="./manual.html" title="How to use this Example">
|
|
|
|
|
<keyword ref="./manual.html#installdocs">Install Docs</keyword>
|
|
|
|
|
<keyword ref="./manual.html#onlydoc">Example Profile</keyword>
|
|
|
|
|
<keyword ref="./manual.html#hide">Hide Sidebar</keyword>
|
|
|
|
|
<keyword ref="./manual.html#openqabutton">Open</keyword>
|
|
|
|
|
<keyword ref="./manual.html#closeqabutton">Close</keyword>
|
|
|
|
|
<keyword ref="./manual.html#display">Display</keyword>
|
|
|
|
|
</section>
|
|
|
|
|
</DCF>
|
|
|
|
|
|
|
|
|
|
</assistantconfig>
|
|
|
|
|
\endcode
|
|
|
|
|
|
|
|
|
|
These files are XML files. Characters such as \c{<}, \c{>}, and \c{&}
|
|
|
|
|
must be written as entities (e.g., \c{<}, \c{>}, \c{&}).
|
|
|
|
|
|
|
|
|
|
\section2 Using Profiles
|
|
|
|
|
|
|
|
|
|
To use a profile, run \QA with the option \c {-profile filename}.
|
|
|
|
|
This will load the profile specified in the file and will customize
|
|
|
|
|
\QA accordingly. For example, to run \QA with the example
|
|
|
|
|
file above, \c helpdemo.adp, we would run the command as follows:
|
|
|
|
|
|
|
|
|
|
\code
|
|
|
|
|
> assistant -profile helpdemo.adp
|
|
|
|
|
\endcode
|
|
|
|
|
|
|
|
|
|
See the HelpDemo example in the Qt distribution for a demonstration
|
|
|
|
|
on how to use \QA with profiles for your own applications.
|
|
|
|
|
|
|
|
|
|
When distributing \QA with your application, you will also need to
|
|
|
|
|
copy the icon files from the \c QTDIR/tools/assistant/images
|
|
|
|
|
directory so that \QA finds its icons.
|
|
|
|
|
|
|
|
|
|
\omit
|
|
|
|
|
For small documentation sets, the sidebar may not be necessary. You
|
|
|
|
|
can hide the sidebar on startup with the following:
|
|
|
|
|
\code
|
|
|
|
|
assistant -hideSidebar
|
|
|
|
|
\endcode
|
|
|
|
|
\endomit
|
|
|
|
|
|
