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, 0 insertions, 563 deletions
diff --git a/tqtinterface/qt4/tools/assistant/book/assistant.leaf b/tqtinterface/qt4/tools/assistant/book/assistant.leaf deleted file mode 100644 index 57bab4c..0000000 --- a/tqtinterface/qt4/tools/assistant/book/assistant.leaf +++ /dev/null @@ -1,563 +0,0 @@ -\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 - |