assistant.leaf

Trolltech公司发布的基于C++图形开发环境

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

\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.

\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