summaryrefslogtreecommitdiffstats
path: root/doc/src/development
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/development')
-rw-r--r--doc/src/development/activeqt-dumpcpp.qdoc143
-rw-r--r--doc/src/development/activeqt-dumpdoc.qdoc83
-rw-r--r--doc/src/development/activeqt-idc.qdoc82
-rw-r--r--doc/src/development/activeqt-testcon.qdoc77
-rw-r--r--doc/src/development/assistant-manual.qdoc810
-rw-r--r--doc/src/development/debug.qdoc243
-rw-r--r--doc/src/development/designer-manual.qdoc2836
-rw-r--r--doc/src/development/developing-on-mac.qdoc269
-rw-r--r--doc/src/development/developing-with-qt.qdoc74
-rw-r--r--doc/src/development/moc.qdoc335
-rw-r--r--doc/src/development/qmake-manual.qdoc4320
-rw-r--r--doc/src/development/qmsdev.qdoc166
-rw-r--r--doc/src/development/qtestlib.qdoc778
-rw-r--r--doc/src/development/rcc.qdoc95
-rw-r--r--doc/src/development/tools-list.qdoc84
-rw-r--r--doc/src/development/uic.qdoc88
16 files changed, 10483 insertions, 0 deletions
diff --git a/doc/src/development/activeqt-dumpcpp.qdoc b/doc/src/development/activeqt-dumpcpp.qdoc
new file mode 100644
index 0000000..8c743a1
--- /dev/null
+++ b/doc/src/development/activeqt-dumpcpp.qdoc
@@ -0,0 +1,143 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page activeqt-dumpcpp.html
+ \title The dumpcpp Tool (ActiveQt)
+
+ \ingroup activeqt-tools
+
+ \keyword dumpcpp
+
+ The \c dumpcpp tool generates a C++ namespace for a type library.
+
+ To generate a C++ namespace for a type library, call \c dumpcpp with the following
+ command line parameters:
+
+ \table
+ \header
+ \i Option
+ \i Result
+ \row
+ \i input
+ \i Generate documentation for \e input. \e input can specify a type library file or a type
+ library ID, or a CLSID or ProgID for an object
+ \row
+ \i -o file
+ \i Writes the class declaration to \e {file}.h and meta object infomation to \e {file}.cpp
+ \row
+ \i -n namespace
+ \i Generate a C++ namespace \e namespace
+ \row
+ \i -nometaobject
+ \i Do not generate a .cpp file with the meta object information.
+ The meta object is then generated in runtime.
+ \row
+ \i -getfile libid
+ \i Print the filename for the typelibrary \e libid to stdout
+ \row
+ \i -compat
+ \i Generate namespace with dynamicCall-compatible API
+ \row
+ \i -v
+ \i Print version information
+ \row
+ \i -h
+ \i Print help
+ \endtable
+
+ \c dumpcpp can be integrated into the \c qmake build system. In your .pro file, list the type
+ libraries you want to use in the TYPELIBS variable:
+
+ \snippet examples/activeqt/qutlook/qutlook.pro 0
+
+ The generated namespace will declare all enumerations, as well as one QAxObject subclass
+ for each \c coclass and \c interface declared in the type library. coclasses marked with
+ the \c control attribute will be wrapped by a QAxWidget subclass.
+
+ Those classes that wrap creatable coclasses (i.e. coclasses that are not marked
+ as \c noncreatable) have a default constructor; this is typically a single class
+ of type \c Application.
+
+ \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 0
+
+ All other classes can only be created by passing an IDispatch interface pointer
+ to the constructor; those classes should however not be created explicitly.
+ Instead, use the appropriate API of already created objects.
+
+ \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 1
+
+ All coclass wrappers also have one constructors taking an interface wrapper class
+ for each interface implemented.
+
+ \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 2
+
+ You have to create coclasses to be able to connect to signals of the subobject.
+ Note that the constructor deletes the interface object, so the following will
+ cause a segmentation fault:
+
+ \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 3
+
+ If the return type is of a coclass or interface type declared in another type
+ library you have to include the namespace header for that other type library
+ before including the header for the namespace you want to use (both header have
+ to be generated with this tool).
+
+ By default, methods and property returning subobjects will use the type as in
+ the type library. The caller of the function is responsible for deleting or
+ reparenting the object returned. If the \c -compat switch is set, properties
+ and method returning a COM object have the return type \c IDispatch*, and
+ the namespace will not declare wrapper classes for interfaces.
+
+ In this case, create the correct wrapper class explicitly:
+
+ \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 4
+
+ You can of course use the IDispatch* returned directly, in which case you have to
+ call \c Release() when finished with the interface.
+
+ All classes in the namespace are tagged with a macro that allows you to export
+ or import them from a DLL. To do that, declare the macro to expand to
+ \c __declspec(dllimport/export) before including the header file.
+
+ To build the tool you must first build the QAxContainer library.
+ Then run your make tool in \c tools/dumpcpp.
+*/
diff --git a/doc/src/development/activeqt-dumpdoc.qdoc b/doc/src/development/activeqt-dumpdoc.qdoc
new file mode 100644
index 0000000..55ab2d7
--- /dev/null
+++ b/doc/src/development/activeqt-dumpdoc.qdoc
@@ -0,0 +1,83 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page activeqt-dumpdoc.html
+ \title The dumpdoc Tool (ActiveQt)
+
+ \ingroup activeqt-tools
+
+ \keyword dumpdoc
+
+ The \c dumpdoc tool generates Qt-style documentation for any
+ COM object and writes it into the file specified.
+
+ Call \c dumpdoc with the following command line parameters:
+
+ \table
+ \header
+ \i Option
+ \i Result
+ \row
+ \i -o file
+ \i Writes output to \e file
+ \row
+ \i object
+ \i Generate documentation for \e object
+ \row
+ \i -v
+ \i Print version information
+ \row
+ \i -h
+ \i Print help
+ \endtable
+
+ \e object must be an object installed on the local machine (ie.
+ remote objects are not supported), and can include subobjects
+ accessible through properties, ie.
+ \c Outlook.Application/Session/CurrentUser
+
+ The generated file will be an HTML file using Qt documentation
+ style.
+
+ To build the tool you must first build the QAxContainer library.
+ Then run your make tool in \c tools/dumpdoc.
+*/
diff --git a/doc/src/development/activeqt-idc.qdoc b/doc/src/development/activeqt-idc.qdoc
new file mode 100644
index 0000000..974eddc
--- /dev/null
+++ b/doc/src/development/activeqt-idc.qdoc
@@ -0,0 +1,82 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page activeqt-idc.html
+ \title IDC - The Interface Description Compiler (ActiveQt)
+
+ \ingroup activeqt-tools
+
+ \keyword idc
+
+ The IDC tool is part of the ActiveQt build system and makes
+ it possible to turn any Qt binary into a full COM object server
+ with only a few lines of code.
+
+ IDC understands the following command line parameters:
+
+ \table
+ \header
+ \i Option
+ \i Result
+ \row
+ \i dll -idl idl -version x.y
+ \i Writes the IDL of the server \e dll to the file \e idl. The
+ type library wll have version x.y.
+ \row
+ \i dll -tlb tlb
+ \i Replaces the type library in \e dll with \e tlb
+ \row
+ \i -v
+ \i Print version information
+ \row
+ \i -regserver dll
+ \i Register the COM server \e dll
+ \row
+ \i -unregserver
+ \i Unregister the COM server \e dll
+ \endtable
+
+ It is usually never necessary to invoke IDC manually, as the \c
+ qmake build system takes care of adding the required post
+ processing steps to the build process. See the \l{ActiveQt}
+ documentation for details.
+*/
diff --git a/doc/src/development/activeqt-testcon.qdoc b/doc/src/development/activeqt-testcon.qdoc
new file mode 100644
index 0000000..9fcfed6
--- /dev/null
+++ b/doc/src/development/activeqt-testcon.qdoc
@@ -0,0 +1,77 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page activeqt-testcon.html
+ \title testcon - An ActiveX Test Container (ActiveQt)
+
+ \ingroup activeqt-tools
+
+ \keyword testcon
+
+ This application implements a generic test container for ActiveX
+ controls. You can insert ActiveX controls installed on your
+ system, and execute methods and modify properties. The container
+ will log information about events and property changes as well
+ as debug output in the log window.
+
+ Parts of the code use internals of the Qt meta object and ActiveQt
+ framework and are not recommended to be used in application code.
+
+ Use the application to view the slots, signals and porperties
+ available through the QAxWidget class when instantiated with a
+ certain ActiveX, and to test ActiveX controls you implement or
+ want to use in your Qt application.
+
+ The application can load and execute script files in JavaScript,
+ VBScript, Perl and Python (if installed) to automate the controls
+ loaded. Example script files using the QAxWidget2 class are available
+ in the \c scripts subdirectory.
+
+ Note that the qmake project of this example includes a resource file
+ \c testcon.rc with a version resource. This is required by some
+ ActiveX controls (ie. Shockwave ActiveX Controls), which might crash
+ or misbehave otherwise if such version information is missing.
+
+ To build the tool you must first build the QAxContainer and the
+ QAxServer libraries. Then run your make tool in \c tools/testcon
+ and run the resulting \c testcon.exe.
+*/
diff --git a/doc/src/development/assistant-manual.qdoc b/doc/src/development/assistant-manual.qdoc
new file mode 100644
index 0000000..b26efcc
--- /dev/null
+++ b/doc/src/development/assistant-manual.qdoc
@@ -0,0 +1,810 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page assistant-manual.html
+ \title Qt Assistant Manual
+ \ingroup qttools
+
+ \startpage {index.html}{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
+ \o \l{The One-Minute Guide to Using Qt Assistant}
+ \o \l{Qt Assistant in More Detail}
+ \o \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
+ \o On Windows, \QA is available as a menu option on the Qt menu.
+ \o On Mac OS X, \QA is installed in the /Developer/Applications/Qt directory.
+ \o 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
+ \o Command Line Option
+ \o Brief Description
+ \row
+ \o -collectionFile <file.qhc>
+ \o Uses the specified collection file instead of the default one.
+ \row
+ \o -showUrl URL
+ \o Shows the document referenced by URL.
+ \row
+ \o -enableRemoteControl
+ \o Enables \QA to be remotly controlled.
+ \row
+ \o -show <widget>
+ \o Shows the specified dockwidget which can be "contents", "index",
+ "bookmarks" or "search".
+ \row
+ \o -hide <widget>
+ \o Hides the specified dockwidget which can be "contents", "index",
+ "bookmarks" or "search.
+ \row
+ \o -activate <widget>
+ \o Activates the specified dockwidget which can be "contents",
+ "index", "bookmarks" or "search.
+ \row
+ \o -register <doc.qch>
+ \o Registers the specified compressed help file in the given help
+ collection.
+ \row
+ \o -unregister <doc.qch>
+ \o Unregisters the specified compressed help file from the given
+ collection file.
+ \row
+ \o -setCurrentFilter filter
+ \o Sets the given filter as the active filter.
+ \row
+ \o -quiet
+ \o 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
+ \o 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.
+ \o 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.
+ \o 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 \o Action \o Description \o Menu Item \o Shortcut
+ \row \o \gui{Previous} \o Takes you to the previous page in the history.
+ \o \menu{Go|Previous} \o \key{Alt+Left Arrow}
+ \row \o \gui{Next} \o Takes you to the next page in the history.
+ \o \menu{Go|Next} \o \key{Alt+Right Arrow}
+ \row \o \gui{Home}
+ \o Takes you to the home page as specified in the Preferences Dialog.
+ \o \menu{Go|Home} \o \key{Ctrl+Home}.
+ \row \o \gui{Sync with Table of Contents}
+ \o Synchronizes the \gui{Contents} tool window with the page currently
+ shown in the \gui{Documentation} window.
+ \o \menu{Go|Sync with Table of Contents} \o
+ \row \o \gui{Copy} \o Copies any selected text to the clipboard.
+ \o \menu{Edit|Copy} \o \key{Ctrl+C}
+ \row \o \gui{Print} \o Opens the \gui{Print} dialog.
+ \o \menu{File|Print} \o \key{Ctrl+P}
+ \row \o \gui{Find in Text} \o Opens the \gui{Find Text} dialog.
+ \o \menu{Edit|Find in Text} \o \key{Ctrl+F}
+ \row \o \gui{Zoom in}
+ \o Increases the font size used to display text in the current tab.
+ \o \menu{View|Zoom in} \o \key{Ctrl++}
+ \row \o \gui{Zoom out}
+ \o Decreases the font size used to display text in the current tab.
+ \o \menu{View|Zoom out} \o \key{Ctrl+-}
+ \row \o \gui{Normal Size}
+ \o Resets the font size to its normal size in the current tab.
+ \o \menu{View|Normal Size} \o \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
+ \o \menu{File|Page Setup...} invokes a dialog allowing you to define
+ page layout properties, such as margin sizes, page orientation and paper size.
+ \o \menu{File|Print Preview...} provides a preview of the printed pages.
+ \o \menu{File|Print...} opens the \l{#Print Dialog}{\gui{Print} dialog}.
+ \o \menu{File|New Tab} opens a new empty tab in the \gui{Documentation}
+ window.
+ \o \menu{File|Close Tab} closes the current tab of the
+ \gui{Documentation} window.
+ \o \menu{File|Exit} closes the \QA application.
+ \endlist
+
+ \section2 Edit Menu
+
+ \list
+ \o \menu{Edit|Copy} copies any selected text to the clipboard.
+ \o \menu{Edit|Find in Text} invokes the \l{#Find Text Control}{\gui{Find Text}
+ control} at the lower end of the \gui{Documentation} window.
+ \o \menu{Edit|Find Next} looks for the next occurance of the specified
+ text in the \gui{Find Text} control.
+ \o \menu{Edit|Find Previous} looks for the previous occurance of
+ the specified text in the \l{#Find Text Control}{\gui{Find Text} control}.
+ \o \menu{Edit|Preferences} invokes the \l{#Preferences Dialog}{\gui{Preferences} dialog}.
+ \endlist
+
+ \section2 View Menu
+
+ \list
+ \o \menu{View|Zoom in} increases the font size in the current tab.
+ \o \menu{View|Zoom out} decreases the font size in the current tab.
+ \o \menu{View|Normal Size} resets the font size in the current tab.
+ \o \menu{View|Contents} toggles the display of the \gui{Contents} tool window.
+ \o \menu{View|Index} toggles the display of the \gui{Index} tool window.
+ \o \menu{View|Bookmarks} toggles the display of the \gui{Bookmarks} tool window.
+ \o \menu{View|Search} toggles the display of the Search in the \gui{Documentation} window.
+ \endlist
+
+ \section2 Go Menu
+
+ \list
+ \o \menu{Go|Home} goes to the home page.
+ \o \menu{Go|Back} displays the previous page in the history.
+ \o \menu{Go|Forward} displays the next page in the history.
+ \o \menu{Go|Sync with Table of Contents} syncs the \gui{Contents} tool window to the currently shown page.
+ \o \menu{Go|Next Page} selects the next tab in the \gui{Documentation} window.
+ \o \menu{Go|Previous Page} selects the previous tab in the \gui{Documentation} window.
+ \endlist
+
+ \section2 Bookmarks Menu
+
+ \list
+ \o \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
+ \o \c deep -- lists all the documents that contain the word 'deep'
+ \o \c{deep*} -- lists all the documents that contain a word beginning
+ with 'deep'
+ \o \c{deep copy} -- lists all documents that contain both 'deep' \e
+ and 'copy'
+ \o \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
+ \o \c{QStin} -- lists all the documents with titles that are similar, such as \c{QString}
+ \o \c{QSting} -- lists all the documents with titles that are similar, such as \c{QString}
+ \o \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/snippets/code/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/snippets/code/doc_src_assistant-manual.qdoc 7
+
+ So, when calling
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8
+
+ \QA actually uses the collection file:
+
+ \snippet doc/src/snippets/code/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/snippets/code/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/snippets/code/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.
+
+ \bold{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
+ \o Tag
+ \o Brief Description
+ \row
+ \o \c{<title>}
+ \o This property is used to specify a window title for \QA.
+ \row
+ \o \c{<homePage>}
+ \o This tag specifies which page should be display when
+ pressing the home button in \QA's main user interface.
+ \row
+ \o \c{<startPage>}
+ \o This tag specifies which page \QA should initially
+ display when the help collection is used.
+ \row
+ \o \c{<currentFilter>}
+ \o 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
+ \o \c{<applicationIcon>}
+ \o 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
+ \o \c{<enableFilterFunctionality>}
+ \o 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
+ \o \c{<enableDocumentationManager>}
+ \o 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
+ \o \c{<enableAddressBar>}
+ \o 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
+ \o \c{<aboutMenuText>, <text>}
+ \o 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
+ \o \c{<aboutDialog>, <file>, <icon>}
+ \o 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
+ \o \c{<cacheDirectory>}
+ \o Specified as a path relative to the directory given by
+ QDesktopServices::DataLocation, the cache path 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.
+ \endtable
+
+ In addition to those \QA specific tags, the tags for generating and registering
+ documentation can be used. See \l{The Qt Help Framework#Creating a Qt Help Collection}
+ {Qt Help Collection} documentation for more information.
+
+ An example of a help collection file that uses all the available tags is shown below:
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 1
+
+ To create the binary collection file, run the \c qcollectiongenerator tool:
+
+ \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 10
+
+ To test the generated collection file, start \QA in the following way:
+
+ \snippet doc/src/snippets/code/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.
+
+ \warning The trailing '\0' must be appended separately to the QByteArray,
+ e.g., \c{QByteArray("command" + '\0')}.
+
+ The following example shows how this can be done:
+
+ \snippet doc/src/snippets/code/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/snippets/code/doc_src_assistant-manual.qdoc 3
+
+ The following commands can be used to control \QA:
+
+ \table
+ \header
+ \o Command
+ \o Brief Description
+ \row
+ \o \c{show <Widget>}
+ \o 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
+ \o \c{hide <Widget>}
+ \o Hides the dock widget specified by <Widget>. Possible values for
+ <Widget> are "contents", "index", "bookmarks" and "search".
+ \row
+ \o \c{setSource <Url>}
+ \o 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
+ \o \c{activateKeyword <Keyword>}
+ \o 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
+ \o \c{activateIdentifier <Id>}
+ \o 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
+ \o \c{syncContents}
+ \o Selects the item in the contents widget which corresponds to
+ the currently displayed page.
+ \row
+ \o \c{setCurrentFilter}
+ \o Selects the specified filter and updates the visual representation
+ accordingly.
+ \row
+ \o \c{expandToc <Depth>}
+ \o Expands the table of contents tree to the given depth. If depth
+ is less than 1, the tree will be collapsed completely.
+ \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/snippets/code/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/snippets/code/doc_src_assistant-manual.qdoc 0
+
+ Other available options the can be passed on the command line.
+
+ \table
+ \header
+ \o Command Line Option
+ \o Brief Description
+ \row
+ \o -collectionFile <file.qhc>
+ \o Uses the specified collection file instead of the default one.
+ \row
+ \o -showUrl URL
+ \o Shows the document referenced by URL.
+ \row
+ \o -enableRemoteControl
+ \o Enables \QA to be remotly controlled.
+ \row
+ \o -show <widget>
+ \o Shows the specified dockwidget which can be "contents", "index",
+ "bookmarks" or "search".
+ \row
+ \o -hide <widget>
+ \o Hides the specified dockwidget which can be "contents", "index",
+ "bookmarks" or "search.
+ \row
+ \o -activate <widget>
+ \o Activates the specified dockwidget which can be "contents",
+ "index", "bookmarks" or "search.
+ \row
+ \o -register <doc.qch>
+ \o Registers the specified compressed help file in the given help
+ collection.
+ \row
+ \o -unregister <doc.qch>
+ \o Unregisters the specified compressed help file from the given
+ collection file.
+ \row
+ \o -quiet
+ \o Doesn't show any error, warning or success messages.
+ \endtable
+ */
diff --git a/doc/src/development/debug.qdoc b/doc/src/development/debug.qdoc
new file mode 100644
index 0000000..f0fe128
--- /dev/null
+++ b/doc/src/development/debug.qdoc
@@ -0,0 +1,243 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page debug.html
+ \title Debugging Techniques
+
+ Here we present some useful hints to help you with debugging your
+ Qt-based software.
+
+ \tableofcontents
+
+ \section1 Configuring Qt for Debugging
+
+ When \l{Installation}{configuring Qt for installation}, it is possible
+ to ensure that it is built to include debug symbols that can make it
+ easier to track bugs in applications and libraries. However, on some
+ platforms, building Qt in debug mode will cause applications to be larger
+ than desirable.
+
+ \section2 Debugging in Mac OS X and Xcode
+
+ \section3 Debugging With/Without Frameworks
+
+ The basic stuff you need to know about debug libraries and
+ frameworks is found at developer.apple.com in:
+ \l{http://developer.apple.com/technotes/tn2004/tn2124.html#SECDEBUGLIB}
+ {Apple Technicle Note TN2124} Qt follows that.
+
+ When you build Qt, frameworks are built by default, and inside the
+ framework you will find both a release and a debug version (e.g.,
+ QtCore and QtCore_debug). If you pass the \c{-no-framework} flag
+ when you build Qt, two dylibs are built for each Qt library (e.g.,
+ libQtCore.4.dylib and libQtCore_debug.4.dylib).
+
+ What happens when you link depends on whether you use frameworks
+ or not. We don't see a compelling reason to recommend one over the
+ other.
+
+ \section4 With Frameworks:
+
+ Since the release and debug libraries are inside the framework,
+ the app is simply linked against the framework. Then when you run
+ in the debugger, you will get either the release version or the
+ debug version, depending on whether you set \c{DYLD_IMAGE_SUFFIX}.
+ If you don't set it, you get the release version by default (i.e.,
+ non _debug). If you set \c{DYLD_IMAGE_SUFFIX=_debug}, you get the
+ debug version.
+
+ \section4 Without Frameworks:
+
+ When you tell \e{qmake} to generate a Makefile with the debug
+ config, it will link against the _debug version of the libraries
+ and generate debug symbols for the app. Running this program in
+ GDB will then work like running GDB on other platforms, and you
+ will be able to trace inside Qt.
+
+ \section3 Debug Symbols and Size
+
+ The amount of space taken up by debug symbols generated by GCC can
+ be excessively large. However, with the release of Xcode 2.3 it is
+ now possible to use Dwarf symbols which take up a significantly
+ smaller amount of space. To enable this feature when configuring
+ Qt, pass the \c{-dwarf-2} option to the configure script.
+
+ This is not enabled by default because previous versions of Xcode
+ will not work with the compiler flag used to implement this
+ feature. Mac OS X 10.5 will use dwarf-2 symbols by default.
+
+ dwarf-2 symbols contain references to source code, so the size of
+ the final debug application should compare favorably to a release
+ build.
+
+ \omit
+ Although it is not necessary to build Qt with debug symbols to use the
+ other techniques described in this document, certain features are only
+ available when Qt is configured for debugging.
+ \endomit
+
+ \section1 Command Line Options Recognized by Qt
+
+ When you run a Qt application, you can specify several
+ command-line options that can help with debugging. These are
+ recognized by QApplication.
+
+ \table
+ \header \o Option \o Description
+ \row \o \c -nograb
+ \o The application should never grab \link QWidget::grabMouse()
+ the mouse\endlink or \link QWidget::grabKeyboard() the
+ keyboard \endlink. This option is set by default when the
+ program is running in the \c gdb debugger under Linux.
+ \row \o \c -dograb
+ \o Ignore any implicit or explicit \c{-nograb}. \c -dograb wins over
+ \c -nograb even when \c -nograb is last on the command line.
+ \row \o \c -sync
+ \o Runs the application in X synchronous mode. Synchronous mode
+ forces the X server to perform each X client request
+ immediately and not use buffer optimization. It makes the
+ program easier to debug and often much slower. The \c -sync
+ option is only valid for the X11 version of Qt.
+ \endtable
+
+ \section1 Warning and Debugging Messages
+
+ Qt includes four global functions for writing out warning and debug
+ text. You can use them for the following purposes:
+
+ \list
+ \o qDebug() is used for writing custom debug output.
+ \o qWarning() is used to report warnings and recoverable errors in
+ your application.
+ \o qCritical() is used for writing critical error mesages and
+ reporting system errors.
+ \o qFatal() is used for writing fatal error messages shortly before exiting.
+ \endlist
+
+ If you include the <QtDebug> header file, the \c qDebug() function
+ can also be used as an output stream. For example:
+
+ \snippet doc/src/snippets/code/doc_src_debug.qdoc 0
+
+ The Qt implementation of these functions prints the text to the
+ \c stderr output under Unix/X11 and Mac OS X. With Windows, if it
+ is a console application, the text is sent to console; otherwise, it
+ is sent to the debugger. You can take over these functions by
+ installing a message handler using qInstallMsgHandler().
+
+ If the \c QT_FATAL_WARNINGS environment variable is set,
+ qWarning() exits after printing the warning message. This makes
+ it easy to obtain a backtrace in the debugger.
+
+ Both qDebug() and qWarning() are debugging tools. They can be
+ compiled away by defining \c QT_NO_DEBUG_OUTPUT and \c
+ QT_NO_WARNING_OUTPUT during compilation.
+
+ The debugging functions QObject::dumpObjectTree() and
+ QObject::dumpObjectInfo() are often useful when an application
+ looks or acts strangely. More useful if you use \l{QObject::setObjectName()}{object names}
+ than not, but often useful even without names.
+
+ \section1 Providing Support for the qDebug() Stream Operator
+
+ You can implement the stream operator used by qDebug() to provide
+ debugging support for your classes. The class that implements the
+ stream is \c QDebug. The functions you need to know about in \c
+ QDebug are \c space() and \c nospace(). They both return a debug
+ stream; the difference between them is whether a space is inserted
+ between each item. Here is an example for a class that represents
+ a 2D coordinate.
+
+ \snippet doc/src/snippets/qdebug/qdebugsnippet.cpp 0
+
+ Integration of custom types with Qt's meta-object system is covered
+ in more depth in the \l{Creating Custom Qt Types} document.
+
+ \section1 Debugging Macros
+
+ The header file \c <QtGlobal> contains some debugging macros and
+ \c{#define}s.
+
+ Three important macros are:
+ \list
+ \o \l{Q_ASSERT()}{Q_ASSERT}(cond), where \c cond is a boolean
+ expression, writes the warning "ASSERT: '\e{cond}' in file xyz.cpp, line
+ 234" and exits if \c cond is false.
+ \o \l{Q_ASSERT_X()}{Q_ASSERT_X}(cond, where, what), where \c cond is a
+ boolean expression, \c where a location, and \c what a message,
+ writes the warning: "ASSERT failure in \c{where}: '\c{what}', file xyz.cpp, line 234"
+ and exits if \c cond is false.
+ \o \l{Q_CHECK_PTR()}{Q_CHECK_PTR}(ptr), where \c ptr is a pointer.
+ Writes the warning "In file xyz.cpp, line 234: Out of memory" and
+ exits if \c ptr is 0.
+ \endlist
+
+ These macros are useful for detecting program errors, e.g. like this:
+
+ \snippet doc/src/snippets/code/doc_src_debug.qdoc 1
+
+ Q_ASSERT(), Q_ASSERT_X(), and Q_CHECK_PTR() expand to nothing if
+ \c QT_NO_DEBUG is defined during compilation. For this reason,
+ the arguments to these macro should not have any side-effects.
+ Here is an incorrect usage of Q_CHECK_PTR():
+
+ \snippet doc/src/snippets/code/doc_src_debug.qdoc 2
+
+ If this code is compiled with \c QT_NO_DEBUG defined, the code in
+ the Q_CHECK_PTR() expression is not executed and \e alloc returns
+ an unitialized pointer.
+
+ The Qt library contains hundreds of internal checks that will
+ print warning messages when a programming error is detected. We
+ therefore recommend that you use a debug version of Qt when
+ developing Qt-based software.
+
+ \section1 Common Bugs
+
+ There is one bug that is so common that it deserves mention here:
+ If you include the Q_OBJECT macro in a class declaration and
+ run \link moc.html the meta-object compiler\endlink (\c{moc}),
+ but forget to link the \c{moc}-generated object code into your
+ executable, you will get very confusing error messages. Any link
+ error complaining about a lack of \c{vtbl}, \c{_vtbl}, \c{__vtbl}
+ or similar is likely to be a result of this problem.
+*/
diff --git a/doc/src/development/designer-manual.qdoc b/doc/src/development/designer-manual.qdoc
new file mode 100644
index 0000000..5d8587a
--- /dev/null
+++ b/doc/src/development/designer-manual.qdoc
@@ -0,0 +1,2836 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page designer-manual.html
+
+ \title Qt Designer Manual
+ \ingroup qttools
+ \keyword Qt Designer
+
+ \QD is Qt's tool for designing and building graphical user
+ interfaces (GUIs) from Qt components. You can compose and customize your
+ widgets or dialogs in a what-you-see-is-what-you-get (WYSIWYG) manner, and
+ test them using different styles and resolutions.
+
+ Widgets and forms created with \QD integrated seamlessly with programmed
+ code, using Qt's signals and slots mechanism, that lets you easily assign
+ behavior to graphical elements. All properties set in \QD can be changed
+ dynamically within the code. Furthermore, features like widget promotion
+ and custom plugins allow you to use your own components with \QD.
+
+ If you are new to \QD, you can take a look at the
+ \l{Getting To Know Qt Designer} document. For a quick tutorial on how to
+ use \QD, refer to \l{A Quick Start to Qt Designer}.
+
+ Qt Designer 4.5 boasts a long list of improvements. For a detailed list of
+ what is new, refer \l{What's New in Qt Designer 4.5}.
+
+ \image designer-multiple-screenshot.png
+
+ For more information on using \QD, you can take a look at the following
+ links:
+
+ \list
+ \o \l{Qt Designer's Editing Modes}
+ \list
+ \o \l{Qt Designer's Widget Editing Mode}{Widget Editing Mode}
+ \o \l{Qt Designer's Signals and Slots Editing Mode}
+ {Signals and Slots Editing Mode}
+ \o \l{Qt Designer's Buddy Editing Mode}
+ {Buddy Editing Mode}
+ \o \l{Qt Designer's Tab Order Editing Mode}
+ {Tab Order Editing Mode}
+ \endlist
+ \o \l{Using Layouts in Qt Designer}
+ \o \l{Saving, Previewing and Printing Forms in Qt Designer}
+ \o \l{Using Containers in Qt Designer}
+ \o \l{Creating Main Windows in Qt Designer}
+ \o \l{Editing Resources with Qt Designer}
+ \o \l{Using Stylesheets with Qt Designer}
+ \o \l{Using a Designer UI File in Your Application}
+ \endlist
+
+ For advanced usage of \QD, you can refer to these links:
+
+ \list
+ \o \l{Customizing Qt Designer Forms}
+ \o \l{Using Custom Widgets with Qt Designer}
+ \o \l{Creating Custom Widgets for Qt Designer}
+ \o \l{Creating Custom Widget Extensions}
+ \o \l{Qt Designer's UI File Format}
+ \endlist
+
+
+ \section1 Legal Notices
+
+ Some source code in \QD is licensed under specific highly permissive
+ licenses from the original authors. The Qt team gratefully acknowledges
+ these contributions to \QD and all uses of \QD should also acknowledge
+ these contributions and quote the following license statements in an
+ appendix to the documentation.
+
+ \list
+ \i \l{Implementation of the Recursive Shadow Casting Algorithm in Qt Designer}
+ \endlist
+*/
+
+
+
+/*!
+ \page designer-whats-new.html
+ \contentspage {Qt Designer Manual}{Contents}
+
+
+ \title What's New in Qt Designer 4.5
+
+ \section1 General Changes
+
+
+ \table
+ \header
+ \i Widget Filter Box
+ \i Widget Morphing
+ \i Disambiguation Field
+ \row
+ \i \inlineimage designer-widget-filter.png
+ \i \inlineimage designer-widget-morph.png
+ \i \inlineimage designer-disambiguation.png
+ \endtable
+
+ \list 1
+ \i Displaying only icons in the \gui{Widget Box}: It is now possible
+ for the \gui{Widget Box} to display icons only. Simply select
+ \gui{Icon View} from the context menu.
+ \i Filter for \gui{Widget Box}: A filter is now provided to quickly
+ locate the widget you need. If you use a particular widget
+ frequently, you can always add it to the
+ \l{Getting to Know Qt Designer#WidgetBox}{scratch pad}.
+ \i Support for QButtonGroup: It is available via the context
+ menu of a selection of QAbstractButton objects.
+ \i Improved support for item widgets: The item widgets' (e.g.,
+ QListWidget, QTableWidget, and QTreeWidget) contents dialogs have
+ been improved. You can now add translation comments and also modify
+ the header properties.
+ \i Widget morphing: A widget can now be morphed from one type to
+ another with its layout and properties preserved. To begin, click
+ on your widget and select \gui{Morph into} from the context menu.
+ \i Disambiguation field: The property editor now shows this extra
+ field under the \gui{accessibleDescription} property. This field
+ has been introduced to aid translators in the case of two source
+ texts being the same but used for different purposes. For example,
+ a dialog could have two \gui{Add} buttons for two different
+ reasons. \note To maintain compatibility, comments in UI files
+ created prior to Qt 4.5 will be listed in the \gui{Disambiguation}
+ field.
+ \endlist
+
+
+
+ \section1 Improved Shortcuts for the Editing Mode
+
+ \list
+ \i The \key{Shift+Click} key combination now selects the ancestor for
+ nested layouts. This iterates from one ancestor to the other.
+
+ \i The \key{Ctrl} key is now used to toggle and copy drag. Previously
+ this was done with the \key{Shift} key but is now changed to
+ conform to standards.
+
+ \i The left mouse button does rubber band selection for form windows;
+ the middle mouse button does rubber band selection everywhere.
+ \endlist
+
+
+ \section1 Layouts
+ \list
+ \i It is now possible to switch a widget's layout without breaking it
+ first. Simply select the existing layout and change it to another
+ type using the context menu or the layout buttons on the toolbar.
+
+ \i To quickly populate a \gui{Form Layout}, you can now use the
+ \gui{Add form layout row...} item available in the context menu or
+ double-click on the red layout.
+ \endlist
+
+
+ \section1 Support for Embedded Design
+
+ \table
+ \header
+ \i Comboboxes to Select a Device Profile
+ \row
+ \i \inlineimage designer-embedded-preview.png
+ \endtable
+
+ It is now possible to specify embedded device profiles, e.g., Style, Font,
+ Screen DPI, resolution, default font, etc., in \gui{Preferences}. These
+ settings will affect the \gui{Form Editor}. The profiles will also be
+ visible with \gui{Preview}.
+
+
+ \section1 Related Classes
+
+ \list
+ \i QUiLoader \mdash forms loaded with this class will now react to
+ QEvent::LanguageChange if QUiLoader::setLanguageChangeEnabled() or
+ QUiLoader::isLanguageChangeEnabled() is set to true.
+
+ \i QDesignerCustomWidgetInterface \mdash the
+ \l{QDesignerCustomWidgetInterface::}{domXml()} function now has new
+ attributes for its \c{<ui>} element. These attributes are
+ \c{language} and \c{displayname}. The \c{language} element can be
+ one of the following "", "c++", "jambi". If this element is
+ specified, it must match the language in which Designer is running.
+ Otherwise, this element will not be available. The \c{displayname}
+ element represents the name that will be displayed in the
+ \gui{Widget Box}. Previously this was hardcoded to be the class
+ name.
+
+ \i QWizard \mdash QWizard's page now has a string \c{id} attribute that
+ can be used to fill in enumeration values to be used by the
+ \c{uic}. However, this attribute has no effect on QUiLoader.
+ \endlist
+*/
+
+
+/*!
+ \page designer-to-know.html
+ \contentspage {Qt Designer Manual}{Contents}
+
+
+ \title Getting to Know Qt Designer
+
+ \tableofcontents
+
+ \image designer-screenshot.png
+
+ \section1 Launching Designer
+
+ The way that you launch \QD depends on your platform:
+
+ \list
+ \i On Windows, click the Start button, under the \gui Programs submenu,
+ open the \gui{Qt 4} submenu and click \gui Designer.
+ \i On Unix or Linux, you might find a \QD icon on the desktop
+ background or in the desktop start menu under the \gui Programming
+ or \gui Development submenus. You can launch \QD from this icon.
+ Alternatively, you can type \c{designer} in a terminal window.
+ \i On Mac OS X, double click on \QD in \gui Finder.
+ \endlist
+
+ \section1 The User Interface
+
+ When used as a standalone application, \QD's user interface can be
+ configured to provide either a multi-window user interface (the default
+ mode), or it can be used in docked window mode. When used from within an
+ integrated development environment (IDE) only the multi-window user
+ interface is available. You can switch modes in the \gui Preferences dialog
+ from the \gui Edit menu.
+
+ In multi-window mode, you can arrange each of the tool windows to suit your
+ working style. The main window consists of a menu bar, a tool bar, and a
+ widget box that contains the widgets you can use to create your user
+ interface.
+
+ \target MainWindow
+ \table
+ \row
+ \i \inlineimage designer-main-window.png
+ \i \bold{Qt Designer's Main Window}
+
+ The menu bar provides all the standard actions for managing forms,
+ using the clipboard, and accessing application-specific help.
+ The current editing mode, the tool windows, and the forms in use can
+ also be accessed via the menu bar.
+
+ The tool bar displays common actions that are used when editing a form.
+ These are also available via the main menu.
+
+ The widget box provides common widgets and layouts that are used to
+ design components. These are grouped into categories that reflect their
+ uses or features.
+ \endtable
+
+ Most features of \QD are accessible via the menu bar, the tool bar, or the
+ widget box. Some features are also available through context menus that can
+ be opened over the form windows. On most platforms, the right mouse is used
+ to open context menus.
+
+ \target WidgetBox
+ \table
+ \row
+ \i \inlineimage designer-widget-box.png
+ \i \bold{Qt Designer's Widget Box}
+
+ The widget box provides a selection of standard Qt widgets, layouts,
+ and other objects that can be used to create user interfaces on forms.
+ Each of the categories in the widget box contain widgets with similar
+ uses or related features.
+
+ \note Since Qt 4.4, new widgets have been included, e.g.,
+ QPlainTextEdit, QCommandLinkButton, QScrollArea, QMdiArea, and
+ QWebView.
+
+ You can display all of the available objects in a category by clicking
+ on the handle next to the category label. When in
+ \l{Qt Designer's Widget Editing Mode}{Widget Editing
+ Mode}, you can add objects to a form by dragging the appropriate items
+ from the widget box onto the form, and dropping them in the required
+ locations.
+
+ \QD provides a scratch pad feature that allows you to collect
+ frequently used objects in a separate category. The scratch pad
+ category can be filled with any widget currently displayed in a form
+ by dragging them from the form and dropping them onto the widget box.
+ These widgets can be used in the same way as any other widgets, but
+ they can also contain child widgets. Open a context menu over a widget
+ to change its name or remove it from the scratch pad.
+ \endtable
+
+
+ \section1 The Concept of Layouts in Qt
+
+ A layout is used to arrange and manage the elements that make up a user
+ interface. Qt provides a number of classes to automatically handle layouts
+ -- QHBoxLayout, QVBoxLayout, QGridLayout, and QFormLayout. These classes
+ solve the challenge of laying out widgets automatically, providing a user
+ interface that behaves predictably. Fortunately knowledge of the layout
+ classes is not required to arrange widgets with \QD. Instead, select one of
+ the \gui{Lay Out Horizontally}, \gui{Lay Out in a Grid}, etc., options from
+ the context menu.
+
+ Each Qt widget has a recommended size, known as \l{QWidget::}{sizeHint()}.
+ The layout manager will attempt to resize a widget to meet its size hint.
+ In some cases, there is no need to have a different size. For example, the
+ height of a QLineEdit is always a fixed value, depending on font size and
+ style. In other cases, you may require the size to change, e.g., the width
+ of a QLineEdit or the width and height of item view widgets. This is where
+ the widget size constraints -- \l{QWidget::minimumSize()}{minimumSize} and
+ \l{QWidget::maximumSize()}{maximumSize} constraints come into play. These
+ are properties you can set in the property editor. For example, to override
+ the default \l{QWidget::}{sizeHint()}, simply set
+ \l{QWidget::minimumSize()}{minimumSize} and \l{QWidget::maximumSize()}
+ {maximumSize} to the same value. Alternatively, to use the current size as
+ a size constraint value, choose one of the \gui{Size Constraint} options
+ from the widget's context menu. The layout will then ensure that those
+ constraints are met. To control the size of your widgets via code, you can
+ reimplement \l{QWidget::}{sizeHint()} in your code.
+
+ The screenshot below shows the breakdown of a basic user interface designed
+ using a grid. The coordinates on the screenshot show the position of each
+ widget within the grid.
+
+ \image addressbook-tutorial-part3-labeled-layout.png
+
+ \note Inside the grid, the QPushButton objects are actually nested. The
+ buttons on the right are first placed in a QVBoxLayout; the buttons at the
+ bottom are first placed in a QHBoxLayout. Finally, they are put into
+ coordinates (1,2) and (3,1) of the QGridLayout.
+
+ To visualize, imagine the layout as a box that shrinks as much as possible,
+ attempting to \e squeeze your widgets in a neat arrangement, and, at the
+ same time, maximize the use of available space.
+
+ Qt's layouts help when you:
+
+ \list 1
+ \i Resize the user face to fit different window sizes.
+ \i Resize elements within the user interface to suit different
+ localizations.
+ \i Arrange elements to adhere to layout guidelines for different
+ platforms.
+ \endlist
+
+ So, you no longer have to worry about rearranging widgets for different
+ platforms, settings, and languages.
+
+ The example below shows how different localizations can affect the user
+ interface. When a localization requires more space for longer text strings
+ the Qt layout automatically scales to accommodate this, while ensuring that
+ the user interface looks presentable and still matches the platform
+ guidelines.
+
+ \table
+ \header
+ \i A Dialog in English
+ \i A Dialog in French
+ \row
+ \i \image designer-english-dialog.png
+ \i \image designer-french-dialog.png
+ \endtable
+
+ The process of laying out widgets consists of creating the layout hierarchy
+ while setting as few widget size constraints as possible.
+
+ For a more technical perspective on Qt's layout classes, refer to the
+ \l{Layout Management} documentation.
+*/
+
+
+/*!
+ \page designer-quick-start.html
+ \contentspage {Qt Designer Manual}{Contents}
+
+
+ \title A Quick Start to Qt Designer
+
+ Using \QD involves \bold four basic steps:
+
+ \list 1
+ \o Choose your form and objects
+ \o Lay the objects out on the form
+ \o Connect the signals to the slots
+ \o Preview the form
+ \endlist
+
+ \image rgbController-screenshot.png
+
+ Suppose you would like to design a small widget (see screenshot above) that
+ contains the controls needed to manipulate Red, Green and Blue (RGB) values
+ -- a type of widget that can be seen everywhere in image manipulation
+ programs.
+
+ \table
+ \row
+ \i \inlineimage designer-choosing-form.png
+ \i \bold{Choosing a Form}
+
+ You start by choosing \gui Widget from the \gui{New Form} dialog.
+ \endtable
+
+
+ \table
+ \row
+ \i \inlineimage rgbController-arrangement.png
+ \i \bold{Placing Widgets on a Form}
+
+ Drag three labels, three spin boxes and three vertical sliders on to your
+ form. To change the label's default text, simply double-click on it. You
+ can arrange them according to how you would like them to be laid out.
+ \endtable
+
+ To ensure that they are laid out exactly like this in your program, you
+ need to place these widgets into a layout. We will do this in groups of
+ three. Select the "RED" label. Then, hold down \key Ctrl while you select
+ its corresponding spin box and slider. In the \gui{Form} menu, select
+ \gui{Lay Out in a Grid}.
+
+ \table
+ \row
+ \i \inlineimage rgbController-form-gridLayout.png
+ \i \inlineimage rgbController-selectForLayout.png
+ \endtable
+
+
+ Repeat the step for the other two labels along with their corresponding
+ spin boxes and sliders as well.
+
+ The next step is to combine all three layouts into one \bold{main layout}.
+ The main layout is the top level widget's (in this case, the QWidget)
+ layout. It is important that your top level widget has a layout; otherwise,
+ the widgets on your window will not resize when your window is resized. To
+ set the layout, \gui{Right click} anywhere on your form, outside of the
+ three separate layouts, and select \gui{Lay Out Horizontally}.
+ Alternatively, you could also select \gui{Lay Out in a Grid} -- you will
+ still see the same arrangement (shown below).
+
+ \image rgbController-final-layout.png
+
+ \note Main layouts cannot be seen on the form. To check if you have a main
+ layout installed, try resizing your form; your widgets should resize
+ accordingly. Alternatively, you can take a look at \QD's
+ \gui{Object Inspector}. If your top level widget does not have a layout,
+ you will see the broken layout icon next to it,
+ \inlineimage rgbController-no-toplevel-layout.png
+ .
+
+ When you click on the slider and drag it to a certain value, you want the
+ spin box to display the slider's position. To accomplish this behavior, you
+ need to connect the slider's \l{QAbstractSlider::}{valueChanged()} signal
+ to the spin box's \l{QSpinBox::}{setValue()} slot. You also need to make
+ the reverse connections, e.g., connect the spin box's \l{QSpinBox::}
+ {valueChanged()} signal to the slider's \l{QAbstractSlider::value()}
+ {setValue()} slot.
+
+ To do this, you have to switch to \gui{Edit Signals/Slots} mode, either by
+ pressing \key{F4} or something \gui{Edit Signals/Slots} from the \gui{Edit}
+ menu.
+
+ \table
+ \row
+ \i \inlineimage rgbController-signalsAndSlots.png
+ \i \bold{Connecting Signals to Slots}
+
+ Click on the slider and drag the cursor towards the spin box. The
+ \gui{Configure Connection} dialog, shown below, will pop up. Select the
+ correct signal and slot and click \gui OK.
+ \endtable
+
+ \image rgbController-configure-connection1.png
+
+ Repeat the step (in reverse order), clicking on the spin box and dragging
+ the cursor towards the slider, to connect the spin box's
+ \l{QSpinBox::}{valueChanged()} signal to the slider's
+ \l{QAbstractSlider::value()}{setValue()} slot.
+
+ You can use the screenshot below as a guide to selecting the correct signal
+ and slot.
+
+ \image rgbController-configure-connection2.png
+
+ Now that you have successfully connected the objects for the "RED"
+ component of the RGB Controller, do the same for the "GREEN" and "BLUE"
+ components as well.
+
+ Since RGB values range between 0 and 255, we need to limit the spin box
+ and slider to that particular range.
+
+ \table
+ \row
+ \i \inlineimage rgbController-property-editing.png
+ \i \bold{Setting Widget Properties}
+
+ Click on the first spin box. Within the \gui{Property Editor}, you will
+ see \l{QSpinBox}'s properties. Enter "255" for the
+ \l{QSpinBox::}{maximum} property. Then, click on the first vertical
+ slider, you will see \l{QAbstractSlider}'s properties. Enter "255" for
+ the \l{QAbstractSlider::}{maximum} property as well. Repeat this
+ process for the remaining spin boxes and sliders.
+ \endtable
+
+ Now, we preview your form to see how it would look in your application -
+ press \key{Ctrl + R} or select \gui Preview from the \gui Form menu. Try
+ dragging the slider - the spin box will mirror its value too (and vice
+ versa). Also, you can resize it to see how the layouts that are used to
+ manage the child widgets, respond to different window sizes.
+*/
+
+
+/*!
+ \page designer-editing-mode.html
+ \previouspage Getting to Know Qt Designer
+ \contentspage {Qt Designer Manual}{Contents}
+ \nextpage Using Layouts in Qt Designer
+
+ \title Qt Designer's Editing Modes
+
+ \QD provides four editing modes: \l{Qt Designer's Widget Editing Mode}
+ {Widget Editing Mode}, \l{Qt Designer's Signals and Slots Editing Mode}
+ {Signals and Slots Editing Mode}, \l{Qt Designer's Buddy Editing Mode}
+ {Buddy Editing Mode} and \l{Qt Designer's Tab Order Editing Mode}
+ {Tab Order Editing Mode}. When working with \QD, you will always be in one
+ of these four modes. To switch between modes, simply select it from the
+ \gui{Edit} menu or the toolbar. The table below describes these modes in
+ further detail.
+
+ \table
+ \header \i \i \bold{Editing Modes}
+ \row
+ \i \inlineimage designer-widget-tool.png
+ \i In \l{Qt Designer's Widget Editing Mode}{Edit} mode, we can
+ change the appearance of the form, add layouts, and edit the
+ properties of each widget. To switch to this mode, press
+ \key{F3}. This is \QD's default mode.
+
+ \row
+ \i \inlineimage designer-connection-tool.png
+ \i In \l{Qt Designer's Signals and Slots Editing Mode}
+ {Signals and Slots} mode, we can connect widgets together using
+ Qt's signals and slots mechanism. To switch to this mode, press
+ \key{F4}.
+
+ \row
+ \i \inlineimage designer-buddy-tool.png
+ \i In \l{Qt Designer's Buddy Editing Mode}{Buddy Editing Mode},
+ buddy widgets can be assigned to label widgets to help them
+ handle keyboard focus correctly.
+
+ \row
+ \i \inlineimage designer-tab-order-tool.png
+ \i In \l{Qt Designer's Tab Order Editing Mode}
+ {Tab Order Editing Mode}, we can set the order in which widgets
+ receive the keyboard focus.
+ \endtable
+
+*/
+
+
+/*!
+ \page designer-widget-mode.html
+ \previouspage Qt Designer's Editing Modes
+ \contentspage {Qt Designer Manual}{Contents}
+ \nextpage Qt Designer's Signals and Slots Editing Mode
+
+ \title Qt Designer's Widget Editing Mode
+
+ \image designer-editing-mode.png
+
+ In the Widget Editing Mode, objects can be dragged from the main window's
+ widget box to a form, edited, resized, dragged around on the form, and even
+ dragged between forms. Object properties can be modified interactively, so
+ that changes can be seen immediately. The editing interface is intuitive
+ for simple operations, yet it still supports Qt's powerful layout
+ facilities.
+
+
+ \tableofcontents
+
+ To create and edit new forms, open the \gui File menu and select
+ \gui{New Form...} or press \key{Ctrl+N}. Existing forms can also be edited
+ by selecting \gui{Open Form...} from the \gui File menu or pressing
+ \key{Ctrl+O}.
+
+ At any point, you can save your form by selecting the \gui{Save From As...}
+ option from the \gui File menu. The UI files saved by \QD contain
+ information about the objects used, and any details of signal and slot
+ connections between them.
+
+
+ \section1 Editing A Form
+
+ By default, new forms are opened in widget editing mode. To switch to Edit
+ mode from another mode, select \gui{Edit Widgets} from the \gui Edit menu
+ or press the \key F3 key.
+
+ Objects are added to the form by dragging them from the main widget box
+ and dropping them in the desired location on the form. Once there, they
+ can be moved around simply by dragging them, or using the cursor keys.
+ Pressing the \key Ctrl key at the same time moves the selected widget
+ pixel by pixel, while using the cursor keys alone make the selected widget
+ snap to the grid when it is moved. Objects can be selected by clicking on
+ them with the left mouse button. You can also use the \key Tab key to
+ change the selection.
+
+ ### Screenshot of widget box, again
+
+ The widget box contains objects in a number of different categories, all of
+ which can be placed on the form as required. The only objects that require
+ a little more preparation are the \gui Container widgets. These are
+ described in further detail in the \l{Using Containers in Qt Designer}
+ chapter.
+
+
+ \target SelectingObjects
+ \table
+ \row
+ \i \inlineimage designer-selecting-widget.png
+ \i \bold{Selecting Objects}
+
+ Objects on the form are selected by clicking on them with the left
+ mouse button. When an object is selected, resize handles are shown at
+ each corner and the midpoint of each side, indicating that it can be
+ resized.
+
+ To select additional objects, hold down the \key Shift key and click on
+ them. If more than one object is selected, the current object will be
+ displayed with resize handles of a different color.
+
+ To move a widget within a layout, hold down \key Shift and \key Control
+ while dragging the widget. This extends the selection to the widget's
+ parent layout.
+
+ Alternatively, objects can be selected in the
+ \l{The Object Inspector}{Object Inspector}.
+ \endtable
+
+ When a widget is selected, normal clipboard operations such as cut, copy,
+ and paste can be performed on it. All of these operations can be done and
+ undone, as necessary.
+
+ The following shortcuts can be used:
+
+ \target ShortcutsForEditing
+ \table
+ \header \i Action \i Shortcut \i Description
+ \row
+ \i Cut
+ \i \key{Ctrl+X}
+ \i Cuts the selected objects to the clipboard.
+ \row
+ \i Copy
+ \i \key{Ctrl+C}
+ \i Copies the selected objects to the clipboard.
+ \row
+ \i Paste
+ \i \key{Ctrl+V}
+ \i Pastes the objects in the clipboard onto the form.
+ \row
+ \i Delete
+ \i \key Delete
+ \i Deletes the selected objects.
+ \row
+ \i Clone object
+ \i \key{Ctrl+drag} (leftmouse button)
+ \i Makes a copy of the selected object or group of objects.
+ \row
+ \i Preview
+ \i \key{Ctrl+R}
+ \i Shows a preview of the form.
+ \endtable
+
+ All of the above actions (apart from cloning) can be accessed via both the
+ \gui Edit menu and the form's context menu. These menus also provide
+ funcitons for laying out objects as well as a \gui{Select All} function to
+ select all the objects on the form.
+
+ Widgets are not unique objects; you can make as many copies of them as you
+ need. To quickly duplicate a widget, you can clone it by holding down the
+ \key Ctrl key and dragging it. This allows widgets to be copied and placed
+ on the form more quickly than with clipboard operations.
+
+
+ \target DragAndDrop
+ \table
+ \row
+ \i \inlineimage designer-dragging-onto-form.png
+ \i \bold{Drag and Drop}
+
+ \QD makes extensive use of the drag and drop facilities provided by Qt.
+ Widgets can be dragged from the widget box and dropped onto the form.
+
+ Widgets can also be "cloned" on the form: Holding down \key Ctrl and
+ dragging the widget creates a copy of the widget that can be dragged to
+ a new position.
+
+ It is also possible to drop Widgets onto the \l {The Object Inspector}
+ {Object Inspector} to handle nested layouts easily.
+ \endtable
+
+ \QD allows selections of objects to be copied, pasted, and dragged between
+ forms. You can use this feature to create more than one copy of the same
+ form, and experiment with different layouts in each of them.
+
+
+ \section2 The Property Editor
+
+ The Property Editor always displays properties of the currently selected
+ object on the form. The available properties depend on the object being
+ edited, but all of the widgets provided have common properties such as
+ \l{QObject::}{objectName}, the object's internal name, and
+ \l{QWidget::}{enabled}, the property that determines whether an
+ object can be interacted with or not.
+
+
+ \target EditingProperties
+ \table
+ \row
+ \i \inlineimage designer-property-editor.png
+ \i \bold{Editing Properties}
+
+ The property editor uses standard Qt input widgets to manage the
+ properties of jbects on the form. Textual properties are shown in line
+ edits, integer properties are displayed in spinboxes, boolean
+ properties are displayed in check boxes, and compound properties such
+ as colors and sizes are presented in drop-down lists of input widgets.
+
+ Modified properties are indicated with bold labels. To reset them, click
+ the arrow button on the right.
+
+ Changes in properties are applied to all selected objects that have the
+ same property.
+ \endtable
+
+ Certain properties are treated specially by the property editor:
+
+ \list
+ \o Compound properties -- properties that are made up of more than one
+ value -- are represented as nodes that can be expanded, allowing
+ their values to be edited.
+ \o Properties that contain a choice or selection of flags are edited
+ via combo boxes with checkable items.
+ \o Properties that allow access to rich data types, such as QPalette,
+ are modified using dialogs that open when the properties are edited.
+ QLabel and the widgets in the \gui Buttons section of the widget box
+ have a \c text property that can also be edited by double-clicking
+ on the widget or by pressing \gui F2. \QD interprets the backslash
+ (\\) character specially, enabling newline (\\n) characters to be
+ inserted into the text; the \\\\ character sequence is used to
+ insert a single backslash into the text. A context menu can also be
+ opened while editing, providing another way to insert special
+ characters and newlines into the text.
+ \endlist
+
+
+ \section2 Dynamic Properties
+
+ The property editor can also be used to add new
+ \l{QObject#Dynamic Properties}{dynamic properties} to both standard Qt
+ widgets and to forms themselves. Since Qt 4.4, dynamic properties are added
+ and removed via the property editor's toolbar, shown below.
+
+ \image designer-property-editor-toolbar.png
+
+ To add a dynamic property, clcik on the \gui Add button
+ \inlineimage designer-property-editor-add-dynamic.png
+ . To remove it, click on the \gui Remove button
+ \inlineimage designer-property-editor-remove-dynamic.png
+ instead. You can also sort the properties alphabetically and change the
+ color groups by clickinig on the \gui Configure button
+ \inlineimage designer-property-editor-configure.png
+ .
+
+ \section2 The Object Inspector
+ \table
+ \row
+ \i \inlineimage designer-object-inspector.png
+ \i \bold{The Object Inspector}
+
+ The \gui{Object Inspector} displays a hierarchical list of all the
+ objects on the form that is currently being edited. To show the child
+ objects of a container widget or a layout, click the handle next to the
+ object label.
+
+ Each object on a form can be selected by clicking on the corresponding
+ item in the \gui{Object Inspector}. Right-clicking opens the form's
+ context menu. These features can be useful if you have many overlapping
+ objects. To locate an object in the \gui{Object Inspector}, use
+ \key{Ctrl+F}.
+
+ Since Qt 4.4, double-clicking on the object's name allows you to change
+ the object's name with the in-place editor.
+
+ Since Qt 4.5, the \gui{Object Inspector} displays the layout state of
+ the containers. The broken layout icon ###ICON is displayed if there is
+ something wrong with the layouts.
+
+ \endtable
+*/
+
+
+/*!
+ \page designer-layouts.html
+ \previouspage Qt Designer's Widget Editing Mode
+ \contentspage
+ \nextpage Qt Designer's Signals and Slots Editing Mode
+
+ \title Using Layouts in Qt Designer
+
+ Before a form can be used, the objects on the form need to be placed into
+ layouts. This ensures that the objects will be displayed properly when the
+ form is previewed or used in an application. Placing objects in a layout
+ also ensures that they will be resized correctly when the form is resized.
+
+
+ \tableofcontents
+
+ \section1 Applying and Breaking Layouts
+
+ The simplest way to manage objects is to apply a layout to a group of
+ existing objects. This is achieved by selecting the objects that you need
+ to manage and applying one of the standard layouts using the main toolbar,
+ the \gui Form menu, or the form's context menu.
+
+ Once widgets have been inserted into a layout, it is not possible to move
+ and resize them individually because the layout itself controls the
+ geometry of each widget within it, taking account of the hints provided by
+ spacers. Instead, you must either break the layout and adjust each object's
+ geometry manually, or you can influence the widget's geometry by resizing
+ the layout.
+
+ To break the layout, press \key{Ctrl+0} or choose \gui{Break Layout} from
+ the form's context menu, the \gui Form menu or the main toolbar. You can
+ also add and remove spacers from the layout to influence the geometries of
+ the widgets.
+
+
+ \target InsertingObjectsIntoALayout
+ \table
+ \row
+ \i \inlineimage designer-layout-inserting.png
+ \i \bold{Inserting Objects into a Layout}
+
+ Objects can be inserted into an existing layout by dragging them from
+ their current positions and dropping them at the required location. A
+ blue cursor is displayed in the layout as an object is dragged over
+ it to indicate where the object will be added.
+ \endtable
+
+
+ \section2 Setting A Top Level Layout
+
+ The form's top level layout can be set by clearing the slection (click the
+ left mouse button on the form itself) and applying a layout. A top level
+ layout is necessary to ensure that your widgets will resize correctly when
+ its window is resized. To check if you have set a top level layout, preview
+ your widget and attempt to resize the window by dragging the size grip.
+
+ \table
+ \row
+ \i \inlineimage designer-set-layout.png
+ \i \bold{Applying a Layout}
+
+ To apply a layout, you can select your choice of layout from the
+ toolbar shown on the left, or from the context menu shown below.
+ \endtable
+
+ \image designer-set-layout2.png
+
+
+ \section2 Horizontal and Vertical Layouts
+
+ The simplest way to arrange objects on a form is to place them in a
+ horizontal or vertical layout. Horizontal layouts ensure that the widgets
+ within are aligned horizontally; vertical layouts ensure that they are
+ aligned vertically.
+
+ Horizontal and vertical layouts can be combined and nested to any depth.
+ However, if you need more control over the placement of objects, consider
+ using the grid layout.
+
+
+ \section3 The Grid Layout
+
+ Complex form layouts can be created by placing objects in a grid layout.
+ This kind of layout gives the form designer much more freedom to arrange
+ widgets on the form, but can result in a much less flexible layout.
+ However, for some kinds of form layout, a grid arrangement is much more
+ suitable than a nested arrangement of horizontal and vertical layouts.
+
+
+ \section3 Splitter Layouts
+
+ Another common way to manage the layout of objects on a form is to place
+ them in a splitter. These splitters arrange the objects horizontally or
+ vertically in the same way as normal layouts, but also allow the user to
+ adjust the amount of space allocated to each object.
+
+ \image designer-splitter-layout.png
+
+ Although QSplitter is a container widget, \QD treats splitter objects as
+ layouts that are applied to existing widgets. To place a group of widgets
+ into a splitter, select them
+ \l{Qt Designer's Widget Editing Mode#SelectingObjects}{as described here}
+ then apply the splitter layout by using the appropriate toolbar button,
+ keyboard shortcut, or \gui{Lay out} context menu entry.
+
+
+ \section3 The Form Layout
+
+ Since Qt 4.4, another layout class has been included -- QFormLayout. This
+ class manages widgets in a two-column form; the left column holds labels
+ and the right column holds field widgets such as line edits, spin boxes,
+ etc. The QFormLayout class adheres to various platform look and feel
+ guidelines and supports wrapping for long rows.
+
+ \image designer-form-layout.png
+
+ The UI file above results in the previews shown below.
+
+ \table
+ \header
+ \i Windows XP
+ \i Mac OS X
+ \i Cleanlooks
+ \row
+ \i \inlineimage designer-form-layout-windowsXP.png
+ \i \inlineimage designer-form-layout-macintosh.png
+ \i \inlineimage designer-form-layout-cleanlooks.png
+ \endtable
+
+
+ \section2 Shortcut Keys
+
+ In addition to the standard toolbar and context menu entries, there is also
+ a set of keyboard shortcuts to apply layouts on widgets.
+
+ \target LayoutShortcuts
+ \table
+ \header
+ \i Layout
+ \i Shortcut
+ \i Description
+ \row
+ \i Horizontal
+ \i \key{Ctrl+1}
+ \i Places the selected objects in a horizontal layout.
+ \row
+ \i Vertical
+ \i \key{Ctrl+2}
+ \i Places the selected objects in a vertical layout.
+ \row
+ \i Grid
+ \i \key{Ctrl+5}
+ \i Places the selected objects in a grid layout.
+ \row
+ \i Form
+ \i \key{Ctrl+6}
+ \i Places the selected objects in a form layout.
+ \row
+ \i Horizontal splitter
+ \i \key{Ctrl+3}
+ \i Creates a horizontal splitter and places the selected objects
+ inside it.
+ \row
+ \i Vertical splitter
+ \i \key{Ctrl+4}
+ \i Creates a vertical splitter and places the selected objects
+ inside it.
+ \row
+ \i Adjust size
+ \i \key{Ctrl+J}
+ \i Adjusts the size of the layout to ensure that each child object
+ has sufficient space to display its contents. See
+ QWidget::adjustSize() for more information.
+ \endtable
+
+ \note \key{Ctrl+0} is used to break a layout.
+
+*/
+
+
+/*!
+ \page designer-preview.html
+ \contentspage {Qt Designer Manual}{Contents}
+ \previouspage Using Layouts in Qt Designer
+ \nextpage Qt Designer's Buddy Editing Mode
+ \title Saving, Previewing and Printing Forms in Qt Designer
+
+ Although \QD's forms are accurate representations of the components being
+ edited, it is useful to preview the final appearance while editing. This
+ feature can be activated by opening the \gui Form menu and selecting
+ \gui Preview, or by pressing \key{Ctrl+R} when in the form.
+
+ \image designer-dialog-preview.png
+
+ The preview shows exactly what the final component will look like when used
+ in an application.
+
+ Since Qt 4.4, it is possible to preview forms with various skins - default
+ skins, skins created with Qt Style Sheets or device skins. This feature
+ simulates the effect of calling \c{QApplication::setStyleSheet()} in the
+ application.
+
+ To preview your form with skins, open the \gui Edit menu and select
+ \gui{Preferences...}
+
+ You will see the dialog shown below:
+
+ \image designer-preview-style.png
+
+ The \gui{Print/Preview Configuration} checkbox must be checked to activate
+ previews of skins. You can select the styles provided from the \gui{Style}
+ drop-down box.
+
+ \image designer-preview-style-selection.png
+
+ Alternatively, you can preview custom style sheet created with Qt Style
+ Sheets. The figure below shows an example of Qt Style Sheet syntax and the
+ corresponding output.
+
+ \image designer-preview-stylesheet.png
+
+ Another option would be to preview your form with device skins. A list of
+ generic device skins are available in \QD, however, you may also use
+ other QVFB skins with the \gui{Browse...} option.
+
+ \image designer-preview-deviceskin-selection.png
+
+
+ \section1 Viewing the Form's Code
+
+ Since Qt 4.4, it is possible to view code generated by the User Interface
+ Compiler (uic) for the \QD form.
+
+ \image designer-form-viewcode.png
+
+ Select \gui{View Code...} from the \gui{Form} menu and a dialog with the
+ generated code will be displayed. The screenshot below is an example of
+ code generated by the \c{uic}.
+
+ \image designer-code-viewer.png
+
+ \section1 Saving and Printing the Form
+
+ Forms created in \QD can be saved to an image or printed.
+
+ \table
+ \row
+ \i \inlineimage designer-file-menu.png
+ \i \bold{Saving Forms}
+
+ To save a form as an image, choose the \gui{Save Image...} option. The file
+ will be saved in \c{.png} format.
+
+ \bold{Printing Forms}
+
+ To print a form, select the \gui{Print...} option.
+
+ \endtable
+*/
+
+
+/*!
+ \page designer-connection-mode.html
+ \contentspage {Qt Designer Manual}{Contents}
+ \previouspage Using Layouts in Qt Designer
+ \nextpage Qt Designer's Buddy Editing Mode
+
+
+ \title Qt Designer's Signals and Slots Editing Mode
+
+ \image designer-connection-mode.png
+
+ In \QD's signals and slots editing mode, you can connect objects in a form
+ together using Qt's signals and slots mechanism. Both widgets and layouts
+ can be connected via an intuitive connection interface, using the menu of
+ compatible signals and slots provided by \QD. When a form is saved, all
+ connections are preserved so that they will be ready for use when your
+ project is built.
+
+
+ \tableofcontents
+
+ For more information on Qt's signals and sltos mechanism, refer to the
+ \l{Signals and Slots} document.
+
+
+ \section1 Connecting Objects
+
+ To begin connecting objects, enter the signals and slots editing mode by
+ opening the \gui Edit menu and selecting \gui{Edit Signals/Slots}, or by
+ pressing the \key F4 key.
+
+ All widgets and layouts on the form can be connected together. However,
+ spacers just provide spacing hints to layouts, so they cannot be connected
+ to other objects.
+
+
+ \target HighlightedObjects
+ \table
+ \row
+ \i \inlineimage designer-connection-highlight.png
+ \i \bold{Highlighted Objects}
+
+ When the cursor is over an object that can be used in a connection, the
+ object will be highlighted.
+ \endtable
+
+ To make a connectionn, press the left mouse button and drag the cursor
+ towards the object you want to connect it to. As you do this, a line will
+ extend from the source object to the cursor. If the cursor is over another
+ object on the form, the line will end with an arrow head that points to the
+ destination object. This indicates that a connection will be made between
+ the two objects when you release the mouse button.
+
+ You can abandon the connection at any point while you are dragging the
+ connection path by pressing \key{Esc}.
+
+ \target MakingAConnection
+ \table
+ \row
+ \i \inlineimage designer-connection-making.png
+ \i \bold{Making a Connection}
+
+ The connection path will change its shape as the cursor moves around
+ the form. As it passes over objects, they are highlighted, indicating
+ that they can be used in a signal and slot connection. Release the
+ mouse button to make the connection.
+ \endtable
+
+ The \gui{Configure Connection} dialog (below) is displayed, showing signals
+ from the source object and slots from the destination object that you can
+ use.
+
+ \image designer-connection-dialog.png
+
+ To complete the connection, select a signal from the source object and a
+ slot from the destination object, then click \key OK. Click \key Cancel if
+ you wish to abandon the connection.
+
+ \note If the \gui{Show all signals and slots} checkbox is selected, all
+ available signals from the source object will be shown. Otherwise, the
+ signals and slots inherited from QWidget will be hidden.
+
+ You can make as many connections as you like between objects on the form;
+ it is possible to connect signals from objects to slots in the form itself.
+ As a result, the signal and slot connections in many dialogs can be
+ completely configured from within \QD.
+
+ \target ConnectingToTheForm
+ \table
+ \row
+ \i \inlineimage designer-connection-to-form.png
+ \i \bold{Connecting to a Form}
+
+ To connect an object to the form itself, simply position the cursor
+ over the form and release the mouse button. The end point of the
+ connection changes to the electrical "ground" symbol.
+ \endtable
+
+
+ \section1 Editing and Deleting Connections
+
+ By default, connection paths are created with two labels that show the
+ signal and slot involved in the connection. These labels are usually
+ oriented along the line of the connection. You can move them around inside
+ their host widgets by dragging the red square at each end of the connection
+ path.
+
+ \target ConnectionEditor
+ \table
+ \row
+ \i \inlineimage designer-connection-editor.png
+ \i \bold{The Signal/Slot Editor}
+
+ The signal and slot used in a connection can be changed after it has
+ been set up. When a connection is configured, it becomes visible in
+ \QD's signal and slot editor where it can be further edited. You can
+ also edit signal/slot connections by double-clicking on the connection
+ path or one of its labels to display the Connection Dialog.
+ \endtable
+
+ \target DeletingConnections
+ \table
+ \row
+ \i \inlineimage designer-connection-editing.png
+ \i \bold{Deleting Connections}
+
+ The whole connection can be selected by clicking on any of its path
+ segments. Once selected, a connection can be deleted with the
+ \key Delete key, ensuring that it will not be set up in the UI
+ file.
+ \endtable
+*/
+
+
+/*!
+ \page designer-buddy-mode.html
+ \contentspage{Qt Designer Manual}{Contents}
+ \previouspage Qt Designer's Signals and Slots Editing Mode
+ \nextpage Qt Designer's Tab Order Editing Mode
+
+ \title Qt Designer's Buddy Editing Mode
+
+ \image designer-buddy-mode.png
+
+ One of the most useful basic features of Qt is the support for buddy
+ widgets. A buddy widget accepts the input focus on behalf of a QLabel when
+ the user types the label's shortcut key combination. The buddy concept is
+ also used in Qt's \l{Model/View Programming}{model/view} framework.
+
+
+ \section1 Linking Labels to Buddy Widgets
+
+ To enter buddy editing mode, open the \gui Edit menu and select
+ \gui{Edit Buddies}. This mode presents the widgets on the form in a similar
+ way to \l{Qt Designer's Signals and Slots Editing Mode}{signals and slots
+ editing mode} but in this mode, connections must start at label widgets.
+ Ideally, you should connect each label widget that provides a shortcut with
+ a suitable input widget, such as a QLineEdit.
+
+
+ \target MakingBuddies
+ \table
+ \row
+ \i \inlineimage designer-buddy-making.png
+ \i \bold{Making Buddies}
+
+ To define a buddy widget for a label, click on the label, drag the
+ connection to another widget on the form, and release the mouse button.
+ The connection shown indicates how input focus is passed to the buddy
+ widget. You can use the form preview to test the connections between
+ each label and its buddy.
+ \endtable
+
+
+ \section1 Removing Buddy Connections
+
+ Only one buddy widget can be defined for each label. To change the buddy
+ used, it is necessary to delete any existing buddy connection before you
+ create a new one.
+
+ Connections between labels and their buddy widgets can be deleted in the
+ same way as signal-slot connections in signals and slots editing mode:
+ Select the buddy connection by clicking on it and press the \key Delete
+ key. This operation does not modify either the label or its buddy in any
+ way.
+*/
+
+
+/*!
+ \page designer-tab-order.html
+ \contentspage {Qt Designer Manual}{Contents}
+ \previouspage Qt Designer's Buddy Editing Mode
+ \nextpage Using Containers in Qt Designer
+
+ \title Qt Designer's Tab Order Editing Mode
+
+ \image designer-tab-order-mode.png
+
+ Many users expect to be able to navigate between widgets and controls
+ using only the keyboard. Qt lets the user navigate between input widgets
+ with the \key Tab and \key{Shift+Tab} keyboard shortcuts. The default
+ \e{tab order} is based on the order in which widgets are constructed.
+ Although this order may be sufficient for many users, it is often better
+ to explicitly specify the tab order to make your application easier to
+ use.
+
+
+ \section1 Setting the Tab Order
+
+ To enter tab order editing mode, open the \gui Edit menu and select
+ \gui{Edit Tab Order}. In this mode, each input widget in the form is shown
+ with a number indicating its position in the tab order. So, if the user
+ gives the first input widget the input focus and then presses the tab key,
+ the focus will move to the second input widget, and so on.
+
+ The tab order is defined by clicking on each of the numbers in the correct
+ order. The first number you click will change to red, indicating the
+ currently edited position in the tab order chain. The widget associated
+ with the number will become the first one in the tab order chain. Clicking
+ on another widget will make it the second in the tab order, and so on.
+
+ Repeat this process until you are satisfied with the tab order in the form
+ -- you do not need to click every input widget if you see that the
+ remaining widgets are already in the correct order. Numbers, for which you
+ already set the order, change to green, while those which are not clicked
+ yet, remain blue.
+
+ If you make a mistake, simply double click outside of any number or choose
+ \gui{Restart} from the form's context menu to start again. If you have many
+ widgets on your form and would like to change the tab order in the middle or
+ at the end of the tab order chain, you can edit it at any position. Press
+ \key{Ctrl} and click the number from which you want to start.
+ Alternatively, choose \gui{Start from Here} in the context menu.
+
+*/
+
+
+/*!
+ \page designer-using-containers.html
+ \contentspage {Qt Designer Manual}{Contents}
+ \previouspage Qt Designer's Tab Order Editing Mode
+ \nextpage Creating Main Windows in Qt Designer
+
+
+ \title Using Containers in Qt Designer
+
+ Container widgets provide high level control over groups of objects on a
+ form. They can be used to perform a variety of functions, such as managing
+ input widgets, providing paged and tabbed layouts, or just acting as
+ decorative containers for other objects.
+
+ \image designer-widget-morph.png
+
+ \QD provides visual feedback to help you place objects inside your
+ containers. When you drag an object from the widget box (or elsewhere) on
+ the form, each container will be highlighted when the cursor is positioned
+ over it. This indicates that you can drop the object inside, making it a
+ child object of the container. This feedback is important because it is
+ easy to place objects close to containers without actually placing them
+ inside. Both widgets and spacers can be used inside containers.
+
+ Stacked widgets, tab widgets, and toolboxes are handled specially in \QD.
+ Normally, when adding pages (tabs, pages, compartments) to these containers
+ in your own code, you need to supply existing widgets, either as
+ placeholders or containing child widgets. In \QD, these are automatically
+ created for you, so you can add child objects to each page straight away.
+
+ Each container typically allows its child objects to be arranged in one or
+ more layouts. The type of layout management provided depends on each
+ container, although setting the layout is usually just a matter of
+ selecting the container by clicking it, and applying a layout. The table
+ below shows a list of available containers.
+
+ \table
+ \row
+ \i \inlineimage designer-containers-frame.png
+ \i \bold Frames
+
+ Frames are used to enclose and group widgets, as well as to provide
+ decoration. They are used as the foundation for more complex
+ containers, but they can also be used as placeholders in forms.
+
+ The most important properties of frames are \c frameShape,
+ \c frameShadow, \c lineWidth, and \c midLineWidth. These are described
+ in more detail in the QFrame class description.
+
+ \row
+ \i \inlineimage designer-containers-groupbox.png
+ \i \bold{Group Boxes}
+
+ Group boxes are usually used to group together collections of
+ checkboxes and radio buttons with similar purposes.
+
+ Among the significant properties of group boxes are \c title, \c flat,
+ \c checkable, and \c checked. These are demonstrated in the
+ \l{widgets/groupbox}{Group Box} example, and described in the QGroupBox
+ class documentation. Each group box can contain its own layout, and
+ this is necessary if it contains other widgets. To add a layout to the
+ group box, click inside it and apply the layout as usual.
+
+ \row
+ \i \inlineimage designer-containers-stackedwidget.png
+ \i \bold{Stacked Widgets}
+
+ Stacked widgets are collections of widgets in which only the topmost
+ layer is visible. Control over the visible layer is usually managed by
+ another widget, such as combobox, using signals and slots.
+
+ \QD shows arrows in the top-right corner of the stack to allow you to
+ see all the widgets in the stack when designing it. These arrows do not
+ appear in the preview or in the final component. To navigate between
+ pages in the stack, select the stacked widget and use the
+ \gui{Next Page} and \gui{Previous Page} entries from the context menu.
+ The \gui{Insert Page} and \gui{Delete Page} context menu options allow
+ you to add and remove pages.
+
+ \row
+ \i \inlineimage designer-containers-tabwidget.png
+ \i \bold{Tab Widgets}
+
+ Tab widgets allow the developer to split up the contents of a widget
+ into different labelled sections, only one of which is displayed at any
+ given time. By default, the tab widget contains two tabs, and these can
+ be deleted or renamed as required. You can also add additional tabs.
+
+ To delete a tab:
+ \list
+ \o Click on its label to make it the current tab.
+ \o Select the tab widget and open its context menu.
+ \o Select \gui{Delete Page}.
+ \endlist
+
+ To add a new tab:
+ \list
+ \o Select the tab widget and open its context menu.
+ \o Select \gui{Insert Page}.
+ \o You can add a page before or after the \e current page. \QD
+ will create a new widget for that particular tab and insert it
+ into the tab widget.
+ \o You can set the title of the current tab by changing the
+ \c currentTabText property in the \gui{Property Editor}.
+ \endlist
+
+ \row
+ \i \inlineimage designer-containers-toolbox.png
+ \i \bold{ToolBox Widgets}
+
+ Toolbox widgets provide a series of pages or compartments in a toolbox.
+ They are handled in a way similar to stacked widgets.
+
+ To rename a page in a toolbox, make the toolbox your current pange and
+ change its \c currentItemText property from the \gui{Property Editor}.
+
+ To add a new page, select \gui{Insert Page} from the toolbox widget's
+ context menu. You can add the page before or after the current page.
+
+ To delete a page, select \gui{Delete Page} from the toolbox widget's
+ context menu.
+
+ \row
+ \i \inlineimage designer-containers-dockwidget.png
+ \i \bold{Dock Widgets}
+
+ Dock widgets are floating panels, often containing input widgets and
+ more complex controls, that are either attached to the edges of the
+ main window in "dock areas", or floated as independent tool windows.
+
+ Although dock widgets can be added to any type of form, they are
+ typically used with forms created from the
+ \l{Creating Main Windows in Qt Designer}{main window template}.
+
+ \endtable
+*/
+
+
+/*!
+ \page designer-creating-mainwindows.html
+ \contentspage {Qt Designer Manual}{Contents}
+ \previouspage Using Containers in Qt Designer
+ \nextpage Editing Resources with Qt Designer
+
+ \title Creating Main Windows in Qt Designer
+
+ \QD can be used to create user interfaces for different purposes, and
+ it provides different kinds of form templates for each user interface. The
+ main window template is used to create application windows with menu bars,
+ toolbars, and dock widgets.
+
+ \omit
+ \image designer-mainwindow-example.png
+ \endomit
+
+ Create a new main window by opening the \gui File menu and selecting the
+ \gui{New Form...} option, or by pressing \key{Ctrl+N}. Then, select the
+ \gui{Main Window} template. This template provides a main application
+ window containing a menu bar and a toolbar by default -- these can be
+ removed if they are not required.
+
+ If you remove the menu bar, a new one can be created by selecting the
+ \gui{Create Menu Bar} option from the context menu, obtained by
+ right-clicking within the main window form.
+
+ An application can have only \bold one menu bar, but \bold several
+ toolbars.
+
+
+ \section1 Menus
+
+ Menus are added to the menu bar by modifying the \gui{Type Here}
+ placeholders. One of these is always present for editing purposes, and
+ will not be displayed in the preview or in the finished window.
+
+ Once created, the properties of a menu can be accessed using the
+ \l{Qt Designer's Widget Editing Mode#The Property Editor}{Property Editor},
+ and each menu can be accessed for this purpose via the
+ \l{Qt Designer's Widget Editing Mode#The Object Inspector}{The Object Inspector}.
+
+ Existing menus can be removed by opening a context menu over the label in
+ the menu bar, and selecting \gui{Remove Menu 'menu_name'}.
+
+
+ \target CreatingAMenu
+ \table
+ \row
+ \i \inlineimage designer-creating-menu1.png
+ \i \inlineimage designer-creating-menu2.png
+ \i \bold{Creating a Menu}
+
+ Double-click the placeholder item to begin editing. The menu text,
+ displayed using a line edit, can be modified.
+
+ \row
+ \i \inlineimage designer-creating-menu3.png
+ \i \inlineimage designer-creating-menu4.png
+ \i Insert the required text for the new menu. Inserting an
+ ampersand character (&) causes the letter following it to be
+ used as a mnemonic for the menu.
+
+ Press \key Return or \key Enter to accept the new text, or press
+ \key Escape to reject it. You can undo the editing operation later if
+ required.
+ \endtable
+
+ Menus can also be rearranged in the menu bar simply by dragging and
+ dropping them in the preferred location. A vertical red line indicates the
+ position where the menu will be inserted.
+
+ Menus can contain any number of entries and separators, and can be nested
+ to the required depth. Adding new entries to menus can be achieved by
+ navigating the menu structure in the usual way.
+
+ \target CreatingAMenuEntry
+ \table
+ \row
+ \i \inlineimage designer-creating-menu-entry1.png
+ \i \inlineimage designer-creating-menu-entry2.png
+ \i \bold{Creating a Menu Entry}
+
+ Double-click the \gui{new action} placeholder to begin editing, or
+ double-click \gui{new separator} to insert a new separator line after
+ the last entry in the menu.
+
+ The menu entry's text is displayed using a line edit, and can be
+ modified.
+
+ \row
+ \i \inlineimage designer-creating-menu-entry3.png
+ \i \inlineimage designer-creating-menu-entry4.png
+ \i Insert the required text for the new entry, optionally using
+ the ampersand character (&) to mark the letter to use as a
+ mnemonic for the entry.
+
+ Press \key Return or \key Enter to accept the new text, or press
+ \key Escape to reject it. The action created for this menu entry will
+ be accessible via the \l{#TheActionEditor}{Action Editor}, and any
+ associated keyboard shortcut can be set there.
+ \endtable
+
+ Just like with menus, entries can be moved around simply by dragging and
+ dropping them in the preferred location. When an entry is dragged over a
+ closed menu, the menu will open to allow it to be inserted there. Since
+ menu entries are based on actions, they can also be dropped onto toolbars,
+ where they will be displayed as toolbar buttons.
+
+
+ \section1 Toolbars
+
+
+ ### SCREENSHOT
+
+ Toolbars ared added to a main window in a similar way to the menu bar:
+ Select the \gui{Add Tool Bar} option from the form's context menu.
+ Alternatively, if there is an existing toolbar in the main window, you can
+ click the arrow on its right end to create a new toolbar.
+
+ Toolbar buttons are created using the action system to populate each
+ toolbar, rather than by using specific button widgets from the widget box.
+ Since actions can be represented by menu entries and toolbar buttons, they
+ can be moved between menus and toolbars. To share an action between a menu
+ and a toolbar, drag its icon from the \l{#TheActionEditor}{Action Editor}
+ to the toolbar rather than from the menu where its entry is located.
+
+ New actions for menus and toolbars can be created in the
+ \l{#TheActionEditor}{Action Editor}.
+
+
+ \section1 Actions
+
+ With the menu bar and the toolbars in place, it's time to populate them
+ with action: \QD provides an action editor to simplify the creation and
+ management of actions.
+
+
+ \target TheActionEditor
+ \table
+ \row
+ \i \inlineimage designer-action-editor.png
+ \i \bold{The Action Editor}
+
+ Enable the action editor by opening the \gui Tools menu, and switching
+ on the \gui{Action Editor} option.
+
+ The action editor allows you to create \gui New actions and \gui Delete
+ actions. It also provides a search function, \gui Filter, using the
+ action's text.
+
+ \QD's action editor can be viewed in the classic \gui{Icon View} and
+ \gui{Detailed View}. The screenshot below shows the action editor in
+ \gui{Detailed View}. You can also copy and paste actions between menus,
+ toolbars and forms.
+ \endtable
+
+ To create an action, use the action editor's \gui New button, which will
+ then pop up an input dialog. Provide the new action with a \gui Text --
+ this is the text that will appear in a menu entry and as the action's
+ tooltip. The text is also automatically added to an "action" prefix,
+ creating the action's \gui{Object Name}.
+
+ In addition, the dialog provides the option of selecting an \gui Icon for
+ the action, as well as removing the current icon.
+
+ Once the action is created, it can be used wherever actions are applicable.
+
+
+ \target AddingAnAction
+ \table
+ \row
+ \i \inlineimage designer-adding-menu-action.png
+ \i \inlineimage designer-adding-toolbar-action.png
+ \i \bold{Adding an Action}
+
+ To add an action to a menu or a toolbar, simply press the left mouse
+ button over the action in the action editor, and drag it to the
+ preferred location.
+
+ \QD provides highlighted guide lines that tell you where the action
+ will be added. Release the mouse button to add the action when you have
+ found the right spot.
+ \endtable
+
+
+ \section1 Dock Widgets
+
+ Since dock widgets are \l{Using Containers in Qt Designer}
+ {container widgets}, they can be added to a form in the usuasl way. Once
+ added to a form, dock widgets are not placed in any particular dock area by
+ default; you need to set the \gui{docked} property to true for each widget
+ and choose an appropriate value for its \gui{dockWidgetArea} property.
+
+ \target AddingADockWidget
+ \table
+ \row
+ \i \inlineimage designer-adding-dockwidget.png
+ \i \bold{Adding a Dock Widget}
+
+ To add a dock widget, simply drag one from the \gui Containers section
+ of the widget box, and drop it onto the main form area. Just like other
+ widgets, its properties can be modified with the \gui{Property Editor}.
+
+ Dock widgets can be optionally floated as indpendent tool windows.
+ Hence, it is useful to give them window titles by setting their
+ \gui{windowTitle} property. This also helps to identify them on the
+ form.
+
+ \endtable
+*/
+
+
+/*!
+ \page designer-resources.html
+ \contentspage {Qt Designer Manual}{Contents}
+ \previouspage Creating Main Windows in Qt Designer
+ \nextpage Using Stylesheets with Qt Designer
+
+ \title Editing Resources with Qt Designer
+
+ \image designer-resources-editing.png
+
+ \QD fully supports the \l{The Qt Resource System}{Qt Resource System},
+ enabling resources to be specified together with forms as they are
+ designed. To aid designers and developers manage resources for their
+ applications, \QD's resource editor allows resources to be defined on a
+ per-form basis. In other words, each form can have a separate resource
+ file.
+
+ \section1 Defining a Resource File
+
+ To specify a resource file you must enable the resource editor by opening
+ the \gui Tools menu, and switching on the \gui{Resource Browser} option.
+
+ \target ResourceFiles
+ \table
+ \row
+ \i \inlineimage designer-resource-browser.png
+ \i \bold{Resource Files}
+
+ Within the resource browser, you can open existing resource files or
+ create new ones. Click the \gui{Edit Resources} button
+ \inlineimage designer-edit-resources-button.png
+ to edit your resources. To reload resources, click on the \gui Reload
+ button
+ \inlineimage designer-reload-resources-button.png
+ .
+ \endtable
+
+
+ Once a resource file is loaded, you can create or remove entries in it
+ using the given \gui{Add Files}
+ \inlineimage designer-add-resource-entry-button.png
+ and \gui{Remove Files}
+ \inlineimage designer-remove-resource-entry-button.png
+ buttons, and specify resources (e.g., images) using the \gui{Add Files}
+ button
+ \inlineimage designer-add-files-button.png
+ . Note that these resources must reside within the current resource file's
+ directory or one of its subdirectories.
+
+
+ \target EditResource
+ \table
+ \row
+ \i \inlineimage designer-edit-resource.png
+ \i \bold{Editing Resource Files}
+
+ Press the
+ \inlineimage designer-add-resource-entry-button.png
+ button to add a new resource entry to the file. Then use the
+ \gui{Add Files} button
+ \inlineimage designer-add-files-button.png
+ to specify the resource.
+
+ You can remove resources by selecting the corresponding entry in the
+ resource editor, and pressing the
+ \inlineimage designer-remove-resource-entry-button.png
+ button.
+ \endtable
+
+
+ \section1 Using the Resources
+
+ Once the resources are defined you can use them actively when composing
+ your form. For example, you might want to create a tool button using an
+ icon specified in the resource file.
+
+ \target UsingResources
+ \table
+ \row
+ \i \inlineimage designer-resources-using.png
+ \i \bold{Using Resources}
+
+ When changing properties with values that may be defined within a
+ resource file, \QD's property editor allows you to specify a resource
+ in addition to the option of selecting a source file in the ordinary
+ way.
+
+ \row
+ \i \inlineimage designer-resource-selector.png
+ \i \bold{Selecting a Resource}
+
+ You can open the resource selector by clicking \gui{Choose Resource...}
+ to add resources any time during the design process.
+
+\omit
+... check with Friedemann
+To quickly assign icon pixmaps to actions or pixmap properties, you may
+drag the pixmap from the resource editor to the action editor, or to the
+pixmap property in the property editor.
+\endomit
+
+ \endtable
+*/
+
+
+/*!
+ \page designer-stylesheet.html
+ \contentspage {Qt Designer Manual}{Contents}
+ \previouspage Editing Resources with Qt Designer
+ \nextpage Using a Designer UI File in Your Application
+
+ \title Using Stylesheets with Qt Designer
+
+ Since Qt 4.2, it is possible to edit stylesheets in \QD with the stylesheet
+ editor.
+
+ \target UsingStylesheets
+ \table
+ \row
+ \i \inlineimage designer-stylesheet-options.png
+ \bold{Setting a Stylesheet}
+
+ The stylesheet editor can be accessed by right-clicking a widget
+ and selecting \gui{Change styleSheet...}
+
+ \row
+ \i \inlineimage designer-stylesheet-usage.png
+ \endtable
+
+*/
+
+
+/*!
+ \page designer-using-a-ui-file.html
+ \previouspage Using Stylesheets with Qt Designer
+ \contentspage {Qt Designer Manual}{Contents}
+ \nextpage Using Custom Widgets with Qt Designer
+
+ \title Using a Designer UI File in Your Application
+
+ With Qt's integrated build tools, \l{qmake Manual}{qmake} and \l uic, the
+ code for user interface components created with \QD is automatically
+ generated when the rest of your application is built. Forms can be included
+ and used directly from your application. Alternatively, you can use them to
+ extend subclasses of standard widgets. These forms can be processed at
+ compile time or at run time, depending on the approach used.
+
+
+ \tableofcontents
+ \section1 Compile Time Form Processing
+
+ A compile time processed form can be used in your application with one of
+ the following approaches:
+
+ \list
+ \o The Direct Approach: you construct a widget to use as a placeholder
+ for the component, and set up the user interface inside it.
+ \o The Single Inheritance Approach: you subclass the form's base class
+ (QWidget or QDialog, for example), and include a private instance
+ of the form's user interface object.
+ \o The MultipleInheritance Approach: you subclass both the form's base
+ class and the form's user interface object. This allows the widgets
+ defined in the form to be used directly from within the scope of
+ the subclass.
+ \endlist
+
+
+ \section2 The Direct Approach
+
+ To demonstrate how to use user interface (UI) files straight from
+ \QD, we create a simple Calculator Form application. This is based on the
+ original \l{Calculator Form Example}{Calculator Form} example.
+
+ The application consists of one source file, \c main.cpp and a UI
+ file.
+
+ The \c{calculatorform.ui} file designed with \QD is shown below:
+
+ \image directapproach-calculatorform.png
+
+ We will use \c qmake to build the executable, so we need to write a
+ \c{.pro} file:
+
+ \snippet doc/src/snippets/uitools/calculatorform/calculatorform.pro 0
+
+ The special feature of this file is the \c FORMS declaration that tells
+ \c qmake which files to process with \c uic. In this case, the
+ \c calculatorform.ui file is used to create a \c ui_calculatorform.h file
+ that can be used by any file listed in the \c SOURCES declaration. To
+ ensure that \c qmake generates the \c ui_calculatorform.h file, we need to
+ include it in a file listed in \c SOURCES. Since we only have \c main.cpp,
+ we include it there:
+
+ \snippet doc/src/snippets/uitools/calculatorform/main.cpp 0
+
+ This include is an additional check to ensure that we do not generate code
+ for UI files that are not used.
+
+ The \c main function creates the calculator widget by constructing a
+ standard QWidget that we use to host the user interface described by the
+ \c calculatorform.ui file.
+
+ \snippet doc/src/snippets/uitools/calculatorform/main.cpp 1
+
+ In this case, the \c{Ui::CalculatorForm} is an interface description object
+ from the \c ui_calculatorform.h file that sets up all the dialog's widgets
+ and the connections between its signals and slots.
+
+ This approach provides a quick and easy way to use simple, self-contained
+ components in your applications, but many componens created with \QD will
+ require close integration with the rest of the application code. For
+ instance, the \c CalculatorForm code provided above will compile and run,
+ but the QSpinBox objects will not interact with the QLabel as we need a
+ custom slot to carry out the add operation and display the result in the
+ QLabel. To achieve this, we need to subclass a standard Qt widget (known as
+ the single inheritance approach).
+
+
+ \section2 The Single Inheritance Approach
+
+ In this approach, we subclass a Qt widget and set up the user interface
+ from within the constructor. Components used in this way expose the widgets
+ and layouts used in the form to the Qt widget subclass, and provide a
+ standard system for making signal and slot connections between the user
+ interface and other objects in your application.
+
+ This approach is used in the \l{Calculator Form Example}{Calculator Form}
+ example.
+
+ To ensure that we can use the user interface, we need to include the header
+ file that \c uic generates before referring to \c{Ui::CalculatorForm}:
+
+ \snippet examples/designer/calculatorform/calculatorform.h 0
+
+ This means that the \c{.pro} file must be updated to include
+ \c{calculatorform.h}:
+
+ \snippet examples/designer/calculatorform/calculatorform.pro 0
+
+ The subclass is defined in the following way:
+
+ \snippet examples/designer/calculatorform/calculatorform.h 1
+
+ The important feature of the class is the private \c ui object which
+ provides the code for setting up and managing the user interface.
+
+ The constructor for the subclass constructs and configures all the widgets
+ and layouts for the dialog just by calling the \c ui object's \c setupUi()
+ function. Once this has been done, it is possible to modify the user
+ interface as needed.
+
+ \snippet examples/designer/calculatorform/calculatorform.cpp 0
+
+ We can connect signals and slots in user interface widgets in the usual
+ way, taking care to prefix the \c ui object to each widget used.
+
+ The advantages of this approach are its simple use of inheritance to
+ provide a QWidget-based interface, and its encapsulation of the user
+ interface widget variables within the \c ui data member. We can use this
+ method to define a number of user interfaces within the same widget, each
+ of which is contained within its own namespace, and overlay (or compose)
+ them. This approach can be used to create individual tabs from existing
+ forms, for example.
+
+
+ \section2 The Multiple Inheritance Approach
+
+ Forms created with \QD can be subclassed together with a standard
+ QWidget-based class. This approach makes all the user interface components
+ defined in the form directly accessible within the scope of the subclass,
+ and enables signal and slot connections to be made in the usual way with
+ the \l{QObject::connect()}{connect()} function.
+
+ This approach is used in the \l{Multiple Inheritance Example}
+ {Multiple Inheritance} example.
+
+ We need to include the header file that \c uic generates from the
+ \c calculatorform.ui file:
+
+ \snippet examples/uitools/multipleinheritance/calculatorform.h 0
+
+ The class is defined in a similar way to the one used in the
+ \l{The Single Inheritance Approach}{single inheritance approach}, except that
+ this time we inherit from \e{both} QWidget and \c{Ui::CalculatorForm}:
+
+ \snippet examples/uitools/multipleinheritance/calculatorform.h 1
+
+ We inherit \c{Ui::CalculatorForm} privately to ensure that the user
+ interface objects are private in our subclass. We can also inherit it with
+ the \c public or \c protected keywords in the same way that we could have
+ made \c ui public or protected in the previous case.
+
+ The constructor for the subclass performs many of the same tasks as the
+ constructor used in the \l{The Single Inheritance Approach}
+ {single inheritance} example:
+
+ \snippet examples/uitools/multipleinheritance/calculatorform.cpp 0
+
+ In this case, the widgets used in the user interface can be accessed in the
+ same say as a widget created in code by hand. We no longer require the
+ \c{ui} prefix to access them.
+
+ Subclassing using multiple inheritance gives us more direct access to the
+ contents of the form, is slightly cleaner than the single inheritance
+ approach, but does not conveniently support composition of multiple user
+ interfaces.
+
+
+ \section1 Run Time Form Processing
+
+ Alternatively, forms can be processed at run time, producing dynamically-
+ generated user interfaces. This can be done using the QtUiTools module
+ that provides the QUiLoader class to handle forms created with \QD.
+
+
+ \section2 The UiTools Approach
+
+ A resource file containing a UI file is required to process forms at
+ run time. Also, the application needs to be configured to use the QtUiTools
+ module. This is done by including the following declaration in a \c qmake
+ project file, ensuring that the application is compiled and linked
+ appropriately.
+
+ \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 0
+
+ The QUiLoader class provides a form loader object to construct the user
+ interface. This user interface can be retrieved from any QIODevice, e.g.,
+ a QFile object, to obtain a form stored in a project's resource file. The
+ QUiLoader::load() function constructs the form widget using the user
+ interface description contained in the file.
+
+ The QtUiTools module classes can be included using the following directive:
+
+ \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 1
+
+ The QUiLoader::load() function is invoked as shown in this code from the
+ \l{Text Finder Example}{Text Finder} example:
+
+ \snippet examples/uitools/textfinder/textfinder.cpp 4
+
+ In a class that uses QtUiTools to build its user interface at run time, we
+ can locate objects in the form using qFindChild(). For example, in the
+ follownig code, we locate some components based on their object names and
+ widget types:
+
+ \snippet examples/uitools/textfinder/textfinder.cpp 1
+
+ Processing forms at run-time gives the developer the freedom to change a
+ program's user interface, just by changing the UI file. This is useful
+ when customizing programs to suit various user needs, such as extra large
+ icons or a different colour scheme for accessibility support.
+
+
+ \section1 Automatic Connections
+
+ The signals and slots connections defined for compile time or run time
+ forms can either be set up manually or automatically, using QMetaObject's
+ ability to make connections between signals and suitably-named slots.
+
+ Generally, in a QDialog, if we want to process the information entered by
+ the user before accepting it, we need to connect the clicked() signal from
+ the \gui OK button to a custom slot in our dialog. We will first show an
+ example of the dialog in which the slot is connected by hand then compare
+ it with a dialog that uses automatic connection.
+
+
+ \section2 A Dialog Without Auto-Connect
+
+ We define the dialog in the same way as before, but now include a slot in
+ addition to the constructor:
+
+ \snippet doc/src/snippets/designer/noautoconnection/imagedialog.h 0
+
+ The \c checkValues() slot will be used to validate the values provided by
+ the user.
+
+ In the dialog's constructor we set up the widgets as before, and connect
+ the \gui Cancel button's \l{QPushButton::clicked()}{clicked()} signal to
+ the dialog's reject() slot. We also disable the
+ \l{QPushButton::autoDefault}{autoDefault} property in both buttons to
+ ensure that the dialog does not interfere with the way that the line edit
+ handles return key events:
+
+ \snippet doc/src/snippets/designer/noautoconnection/imagedialog.cpp 0
+ \dots
+ \snippet doc/src/snippets/designer/noautoconnection/imagedialog.cpp 1
+
+ We connect the \gui OK button's \l{QPushButton::clicked()}{clicked()}
+ signal to the dialog's checkValues() slot which we implement as follows:
+
+ \snippet doc/src/snippets/designer/noautoconnection/imagedialog.cpp 2
+
+ This custom slot does the minimum necessary to ensure that the data
+ entered by the user is valid - it only accepts the input if a name was
+ given for the image.
+
+ \section2 Widgets and Dialogs with Auto-Connect
+
+ Although it is easy to implement a custom slot in the dialog and connect
+ it in the constructor, we could instead use QMetaObject's auto-connection
+ facilities to connect the \gui OK button's clicked() signal to a slot in
+ our subclass. \c{uic} automatically generates code in the dialog's
+ \c setupUi() function to do this, so we only need to declare and
+ implement a slot with a name that follows a standard convention:
+
+ \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 2
+
+ Using this convention, we can define and implement a slot that responds to
+ mouse clicks on the \gui OK button:
+
+ \snippet doc/src/snippets/designer/autoconnection/imagedialog.h 0
+
+ Another example of automatic signal and slot connection would be the
+ \l{Text Finder Example}{Text Finder} with its \c{on_findButton_clicked()}
+ slot.
+
+ We use QMetaObject's system to enable signal and slot connections:
+
+ \snippet examples/uitools/textfinder/textfinder.cpp 2
+
+ This enables us to implement the slot, as shown below:
+
+ \snippet examples/uitools/textfinder/textfinder.cpp 6
+ \dots
+ \snippet examples/uitools/textfinder/textfinder.cpp 8
+
+ Automatic connection of signals and slots provides both a standard naming
+ convention and an explicit interface for widget designers to work to. By
+ providing source code that implements a given interface, user interface
+ designers can check that their designs actually work without having to
+ write code themselves.
+*/
+
+
+/*!
+ \page designer-customizing-forms.html
+ \contentspage {Qt Designer Manual}{Contents}
+ \previouspage Using Stylesheets with Qt Designer
+ \nextpage Using Custom Widgets with Qt Designer
+
+ \title Customizing Qt Designer Forms
+
+ \image designer-form-settings.png
+
+ When saving a form in \QD, it is stored as a UI file. Several form
+ settings, for example the grid settings or the margin and spacing for the
+ default layout, are stored along with the form's components. These settings
+ are used when the \l uic generates the form's C++ code. For more
+ information on how to use forms in your application, see the
+ \l{Using a Designer UI File in Your Application} section.
+
+
+ \section1 Modifying the Form Settings
+
+ To modify the form settings, open the \gui Form menu and select \gui{Form
+ Settings...}
+
+ In the forms settings dialog you can specify the \gui Author of the form.
+
+ You can also alter the margin and spacing properties for the form's default
+ layout (\gui {Layout Default}). These default layout properties will be
+ replaced by the corresponding \gui {Layout Function}, if the function is
+ specified, when \c uic generates code for the form. The form settings
+ dialog lets you specify functions for both the margin and the spacing.
+
+ \target LayoutFunction
+ \table
+ \row
+ \i \inlineimage designer-form-layoutfunction.png
+ \i \bold{Layout Function}
+
+ The default layout properties will be replaced by the corresponding
+ \gui{Layout Function}, when \c uic generates code for the form. This is
+ useful when different environments requires different layouts for the same
+ form.
+
+ To specify layout functions for the form's margin and spacing, check the
+ \gui{Layout Function} group box to enable the line edits.
+ \endtable
+
+ You can also specify the form's \gui{Include Hints}; i.e., provide a list
+ of the header files which will then be included in the form window's
+ associated UI file. Header files may be local, i.e., relative to the
+ project's directory, \c "mywidget.h", or global, i.e. part of Qt or the
+ compilers standard libraries: \c <QtGui/QWidget>.
+
+ Finally, you can specify the function used to load pixmaps into the form
+ window (the \gui {Pixmap Function}).
+*/
+
+
+/*!
+ \page designer-using-custom-widgets.html
+ \contentspage {Qt Designer Manual}{Contents}
+ \previouspage Customizing Qt Designer Forms
+ \nextpage Creating Custom Widgets for Qt Designer
+
+ \title Using Custom Widgets with Qt Designer
+
+ \QD can display custom widgets through its extensible plugin mechanism,
+ allowing the range of designable widgets to be extended by the user and
+ third parties. This feature also allows \QD to optionally support
+ \l{Qt3Support}{Qt 3 compatibility widgets}. Alternatively, it is possible
+ to use existing widgets as placeholders for widget classes that provide
+ similar APIs.
+
+ Widgets from the Qt3Support library are made available via in \QD's support
+ for custom widgets.
+
+
+ \section1 Handling Custom Widgets
+
+ Although \QD supports all of the standard Qt widgets, and can be configured
+ to handle widgets supplied in the Qt3Support library, some specialized
+ widgets may not be available as standard for a number of reasons:
+
+ \list
+ \i Custom widgets may not be available at the time the user interface
+ is being designed.
+ \i Custom widgets may be platform-specific, and designers may be
+ developing the user interface on a different platform to end users.
+ \i The source code for a custom widget is not available, or the user
+ interface designers are unable to use the widget for non-technical
+ reasons.
+ \endlist
+
+ In the above situations, it is still possible to design forms with the aim
+ of using custom widgets in the application. To achieve this, we can use
+ the widget promotion feature of \QD.
+
+ In all other cases, where the source code to the custom widgets is
+ available, we can adapt the custom widget for use with \QD.
+
+
+ \section2 Promoting Widgets
+
+ \image designer-promoting-widgets.png
+
+ If some forms must be designed, but certain custom widgets are unavailble
+ to the designer, we can substitute similar widgets to represent the missing
+ widgets. For example, we might represent instances of a custom push button
+ class, \c MyPushButton, with instances of QPushButton and promote these to
+ \c MyPushButton so that \l{uic.html}{uic} generates suitable code for this
+ missing class.
+
+ When choosing a widget to use as a placeholder, it is useful to compare the
+ API of the missing widget with those of standard Qt widgets. For
+ specialized widgets that subclass standard classes, the obvious choice of
+ placeholder is the base class of the custom widget; for example, QSlider
+ might be used for specialized QSlider subclasses.
+
+ For specialized widgets that do not share a common API with standard Qt
+ widgets, it is worth considering adapting a custom widget for use in \QD.
+ If this is not possible then QWidget is the obvious choice for a
+ placeholder widget since it is the lowest common denominator for all
+ widgets.
+
+ To add a placeholder, select an object of a suitable base class and choose
+ \gui{Promote to ...} from the form's context menu. After entering the class
+ name and header file in the lower part of the dialog, choose \gui{Add}. The
+ placeholder class will now appear along with the base class in the upper
+ list. Click the \gui{Promote} button to accept this choice.
+
+ Now, when the form's context menu is opened over objects of the base class,
+ the placeholder class will appear in the \gui{Promote to} submenu, allowing
+ for convenient promotion of objects to that class.
+
+ A promoted widget can be reverted to its base class by choosing
+ \gui{Demote to} from the form's context menu.
+
+
+ \section2 User Defined Custom Widgets
+
+ \image worldtimeclockplugin-example.png
+
+ Custom widgets can be adapted for use with \QD, giving designers the
+ opportunity to configure the user interface using the actual widgets that
+ will be used in an application rather than placeholder widgets. The process
+ of creating a custom widget plugin is described in the
+ \l{Creating Custom Widgets for Qt Designer} chapter of this manual.
+
+ To use a plugin created in this way, it is necessary to ensure that the
+ plugin is located on a path that \QD searches for plugins. Generally,
+ plugins stored in \c{$QTDIR/plugins/designer} will be loaded when \QD
+ starts. Further information on building and installing plugins can be found
+ \l{Creating Custom Widgets for Qt Designer#BuildingandInstallingthePlugin}
+ {here}. You can also refer to the \l{How to Create Qt Plugins}
+ {Plugins HOWTO} document for information about creating plugins.
+*/
+
+
+/*!
+ \page designer-creating-custom-widgets.html
+ \previouspage Using Custom Widgets with Qt Designer
+ \contentspage {Qt Designer Manual}{Contents}
+ \nextpage Creating Custom Widget Extensions
+
+ \title Creating Custom Widgets for Qt Designer
+
+ \QD's plugin-based architecture allows user-defined and third party custom
+ widgets to be edited just like you do with standard Qt widgets. All of the
+ custom widget's features are made available to \QD, including widget
+ properties, signals, and slots. Since \QD uses real widgets during the form
+ design process, custom widgets will appear the same as they do when
+ previewed.
+
+ \image worldtimeclockplugin-example.png
+
+ The \l QtDesigner module provides you with the ability to create custom
+ widgets in \QD.
+
+
+ \section1 Getting Started
+
+ To integrate a custom widget with \QD, you require a suitable description
+ for the widget and an appropriate \c{.pro} file.
+
+
+ \section2 Providing an Interface Description
+
+ To inform \QD about the type of widget you want to provide, create a
+ subclass of QDesignerCustomWidgetInterface that describes the various
+ properties your widget exposes. Most of these are supplied by functions
+ that are pure virtual in the base class, because only the author of the
+ plugin can provide this information.
+
+ \table
+ \header
+ \o Function
+ \o Description of the return value
+ \row
+ \o \c name()
+ \o The name of the class that provides the widget.
+ \row
+ \o \c group()
+ \o The group in \QD's widget box that the widget belongs to.
+ \row
+ \o \c toolTip()
+ \o A short description to help users identify the widget in \QD.
+ \row
+ \o \c whatsThis()
+ \o A longer description of the widget for users of \QD.
+ \row
+ \o \c includeFile()
+ \o The header file that must be included in applications that use
+ this widget. This information is stored in UI files and will
+ be used by \c uic to create a suitable \c{#includes} statement
+ in the code it generates for the form containing the custom
+ widget.
+ \row
+ \o \c icon()
+ \o An icon that can be used to represent the widget in \QD's
+ widget box.
+ \row
+ \o \c isContainer()
+ \o True if the widget will be used to hold child widgets;
+ false otherwise.
+ \row
+ \o \c createWidget()
+ \o A QWidget pointer to an instance of the custom widget,
+ constructed with the parent supplied.
+ \note createWidget() is a factory function responsible for
+ creating the widget only. The custom widget's properties will
+ not be available until load() returns.
+ \row
+ \o \c domXml()
+ \o A description of the widget's properties, such as its object
+ name, size hint, and other standard QWidget properties.
+ \row
+ \o \c codeTemplate()
+ \o This function is reserved for future use by \QD.
+ \endtable
+
+ Two other virtual functions can also be reimplemented:
+
+ \table
+ \row
+ \o \c initialize()
+ \o Sets up extensions and other features for custom widgets. Custom
+ container extensions (see QDesignerContainerExtension) and task
+ menu extensions (see QDesignerTaskMenuExtension) should be set
+ up in this function.
+ \row
+ \o \c isInitialized()
+ \o Returns true if the widget has been initialized; returns false
+ otherwise. Reimplementations usually check whether the
+ \c initialize() function has been called and return the result
+ of this test.
+ \endtable
+
+
+ \section2 Notes on the \c{domXml()} Function
+
+ The \c{domXml()} function returns a UI file snippet that is used by
+ \QD's widget factory to create a custom widget and its applicable
+ properties.
+
+ Since Qt 4.4, \QD's widget box allows for a complete UI file to
+ describe \bold one custom widget. The UI file can be loaded using the
+ \c{<ui>} tag. Specifying the <ui> tag allows for adding the <customwidget>
+ element that contains additional information for custom widgets. The
+ \c{<widget>} tag is sufficient if no additional information is required
+
+ If the custom widget does not provide a reasonable size hint, it is
+ necessary to specify a default geometry in the string returned by the
+ \c domXml() function in your subclass. For example, the
+ \c AnalogClockPlugin provided by the \l{designer/customwidgetplugin}
+ {Custom Widget Plugin} example, defines a default widgetgeometry in the
+ following way:
+
+ \dots
+ \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 11
+ \dots
+
+ An additional feature of the \c domXml() function is that, if it returns
+ an empty string, the widget will not be installed in \QD's widget box.
+ However, it can still be used by other widgets in the form. This feature
+ is used to hide widgets that should not be explicitly created by the user,
+ but are required by other widgets.
+
+
+ A complete custom widget specification looks like:
+
+ \code
+<ui language="c++"> displayname="MyWidget">
+ <widget class="widgets::MyWidget" name="mywidget"/>
+ <customwidgets>
+ <customwidget>
+ <class>widgets::MyWidget</class>
+ <addpagemethod>addPage</addpagemethod>
+ <propertyspecifications>
+ <stringpropertyspecification name="fileName" notr="true" type="singleline"
+ <stringpropertyspecification name="text" type="richtext"
+ </propertyspecifications>
+ </customwidget>
+ </customwidgets>
+</ui>
+ \endcode
+
+ Attributes of the \c{<ui>} tag:
+ \table
+ \header
+ \o Attribute
+ \o Presence
+ \o Values
+ \o Comment
+ \row
+ \o \c{language}
+ \o optional
+ \o "c++", "jambi"
+ \o This attribute specifies the language the custom widget is intended for.
+ It is mainly there to prevent C++-plugins from appearing in Qt Jambi.
+ \row
+ \o \c{displayname}
+ \o optional
+ \o Class name
+ \o The value of the attribute appears in the Widget box and can be used to
+ strip away namespaces.
+ \endtable
+
+ The \c{<addpagemethod>} tag tells \QD and \l uic which method should be used to
+ add pages to a container widget. This applies to container widgets that require
+ calling a particular method to add a child rather than adding the child by passing
+ the parent. In particular, this is relevant for containers that are not a
+ a subclass of the containers provided in \QD, but are based on the notion
+ of \e{Current Page}. In addition, you need to provide a container extension
+ for them.
+
+ The \c{<propertyspecifications>} element can contain a list of property meta information.
+ Currently, properties of type string are supported. For these properties, the
+ \c{<stringpropertyspecification>} tag can be used. This tag has the following attributes:
+
+
+ \table
+ \header
+ \o Attribute
+ \o Presence
+ \o Values
+ \o Comment
+ \row
+ \o \c{name}
+ \o required
+ \o Name of the property
+ \row
+ \o \c{type}
+ \o required
+ \o See below table
+ \o The value of the attribute determines how the property editor will handle them.
+ \row
+ \o \c{notr}
+ \o optional
+ \o "true", "false"
+ \o If the attribute is "true", the value is not meant to be translated.
+ \endtable
+
+ Values of the \c{type} attribute of the string property:
+
+ \table
+ \header
+ \o Value
+ \o Type
+ \row
+ \o \c{"richtext"}
+ \o Rich text.
+ \row
+ \o \c{"multiline"}
+ \o Multi-line plain text.
+ \row
+ \o \c{"singleline"}
+ \o Single-line plain text.
+ \row
+ \o \c{"stylesheet"}
+ \o A CSS-style sheet.
+ \row
+ \o \c{"objectname"}
+ \o An object name (restricted set of valid characters).
+ \row
+ \o \c{"url"}
+ \o URL, file name.
+ \endtable
+
+ \section1 Plugin Requirements
+
+ In order for plugins to work correctly on all platforms, you need to ensure
+ that they export the symbols needed by \QD.
+
+ First of all, the plugin class must be exported in order for the plugin to
+ be loaded by \QD. Use the Q_EXPORT_PLUGIN2() macro to do this. Also, the
+ QDESIGNER_WIDGET_EXPORT macro must be used to define each custom widget class
+ within a plugin, that \QD will instantiate.
+
+
+ \section1 Creating Well Behaved Widgets
+
+ Some custom widgets have special user interface features that may make them
+ behave differently to many of the standard widgets found in \QD.
+ Specifically, if a custom widget grabs the keyboard as a result of a call
+ to QWidget::grabKeyboard(), the operation of \QD will be affected.
+
+ To give custom widgets special behavior in \QD, provide an implementation
+ of the initialize() function to configure the widget construction process
+ for \QD specific behavior. This function will be called for the first time
+ before any calls to createWidget() and could perhaps set an internal flag
+ that can be tested later when \QD calls the plugin's createWidget()
+ function.
+
+
+ \target BuildingandInstallingthePlugin
+ \section1 Building and Installing the Plugin
+
+ \section2 A Simple Plugin
+
+ The \l{Custom Widget Plugin Example} demonstrates a simple \QD plugin.
+
+ The \c{.pro} file for a plugin must specify the headers and sources for
+ both the custom widget and the plugin interface. Typically, this file only
+ has to specify that the plugin's project is to be built as a library, but
+ with specific plugin support for \QD. This is done with the following
+ declarations:
+
+ \snippet examples/designer/customwidgetplugin/customwidgetplugin.pro 1
+
+ If Qt is configured to build in both debug and release modes, \QD will be
+ built in release mode. When this occurs, it is necessary to ensure that
+ plugins are also built in release mode. To do this, include the following
+ declaration in the plugin's \c{.pro} file:
+
+ \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 3
+
+ If plugins are built in a mode that is incompatible with \QD, they will
+ not be loaded and installed. For more information about plugins, see the
+ \l{plugins-howto.html}{Plugins HOWTO} document.
+
+ It is also necessary to ensure that the plugin is installed together with
+ other \QD widget plugins:
+
+ \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 4
+
+ The \c $[QT_INSTALL_PLUGINS] variable is a placeholder to the location of
+ the installed Qt plugins. You can configure \QD to look for plugins in
+ other locations by setting the \c QT_PLUGIN_PATH environment variable
+ before running the application.
+
+ \note \QD will look for a \c designer subdirectory in each path supplied.
+
+ See QCoreApplication::libraryPaths() for more information about customizing
+ paths for libraries and plugins with Qt applications.
+
+ \section2 Splitting up the Plugin
+
+ In a real world scenario, you do not want to have dependencies of the
+ application making use of the custom widgets to the \QD headers and
+ libraries as introduced by the simple approach explained above.
+
+ There are two ways to resolve this:
+
+ \list
+ \i Create a \c{.pri} file that contains the headers sources and sources
+ of the custom widget:
+
+ \code
+ INCLUDEPATH += $$PWD
+ HEADERS += $$PWD/analogclock.h
+ SOURCES += $$PWD/analogclock.cpp
+ \endcode
+
+ This file would then be included by the \c{.pro} file of the plugin and
+ the application:
+
+ \code
+ include(customwidget.pri)
+ \endcode
+
+ Running \c{qmake -Wall} on the \c{.pro} files causes a warning to be
+ printed if an included \c{.pri} file cannot be found.
+
+ \i Create a standalone shared library containing the custom widgets only
+ as described in
+ \l{sharedlibrary.html}{Creating Shared Libraries}.
+
+ This library would then be used by the application as well as by the
+ \QD plugin. Care must be taken to ensure that the plugin can locate
+ the library at run-time.
+ \endlist
+
+ \section1 Related Examples
+
+ For more information on using custom widgets in \QD, refer to the
+ \l{designer/customwidgetplugin}{Custom Widget Plugin} and
+ \l{designer/worldtimeclockplugin}{World Time Clock Plugin} examples for more
+ information about using custom widgets in \QD. Also, you can use the
+ QDesignerCustomWidgetCollectionInterface class to combine several custom
+ widgets into a single library.
+*/
+
+
+/*!
+ \page designer-creating-custom-widgets-extensions.html
+ \previouspage Creating Custom Widgets for Qt Designer
+ \nextpage Qt Designer's UI File Format
+ \contentspage {Qt Designer Manual}{Contents}
+
+ \title Creating Custom Widget Extensions
+
+ Once you have a custom widget plugin for \QD, you can provide it with the
+ expected behavior and functionality within \QD's workspace, using custom
+ widget extensions.
+
+
+ \section1 Extension Types
+
+ There are several available types of extensions in \QD. You can use all of
+ these extensions in the same pattern, only replacing the respective
+ extension base class.
+
+ QDesignerContainerExtension is necessary when implementing a custom
+ multi-page container.
+
+ \table
+ \row
+ \i \inlineimage designer-manual-taskmenuextension.png
+ \i \bold{QDesignerTaskMenuExtension}
+
+ QDesignerTaskMenuExtension is useful for custom widgets. It provides an
+ extension that allows you to add custom menu entries to \QD's task
+ menu.
+
+ The \l{designer/taskmenuextension}{Task Menu Extension} example
+ illustrates how to use this class.
+
+ \row
+ \i \inlineimage designer-manual-containerextension.png
+ \i \bold{QDesignerContainerExtension}
+
+ QDesignerContainerExtension is necessary when implementing a custom
+ multi-page container. It provides an extension that allows you to add
+ and delete pages for a multi-page container plugin in \QD.
+
+ The \l{designer/containerextension}{Container Extension} example
+ further explains how to use this class.
+
+ \note It is not possible to add custom per-page properties for some
+ widgets (e.g., QTabWidget) due to the way they are implemented.
+ \endtable
+
+ \table
+ \row
+ \i \inlineimage designer-manual-membersheetextension.png
+ \i \bold{QDesignerMemberSheetExtension}
+
+ The QDesignerMemberSheetExtension class allows you to manipulate a
+ widget's member functions displayed when connecting signals and slots.
+
+ \row
+ \i \inlineimage designer-manual-propertysheetextension.png
+ \i \bold{QDesignerPropertySheetExtension,
+ QDesignerDynamicPropertySheetExtension}
+
+ These extension classes allow you to control how a widget's properties
+ are displayed in \QD's property editor.
+ \endtable
+
+\omit
+ \row
+ \o
+ \o \bold {QDesignerScriptExtension}
+
+ The QDesignerScriptExtension class allows you to define script
+ snippets that are executed when a form is loaded. The extension
+ is primarily intended to be used to set up the internal states
+ of custom widgets.
+ \endtable
+\endomit
+
+
+ \QD uses the QDesignerPropertySheetExtension and the
+ QDesignerMemberSheetExtension classes to feed its property and signal and
+ slot editors. Whenever a widget is selected in its workspace, \QD will
+ query for the widget's property sheet extension; likewise, whenever a
+ connection between two widgets is requested, \QD will query for the
+ widgets' member sheet extensions.
+
+ \warning All widgets have default property and member sheets. If you
+ implement custom property sheet or member sheet extensions, your custom
+ extensions will override the default sheets.
+
+
+ \section1 Creating an Extension
+
+ To create an extension you must inherit both QObject and the appropriate
+ base class, and reimplement its functions. Since we are implementing an
+ interface, we must ensure that it is made known to the meta object system
+ using the Q_INTERFACES() macro in the extension class's definition. For
+ example:
+
+ \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 7
+
+ This enables \QD to use the qobject_cast() function to query for supported
+ interfaces using a QObject pointer only.
+
+
+ \section1 Exposing an Extension to Qt Designer
+
+ In \QD the extensions are not created until they are required. For this
+ reason, when implementing extensions, you must subclass QExtensionFactory
+ to create a class that is able to make instances of your extensions. Also,
+ you must register your factory with \QD's extension manager; the extension
+ manager handles the construction of extensions.
+
+ When an extension is requested, \QD's extension manager will run through
+ its registered factories calling QExtensionFactory::createExtension() for
+ each of them until it finds one that is able to create the requested
+ extension for the selected widget. This factory will then make an instance
+ of the extension.
+
+ \image qtdesignerextensions.png
+
+
+ \section2 Creating an Extension Factory
+
+ The QExtensionFactory class provides a standard extension factory, but it
+ can also be used as an interface for custom extension factories.
+
+ The purpose is to reimplement the QExtensionFactory::createExtension()
+ function, making it able to create your extension, such as a
+ \l{designer/containerextension}{MultiPageWidget} container extension.
+
+ You can either create a new QExtensionFactory and reimplement the
+ QExtensionFactory::createExtension() function:
+
+ \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 8
+
+ or you can use an existing factory, expanding the
+ QExtensionFactory::createExtension() function to enable the factory to
+ create your custom extension as well:
+
+ \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 9
+
+
+ \section2 Accessing Qt Designer's Extension Manager
+
+ When implementing a custom widget plugin, you must subclass the
+ QDesignerCustomWidgetInterface to expose your plugin to \QD. This is
+ covered in more detail in the
+ \l{Creating Custom Widgets for Qt Designer} section. The registration of
+ an extension factory is typically made in the
+ QDesignerCustomWidgetInterface::initialize() function:
+
+ \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 10
+
+ The \c formEditor parameter in the
+ QDesignerCustomWidgetInterface::initialize() function is a pointer to \QD's
+ current QDesignerFormEditorInterface object. You must use the
+ QDesignerFormEditorInterface::extensionManager() function to retrieve an
+ interface to \QD's extension manager. Then you use the
+ QExtensionManager::registerExtensions() function to register your custom
+ extension factory.
+
+
+ \section1 Related Examples
+
+ For more information on creating custom widget extensions in \QD, refer to
+ the \l{designer/taskmenuextension}{Task Menu Extension} and
+ \l{designer/containerextension}{Container Extension} examples.
+*/
+
+
+/*!
+ \page designer-ui-file-format.html
+ \previouspage Creating Custom Widget Extensions
+ \contentspage {Qt Designer Manual}{Contents}
+
+ \title Qt Designer's UI File Format
+
+ The \c UI file format used by \QD is described by the
+ \l{http://www.w3.org/XML/Schema}{XML schema} presented below,
+ which we include for your convenience. Be aware that the format
+ may change in future Qt releases.
+
+ \quotefile tools/designer/data/ui4.xsd
+*/
+
+
+/*!
+ \page designer-recursive-shadow-casting.html
+ \title Implementation of the Recursive Shadow Casting Algorithm in Qt Designer
+ \contentspage {Qt Designer Manual}{Contents}
+
+ \ingroup licensing
+ \brief License information for contributions to specific parts of the Qt
+ Designer source code.
+
+ \legalese
+ Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). \BR
+ Copyright (C) 2005 Bjoern Bergstroem
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, modify, market, reproduce,
+ grant sublicenses and distribute subject to the following conditions:
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software. These
+ files are provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
+ WARRANTY OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE.
+ \endlegalese
+*/
diff --git a/doc/src/development/developing-on-mac.qdoc b/doc/src/development/developing-on-mac.qdoc
new file mode 100644
index 0000000..dee6d4d
--- /dev/null
+++ b/doc/src/development/developing-on-mac.qdoc
@@ -0,0 +1,269 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page developing-on-mac.html
+ \title Developing Qt Applications on Mac OS X
+ \brief A overview of items to be aware of when developing Qt applications
+ on Mac OS X
+ \ingroup platform-specific
+
+ \tableofcontents
+
+ Mac OS X is a UNIX platform and behaves similar to other Unix-like
+ platforms. The main difference is X11 is not used as the primary windowing
+ system. Instead, Mac OS X uses its own native windowing system that is
+ accessible through the Carbon and Cocoa APIs. Application development on
+ Mac OS X is done using Xcode Tools, an optional install included on every
+ Mac with updates available from \l {http://developer.apple.com}{Apple's
+ developer website}. Xcode Tools includes Apple-modified versions of the GCC
+ compiler.
+
+
+ \section1 What Versions of Mac OS X are Supported?
+
+ As of Qt 4.6, Qt supports Mac OS X versions 10.4 and up. It is usually in
+ the best interest of the developer and user to be running the latest
+ updates to any version. We test internally against Mac OS X 10.4.11 as well
+ as the updated release of Mac OS X 10.5 and Mac OS X 10.6.
+
+ \section2 Carbon or Cocoa?
+
+ Historically, Qt has used the Carbon toolkit, which supports 32-bit
+ applications on Mac OS X 10.4 and up. Qt 4.5 and up has support for the Cocoa
+ toolkit, which requires 10.5 and provides 64-bit support.
+
+ This detail is typically not important to Qt application developers. Qt is
+ cross-platform across Carbon and Cocoa, and Qt applications behave
+ the same way when configured for either one. Eventually, the Carbon
+ version will be discontinued. This is something to keep in mind when you
+ consider writing code directly against native APIs.
+
+ The current binary for Qt is built in two flavors, 32-bit Carbon and full
+ universal Cocoa (32-bit and 64-bit). If you want a different setup for
+ Qt will use, you must build from scratch. Carbon or Cocoa is chosen when
+ configuring the package for building. The configure process selects Carbon
+ by default, to specify Cocoa use the \c{-cocoa} flag. configure for a
+ 64-bit architecture using one of the \c{-arch} flags (see \l{universal
+ binaries}{Universal Binaries}).
+
+ Currently, Apple's default GCC compiler is used by default (GCC 4.0.1 on
+ 10.4 and 10.5, GCC 4.2 on 10.6). You can specify alternate compilers
+ though. For example, on Mac OS X 10.5, Apple's GCC 4.2 is also available
+ and selectable with the configure flag: \c{-platform macx-g++42}. LLVM-GCC
+ support is available by passing in the \c{-platform macx-llvm} flag. GCC
+ 3.x will \e not work. Though they may work, We do not support custom-built
+ GCC's.
+
+ The following table summarizes the different versions of Mac OS X and what
+ capabilities are used by Qt.
+
+ \table
+ \header
+ \o Mac OS X Version
+ \o Cat Name
+ \o Native API Used by Qt
+ \o Bits available to address memory
+ \o CPU Architecture Supported
+ \o Development Platform
+ \row
+ \o 10.4
+ \o Tiger
+ \o Carbon
+ \o 32
+ \o PPC/Intel
+ \o Yes
+ \row
+ \o 10.5
+ \o Leopard
+ \o Carbon
+ \o 32
+ \o PPC/Intel
+ \o Yes
+ \row
+ \o 10.5
+ \o Leopard
+ \o Cocoa
+ \o 32/64
+ \o PPC/Intel
+ \o Yes
+ \row
+ \o 10.6
+ \o Snow Leopard
+ \o Carbon
+ \o 32
+ \o PPC/Intel
+ \o Yes
+ \row
+ \o 10.6
+ \o Snow Leopard
+ \o Cocoa
+ \o 32/64
+ \o PPC/Intel
+ \o Yes
+ \endtable
+
+ \section2 Which One Should I Use?
+
+ Carbon and Cocoa both have their advantages and disadvantages. Probably the
+ easiest way to determine is to look at the version of Mac OS X you are
+ targetting. If you are starting a new application and can target 10.5 and
+ up, then please consider Cocoa only. If you have an existing application or
+ need to target earlier versions of the operating system and do not need
+ access to 64-bit or newer Apple technologies, then Carbon is a good fit. If
+ your needs fall in between, you can go with a 64-bit Cocoa and 32-bit
+ Carbon universal application with the appropriate checks in your code to
+ choose the right path based on where you are running the application.
+
+ For Mac OS X 10.6, Apple has started recommending developers to build their
+ applications 64-bit. The main reason is that there is a small speed
+ increase due to the extra registers on Intel CPU's, all their machine
+ offerings have been 64-bit since 2007, and there is a cost for reading all
+ the 32-bit libraries into memory if everything else is 64-bit. If you want
+ to follow this advice, there is only one choice, 64-bit Cocoa.
+
+ \target universal binaries
+ \section1 Universal Binaries
+
+ In 2006, Apple begin transitioning from PowerPC (PPC) to Intel (x86)
+ systems. Both architectures are supported by Qt. The release of Mac OS X
+ 10.5 in October 2007 added the possibility of writing and deploying 64-bit
+ GUI applications. Qt 4.5 and up supports both the 32-bit (PPC and x86) and
+ 64-bit (PPC64 and x86-64) versions of PowerPC and Intel-based systems.
+
+ Universal binaries are used to bundle binaries for more than one
+ architecture into a single package, simplifying deployment and
+ distribution. When running an application the operating system will select
+ the most appropriate architecture. Universal binaries support the following
+ architectures; they can be added to the build at configure time using the
+ \c{-arch} arguments:
+
+ \table
+ \header
+ \o Architecture
+ \o Flag
+ \row
+ \o Intel, 32-bit
+ \o \c{-arch x86}
+ \row
+ \o Intel, 64-bit
+ \o \c{-arch x86_64}
+ \row
+ \o PPC, 32-bit
+ \o \c{-arch ppc}
+ \row
+ \o PPC, 64-bit
+ \o \c{-arch ppc64}
+ \endtable
+
+ If there are no \c{-arch} flags specified, configure builds for the 32-bit
+ architecture, if you are currently on one. Universal binaries were initially
+ used to simplify the PPC to Intel migration. You can use \c{-universal} to
+ build for both the 32-bit Intel and PPC architectures.
+
+ \note The \c{-arch} flags at configure time only affect how Qt is built.
+ Applications are by default built for the 32-bit architecture you are
+ currently on. To build a universal binary, add the architectures to the
+ CONFIG variable in the .pro file:
+
+ \code
+ CONFIG += x86 ppc x86_64 ppc64
+ \endcode
+
+
+ \section1 Day-to-Day Application Development on OS X
+
+ On the command-line, applications can be built using \c qmake and \c make.
+ Optionally, \c qmake can generate project files for Xcode with
+ \c{-spec macx-xcode}. If you are using the binary package, \c qmake
+ generates Xcode projects by default; use \c{-spec macx-gcc} to generate
+ makefiles.
+
+ The result of the build process is an application bundle, which is a
+ directory structure that contains the actual application executable. The
+ application can be launched by double-clicking it in Finder, or by
+ referring directly to its executable from the command line, i. e.
+ \c{myApp.app/Contents/MacOS/myApp}.
+
+ If you wish to have a command-line tool that does not use the GUI (e.g.,
+ \c moc, \c uic or \c ls), you can tell \c qmake not to execute the bundle
+ creating steps by removing it from the \c{CONFIG} in your \c{.pro} file:
+
+ \code
+ CONFIG -= app_bundle
+ \endcode
+
+
+ \section1 Deployment - "Compile once, deploy everywhere"
+
+ In general, Qt supports building on one Mac OS X version and deploying on
+ all others, both forward and backwards. You can build on 10.4 Tiger and run
+ the same binary on 10.5 and up.
+
+ Some restrictions apply:
+
+ \list
+ \o Some functions and optimization paths that exist in later versions
+ of Mac OS X will not be available if you build on an earlier
+ version of Mac OS X.
+ \o The CPU architecture should match.
+ \o Cocoa support is only available for Mac OS X 10.5 and up.
+ \endlist
+
+ Universal binaries can be used to provide a smorgasbord of configurations
+ catering to all possible architectures.
+
+ Mac applications are typically deployed as self-contained application
+ bundles. The application bundle contains the application executable as well
+ as dependencies such as the Qt libraries, plugins, translations and other
+ resources you may need. Third party libraries like Qt are normally not
+ installed system-wide; each application provides its own copy.
+
+ The most common way to distribute applications is to provide a compressed
+ disk image (.dmg file) that the user can mount in Finder. The Mac
+ deployment tool (macdeployqt) can be used to create the self-contained bundles, and
+ optionally also create a .dmg archive. See the
+ \l{Deploying an Application on Mac OS X}{Mac deployment guide} for more
+ information about deployment. It is also possible to use an installer
+ wizard. More information on this option can be found in
+ \l{http://developer.apple.com/mac/}{Apple's documentation}.
+*/
+
diff --git a/doc/src/development/developing-with-qt.qdoc b/doc/src/development/developing-with-qt.qdoc
new file mode 100644
index 0000000..9fa2242
--- /dev/null
+++ b/doc/src/development/developing-with-qt.qdoc
@@ -0,0 +1,74 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page developing-with-qt.html
+ \title Cross Platform Development with Qt
+
+ Qt is provided with a set of build tools to help developers automate
+ the process of building and installing Qt applications.
+
+ \table 100%
+ \header \o Development \o Cross-Platform Issues \o Specific Tools
+ \row
+ \o
+ \list
+ \o \l {Debugging Techniques}
+ \o \l {Qt's Tools}
+ \o \l {The Qt Resource System}
+ \o \l {Using Precompiled Headers}
+ \endlist
+ \o
+ \list
+ \o \l {Cross Compiling Qt for Embedded Linux Applications}
+ \o \l {Deploying Qt Applications}
+ \o \l {Installation}{Installing Qt}
+ \o \l {Window System Specific Notes}
+ \endlist
+ \o
+ \list
+ \o \l lupdate and \l lrelease
+ \o \l {moc}{Meta-Object Compiler (moc)}
+ \o \l {User Interface Compiler (uic)}
+ \o \l {Resource Compiler (rcc)}
+ \endlist
+ \endtable
+*/
diff --git a/doc/src/development/moc.qdoc b/doc/src/development/moc.qdoc
new file mode 100644
index 0000000..747c68d
--- /dev/null
+++ b/doc/src/development/moc.qdoc
@@ -0,0 +1,335 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page moc.html
+ \title Using the Meta-Object Compiler (moc)
+ \ingroup qttools
+ \keyword moc
+
+ The Meta-Object Compiler, \c moc, is the program that handles
+ \l{Meta-Object System}{Qt's C++ extensions}.
+
+ The \c moc tool reads a C++ header file. If it finds one or more
+ class declarations that contain the Q_OBJECT macro, it
+ produces a C++ source file containing the meta-object code for
+ those classes. Among other things, meta-object code is required
+ for the signals and slots mechanism, the run-time type information,
+ and the dynamic property system.
+
+ The C++ source file generated by \c moc must be compiled and
+ linked with the implementation of the class.
+
+ If you use \l qmake to create your makefiles, build rules will be
+ included that call the moc when required, so you will not need to
+ use the moc directly. For more background information on \c moc,
+ see \l{Why Doesn't Qt Use Templates for Signals and Slots?}
+
+ \section1 Usage
+
+ \c moc is typically used with an input file containing class
+ declarations like this:
+
+ \snippet doc/src/snippets/moc/myclass1.h 0
+
+ In addition to the signals and slots shown above, \c moc also
+ implements object properties as in the next example. The
+ Q_PROPERTY() macro declares an object property, while
+ Q_ENUMS() declares a list of enumeration types within the class
+ to be usable inside the \l{Qt's Property System}{property
+ system}.
+
+ In the following example, we declare a property of the
+ enumeration type \c Priority that is also called \c priority and
+ has a get function \c priority() and a set function \c
+ setPriority().
+
+ \snippet doc/src/snippets/moc/myclass2.h 0
+
+ The Q_FLAGS() macro declares enums that are to be used
+ as flags, i.e. OR'd together. Another macro, Q_CLASSINFO(),
+ allows you to attach additional name/value pairs to the class's
+ meta-object:
+
+ \snippet doc/src/snippets/moc/myclass3.h 0
+
+ The output produced by \c moc must be compiled and linked, just
+ like the other C++ code in your program; otherwise, the build
+ will fail in the final link phase. If you use \c qmake, this is
+ done automatically. Whenever \c qmake is run, it parses the
+ project's header files and generates make rules to invoke \c moc
+ for those files that contain a Q_OBJECT macro.
+
+ If the class declaration is found in the file \c myclass.h, the
+ moc output should be put in a file called \c moc_myclass.cpp.
+ This file should then be compiled as usual, resulting in an
+ object file, e.g., \c moc_myclass.obj on Windows. This object
+ should then be included in the list of object files that are
+ linked together in the final building phase of the program.
+
+ \section1 Writing Make Rules for Invoking \c moc
+
+ For anything but the simplest test programs, it is recommended
+ that you automate running the \c{moc}. By adding some rules to
+ your program's makefile, \c make can take care of running moc
+ when necessary and handling the moc output.
+
+ We recommend using the \l qmake makefile generation tool for
+ building your makefiles. This tool generates a makefile that does
+ all the necessary \c moc handling.
+
+ If you want to create your makefiles yourself, here are some tips
+ on how to include moc handling.
+
+ For Q_OBJECT class declarations in header files, here is a
+ useful makefile rule if you only use GNU make:
+
+ \snippet doc/src/snippets/code/doc_src_moc.qdoc 0
+
+ If you want to write portably, you can use individual rules of
+ the following form:
+
+ \snippet doc/src/snippets/code/doc_src_moc.qdoc 1
+
+ You must also remember to add \c moc_foo.cpp to your \c SOURCES
+ (substitute your favorite name) variable and \c moc_foo.o or \c
+ moc_foo.obj to your \c OBJECTS variable.
+
+ Both examples assume that \c $(DEFINES) and \c $(INCPATH) expand
+ to the define and include path options that are passed to the C++
+ compiler. These are required by \c moc to preprocess the source
+ files.
+
+ While we prefer to name our C++ source files \c .cpp, you can use
+ any other extension, such as \c .C, \c .cc, \c .CC, \c .cxx, and
+ \c .c++, if you prefer.
+
+ For Q_OBJECT class declarations in implementation (\c .cpp)
+ files, we suggest a makefile rule like this:
+
+ \snippet doc/src/snippets/code/doc_src_moc.qdoc 2
+
+ This guarantees that make will run the moc before it compiles
+ \c foo.cpp. You can then put
+
+ \snippet doc/src/snippets/code/doc_src_moc.qdoc 3
+
+ at the end of \c foo.cpp, where all the classes declared in that
+ file are fully known.
+
+ \section1 Command-Line Options
+
+ Here are the command-line options supported by the moc:
+
+ \table
+ \header \o Option \o Description
+
+ \row
+ \o \c{-o<file>}
+ \o Write output to \c <file> rather than to standard output.
+
+ \row
+ \o \c{-f[<file>]}
+ \o Force the generation of an \c #include statement in the
+ output. This is the default for header files whose extension
+ starts with \c H or \c h. This option is useful if you have
+ header files that do not follow the standard naming conventions.
+ The \c <file> part is optional.
+
+ \row
+ \o \c -i
+ \o Do not generate an \c #include statement in the output.
+ This may be used to run the moc on on a C++ file containing one or
+ more class declarations. You should then \c #include the meta-object
+ code in the \c .cpp file.
+
+ \row
+ \o \c -nw
+ \o Do not generate any warnings. (Not recommended.)
+
+ \row
+ \o \c {-p<path>}
+ \o Makes the moc prepend \c {<path>/} to the file name in the
+ generated \c #include statement.
+
+ \row
+ \o \c {-I<dir>}
+ \o Add dir to the include path for header files.
+
+ \row
+ \o \c{-E}
+ \o Preprocess only; do not generate meta-object code.
+
+ \row
+ \o \c {-D<macro>[=<def>]}
+ \o Define macro, with optional definition.
+
+ \row
+ \o \c{-U<macro>}
+ \o Undefine macro.
+
+ \row
+ \o \c{@<file>}
+ \o Read additional command-line options from \c{<file>}.
+ Each line of the file is treated as a single option. Empty lines
+ are ignored. Note that this option is not supported within the
+ options file itself (i.e. an options file can't "include" another
+ file).
+
+ \row
+ \o \c{-h}
+ \o Display the usage and the list of options.
+
+ \row
+ \o \c {-v}
+ \o Display \c{moc}'s version number.
+
+ \row
+ \o \c{-Fdir}
+
+ \o Mac OS X. Add the framework directory \c{dir} to the head of
+ the list of directories to be searched for header files. These
+ directories are interleaved with those specified by -I options
+ and are scanned in a left-to-right order (see the manpage for
+ gcc). Normally, use -F /Library/Frameworks/
+
+ \endtable
+
+ You can explicitly tell the moc not to parse parts of a header
+ file. \c moc defines the preprocessor symbol \c Q_MOC_RUN. Any
+ code surrounded by
+
+ \snippet doc/src/snippets/code/doc_src_moc.qdoc 4
+
+ is skipped by the \c moc.
+
+ \section1 Diagnostics
+
+ \c moc will warn you about a number of dangerous or illegal
+ constructs in the Q_OBJECT class declarations.
+
+ If you get linkage errors in the final building phase of your
+ program, saying that \c YourClass::className() is undefined or
+ that \c YourClass lacks a vtable, something has been done wrong.
+ Most often, you have forgotten to compile or \c #include the
+ moc-generated C++ code, or (in the former case) include that
+ object file in the link command. If you use \c qmake, try
+ rerunning it to update your makefile. This should do the trick.
+
+ \section1 Limitations
+
+ \c moc does not handle all of C++. The main problem is that class
+ templates cannot have signals or slots. Here is an example:
+
+ \snippet doc/src/snippets/code/doc_src_moc.qdoc 5
+
+ Another limitation is that moc does not expand macros, so you
+ for example cannot use a macro to declare a signal/slot
+ or use one to define a base class for a QObject.
+
+ Less importantly, the following constructs are illegal. All of
+ them have alternatives which we think are usually better, so
+ removing these limitations is not a high priority for us.
+
+ \section2 Multiple Inheritance Requires QObject to Be First
+
+ If you are using multiple inheritance, \c moc assumes that the
+ first inherited class is a subclass of QObject. Also, be sure
+ that only the first inherited class is a QObject.
+
+ \snippet doc/src/snippets/code/doc_src_moc.qdoc 6
+
+ Virtual inheritance with QObject is \e not supported.
+
+ \section2 Function Pointers Cannot Be Signal or Slot Parameters
+
+ In most cases where you would consider using function pointers as
+ signal or slot parameters, we think inheritance is a better
+ alternative. Here is an example of illegal syntax:
+
+ \snippet doc/src/snippets/code/doc_src_moc.qdoc 7
+
+ You can work around this restriction like this:
+
+ \snippet doc/src/snippets/code/doc_src_moc.qdoc 8
+
+ It may sometimes be even better to replace the function pointer
+ with inheritance and virtual functions.
+
+ \section2 Enums and Typedefs Must Be Fully Qualified for Signal and Slot Parameters
+
+ When checking the signatures of its arguments, QObject::connect()
+ compares the data types literally. Thus,
+ \l{Qt::Alignment}{Alignment} and \l{Qt::Alignment} are treated as
+ two distinct types. To work around this limitation, make sure to
+ fully qualify the data types when declaring signals and slots,
+ and when establishing connections. For example:
+
+ \snippet doc/src/snippets/code/doc_src_moc.qdoc 9
+
+ \section2 Type Macros Cannot Be Used for Signal and Slot Parameters
+
+ Since \c moc doesn't expand \c{#define}s, type macros that take
+ an argument will not work in signals and slots. Here is an
+ illegal example:
+
+ \snippet doc/src/snippets/code/doc_src_moc.qdoc 10
+
+ A macro without parameters will work.
+
+ \section2 Nested Classes Cannot Have Signals or Slots
+
+ Here's an example of the offending construct:
+
+ \snippet doc/src/snippets/code/doc_src_moc.qdoc 11
+
+ \section2 Signal/Slot return types cannot be references
+
+ Signals and slots can have return types, but signals or slots returning references
+ will be treated as returning void.
+
+ \section2 Only Signals and Slots May Appear in the \c signals and \c slots Sections of a Class
+
+ \c moc will complain if you try to put other constructs in the \c
+ signals or \c slots sections of a class than signals and slots.
+
+ \sa {Meta-Object System}, {Signals and Slots}, {Qt's Property System}
+*/
diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc
new file mode 100644
index 0000000..181ba6a
--- /dev/null
+++ b/doc/src/development/qmake-manual.qdoc
@@ -0,0 +1,4320 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page qmake-manual.html
+ \title qmake Manual
+ \startpage {index.html}{Qt Reference Documentation}
+ \nextpage qmake Tutorial
+
+ \ingroup qttools
+ \keyword qmake
+
+ \c qmake is a tool that helps simplify the build
+ process for development project across different platforms. \c qmake
+ automates the generation of Makefiles so that only a few lines of
+ information are needed to create each Makefile. \c qmake can be used for
+ any software project, whether it is written in Qt or not.
+
+ \c qmake generates a Makefile based on the information in a project
+ file. Project files are created by the developer, and are usually
+ simple, but more sophisticated project files can be created for
+ complex projects.
+ \c qmake contains additional features to support development with Qt,
+ automatically including build rules for \l{moc.html}{moc}
+ and \l{uic.html}{uic}.
+ \c qmake can also generate projects for Microsoft Visual studio
+ without requiring the developer to change the project file.
+
+ \section1 Getting Started
+
+ The \l{qmake Tutorial} and guide to \l{qmake Common Projects} provide overviews
+ that aim to help new users get started with \c qmake.
+
+ \list
+ \o \l{qmake Tutorial}
+ \tableofcontents{1 qmake Tutorial}
+ \endlist
+
+ \list
+ \o \l{qmake Common Projects}
+ \tableofcontents{1 qmake Common Projects}
+ \endlist
+
+ \section1 Table of Contents
+
+ \list
+ \o \l{Using qmake}
+ \tableofcontents{1 Using qmake}
+ \o \l{qmake Project Files}
+ \tableofcontents{1 qmake Project Files}
+ \o \l{Running qmake}
+ \tableofcontents{1 Running qmake}
+ \o \l{qmake Platform Notes}
+ \tableofcontents{1 qmake Platform Notes}
+ \o \l{qmake Advanced Usage}
+ \tableofcontents{1 qmake Advanced Usage}
+ \o \l{Using Precompiled Headers}
+ \tableofcontents{1 Using Precompiled Headers}
+ \o \l{qmake Reference}
+ \tableofcontents{1 qmake Reference}
+ \o \l{qmake Variable Reference}
+ \tableofcontents{1 qmake Variable Reference}
+ \o \l{qmake Function Reference}
+ \tableofcontents{1 qmake Function Reference}
+ \o \l{Configuring qmake's Environment}
+ \tableofcontents{1 Configuring qmake's Environment}
+ \endlist
+*/
+
+/*!
+ \page qmake-using.html
+ \title Using qmake
+ \contentspage {qmake Manual}{Contents}
+ \previouspage qmake Manual
+ \nextpage qmake Project Files
+
+ \c qmake provides a project-oriented system for managing the build
+ process for applications, libraries, and other components. This
+ approach gives developers control over the source files used, and
+ allows each of the steps in the process to be described concisely,
+ typically within a single file. \c qmake expands the information in
+ each project file to a Makefile that executes the necessary commands
+ for compiling and linking.
+
+ In this document, we provide a basic introduction to project files,
+ describe some of the main features of \c qmake, and show how to use
+ \c qmake on the command line.
+
+ \section1 Describing a Project
+
+ Projects are described by the contents of project (\c .pro) files.
+ The information within these is used by \c qmake to generate a Makefile
+ containing all the commands that are needed to build each project.
+ Project files typically contain a list of source and header files,
+ general configuration information, and any application-specific details,
+ such as a list of extra libraries to link against, or a list of extra
+ include paths to use.
+
+ Project files can contain a number of different elements, including
+ comments, variable declarations, built-in functions, and some simple
+ control structures. In most simple projects, it is only necessary
+ to declare the source and header files that are used to build the
+ project with some basic configuration options.
+
+ Complete examples of project files can be found in the
+ \l{qmake Tutorial}.
+ An introduction to project files can be found in the
+ \l{qmake Project Files} chapter, and a more detailed description is
+ available in the \l{qmake Reference}.
+
+ \section1 Building a Project
+
+ For simple projects, you only need to run \c qmake in the top
+ level directory of your project. By default, \c qmake generates a
+ Makefile that you then use to build the project, and you can then
+ run your platform's \c make tool to build the project.
+
+ \c qmake can also be used to generate project files. A full
+ description of \c{qmake}'s command line options can be found in the
+ \l{Running qmake} chapter of this manual.
+
+ \section1 Using Precompiled Headers
+
+ In large projects, it is possible to take advantage of precompiled
+ header files to speed up the build process. This feature is described
+ in detail in the \l{Using Precompiled Headers} chapter.
+*/
+
+/*!
+ \page qmake-project-files.html
+ \title qmake Project Files
+ \contentspage {qmake Manual}{Contents}
+ \previouspage Using qmake
+ \nextpage Running qmake
+
+ Project files contain all the information required by \c qmake to build
+ your application, library, or plugin. The resources used by your project
+ are generally specified using a series of declarations, but support for
+ simple programming constructs allow you to describe different build
+ processes for different platforms and environments.
+
+ \tableofcontents
+
+ \section1 Project File Elements
+
+ The project file format used by \c qmake can be used to support both
+ simple and fairly complex build systems. Simple project files will
+ use a straightforward declarative style, defining standard variables
+ to indicate the source and header files that are used in the project.
+ Complex projects may use the control flow structures to fine-tune the
+ build process.
+
+ The following sections describe the different types of elements used
+ in project files.
+
+ \section2 Variables
+
+ In a project file, variables are used to hold lists of strings.
+ In the simplest projects, these variables inform \c qmake about the
+ configuration options to use, or supply filenames and paths to use
+ in the build process.
+
+ \c qmake looks for certain variables in each project file, and it
+ uses the contents of these to determine what it should write to a
+ Makefile. For example, the list of values in the \c HEADERS and
+ \c SOURCES variables are used to tell \c qmake about header and
+ source files in the same directory as the project file.
+
+ Variables can also be used internally to store temporary lists of values,
+ and existing lists of values can be overwritten or extended with new
+ values.
+
+ The following lines show how lists of values are assigned to variables:
+
+ \snippet doc/src/snippets/qmake/variables.pro 0
+
+ Note that the first assignment only includes values that are specified on
+ the same line as the \c SOURCES variable. The second assignment splits
+ the items across lines by using the \c \\ character.
+
+ The list of values in a variable is extended in the following way:
+
+ \snippet doc/src/snippets/qmake/variables.pro 1
+
+ The \c CONFIG variable is another special variable that \c qmake
+ uses when generating a Makefile. It is discussed in the section on
+ \l{#GeneralConfiguration}{general configuration} later in this chapter.
+ In the above line, \c qt is added to the list of existing values
+ contained in \c CONFIG.
+
+ The following table lists the variables that \c qmake recognizes, and
+ describes what they should contain.
+
+ \table
+ \header \o Variable \o Contents
+ \row \o CONFIG \o General project configuration options.
+ \row \o DESTDIR \o The directory in which the executable or binary file will
+ be placed.
+ \row \o FORMS \o A list of UI files to be processed by \c uic.
+ \row \o HEADERS \o A list of filenames of header (.h) files used when
+ building the project.
+ \row \o QT \o Qt-specific configuration options.
+ \row \o RESOURCES \o A list of resource (.rc) files to be included in the
+ final project. See the \l{The Qt Resource System} for
+ more information about these files.
+ \row \o SOURCES \o A list of source code files to be used when building
+ the project.
+ \row \o TEMPLATE \o The template to use for the project. This determines
+ whether the output of the build process will be an
+ application, a library, or a plugin.
+ \endtable
+
+ The contents of a variable can be read by prepending the variable name with
+ \c $$. This can be used to assign the contents of one variable to another:
+
+ \snippet doc/src/snippets/qmake/dereferencing.pro 0
+
+ The \c $$ operator is used extensively with built-in functions that operate
+ on strings and lists of values. These are described in the chapter on
+ \l{qmake Advanced Usage}.
+
+ \section3 Whitespace
+
+ Normally, variables are used to contain whitespace-separated lists
+ of values. However, it is sometimes necessary to specify values containing
+ spaces. These must be quoted by using the
+ \l{qmake Function Reference#quote-string}{quote()} function in the following way:
+
+ \snippet doc/src/snippets/qmake/quoting.pro 0
+
+ The quoted text is treated as a single item in the list of values held by
+ the variable. A similar approach is used to deal with paths that contain
+ spaces, particularly when defining the
+ \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} and
+ \l{qmake Variable Reference#LIBS}{LIBS} variables for the Windows platform.
+ In cases like these, the \l{qmake Function Reference#quote(string)}{quote()}
+ function can be used in the following way:
+
+ \snippet doc/src/snippets/qmake/spaces.pro quoting include paths with spaces
+
+ \section2 Comments
+
+ You can add comments to project files. Comments begin with the \c
+ # character and continue to the end of the same line. For example:
+
+ \snippet doc/src/snippets/qmake/comments.pro 0
+
+ To include the \c # character in variable assignments, it is necessary
+ to use the contents of the built-in \c LITERAL_HASH variable. See the
+ \l{qmake Variable Reference#LITERAL_HASH}{variable reference} for more
+ information.
+
+ \section2 Built-in Functions and Control Flow
+
+ \c qmake provides a number of built-in functions to allow the contents
+ of variables to be processed. The most commonly used function in simple
+ project files is the \c include function which takes a filename as an
+ argument. The contents of the given file are included in the project
+ file at the place where the \c include function is used.
+ The \c include function is most commonly used to include other project
+ files:
+
+ \snippet doc/src/snippets/qmake/include.pro 0
+
+ Support for conditional structures is made available via
+ \l{qmake Advanced Usage#scopes}{scopes} that behave like \c if
+ statements in programming languages:
+
+ \snippet doc/src/snippets/qmake/scopes.pro 0
+
+ The assignments inside the braces are only made if the condition is
+ true. In this case, the special \c win32 variable must be set; this
+ happens automatically on Windows, but this can also be specified on
+ other platforms by running \c qmake with the \c{-win32} command line
+ option (see \l{Running qmake} for more information). The opening
+ brace must stand on the same line as the condition.
+
+ Simple loops are constructed by iterating over lists of values using
+ the built-in \c for function. The following code adds directories
+ to the \l{qmake Variable Reference#SUBDIRS}{SUBDIRS} variable, but
+ only if they exist:
+
+ \snippet doc/src/snippets/qmake/functions.pro 0
+
+ More complex operations on variables that would usually require loops
+ are provided by built-in functions such as \c find, \c unique, and
+ \c count. These functions, and many others are provided to manipulate
+ strings and paths, support user input, and call external tools. A list
+ of the functions available can be found in the
+ \l{qmake Advanced Usage} chapter of this manual.
+
+ \section1 Project Templates
+
+ The \c TEMPLATE variable is used to define the type of project that will
+ be built. If this is not declared in the project file, \c qmake assumes
+ that an application should be built, and will generate an appropriate
+ Makefile (or equivalent file) for the purpose.
+
+ The types of project available are listed in the following table with
+ information about the files that \c qmake will generate for each of them:
+
+ \table
+ \header \o Template \o Description of \c qmake output
+ \row \o app (default) \o Creates a Makefile to build an application.
+ \row \o lib \o Creates a Makefile to build a library.
+ \row \o subdirs \o Creates a Makefile containing rules for the
+ subdirectories specified using the \l{qmake Variable Reference#SUBDIRS}{SUBDIRS}
+ variable. Each subdirectory must contain its own project file.
+ \row \o vcapp \o Creates a Visual Studio Project file to build
+ an application.
+ \row \o vclib \o Creates a Visual Studio Project file to build a library.
+ \endtable
+
+ See the \l{qmake Tutorial} for advice on writing project files for
+ projects that use the \c app and \c lib templates.
+
+ When the \c subdirs template is used, \c qmake generates a Makefile
+ to examine each specified subdirectory, process any project file it finds
+ there, and run the platform's \c make tool on the newly-created Makefile.
+ The \l{qmake Variable Reference#SUBDIRS}{SUBDIRS} variable is used to
+ contain a list of all the subdirectories to be processed.
+
+ \target GeneralConfiguration
+ \section1 General Configuration
+
+ The \l{qmake Variable Reference#CONFIG}{CONFIG variable} specifies the
+ options and features that the compiler should use and the libraries that
+ should be linked against. Anything can be added to the \c CONFIG variable,
+ but the options covered below are recognized by \c qmake internally.
+
+ The following options control the compiler flags that are used to build the
+ project:
+
+ \table
+ \header \o Option \o Description
+ \row \o release \o The project is to be built in release mode.
+ This is ignored if \c debug is also specified.
+ \row \o debug \o The project is to be built in debug mode.
+ \row \o debug_and_release \o The project is built in \e both debug and
+ release modes.
+ \row \o debug_and_release_target \o The project is built in \e both debug
+ and release modes. TARGET is built into \e both the debug and release directories.
+ \row \o build_all \o If \c debug_and_release is specified, the project is
+ built in both debug and release modes by default.
+ \row \o autogen_precompile_source \o Automatically generates a \c .cpp file that includes
+ the precompiled header file specified in the .pro file.
+ \row \o ordered \o When using the \c subdirs template, this option
+ specifies that the directories listed should be processed in the
+ order in which they are given.
+ \row \o warn_on \o The compiler should output as many warnings as possible.
+ This is ignored if \c warn_off is specified.
+ \row \o warn_off \o The compiler should output as few warnings as possible.
+ \row \o copy_dir_files \o Enables the install rule to also copy directories, not just files.
+ \endtable
+
+ The \c debug_and_release option is special in that it enables \e both debug and
+ release versions of a project to be built. In such a case, the Makefile that
+ \c qmake generates includes a rule that builds both versions, and this can be
+ invoked in the following way:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 0
+
+ Adding the \c build_all option to the \c CONFIG variable makes this rule
+ the default when building the project, and installation targets will be
+ created for both debug and release builds.
+
+ Note that each of the options specified in the \c CONFIG variable can also be
+ used as a scope condition.
+ You can test for the presence of certain configuration options by using the
+ built-in \l{qmake Function Reference#CONFIG(config)}{CONFIG()} function.
+ For example, the following lines show the function as the condition in a scope
+ to test whether only the \c opengl option is in use:
+
+ \snippet doc/src/snippets/qmake/configscopes.pro 4
+ \snippet doc/src/snippets/qmake/configscopes.pro 5
+
+ This enables different configurations to be defined for \c release and
+ \c debug builds, and is described in more detail in the
+ \l{qmake Advanced Usage#Scopes}{Scopes} section of the
+ \l{qmake Advanced Usage}{Advanced Usage} chapter of this manual.
+
+ The following options define the type of project to be built. Note that some
+ of these options only take effect when used on the relevant platform. On other
+ platforms, they have no effect.
+
+ \table
+ \header \o Option \o Description
+ \row \o qt \o The project is a Qt application and should link against the Qt
+ library. You can use the \c QT variable to control any additional
+ Qt modules that are required by your application.
+ \row \o thread \o The project is a multi-threaded application.
+ \row \o x11 \o The project is an X11 application or library.
+ \endtable
+
+ When using \l{qmake Variable Reference#TEMPLATE}{application or library project
+ templates}, more specialized configuration options can be used to fine tune the
+ build process. These are explained in details in the
+ \l{qmake-common-projects.html}{Common Projects} chapter of this manual.
+
+ For example, if your application uses the Qt library and you want to
+ build it as a multi-threaded application in \c debug mode, your project
+ file will contain the following line:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 1
+
+ Note, that you must use "+=", not "=", or \c qmake will not be able to
+ use Qt's configuration to determine the settings needed for your project.
+
+ \section1 Declaring Qt Libraries
+
+ If the \c CONFIG variable contains the \c qt value, qmake's support for Qt
+ applications is enabled. This makes it possible to fine-tune which of the
+ Qt modules are used by your application. This is achieved with the \c QT
+ variable which can be used to declare the required extension modules.
+ For example, we can enable the XML and network modules in the following way:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 2
+
+ Note that \c QT includes the \c core and \c gui modules by default, so the
+ above declaration \e adds the network and XML modules to this default list.
+ The following assignment \e omits the default modules, and will lead to
+ errors when the application's source code is being compiled:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 3
+
+ If you want to build a project \e without the \c gui module, you need to
+ exclude it with the "-=" operator. By default, \c QT contains both
+ \c core and \c gui, so the following line will result in a minimal
+ Qt project being built:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 4
+
+ The table below shows the options that can be used with the \c QT variable
+ and the features that are associated with each of them:
+
+ \table
+ \header \o Option \o Features
+ \row \o core (included by default) \o QtCore module
+ \row \o gui (included by default) \o QtGui module
+ \row \o network \o QtNetwork module
+ \row \o opengl \o QtOpenGL module
+ \row \o sql \o QtSql module
+ \row \o svg \o QtSvg module
+ \row \o xml \o QtXml module
+ \row \o xmlpatterns \o QtXmlPatterns module
+ \row \o qt3support \o Qt3Support module
+ \endtable
+
+ Note that adding the \c opengl option to the \c QT variable automatically
+ causes the equivalent option to be added to the \c CONFIG variable.
+ Therefore, for Qt applications, it is not necessary to add the \c opengl
+ option to both \c CONFIG and \c{QT}.
+
+ \section1 Configuration Features
+
+ \c qmake can be set up with extra configuration features that are specified
+ in feature (.prf) files. These extra features often provide support for
+ custom tools that are used during the build process. To add a feature to
+ the build process, append the feature name (the stem of the feature filename)
+ to the \c CONFIG variable.
+
+ For example, \c qmake can configure the build process to take advantage
+ of external libraries that are supported by
+ \l{http://www.freedesktop.org/wiki/Software_2fpkgconfig}{pkg-config},
+ such as the D-Bus and ogg libraries, with the following lines:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 5
+
+ More information about features can be found in the
+ \l{qmake Advanced Usage#Adding New Configuration Features}
+ {Adding New Configuration Features} section of the \l{qmake Advanced Usage}
+ chapter.
+
+ \section1 Declaring Other Libraries
+
+ If you are using other libraries in your project in addition to those
+ supplied with Qt, you need to specify them in your project file.
+
+ The paths that \c qmake searches for libraries and the specific libraries
+ to link against can be added to the list of values in the
+ \l{qmake Variable Reference#LIBS}{LIBS} variable. The paths to the libraries
+ themselves can be given, or the familiar Unix-style notation for specifying
+ libraries and paths can be used if preferred.
+
+ For example, the following lines show how a library can be specified:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 6
+
+ The paths containing header files can also be specified in a similar way
+ using the \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} variable.
+
+ For example, it is possible to add several paths to be searched for header
+ files:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 7
+*/
+
+/*!
+ \page qmake-running.html
+ \title Running qmake
+ \contentspage {qmake Manual}{Contents}
+ \previouspage qmake Project Files
+ \nextpage qmake Platform Notes
+
+ The behavior of \c qmake can be customized when it is run by
+ specifying various options on the command line. These allow the
+ build process to be fine-tuned, provide useful diagnostic
+ information, and can be used to specify the target platform for
+ your project.
+
+ \tableofcontents
+
+ \target Commands
+ \section1 Command-Line Options
+
+ \section2 Syntax
+
+ The syntax used to run \c qmake takes the following simple form:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 8
+
+ \c qmake supports two different modes of operation: In the default mode,
+ \c qmake will use the description in a project file to generate a Makefile,
+ but it is also possible to use \c qmake to generate project files.
+ If you want to explicitly set the mode, you must specify it before all
+ other options. The \c mode can be either of the following two values:
+
+ \list
+ \o \c -makefile \BR
+ \c qmake output will be a Makefile.
+ \o \c -project \BR
+ \c qmake output will be a project file. \BR
+\bold{Note:} It is likely that the created file will need to be edited for example adding the \c QT variable to suit what modules are required for the project.
+ \endlist
+
+ The following \c options are used to specify both general and mode-specific
+ settings. Options that only apply to the Makefile mode are described in the
+ \l{#MakefileMode}{Makefile Mode Options} section; options that influence the
+ creation of project files are described in the
+ \l{#ProjectMode}{Project File Options} section.
+
+ The \c files argument represents a list of one or more project files, separated
+ by spaces.
+
+ \section2 Options
+
+ A wide range of options can be specified on the command line to \c qmake in
+ order to customize the build process, and to override default settings for
+ your platform. The following basic options provide usage information, specify
+ where \c qmake writes the output file, and control the level of debugging
+ information that will be written to the console:
+
+ \list
+ \o \c -help \BR
+ \c qmake will go over these features and give some useful help.
+ \o \c -o file \BR
+ \c qmake output will be directed to \e file. If this option
+ is not specified, \c qmake will try to use a suitable file name for its
+ output, depending on the mode it is running in.\BR
+ If '-' is specified, output is directed to stdout.
+ \o \c -d \BR
+ \c qmake will output debugging information.
+ \endlist
+
+ For projects that need to be built differently on each target platform, with
+ many subdirectories, you can run \c qmake with each of the following
+ options to set the corresponding platform-specific variable in each
+ project file:
+
+ \list
+ \o \c -unix \BR
+ \c qmake will run in unix mode. In this mode, Unix file
+ naming and path conventions will be used, additionally testing for \c unix
+ (as a scope) will succeed. This is the default mode on all Unices.
+ \o \c -macx \BR
+ \c qmake will run in Mac OS X mode. In this mode, Unix file
+ naming and path conventions will be used, additionally testing for \c macx
+ (as a scope) will succeed. This is the default mode on Mac OS X.
+ \o \c -win32 \BR
+ \c qmake will run in win32 mode. In this mode, Windows file naming and path
+ conventions will be used, additionally testing for \c win32 (as a scope)
+ will succeed. This is the default mode on Windows.
+ \endlist
+
+ The template used for the project is usually specified by the \c TEMPLATE
+ variable in the project file. We can override or modify this by using the
+ following options:
+
+ \list
+ \o \c -t tmpl \BR
+ \c qmake will override any set \c TEMPLATE variables with tmpl, but only
+ \e after the .pro file has been processed.
+ \o \c -tp prefix \BR
+ \c qmake will add the prefix to the \c TEMPLATE variable.
+ \endlist
+
+ The level of warning information can be fine-tuned to help you find problems in
+ your project file:
+
+ \list
+ \o \c -Wall \BR
+ \c qmake will report all known warnings.
+ \o \c -Wnone \BR
+ No warning information will be generated by \c qmake.
+ \o \c -Wparser \BR
+ \c qmake will only generate parser warnings. This will alert
+ you to common pitfalls and potential problems in the parsing of your
+ project files.
+ \o \c -Wlogic \BR
+ \c qmake will warn of common pitfalls and potential problems in your
+ project file. For example, \c qmake will report whether a file is placed
+ into a list of files multiple times, or if a file cannot be found.
+ \endlist
+
+ \target MakefileMode
+ \section2 Makefile Mode Options
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 9
+
+ In Makefile mode, \c qmake will generate a Makefile that is used to build the
+ project. Additionally, the following options may be used in this mode to
+ influence the way the project file is generated:
+
+ \list
+ \o \c -after \BR
+ \c qmake will process assignments given on the command line after
+ the specified files.
+ \o \c -nocache \BR
+ \c qmake will ignore the .qmake.cache file.
+ \o \c -nodepend \BR
+ \c qmake will not generate any dependency information.
+ \o \c -cache file \BR
+ \c qmake will use \e file as the cache file, ignoring any other
+ .qmake.cache files found.
+ \o \c -spec spec \BR
+ \c qmake will use \e spec as a path to platform and compiler information,
+ and the value of \c QMAKESPEC will be ignored.
+ \endlist
+
+ You may also pass \c qmake assignments on the command line;
+ they will be processed before all of the files specified. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 10
+
+ This will generate a Makefile, from test.pro with Unix pathnames. However
+ many of the specified options aren't necessary as they are the default.
+ Therefore, the line can be simplified on Unix to:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 11
+
+ If you are certain you want your variables processed after the
+ files specified, then you may pass the \c -after option. When this
+ is specified, all assignments on the command line after the \c -after
+ option will be postponed until after the specified files are parsed.
+
+ \target ProjectMode
+ \section2 Project Mode Options
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 12
+
+ In project mode, \c qmake will generate a project file. Additionally, you
+ may supply the following options in this mode:
+
+ \list
+ \o \c -r \BR
+ \c qmake will look through supplied directories recursively
+ \o \c -nopwd \BR
+ \c qmake will not look in your current working directory for
+ source code and only use the specified \c files
+ \endlist
+
+ In this mode, the \c files argument can be a list of files or directories.
+ If a directory is specified, it will be included in the \c DEPENDPATH
+ variable, and relevant code from there will be included in the generated
+ project file. If a file is given, it will be appended to the correct
+ variable, depending on its extension; for example, UI files are added
+ to \c FORMS, and C++ files are added to \c SOURCES.
+
+ You may also pass assignments on the command line in this mode. When doing
+ so, these assignments will be placed last in the generated project file.
+*/
+
+/*!
+ \page qmake-platform-notes.html
+ \title qmake Platform Notes
+ \contentspage {qmake Manual}{Contents}
+ \previouspage Running qmake
+ \nextpage qmake Advanced Usage
+
+ Many cross-platform projects can be handled by the \c{qmake}'s basic
+ configuration features. On some platforms, it is sometimes useful, or even
+ necessary, to take advantage of platform-specific features. \c qmake knows
+ about many of these features, and these can be accessed via specific
+ variables that only have an effect on the platforms where they are relevant.
+
+ \tableofcontents
+
+ \section1 Mac OS X
+
+ Features specific to this platform include support for creating universal
+ binaries, frameworks and bundles.
+
+ \section2 Source and Binary Packages
+
+ The version of \c qmake supplied in source packages is configured slightly
+ differently to that supplied in binary packages in that it uses a different
+ feature specification. Where the source package typically uses the
+ \c macx-g++ specification, the binary package is typically configured to
+ use the \c macx-xcode specification.
+
+ Users of each package can override this configuration by invoking \c qmake
+ with the \c -spec option (see \l{Running qmake} for more information). This
+ makes it possible, for example, to use \c qmake from a binary package to
+ create a Makefile in a project directory with the following command line
+ invocation:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 13
+
+ \section2 Using Frameworks
+
+ \c qmake is able to automatically generate build rules for linking against
+ frameworks in the standard framework directory on Mac OS X, located at
+ \c{/Library/Frameworks/}.
+
+ Directories other than the standard framework directory need to be specified
+ to the build system, and this is achieved by appending linker options to the
+ \l{qmake Variable Reference#QMAKE_LFLAGS}{QMAKE_LFLAGS} variable, as shown
+ in the following example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 14
+
+ The framework itself is linked in by appending the \c{-framework} options and
+ the name of the framework to the \l{qmake Variable Reference#LIBS}{LIBS}
+ variable:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 15
+
+ \section2 Creating Frameworks
+
+ Any given library project can be configured so that the resulting library
+ file is placed in a
+ \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html}
+ {framework}, ready for deployment. To do this, set up the project to use the
+ \l{qmake Variable Reference#TEMPLATE}{\c lib template} and add the
+ \c lib_bundle option to the
+ \l{qmake Variable Reference#CONFIG}{CONFIG} variable:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 16
+
+ The data associated with the library is specified using the
+ \l{qmake Variable Reference#QMAKE_BUNDLE_DATA}{QMAKE_BUNDLE_DATA}
+ variable. This holds items that will be installed with a library
+ bundle, and is often used to specify a collection of header files,
+ as in the following example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 17
+
+ Here, the \c FRAMEWORK_HEADERS variable is a user-defined variable that
+ is used to define the headers required to use a particular framework.
+ Appending it to the \c QMAKE_BUNDLE_DATA variable ensures that the
+ information about these headers are added to the collection of
+ resources that will be installed with the library bundle. Also, the
+ framework's name and version are specified by
+ \l{qmake Variable Reference#QMAKE_FRAMEWORK_BUNDLE_NAME}
+ {QMAKE_FRAMEWORK_BUNDLE_NAME}
+ and \l{qmake Variable Reference#QMAKE_FRAMEWORK_VERSION}
+ {QMAKE_FRAMEWORK_VERSION} variables. By default, the values used for
+ these are obtained from the \l{qmake Variable Reference#TARGET}{TARGET}
+ and \l{qmake Variable Reference#VERSION}{VERSION} variables.
+
+ See \l{Deploying an Application on Mac OS X} for more information about
+ deploying applications and libraries.
+
+ \section2 Creating Universal Binaries
+
+ To create a universal binary for your application, you need to be using
+ a version of Qt that has been configured with the \c{-universal} option.
+
+ The architectures to be supported in the binary are specified with the
+ \l{qmake Variable Reference#CONFIG}{CONFIG} variable. For example, the
+ following assignment causes \c qmake to generate build rules to create
+ a universal binary for both PowerPC and x86 architectures:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 18
+
+ Additionally, developers using a PowerPC-based platform need to set the
+ \l{qmake Variable Reference#QMAKE_MAC_SDK}{QMAKE_MAC_SDK} variable.
+ This process is discussed in more detail in the
+ \l{Deploying an Application on Mac OS X#Architecture Dependencies}{deployment guide for Mac OS X}.
+
+ \section2 Creating and Moving Xcode Projects
+
+ Developers on Mac OS X can take advantage of \c{qmake}'s support for Xcode
+ project files, as described in
+ \l{Qt is Mac OS X Native#Development Tools}{Qt is Mac OS X Native},
+ by running \c qmake to generate an Xcode project from an existing \c qmake
+ project files. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 19
+
+ Note that, if a project is later moved on the disk, \c qmake must be run
+ again to process the project file and create a new Xcode project file.
+
+ \section2 On supporting two build targets simultaneously
+
+ Implementing this is currently not feasible, because the XCode
+ concept of Active Build Configurations is conceptually different
+ from the qmake idea of build targets.
+
+ The XCode Active Build Configurations settings are for modifying
+ xcode configurations, compiler flags and similar build
+ options. Unlike Visual Studio, XCode does not allow for the
+ selection of specific library files based on whether debug or
+ release build configurations are selected. The qmake debug and
+ release settings control which library files are linked to the
+ executable.
+
+ It is currently not possible to set files in XCode configuration
+ settings from the qmake generated xcode project file. The way the
+ libraries are linked in the "Frameworks & Libraries" phase in the
+ XCode build system.
+
+ Furthermore, The selected "Active Build Configuration" is stored
+ in a .pbxuser file, which is generated by xcode on first load, not
+ created by qmake.
+
+ \section1 Windows
+
+ Features specific to this platform include support for creating Visual
+ Studio project files and handling manifest files when deploying Qt
+ applications developed using Visual Studio 2005.
+
+ \section2 Creating Visual Studio Project Files
+
+ Developers using Visual Studio to write Qt applications can use the
+ Visual Studio integration facilities provided with the
+ \l{Qt Commercial Editions} and do not need to worry about how
+ project dependencies are managed.
+
+ However, some developers may need to import an existing \c qmake project
+ into Visual Studio. \c qmake is able to take a project file and create a
+ Visual Studio project that contains all the necessary information required
+ by the development environment. This is achieved by setting the \c qmake
+ \l{qmake Variable Reference#TEMPLATE}{project template} to either \c vcapp
+ (for application projects) or \c vclib (for library projects).
+
+ This can also be set using a command line option, for example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 20
+
+ It is possible to recursively generate \c{.vcproj} files in subdirectories
+ and a \c{.sln} file in the main directory, by typing:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 21
+
+ Each time you update the project file, you need to run \c qmake to generate
+ an updated Visual Studio project.
+
+ \note If you are using the Visual Studio Add-in, you can import \c .pro
+ files via the \gui{Qt->Import from .pro file} menu item.
+
+ \section2 Visual Studio 2005 Manifest Files
+
+ When deploying Qt applications built using Visual Studio 2005, it is
+ necessary to ensure that the manifest file, created when the application
+ was linked, is handled correctly. This is handled automatically for
+ projects that generate DLLs.
+
+ Removing manifest embedding for application executables can be done with
+ the following assignment to the \l{qmake Variable Reference#CONFIG}
+ {CONFIG} variable:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 22
+
+ Also, the manifest embedding for DLLs can be removed with the following
+ assignment to the \l{qmake Variable Reference#CONFIG}{CONFIG} variable:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 23
+
+ This is discussed in more detail in the
+ \l{Deploying an Application on Windows#Visual Studio 2005 Onwards}
+ {deployment guide for Windows}.
+*/
+
+/*!
+ \page qmake-reference.html
+ \title qmake Reference
+ \contentspage {qmake Manual}{Contents}
+ \previouspage Using Precompiled Headers
+ \nextpage qmake Variable Reference
+
+ This reference is a detailed index of all the variables and function
+ that are available for use in \c qmake project files.
+
+ \section1 Variable Reference
+
+ The \l{qmake Variable Reference} describes the variables that are
+ recognized by \c qmake when configuring the build process for
+ projects.
+
+ \section1 Function Reference
+
+ The \l{qmake Function Reference} describes the function that can be
+ used to process the contents of variables defined in project files.
+
+ \target FrequentlyUsedVariables
+ \section1 Frequently Used Variables
+
+ The following variables are frequently used in project files to describe
+ common aspects of the build process. These are fully described in the
+ \l{qmake-variable-reference.html}{Variable Reference}.
+
+ \list
+ \o \l{qmake Variable Reference#CONFIG}{CONFIG}
+ \o \l{qmake Variable Reference#DEF_FILE}{DEF_FILE}
+ \o \l{qmake Variable Reference#DEFINES}{DEFINES}
+ \o \l{qmake Variable Reference#DESTDIR}{DESTDIR}
+ \o \l{qmake Variable Reference#DISTFILES}{DISTFILES}
+ \o \l{qmake Variable Reference#DLLDESTDIR}{DLLDESTDIR}
+ \o \l{qmake Variable Reference#FORMS}{FORMS}
+ \o \l{qmake Variable Reference#FORMS3}{FORMS3}
+ \o \l{qmake Variable Reference#GUID}{GUID}
+ \o \l{qmake Variable Reference#HEADERS}{HEADERS}
+ \o \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH}
+ \o \l{qmake Variable Reference#LEXSOURCES}{LEXSOURCES}
+ \o \l{qmake Variable Reference#LIBS}{LIBS}
+ \o \l{qmake Variable Reference#MOC_DIR}{MOC_DIR}
+ \o \l{qmake Variable Reference#OBJECTS_DIR}{OBJECTS_DIR}
+ \o \l{qmake Variable Reference#QT}{QT}
+ \o \l{qmake Variable Reference#RCC_DIR}{RCC_DIR}
+ \o \l{qmake Variable Reference#REQUIRES}{REQUIRES}
+ \o \l{qmake Variable Reference#RESOURCES}{RESOURCES}
+ \o \l{qmake Variable Reference#SOURCES}{SOURCES}
+ \o \l{qmake Variable Reference#SUBDIRS}{SUBDIRS}
+ \o \l{qmake Variable Reference#TARGET}{TARGET}
+ \o \l{qmake Variable Reference#TEMPLATE}{TEMPLATE}
+ \o \l{qmake Variable Reference#TRANSLATIONS}{TRANSLATIONS}
+ \o \l{qmake Variable Reference#UI_DIR}{UI_DIR}
+ \o \l{qmake Variable Reference#UI_HEADERS_DIR}{UI_HEADERS_DIR}
+ \o \l{qmake Variable Reference#UI_SOURCES_DIR}{UI_SOURCES_DIR}
+ \o \l{qmake Variable Reference#VERSION}{VERSION}
+ \o \l{qmake Variable Reference#YACCSOURCES}{YACCSOURCES}
+ \endlist
+
+ \section1 Environment Variables and Configuration
+
+ The \l{Configuring qmake's Environment} chapter of this manual
+ describes the environment variables that \c qmake uses when
+ configuring the build process.
+*/
+
+/*!
+ \page qmake-variable-reference.html
+ \title qmake Variable Reference
+ \contentspage {qmake Manual}{Contents}
+ \previouspage qmake Reference
+ \nextpage qmake Function Reference
+
+ \c{qmake}'s fundamental behavior is influenced by variable declarations that
+ define the build process of each project. Some of these declare resources,
+ such as headers and source files, that are common to each platform; others
+ are used to customize the behavior of compilers and linkers on specific
+ platforms.
+
+ Platform-specific variables follow the naming pattern of the
+ variables which they extend or modify, but include the name of the relevant
+ platform in their name. For example, \c QMAKE_LIBS can be used to specify a list
+ of libraries that a project needs to link against, and \c QMAKE_LIBS_X11 can be
+ used to extend or override this list.
+
+ \tableofcontents{3}
+
+ \target CONFIG
+ \section1 CONFIG
+
+ The \c CONFIG variable specifies project configuration and
+ compiler options. The values will be recognized internally by
+ \c qmake and have special meaning. They are as follows.
+
+ These \c CONFIG values control compilation flags:
+
+ \table 95%
+ \header \o Option \o Description
+ \row \o release \o The project is to be built in release mode.
+ This is ignored if \c debug is also specified.
+ \row \o debug \o The project is to be built in debug mode.
+ \row \o debug_and_release \o The project is built in \e both debug and
+ release modes. This can have some unexpected side effects (see
+ below for more information).
+ \row \o build_all \o If \c debug_and_release is specified, the project is
+ built in both debug and release modes by default.
+ \row \o ordered \o When using the \c subdirs template, this option
+ specifies that the directories listed should be processed in the
+ order in which they are given.
+ \row \o precompile_header \o Enables support for the use of
+ \l{Using Precompiled Headers}{precompiled headers} in projects.
+ \row \o warn_on \o The compiler should output as many warnings as possible.
+ This is ignored if \c warn_off is specified.
+ \row \o warn_off \o The compiler should output as few warnings as possible.
+ \omit
+ \row \o qt_debug \o Specifies that the project should be built against
+ debug versions of the Qt libraries specified using the
+ \l{#QT}{QT} variable.
+ \row \o qt_release \o Specifies that the project should be built against
+ release versions of the Qt libraries specified using the
+ \l{#QT}{QT} variable.
+ \endomit
+ \endtable
+
+ Since the \c debug option overrides the \c release option when both are
+ defined in the \c CONFIG variable, it is necessary to use the
+ \c debug_and_release option if you want to allow both debug and release
+ versions of a project to be built. In such a case, the Makefile that
+ \c qmake generates includes a rule that builds both versions, and this can
+ be invoked in the following way:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 24
+
+ When linking a library, \c qmake relies on the underlying platform to know
+ what other libraries this library links against. However, if linking
+ statically, \c qmake will not get this information unless we use the following
+ \c CONFIG options:
+
+ \table 95%
+ \header \o Option \o Description
+ \row \o create_prl \o This option enables \c qmake to track these
+ dependencies. When this option is enabled, \c qmake will create a file
+ ending in \c .prl which will save meta-information about the library
+ (see \l{LibDepend}{Library Dependencies} for more info).
+ \row \o link_prl \o When this is enabled, \c qmake will process all
+ libraries linked to by the application and find their meta-information
+ (see \l{LibDepend}{Library Dependencies} for more info).
+ \endtable
+
+ Please note that \c create_prl is required when \e {building} a
+ static library, while \c link_prl is required when \e {using} a
+ static library.
+
+ On Windows (or if Qt is configured with \c{-debug_and_release}, adding the
+ \c build_all option to the \c CONFIG variable makes this rule the default
+ when building the project, and installation targets will be created for
+ both debug and release builds.
+
+ Additionally, adding \c debug_and_release to the \c CONFIG variable will
+ cause both \c debug and \c release to be defined in the contents of
+ \c CONFIG. When the project file is processed, the
+ \l{qmake Advanced Usage#Scopes}{scopes} that test for each value will be
+ processed for \e both debug and release modes. The \c{build_pass} variable
+ will be set for each of these mode, and you can test for this to perform
+ build-specific tasks. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 25
+
+ As a result, it may be useful to define mode-specific variables, such as
+ \l{#QMAKE_LFLAGS_RELEASE}{QMAKE_LFLAGS_RELEASE}, instead of general
+ variables, such as \l{#QMAKE_LFLAGS}{QMAKE_LFLAGS}, where possible.
+
+ The following options define the application/library type:
+
+ \table 95%
+ \header \o Option \o Description
+ \row \o qt \o The target is a Qt application/library and requires the Qt
+ library and header files. The proper include and library paths for the
+ Qt library will automatically be added to the project. This is defined
+ by default, and can be fine-tuned with the \c{\l{#qt}{QT}} variable.
+ \row \o thread \o The target is a multi-threaded application or library. The
+ proper defines and compiler flags will automatically be added to
+ the project.
+ \row \o x11 \o The target is a X11 application or library. The proper
+ include paths and libraries will automatically be added to the
+ project.
+ \row \o windows \o The target is a Win32 window application (app only). The
+ proper include paths, compiler flags and libraries will
+ automatically be added to the project.
+ \row \o console \o The target is a Win32 console application (app only). The
+ proper include paths, compiler flags and libraries will
+ automatically be added to the
+ project.
+ \row \o shared \o{1,3} The target is a shared object/DLL. The proper
+ include paths, compiler flags and libraries will automatically be
+ added to the project.
+ \row \o dll \o
+ \row \o dylib \o
+ \row \o static \o{1,2} The target is a static library (lib only). The proper
+ compiler flags will automatically be added to the project.
+ \row \o staticlib \o
+ \row \o plugin \o The target is a plugin (lib only). This enables dll as well.
+ \row \o designer \o The target is a plugin for \QD.
+ \row \o uic3 \o Configures qmake to run uic3 on the content of \c FORMS3 if
+ defined; otherwise the contents of \c FORMS will be processed instead.
+ \row \o no_lflags_merge \o Ensures that the list of libraries stored in the
+ \c LIBS variable is not reduced to a list of unique values before it is used.
+ \row \o resources \o Configures qmake to run rcc on the content of \c RESOURCES
+ if defined.
+ \endtable
+
+ These options are used to set the compiler flags:
+
+ \table 95%
+ \header \o Option \o Description
+ \row \o 3dnow \o AMD 3DNow! instruction support is enabled.
+ \row \o exceptions \o Exception support is enabled.
+ \row \o mmx \o Intel MMX instruction support is enabled.
+ \row \o rtti \o RTTI support is enabled.
+ \row \o stl \o STL support is enabled.
+ \row \o sse \o SSE support is enabled.
+ \row \o sse2 \o SSE2 support is enabled.
+ \endtable
+
+ These options define specific features on Windows only:
+
+ \table 95%
+ \header \o Option \o Description
+ \row \o flat \o When using the vcapp template this will put all the source
+ files into the source group and the header files into the header group
+ regardless of what directory they reside in. Turning this
+ option off will group the files within the source/header group depending
+ on the directory they reside. This is turned on by default.
+ \row \o embed_manifest_dll \o Embeds a manifest file in the DLL created
+ as part of a library project.
+ \row \o embed_manifest_exe \o Embeds a manifest file in the DLL created
+ as part of an application project.
+ \row \o incremental \o Used to enable or disable incremental linking in Visual
+ C++, depending on whether this feature is enabled or disabled by default.
+ \endtable
+
+ See \l{qmake Platform Notes#Visual Studio 2005 Manifest Files}{qmake Platform Notes}
+ for more information on the options for embedding manifest files.
+
+ These options only have an effect on Mac OS X:
+
+ \table 95%
+ \header \o Option \o Description
+ \row \o ppc \o Builds a PowerPC binary.
+ \row \o x86 \o Builds an i386 compatible binary.
+ \row \o app_bundle \o Puts the executable into a bundle (this is the default).
+ \row \o lib_bundle \o Puts the library into a library bundle.
+ \endtable
+
+ The build process for bundles is also influenced by
+ the contents of the \l{#QMAKE_BUNDLE_DATA}{QMAKE_BUNDLE_DATA} variable.
+
+ These options have an effect on Linux/Unix platforms:
+
+ \table 95%
+ \header \o Option \o Description
+ \row \o largefile \o Includes support for large files.
+ \row \o separate_debug_info \o Puts debugging information for libraries in
+ separate files.
+ \endtable
+
+ The \c CONFIG variable will also be checked when resolving scopes. You may
+ assign anything to this variable.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 26
+
+ \target DEFINES
+ \section1 DEFINES
+
+ \c qmake adds the values of this variable as compiler C
+ preprocessor macros (-D option).
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 27
+
+ \target DEF_FILE
+ \section1 DEF_FILE
+
+ \e {This is only used on Windows when using the \c app template}.
+
+ Specifies a \c .def file to be included in the project.
+
+ \target DEPENDPATH
+ \section1 DEPENDPATH
+
+ This variable contains the list of all directories to look in to
+ resolve dependencies. This will be used when crawling through
+ \c included files.
+
+ \target DEPLOYMENT
+ \section1 DEPLOYMENT
+
+ \e {This is only used on Windows CE.}
+
+ Specifies which additional files will be deployed. Deployment means the
+ transfer of files from the development system to the target device or
+ emulator.
+
+ Files can be deployed by either creating a Visual Studio project or using
+ the \l {Using QTestLib remotely on Windows CE}{cetest} executable.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 28
+
+ This will upload all PNG images in \c path to the same directory your
+ build target will be deployed to.
+
+ The default deployment target path for Windows CE is
+ \c{%CSIDL_PROGRAM_FILES%\target}, which usually gets expanded to
+ \c{\Program Files\target}.
+
+ It is also possible to specify multiple \c sources to be deployed on
+ target \c paths. In addition, different variables can be used for
+ deployment to different directories.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 29
+
+ \note All linked Qt libraries will be deployed to the path specified
+ by \c{myFiles.path}.
+
+ \target DEPLOYMENT_PLUGIN
+ \section1 DEPLOYMENT_PLUGIN
+
+ \e {This is only used on Windows CE.}
+
+ This variable specifies the Qt plugins that will be deployed. All plugins
+ available in Qt can be explicitly deployed to the device. See
+ \l{Static Plugins}{Static Plugins} for a complete list.
+
+ \note No plugins will be deployed automatically. If the application
+ depends on plugins, these plugins have to be specified manually.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 128
+
+ This will upload the jpeg imageformat plugin to the plugins directory
+ on the Windows CE device.
+
+ \target DESTDIR
+ \section1 DESTDIR
+
+ Specifies where to put the \l{#TARGET}{target} file.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 30
+
+ \target DESTDIR_TARGET
+ \section1 DESTDIR_TARGET
+
+ This variable is set internally by \c qmake, which is basically the
+ \c DESTDIR variable with the \c TARGET variable appened at the end.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target DLLDESTDIR
+ \section1 DLLDESTDIR
+
+ Specifies where to copy the \l{#TARGET}{target} dll.
+
+ \target DISTFILES
+ \section1 DISTFILES
+
+ This variable contains a list of files to be included in the dist
+ target. This feature is supported by UnixMake specs only.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 31
+
+ \target DSP_TEMPLATE
+ \section1 DSP_TEMPLATE
+
+ This variable is set internally by \c qmake, which specifies where the
+ dsp template file for basing generated dsp files is stored. The value
+ of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target FORMS
+ \section1 FORMS
+
+ This variable specifies the UI files (see \link
+ designer-manual.html Qt Designer \endlink) to be processed through \c uic
+ before compiling. All dependencies, headers and source files required
+ to build these UI files will automatically be added to the project.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 32
+
+ If FORMS3 is defined in your project, then this variable must contain
+ forms for uic, and not uic3. If CONFIG contains uic3, and FORMS3 is not
+ defined, the this variable must contain only uic3 type forms.
+
+ \target FORMS3
+ \section1 FORMS3
+
+ This variable specifies the old style UI files to be processed
+ through \c uic3 before compiling, when \c CONFIG contains uic3.
+ All dependencies, headers and source files required to build these
+ UI files will automatically be added to the project.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 33
+
+ \target GUID
+ \section1 GUID
+
+ Specifies the GUID that is set inside a \c{.vcproj} file. The GUID is
+ usually randomly determined. However, should you require a fixed GUID,
+ it can be set using this variable.
+
+ This variable is specific to \c{.vcproj} files only; it is ignored
+ otherwise.
+
+ \target HEADERS
+ \section1 HEADERS
+
+ Defines the header files for the project.
+
+ \c qmake will generate dependency information (unless \c -nodepend
+ is specified on the \l{Running qmake#Commands}{command line})
+ for the specified headers. \c qmake will also automatically detect if
+ \c moc is required by the classes in these headers, and add the
+ appropriate dependencies and files to the project for generating and
+ linking the moc files.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 34
+
+ See also \l{#SOURCES}{SOURCES}.
+
+ \target INCLUDEPATH
+ \section1 INCLUDEPATH
+
+ This variable specifies the #include directories which should be
+ searched when compiling the project. Use ';' or a space as the
+ directory separator.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 35
+
+ To specify a path containing spaces, quote the path using the technique
+ mentioned in the \l{qmake Project Files#Whitespace}{qmake Project Files}
+ document. For example, paths with spaces can be specified on Windows
+ and Unix platforms by using the \l{qmake Function Reference#quote-string}{quote()}
+ function in the following way:
+
+ \snippet doc/src/snippets/qmake/spaces.pro quoting include paths with spaces
+
+ \target INSTALLS
+ \section1 INSTALLS
+
+ This variable contains a list of resources that will be installed when
+ \c{make install} or a similar installation procedure is executed. Each
+ item in the list is typically defined with attributes that provide
+ information about where it will be installed.
+
+ For example, the following \c{target.path} definition describes where the
+ build target will be installed, and the \c INSTALLS assignment adds the
+ build target to the list of existing resources to be installed:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 36
+
+ \target LEXIMPLS
+ \section1 LEXIMPLS
+
+ This variable contains a list of lex implementation files. The value
+ of this variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
+ needs to be modified.
+
+ \target LEXOBJECTS
+ \section1 LEXOBJECTS
+
+ This variable contains the names of intermediate lex object
+ files.The value of this variable is typically handled by
+ \c qmake and rarely needs to be modified.
+
+ \target LEXSOURCES
+ \section1 LEXSOURCES
+
+ This variable contains a list of lex source files. All
+ dependencies, headers and source files will automatically be added to
+ the project for building these lex files.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 37
+
+ \target LIBS
+ \section1 LIBS
+
+ This variable contains a list of libraries to be linked into the project.
+ You can use the Unix \c -l (library) and -L (library path) flags and qmake
+ will do the correct thing with these libraries on Windows (namely this
+ means passing the full path of the library to the linker). The only
+ limitation to this is the library must exist, for qmake to find which
+ directory a \c -l lib lives in.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 38
+
+ To specify a path containing spaces, quote the path using the technique
+ mentioned in the \l{qmake Project Files#Whitespace}{qmake Project Files}
+ document. For example, paths with spaces can be specified on Windows
+ and Unix platforms by using the \l{qmake Function Reference#quote-string}{quote()}
+ function in the following way:
+
+ \snippet doc/src/snippets/qmake/spaces.pro quoting library paths with spaces
+
+ \bold{Note:} On Windows, specifying libraries with the \c{-l} option,
+ as in the above example, will cause the library with the highest version
+ number to be used; for example, \c{libmath2.lib} could potentially be used
+ instead of \c{libmathlib}. To avoid this ambiguity, we recommend that you
+ explicitly specify the library to be used by including the \c{.lib}
+ file name suffix.
+
+ By default, the list of libraries stored in \c LIBS is reduced to a list of
+ unique names before it is used. To change this behavior, add the
+ \c no_lflags_merge option to the \c CONFIG variable:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 39
+
+ \target LITERAL_HASH
+ \section1 LITERAL_HASH
+
+ This variable is used whenever a literal hash character (\c{#}) is needed in
+ a variable declaration, perhaps as part of a file name or in a string passed
+ to some external application.
+
+ For example:
+
+ \snippet doc/src/snippets/qmake/comments.pro 1
+
+ By using \c LITERAL_HASH in this way, the \c # character can be used
+ to construct a URL for the \c message() function to print to the console.
+
+ \target MAKEFILE
+ \section1 MAKEFILE
+
+ This variable specifies the name of the Makefile which
+ \c qmake should use when outputting the dependency information
+ for building a project. The value of this variable is typically
+ handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target MAKEFILE_GENERATOR
+ \section1 MAKEFILE_GENERATOR
+
+ This variable contains the name of the Makefile generator to use
+ when generating a Makefile. The value of this variable is typically
+ handled internally by \c qmake and rarely needs to be modified.
+
+ \target MOC_DIR
+ \section1 MOC_DIR
+
+ This variable specifies the directory where all intermediate moc
+ files should be placed.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 40
+
+ \target OBJECTS
+ \section1 OBJECTS
+
+ This variable is generated from the \link #SOURCES SOURCES
+ \endlink variable. The extension of each source file will have been
+ replaced by .o (Unix) or .obj (Win32). The value of this variable is
+ typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and
+ rarely needs to be modified.
+
+ \target OBJECTS_DIR
+ \section1 OBJECTS_DIR
+
+ This variable specifies the directory where all intermediate
+ objects should be placed.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 41
+
+ \target OBJMOC
+ \section1 OBJMOC
+
+ This variable is set by \c qmake if files can be found that
+ contain the Q_OBJECT macro. \c OBJMOC contains the
+ name of all intermediate moc object files. The value of this variable
+ is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be
+ modified.
+
+ \target POST_TARGETDEPS
+ \section1 POST_TARGETDEPS
+
+ All libraries that the \l{#TARGET}{target} depends on can be
+ listed in this variable. Some backends do not support this, these include
+ MSVC Dsp, and ProjectBuilder .pbproj files. Generally this is supported
+ internally by these build tools, this is useful for explicitly listing
+ dependant static libraries.
+
+ This list will go after all builtin (and \link #PRE_TARGETDEPS
+ $$PRE_TARGETDEPS \endlink) dependencies.
+
+ \target PRE_TARGETDEPS
+ \section1 PRE_TARGETDEPS
+
+ All libraries that the \l{#TARGET}{target} depends on can be
+ listed in this variable. Some backends do not support this, these include
+ MSVC Dsp, and ProjectBuilder .pbproj files. Generally this is supported
+ internally by these build tools, this is useful for explicitly listing
+ dependant static libraries.
+
+ This list will go before all builtin dependencies.
+
+ \target PRECOMPILED_HEADER
+ \section1 PRECOMPILED_HEADER
+
+ This variable indicates the header file for creating a precompiled
+ header file, to increase the compilation speed of a project.
+ Precompiled headers are currently only supported on some platforms
+ (Windows - all MSVC project types, Mac OS X - Xcode, Makefile,
+ Unix - gcc 3.3 and up).
+
+ On other platforms, this variable has different meaning, as noted
+ below.
+
+ This variable contains a list of header files that require some
+ sort of pre-compilation step (such as with moc). The value of this
+ variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be
+ modified.
+
+ \target PWD
+ \section1 PWD
+
+ This variable contains the full path leading to the directory where
+ the \c qmake project file (project.pro) is located.
+
+ \target OUT_PWD
+ \section1 OUT_PWD
+
+ This variable contains the full path leading to the directory where
+ \c qmake places the generated Makefile.
+
+ \target QMAKE_systemvariable
+ \section1 QMAKE
+
+ This variable contains the name of the \c qmake program
+ itself and is placed in generated Makefiles. The value of this
+ variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be
+ modified.
+
+ \target QMAKESPEC_systemvariable
+ \section1 QMAKESPEC
+
+ This variable contains the name of the \c qmake
+ configuration to use when generating Makefiles. The value of this
+ variable is typically handled by \c qmake and rarely needs to be modified.
+
+ Use the \c{QMAKESPEC} environment variable to override the \c qmake configuration.
+ Note that, due to the way \c qmake reads project files, setting the \c{QMAKESPEC}
+ environment variable from within a project file will have no effect.
+
+ \target QMAKE_APP_FLAG
+ \section1 QMAKE_APP_FLAG
+
+ This variable is empty unless the \c app
+ \l{#TEMPLATE}{TEMPLATE} is specified. The value of this
+ variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be
+ modified. Use the following instead:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 42
+
+ \target QMAKE_APP_OR_DLL
+ \section1 QMAKE_APP_OR_DLL
+
+ This variable is empty unless the \c app or \c dll
+ \l{#TEMPLATE}{TEMPLATE} is specified. The value of this
+ variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be
+ modified.
+
+ \target QMAKE_AR_CMD
+ \section1 QMAKE_AR_CMD
+
+ \e {This is used on Unix platforms only.}
+
+ This variable contains the command for invoking the program which
+ creates, modifies and extracts archives. The value of this variable is
+ typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf}
+ and rarely needs to be modified.
+
+ \target QMAKE_BUNDLE_DATA
+ \section1 QMAKE_BUNDLE_DATA
+
+ This variable is used to hold the data that will be installed with a library
+ bundle, and is often used to specify a collection of header files.
+
+ For example, the following lines add \c path/to/header_one.h
+ and \c path/to/header_two.h to a group containing information about the
+ headers supplied with the framework:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 43
+
+ The last line adds the information about the headers to the collection of
+ resources that will be installed with the library bundle.
+
+ Library bundles are created when the \c lib_bundle option is added to the
+ \l{#CONFIG}{CONFIG} variable.
+
+ See \l{qmake Platform Notes#Creating Frameworks}{qmake Platform Notes} for
+ more information about creating library bundles.
+
+ \e{This is used on Mac OS X only.}
+
+ \section1 QMAKE_BUNDLE_EXTENSION
+
+ This variable defines the extension to be used for library bundles.
+ This allows frameworks to be created with custom extensions instead of the
+ standard \c{.framework} directory name extension.
+
+ For example, the following definition will result in a framework with the
+ \c{.myframework} extension:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 44
+
+ \e{This is used on Mac OS X only.}
+
+ \section1 QMAKE_CC
+
+ This variable specifies the C compiler that will be used when building
+ projects containing C source code. Only the file name of the compiler
+ executable needs to be specified as long as it is on a path contained
+ in the \c PATH variable when the Makefile is processed.
+
+ \target QMAKE_CFLAGS_DEBUG
+ \section1 QMAKE_CFLAGS_DEBUG
+
+ This variable contains the flags for the C compiler in debug mode.The value of this variable is
+ typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf}
+ and rarely needs to be modified.
+
+ \target QMAKE_CFLAGS_MT
+ \section1 QMAKE_CFLAGS_MT
+
+ This variable contains the compiler flags for creating a
+ multi-threaded application or when the version of Qt that you link
+ against is a multi-threaded statically linked library. The value of
+ this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target QMAKE_CFLAGS_MT_DBG
+ \section1 QMAKE_CFLAGS_MT_DBG
+
+ This variable contains the compiler flags for creating a debuggable
+ multi-threaded application or when the version of Qt that you link
+ against is a debuggable multi-threaded statically linked library. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target QMAKE_CFLAGS_MT_DLL
+ \section1 QMAKE_CFLAGS_MT_DLL
+
+ \e {This is used on Windows only.}
+
+ This variable contains the compiler flags for creating a
+ multi-threaded dll or when the version of Qt that you link
+ against is a multi-threaded dll. The value of this variable is typically
+ handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and
+ rarely needs to be modified.
+
+ \target QMAKE_CFLAGS_MT_DLLDBG
+ \section1 QMAKE_CFLAGS_MT_DLLDBG
+
+ \e {This is used on Windows only.}
+
+ This variable contains the compiler flags for creating a debuggable
+ multi-threaded dll or when the version of Qt that you link
+ against is a debuggable multi-threaded statically linked library.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target QMAKE_CFLAGS_RELEASE
+ \section1 QMAKE_CFLAGS_RELEASE
+
+ This variable contains the compiler flags for creating a non-debuggable
+ application. The value of this variable is typically
+ handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and
+ rarely needs to be modified.
+
+ \target QMAKE_CFLAGS_SHLIB
+ \section1 QMAKE_CFLAGS_SHLIB
+
+ \e {This is used on Unix platforms only.}
+
+ This variable contains the compiler flags for creating a shared
+ library. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs
+ to be modified.
+
+ \target QMAKE_CFLAGS_THREAD
+ \section1 QMAKE_CFLAGS_THREAD
+
+ This variable contains the compiler flags for creating a multi-threaded
+ application. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs
+ to be modified.
+
+ \target QMAKE_CFLAGS_WARN_OFF
+ \section1 QMAKE_CFLAGS_WARN_OFF
+
+ This variable is not empty if the warn_off
+ \l{#TEMPLATE}{TEMPLATE} option is specified. The value of this
+ variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf}
+ and rarely needs to be modified.
+
+ \target QMAKE_CFLAGS_WARN_ON
+ \section1 QMAKE_CFLAGS_WARN_ON
+
+ This variable is not empty if the warn_on
+ \l{#TEMPLATE}{TEMPLATE} option is specified.
+ The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs
+ to be modified.
+
+ \target QMAKE_CLEAN
+ \section1 QMAKE_CLEAN
+
+ This variable contains any files which are not generated files (such as moc and uic
+ generated files) and object files that should be removed when using "make clean".
+
+ \section1 QMAKE_CXX
+
+ This variable specifies the C++ compiler that will be used when building
+ projects containing C++ source code. Only the file name of the compiler
+ executable needs to be specified as long as it is on a path contained
+ in the \c PATH variable when the Makefile is processed.
+
+ \section1 QMAKE_CXXFLAGS
+
+ This variable contains the C++ compiler flags that are used when building
+ a project. The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. The flags
+ specific to debug and release modes can be adjusted by modifying
+ the \c QMAKE_CXXFLAGS_DEBUG and \c QMAKE_CXXFLAGS_RELEASE variables,
+ respectively.
+
+ \target QMAKE_CXXFLAGS_DEBUG
+ \section1 QMAKE_CXXFLAGS_DEBUG
+
+ This variable contains the C++ compiler flags for creating a debuggable
+ application. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs
+ to be modified.
+
+ \target QMAKE_CXXFLAGS_MT
+ \section1 QMAKE_CXXFLAGS_MT
+
+ This variable contains the C++ compiler flags for creating a multi-threaded
+ application. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs
+ to be modified.
+
+ \target QMAKE_CXXFLAGS_MT_DBG
+ \section1 QMAKE_CXXFLAGS_MT_DBG
+
+ This variable contains the C++ compiler flags for creating a debuggable multi-threaded
+ application. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs
+ to be modified.
+
+ \target QMAKE_CXXFLAGS_MT_DLL
+ \section1 QMAKE_CXXFLAGS_MT_DLL
+
+ \c {This is used on Windows only.}
+
+ This variable contains the C++ compiler flags for creating a multi-threaded
+ dll. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs
+ to be modified.
+
+ \target QMAKE_CXXFLAGS_MT_DLLDBG
+ \section1 QMAKE_CXXFLAGS_MT_DLLDBG
+
+ \c {This is used on Windows only.}
+
+ This variable contains the C++ compiler flags for creating a multi-threaded debuggable
+ dll. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs
+ to be modified.
+
+ \target QMAKE_CXXFLAGS_RELEASE
+ \section1 QMAKE_CXXFLAGS_RELEASE
+
+ This variable contains the C++ compiler flags for creating an
+ application. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs
+ to be modified.
+
+ \target QMAKE_CXXFLAGS_SHLIB
+ \section1 QMAKE_CXXFLAGS_SHLIB
+
+ This variable contains the C++ compiler flags for creating a
+ shared library. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs
+ to be modified.
+
+ \target QMAKE_CXXFLAGS_THREAD
+ \section1 QMAKE_CXXFLAGS_THREAD
+
+ This variable contains the C++ compiler flags for creating a
+ multi-threaded application. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs
+ to be modified.
+
+ \target QMAKE_CXXFLAGS_WARN_OFF
+ \section1 QMAKE_CXXFLAGS_WARN_OFF
+
+ This variable contains the C++ compiler flags for suppressing compiler warnings.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target QMAKE_CXXFLAGS_WARN_ON
+ \section1 QMAKE_CXXFLAGS_WARN_ON
+
+ This variable contains C++ compiler flags for generating compiler warnings.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target QMAKE_DISTCLEAN
+ \section1 QMAKE_DISTCLEAN
+
+ This variable removes extra files upon the invocation of \c{make distclean}.
+
+ \target QMAKE_EXTENSION_SHLIB
+ \section1 QMAKE_EXTENSION_SHLIB
+
+ This variable contains the extention for shared libraries. The value of this
+ variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf}
+ and rarely needs to be modified.
+
+ Note that platform-specific variables that change the extension will override
+ the contents of this variable.
+
+ \section1 QMAKE_EXT_MOC
+
+ This variable changes the extention used on included moc files.
+
+ See also \l{Configuring qmake's Environment#Extensions}{File Extensions}.
+
+ \section1 QMAKE_EXT_UI
+
+ This variable changes the extention used on /e Designer UI files.
+
+ See also \l{Configuring qmake's Environment#Extensions}{File Extensions}.
+
+ \section1 QMAKE_EXT_PRL
+
+ This variable changes the extention used on created PRL files.
+
+ See also \l{Configuring qmake's Environment#Extensions}{File Extensions},
+ \l{Configuring qmake's Environment#libdepend}{Library Dependencies}.
+
+ \section1 QMAKE_EXT_LEX
+
+ This variable changes the extention used on files given to lex.
+
+ See also \l{Configuring qmake's Environment#Extensions}{File Extensions},
+ \l{#LEXSOURCES}{LEXSOURCES}.
+
+ \section1 QMAKE_EXT_YACC
+ This variable changes the extention used on files given to yacc.
+
+ See also \l{Configuring qmake's Environment#Extensions}{File Extensions},
+ \l{#YACCSOURCES}{YACCSOURCES}.
+
+ \section1 QMAKE_EXT_OBJ
+
+ This variable changes the extention used on generated object files.
+
+ See also \l{Configuring qmake's Environment#Extensions}{File Extensions}.
+
+ \section1 QMAKE_EXT_CPP
+
+ This variable changes the interpretation of all suffixes in this
+ list of values as files of type C++ source code.
+
+ See also \l{Configuring qmake's Environment#Extensions}{File Extensions}.
+
+ \section1 QMAKE_EXT_H
+
+ This variable changes the interpretation of all suffixes in this
+ list of values as files of type C header files.
+
+ See also \l{Configuring qmake's Environment#Extensions}{File Extensions}.
+
+ \section1 QMAKE_EXTRA_COMPILERS
+
+ This variable contains the extra compilers/preprocessors that have been added
+
+ See also \l{Configuring qmake's Environment#Customizing}{Customizing Makefile Output}
+
+ \section1 QMAKE_EXTRA_TARGETS
+
+ This variable contains the extra targets that have been added
+
+ See also \l{Configuring qmake's Environment#Customizing}{Customizing Makefile Output}
+
+ \target QMAKE_FAILED_REQUIREMENTS
+ \section1 QMAKE_FAILED_REQUIREMENTS
+
+ This variable contains the list of requirements that were failed to be met when
+ \c qmake was used. For example, the sql module is needed and wasn't compiled into Qt. The
+ value of this variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf}
+ and rarely needs to be modified.
+
+ \target QMAKE_FILETAGS
+ \section1 QMAKE_FILETAGS
+
+ This variable contains the file tags needed to be entered into the Makefile, such as SOURCES
+ and HEADERS. The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_FRAMEWORK_BUNDLE_NAME
+
+ In a framework project, this variable contains the name to be used for the
+ framework that is built.
+
+ By default, this variable contains the same value as the \l{#TARGET}{TARGET}
+ variable.
+
+ See \l{qmake Platform Notes#Creating Frameworks}{qmake Platform Notes} for
+ more information about creating frameworks and library bundles.
+
+ \e{This is used on Mac OS X only.}
+
+ \target QMAKE_FRAMEWORK_VERSION
+ \section1 QMAKE_FRAMEWORK_VERSION
+
+ For projects where the build target is a Mac OS X framework, this variable
+ is used to specify the version number that will be applied to the framework
+ that is built.
+
+ By default, this variable contains the same value as the \l{#VERSION}{VERSION}
+ variable.
+
+ See \l{qmake Platform Notes#Creating Frameworks}{qmake Platform Notes} for
+ more information about creating frameworks.
+
+ \e{This is used on Mac OS X only.}
+
+ \target QMAKE_INCDIR
+ \section1 QMAKE_INCDIR
+
+ This variable contains the location of all known header files to be added to
+ INCLUDEPATH when building an application. The value of this variable is
+ typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
+ needs to be modified.
+
+ \target QMAKE_INCDIR_EGL
+ \section1 QMAKE_INCDIR_EGL
+
+ This variable contains the location of EGL header files to be added
+ to INCLUDEPATH when building an application with OpenGL/ES or
+ OpenVG support. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target QMAKE_INCDIR_OPENGL
+ \section1 QMAKE_INCDIR_OPENGL
+
+ This variable contains the location of OpenGL header files to be added
+ to INCLUDEPATH when building an application with OpenGL support. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ If the OpenGL implementation uses EGL (most OpenGL/ES systems),
+ then QMAKE_INCDIR_EGL may also need to be set.
+
+ \target QMAKE_INCDIR_OPENVG
+ \section1 QMAKE_INCDIR_OPENVG
+
+ This variable contains the location of OpenVG header files to be added
+ to INCLUDEPATH when building an application with OpenVG support. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ If the OpenVG implementation uses EGL then QMAKE_INCDIR_EGL may also
+ need to be set.
+
+ \target QMAKE_INCDIR_QT
+ \section1 QMAKE_INCDIR_QT
+
+ This variable contains the location of all known header file
+ paths to be added to INCLUDEPATH when building a Qt application. The value
+ of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target QMAKE_INCDIR_THREAD
+ \section1 QMAKE_INCDIR_THREAD
+
+ This variable contains the location of all known header file
+ paths to be added to INCLUDEPATH when building a multi-threaded application.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target QMAKE_INCDIR_X11
+ \section1 QMAKE_INCDIR_X11
+
+ \e {This is used on Unix platforms only.}
+
+ This variable contains the location of X11 header file paths to be
+ added to INCLUDEPATH when building a X11 application. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target QMAKE_INFO_PLIST
+ \section1 QMAKE_INFO_PLIST
+
+ \e {This is used on Mac OS X platforms only.}
+
+ This variable contains the name of the property list file, \c{.plist}, you
+ would like to include in your Mac OS X application bundle.
+
+ In the \c{.plist} file, you can define some variables, e.g., @EXECUTABLE@,
+ which qmake will replace with the actual executable name. Other variables
+ include @ICON@, @TYPEINFO@, @LIBRARY@, and @SHORT_VERSION@.
+
+ \note Most of the time, the default \c{Info.plist} is good enough.
+
+ \section1 QMAKE_LFLAGS
+
+ This variable contains a general set of flags that are passed to
+ the linker. If you need to change the flags used for a particular
+ platform or type of project, use one of the specialized variables
+ for that purpose instead of this variable.
+
+ \target QMAKE_LFLAGS_CONSOLE
+ \section1 QMAKE_LFLAGS_CONSOLE
+
+ \e {This is used on Windows only.}
+
+ This variable contains link flags when building console
+ programs. The value of this variable is typically handled by
+ \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LFLAGS_CONSOLE_DLL
+
+ \e {This is used on Windows only.}
+
+ This variable contains link flags when building console
+ dlls. The value of this variable is typically handled by
+ \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LFLAGS_DEBUG
+
+ This variable contains link flags when building debuggable applications. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LFLAGS_PLUGIN
+
+ This variable contains link flags when building plugins. The value
+ of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LFLAGS_QT_DLL
+
+ This variable contains link flags when building programs that
+ use the Qt library built as a dll. The value of this variable is
+ typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LFLAGS_RELEASE
+
+ This variable contains link flags when building applications for
+ release. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LFLAGS_SHAPP
+
+ This variable contains link flags when building applications which are using
+ the \c app template. The value of this variable is typically handled by
+ \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LFLAGS_SHLIB
+
+ This variable contains link flags when building shared libraries
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LFLAGS_SONAME
+
+ This variable specifies the link flags to set the name of shared objects,
+ such as .so or .dll. The value of this variable is typically handled by \c
+ qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LFLAGS_THREAD
+
+ This variable contains link flags when building multi-threaded projects.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LFLAGS_WINDOWS
+
+ \e {This is used on Windows only.}
+
+ This variable contains link flags when building Windows GUI projects
+ (i.e. non-console applications).
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LFLAGS_WINDOWS_DLL
+
+ \e {This is used on Windows only.}
+
+ This variable contains link flags when building Windows DLL projects.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBDIR
+
+ This variable contains the location of all known library
+ directories.The value of this variable is typically handled by
+ \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBDIR_FLAGS
+
+ \e {This is used on Unix platforms only.}
+
+ This variable contains the location of all library
+ directory with -L prefixed. The value of this variable is typically handled by
+ \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBDIR_EGL
+
+ This variable contains the location of the EGL library
+ directory, when EGL is used with OpenGL/ES or OpenVG. The value
+ of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBDIR_OPENGL
+
+ This variable contains the location of the OpenGL library
+ directory.The value of this variable is typically handled by
+ \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ If the OpenGL implementation uses EGL (most OpenGL/ES systems),
+ then QMAKE_LIBDIR_EGL may also need to be set.
+
+ \section1 QMAKE_LIBDIR_OPENVG
+
+ This variable contains the location of the OpenVG library
+ directory. The value of this variable is typically handled by
+ \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ If the OpenVG implementation uses EGL, then QMAKE_LIBDIR_EGL
+ may also need to be set.
+
+ \section1 QMAKE_LIBDIR_QT
+
+ This variable contains the location of the Qt library
+ directory.The value of this variable is typically handled by
+ \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBDIR_X11
+
+ \e {This is used on Unix platforms only.}
+
+ This variable contains the location of the X11 library
+ directory.The value of this variable is typically handled by
+ \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBS
+
+ This variable contains all project libraries. The value of this
+ variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBS_CONSOLE
+
+ \e {This Windows-specific variable is no longer used.}
+
+ Prior to Qt 4.2, this variable was used to list the libraries
+ that should be linked against when building a console application
+ project on Windows. \l{#QMAKE_LIBS_WINDOW}{QMAKE_LIBS_WINDOW}
+ should now be used instead.
+
+ \section1 QMAKE_LIBS_EGL
+
+ This variable contains all EGL libraries when building Qt with
+ OpenGL/ES or OpenVG. The value of this variable is typically
+ handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely
+ needs to be modified. The usual value is \c{-lEGL}.
+
+ \section1 QMAKE_LIBS_OPENGL
+
+ This variable contains all OpenGL libraries. The value of this
+ variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ If the OpenGL implementation uses EGL (most OpenGL/ES systems),
+ then QMAKE_LIBS_EGL may also need to be set.
+
+ \section1 QMAKE_LIBS_OPENGL_QT
+
+ This variable contains all OpenGL Qt libraries.The value of this
+ variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBS_OPENVG
+
+ This variable contains all OpenVG libraries. The value of this
+ variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf}
+ and rarely needs to be modified. The usual value is \c{-lOpenVG}.
+
+ Some OpenVG engines are implemented on top of OpenGL. This will
+ be detected at configure time and QMAKE_LIBS_OPENGL will be implicitly
+ added to QMAKE_LIBS_OPENVG wherever the OpenVG libraries are linked.
+
+ If the OpenVG implementation uses EGL, then QMAKE_LIBS_EGL may also
+ need to be set.
+
+ \section1 QMAKE_LIBS_QT
+
+ This variable contains all Qt libraries.The value of this
+ variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBS_QT_DLL
+
+ \e {This is used on Windows only.}
+
+ This variable contains all Qt libraries when Qt is built as a dll. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBS_QT_OPENGL
+
+ This variable contains all the libraries needed to link against if
+ OpenGL support is turned on. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBS_QT_THREAD
+
+ This variable contains all the libraries needed to link against if
+ thread support is turned on. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBS_RT
+
+ \e {This is used with Borland compilers only.}
+
+ This variable contains the runtime library needed to link against when
+ building an application. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBS_RTMT
+
+ \e {This is used with Borland compilers only.}
+
+ This variable contains the runtime library needed to link against when
+ building a multi-threaded application. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBS_THREAD
+
+ \e {This is used on Unix platforms only.}
+
+ This variable contains all libraries that need to be linked against
+ when building a multi-threaded application. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBS_WINDOWS
+
+ \e {This is used on Windows only.}
+
+ This variable contains all windows libraries.The value of this
+ variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBS_X11
+
+ \e {This is used on Unix platforms only.}
+
+ This variable contains all X11 libraries.The value of this
+ variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIBS_X11SM
+
+ \e {This is used on Unix platforms only.}
+
+ This variable contains all X11 session management libraries. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LIB_FLAG
+
+ This variable is not empty if the \c lib template is specified. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_LINK_SHLIB_CMD
+
+ This variable contains the command to execute when creating a
+ shared library. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_POST_LINK
+
+ This variable contains the command to execute after linking the TARGET
+ together. This variable is normally empty and therefore nothing is
+ executed, additionally some backends will not support this - mostly only
+ Makefile backends.
+
+ \section1 QMAKE_PRE_LINK
+
+ This variable contains the command to execute before linking the TARGET
+ together. This variable is normally empty and therefore nothing is
+ executed, additionally some backends will not support this - mostly only
+ Makefile backends.
+
+ \section1 QMAKE_LN_SHLIB
+
+ This variable contains the command to execute when creating a link
+ to a shared library. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_MAC_SDK
+
+ This variable is used on Mac OS X when building universal binaries.
+ This process is described in more detail in the
+ \l{Deploying an Application on Mac OS X#Architecture Dependencies}{Deploying
+ an Application on Mac OS X} document.
+
+ \section1 QMAKE_MACOSX_DEPLOYMENT_TARGET
+ This variable only has an effect when building on Mac OS X. On that
+ platform, the variable will be forwarded to the MACOSX_DEPLOYMENT_TARGET
+ environment variable, which is interpreted by the compiler or linker.
+ For more information, see the
+ \l{Deploying an Application on Mac OS X#Mac OS X Version Dependencies}{Deploying
+ an Application on Mac OS X} document.
+
+ \section1 QMAKE_MAKEFILE
+
+ This variable contains the name of the Makefile to create. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_MOC_SRC
+
+ This variable contains the names of all moc source files to
+ generate and include in the project. The value of this variable is
+ typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_QMAKE
+
+ This variable contains the location of qmake if it is not in the path.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_QT_DLL
+
+ This variable is not empty if Qt was built as a dll. The
+ value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_RESOURCE_FLAGS
+
+ This variable is used to customize the list of options passed to the
+ \l{rcc}{Resource Compiler} in each of the build rules where it is used.
+ For example, the following line ensures that the \c{-threshold} and
+ \c{-compress} options are used with particular values each time that
+ \c rcc is invoked:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 45
+
+ \section1 QMAKE_RUN_CC
+
+ This variable specifies the individual rule needed to build an object.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_RUN_CC_IMP
+
+ This variable specifies the individual rule needed to build an object.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_RUN_CXX
+
+ This variable specifies the individual rule needed to build an object.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_RUN_CXX_IMP
+
+ This variable specifies the individual rule needed to build an object.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_TARGET
+
+ This variable contains the name of the project target. The value of
+ this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 QMAKE_UIC
+
+ This variable contains the location of uic if it is not in the path.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ It can be used to specify arguments to uic as well, such as additional plugin
+ paths. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 46
+
+ \section1 QT
+
+ The values stored in the \c QT variable control which of the Qt modules are
+ used by your project.
+
+ The table below shows the options that can be used with the \c QT variable
+ and the features that are associated with each of them:
+
+ \table
+ \header \o Option \o Features
+ \row \o core (included by default) \o QtCore module
+ \row \o gui (included by default) \o QtGui module
+ \row \o network \o QtNetwork module
+ \row \o opengl \o QtOpenGL module
+ \row \o phonon \o Phonon Multimedia Framework
+ \row \o sql \o QtSql module
+ \row \o svg \o QtSvg module
+ \row \o xml \o QtXml module
+ \row \o webkit \o WebKit integration
+ \row \o qt3support \o Qt3Support module
+ \endtable
+
+ By default, \c QT contains both \c core and \c gui, ensuring that standard
+ GUI applications can be built without further configuration.
+
+ If you want to build a project \e without the QtGui module, you need to
+ exclude the \c gui value with the "-=" operator; the following line will
+ result in a minimal Qt project being built:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 47
+
+ Note that adding the \c opengl option to the \c QT variable automatically
+ causes the equivalent option to be added to the \c CONFIG variable.
+ Therefore, for Qt applications, it is not necessary to add the \c opengl
+ option to both \c CONFIG and \c{QT}.
+
+ \section1 QTPLUGIN
+
+ This variable contains a list of names of static plugins that are to be
+ compiled with an application so that they are available as built-in
+ resources.
+
+ \target QT_VERSION
+ \section1 QT_VERSION
+
+ This variable contains the current version of Qt.
+
+ \target QT_MAJOR_VERSION
+ \section1 QT_MAJOR_VERSION
+
+ This variable contains the current major version of Qt.
+
+ \target QT_MINOR_VERSION
+ \section1 QT_MINOR_VERSION
+
+ This variable contains the current minor version of Qt.
+
+ \target QT_PATCH_VERSION
+ \section1 QT_PATCH_VERSION
+
+ This variable contains the current patch version of Qt.
+
+ \section1 RC_FILE
+
+ This variable contains the name of the resource file for the application.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target RCC_DIR
+ \section1 RCC_DIR
+
+ This variable specifies the directory where all intermediate
+ resource files should be placed.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 48
+
+ \target REQUIRES
+ \section1 REQUIRES
+
+ This is a special variable processed by \c qmake. If the
+ contents of this variable do not appear in CONFIG by the time this
+ variable is assigned, then a minimal Makefile will be generated that
+ states what dependencies (the values assigned to REQUIRES) are
+ missing.
+
+ This is mainly used in Qt's build system for building the examples.
+
+ \section1 RESOURCES
+
+ This variable contains the name of the resource collection file (qrc)
+ for the application. Further information about the resource collection
+ file can be found at \l{The Qt Resource System}.
+
+ \section1 RES_FILE
+
+ This variable contains the name of the resource file for the application.
+ The value of this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target SIGNATURE_FILE
+ \section1 SIGNATURE_FILE
+
+ \e {This is only used on Windows CE.}
+
+ Specifies which signature file should be used to sign the project target.
+
+ \note This variable will overwrite the setting you have specified in configure,
+ with the \c -signature option.
+
+ \target SOURCES
+ \section1 SOURCES
+
+ This variable contains the name of all source files in the project.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 49
+
+ See also \l{#HEADERS}{HEADERS}
+
+ \section1 SRCMOC
+
+ This variable is set by \c qmake if files can be found that
+ contain the Q_OBJECT macro. \c SRCMOC contains the
+ name of all the generated moc files. The value of this variable
+ is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be
+ modified.
+
+ \target SUBDIRS
+ \section1 SUBDIRS
+
+ This variable, when used with the \l{#TEMPLATE}{\c subdirs template}
+ contains the names of all subdirectories that contain parts of the project
+ that need be built. Each subdirectory must contain its own project file.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 50
+
+ It is essential that the project file in each subdirectory has the same
+ name as the subdirectory itself, so that \c qmake can find it.
+ For example, if the subdirectory is called \c myapp then the project file
+ in that directory should be called \c myapp.pro.
+
+ If you need to ensure that the subdirectories are built in the order in
+ which they are specified, update the \l{#CONFIG}{CONFIG} variable to
+ include the \c ordered option:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 51
+
+ \target TARGET
+ \section1 TARGET
+
+ This specifies the name of the target file.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 52
+
+ The project file above would produce an executable named \c myapp on
+ unix and 'myapp.exe' on windows.
+
+ \section1 TARGET_EXT
+
+ This variable specifies the target's extension. The value of this variable
+ is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be
+ modified.
+
+ \section1 TARGET_x
+
+ This variable specifies the target's extension with a major version number. The value of this variable
+ is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be
+ modified.
+
+ \section1 TARGET_x.y.z
+
+ This variable specifies the target's extension with version number. The value of this variable
+ is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be
+ modified.
+
+ \target TEMPLATE
+ \section1 TEMPLATE
+
+ This variable contains the name of the template to use when
+ generating the project. The allowed values are:
+
+ \table
+ \header \o Option \o Description
+ \row \o app \o Creates a Makefile for building applications (the default). (See
+ \l{qmake Common Projects#Application}{qmake Common Projects} for more information.)
+ \row \o lib \o Creates a Makefile for building libraries. (See
+ \l{qmake Common Projects#Library}{qmake Common Projects} for more information.)
+ \row \o subdirs \o Creates a Makefile for building targets in subdirectories.
+ The subdirectories are specified using the \l{#SUBDIRS}{SUBDIRS}
+ variable.
+ \row \o vcapp \o \e {Windows only} Creates an application project for Visual Studio.
+ (See \l{qmake Platform Notes#Creating Visual Studio Project Files}{qmake Platform Notes}
+ for more information.)
+ \row \o vclib \o \e {Windows only} Creates a library project for Visual Studio.
+ (See \l{qmake Platform Notes#Creating Visual Studio Project Files}{qmake Platform Notes}
+ for more information.)
+ \endtable
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 53
+
+ The template can be overridden by specifying a new template type with the
+ \c -t command line option. This overrides the template type \e after the .pro
+ file has been processed. With .pro files that use the template type to
+ determine how the project is built, it is necessary to declare TEMPLATE on
+ the command line rather than use the \c -t option.
+
+ \section1 TRANSLATIONS
+
+ This variable contains a list of translation (.ts) files that contain
+ translations of the user interface text into non-native languages.
+
+ See the \l{Qt Linguist Manual} for more information about
+ internationalization (i18n) and localization (l10n) with Qt.
+
+ \section1 UICIMPLS
+
+ This variable contains a list of the generated implementation files by UIC.
+ The value of this variable
+ is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be
+ modified.
+
+ \section1 UICOBJECTS
+
+ This variable is generated from the UICIMPLS variable. The extension of each
+ file will have been replaced by .o (Unix) or .obj (Win32). The value of this variable is
+ typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and
+ rarely needs to be modified.
+
+ \target UI_DIR
+ \section1 UI_DIR
+
+ This variable specifies the directory where all intermediate files from uic
+ should be placed. This variable overrides both UI_SOURCES_DIR and
+ UI_HEADERS_DIR.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 54
+
+ \target UI_HEADERS_DIR
+ \section1 UI_HEADERS_DIR
+
+ This variable specifies the directory where all declaration files (as
+ generated by uic) should be placed.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 55
+
+ \target UI_SOURCES_DIR
+ \section1 UI_SOURCES_DIR
+
+ This variable specifies the directory where all implementation files (as generated
+ by uic) should be placed.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 56
+
+ \target VERSION
+ \section1 VERSION
+
+ This variable contains the version number of the application or library if
+ either the \c app \l{#TEMPLATE}{TEMPLATE} or the \c lib \l{#TEMPLATE}{TEMPLATE}
+ is specified.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 57
+
+ \section1 VER_MAJ
+
+ This variable contains the major version number of the library, if the
+ \c lib \l{#TEMPLATE}{template} is specified.
+
+ \section1 VER_MIN
+
+ This variable contains the minor version number of the library, if the
+ \c lib \l{#TEMPLATE}{template} is specified.
+
+ \section1 VER_PAT
+
+ This variable contains the patch version number of the library, if the
+ \c lib \l{#TEMPLATE}{template} is specified.
+
+ \section1 VPATH
+
+ This variable tells \c qmake where to search for files it cannot
+ open. With this you may tell \c qmake where it may look for things
+ like SOURCES, and if it finds an entry in SOURCES that cannot be
+ opened it will look through the entire VPATH list to see if it can
+ find the file on its own.
+
+ See also \l{#DEPENDPATH}{DEPENDPATH}.
+
+ \section1 YACCIMPLS
+
+ This variable contains a list of yacc source files. The value of
+ this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \section1 YACCOBJECTS
+
+ This variable contains a list of yacc object files. The value of
+ this variable is typically handled by \c qmake or
+ \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified.
+
+ \target YACCSOURCES
+ \section1 YACCSOURCES
+
+ This variable contains a list of yacc source files to be included
+ in the project. All dependencies, headers and source files will
+ automatically be included in the project.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 58
+
+ \section1 _PRO_FILE_
+
+ This variable contains the path to the project file in use.
+
+ For example, the following line causes the location of the project
+ file to be written to the console:
+
+ \snippet doc/src/snippets/qmake/project_location.pro project file
+
+ \section1 _PRO_FILE_PWD_
+
+ This variable contains the path to the directory containing the project
+ file in use.
+
+ For example, the following line causes the location of the directory
+ containing the project file to be written to the console:
+
+ \snippet doc/src/snippets/qmake/project_location.pro project file directory
+*/
+
+/*!
+ \page qmake-function-reference.html
+ \title qmake Function Reference
+ \contentspage {qmake Manual}{Contents}
+ \previouspage qmake Variable Reference
+ \nextpage Configuring qmake's Environment
+
+ \c qmake provides built-in functions to allow the contents of
+ variables to be processed, and to enable tests to be performed
+ during the configuration process. Functions that process the
+ contents of variables typically return values that can be assigned
+ to other variables, and these values are obtained by prefixing
+ function with the \c $$ operator. Functions that perform tests
+ are usually used as the conditional parts of scopes; these are
+ indicated in the function descriptions below.
+
+ \tableofcontents{2}
+
+ \section1 basename(variablename)
+
+ Returns the basename of the file specified. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 59
+
+ \section1 CONFIG(config)
+ [Conditional]
+
+ This function can be used to test for variables placed into the
+ \c CONFIG variable. This is the same as regular old style (tmake) scopes,
+ but has the added advantage a second parameter can be passed to test for
+ the active config. As the order of values is important in \c CONFIG
+ variables (i.e. the last one set will be considered the active config for
+ mutually exclusive values) a second parameter can be used to specify a set
+ of values to consider. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 60
+
+ Because release is considered the active setting (for feature parsing)
+ it will be the CONFIG used to generate the build file. In the common
+ case a second parameter is not needed, but for specific mutual
+ exclusive tests it is invaluable.
+
+ \section1 contains(variablename, value)
+ [Conditional]
+
+ Succeeds if the variable \e variablename contains the value \e value;
+ otherwise fails. You can check the return value of this function using
+ a scope.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 61
+
+ The contents of the scope are only processed if the \c drivers
+ variable contains the value, \c network. If this is the case, the
+ appropriate files are added to the \c SOURCES and \c HEADERS
+ variables.
+
+ \section1 count(variablename, number)
+ [Conditional]
+
+ Succeeds if the variable \e variablename contains a list with the
+ specified \e number of value; otherwise fails.
+
+ This function is used to ensure that declarations inside a scope are
+ only processed if the variable contains the correct number of values;
+ for example:
+
+ \snippet doc/src/snippets/qmake/functions.pro 2
+
+ \section1 dirname(file)
+
+ Returns the directory name part of the specified file. For example:
+
+ \snippet doc/src/snippets/qmake/dirname.pro 0
+
+ \section1 error(string)
+
+ This function never returns a value. \c qmake displays the given
+ \e string to the user, and exits. This function should only be used
+ for unrecoverable errors.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 62
+
+ \section1 eval(string)
+ [Conditional]
+
+ Evaluates the contents of the string using \c qmake's syntax rules
+ and returns true.
+ Definitions and assignments can be used in the string to modify the
+ values of existing variables or create new definitions.
+
+ For example:
+ \snippet doc/src/snippets/qmake/functions.pro 4
+
+ Note that quotation marks can be used to delimit the string, and that
+ the return value can be discarded if it is not needed.
+
+ \section1 exists(filename)
+ [Conditional]
+
+ Tests whether a file with the given \e filename exists.
+ If the file exists, the function succeeds; otherwise it fails.
+ If a regular expression is specified for the filename, this function
+ succeeds if any file matches the regular expression specified.
+
+ For example:
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 63
+
+ Note that "/" can be used as a directory separator, regardless of the
+ platform in use.
+
+ \section1 find(variablename, substr)
+
+ Places all the values in \e variablename that match \e substr. \e
+ substr may be a regular expression, and will be matched accordingly.
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 64
+
+ MY_VAR2 will contain '-Lone -Ltwo -Lthree -Lfour -Lfive', and MY_VAR3 will
+ contains 'three two three'.
+
+ \section1 for(iterate, list)
+
+ This special test function will cause a loop to be started that
+ iterates over all values in \e list, setting \e iterate to each
+ value in turn. As a convenience, if \e list is 1..10 then iterate will
+ iterate over the values 1 through 10.
+
+ The use of an else scope afer a condition line with a for() loop is
+ disallowed.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 65
+
+ \section1 include(filename)
+ [Conditional]
+
+ Includes the contents of the file specified by \e filename into the
+ current project at the point where it is included. This function
+ succeeds if \e filename is included; otherwise it fails. The included
+ file is processed immediately.
+
+ You can check whether the file was included by using this function as
+ the condition for a scope; for example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 66
+
+ \section1 infile(filename, var, val)
+ [Conditional]
+
+ Succeeds if the file \e filename (when parsed by \c qmake itself)
+ contains the variable \e var with a value of \e val; otherwise fails.
+ If you do not specify a third argument (\e val), the function will
+ only test whether \e var has been declared in the file.
+
+ \section1 isEmpty(variablename)
+ [Conditional]
+
+ Succeeds if the variable \e variablename is empty; otherwise fails.
+ This is the equivalent of \c{count( variablename, 0 )}.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 67
+
+ \section1 join(variablename, glue, before, after)
+
+ Joins the value of \e variablename with \c glue. If this value is
+ non-empty it prefixes the value with \e before and suffix it with \e
+ after. \e variablename is the only required field, the others default
+ to empty strings. If you need to encode spaces in \e glue, \e before, or \e
+ after you must quote them.
+
+ \section1 member(variablename, position)
+
+ Returns the value at the given \e position in the list of items in
+ \e variablename.
+ If an item cannot be found at the position specified, an empty string is
+ returned. \e variablename is the only required field. If not specified,
+ \c position defaults to 0, causing the first value in the list to be
+ returned.
+
+ \section1 message(string)
+
+ This function simply writes a message to the console. Unlike the
+ \c error() function, this function allows processing to continue.
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 68
+
+ The above line causes "This is a message" to be written to the console.
+ The use of quotation marks is optional.
+
+ \note By default, messages are written out for each Makefile generated by
+ qmake for a given project. If you want to ensure that messages only appear
+ once for each project, test the \c build_pass variable
+ \l{qmake Advanced Usage}{in conjunction with a scope} to filter out
+ messages during builds; for example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 69
+
+ \section1 prompt(question)
+
+ Displays the specified \e question, and returns a value read from stdin.
+
+ \section1 quote(string)
+
+ Converts a whole \e string into a single entity and returns the result.
+ Newlines, carriage returns, and tabs can be specified in the string
+ with \\n \\r and \\t. The return value does not contain either single
+ or double quotation marks unless you explicitly include them yourself,
+ but will be placed into a single entry (for literal expansion).
+
+ \section1 replace(string, old_string, new_string)
+
+ Replaces each instance of \c old_string with \c new_string in the
+ contents of the variable supplied as \c string. For example, the
+ code
+
+ \snippet doc/src/snippets/qmake/replace.pro 0
+
+ prints the message:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 70
+
+ \section1 sprintf(string, arguments...)
+
+ Replaces %1-%9 with the arguments passed in the comma-separated list
+ of function \e arguments and returns the processed string.
+
+ \section1 system(command)
+ [Conditional]
+
+ Executes the given \c command in a secondary shell, and succeeds
+ if the command returns with a zero exit status; otherwise fails.
+ You can check the return value of this function using a scope:
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 71
+
+ Alternatively, you can use this function to obtain stdout and stderr
+ from the command, and assign it to a variable. For example, you can
+ use this to interrogate information about the platform:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 72
+
+ \target unique
+ \section1 unique(variablename)
+
+ This will return a list of values in variable that are unique (that is
+ with repetitive entries removed). For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 73
+
+ \section1 warning(string)
+
+ This function will always succeed, and will display the given
+ \e string to the user. message() is a synonym for warning().
+*/
+
+/*!
+ \page qmake-environment-reference.html
+ \contentspage {qmake Manual}{Contents}
+ \previouspage qmake Function Reference
+
+ \title Configuring qmake's Environment
+
+ \tableofcontents
+
+ \target Properties
+ \section1 Properties
+
+ \c qmake has a system of persistant information, this allows you to
+ \c set a variable in qmake once, and each time qmake is invoked this
+ value can be queried. Use the following to set a property in qmake:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 74
+
+ The appropriate variable and value should be substituted for
+ \c VARIABLE and \c VALUE.
+
+ To retrieve this information back from qmake you can do:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 75
+
+ \note \c{qmake -query} will only list variables that you have
+ previously set with \c{qmake -set VARIABLE VALUE}.
+
+ This information will be saved into a QSettings object (meaning it
+ will be stored in different places for different platforms). As
+ \c VARIABLE is versioned as well, you can set one value in an older
+ version of \c qmake, and newer versions will retrieve this value. However,
+ if you set \c VARIABLE for a newer version of \c qmake, the older version
+ will not use this value. You can however query a specific version of a
+ variable if you prefix that version of \c qmake to \c VARIABLE, as in
+ the following example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 76
+
+ \c qmake also has the notion of \c builtin properties, for example you can
+ query the installation of Qt for this version of \c qmake with the
+ \c QT_INSTALL_PREFIX property:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 77
+
+ These built-in properties cannot have a version prefixed to them as
+ they are not versioned, and each version of \c qmake will have its own
+ built-in set of these values. The list below outlines the built-in
+ properties:
+
+ \list
+ \o \c QT_INSTALL_PREFIX - Where the version of Qt this qmake is built for resides
+ \o \c QT_INSTALL_DATA - Where data for this version of Qt resides
+ \o \c QMAKE_VERSION - The current version of qmake
+ \endlist
+
+ Finally, these values can be queried in a project file with a special
+ notation such as:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 78
+
+ \target QMAKESPEC
+ \section1 QMAKESPEC
+
+ \c qmake requires a platform and compiler description file which
+ contains many default values used to generate appropriate Makefiles.
+ The standard Qt distribution comes with many of these files, located
+ in the \c mkspecs subdirectory of the Qt installation.
+
+ The \c QMAKESPEC environment variable can contain any of the following:
+
+ \list
+ \o A complete path to a directory containing a \c{qmake.conf} file.
+ In this case \c qmake will open the \c{qmake.conf} file from within that
+ directory. If the file does not exist, \c qmake will exit with an
+ error.
+ \o The name of a platform-compiler combination. In this case, \c qmake
+ will search in the directory specified by the \c mkspecs subdirectory
+ of the data path specified when Qt was compiled (see
+ QLibraryInfo::DataPath).
+ \endlist
+
+ \bold{Note:} The \c QMAKESPEC path will automatically be added to the
+ \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} system variable.
+
+ \target INSTALLS
+ \section1 INSTALLS
+
+ It is common on Unix to also use the build tool to install applications
+ and libraries; for example, by invoking \c{make install}. For this reason,
+ \c qmake has the concept of an install set, an object which contains
+ instructions about the way part of a project is to be installed.
+ For example, a collection of documentation files can be described in the
+ following way:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 79
+
+ The \c path member informs \c qmake that the files should be installed in
+ \c /usr/local/program/doc (the path member), and the \c files member
+ specifies the files that should be copied to the installation directory.
+ In this case, everything in the \c docs directory will be coped to
+ \c /usr/local/program/doc.
+
+ Once an install set has been fully described, you can append it to the
+ install list with a line like this:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 80
+
+ \c qmake will ensure that the specified files are copied to the installation
+ directory. If you require greater control over this process, you can also
+ provide a definition for the \c extra member of the object. For example,
+ the following line tells \c qmake to execute a series of commands for this
+ install set:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 81
+
+ The \c unix scope
+ (see \l{qmake Advanced Usage#Scopes and Conditions}{Scopes and Conditions})
+ ensures that these particular commands are only executed on Unix platforms.
+ Appropriate commands for other platforms can be defined using other scope
+ rules.
+
+ Commands specified in the \c extra member are executed before the instructions
+ in the other members of the object are performed.
+
+ If you append a built-in install set to the \c INSTALLS variable and do
+ not specify \c files or \c extra members, \c qmake will decide what needs to
+ be copied for you. Currently, the only supported built-in install set is
+ \c target:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 82
+
+ In the above lines, \c qmake knows what needs to be copied, and will handle
+ the installation process automatically.
+
+ \target cache
+ \section1 Cache File
+
+ The cache file is a special file \c qmake reads to find settings not specified
+ in the \c qmake.conf file, project files, or at the command line. If
+ \c -nocache is not specified when \c qmake is run, it will try to find a file
+ called \c{.qmake.cache} in parent directories of the current directory. If
+ it fails to find this file, it will silently ignore this step of processing.
+
+ If it finds a \c{.qmake.cache} file then it will process this file first before
+ it processes the project file.
+
+ \target LibDepend
+ \section1 Library Dependencies
+
+ Often when linking against a library, \c qmake relies on the underlying
+ platform to know what other libraries this library links against, and
+ lets the platform pull them in. In many cases, however, this is not
+ sufficent. For example, when statically linking a library, no other
+ libraries are linked to, and therefore no dependencies to those
+ libraries are created. However, an application that later links
+ against this library will need to know where to find the symbols that
+ the static library will require. To help with this situation, \c qmake
+ attempts to follow a library's dependencies where appropriate, but
+ this behavior must be explicitly enabled by following two steps.
+
+ The first step is to enable dependency tracking in the library itself.
+ To do this you must tell \c qmake to save information about the library:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 83
+
+ This is only relevant to the \c lib template, and will be ignored for
+ all others. When this option is enabled, \c qmake will create a file
+ ending in .prl which will save some meta-information about the
+ library. This metafile is just like an ordinary project file, but only
+ contains internal variable declarations. You are free to view this file
+ and, if it is deleted, \c qmake will know to recreate it when necessary,
+ either when the project file is later read, or if a dependent library
+ (described below) has changed. When installing this library, by
+ specifying it as a target in an \c INSTALLS declaration, \c qmake will
+ automatically copy the .prl file to the installation path.
+
+ The second step in this process is to enable reading of this meta
+ information in the applications that use the static library:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 84
+
+ When this is enabled, \c qmake will process all libraries linked to
+ by the application and find their meta-information. \c qmake will use
+ this to determine the relevant linking information, specifically adding
+ values to the application project file's list of \c DEFINES as well as
+ \c LIBS. Once \c qmake has processed this file, it will then look through
+ the newly introduced libraries in the \c LIBS variable, and find their
+ dependent .prl files, continuing until all libraries have been resolved.
+ At this point, the Makefile is created as usual, and the libraries are
+ linked explicitlyy against the application.
+
+ The internals of the .prl file are left closed so they can easily
+ change later. They are not designed to be changed by hand, should only
+ be created by \c qmake, and should not be transferred between operating
+ systems as they may contain platform-dependent information.
+
+ \target Extensions
+ \section1 File Extensions
+
+ Under normal circumstances \c qmake will try to use appropriate file extensions
+ for your platform. However, it is sometimes necessary to override the default
+ choices for each platform and explicitly define file extensions for \c qmake to use.
+ This is achieved by redefining certain built-in variables; for example the extension
+ used for \l moc files can be redefined with the following assignment in a project
+ file:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 85
+
+ The following variables can be used to redefine common file extensions recognized
+ by \c qmake:
+
+ \list
+ \o QMAKE_EXT_MOC - This modifies the extension placed on included moc files.
+ \o QMAKE_EXT_UI - This modifies the extension used for designer UI files (usually
+ in \c FORMS).
+ \o QMAKE_EXT_PRL - This modifies the extension placed on
+ \l{#LibDepend}{library dependency files}.
+ \o QMAKE_EXT_LEX - This changes the suffix used in files (usually in \c LEXSOURCES).
+ \o QMAKE_EXT_YACC - This changes the suffix used in files (usually in \c YACCSOURCES).
+ \o QMAKE_EXT_OBJ - This changes the suffix used on generated object files.
+ \endlist
+
+ All of the above accept just the first value, so you must assign to it just one
+ value that will be used throughout your project file. There are two variables that
+ accept a list of values:
+
+ \list
+ \o QMAKE_EXT_CPP - Causes \c qmake to interpret all files with these suffixes as
+ C++ source files.
+ \o QMAKE_EXT_H - Causes \c qmake to interpret all files with these suffixes as
+ C and C++ header files.
+ \endlist
+
+ \target Customizing
+ \section1 Customizing Makefile Output
+
+ \c qmake tries to do everything expected of a cross-platform build tool.
+ This is often less than ideal when you really need to run special
+ platform-dependent commands. This can be achieved with specific instructions
+ to the different \c qmake backends.
+
+ Customization of the Makefile output is performed through an object-style
+ API as found in other places in \c qmake. Objects are defined automatically
+ by specifying their members; for example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 86
+
+ The definitions above define a \c qmake target called \c mytarget, containing
+ a Makefile target called \c{.buildfile} which in turn is generated with
+ the \c touch command. Finally, the \c{.depends} member specifies that
+ \c mytarget depends on \c mytarget2, another target that is defined afterwards.
+ \c mytarget2 is a dummy target; it is only defined to echo some text to
+ the console.
+
+ The final step is to instruct \c qmake that this object is a target to be built:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 87
+
+ This is all you need to do to actually build custom targets. Of course, you may
+ want to tie one of these targets to the
+ \l{qmake Variable Reference#TARGET}{qmake build target}. To do this, you simply need to
+ include your Makefile target in the list of
+ \l{qmake Variable Reference#PRE_TARGETDEPS}{PRE_TARGETDEPS}.
+
+ The following tables are an overview of the options available to you with the QMAKE_EXTRA_TARGETS
+ variable.
+
+ \table
+ \header
+ \o Member
+ \o Description
+ \row
+ \o commands
+ \o The commands for generating the custom build target.
+ \row
+ \o CONFIG
+ \o Specific configuration options for the custom build target. See the CONFIG table for details.
+ \row
+ \o depends
+ \o The existing build targets that the custom build target depends on.
+ \row
+ \o recurse
+ \o Specifies which sub-targets should used when creating the rules in the Makefile to call in
+ the sub-target specific Makefile. This is only used when \c recursive is set in the CONFIG.
+ \row
+ \o recurse_target
+ \o Specifies the target that should be built via the sub-target Makefile for the rule in the Makefile.
+ This adds something like $(MAKE) -f Makefile.[subtarget] [recurse_target]. This is only used when
+ \c recursive is set in the CONFIG.
+ \row
+ \o target
+ \o The file being created by the custom build target.
+ \endtable
+
+ List of members specific to the CONFIG option:
+
+ \table
+ \header
+ \o Member
+ \o Description
+ \row
+ \o recursive
+ \o Indicates that rules should be created in the Makefile and thus call
+ the relevant target inside the sub-target specific Makefile. This defaults to creating
+ an entry for each of the sub-targets.
+ \endtable
+
+ For convenience, there is also a method of customizing projects
+ for new compilers or preprocessors:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 88
+
+ With the above definitions, you can use a drop-in replacement for moc if one
+ is available. The commands is executed on all arguments given to the
+ \c NEW_HEADERS variable (from the \c input member), and the result is written
+ to the file defined by the \c output member; this file is added to the
+ other source files in the project.
+ Additionally, \c qmake will execute \c depend_command to generate dependency
+ information, and place this information in the project as well.
+
+ These commands can easily be placed into a cache file, allowing subsequent
+ project files to add arguments to \c NEW_HEADERS.
+
+ The following tables are an overview of the options available to you with the QMAKE_EXTRA_COMPILERS
+ variable.
+
+ \table
+ \header
+ \o Member
+ \o Description
+ \row
+ \o commands
+ \o The commands used for for generating the output from the input.
+ \row
+ \o CONFIG
+ \o Specific configuration options for the custom compiler. See the CONFIG table for details.
+ \row
+ \o depend_command
+ \o Specifies a command used to generate the list of dependencies for the output.
+ \row
+ \o dependency_type
+ \o Specifies the type of file the output is, if it is a known type (such as TYPE_C,
+ TYPE_UI, TYPE_QRC) then it is handled as one of those type of files.
+ \row
+ \o depends
+ \o Specifies the dependencies of the output file.
+ \row
+ \o input
+ \o The variable that contains the files that should be processed with the custom compiler.
+ \row
+ \o name
+ \o A description of what the custom compiler is doing. This is only used in some backends.
+ \row
+ \o output
+ \o The filename that is created from the custom compiler.
+ \row
+ \o output_function
+ \o Specifies a custom qmake function that is used to specify the filename to be created.
+ \row
+ \o variable_out
+ \o The variable that the files created from the output should be added to.
+ \endtable
+
+ List of members specific to the CONFIG option:
+
+ \table
+ \header
+ \o Member
+ \o Description
+ \row
+ \o combine
+ \o Indicates that all of the input files are combined into a single output file.
+ \row
+ \o target_predeps
+ \o Indicates that the output should be added to the list of PRE_TARGETDEPS.
+ \row
+ \o explicit_dependencies
+ \o The dependencies for the output only get generated from the depends member and from
+ nowhere else.
+ \row
+ \o no_link
+ \o Indicates that the output should not be added to the list of objects to be linked in
+ \endtable
+*/
+
+/*!
+ \page qmake-advanced-usage.html
+ \title qmake Advanced Usage
+ \contentspage {qmake Manual}{Contents}
+ \previouspage qmake Platform Notes
+ \nextpage Using Precompiled Headers
+
+ Many \c qmake project files simply describe the sources and header files used
+ by the project, using a list of \c{name = value} and \c{name += value}
+ definitions. \c qmake also provides other operators, functions, and scopes
+ that can be used to process the information supplied in variable declarations.
+ These advanced features allow Makefiles to be generated for multiple platforms
+ from a single project file.
+
+ \tableofcontents
+
+ \section1 Operators
+
+ In many project files, the assignment (\c{=}) and append (\c{+=}) operators can
+ be used to include all the information about a project. The typical pattern of
+ use is to assign a list of values to a variable, and append more values
+ depending on the result of various tests. Since \c qmake defines certain
+ variables using default values, it is sometimes necessary to use the removal
+ (\c{-=}) operator to filter out values that are not required. The following
+ operators can be used to manipulate the contents of variables.
+
+ The \c = operator assigns a value to a variable:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 89
+
+ The above line sets the \c TARGET variable to \c myapp. This will overwrite any
+ values previously set for \c TARGET with \c myapp.
+
+ The \c += operator appends a new value to the list of values in a variable:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 90
+
+ The above line appends \c QT_DLL to the list of pre-processor defines to be put
+ in the generated Makefile.
+
+ The \c -= operator removes a value from the list of values in a variable:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 91
+
+ The above line removes \c QT_DLL from the list of pre-processor defines to be
+ put in the generated Makefile.
+
+ The \c *= operator adds a value to the list of values in a variable, but only
+ if it is not already present. This prevents values from being included many
+ times in a variable. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 92
+
+ In the above line, \c QT_DLL will only be added to the list of pre-processor
+ defines if it is not already defined. Note that the
+ \l{qmake Function Reference#unique}{unique()}
+ function can also be used to ensure that a variables only contains one
+ instance of each value.
+
+ The \c ~= operator replaces any values that match a regular expression with
+ the specified value:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 93
+
+ In the above line, any values in the list that start with \c QT_D or \c QT_T are
+ replaced with \c QT.
+
+ The \c $$ operator is used to extract the contents of a variable, and can be
+ used to pass values between variables or supply them to functions:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 94
+
+ \target Scopes
+ \section1 Scopes
+
+ Scopes are similar to \c if statements in procedural programming languages.
+ If a certain condition is true, the declarations inside the scope are processed.
+
+ \section2 Syntax
+
+ Scopes consist of a condition followed by an opening brace on the same line,
+ a sequence of commands and definitions, and a closing brace on a new line:
+
+ \snippet doc/src/snippets/qmake/scopes.pro syntax
+
+ The opening brace \e{must be written on the same line as the condition}.
+ Scopes may be concatenated to include more than one condition; see below
+ for examples.
+
+ \section2 Scopes and Conditions
+
+ A scope is written as a condition followed by a series of declarations
+ contained within a pair of braces; for example:
+
+ \snippet doc/src/snippets/qmake/scopes.pro 0
+
+ The above code will add the \c paintwidget_win.cpp file to the sources listed
+ in the generated Makefile if \c qmake is used on a Windows platform.
+ If \c qmake is used on a platform other than Windows, the define will be
+ ignored.
+
+ The conditions used in a given scope can also be negated to provide an
+ alternative set of declarations that will be processed only if the
+ original condition is false. For example, suppose we want to process
+ something on all platforms \e except for Windows. We can achieve this by
+ negating the scope like this:
+
+ \snippet doc/src/snippets/qmake/scopes.pro 1
+
+ Scopes can be nested to combine more than one condition. For instance, if
+ you want to include a particular file for a certain platform only if
+ debugging is enabled then you write the following:
+
+ \snippet doc/src/snippets/qmake/scopes.pro 2
+
+ To save writing many nested scopes, you can nest scopes using the \c :
+ operator. The nested scopes in the above example can be rewritten in
+ the following way:
+
+ \snippet doc/src/snippets/qmake/scopes.pro 3
+
+ You may also use the \c : operator to perform single line conditional
+ assignments; for example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 95
+
+ The above line adds \c QT_DLL to the \c DEFINES variable only on the
+ Windows platform.
+ Generally, the \c : operator behaves like a logical AND operator, joining
+ together a number of conditions, and requiring all of them to be true.
+
+ There is also the \c | operator to act like a logical OR operator, joining
+ together a number of conditions, and requiring only one of them to be true.
+
+ \snippet doc/src/snippets/qmake/scopes.pro 4
+
+ You can also provide alternative declarations to those within a scope by
+ using an \c else scope. Each \c else scope is processed if the conditions
+ for the preceding scopes are false.
+ This allows you to write complex tests when combined with other scopes
+ (separated by the \c : operator as above). For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 96
+
+ \section2 Configuration and Scopes
+
+ The values stored in the
+ \l{qmake-project-files.html#GeneralConfiguration}{\c CONFIG variable}
+ are treated specially by \c qmake. Each of the possible values can be
+ used as the condition for a scope. For example, the list of values
+ held by \c CONFIG can be extended with the \c opengl value:
+
+ \snippet doc/src/snippets/qmake/configscopes.pro 0
+
+ As a result of this operation, any scopes that test for \c opengl will
+ be processed. We can use this feature to give the final executable an
+ appropriate name:
+
+ \snippet doc/src/snippets/qmake/configscopes.pro 1
+ \snippet doc/src/snippets/qmake/configscopes.pro 2
+ \snippet doc/src/snippets/qmake/configscopes.pro 3
+
+ This feature makes it easy to change the configuration for a project
+ without losing all the custom settings that might be needed for a specific
+ configuration. In the above code, the declarations in the first scope are
+ processed, and the final executable will be called \c application-gl.
+ However, if \c opengl is not specified, the declarations in the second
+ scope are processed instead, and the final executable will be called
+ \c application.
+
+ Since it is possible to put your own values on the \c CONFIG
+ line, this provides you with a convenient way to customize project files
+ and fine-tune the generated Makefiles.
+
+ \section2 Platform Scope Values
+
+ In addition to the \c win32, \c macx, and \c unix values used in many
+ scope conditions, various other built-in platform and compiler-specific
+ values can be tested with scopes. These are based on platform
+ specifications provided in Qt's \c mkspecs directory. For example, the
+ following lines from a project file show the current specification in
+ use and test for the \c linux-g++ specification:
+
+ \snippet doc/src/snippets/qmake/specifications.pro 0
+
+ You can test for any other platform-compiler combination as long as a
+ specification exists for it in the \c mkspecs directory.
+
+ \section1 Variables
+
+ Many of the variables used in project files are special variables that
+ \c qmake uses when generating Makefiles, such as \c DEFINES, \c SOURCES,
+ and \c HEADERS. It is possible for you to create variables for your own
+ use; \c qmake creates new variables with a given name when it encounters
+ an assignment to that name. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 97
+
+ There are no restricitions on what you do to your own variables, as \c
+ qmake will ignore them unless it needs to evaluate them when processing
+ a scope.
+
+ You can also assign the value of a current variable to another
+ variable by prefixing $$ to the variable name. For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 98
+
+ Now the MY_DEFINES variable contains what is in the DEFINES variable at
+ this point in the project file. This is also equivalent to:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 99
+
+ The second notation allows you to append the contents of the variable to
+ another value without separating the two with a space. For example, the
+ following will ensure that the final executable will be given a name
+ that includes the project template being used:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 100
+
+ Variables can be used to store the contents of environment variables.
+ These can be evaluated at the time that \c qmake is run, or included
+ in the generated Makefile for evaluation when the project is built.
+
+ To obtain the contents of an environment value when \c qmake is run,
+ use the \c $$(...) operator:
+
+ \snippet doc/src/snippets/qmake/environment.pro 0
+
+ In the above assignment, the value of the \c PWD environment variable
+ is read when the project file is processed.
+
+ To obtain the contents of an environment value at the time when the
+ generated Makefile is processed, use the \c $(...) operator:
+
+ \snippet doc/src/snippets/qmake/environment.pro 1
+
+ In the above assignment, the value of \c PWD is read immediately
+ when the project file is processed, but \c $(PWD) is assigned to
+ \c DESTDIR in the generated Makefile. This makes the build process
+ more flexible as long as the environment variable is set correctly
+ when the Makefile is processed.
+
+ The special \c $$[...] operator can be used to access various
+ configuration options that were set when Qt was built:
+
+ \snippet doc/src/snippets/qmake/qtconfiguration.pro 0
+
+ The variables accessible with this operator are typically used to
+ enable third party plugins and components to be integrated with Qt.
+ For example, a \QD plugin can be installed alongside \QD's built-in
+ plugins if the following declaration is made in its project file:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 101
+
+ \target VariableProcessingFunctions
+ \section1 Variable Processing Functions
+
+ \c qmake provides a selection of built-in functions to allow the
+ contents of variables to be processed. These functions process the
+ arguments supplied to them and return a value, or list of values, as
+ a result. In order to assign a result to a variable, it is necessary
+ to use the \c $$ operator with this type of function in the same way
+ used to assign contents of one variable to another:
+
+ \snippet doc/src/snippets/qmake/functions.pro 1
+
+ This type of function should be used on the right-hand side of
+ assignments (i.e, as an operand).
+
+ It is possible to define your own functions for processing the
+ contents of variables. These functions can be defined in the following
+ way:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 102
+
+ The following example function takes a variable name as its only
+ argument, extracts a list of values from the variable with the
+ \l{qmake-function-reference.html}{eval()} built-in function,
+ and compiles a list of files:
+
+ \snippet doc/src/snippets/qmake/replacefunction.pro 0
+
+ \target ConditionalFunctions
+ \section1 Conditional Functions
+
+ \c qmake provides built-in functions that can be used as conditions
+ when writing scopes. These functions do not return a value, but
+ instead indicate "success" or "failure":
+
+ \snippet doc/src/snippets/qmake/functions.pro 3
+
+ This type of function should be used in conditional expressions
+ only.
+
+ It is possible to define your own functions to provide conditions
+ for scopes. The following example tests whether each file in a list
+ exists and returns true if they all exist, or false if not:
+
+ \snippet doc/src/snippets/qmake/testfunction.pro 0
+
+ \section1 Adding New Configuration Features
+
+ \c qmake lets you create your own \e features that can be included in
+ project files by adding their names to the list of values specified by
+ the \c CONFIG variable. Features are collections of custom functions and
+ definitions in \c{.prf} files that can reside in one of many standard
+ directories. The locations of these directories are defined in a number
+ of places, and \c qmake checks each of them in the following order when
+ it looks for \c{.prf} files:
+
+ \list 1
+ \o In a directory listed in the \c QMAKEFEATURES environment variable;
+ this contains a colon-separated list of directories.
+ \o In a directory listed in the \c QMAKEFEATURES property variable; this
+ contains a colon-spearated list of directories.
+ \omit
+ \o In a features directory beneath the project's root directory (where
+ the \c{.qmake.cache} file is generated).
+ \endomit
+ \o In a features directory residing within a \c mkspecs directory.
+ \c mkspecs directories can be located beneath any of the directories
+ listed in the \c QMAKEPATH environment variable (a colon-separated list
+ of directories). (\c{$QMAKEPATH/mkspecs/<features>})
+ \o In a features directory residing beneath the directory provided by the
+ \c QMAKESPEC environment variable. (\c{$QMAKESPEC/<features>})
+ \o In a features directory residing in the \c data_install/mkspecs directory.
+ (\c{data_install/mkspecs/<features>})
+ \o In a features directory that exists as a sibling of the directory
+ specified by the \c QMAKESPEC environment variable.
+ (\c{$QMAKESPEC/../<features>})
+ \endlist
+
+ The following features directories are searched for features files:
+
+ \list 1
+ \o \c{features/unix}, \c{features/win32}, or \c{features/macx}, depending on
+ the platform in use
+ \o \c features/
+ \endlist
+
+ For example, consider the following assignment in a project file:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 103
+
+ With this addition to the \c CONFIG variable, \c qmake will search the
+ locations listed above for the \c myfeatures.prf file after it has
+ finished parsing your project file. On Unix systems, it will look for
+ the following file:
+
+ \list 1
+ \o \c $QMAKEFEATURES/myfeatures.prf (for each directory listed in the
+ \c QMAKEFEATURES environment variable)
+ \o \c $$QMAKEFEATURES/myfeatures.prf (for each directory listed in the
+ \c QMAKEFEATURES property variable)
+ \o \c myfeatures.prf (in the project's root directory)
+ \o \c $QMAKEPATH/mkspecs/features/unix/myfeatures.prf and
+ \c $QMAKEPATH/mkspecs/features/myfeatures.prf (for each directory
+ listed in the \c QMAKEPATH environment variable)
+ \o \c $QMAKESPEC/features/unix/myfeatures.prf and
+ \c $QMAKESPEC/features/myfeatures.prf
+ \o \c data_install/mkspecs/features/unix/myfeatures.prf and
+ \c data_install/mkspecs/features/myfeatures.prf
+ \o \c $QMAKESPEC/../features/unix/myfeatures.prf and
+ \c $QMAKESPEC/../features/myfeatures.prf
+ \endlist
+
+ \note The \c{.prf} files must have names in lower case.
+
+
+*/
+
+/*!
+ \page qmake-precompiledheaders.html
+ \title Using Precompiled Headers
+ \contentspage {qmake Manual}{Contents}
+ \previouspage qmake Advanced Usage
+ \nextpage qmake Reference
+
+ \target Introduction
+
+ Precompiled headers are a performance feature supported by some
+ compilers to compile a stable body of code, and store the compiled
+ state of the code in a binary file. During subsequent compilations,
+ the compiler will load the stored state, and continue compiling the
+ specified file. Each subsequent compilation is faster because the
+ stable code does not need to be recompiled.
+
+ \c qmake supports the use of precompiled headers (PCH) on some
+ platforms and build environments, including:
+ \list
+ \o Windows
+ \list
+ \o nmake
+ \o Dsp projects (VC 6.0)
+ \o Vcproj projects (VC 7.0 \& 7.1)
+ \endlist
+ \o Mac OS X
+ \list
+ \o Makefile
+ \o Xcode
+ \endlist
+ \o Unix
+ \list
+ \o GCC 3.4 and above
+ \endlist
+ \endlist
+
+ \target ADD_PCH
+ \section1 Adding Precompiled Headers to Your Project
+
+ \target PCH_CONTENTS
+ \section2 Contents of the Precompiled Header File
+
+ The precompiled header must contain code which is \e stable
+ and \e static throughout your project. A typical PCH might look
+ like this:
+
+ \section3 Example: \c stable.h
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 104
+
+ Note that a precompiled header file needs to separate C includes from
+ C++ includes, since the precompiled header file for C files may not
+ contain C++ code.
+
+ \target PROJECT_OPTIONS
+ \section2 Project Options
+
+ To make your project use PCH, you only need to define the
+ \c PRECOMPILED_HEADER variable in your project file:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 105
+
+ \c qmake will handle the rest, to ensure the creation and use of the
+ precompiled header file. You do not need to include the precompiled
+ header file in \c HEADERS, as \c qmake will do this if the configuration
+ supports PCH.
+
+ All platforms that support precompiled headers have the configuration
+ option \c precompile_header set. Using this option, you may trigger
+ conditional blocks in your project file to add settings when using PCH.
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 106
+
+ \section1 Notes on Possible Issues
+
+ On some platforms, the file name suffix for precompiled header files is
+ the same as that for other object files. For example, the following
+ declarations may cause two different object files with the same name to
+ be generated:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 107
+
+ To avoid potential conflicts like these, it is good practice to ensure
+ that header files that will be precompiled are given distinctive names.
+
+ \target EXAMPLE_PROJECT
+ \section1 Example Project
+
+ You can find the following source code in the
+ \c{examples/qmake/precompile} directory in the Qt distribution:
+
+ \section2 \c mydialog.ui
+
+ \quotefromfile examples/qmake/precompile/mydialog.ui
+ \printuntil
+
+ \section2 \c stable.h
+
+ \snippet examples/qmake/precompile/stable.h 0
+
+ \section2 \c myobject.h
+
+ \snippet examples/qmake/precompile/myobject.h 0
+
+ \section2 \c myobject.cpp
+
+ \snippet examples/qmake/precompile/myobject.cpp 0
+
+ \section2 \c util.cpp
+
+ \snippet examples/qmake/precompile/util.cpp 0
+
+ \section2 \c main.cpp
+
+ \snippet examples/qmake/precompile/main.cpp 0
+
+ \section2 \c precompile.pro
+
+ \snippet examples/qmake/precompile/precompile.pro 0
+*/
+
+/*!
+ \page qmake-tutorial.html
+ \title qmake Tutorial
+ \contentspage {qmake Manual}{Contents}
+ \previouspage qmake Manual
+ \nextpage qmake Common Projects
+
+ This tutorial teaches you how to use \c qmake. We recommend that
+ you read the \c qmake user guide after completing this tutorial.
+
+ \section1 Starting off Simple
+
+ Let's assume that you have just finished a basic implementation of
+ your application, and you have created the following files:
+
+ \list
+ \o hello.cpp
+ \o hello.h
+ \o main.cpp
+ \endlist
+
+ You will find these files in the \c{examples/qmake/tutorial} directory
+ of the Qt distribution. The only other thing you know about the setup of
+ the application is that it's written in Qt. First, using your favorite
+ plain text editor, create a file called \c hello.pro in
+ \c{examples/qmake/tutorial}. The first thing you need to do is add the
+ lines that tell \c qmake about the source and header files that are part
+ of your development project.
+
+ We'll add the source files to the project file first. To do this you
+ need to use the \l{qmake Variable Reference#SOURCES}{SOURCES} variable.
+ Just start a new line with \c {SOURCES +=} and put hello.cpp after it.
+ You should have something like this:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 108
+
+ We repeat this for each source file in the project, until we end up
+ with the following:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 109
+
+ If you prefer to use a Make-like syntax, with all the files listed in
+ one go you can use the newline escaping like this:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 110
+
+ Now that the source files are listed in the project file, the header
+ files must be added. These are added in exactly the same way as source
+ files, except that the variable name we use is
+ \l{qmake Variable Reference#HEADERS}{HEADERS}.
+
+ Once you have done this, your project file should look something like
+ this:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 111
+
+ The target name is set automatically; it is the same as the project
+ file, but with the suffix appropriate to the platform. For example, if
+ the project file is called \c hello.pro, the target will be \c hello.exe
+ on Windows and \c hello on Unix. If you want to use a different name
+ you can set it in the project file:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 112
+
+ The final step is to set the \l{qmake Variable Reference#CONFIG}{CONFIG}
+ variable. Since this is a Qt application, we need to put \c qt on the
+ \c CONFIG line so that \c qmake will add the relevant libraries to be
+ linked against and ensure that build lines for \c moc and \c uic are
+ included in the generated Makefile.
+
+ The finished project file should look like this:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 113
+
+ You can now use \c qmake to generate a Makefile for your application.
+ On the command line, in your project's directory, type the following:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 114
+
+ Then type \c make or \c nmake depending on the compiler you use.
+
+ For Visual Studio users, \c qmake can also generate \c .dsp or
+ \c .vcproj files, for example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 115
+
+ \section1 Making an Application Debuggable
+
+ The release version of an application doesn't contain any debugging
+ symbols or other debugging information. During development it is useful
+ to produce a debugging version of the application that has the
+ relevant information. This is easily achieved by adding \c debug to the
+ \c CONFIG variable in the project file.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 116
+
+ Use \c qmake as before to generate a Makefile and you will be able to
+ obtain useful information about your application when running it in
+ a debugging environment.
+
+ \section1 Adding Platform-Specific Source Files
+
+ After a few hours of coding, you might have made a start on the
+ platform-specific part of your application, and decided to keep the
+ platform-dependent code separate. So you now have two new files to
+ include into your project file: \c hellowin.cpp and \c
+ hellounix.cpp. We can't just add these to the \c SOURCES
+ variable since this will put both files in the Makefile. So, what we
+ need to do here is to use a scope which will be processed depending on
+ which platform \c qmake is run on.
+
+ A simple scope that will add in the platform-dependent file for
+ Windows looks like this:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 117
+
+ So if \c qmake is run on Windows, it will add \c hellowin.cpp to the
+ list of source files. If \c qmake is run on any other platform, it
+ will simply ignore it. Now all that is left to be done is to create a
+ scope for the Unix-specific file.
+
+ When you have done that, your project file should now look
+ something like this:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 118
+
+ Use \c qmake as before to generate a Makefile.
+
+ \section1 Stopping qmake If a File Doesn't Exist
+
+ You may not want to create a Makefile if a certain file doesn't exist.
+ We can check if a file exists by using the exists() function. We can
+ stop \c qmake from processing by using the error() function. This
+ works in the same way as scopes do. Simply replace the scope condition
+ with the function. A check for a \c main.cpp file looks like this:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 119
+
+ The \c{!} symbol is used to negate the test; i.e. \c{exists( main.cpp )}
+ is true if the file exists, and \c{!exists( main.cpp )} is true if the
+ file doesn't exist.
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 120
+
+ Use \c qmake as before to generate a makefile. If you rename \c
+ main.cpp temporarily, you will see the message and \c qmake will stop
+ processing.
+
+ \section1 Checking for More than One Condition
+
+ Suppose you use Windows and you want to be able to see statement
+ output with qDebug() when you run your application on the command line.
+ Unless you build your application with the appropriate console setting,
+ you won't see the output. We can easily put \c console on the \c CONFIG
+ line so that on Windows the makefile will have this setting. However,
+ let's say that we only want to add the \c CONFIG line if we are running
+ on Windows \e and when \c debug is already on the \c CONFIG line.
+ This requires using two nested scopes; just create one scope, then create
+ the other inside it. Put the settings to be processed inside the last
+ scope, like this:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 121
+
+ Nested scopes can be joined together using colons, so the final
+ project file looks like this:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 122
+
+ That's it! You have now completed the tutorial for \c qmake, and are
+ ready to write project files for your development projects.
+*/
+
+/*!
+ \page qmake-common-projects.html
+ \title qmake Common Projects
+ \contentspage {qmake Manual}{Contents}
+ \previouspage qmake Tutorial
+ \nextpage Using qmake
+
+ This chapter describes how to set up \c qmake project files for three
+ common project types that are based on Qt. Although all kinds of
+ projects use many of the same variables, each of them use project-specific
+ variables to customize output files.
+
+ Platform-specific variables are not described here; we refer the reader to
+ the \l{Deploying Qt Applications} document for information on issues such as
+ \l{Deploying an Application on Mac OS X#Architecture Dependencies}{building
+ universal binaries for Mac OS X} and
+ \l{Deploying an Application on Windows#Visual Studio 2005 Onwards}
+ {handling Visual Studio manifest files}.
+
+ \tableofcontents
+
+ \target Application
+ \section1 Building an Application
+
+ \section2 The app Template
+
+ The \c app template tells \c qmake to generate a Makefile that will build
+ an application. With this template, the type of application can be specified
+ by adding one of the following options to the \c CONFIG variable definition:
+
+ \table
+ \header \o Option \o Description
+ \row \o windows \o The application is a Windows GUI application.
+ \row \o console \o \c app template only: the application is a Windows console
+ application.
+ \endtable
+
+ When using this template the following \c qmake system variables are recognized.
+ You should use these in your .pro file to specify information about your
+ application.
+
+ \list
+ \o HEADERS - A list of all the header files for the application.
+ \o SOURCES - A list of all the source files for the application.
+ \o FORMS - A list of all the UI files (created using \c{Qt Designer})
+ for the application.
+ \o LEXSOURCES - A list of all the lex source files for the application.
+ \o YACCSOURCES - A list of all the yacc source files for the application.
+ \o TARGET - Name of the executable for the application. This defaults
+ to the name of the project file. (The extension, if any, is added
+ automatically).
+ \o DESTDIR - The directory in which the target executable is placed.
+ \o DEFINES - A list of any additional pre-processor defines needed for the application.
+ \o INCLUDEPATH - A list of any additional include paths needed for the application.
+ \o DEPENDPATH - The dependency search path for the application.
+ \o VPATH - The search path to find supplied files.
+ \o DEF_FILE - Windows only: A .def file to be linked against for the application.
+ \o RC_FILE - Windows only: A resource file for the application.
+ \o RES_FILE - Windows only: A resource file to be linked against for the application.
+ \endlist
+
+ You only need to use the system variables that you have values for,
+ for instance, if you do not have any extra INCLUDEPATHs then you do not
+ need to specify any, \c qmake will add in the default ones needed.
+ For instance, an example project file might look like this:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 123
+
+ For items that are single valued, e.g. the template or the destination
+ directory, we use "="; but for multi-valued items we use "+=" to \e
+ add to the existing items of that type. Using "=" replaces the item's
+ value with the new value, for example if we wrote \c{DEFINES=QT_DLL},
+ all other definitions would be deleted.
+
+ \target Library
+ \section1 Building a Library
+
+ \section2 The lib Template
+
+ The \c lib template tells \c qmake to generate a Makefile that will
+ build a library. When using this template, in addition to the system variables
+ mentioned above for the \c app template the \c VERSION variable is
+ supported. You should use these in your .pro file to specify
+ information about the library.
+
+ When using the \c lib template, the following options can be added to the
+ \c CONFIG variable to determine the type of library that is built:
+
+ \table
+ \header \o Option \o Description
+ \row \o dll \o The library is a shared library (dll).
+ \row \o staticlib \o The library is a static library.
+ \row \o plugin \o The library is a plugin; this also enables the dll option.
+ \endtable
+
+ The following option can also be defined to provide additional information about
+ the library.
+
+ \list
+ \o VERSION - The version number of the target library, for example, 2.3.1.
+ \endlist
+
+ The target file name for the library is platform-dependent. For example, on
+ X11 and Mac OS X, the library name will be prefixed by \c lib; on Windows,
+ no prefix is added to the file name.
+
+ \target Plugin
+ \section1 Building a Plugin
+
+ Plugins are built using the \c lib template, as described in the previous
+ section. This tells \c qmake to generate a Makefile for the project that will
+ build a plugin in a suitable form for each platform, usually in the form of a
+ library. As with ordinary libraries, the \c VERSION variable is used to specify
+ information about the plugin.
+
+ \list
+ \o VERSION - The version number of the target library, for example, 2.3.1.
+ \endlist
+
+ \section2 Building a Qt Designer Plugin
+
+ \QD plugins are built using a specific set of configuration settings that
+ depend on the way Qt was configured for your system. For convenience, these
+ settings can be enabled by adding \c designer to the project's \c CONFIG
+ variable. For example:
+
+ \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 0
+
+ See the \l{Qt Designer Examples} for more examples of plugin-based projects.
+
+ \section1 Building and Installing in Debug and Release Modes
+
+ Sometimes, it is necessary to build a project in both debug and release
+ modes. Although the \c CONFIG variable can hold both \c debug and \c release
+ options, the \c debug option overrides the \c release option.
+
+ \section2 Building in Both Modes
+
+ To enable a project to be built in both modes, you must add the
+ \c debug_and_release option to your project's \c CONFIG definition:
+
+ \snippet doc/src/snippets/qmake/debug_and_release.pro 0
+ \snippet doc/src/snippets/qmake/debug_and_release.pro 1
+
+ The scope in the above snippet modifies the build target in each mode to
+ ensure that the resulting targets have different names. Providing different
+ names for targets ensures that one will not overwrite the other.
+
+ When \c qmake processes the project file, it will generate a Makefile rule
+ to allow the project to be built in both modes. This can be invoked in the
+ following way:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 124
+
+ The \c build_all option can be added to the \c CONFIG variable in the
+ project file to ensure that the project is built in both modes by default:
+
+ \snippet doc/src/snippets/qmake/debug_and_release.pro 2
+
+ This allows the Makefile to be processed using the default rule:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 125
+
+ \section2 Installing in Both Modes
+
+ The \c build_all option also ensures that both versions of the target
+ will be installed when the installation rule is invoked:
+
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 126
+
+ It is possible to customize the names of the build targets depending on
+ the target platform. For example, a library or plugin may be named using a
+ different convention on Windows to the one used on Unix platforms:
+
+ \omit
+ Note: This was originally used in the customwidgetplugin.pro file, but is
+ no longer needed there.
+ \endomit
+ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 127
+
+ The default behavior in the above snippet is to modify the name used for
+ the build target when building in debug mode. An \c else clause could be
+ added to the scope to do the same for release mode; left as it is, the
+ target name remains unmodified.
+*/
+
diff --git a/doc/src/development/qmsdev.qdoc b/doc/src/development/qmsdev.qdoc
new file mode 100644
index 0000000..ceed4c1
--- /dev/null
+++ b/doc/src/development/qmsdev.qdoc
@@ -0,0 +1,166 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/* NOT DOCUMENTED !
+ \page qmsdev.html
+
+ \title The QMsDev Plugin
+
+ The Visual Studio Integration Plugin is currently available only to users of
+ Visual Studio 6. It offers simple ways of doing common tasks when writing a
+ Qt application.
+
+ \tableofcontents
+
+ \section1 How to install the Visual Studio Integration Plugin
+
+ When you install Qt, the integration plugin should be installed for you,
+ however, sometimes this does not happen, so to install the integration
+ plugin manually just carry out the following steps.
+
+ \list
+ \i Start up Visual Studio.
+ \i Select Tools|Customize|Add-ins and Macro Files.
+ \i Ensure that there is a tick next to QMsDev Developer Studio Add-In.
+ \i Click Close.
+ \endlist
+
+ Now the integration plugin should be installed. If this doesn't
+ work, then contact Qt technical support giving details of
+ what went wrong.
+
+ \section1 How to uninstall the Visual Studio Integration Plugin
+
+ When you want to uninstall the integration plugin, just carry out the
+ following steps.
+
+ \list
+ \i Close down any instances of Visual Studio.
+ \i Delete the file '%MSDevDir%\\addins\\qmsdev.dll'
+ \endlist
+
+ \section1 What can the Visual Studio Integration Plugin do?
+
+ The integration plugin adds the following options to Visual Studio:
+
+ \list
+ \i New Qt Project
+ \i New Qt Dialog
+ \i Qt Designer
+ \i Open Qt Project
+ \i Write Qt Project
+ \i Use Qt In Current Project
+ \i Add MOC
+ \endlist
+
+ \section2 Using the 'New Qt Project' button
+
+ The 'New Qt Project' button allows you to create a simple Qt project
+ ready for development. Simply fill in the form and if you select
+ 'Dialog' or 'Main Window' without MDI support then it will
+ automatically start up \e{Qt Designer}. When you have finished with
+ the form in \e{Qt Designer} just save it and it will appear in a
+ ready made Qt project.
+
+ If you select 'Main Window' with 'MDI Support' then it will simply
+ give you a code skeleton in a project ready for you to populate with
+ your own code.
+
+ \section2 Using the 'New Qt Dialog' button
+
+ The 'New Qt Dialog' button works in two ways: You can use it to create a new
+ dialog for your project; or you can use it to insert an existing
+ dialog into your project.
+
+ If you want to create a new dialog then all you need to do is specify where
+ the dialog file should be saved and give it a name. This will start up
+ \e{Qt Designer} to allow you to design your new dialog, and will add it to
+ the existing project.
+
+ If you want to add an existing dialog to your project, then just select the
+ relevant UI file. This will then add it to your existing project and add
+ the relevant steps to create the generated code.
+
+ \section2 Using the 'Qt Designer' button
+
+ The 'Qt Designer' button simply starts up \e{Qt Designer}, it has no ties to
+ your existing project so whatever you do with it will not affect your
+ existing projects. It can also be started up by using the Ctrl+Shift+D key
+ combination in Visual Studio.
+
+ \section2 Using the 'Open Qt Project' button
+
+ The 'Open Qt Project' button allows you to convert an existing \c
+ qmake project file into a \c .dsp file which you can insert into
+ your existing workspace. When you click the 'Open Qt Project'
+ button, just select an existing \c qmake project file (a \c .pro
+ file) and then click OK. You will get a message box at the end
+ which asks you to insert the newly created \c .dsp file into your
+ existing workspace.
+
+ \section2 Using the 'Write Qt Project' button
+
+ The 'Write Qt Project' button creates a \c qmake project (\c .pro)
+ file for your current project so that you can easily copy the files
+ onto another platform and be able to use \c qmake to create a Makefile
+ on that other platform. All you need to do is make the project you
+ want to create a \c .pro file for, and click on the button. Just
+ name your \c qmake project file and click Save.
+
+ \section2 Using the 'Use Qt In Current Project' button
+
+ The 'Use Qt In Current Project' button simply adds in the necessary
+ information for the current project so that it links against Qt and
+ sets any other settings needed to use Qt in that project.
+
+ \section2 Using the 'Add MOC' button
+
+ The 'Add MOC' button will add in the custom build step for the selected file
+ so that it creates any needed MOC files and it will add these generated
+ files to the project. All you need to do to use it is click on a file that
+ has Q_OBJECT and click the button.
+
+ You only need to use this button if you added a file that has
+ Q_OBJECT in it by hand, you don't need to use this if you used any
+ of the previously mentioned buttons. It can also be invoked by using
+ the \key{Ctrl+Shift+M} key combination in Visual Studio.
+
+*/
diff --git a/doc/src/development/qtestlib.qdoc b/doc/src/development/qtestlib.qdoc
new file mode 100644
index 0000000..13a5b7c
--- /dev/null
+++ b/doc/src/development/qtestlib.qdoc
@@ -0,0 +1,778 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page qtestlib-manual.html
+ \title QTestLib Manual
+ \brief An overview of Qt's unit testing framework.
+
+ \ingroup frameworks-technologies
+ \keyword qtestlib
+
+ The QTestLib framework, provided by Nokia, is a tool for unit
+ testing Qt based applications and libraries. QTestLib provides
+ all the functionality commonly found in unit testing frameworks as
+ well as extensions for testing graphical user interfaces.
+
+ Table of contents:
+
+ \tableofcontents
+
+ \section1 QTestLib Features
+
+ QTestLib is designed to ease the writing of unit tests for Qt
+ based applications and libraries:
+
+ \table
+ \header \o Feature \o Details
+ \row
+ \o \bold Lightweight
+ \o QTestLib consists of about 6000 lines of code and 60
+ exported symbols.
+ \row
+ \o \bold Self-contained
+ \o QTestLib requires only a few symbols from the Qt Core library
+ for non-gui testing.
+ \row
+ \o \bold {Rapid testing}
+ \o QTestLib needs no special test-runners; no special
+ registration for tests.
+ \row
+ \o \bold {Data-driven testing}
+ \o A test can be executed multiple times with different test data.
+ \row
+ \o \bold {Basic GUI testing}
+ \o QTestLib offers functionality for mouse and keyboard simulation.
+ \row
+ \o \bold {Benchmarking}
+ \o QTestLib supports benchmarking and provides several measurement back-ends.
+ \row
+ \o \bold {IDE friendly}
+ \o QTestLib outputs messages that can be interpreted by Visual
+ Studio and KDevelop.
+ \row
+ \o \bold Thread-safety
+ \o The error reporting is thread safe and atomic.
+ \row
+ \o \bold Type-safety
+ \o Extensive use of templates prevent errors introduced by
+ implicit type casting.
+ \row
+ \o \bold {Easily extendable}
+ \o Custom types can easily be added to the test data and test output.
+ \endtable
+
+ Note: For higher-level GUI and application testing needs, please
+ see the \l{Third-Party Tools}{Qt testing products provided by
+ Nokia partners}.
+
+
+ \section1 QTestLib API
+
+ All public methods are in the \l QTest namespace. In addition, the
+ \l QSignalSpy class provides easy introspection for Qt's signals and slots.
+
+
+ \section1 Using QTestLib
+
+ \section2 Creating a Test
+
+ To create a test, subclass QObject and add one or more private slots to it. Each
+ private slot is a testfunction in your test. QTest::qExec() can be used to execute
+ all testfunctions in the test object.
+
+ In addition, there are four private slots that are \e not treated as testfunctions.
+ They will be executed by the testing framework and can be used to initialize and
+ clean up either the entire test or the current test function.
+
+ \list
+ \o \c{initTestCase()} will be called before the first testfunction is executed.
+ \o \c{cleanupTestCase()} will be called after the last testfunction was executed.
+ \o \c{init()} will be called before each testfunction is executed.
+ \o \c{cleanup()} will be called after every testfunction.
+ \endlist
+
+ If \c{initTestCase()} fails, no testfunction will be executed. If \c{init()} fails,
+ the following testfunction will not be executed, the test will proceed to the next
+ testfunction.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 0
+
+ For more examples, refer to the \l{QTestLib Tutorial}.
+
+ \section2 Building a Test
+
+ If you are using \c qmake as your build tool, just add the
+ following to your project file:
+
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 1
+
+ If you are using other buildtools, make sure that you add the location
+ of the QTestLib header files to your include path (usually \c{include/QtTest}
+ under your Qt installation directory). If you are using a release build
+ of Qt, link your test to the \c QtTest library. For debug builds, use
+ \c{QtTest_debug}.
+
+ See \l {Chapter 1: Writing a Unit Test}{Writing a Unit Test} for a step by
+ step explanation.
+
+ \section2 QTestLib Command Line Arguments
+
+ \section3 Syntax
+
+ The syntax to execute an autotest takes the following simple form:
+
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 2
+
+ Substitute \c testname with the name of your executable. \c
+ testfunctions can contain names of test functions to be
+ executed. If no \c testfunctions are passed, all tests are run. If you
+ append the name of an entry in \c testdata, the test function will be
+ run only with that test data.
+
+ For example:
+
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 3
+
+ Runs the test function called \c toUpper with all available test data.
+
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 4
+
+ Runs the \c toUpper test function with all available test data,
+ and the \c toInt test function with the testdata called \c
+ zero (if the specified test data doesn't exist, the associated test
+ will fail).
+
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 5
+
+ Runs the testMyWidget function test, outputs every signal
+ emission and waits 500 milliseconds after each simulated
+ mouse/keyboard event.
+
+ \section3 Options
+
+ The following command line arguments are understood:
+
+ \list
+ \o \c -help \BR
+ outputs the possible command line arguments and give some useful help.
+ \o \c -functions \BR
+ outputs all test functions available in the test.
+ \o \c -o \e filename \BR
+ write output to the specified file, rather than to standard output
+ \o \c -silent \BR
+ silent output, only shows warnings, failures and minimal status messages
+ \o \c -v1 \BR
+ verbose output; outputs information on entering and exiting test functions.
+ \o \c -v2 \BR
+ extended verbose output; also outputs each \l QCOMPARE() and \l QVERIFY()
+ \o \c -vs \BR
+ outputs every signal that gets emitted
+ \o \c -xml \BR
+ outputs XML formatted results instead of plain text
+ \o \c -lightxml \BR
+ outputs results as a stream of XML tags
+ \o \c -eventdelay \e ms \BR
+ if no delay is specified for keyboard or mouse simulation
+ (\l QTest::keyClick(),
+ \l QTest::mouseClick() etc.), the value from this parameter
+ (in milliseconds) is substituted.
+ \o \c -keydelay \e ms \BR
+ like -eventdelay, but only influences keyboard simulation and not mouse
+ simulation.
+ \o \c -mousedelay \e ms \BR
+ like -eventdelay, but only influences mouse simulation and not keyboard
+ simulation.
+ \o \c -keyevent-verbose \BR
+ output more verbose output for keyboard simulation
+ \o \c -maxwarnings \e number\BR
+ sets the maximum number of warnings to output. 0 for unlimited, defaults to 2000.
+ \endlist
+
+ \section2 Creating a Benchmark
+
+ To create a benchmark, follow the instructions for crating a test and then add a
+ QBENCHMARK macro to the test function that you want to benchmark.
+
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 12
+
+ The code insde the QBENCHMARK macro will be measured, and possibly also repeated
+ several times in order to get an accurate measurement. This depends on the selected
+ measurement back-end. Several back-ends are available an can be selected on the
+ command line:
+
+ \target testlib-benchmarking-measurement
+
+ \table
+ \header \o Name
+ \o Commmand-line Arguemnt
+ \o Availability
+ \row \o Walltime
+ \o (default)
+ \o All platforms
+ \row \o CPU tick counter
+ \o -tickcounter
+ \o Windows, Mac OS X, Linux, many UNIX-like systems.
+ \row \o Valgrind/Callgrind
+ \o -callgrind
+ \o Linux (if installed)
+ \row \o Event Counter
+ \o -eventcounter
+ \o All platforms
+ \endtable
+
+ In short, walltime is always available but requires many repetitions to
+ get a useful result.
+ Tick counters are usually available and can provide
+ results with fewer repetitions, but can be susceptible to CPU frequency
+ scaling issues.
+ Valgrind provides exact results, but does not take
+ I/O waits into account, and is only available on a limited number of
+ platforms.
+ Event counting is available on all platforms and it provides the number of events
+ that were received by the event loop before they are sent to their corresponding
+ targets (this might include non-Qt events).
+
+ \note Depending on the device configuration, Tick counters on the
+ Windows CE platform may not be as fine-grained, compared to other platforms.
+ Devices that do not support high-resolution timers default to
+ one-millisecond granularity.
+
+ See the chapter 5 in the \l{QTestLib Tutorial} for more benchmarking examples.
+
+ \section1 Using QTestLib remotely on Windows CE
+ \c cetest is a convenience application which helps the user to launch an
+ application remotely on a Windows CE device or emulator.
+
+ It needs to be executed after the unit test has been successfully compiled.
+
+ Prior to launching, the following files are copied to the device:
+
+ \list
+ \o all Qt libraries the project links to
+ \o \l {QtRemote}{QtRemote.dll}
+ \o the c runtime library specified during installation
+ \o all files specified in the \c .pro file following the \l DEPLOYMENT rules.
+ \endlist
+
+ \section2 Using \c cetest
+ \section3 Syntax
+ The syntax to execute an autotest takes the following simple form:
+
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 6
+
+ \section3 Options
+ \c cetest provides the same options as those for unit-testing on non cross-compiled
+ platforms. See \l {QTestLib Command Line Arguments} {Command Line Arguments} for
+ more information.
+
+ The following commands are also included:
+
+ \list
+ \o \c -debug \BR
+ Test version compiled in debug mode.
+ \o \c -release \BR
+ Test version compiled in release mode.
+ \o \c -libpath \e path \BR
+ Target path to copy Qt libraries to.
+ \o \c -qt-delete \BR
+ Delete Qt libraries after execution.
+ \o \c -project-delete \BR
+ Delete project files after execution.
+ \o \c -delete \BR
+ Delete project and Qt libraries after execution.
+ \o \c -conf \BR
+ Specifies a qt.conf file to be deployed to remote directory.
+ \endlist
+
+ \note \c{debug} is the default build option.
+
+ \section2 QtRemote
+ \c QtRemote is a small library which is build after QTestLib. It allows the host
+ system to create a process on a remote device and waits until its execution has
+ been finished.
+
+ \section2 Requirements
+ \c cetest uses Microsoft ActiveSync to establish a remote connection between the
+ host computer and the device. Thus header files and libraries are needed to compile
+ cetest and QtRemote successfully.
+
+ Prior to \l{Installing Qt on Windows CE}{installation} of Qt, you need to set your
+ \c INCLUDE and \c LIB environment variables properly.
+
+ A default installation of Windows Mobile 5 for Pocket PC can be obtained by:
+
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 7
+
+ Note that Qt will remember the path, so you do not need to set it again
+ after switching the environments for cross-compilation.
+
+ \section1 3rd Party Code
+
+ The CPU tick counters used for benchmarking is licensed under the following
+ license: (from src/testlib/3rdparty/cycle.h)
+
+ \legalese
+ Copyright (c) 2003, 2006 Matteo Frigo\br
+ Copyright (c) 2003, 2006 Massachusetts Institute of Technology
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ \endlegalese
+*/
+
+/*!
+ \page qtestlib-tutorial.html
+ \brief A short introduction to testing with QTestLib.
+ \contentspage QTestLib Manual
+ \nextpage {Chapter 1: Writing a Unit Test}{Chapter 1}
+
+ \title QTestLib Tutorial
+
+ This tutorial gives a short introduction to how to use some of the
+ features of the QTestLib framework. It is divided into four
+ chapters:
+
+ \list 1
+ \o \l {Chapter 1: Writing a Unit Test}{Writing a Unit Test}
+ \o \l {Chapter 2: Data Driven Testing}{Data Driven Testing}
+ \o \l {Chapter 3: Simulating GUI Events}{Simulating GUI Events}
+ \o \l {Chapter 4: Replaying GUI Events}{Replaying GUI Events}
+ \o \l {Chapter 5: Writing a Benchmark}{Writing a Benchmark}
+ \endlist
+
+*/
+
+
+/*!
+ \example qtestlib/tutorial1
+
+ \contentspage {QTestLib Tutorial}{Contents}
+ \nextpage {Chapter 2: Data Driven Testing}{Chapter 2}
+
+ \title Chapter 1: Writing a Unit Test
+
+ In this first chapter we will see how to write a simple unit test
+ for a class, and how to execute it.
+
+ \section1 Writing a Test
+
+ Let's assume you want to test the behavior of our QString class.
+ First, you need a class that contains your test functions. This class
+ has to inherit from QObject:
+
+ \snippet examples/qtestlib/tutorial1/testqstring.cpp 0
+
+ Note that you need to include the QTest header, and that the
+ test functions have to be declared as private slots so the
+ test framework finds and executes it.
+
+ Then you need to implement the test function itself. The
+ implementation could look like this:
+
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 8
+
+ The \l QVERIFY() macro evaluates the expression passed as its
+ argument. If the expression evaluates to true, the execution of
+ the test function continues. Otherwise, a message describing the
+ failure is appended to the test log, and the test function stops
+ executing.
+
+ But if you want a more verbose output to the test log, you should
+ use the \l QCOMPARE() macro instead:
+
+ \snippet examples/qtestlib/tutorial1/testqstring.cpp 1
+
+ If the strings are not equal, the contents of both strings is
+ appended to the test log, making it immediately visible why the
+ comparison failed.
+
+ Finally, to make our test case a stand-alone executable, the
+ following two lines are needed:
+
+ \snippet examples/qtestlib/tutorial1/testqstring.cpp 2
+
+ The \l QTEST_MAIN() macro expands to a simple \c main()
+ method that runs all the test functions. Note that if both the
+ declaration and the implementation of our test class are in a \c
+ .cpp file, we also need to include the generated moc file to make
+ Qt's introspection work.
+
+ \section1 Executing a Test
+
+ Now that we finished writing our test, we want to execute
+ it. Assuming that our test was saved as \c testqstring.cpp in an
+ empty directory: we build the test using qmake to create a project
+ and generate a makefile.
+
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 9
+
+ \bold {Note:}If you're using windows, replace \c make with \c
+ nmake or whatever build tool you use.
+
+ Running the resulting executable should give you the following
+ output:
+
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 10
+
+ Congratulations! You just wrote and executed your first unit test
+ using the QTestLib framework.
+*/
+
+/*!
+ \example qtestlib/tutorial2
+
+ \previouspage {Chapter 1: Writing a Unit Test}{Chapter 1}
+ \contentspage {QTestLib Tutorial}{Contents}
+ \nextpage {Chapter 3: Simulating Gui Events}{Chapter 3}
+
+ \title Chapter 2: Data Driven Testing
+
+ In this chapter we will demonstrate how to execute a test
+ multiple times with different test data.
+
+ So far, we have hard coded the data we wanted to test into our
+ test function. If we add more test data, the function might look like
+ this:
+
+ \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 11
+
+ To prevent that the function ends up being cluttered by repetitive
+ code, QTestLib supports adding test data to a test function. All
+ we need is to add another private slot to our test class:
+
+ \snippet examples/qtestlib/tutorial2/testqstring.cpp 0
+
+ \section1 Writing the Data Function
+
+ A test function's associated data function carries the same name,
+ appended by \c{_data}. Our data function looks like this:
+
+ \snippet examples/qtestlib/tutorial2/testqstring.cpp 1
+
+ First, we define the two elements of our test table using the \l
+ QTest::addColumn() function: A test string, and the
+ expected result of applying the QString::toUpper() function to
+ that string.
+
+ Then we add some data to the table using the \l
+ QTest::newRow() function. Each set of data will become a
+ separate row in the test table.
+
+ \l QTest::newRow() takes one argument: A name that will be
+ associated with the data set. If the test fails, the name will be
+ used in the test log, referencing the failed data. Then we
+ stream the data set into the new table row: First an arbitrary
+ string, and then the expected result of applying the
+ QString::toUpper() function to that string.
+
+ You can think of the test data as a two-dimensional table. In
+ our case, it has two columns called \c string and \c result and
+ three rows. In addition a name as well as an index is associated
+ with each row:
+
+ \table
+ \header
+ \o index
+ \o name
+ \o string
+ \o result
+ \row
+ \o 0
+ \o all lower
+ \o "hello"
+ \o HELLO
+ \row
+ \o 1
+ \o mixed
+ \o "Hello"
+ \o HELLO
+ \row
+ \o 2
+ \o all upper
+ \o "HELLO"
+ \o HELLO
+ \endtable
+
+ \section1 Rewriting the Test Function
+
+ Our test function can now be rewritten:
+
+ \snippet examples/qtestlib/tutorial2/testqstring.cpp 2
+
+ The TestQString::toUpper() function will be executed three times,
+ once for each entry in the test table that we created in the
+ associated TestQString::toUpper_data() function.
+
+ First, we fetch the two elements of the data set using the \l
+ QFETCH() macro. \l QFETCH() takes two arguments: The data type of
+ the element and the element name. Then we perform the test using
+ the \l QCOMPARE() macro.
+
+ This approach makes it very easy to add new data to the test
+ without modifying the test itself.
+
+ And again, to make our test case a stand-alone executable,
+ the following two lines are needed:
+
+ \snippet examples/qtestlib/tutorial2/testqstring.cpp 3
+
+ As before, the QTEST_MAIN() macro expands to a simple main()
+ method that runs all the test functions, and since both the
+ declaration and the implementation of our test class are in a .cpp
+ file, we also need to include the generated moc file to make Qt's
+ introspection work.
+*/
+
+/*!
+ \example qtestlib/tutorial3
+
+ \previouspage {Chapter 2 Data Driven Testing}{Chapter 2}
+ \contentspage {QTestLib Tutorial}{Contents}
+ \nextpage {Chapter 4: Replaying GUI Events}{Chapter 4}
+
+ \title Chapter 3: Simulating GUI Events
+
+ QTestLib features some mechanisms to test graphical user
+ interfaces. Instead of simulating native window system events,
+ QTestLib sends internal Qt events. That means there are no
+ side-effects on the machine the tests are running on.
+
+ In this chapter we will se how to write a simple GUI test.
+
+ \section1 Writing a GUI test
+
+ This time, let's assume you want to test the behavior of our
+ QLineEdit class. As before, you will need a class that contains
+ your test function:
+
+ \snippet examples/qtestlib/tutorial3/testgui.cpp 0
+
+ The only difference is that you need to include the QtGui class
+ definitions in addition to the QTest namespace.
+
+ \snippet examples/qtestlib/tutorial3/testgui.cpp 1
+
+ In the implementation of the test function we first create a
+ QLineEdit. Then we simulate writing "hello world" in the line edit
+ using the \l QTest::keyClicks() function.
+
+ \note The widget must also be shown in order to correctly test keyboard
+ shortcuts.
+
+ QTest::keyClicks() simulates clicking a sequence of keys on a
+ widget. Optionally, a keyboard modifier can be specified as well
+ as a delay (in milliseconds) of the test after each key click. In
+ a similar way, you can use the QTest::keyClick(),
+ QTest::keyPress(), QTest::keyRelease(), QTest::mouseClick(),
+ QTest::mouseDClick(), QTest::mouseMove(), QTest::mousePress()
+ and QTest::mouseRelease() functions to simulate the associated
+ GUI events.
+
+ Finally, we use the \l QCOMPARE() macro to check if the line edit's
+ text is as expected.
+
+ As before, to make our test case a stand-alone executable, the
+ following two lines are needed:
+
+ \snippet examples/qtestlib/tutorial3/testgui.cpp 2
+
+ The QTEST_MAIN() macro expands to a simple main() method that
+ runs all the test functions, and since both the declaration and
+ the implementation of our test class are in a .cpp file, we also
+ need to include the generated moc file to make Qt's introspection
+ work.
+*/
+
+/*!
+ \example qtestlib/tutorial4
+
+ \previouspage {Chapter 3: Simulating GUI Event}{Chapter 3}
+ \contentspage {QTestLib Tutorial}{Contents}
+ \nextpage {Chapter 5: Writing a Benchmark}{Chapter 5}
+
+ \title Chapter 4: Replaying GUI Events
+
+ In this chapter, we will show how to simulate a GUI event,
+ and how to store a series of GUI events as well as replay them on
+ a widget.
+
+ The approach to storing a series of events and replay them, is
+ quite similar to the approach explained in \l {Chapter 2:
+ Data Driven Testing}{chapter 2}; all you need is to add a data
+ function to your test class:
+
+ \snippet examples/qtestlib/tutorial4/testgui.cpp 0
+
+ \section1 Writing the Data Function
+
+ As before, a test function's associated data function carries the
+ same name, appended by \c{_data}.
+
+ \snippet examples/qtestlib/tutorial4/testgui.cpp 1
+
+ First, we define the elements of the table using the
+ QTest::addColumn() function: A list of GUI events, and the
+ expected result of applying the list of events on a QWidget. Note
+ that the type of the first element is \l QTestEventList.
+
+ A QTestEventList can be populated with GUI events that can be
+ stored as test data for later usage, or be replayed on any
+ QWidget.
+
+ In our current data function, we create two \l
+ {QTestEventList}s. The first list consists of a single click to
+ the 'a' key. We add the event to the list using the
+ QTestEventList::addKeyClick() function. Then we use the
+ QTest::newRow() function to give the data set a name, and
+ stream the event list and the expected result into the table.
+
+ The second list consists of two key clicks: an 'a' with a
+ following 'backspace'. Again we use the
+ QTestEventList::addKeyClick() to add the events to the list, and
+ QTest::newRow() to put the event list and the expected
+ result into the table with an associated name.
+
+ \section1 Rewriting the Test Function
+
+ Our test can now be rewritten:
+
+ \snippet examples/qtestlib/tutorial4/testgui.cpp 2
+
+ The TestGui::testGui() function will be executed two times,
+ once for each entry in the test data that we created in the
+ associated TestGui::testGui_data() function.
+
+ First, we fetch the two elements of the data set using the \l
+ QFETCH() macro. \l QFETCH() takes two arguments: The data type of
+ the element and the element name. Then we create a QLineEdit, and
+ apply the list of events on that widget using the
+ QTestEventList::simulate() function.
+
+ Finally, we use the QCOMPARE() macro to check if the line edit's
+ text is as expected.
+
+ As before, to make our test case a stand-alone executable,
+ the following two lines are needed:
+
+ \snippet examples/qtestlib/tutorial4/testgui.cpp 3
+
+ The QTEST_MAIN() macro expands to a simple main() method that
+ runs all the test functions, and since both the declaration and
+ the implementation of our test class are in a .cpp file, we also
+ need to include the generated moc file to make Qt's introspection
+ work.
+*/
+
+/*!
+ \example qtestlib/tutorial5
+
+ \previouspage {Chapter 4: Replaying GUI Events}{Chapter 4}
+ \contentspage {QTestLib Tutorial}{Contents}
+
+ \title Chapter 5: Writing a Benchmark
+
+ In this final chapter we will demonstrate how to write benchmarks
+ using QTestLib.
+
+ \section1 Writing a Benchmark
+ To create a benchmark we extend a test function with a QBENCHMARK macro.
+ A benchmark test function will then typically consist of setup code and
+ a QBENCHMARK macro that contains the code to be measured. This test
+ function benchmarks QString::localeAwareCompare().
+
+ \snippet examples/qtestlib/tutorial5/benchmarking.cpp 0
+
+ Setup can be done at the beginning of the function, the clock is not
+ running at this point. The code inside the QBENCHMARK macro will be
+ measured, and possibly repeated several times in order to get an
+ accurate measurement.
+
+ Several \l {testlib-benchmarking-measurement}{back-ends} are available
+ and can be selected on the command line.
+
+ \section1 Data Functions
+
+ Data functions are useful for creating benchmarks that compare
+ multiple data inputs, for example locale aware compare against standard
+ compare.
+
+ \snippet examples/qtestlib/tutorial5/benchmarking.cpp 1
+
+ The test function then uses the data to determine what to benchmark.
+
+ \snippet examples/qtestlib/tutorial5/benchmarking.cpp 2
+
+ The "if(useLocaleCompare)" switch is placed outside the QBENCHMARK
+ macro to avoid measuring its overhead. Each benchmark test function
+ can have one active QBENCHMARK macro.
+
+ \section1 External Tools
+
+ Tools for handling and visualizing test data are available as part of
+ the \l{qtestlib-tools} project on the Qt Labs Web site. These include
+ a tool for comparing performance data obtained from test runs and a
+ utility to generate Web-based graphs of performance data.
+
+ See the \l{qtestlib-tools Announcement} for more information on these
+ tools and a simple graphing example.
+
+*/
+
+
+
diff --git a/doc/src/development/rcc.qdoc b/doc/src/development/rcc.qdoc
new file mode 100644
index 0000000..1da641c
--- /dev/null
+++ b/doc/src/development/rcc.qdoc
@@ -0,0 +1,95 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page rcc.html
+ \title Resource Compiler (rcc)
+ \ingroup qttools
+ \keyword rcc
+
+ The \c rcc tool is used to embed resources into a Qt application during
+ the build process. It works by generating a C++ source file containing
+ data specified in a Qt resource (.qrc) file.
+
+ Usage:
+ \snippet doc/src/snippets/code/doc_src_rcc.qdoc 0
+
+ RCC accepts the following command line options:
+
+ \table
+ \header \o Option \o Argument \o Description
+
+ \row \o \c{-o} \o \o Writes output to file rather than
+ stdout.
+
+ \row \o \c{-name} \o \c name \o Creates an external initialization
+ function with name.
+
+ \row \o \c{-threshold} \o \c level \o Specifies a threshold (in bytes)
+ to use when compressing files. If
+ the file is smaller than the
+ threshold, it will not be
+ compressed, independent of what
+ the compression level is.
+
+ \row \o \c{-compress} \o \c level \o Compresses input files with the
+ given level. Level is an integer
+ from 1 to 9 - 1 being the fastest,
+ producing the least compression;
+ 9 being the slowest, producing
+ the most compression.
+
+ \row \o \c{-root} \o \c path \o Prefixes the resource access path
+ with root path.
+
+ \row \o \c{-no-compress} \o \o Disables all compression.
+
+ \row \o \c{-binary} \o \o Outputs a binary file for use as
+ a dynamic resource.
+
+ \row \o \c{-version} \o \o Displays version information.
+
+ \row \o \c{-help} \o \o Displays usage information.
+ \endtable
+
+ See also \l{The Qt Resource System} for more information about embedding
+ resources in Qt applications.
+*/
diff --git a/doc/src/development/tools-list.qdoc b/doc/src/development/tools-list.qdoc
new file mode 100644
index 0000000..01f71d3
--- /dev/null
+++ b/doc/src/development/tools-list.qdoc
@@ -0,0 +1,84 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \group qttools
+ \title Qt's Tools
+
+ Qt is supplied with several command line and graphical tools to
+ ease and speed the development process. Each tool is listed here
+ with a link to its documentation.
+
+ \table
+ \header \o Tool \o Description
+ \row \o \l{Qt Designer Manual}{Qt Designer}
+ \o Create forms visually.
+ \row \o \l{Qt Assistant Manual}{Qt Assistant}
+ \o Quickly find the help you need.
+ \row \o \l{Qt Linguist Manual}{Qt Linguist, lupdate, lrelease, lconvert}
+ \o Translate applications to reach international markets.
+ \row \o \l{qmake Manual}{qmake}
+ \o Create makefiles from simple platform-independent project files (\c .pro files).
+ \row \o \l{The Virtual Framebuffer}{qvfb}
+ \o Run and test embedded applications on the desktop.
+ \row \o \l{makeqpf}
+ \o Create pre-rendered fonts for embedded devices.
+ \row \o \l{moc}{Meta-Object Compiler (moc)}
+ \o Generate meta-object information for QObject subclasses.
+ \row \o \l{User Interface Compiler (uic)}
+ \o Generate C++ code from user interface files.
+ \row \o \l{Resource Compiler (rcc)}
+ \o Embed resources into Qt applications during the build process.
+ \row \o \l{Configuring Qt}{Configuring Qt (qtconfig)}
+ \o X11-based Qt configuration tool with online help.
+ \row \o \l{Fine-Tuning Features in Qt}{Configuring Qt Embedded (qconfig)}
+ \o Qt Embedded (Linux and Windows CE) configuration tool.
+ \row \o \l{Examples and Demos Launcher}
+ \o A launcher for Qt's Examples and Demonstration programs.
+ \row \o \l{qt3to4 - The Qt 3 to 4 Porting Tool}
+ \o A tool to assist in porting applications from Qt 3 to Qt 4.
+ \row \o \l{QtDBus XML compiler (qdbusxml2cpp)}
+ \o A tool to convert D-Bus interface descriptions to C++ source code.
+ \row \o \l{D-Bus Viewer}
+ \o A tool to introspect D-Bus objects and messages.
+ \endtable
+
+*/
diff --git a/doc/src/development/uic.qdoc b/doc/src/development/uic.qdoc
new file mode 100644
index 0000000..b05643c
--- /dev/null
+++ b/doc/src/development/uic.qdoc
@@ -0,0 +1,88 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page uic.html
+ \title User Interface Compiler (uic)
+ \ingroup qttools
+ \keyword uic
+
+ \omit KEEP THIS FILE SYNCHRONIZED WITH uic.1 \endomit
+
+ This page documents the \e{User Interface Compiler} for the Qt GUI
+ toolkit. The \c uic reads an XML format user interface definition
+ (\c .ui) file as generated by \l{designer-manual.html}{Qt
+ Designer} and creates a corresponding C++ header file.
+
+ Usage:
+ \snippet doc/src/snippets/code/doc_src_uic.qdoc 0
+
+ \section1 Options
+
+ The following table lists the command-line options recognized by
+ \c uic.
+
+ \table
+ \header \o Option \o Description
+ \row \o \c{-o <file>} \o Write output to \c <file> instead of to standard output.
+ \row \o \c{-tr <func>} \o Use \c <func> for translating strings instead of \c tr().
+ \row \o \c{-p} \o Don't generate guards against multiple inclusion (\c #ifndef FOO_H ...).
+ \row \o \c{-h} \o Display the usage and the list of options.
+ \row \o \c{-v} \o Display \c{uic}'s version number.
+ \endtable
+
+ \section1 Examples
+
+ If you use \c qmake, \c uic will be invoked automatically for
+ header files.
+
+ Here are useful makefile rules if you only use GNU make:
+
+ \snippet doc/src/snippets/code/doc_src_uic.qdoc 1
+
+ If you want to write portably, you can use individual rules of the
+ following form:
+
+ \snippet doc/src/snippets/code/doc_src_uic.qdoc 2
+
+ You must also remember to add \c{ui_foo.h} to your \c HEADERS
+ (substitute your favorite name).
+*/