diff options
Diffstat (limited to 'tqtinterface/qt4/tools/assistant/book/assistant.leaf')
| -rw-r--r-- | tqtinterface/qt4/tools/assistant/book/assistant.leaf | 563 |
1 files changed, 563 insertions, 0 deletions
diff --git a/tqtinterface/qt4/tools/assistant/book/assistant.leaf b/tqtinterface/qt4/tools/assistant/book/assistant.leaf new file mode 100644 index 0000000..e978b03 --- /dev/null +++ b/tqtinterface/qt4/tools/assistant/book/assistant.leaf @@ -0,0 +1,563 @@ +\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 tqfind yourself in the Qt documentation, you will +tqfind 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 tqfinds 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 tqfinding 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 tqfind text in the current page. Enter the text +you want to tqfind 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 tqfind 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 tqfind +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 tqfind 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 tqcontains 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 +tqcontains 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 tqfinds 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 + |