diff options
| author | Jason Barron <jbarron@trolltech.com> | 2009-08-18 08:34:18 +0200 |
|---|---|---|
| committer | Jason Barron <jbarron@trolltech.com> | 2009-08-18 08:34:18 +0200 |
| commit | fd6740b6ade6e7f8e51a9cc558b723e7fae15ccf (patch) | |
| tree | aa2ba4ce64d047d73c29ab0616e8a89d352c3abd /doc/src/development | |
| parent | d24029e3d4639f1300e7a68858936911df969f69 (diff) | |
| parent | 572e165dcb8cc8fcdfaa4ab9bdab050f6a6cc173 (diff) | |
Merge commit 'qt/master'
Conflicts:
doc/src/examples.qdoc
doc/src/plugins-howto.qdoc
doc/src/topics.qdoc
examples/phonon/musicplayer/mainwindow.cpp
src/3rdparty/freetype/src/base/ftobjs.c
src/corelib/global/qglobal.h
src/corelib/tools/qalgorithms.h
src/corelib/tools/qshareddata.cpp
src/corelib/tools/qsharedpointer.cpp
src/corelib/tools/tools.pri
src/corelib/xml/qxmlstream.h
src/gui/painting/painting.pri
src/gui/widgets/qdatetimeedit.cpp
tests/auto/qdesktopservices/qdesktopservices.pro
tests/auto/qgraphicsitem/tst_qgraphicsitem.cpp
tests/auto/qtextcodec/test/test.pro
Diffstat (limited to 'doc/src/development')
| -rw-r--r-- | doc/src/development/activeqt-dumpcpp.qdoc | 143 | ||||
| -rw-r--r-- | doc/src/development/activeqt-dumpdoc.qdoc | 83 | ||||
| -rw-r--r-- | doc/src/development/activeqt-idc.qdoc | 82 | ||||
| -rw-r--r-- | doc/src/development/activeqt-testcon.qdoc | 77 | ||||
| -rw-r--r-- | doc/src/development/assistant-manual.qdoc | 810 | ||||
| -rw-r--r-- | doc/src/development/debug.qdoc | 243 | ||||
| -rw-r--r-- | doc/src/development/designer-manual.qdoc | 2836 | ||||
| -rw-r--r-- | doc/src/development/developing-on-mac.qdoc | 269 | ||||
| -rw-r--r-- | doc/src/development/developing-with-qt.qdoc | 74 | ||||
| -rw-r--r-- | doc/src/development/moc.qdoc | 335 | ||||
| -rw-r--r-- | doc/src/development/qmake-manual.qdoc | 4722 | ||||
| -rw-r--r-- | doc/src/development/qmsdev.qdoc | 166 | ||||
| -rw-r--r-- | doc/src/development/qtestlib.qdoc | 778 | ||||
| -rw-r--r-- | doc/src/development/rcc.qdoc | 95 | ||||
| -rw-r--r-- | doc/src/development/tools-list.qdoc | 84 | ||||
| -rw-r--r-- | doc/src/development/uic.qdoc | 88 |
16 files changed, 10885 insertions, 0 deletions
diff --git a/doc/src/development/activeqt-dumpcpp.qdoc b/doc/src/development/activeqt-dumpcpp.qdoc new file mode 100644 index 0000000000..8c743a11c9 --- /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 0000000000..55ab2d7844 --- /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 0000000000..974eddcd53 --- /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 0000000000..9fcfed6665 --- /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 0000000000..b26efccdd5 --- /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 0000000000..f0fe128b3e --- /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 0000000000..5d8587a60e --- /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 0000000000..dee6d4d3de --- /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 0000000000..9fa224281f --- /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 0000000000..747c68d6a0 --- /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 0000000000..5fdc4e86d3 --- /dev/null +++ b/doc/src/development/qmake-manual.qdoc @@ -0,0 +1,4722 @@ +/**************************************************************************** +** +** 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}. + + + \section1 S60 + + Features specific to this platform include handling of static data, + capabilities, stack and heap size, compiler specific options, and unique + identifiers for the application or library. + + \section2 Handling of static data + + If the application uses any static data, the build system needs to be + informed about it. This is because Symbian tries to save memory if no + static data is in use. + + To specify that static data support is desired, add this to the project file: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 129 + + The default value is zero. + + \section2 Stack and heap size + + Symbian uses predefined sizes for stacks and heaps. If an + application exceeds either limit, it may crash or fail to complete its + task. Crashes that seem to have no reason can often be traced back to + insufficient stack and/or heap sizes. + + The stack size has a maximum value, whereas the heap size has a + minimum and a maximum value, all specified in bytes. The minimum value + prevents the application from starting if that amount of memory is not available. The + minimum and maximum values are separated by a space. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 130 + + The default values depend on the version of the S60 SDK you're using. + + \section2 Compiler specific options + + General compiler options can as usual be set using \c QMAKE_CFLAGS and \c QMAKE_CXXFLAGS. + In order to set specific compiler options, \c QMAKE_CFLAGS.<compiler> and + \c QMAKE_CXXFLAGS.<compiler> can be used. \c <compiler> can be either \c CW for the WINSCW + architecture (emulator), or \c ARMCC for the ARMv5 architecture (hardware). + + Here is an example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 131 + + \section2 Unique identifiers + + Symbian applications may have unique identifiers attached to them. + Here is how to define them in a project file: + + There are four types of IDs supported: \c UID2, \c UID3, \c SID, and \c VID. They + are specified like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 132 + + If \c UID2 is not specified, it defaults to the same value as \c UID3. + If \c UID3 is not specified, qmake will automatically generate a \c UID3 + suitable for development and debugging. This value should be manually + specified for applications that are to be released. In order to optain + an official UID, please contact Nokia. Both \c SID and \c VID default to empty values. + + For more information about unique identifiers and their meaning for + Symbian applications, please refer to the + \l{http://www.symbian.com/developer/techlib/v9.2docs/doc_source/ToolsAndUtilities/BuildTools/UsingUids.guide.html}{respective S60 SDK documentation}. + + \section2 Capabilities + + Capabilities define extra priviledges for the application, such as the + ability to list all files on the file system. Capabilities are defined + in the project file like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 133 + + It is also possible to specify which capabilities \e not to have, + by first specifying \c ALL and then list the unwanted capabilities + with a minus in front of them, like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 134 + + For more information about capabilities, please refer to the + \l{http://www.symbian.com/developer/techlib/v9.2docs/doc_source/guide/platsecsdk/index.html}{respective S60 SDK documentation}. +*/ + +/*! + \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 BLD_INF_RULES + \section1 BLD_INF_RULES + + \e {This is only used on Symbian.} + + Generic \c bld.inf file content can be specified with \c BLD_INF_RULES variables. + The section of \c bld.inf file where each rule goes is appended to + \c BLD_INF_RULES with a dot. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 146 + + This will add the specified statements to the \c prj_exports section of the + generated \c bld.inf file. + + It is also possible to add multiple rows in a single block. Each double + quoted string will be placed on a new row in the generated \c bld.inf file. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 143 + + Any rules you define will be added after automatically generated + rules in each section. + + \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 only have an effect on Symbian: + + \table 95% + \header \o Option \o Description + \row \o stdbinary \o Builds an Open C binary (i.e. STDDLL, STDEXE, or STDLIB, + depending on the target binary type.) + \row \o no_icon \o Doesn't generate resources needed for displaying an icon + for executable in application menu (app only). + \row \o symbian_test \o Places mmp files and extension makefiles under + test sections in generated bld.inf instead of their regular sections. + Note that this only affects automatically generated bld.inf content; + the content added via \c BLD_INF_RULES variable is not affected. + \endtable + + 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 and Symbian.} + + 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}. For Symbian, the default target is the application + private directory on the drive it is installed to. + + 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 In Windows CE all linked Qt libraries will be deployed to the path + specified by \c{myFiles.path}. In Symbian all libraries and executables + will always be deployed to the \\sys\\bin of the installation drive. + + Since the Symbian build system automatically moves binaries to certain + directories under the epoc32 directory, custom plugins, executables or + dynamically loadable libraries need special handling. When deploying + extra executables or dynamically loadable libraries, the target path + must specify \\sys\\bin. For plugins, the target path must specify the + location where the plugin stub will be deployed to (see the + \l{How to Create Qt Plugins} document for more information about plugins). + If the binary cannot be found from the indicated source path, + the directory Symbian build process moves the executables to is + searched, e.g. \\epoc32\\release\\armv5\\urel. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 128 + + In Symbian, generic PKG file content can also be specified with this + variable. You can use either \c pkg_prerules or \c pkg_postrules to + pass raw data to PKG file. The strings in \c pkg_prerules are added before + package-body and \c pkg_postrules after. The strings defined in + \c pkg_postrules or \c pkg_prerules are not parsed by qmake, so they + should be in a format understood by Symbian package generation tools. + Please consult Symbian documentation for correct syntax. + + For example, to deploy DLL and add a new dependency: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 140 + + Please note that \c pkg_prerules can also replace default statements in + pkg file. If no pkg_prerules is defined, qmake makes sure that PKG file + syntax is correct and it contains all mandatory statements such as: + + \list + \o languages, for example \BR + &EN,FR + \o package-header, for example \BR + #{"MyApp-EN", "MyApp-FR"}, (0x1000001F), 1, 2, 3, TYPE=SA + \o localized and unique vendor, for example \BR + %{"Vendor-EN", ..., "Vendor-FR"} + :"Unique vendor name" + \endlist + + If you decide to override any of these statements, you need to pay + attention that also other statements stay valid. For example if you + override languages statement, you must override also package-header + statement and all other statements which are language specific. + + In Symbian, the \c default_deployment item specifies + default platform dependencies. It can be overwritten if a more + restrictive set is needed - e.g. if a specific + device is required to run the application. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 141 + + \target DEPLOYMENT_PLUGIN + \section1 DEPLOYMENT_PLUGIN + + \e {This is only used on Windows CE and Symbian.} + + 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 In Windows CE, No plugins will be deployed automatically. + If the application depends on plugins, these plugins have to be specified + manually. + + \note In Symbian, all plugins supported by this variable will be deployed + by default with Qt libraries, so generally using this variable is not + needed. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 142 + + 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 ICON + \section1 ICON + + This variable is used only in MAC and S60 to set the application icon. + Please see \l{Setting the Application Icon}{the application icon documentation} + for more information. + + \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 and Symbian + (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. + + \bold{Note:} On S60, the build system makes a distinction between shared and + static libraries. In most cases, qmake will figure out which library you + are refering to, but in some cases you may have to specify it explicitly to + get the expected behavior. This typically happens if you are building a + library and using it in the same project. To specify that the library is + either shared or static, add a ".dll" or ".lib" suffix, respectively, to the + library name. + + 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 MMP_RULES + \section1 MMP_RULES + + \e {This is only used on Symbian.} + + Generic MMP file content can be specified with this variable. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 137 + + This will add the specified statement to the end of the generated MMP file. + + It is also possible to add multiple rows in a single block. Each double + quoted string will be placed on a new row in the generated MMP file. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 138 + + If you need to include a hash (\c{#}) character inside the + \c MMP_RULES statement, it can be done with the variable + \c LITERAL_HASH as follows: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 139 + + \note You should not use this variable to add MMP statements that are + explicitly supported by their own variables, such as + \c TARGET.EPOCSTACKSIZE. + Doing so could result in duplicate statements in the MMP file. + + \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. + + \bold{Note:} On S60, this variable can be used to pass architecture specific + options to each compiler in the Symbian build system. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 131 + + For more information, see + \l{qmake Platform Notes#Compiler specific options}{qmake Platform Notes}. + + \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 RSS_RULES + \section1 RSS_RULES + + \e {This is only used on Symbian.} + + Generic RSS file content can be specified with this variable. The syntax is + similar to \c MMP_RULES and \c BLD_INF_RULES. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 144 + + This will add the specified statement to the end of the generated + registration resource file. As an impact of this statement, the application + will not be visible in application shell. + + It is also possible to add multiple rows in a single block. Each double + quoted string will be placed on a new row in the registration resource file. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 145 + + This example will install the application to MyFolder in S60 application + shell. In addition it will make the application to be launched in background. + + For detailed list of possible RSS statements, please refer to Symbian OS help. + + \note You should not use \c RSS_RULES variable to set the following RSS statements: + + app_file + localisable_resource_file + localisable_resource_id + + These statements are internally handled by qmake. + + \target S60_VERSION + \section1 S60_VERSION + + \e {This is only used on Symbian.} + + Contains the version number of the underlying S60 SDK; e.g. "5.0". + + \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. + + \target TARGET.CAPABILITY + \section1 TARGET.CAPABILITY + + \e {This is only used on Symbian.} + + Specifies which platform capabilities the application should have. For more + information, please refer to the S60 SDK documentation. + + \target TARGET.EPOCALLOWDLLDATA + \section1 TARGET.EPOCALLOWDLLDATA + + \e {This is only used on Symbian.} + + Specifies whether static data should be allowed in the application. Symbian + disallows this by default in order to save memory. To use it, set this to 1. + + \target TARGET.EPOCHEAPSIZE + \section1 TARGET.EPOCHEAPSIZE + + \e {This is only used on Symbian.} + + Specifies the minimum and maximum heap size of the application. The program + will refuse to run if the minimum size is not available when it starts. For + example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 135 + + \target TARGET.EPOCSTACKSIZE + \section1 TARGET.EPOCSTACKSIZE + + \e {This is only used on Symbian.} + + Specifies the maximum stack size of the application. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 136 + + \target TARGET.SID + \section1 TARGET.SID + + \e {This is only used on Symbian.} + + Specifies which secure identifier to use for the target application or + library. For more information, see the S60 SDK documentation. + + \target TARGET.UID2 + \section1 TARGET.UID2 + + \e {This is only used on Symbian.} + + Specifies which unique identifier 2 to use for the target application or + library. If this variable is not specified, it defaults to the same value + as TARGET.UID3. For more information, see the S60 SDK documentation. + + \target TARGET.UID3 + \section1 TARGET.UID3 + + \e {This is only used on Symbian.} + + Specifies which unique identifier 3 to use for the target application or + library. If this variable is not specified, a UID3 suitable for development + and debugging will be generated automatically. However, applications being + released should always define this variable. For more information, see the + S60 SDK documentation. + + \target TARGET.VID + \section1 TARGET.VID + + \e {This is only used on Symbian.} + + Specifies which vendor identifier to use for the target application or + library. For more information, see the S60 SDK documentation. + + \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 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 variables + \o Indicates that the variables specified here are replaced with $(QMAKE_COMP_VARNAME) when refered to + in the pro file as $(VARNAME). + \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 + + \note Symbian specific: Generating objects to be linked in is not supported in Symbian, + so either the \c CONFIG option \c no_link or variable \c variable_out + should always be defined for extra compilers. + +*/ + +/*! + \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 0000000000..ceed4c1090 --- /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 0000000000..13a5b7c04b --- /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 0000000000..1da641c43c --- /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 0000000000..01f71d38a1 --- /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 0000000000..b05643c13a --- /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). +*/ |