summaryrefslogtreecommitdiffstats
path: root/Source/cmRemoveDefinitionsCommand.cxx
diff options
context:
space:
mode:
authorDaniel Pfeifer <daniel@pfeifer-mail.de>2016-10-19 06:54:18 (GMT)
committerDaniel Pfeifer <daniel@pfeifer-mail.de>2016-10-21 16:14:50 (GMT)
commitf69e768d94ff5e0238cbb924836737c4ce11a930 (patch)
tree88d4d5f0725b81517779456a6a2c9dd9136a5297 /Source/cmRemoveDefinitionsCommand.cxx
parent1e555a44aa4e3d40bca2f88915c9f957098e5a55 (diff)
downloadCMake-f69e768d94ff5e0238cbb924836737c4ce11a930.zip
CMake-f69e768d94ff5e0238cbb924836737c4ce11a930.tar.gz
CMake-f69e768d94ff5e0238cbb924836737c4ce11a930.tar.bz2
Separate compilation for commands included in cmCommands
Diffstat (limited to 'Source/cmRemoveDefinitionsCommand.cxx')
-rw-r--r--Source/cmRemoveDefinitionsCommand.cxx4
1 files changed, 4 insertions, 0 deletions
diff --git a/Source/cmRemoveDefinitionsCommand.cxx b/Source/cmRemoveDefinitionsCommand.cxx
index cae5072..f5fe2df 100644
--- a/Source/cmRemoveDefinitionsCommand.cxx
+++ b/Source/cmRemoveDefinitionsCommand.cxx
@@ -2,6 +2,10 @@
file Copyright.txt or https://cmake.org/licensing for details. */
#include "cmRemoveDefinitionsCommand.h"
+#include "cmMakefile.h"
+
+class cmExecutionStatus;
+
// cmRemoveDefinitionsCommand
bool cmRemoveDefinitionsCommand::InitialPass(
std::vector<std::string> const& args, cmExecutionStatus&)
n Aug 10 19:09:57 2009 +0200 This should link to the platform specific documentation. commit 38610f0ff210286f92528495d48f434d2c0db8e8 Author: Volker Hilsheimer Date: Mon Aug 10 18:59:35 2009 +0200 These groups are embedded in the respective framework overview already. commit 1e58a90c561d33aada9427b17db8e0f7bbe02fa7 Author: Volker Hilsheimer Date: Mon Aug 10 18:54:47 2009 +0200 Remove howtos and overviews from script group. The "Making Applications Scriptable" page needs to be split into a walkthrough anyway. commit 1e68b8d7d53500b8fb6c9c821d46e045ed7efe6f Author: Volker Hilsheimer Date: Mon Aug 10 18:30:10 2009 +0200 Groups are for classes. The objectmodel framework overview links to those. commit a0a95420c82e2a77150b070e98609aa3e1b3b1a6 Author: Volker Hilsheimer Date: Mon Aug 10 18:22:20 2009 +0200 Kill the "buildsystem" group. All documents can be reached through the "Developing with Qt" page. commit 7b23a40c5ba3a215fba6032ad96199b5c9797e98 Author: Volker Hilsheimer Date: Mon Aug 10 18:07:23 2009 +0200 This guide should only be in the porting group. commit ef731bcc53a9b34ba3b42e5ad7caf4234941c4a9 Author: Volker Hilsheimer Date: Mon Aug 10 18:06:21 2009 +0200 Phonon is a framework on its own. The whole "multimedia" group is a rather random collection of stuff... commit 5d290d48fc428573ccd31861cf57d214051ba349 Author: Volker Hilsheimer Date: Mon Aug 10 17:59:36 2009 +0200 Move the Qt Help documentation into frameworks. This needs a bit of a rewrite, and the list of classes needs to be integrated. commit 5e4d094c8712bfb46d844e09746aad5da3ac4a91 Author: Volker Hilsheimer Date: Mon Aug 10 17:58:52 2009 +0200 The list of all classes that use implicit sharing is not useful on its own. commit 2059a0be23c5953f9758098cb7a9416cb86d5ad1 Author: Volker Hilsheimer Date: Mon Aug 10 17:55:20 2009 +0200 Make the QtScript overview documentation part of frameworks. commit 3413696bd745ee5862aa517dcfc9c8446fee9b82 Author: Volker Hilsheimer Date: Mon Aug 10 17:54:59 2009 +0200 Make the list of drag & drop classes part of the framework docu. commit f1c85ea263b30de1e1a1f6c5cb8b8d9ee12254cb Author: Volker Hilsheimer Date: Mon Aug 10 17:44:57 2009 +0200 Porting guides are part of the Howto's commit cfcc742f938cf7c278f1f8b11b24a61f62fb4c62 Author: Volker Hilsheimer Date: Mon Aug 10 17:44:26 2009 +0200 All platform specific docu is available through one toplevel page. commit 53c642fe4cbc2dbd44fe5b9b4e32feeca438b5c3 Merge: c564285 41537bb Author: Volker Hilsheimer Date: Mon Aug 10 16:48:09 2009 +0200 Merge branch 'master' into doccleanup commit c5642857b2f2364134f58776661cc08a9da13b2c Merge: 9cdeba7 24aa363 Author: Volker Hilsheimer Date: Mon Aug 10 15:53:47 2009 +0200 Merge branch 'master' into doccleanup commit 9cdeba712c51eb0bf71eab35080734a2b93efcc5 Merge: 09dac33 d13418e Author: Volker Hilsheimer Date: Sat Aug 8 11:46:42 2009 +0200 Merge branch 'master' into doccleanup commit 09dac333d427792a8d33fa311a63c620678e7920 Merge: f7b211e dfa2842 Author: Volker Hilsheimer Date: Fri Aug 7 15:40:33 2009 +0200 Merge branch 'master' into doccleanup Conflicts: doc/src/examples.qdoc commit f7b211e5588fee20913a8d02c55cca0e05ea2859 Author: Volker Hilsheimer Date: Thu Aug 6 14:58:49 2009 +0200 Rename file to follow naming scheme and resulting html. commit ed6432fea376e60e4dd7c8987ed61a063af11ac7 Author: Volker Hilsheimer Date: Thu Aug 6 14:58:10 2009 +0200 Structure the XML documentation into a walk-through. The XmlPatterns docu should probably be split into two or three sections, XQuery, XPath and XML Schema. commit 3dbc1d4ca08d3cac47ca2709b6fb1a2419442c36 Author: Volker Hilsheimer Date: Thu Aug 6 14:15:00 2009 +0200 Add a table of contents. commit 1569c35cb90c10ead72dcea2c4b99a0a6cbfcc13 Author: Volker Hilsheimer Date: Thu Aug 6 14:04:52 2009 +0200 Splitting the long SQL documentation into walkthrough steps. commit 6a05688bce3cca34dd1b8b323b8feb49d3133d7e Author: Volker Hilsheimer Date: Thu Aug 6 13:49:50 2009 +0200 Combining various desktop integration topics into one document. commit c02c9adca98ba1d4494dd9c7de4ef5b191d9721a Merge: 4cc4a81 2a286b0 Author: Volker Hilsheimer Date: Thu Aug 6 08:16:04 2009 +0200 Merge branch 'doccleanup' of git@scm.dev.nokia.troll.no:qt/vohis-docuwork into doccleanup commit 4cc4a81324cff3c1ad91867cf3acb87d9b4184c6 Merge: a88dc5d 06d57fc Author: Volker Hilsheimer Date: Thu Aug 6 08:15:52 2009 +0200 Merge branch 'master' into doccleanup commit 2a286b03167ce028821b4007bf08537d2c5637c2 Author: Volker Hilsheimer Date: Wed Aug 5 23:23:28 2009 +0200 Some writing on windows and dialogs. Also some restructuring of the existing content. commit a88dc5d72bec7abeec23b289c212418499c25e4a Merge: 86f956c fb8bb14 Author: Volker Hilsheimer Date: Wed Aug 5 18:09:58 2009 +0200 Merge branch 'master' into doccleanup commit 86f956c89b9b8fb3d684665797d4a5b5e538fb2c Author: Volker Hilsheimer Date: Wed Aug 5 17:09:36 2009 +0200 All "Qt 4 vs Qt 3" docu lives in porting. Some of those files have been changed by now to move docu into overview files where the respective information was missing. commit ac6f1fc8b1e760ae69ce799e13ac92144eeb89e2 Author: Volker Hilsheimer Date: Wed Aug 5 17:06:15 2009 +0200 Start work on windows and dialogs docu. commit 4253dea2661dc3526a9dec53f336301992b543cb Author: Volker Hilsheimer Date: Wed Aug 5 16:03:52 2009 +0200 Make QtWebKit module documentation follow the other modules: - Module overview only lists classes, library, header and license implication - Usage-documentation is separated commit a27f1b8498ba8d06743e70ecde4fc1e44d5f02f0 Author: Volker Hilsheimer Date: Wed Aug 5 16:01:25 2009 +0200 Make QtWebKit classes show up in the module overview. commit d38d185ec8b7d32037e86b4ecbbc725343aabea7 Author: Volker Hilsheimer Date: Wed Aug 5 15:40:17 2009 +0200 Make the most important sections a bit larger. commit 70991dcdfb8c00baa960381b297fdcb8ed7f50d0 Merge: deb4c2b e95166d Author: Volker Hilsheimer Date: Wed Aug 5 14:35:07 2009 +0200 Merge branch 'master' into doccleanup commit deb4c2bb4d7120579fda541b03c0a77d989089d5 Merge: 37e5373 f78bd88 Author: Volker Hilsheimer Date: Wed Aug 5 12:59:22 2009 +0200 Merge branch 'master' into doccleanup commit 37e5373dcc5455b1e029ee389ce7985a98f579d9 Author: Volker Hilsheimer Date: Wed Aug 5 11:32:43 2009 +0200 These new examples are not yet fully documented commit 85fb40ea11458040e09302bb898d89664eb280b5 Merge: 8b78e18 bcf41cf Author: Volker Hilsheimer Date: Wed Aug 5 11:30:26 2009 +0200 Merge branch 'master' into doccleanup Conflicts: doc/src/examples-overview.qdoc doc/src/examples.qdoc tools/qdoc3/htmlgenerator.cpp commit 8b78e1828b93a9762301d80cb110a1f1b7c4211f Author: Volker Hilsheimer Date: Wed Aug 5 00:04:36 2009 +0200 Line-feed fixes. commit 2fa80a411dd96369c0e09defc54af44118930ae5 Author: Volker Hilsheimer Date: Wed Aug 5 00:04:00 2009 +0200 The "buildsystem" docu seems a reasonable start for proper documentation. Three lists of tools - in the buildsystem table, in the tools-list docu and implicitly through \ingroup qttools. Needs to be consolidated. commit 8d4043feab66698664cfa17bd150eabf4fe2420d Author: Volker Hilsheimer Date: Wed Aug 5 00:01:32 2009 +0200 Restructure the i18n page. The list of classes needs to be reviewed. commit 49f718b1e75c02bc43feac93d5b233064c032555 Author: Volker Hilsheimer Date: Wed Aug 5 00:00:45 2009 +0200 The Accessibility group is just a group of classes. commit b17db7dc54c1945cd2651fdebde471c71ef4001d Author: Volker Hilsheimer Date: Tue Aug 4 23:40:21 2009 +0200 Remove the "Topics" group. Things are part of frameworks or how-to documentation. Top-level groups are right now still on the "all overviews" document. commit 31e5c276b50130542dbd824b0b8cc20b16ca1cb1 Author: Volker Hilsheimer Date: Tue Aug 4 22:45:43 2009 +0200 Splitting the thread documentation into multiple pages. Also add relevant classes from QtConcurrent to the thread group. commit d491ffb0e949f1d8653d73495e091b241a025558 Merge: e99794c 3ff7afd Author: Volker Hilsheimer Date: Tue Aug 4 19:29:18 2009 +0200 Merge branch 'doccleanup' of git@scm.dev.nokia.troll.no:qt/vohis-docuwork into doccleanup commit 3ff7afd6c11d824af38c72afdea4b6578f6de784 Merge: 1dae0ad 2df403d Author: Volker Hilsheimer Date: Tue Aug 4 18:07:11 2009 +0200 Merge branch 'doccleanup' of git@scm.dev.nokia.troll.no:qt/vohis-docuwork into doccleanup Conflicts: doc/src/accessible.qdoc doc/src/activeqt.qdoc doc/src/animation.qdoc doc/src/containers.qdoc doc/src/custom-types.qdoc doc/src/desktop-integration.qdoc doc/src/dnd.qdoc doc/src/frameworks-technologies/accessible.qdoc doc/src/frameworks-technologies/activeqt-container.qdoc doc/src/frameworks-technologies/activeqt-server.qdoc doc/src/frameworks-technologies/activeqt.qdoc doc/src/frameworks-technologies/animation.qdoc doc/src/frameworks-technologies/containers.qdoc doc/src/frameworks-technologies/dbus-adaptors.qdoc doc/src/frameworks-technologies/dbus-intro.qdoc doc/src/frameworks-technologies/desktop-integration.qdoc doc/src/frameworks-technologies/dnd.qdoc doc/src/frameworks-technologies/implicit-sharing.qdoc doc/src/frameworks-technologies/ipc.qdoc doc/src/frameworks-technologies/model-view-programming.qdoc doc/src/frameworks-technologies/phonon.qdoc doc/src/frameworks-technologies/qt4-interview.qdoc doc/src/frameworks-technologies/qtdesigner.qdoc doc/src/frameworks-technologies/qthelp.qdoc doc/src/frameworks-technologies/statemachine.qdoc doc/src/frameworks-technologies/templates.qdoc doc/src/frameworks-technologies/unicode.qdoc doc/src/frameworks/accessible.qdoc doc/src/frameworks/activeqt-container.qdoc doc/src/frameworks/activeqt-server.qdoc doc/src/frameworks/activeqt.qdoc doc/src/frameworks/animation.qdoc doc/src/frameworks/containers.qdoc doc/src/frameworks/dbus-adaptors.qdoc doc/src/frameworks/dbus-intro.qdoc doc/src/frameworks/desktop-integration.qdoc doc/src/frameworks/dnd.qdoc doc/src/frameworks/ipc.qdoc doc/src/frameworks/model-view-programming.qdoc doc/src/frameworks/phonon.qdoc doc/src/frameworks/qt4-interview.qdoc doc/src/frameworks/qtdesigner.qdoc doc/src/frameworks/qthelp.qdoc doc/src/frameworks/qundo.qdoc doc/src/frameworks/richtext.qdoc doc/src/frameworks/statemachine.qdoc doc/src/graphicsview.qdoc doc/src/howtos/custom-types.qdoc doc/src/howtos/session.qdoc doc/src/implicit-sharing.qdoc doc/src/introtodbus.qdoc doc/src/ipc.qdoc doc/src/model-view-programming.qdoc doc/src/modules.qdoc doc/src/new_index.qdoc doc/src/objectmodel/custom-types.qdoc doc/src/objectmodel/object.qdoc doc/src/objectmodel/objecttrees.qdoc doc/src/overviews.qdoc doc/src/phonon.qdoc doc/src/porting/qt4-tulip.qdoc doc/src/qaxcontainer.qdoc doc/src/qaxserver.qdoc doc/src/qdbusadaptors.qdoc doc/src/qt4-interview.qdoc doc/src/qtdesigner.qdoc doc/src/qthelp.qdoc doc/src/statemachine.qdoc doc/src/technologies/implicit-sharing.qdoc doc/src/technologies/templates.qdoc doc/src/technologies/unicode.qdoc doc/src/templates.qdoc doc/src/unicode.qdoc doc/src/widgets-and-layouts/layout.qdoc doc/src/widgets-and-layouts/styles.qdoc doc/src/widgets-and-layouts/widgets.qdoc src/gui/kernel/qstandardgestures.cpp commit 1dae0adf3d85620f7574a2a0475510a627a896dc Author: Volker Hilsheimer Date: Tue Aug 4 17:46:58 2009 +0200 This way it appears as part of the overview, and the moc docu links to it. commit 5802092887e46dc5eb034bb9b45dd34a265607f5 Author: Volker Hilsheimer Date: Tue Aug 4 17:45:09 2009 +0200 Not sure what it is yet, but definitely not an architecture. QDataStream links to this page, that might just as well be enough. commit 69d32c4ff079bcaea098b34de70b7d9587e51e88 Author: Volker Hilsheimer Date: Tue Aug 4 17:43:42 2009 +0200 Use \annotatedlist command to list all widget classes. Needs nicer formatting, ie qdoc could be \table aware for those lists and skip the header. commit 02057d7575bb4f0875e82ea4cb76552f2d8ac17a Author: Volker Hilsheimer Date: Tue Aug 4 17:35:46 2009 +0200 This should be together with all the other licensing documentation. commit be91b2fe15c67cb90eaa59121d7ff51eb21b4dba Author: Volker Hilsheimer Date: Tue Aug 4 17:26:02 2009 +0200 These are best practices. commit 8e0b104db1266a736ac246c9466656c058df18f2 Author: Volker Hilsheimer Date: Tue Aug 4 17:25:35 2009 +0200 Another technology. commit 19c16384d712c652716776c94c749030b0742752 Author: Volker Hilsheimer Date: Tue Aug 4 17:24:55 2009 +0200 Remove duplicate and out-of-date license headers. commit 689aa91de0f840fc0f98f0adfbb2f18d72c6b985 Author: Volker Hilsheimer Date: Tue Aug 4 17:21:00 2009 +0200 Move into frameworks. Add explicitly printed list of classes instead of using a separate \group page. The \group page is still there as long as qdoc requires it. Threading and WebKit are still "architectures", coming later. commit 3f96833ab78dacd7ae66e6dd58a3a0dee22229e7 Author: Volker Hilsheimer Date: Tue Aug 4 16:35:17 2009 +0200 Remove IPC group. Only two classes, and those are explicitly listed in the real documentation about IPC in Qt. commit bbb02d8cc55c9595226f42fe5b617261584c6bdd Author: Volker Hilsheimer Date: Tue Aug 4 15:54:46 2009 +0200 Use the new \annotatedlist command, and make it a framework. commit ba3a0376acb44ae5cafc8bd3802bd425dcb663a5 Author: Volker Hilsheimer Date: Tue Aug 4 15:38:24 2009 +0200 Make \annotatedlist work. commit c80fb8d6a143c81700c2aefe7af1e83dd487dde4 Author: Volker Hilsheimer Date: Tue Aug 4 15:37:51 2009 +0200 These are API documentation, not architecture. commit 713744520bd35d510864ad48464575f1c8a35668 Author: Volker Hilsheimer Date: Tue Aug 4 15:10:25 2009 +0200 Frameworks and technologies used in Qt are really one thing. commit a86d4248c1e3c13f245c49f3f2d018ec4babc822 Author: Volker Hilsheimer Date: Tue Aug 4 15:00:35 2009 +0200 Move into correct groups and make the howto a walk-through. commit 7cc88f310e0dfa37d39026d67443f518531d7fe9 Author: Volker Hilsheimer Date: Tue Aug 4 12:50:58 2009 +0200 Architecture -> Frameworks and Technologies commit 4a3ba3f19d78c4df5343af951c761df47e22759a Author: Volker Hilsheimer Date: Tue Aug 4 12:50:41 2009 +0200 Some consolidation of the Tulip documentation. commit d3dab98b96d83ce408523f8ccb9363a09eed1f34 Author: Volker Hilsheimer Date: Tue Aug 4 12:01:10 2009 +0200 Start with "Frameworks and Technologies" vs "howtos and best practices". commit 37a8e364442e6234c6a83667eb64af1c79b38e9b Author: Volker Hilsheimer Date: Tue Aug 4 12:00:34 2009 +0200 Beautify. commit c86d844a79406d4b9fee67578efd67e27ce96b83 Author: Volker Hilsheimer Date: Tue Aug 4 00:04:40 2009 +0200 Fix some headers. commit 20b775d781d3b1d91164320807c21c8a6efcf011 Author: Volker Hilsheimer Date: Mon Aug 3 23:48:17 2009 +0200 Split the accessibility docu into a "compared to Qt 3" section, and move real information into the overview. commit 6846a1bccf7d212f7ee0471f992cfb16efb71c43 Author: Volker Hilsheimer Date: Mon Aug 3 23:47:37 2009 +0200 The gui-programming seems rather arbitrary and should go away. Some things fit into the desktop integration, which is probably more a howto. Focus is a concept in the widgets context, and application-wide techniques like accelerators should probably be part of the "window" docu. commit 8c7bc99e78a69751080de07618bf003bc227e2db Author: Volker Hilsheimer Date: Mon Aug 3 23:45:28 2009 +0200 Move "Getting Started" documentation into getting-started directory. commit 561cc3eafa20903243f3946ac4b7b724554c341c Author: Volker Hilsheimer Date: Mon Aug 3 19:06:16 2009 +0200 Group "getting started" documents into a walkthrough structure. commit 6d703807348923a068dea7360fb4456cbde071b6 Author: Volker Hilsheimer Date: Mon Aug 3 17:35:15 2009 +0200 Add screenshots for example-overview page. commit f7a47536305e157c16e8a863f145a2617606a2cc Author: Volker Hilsheimer Date: Sun Aug 2 16:57:04 2009 +0200 Link to the real documentation, not just to the modules overview. commit 92ce250ba206f4dde198637f1a30cd10768d9ae5 Author: Volker Hilsheimer Date: Sun Aug 2 16:56:41 2009 +0200 A new layout for the examples. Needs a bit of shuffeling around, and more screenshots and descriptive text for some categories. commit a5e2e2939b32dee0aceabe136aa4c13b12c88070 Author: Volker Hilsheimer Date: Sat Aug 1 22:39:27 2009 +0200 Cleanup the script-related groups a bit. commit ca469165a9f55ca6bd31e53d85d74883fe892ed4 Author: Volker Hilsheimer Date: Sat Aug 1 22:17:16 2009 +0200 Add QContiguousCache to the list of containers as a special case. commit a21292704bd12daf2495195b216424442e097220 Author: Volker Hilsheimer Date: Sat Aug 1 21:52:37 2009 +0200 Cleaning up groups of text- and string-related classes. Make a clear separation between classes that deal with string data (ie QString, QByteArray, QTextStream) and classes that are part of the "scribe" framework. Merge documentation from the Qt 4.0 introduction of Scribe into the richtext processing guide. commit 3854592806e23955f69613bdc1e2998d5d6f3a8a Author: Volker Hilsheimer Date: Sat Aug 1 20:50:06 2009 +0200 One group of thread-related classes should be enough. commit b8935bc0ec3d33b6a3fe7b3b220b5781ad79d68d Author: Volker Hilsheimer Date: Sat Aug 1 19:32:21 2009 +0200 Move documentation for classes into same directory as the respective header files (or implementation file, if one exists). This follows the Qt standard, and there is no particular reason why .qdoc files cannot live in src. Since there are a number of .cpp files that have only documentation it might also be an idea to rename the .qdoc files to .cpp and add them to the .pro-files to have them included in generated project files for easier access. commit b61cc5eaf2f2bf72cff209ab0f69fde48fb87471 Author: Volker Hilsheimer Date: Fri Jul 31 19:29:46 2009 +0200 Starting to tie together the widgets and layouts groups and documentation. commit 47fb0c6cf1dacdbfa07a59cf4dc703dd2c35eb8c Author: Volker Hilsheimer Date: Fri Jul 31 18:43:34 2009 +0200 This is all duplicate information that is better covered in the sql-programming guide. commit d3c70dd9ed84b4688cbabf30f6b906665b676b76 Author: Volker Hilsheimer Date: Fri Jul 31 18:37:53 2009 +0200 Consolidate style documentation. commit 1d8d30eee1e2fe9f8e77ce1462803921b2132ade Author: Volker Hilsheimer Date: Fri Jul 31 17:13:44 2009 +0200 Split plugin-documentation into two: writing plugins and deploying plugins. commit a329665353a78749b0d4fdd6e75403252d34f679 Author: Volker Hilsheimer Date: Fri Jul 31 14:19:47 2009 +0200 Some final module cleaning up. commit e3de6579d43cc9796b69188cfb9d3d415a91a770 Author: Volker Hilsheimer Date: Fri Jul 31 13:51:54 2009 +0200 Move remaining overview groups into one file. commit 7d783342f520f8376e561246268371d0b74a4e44 Author: Volker Hilsheimer Date: Fri Jul 31 13:51:34 2009 +0200 The "io" group should be about file access (be it local or networked). commit 961fcefb034fea89d1aab2bfed5acaabb65e8d34 Author: Volker Hilsheimer Date: Fri Jul 31 13:36:51 2009 +0200 Kill the "time" group. The "How to use timers in your application" documentation covers the usecase. commit c7bebf1a4c3e2da54ce6a5d649926d76bf65e41e Author: Volker Hilsheimer Date: Fri Jul 31 13:28:21 2009 +0200 Kill the group "misc". commit e414a8945cb938ccc6bd1bd8cd52adbfade096c2 Author: Volker Hilsheimer Date: Fri Jul 31 13:09:24 2009 +0200 Kill the "Environment" group. It was a random collection of classes, mostly ending up in there because of copy/paste (I suspect). commit 9236a04e7ac6dd3910f035d15b8ab23297fd5f24 Author: Volker Hilsheimer Date: Fri Jul 31 13:08:37 2009 +0200 More moving of files and content. commit 1ef3134bade2df33ff68c7c906cf20343abd86a5 Author: Volker Hilsheimer Date: Fri Jul 31 02:03:07 2009 +0200 Workaround qdoc being difficult. commit 49064b0570088fe749fc08c02c5ab6d23855089f Author: Volker Hilsheimer Date: Fri Jul 31 01:49:52 2009 +0200 Some more moving of files into meaningful directories. commit df4ced831cf9f49c638c231fa9f2754699a8a59d Author: Volker Hilsheimer Date: Fri Jul 31 01:41:14 2009 +0200 Separate module documentation from frameworks documentation. Module documentation will list the classes in each module, how to use the respective libraries and headerfiles from a build-system perspective and what the legal implications are when linking against those libraries. The documentation of frameworks lives now in the frameworks subdirectory, or in dedicated subdirectories for the key frameworks. commit f4ccabe1abb97f91f196dab1948fee6135c9fa6e Author: Volker Hilsheimer Date: Fri Jul 31 00:47:54 2009 +0200 Group files in subdirectories that would correspond to top level topics. commit ceb0110a364185b8b5d7bea3d3d1d54500035fcc Author: Volker Hilsheimer Date: Thu Jul 30 21:48:45 2009 +0200 Group files in subdirectories that would correspond to top level topics. commit 72a4dae65b25c9df400218252f1c68d59724ff75 Author: Volker Hilsheimer Date: Thu Jul 30 20:57:39 2009 +0200 Fix a few links. commit ecb79681417e8bc3d8e46065dc12146f4d4dfc5f Author: Volker Hilsheimer Date: Thu Jul 30 20:20:55 2009 +0200 Consolidate the two example documents into one page. commit d30d980055e7c531c9e73cdf9a1b220ce9691eef Author: Volker Hilsheimer Date: Thu Jul 30 19:25:16 2009 +0200 The QtAssistant module is obsolete, remove it. QAssistantClient is in the list of obsolete classes. commit 137ecd1ee70f0766fd94c6199d8a6b8217d020ca Author: Volker Hilsheimer Date: Thu Jul 30 18:56:14 2009 +0200 Get rid of \mainclass If we want to select a list of main classes, then we can use \ingroup for that, and document them coherently as part of the Fundamentals or a relevant framework. commit 042a7f21e68120e43b68444cbf3cfeca3aad4488 Author: Volker Hilsheimer Date: Thu Jul 30 18:23:55 2009 +0200 The new index page and respective style changes. commit 5245d784eb46287f8e1ae41addb2765eb19b0663 Author: Volker Hilsheimer Date: Thu Jul 30 17:05:46 2009 +0200 Deployment group is gone. commit 567d737a8d08f227133674ebfe2d161888862b8c Author: Volker Hilsheimer Date: Thu Jul 30 16:48:53 2009 +0200 All "lists of classes etc" are now in classes.qdoc... I hope. commit 0bb6074c0b38f07697e72a50a2ef60b561e718fe Author: Volker Hilsheimer Date: Thu Jul 30 16:47:20 2009 +0200 Cleaning up files documenting deployment. Text need to be reviewed and merged. commit 2df403da24a2959c02d0d845d1d4fac0c3aa38e0 Author: Thierry Bastian Date: Mon Aug 3 16:49:46 2009 +0200 fix warnings on mingw (gcc4.4) basically reordering members initialization in constructors or fixing singed/unsigned checks. Reviewed-by: Trustme commit e887c7705b8b7f218b3605eeefb316dea274fe27 Author: Richard Moe Gustavsen Date: Tue Aug 4 10:00:01 2009 +0200 Mac: Remove debug work output commit 62687960508b2855b48d64825b445e5738c44142 Author: Richard Moe Gustavsen Date: Tue Aug 4 09:45:47 2009 +0200 Modify imagewidget example so it works with new API commit 9c7aed68270b336ae9a309d9eb0107d49729c1f3 Author: Richard Moe Gustavsen Date: Tue Aug 4 09:43:14 2009 +0200 Add support for pan gesture on mac (carbon and cocoa) commit be5783878a977148b34dc64c464e951be312964e Author: Morten Sorvig Date: Tue Aug 4 09:47:05 2009 +0200 Remove the "preliminary support" warning for 10.6 Also make the "usupported on > 10.6" error a warning. No need to stop the build, the warning will be printed enough times. commit f6282eec434d073fef46d50ef141df6fa36033b9 Author: Morten Sorvig Date: Tue Aug 4 09:31:56 2009 +0200 Build on snow leopard. Don't error out when building qmake, just let it build a 64-bit binary (even for carbon) RebBy: Richard Moe Gustavsen commit abae82a26f4dec34635827acf0784058be638e31 Author: Morten Sorvig Date: Tue Aug 4 08:15:21 2009 +0200 Make Cocoa builds 64-bit by default on snow leopard. commit 4672e771c164503d998ccb6ca05cf7e7906fb031 Author: Jason McDonald Date: Tue Aug 4 15:40:15 2009 +1000 Fix incorrect license headers. Reviewed-by: Trust Me commit a3bd65e8eb0fd39e14539919cc9ced645c969883 Author: Bill King Date: Tue Aug 4 14:57:36 2009 +1000 Fixes failed queries when mysql auto-prepares Queries like "Show Index" etc, fail on mysql when automatically prepared due to a bug in several versions of mysql. Basically anything but a select query will fail. This fixes this by making the user explicitly prepare the query if they want to, and the blame then falls on them if they try and prepare a statement likely to fail. This fix also seems to result in a speedup for single-execution queries, possibly due to reduction in roundtrip communications. All autotests pass & behaviour conforms to documentation. Task-number: 252450, 246125 commit 4612596a6a945ab0199fe06727ff3ea350092ec1 Author: Jason McDonald Date: Tue Aug 4 14:49:14 2009 +1000 Fix obsolete license headers Reviewed-by: Trust Me commit c3bcc8b094341e0dc768ef5820ba359e2c23436a Author: Aaron Kennedy Date: Tue Aug 4 10:59:02 2009 +1000 Doc fixes Reviewed-by: TrustMe commit 1d60528ced1f6818a60889d672089bfe4d2290bb Author: Morten Sorvig Date: Mon Aug 3 15:57:44 2009 +0200 Fix spelling error. commit e99794c1200515f18ffdd0bec9c143db46e009a1 Merge: 199db81 d65f893 Author: Volker Hilsheimer Date: Tue Aug 4 09:24:14 2009 +0200 Merge branch 'master' into doccleanup commit 199db8104a680f91451cf2c93d2d41077b5605bb Author: Volker Hilsheimer Date: Tue Aug 4 00:04:40 2009 +0200 Fix some headers. commit e8f8193b951a9f9e4b6d309c44151c47b715e901 Author: Volker Hilsheimer Date: Mon Aug 3 23:48:17 2009 +0200 Split the accessibility docu into a "compared to Qt 3" section, and move real information into the overview. commit 8006ec36024e972be21e8397c2cc758a0e9b2ba0 Author: Volker Hilsheimer Date: Mon Aug 3 23:47:37 2009 +0200 The gui-programming seems rather arbitrary and should go away. Some things fit into the desktop integration, which is probably more a howto. Focus is a concept in the widgets context, and application-wide techniques like accelerators should probably be part of the "window" docu. commit 8dab96460280b8af6726905e8d5d24020930b882 Author: Volker Hilsheimer Date: Mon Aug 3 23:45:28 2009 +0200 Move "Getting Started" documentation into getting-started directory. commit 523fd47c29c24a865855d085a0036fc741203930 Merge: a1e50f6 2076f15 Author: Volker Hilsheimer Date: Mon Aug 3 19:10:51 2009 +0200 Merge branch 'master' into doccleanup commit a1e50f6619ff1a302dd1fefbcb6b0cd62a653e7d Author: Volker Hilsheimer Date: Mon Aug 3 19:06:16 2009 +0200 Group "getting started" documents into a walkthrough structure. commit e393b4f458263cb2f011cc5e5e67cdcc48610ea9 Author: Volker Hilsheimer Date: Mon Aug 3 17:35:15 2009 +0200 Add screenshots for example-overview page. commit 8c84f307f73ab7b77a91e61ed18fdc685afebcc5 Merge: a16033a 34e272a Author: Volker Hilsheimer Date: Mon Aug 3 11:03:41 2009 +0200 Merge branch 'master' into doccleanup commit a16033a287afe2f494401e24f02f046ec98d944c Author: Volker Hilsheimer Date: Sun Aug 2 16:57:04 2009 +0200 Link to the real documentation, not just to the modules overview. commit 6c4ed0361c860e738b9344dfb191f55d35b3309f Author: Volker Hilsheimer Date: Sun Aug 2 16:56:41 2009 +0200 A new layout for the examples. Needs a bit of shuffeling around, and more screenshots and descriptive text for some categories. commit 2dde2faa8f6e86acf738a808412c5e3c21c44658 Author: Volker Hilsheimer Date: Sat Aug 1 22:39:27 2009 +0200 Cleanup the script-related groups a bit. commit a66227d0bed87c633a22a4d155f6a7f0061fc34e Author: Volker Hilsheimer Date: Sat Aug 1 22:17:16 2009 +0200 Add QContiguousCache to the list of containers as a special case. commit b22133eef28566f1c3c5d57aa0e8272af26da86a Author: Volker Hilsheimer Date: Sat Aug 1 21:52:37 2009 +0200 Cleaning up groups of text- and string-related classes. Make a clear separation between classes that deal with string data (ie QString, QByteArray, QTextStream) and classes that are part of the "scribe" framework. Merge documentation from the Qt 4.0 introduction of Scribe into the richtext processing guide. commit b30ba739308905b6c06987cec47d4de1e5d172de Author: Volker Hilsheimer Date: Sat Aug 1 20:50:06 2009 +0200 One group of thread-related classes should be enough. commit a2511650577126026f98cb7416c159498f6f2db5 Author: Volker Hilsheimer Date: Sat Aug 1 19:32:21 2009 +0200 Move documentation for classes into same directory as the respective header files (or implementation file, if one exists). This follows the Qt standard, and there is no particular reason why .qdoc files cannot live in src. Since there are a number of .cpp files that have only documentation it might also be an idea to rename the .qdoc files to .cpp and add them to the .pro-files to have them included in generated project files for easier access. commit f333ad71384cf42c20219a55d9dfa1e29a8c263e Merge: bad9ba5 5aed3db Author: Volker Hilsheimer Date: Sat Aug 1 12:04:55 2009 +0200 Merge branch 'master' into doccleanup commit bad9ba5468333be2f08da7f28950c980bc63c787 Merge: 49f38b7 c57ed13 Author: Volker Hilsheimer Date: Fri Jul 31 19:31:04 2009 +0200 Merge branch 'master' into doccleanup commit 49f38b7afe3205eedccf655c0ad749d685cb3d52 Author: Volker Hilsheimer Date: Fri Jul 31 19:29:46 2009 +0200 Starting to tie together the widgets and layouts groups and documentation. commit e6c4b8316b7c90b19815c0008a282983012c68b3 Author: Volker Hilsheimer Date: Fri Jul 31 18:43:34 2009 +0200 This is all duplicate information that is better covered in the sql-programming guide. commit 620620ae969bed86d970519bead45762bd39ede1 Author: Volker Hilsheimer Date: Fri Jul 31 18:37:53 2009 +0200 Consolidate style documentation. commit 01c78ff78888d3ccb50189206b9bcacaf13f5c80 Author: Volker Hilsheimer Date: Fri Jul 31 17:13:44 2009 +0200 Split plugin-documentation into two: writing plugins and deploying plugins. commit a21f510c982dce06ac1769e61e93574f90cc48c4 Merge: da93c4c c6cdfcb Author: Volker Hilsheimer Date: Fri Jul 31 16:04:51 2009 +0200 Merge branch 'master' into doccleanup commit da93c4ccc25dd189dfb9b71bda28bd1e3a7230c1 Author: Volker Hilsheimer Date: Fri Jul 31 14:19:47 2009 +0200 Some final module cleaning up. commit 9eb0815bbd01b7e30877110b53aa6f82b8e9221d Author: Volker Hilsheimer Date: Fri Jul 31 13:51:54 2009 +0200 Move remaining overview groups into one file. commit 65d4c4145386a409aeb1372ae5adc6f3e71e444b Author: Volker Hilsheimer Date: Fri Jul 31 13:51:34 2009 +0200 The "io" group should be about file access (be it local or networked). commit 1a3de3a7add6d9e7653e46b57b00852845384a42 Author: Volker Hilsheimer Date: Fri Jul 31 13:36:51 2009 +0200 Kill the "time" group. The "How to use timers in your application" documentation covers the usecase. commit dbadf1c060e051dbac7f5c72528ef6a3125d5ba3 Author: Volker Hilsheimer Date: Fri Jul 31 13:28:21 2009 +0200 Kill the group "misc". commit 7b7484b37b074d52af5c4ff9b138087a75965508 Author: Volker Hilsheimer Date: Fri Jul 31 13:09:24 2009 +0200 Kill the "Environment" group. It was a random collection of classes, mostly ending up in there because of copy/paste (I suspect). commit b5271d81e7da6666d339041d028a0ae6c8ed75c4 Author: Volker Hilsheimer Date: Fri Jul 31 13:08:37 2009 +0200 More moving of files and content. commit 96a707d25342c273cdd7629fc1e24b0ead4118de Merge: 4ffe572 18fbfdf Author: Volker Hilsheimer Date: Fri Jul 31 11:08:11 2009 +0200 Merge branch 'master' into doccleanup commit 4ffe572a954e99d604c1360fc55db25e8586436c Author: Volker Hilsheimer Date: Fri Jul 31 02:03:07 2009 +0200 Workaround qdoc being difficult. commit 7f0e965c7cf613782e8189069444a4b549f0c11a Author: Volker Hilsheimer Date: Fri Jul 31 01:49:52 2009 +0200 Some more moving of files into meaningful directories. commit b0d67674469e57b29e60110888352ae955adcdd8 Author: Volker Hilsheimer Date: Fri Jul 31 01:41:14 2009 +0200 Separate module documentation from frameworks documentation. Module documentation will list the classes in each module, how to use the respective libraries and headerfiles from a build-system perspective and what the legal implications are when linking against those libraries. The documentation of frameworks lives now in the frameworks subdirectory, or in dedicated subdirectories for the key frameworks. commit 45240a9c0eba9e42e6e441a55a407173a81a7344 Author: Volker Hilsheimer Date: Fri Jul 31 00:47:54 2009 +0200 Group files in subdirectories that would correspond to top level topics. commit 896507f2f4fdc541fc436cf901a2beb72d35f6aa Author: Volker Hilsheimer Date: Thu Jul 30 21:48:45 2009 +0200 Group files in subdirectories that would correspond to top level topics. commit 37eb554f75d8b1d9d76993f6fcf632933c9616a2 Author: Volker Hilsheimer Date: Thu Jul 30 20:57:39 2009 +0200 Fix a few links. commit 74027c3568c1bdbb9960d203266f4ccc5e89c05c Author: Volker Hilsheimer Date: Thu Jul 30 20:20:55 2009 +0200 Consolidate the two example documents into one page. commit cfc0fd3df050cf6c0e3229d22adfbff35aed46af Author: Volker Hilsheimer Date: Thu Jul 30 19:25:16 2009 +0200 The QtAssistant module is obsolete, remove it. QAssistantClient is in the list of obsolete classes. commit 0f86c7a176fc920669ca8a880afa141434f37767 Author: Volker Hilsheimer Date: Thu Jul 30 18:56:14 2009 +0200 Get rid of \mainclass If we want to select a list of main classes, then we can use \ingroup for that, and document them coherently as part of the Fundamentals or a relevant framework. commit c4dfbc6bf58ef741fdab01538e75e9472e8370bf Author: Volker Hilsheimer Date: Thu Jul 30 18:23:55 2009 +0200 The new index page and respective style changes. commit a3e4eb6712e24a4d6156c340ee98671887a2b2fa Author: Volker Hilsheimer Date: Thu Jul 30 17:05:46 2009 +0200 Deployment group is gone. commit f03ee6192450db977bc2e4b07ffc613314b63a80 Author: Volker Hilsheimer Date: Thu Jul 30 16:48:53 2009 +0200 All "lists of classes etc" are now in classes.qdoc... I hope. commit c5fb9a4b5208498454812d27578ac62ae23652a4 Author: Volker Hilsheimer Date: Thu Jul 30 16:47:20 2009 +0200 Cleaning up files documenting deployment. Text need to be reviewed and merged. --- doc/src/accelerators.qdoc | 137 - doc/src/accessible.qdoc | 600 --- doc/src/activeqt-dumpcpp.qdoc | 143 - doc/src/activeqt-dumpdoc.qdoc | 83 - doc/src/activeqt-idc.qdoc | 82 - doc/src/activeqt-testcon.qdoc | 77 - doc/src/activeqt.qdoc | 88 - doc/src/animation.qdoc | 364 -- doc/src/appicon.qdoc | 226 - doc/src/assistant-manual.qdoc | 810 ---- doc/src/atomic-operations.qdoc | 89 - doc/src/bughowto.qdoc | 1 - doc/src/classes.qdoc | 31 +- doc/src/classes/exportedfunctions.qdoc | 139 + doc/src/classes/phonon-namespace.qdoc | 54 + doc/src/classes/q3asciicache.qdoc | 465 --- doc/src/classes/q3asciidict.qdoc | 416 -- doc/src/classes/q3cache.qdoc | 461 --- doc/src/classes/q3dict.qdoc | 446 -- doc/src/classes/q3intcache.qdoc | 446 -- doc/src/classes/q3intdict.qdoc | 390 -- doc/src/classes/q3memarray.qdoc | 523 --- doc/src/classes/q3popupmenu.qdoc | 76 - doc/src/classes/q3ptrdict.qdoc | 388 -- doc/src/classes/q3ptrlist.qdoc | 1157 ------ doc/src/classes/q3ptrqueue.qdoc | 230 -- doc/src/classes/q3ptrstack.qdoc | 217 - doc/src/classes/q3ptrvector.qdoc | 427 -- doc/src/classes/q3sqlfieldinfo.qdoc | 234 -- doc/src/classes/q3sqlrecordinfo.qdoc | 89 - doc/src/classes/q3valuelist.qdoc | 569 --- doc/src/classes/q3valuestack.qdoc | 149 - doc/src/classes/q3valuevector.qdoc | 274 -- doc/src/classes/qalgorithms.qdoc | 651 --- doc/src/classes/qcache.qdoc | 244 -- doc/src/classes/qcolormap.qdoc | 152 - doc/src/classes/qdesktopwidget.qdoc | 266 -- doc/src/classes/qiterator.qdoc | 1431 ------- doc/src/classes/qmacstyle.qdoc | 261 -- doc/src/classes/qnamespace.qdoc | 2756 ------------- doc/src/classes/qpagesetupdialog.qdoc | 84 - doc/src/classes/qpaintdevice.qdoc | 289 -- doc/src/classes/qpair.qdoc | 229 -- doc/src/classes/qplugin.qdoc | 135 - doc/src/classes/qprintdialog.qdoc | 72 - doc/src/classes/qprinterinfo.qdoc | 137 - doc/src/classes/qset.qdoc | 953 ----- doc/src/classes/qsignalspy.qdoc | 98 - doc/src/classes/qsizepolicy.qdoc | 522 --- doc/src/classes/qtdesigner-api.qdoc | 1413 ------- doc/src/classes/qtendian.qdoc | 168 - doc/src/classes/qtestevent.qdoc | 191 - doc/src/classes/qvarlengtharray.qdoc | 274 -- doc/src/classes/qwaitcondition.qdoc | 188 - doc/src/codecs.qdoc | 534 --- doc/src/compiler-notes.qdoc | 278 -- doc/src/containers.qdoc | 775 ---- doc/src/coordsys.qdoc | 486 --- doc/src/custom-types.qdoc | 178 - doc/src/datastreamformat.qdoc | 376 -- doc/src/debug.qdoc | 256 -- doc/src/demos.qdoc | 151 - doc/src/demos/qtdemo.qdoc | 67 + doc/src/deployment.qdoc | 1478 ------- doc/src/deployment/deployment-plugins.qdoc | 236 ++ doc/src/deployment/deployment.qdoc | 1464 +++++++ doc/src/deployment/qt-conf.qdoc | 135 + doc/src/deployment/qtconfig.qdoc | 56 + doc/src/designer-manual.qdoc | 2836 ------------- doc/src/desktop-integration.qdoc | 90 - doc/src/developing-on-mac.qdoc | 269 -- doc/src/development/activeqt-dumpcpp.qdoc | 143 + doc/src/development/activeqt-dumpdoc.qdoc | 83 + doc/src/development/activeqt-idc.qdoc | 82 + doc/src/development/activeqt-testcon.qdoc | 77 + doc/src/development/assistant-manual.qdoc | 810 ++++ doc/src/development/debug.qdoc | 243 ++ doc/src/development/designer-manual.qdoc | 2836 +++++++++++++ doc/src/development/developing-on-mac.qdoc | 269 ++ doc/src/development/developing-with-qt.qdoc | 74 + doc/src/development/moc.qdoc | 335 ++ doc/src/development/qmake-manual.qdoc | 4320 +++++++++++++++++++ doc/src/development/qmsdev.qdoc | 166 + doc/src/development/qtestlib.qdoc | 778 ++++ doc/src/development/rcc.qdoc | 95 + doc/src/development/tools-list.qdoc | 84 + doc/src/development/uic.qdoc | 88 + doc/src/distributingqt.qdoc | 154 - doc/src/dnd.qdoc | 546 --- doc/src/ecmascript.qdoc | 313 -- doc/src/emb-accel.qdoc | 143 - doc/src/emb-charinput.qdoc | 164 - doc/src/emb-crosscompiling.qdoc | 191 - doc/src/emb-deployment.qdoc | 111 - doc/src/emb-differences.qdoc | 72 - doc/src/emb-envvars.qdoc | 168 - doc/src/emb-features.qdoc | 147 - doc/src/emb-fonts.qdoc | 201 - doc/src/emb-framebuffer-howto.qdoc | 53 - doc/src/emb-install.qdoc | 197 - doc/src/emb-kmap2qmap.qdoc | 84 - doc/src/emb-makeqpf.qdoc | 53 - doc/src/emb-performance.qdoc | 152 - doc/src/emb-pointer.qdoc | 209 - doc/src/emb-porting.qdoc | 193 - doc/src/emb-qvfb.qdoc | 296 -- doc/src/emb-running.qdoc | 210 - doc/src/emb-vnc.qdoc | 141 - doc/src/eventsandfilters.qdoc | 221 - doc/src/examples-overview.qdoc | 367 -- doc/src/examples.qdoc | 437 -- doc/src/examples/application.qdoc | 2 +- doc/src/examples/drilldown.qdoc | 4 +- doc/src/examples/qtscriptcalculator.qdoc | 1 - doc/src/examples/trafficinfo.qdoc | 2 +- doc/src/exportedfunctions.qdoc | 139 - doc/src/files-and-resources/datastreamformat.qdoc | 363 ++ doc/src/files-and-resources/resources.qdoc | 203 + doc/src/focus.qdoc | 213 - doc/src/frameworks-technologies/accessible.qdoc | 624 +++ .../activeqt-container.qdoc | 218 + .../frameworks-technologies/activeqt-server.qdoc | 856 ++++ doc/src/frameworks-technologies/activeqt.qdoc | 100 + doc/src/frameworks-technologies/animation.qdoc | 377 ++ doc/src/frameworks-technologies/containers.qdoc | 810 ++++ doc/src/frameworks-technologies/dbus-adaptors.qdoc | 494 +++ doc/src/frameworks-technologies/dbus-intro.qdoc | 229 ++ .../desktop-integration.qdoc | 111 + doc/src/frameworks-technologies/dnd.qdoc | 449 ++ .../frameworks-technologies/eventsandfilters.qdoc | 235 ++ doc/src/frameworks-technologies/gestures.qdoc | 170 + doc/src/frameworks-technologies/graphicsview.qdoc | 554 +++ .../frameworks-technologies/implicit-sharing.qdoc | 152 + doc/src/frameworks-technologies/ipc.qdoc | 89 + .../model-view-programming.qdoc | 2498 +++++++++++ doc/src/frameworks-technologies/phonon.qdoc | 558 +++ doc/src/frameworks-technologies/plugins-howto.qdoc | 311 ++ doc/src/frameworks-technologies/qthelp.qdoc | 382 ++ doc/src/frameworks-technologies/qundo.qdoc | 113 + doc/src/frameworks-technologies/richtext.qdoc | 1226 ++++++ doc/src/frameworks-technologies/statemachine.qdoc | 548 +++ doc/src/frameworks-technologies/templates.qdoc | 229 ++ doc/src/frameworks-technologies/threads.qdoc | 700 ++++ doc/src/frameworks-technologies/unicode.qdoc | 182 + doc/src/gallery-cde.qdoc | 392 -- doc/src/gallery-cleanlooks.qdoc | 392 -- doc/src/gallery-gtk.qdoc | 358 -- doc/src/gallery-macintosh.qdoc | 392 -- doc/src/gallery-motif.qdoc | 392 -- doc/src/gallery-plastique.qdoc | 392 -- doc/src/gallery-windows.qdoc | 392 -- doc/src/gallery-windowsvista.qdoc | 392 -- doc/src/gallery-windowsxp.qdoc | 392 -- doc/src/gallery.qdoc | 151 - doc/src/geometry.qdoc | 150 - doc/src/gestures.qdoc | 170 - doc/src/getting-started/demos.qdoc | 166 + doc/src/getting-started/examples.qdoc | 1108 +++++ doc/src/getting-started/how-to-learn-qt.qdoc | 118 + doc/src/getting-started/installation.qdoc | 806 ++++ doc/src/getting-started/known-issues.qdoc | 143 + doc/src/getting-started/tutorials.qdoc | 103 + doc/src/graphicsview.qdoc | 543 --- doc/src/groups.qdoc | 487 --- doc/src/guibooks.qdoc | 121 - doc/src/how-to-learn-qt.qdoc | 115 - doc/src/howtos/accelerators.qdoc | 138 + doc/src/howtos/appicon.qdoc | 215 + doc/src/howtos/custom-types.qdoc | 179 + doc/src/howtos/guibooks.qdoc | 120 + doc/src/howtos/openvg.qdoc | 322 ++ doc/src/howtos/qtdesigner.qdoc | 144 + doc/src/howtos/restoring-geometry.qdoc | 87 + doc/src/howtos/session.qdoc | 178 + doc/src/howtos/sharedlibrary.qdoc | 176 + doc/src/howtos/timers.qdoc | 137 + doc/src/howtos/unix-signal-handlers.qdoc | 105 + doc/src/i18n.qdoc | 508 --- doc/src/images/activeqt-examples.png | Bin 0 -> 6671 bytes doc/src/images/animation-examples.png | Bin 0 -> 28060 bytes doc/src/images/ipc-examples.png | Bin 0 -> 7727 bytes doc/src/images/qq-thumbnail.png | Bin 0 -> 27022 bytes doc/src/images/statemachine-examples.png | Bin 0 -> 3326 bytes doc/src/images/webkit-examples.png | Bin 26874 -> 19323 bytes doc/src/implicit-sharing.qdoc | 144 - doc/src/index.qdoc | 195 +- doc/src/installation.qdoc | 794 ---- doc/src/internationalization/i18n.qdoc | 515 +++ doc/src/internationalization/linguist-manual.qdoc | 1512 +++++++ doc/src/introtodbus.qdoc | 229 -- doc/src/ipc.qdoc | 91 - doc/src/known-issues.qdoc | 143 - doc/src/layout.qdoc | 384 -- doc/src/legal/editions.qdoc | 12 - doc/src/legal/licenses.qdoc | 1 - doc/src/linguist-manual.qdoc | 1512 ------- doc/src/mac-differences.qdoc | 339 -- doc/src/metaobjects.qdoc | 149 - doc/src/moc.qdoc | 336 -- doc/src/model-view-programming.qdoc | 2485 ----------- doc/src/modules.qdoc | 952 ++++- doc/src/network-programming/qtnetwork.qdoc | 330 ++ doc/src/network-programming/ssl.qdoc | 67 + doc/src/object.qdoc | 132 - doc/src/objectmodel/metaobjects.qdoc | 148 + doc/src/objectmodel/object.qdoc | 139 + doc/src/objectmodel/objecttrees.qdoc | 115 + doc/src/objectmodel/properties.qdoc | 278 ++ doc/src/objectmodel/signalsandslots.qdoc | 421 ++ doc/src/objecttrees.qdoc | 117 - doc/src/overviews.qdoc | 25 + doc/src/painting-and-printing/coordsys.qdoc | 477 +++ doc/src/painting-and-printing/paintsystem.qdoc | 570 +++ doc/src/painting-and-printing/printing.qdoc | 191 + doc/src/paintsystem.qdoc | 483 --- doc/src/phonon.qdoc | 643 --- doc/src/platform-notes-rtos.qdoc | 220 - doc/src/platform-notes.qdoc | 401 -- doc/src/platforms/atomic-operations.qdoc | 90 + doc/src/platforms/compiler-notes.qdoc | 278 ++ doc/src/platforms/emb-accel.qdoc | 143 + doc/src/platforms/emb-architecture.qdoc | 338 ++ doc/src/platforms/emb-charinput.qdoc | 164 + doc/src/platforms/emb-crosscompiling.qdoc | 191 + doc/src/platforms/emb-deployment.qdoc | 111 + doc/src/platforms/emb-differences.qdoc | 72 + doc/src/platforms/emb-displaymanagement.qdoc | 205 + doc/src/platforms/emb-envvars.qdoc | 168 + doc/src/platforms/emb-features.qdoc | 147 + doc/src/platforms/emb-fonts.qdoc | 201 + doc/src/platforms/emb-framebuffer-howto.qdoc | 53 + doc/src/platforms/emb-install.qdoc | 197 + doc/src/platforms/emb-kmap2qmap.qdoc | 84 + doc/src/platforms/emb-makeqpf.qdoc | 53 + doc/src/platforms/emb-opengl.qdoc | 227 + doc/src/platforms/emb-performance.qdoc | 152 + doc/src/platforms/emb-pointer.qdoc | 209 + doc/src/platforms/emb-porting.qdoc | 193 + doc/src/platforms/emb-qvfb.qdoc | 296 ++ doc/src/platforms/emb-running.qdoc | 210 + doc/src/platforms/emb-vnc.qdoc | 141 + doc/src/platforms/mac-differences.qdoc | 339 ++ doc/src/platforms/platform-notes-rtos.qdoc | 220 + doc/src/platforms/platform-notes.qdoc | 412 ++ doc/src/platforms/qt-embedded-linux.qdoc | 126 + doc/src/platforms/qt-embedded.qdoc | 76 + doc/src/platforms/qtmac-as-native.qdoc | 202 + doc/src/platforms/supported-platforms.qdoc | 141 + doc/src/platforms/wince-customization.qdoc | 264 ++ doc/src/platforms/wince-introduction.qdoc | 142 + doc/src/platforms/wince-opengl.qdoc | 98 + doc/src/platforms/winsystem.qdoc | 98 + doc/src/platforms/x11overlays.qdoc | 98 + doc/src/plugins-howto.qdoc | 470 --- doc/src/porting-qsa.qdoc | 475 --- doc/src/porting/porting-qsa.qdoc | 475 +++ doc/src/porting/porting4-canvas.qdoc | 702 ++++ doc/src/porting/porting4-designer.qdoc | 349 ++ doc/src/porting/porting4-dnd.qdoc | 152 + doc/src/porting/porting4-modifiedvirtual.qdocinc | 63 + .../porting/porting4-obsoletedmechanism.qdocinc | 3 + doc/src/porting/porting4-overview.qdoc | 373 ++ doc/src/porting/porting4-removedenumvalues.qdocinc | 6 + doc/src/porting/porting4-removedtypes.qdocinc | 1 + .../porting4-removedvariantfunctions.qdocinc | 16 + doc/src/porting/porting4-removedvirtual.qdocinc | 605 +++ doc/src/porting/porting4-renamedclasses.qdocinc | 3 + doc/src/porting/porting4-renamedenumvalues.qdocinc | 234 ++ doc/src/porting/porting4-renamedfunctions.qdocinc | 6 + doc/src/porting/porting4-renamedstatic.qdocinc | 3 + doc/src/porting/porting4-renamedtypes.qdocinc | 26 + doc/src/porting/porting4.qdoc | 4244 +++++++++++++++++++ doc/src/porting/qt3to4.qdoc | 179 + doc/src/porting/qt4-accessibility.qdoc | 162 + doc/src/porting/qt4-arthur.qdoc | 336 ++ doc/src/porting/qt4-designer.qdoc | 298 ++ doc/src/porting/qt4-interview.qdoc | 293 ++ doc/src/porting/qt4-mainwindow.qdoc | 250 ++ doc/src/porting/qt4-network.qdoc | 243 ++ doc/src/porting/qt4-scribe.qdoc | 257 ++ doc/src/porting/qt4-sql.qdoc | 175 + doc/src/porting/qt4-styles.qdoc | 157 + doc/src/porting/qt4-threads.qdoc | 101 + doc/src/porting/qt4-tulip.qdoc | 200 + doc/src/porting4-canvas.qdoc | 703 ---- doc/src/porting4-designer.qdoc | 349 -- doc/src/porting4-modifiedvirtual.qdocinc | 63 - doc/src/porting4-obsoletedmechanism.qdocinc | 3 - doc/src/porting4-overview.qdoc | 373 -- doc/src/porting4-removedenumvalues.qdocinc | 6 - doc/src/porting4-removedtypes.qdocinc | 1 - doc/src/porting4-removedvariantfunctions.qdocinc | 16 - doc/src/porting4-removedvirtual.qdocinc | 605 --- doc/src/porting4-renamedclasses.qdocinc | 3 - doc/src/porting4-renamedenumvalues.qdocinc | 234 -- doc/src/porting4-renamedfunctions.qdocinc | 6 - doc/src/porting4-renamedstatic.qdocinc | 3 - doc/src/porting4-renamedtypes.qdocinc | 26 - doc/src/porting4.qdoc | 4231 ------------------- doc/src/printing.qdoc | 175 - doc/src/properties.qdoc | 279 -- doc/src/qaxcontainer.qdoc | 260 -- doc/src/qaxserver.qdoc | 898 ---- doc/src/qdbusadaptors.qdoc | 518 --- doc/src/qmake-manual.qdoc | 4323 -------------------- doc/src/qmsdev.qdoc | 137 - doc/src/qsql.qdoc | 139 - doc/src/qsqldatatype-table.qdoc | 581 --- doc/src/qt-conf.qdoc | 136 - doc/src/qt-embedded.qdoc | 76 - doc/src/qt-webpages.qdoc | 245 ++ doc/src/qt3support.qdoc | 81 - doc/src/qt3to4.qdoc | 179 - doc/src/qt4-accessibility.qdoc | 163 - doc/src/qt4-arthur.qdoc | 336 -- doc/src/qt4-designer.qdoc | 298 -- doc/src/qt4-interview.qdoc | 293 -- doc/src/qt4-intro.qdoc | 6 +- doc/src/qt4-mainwindow.qdoc | 250 -- doc/src/qt4-network.qdoc | 243 -- doc/src/qt4-scribe.qdoc | 257 -- doc/src/qt4-sql.qdoc | 175 - doc/src/qt4-styles.qdoc | 157 - doc/src/qt4-threads.qdoc | 101 - doc/src/qt4-tulip.qdoc | 200 - doc/src/qtassistant.qdoc | 54 - doc/src/qtconfig.qdoc | 56 - doc/src/qtcore.qdoc | 60 - doc/src/qtdbus.qdoc | 124 - doc/src/qtdemo.qdoc | 67 - doc/src/qtdesigner.qdoc | 168 - doc/src/qtestlib.qdoc | 779 ---- doc/src/qtgui.qdoc | 59 - doc/src/qthelp.qdoc | 410 -- doc/src/qtmac-as-native.qdoc | 202 - doc/src/qtmain.qdoc | 93 - doc/src/qtnetwork.qdoc | 344 -- doc/src/qtopengl.qdoc | 163 - doc/src/qtopenvg.qdoc | 324 -- doc/src/qtopiacore-architecture.qdoc | 338 -- doc/src/qtopiacore-displaymanagement.qdoc | 205 - doc/src/qtopiacore-opengl.qdoc | 227 - doc/src/qtopiacore.qdoc | 114 - doc/src/qtscript.qdoc | 1934 --------- doc/src/qtscriptdebugger-manual.qdoc | 437 -- doc/src/qtscriptextensions.qdoc | 126 - doc/src/qtscripttools.qdoc | 72 - doc/src/qtsql.qdoc | 571 --- doc/src/qtsvg.qdoc | 135 - doc/src/qttest.qdoc | 70 - doc/src/qtuiloader.qdoc | 82 - doc/src/qtxml.qdoc | 615 --- doc/src/qtxmlpatterns.qdoc | 968 ----- doc/src/qundo.qdoc | 113 - doc/src/rcc.qdoc | 96 - doc/src/resources.qdoc | 192 - doc/src/richtext.qdoc | 1076 ----- doc/src/scripting/ecmascript.qdoc | 312 ++ doc/src/scripting/qtscriptdebugger-manual.qdoc | 436 ++ doc/src/scripting/qtscriptextensions.qdoc | 115 + doc/src/scripting/scripting.qdoc | 1929 +++++++++ doc/src/session.qdoc | 177 - doc/src/sharedlibrary.qdoc | 186 - doc/src/signalsandslots.qdoc | 422 -- doc/src/snippets/code/doc_src_qtmultimedia.qdoc | 8 + doc/src/sql-driver.qdoc | 762 ---- doc/src/sql-programming/qsqldatatype-table.qdoc | 583 +++ doc/src/sql-programming/sql-driver.qdoc | 762 ++++ doc/src/sql-programming/sql-programming.qdoc | 614 +++ doc/src/statemachine.qdoc | 536 --- doc/src/styles.qdoc | 2059 ---------- doc/src/stylesheet.qdoc | 3960 ------------------ doc/src/supported-platforms.qdoc | 141 - doc/src/templates.qdoc | 230 -- doc/src/threads.qdoc | 616 --- doc/src/timers.qdoc | 136 - doc/src/tools-list.qdoc | 85 - doc/src/topics.qdoc | 290 -- doc/src/trolltech-webpages.qdoc | 245 -- doc/src/tutorials/addressbook-fr.qdoc | 3 +- doc/src/tutorials/addressbook.qdoc | 3 +- doc/src/tutorials/widgets-tutorial.qdoc | 15 +- doc/src/uic.qdoc | 89 - doc/src/unicode.qdoc | 161 - doc/src/unix-signal-handlers.qdoc | 103 - doc/src/widgets-and-layouts/focus.qdoc | 200 + doc/src/widgets-and-layouts/gallery-cde.qdoc | 392 ++ .../widgets-and-layouts/gallery-cleanlooks.qdoc | 392 ++ doc/src/widgets-and-layouts/gallery-gtk.qdoc | 358 ++ doc/src/widgets-and-layouts/gallery-macintosh.qdoc | 392 ++ doc/src/widgets-and-layouts/gallery-motif.qdoc | 392 ++ doc/src/widgets-and-layouts/gallery-plastique.qdoc | 392 ++ doc/src/widgets-and-layouts/gallery-windows.qdoc | 392 ++ .../widgets-and-layouts/gallery-windowsvista.qdoc | 392 ++ doc/src/widgets-and-layouts/gallery-windowsxp.qdoc | 392 ++ doc/src/widgets-and-layouts/gallery.qdoc | 150 + doc/src/widgets-and-layouts/layout.qdoc | 396 ++ doc/src/widgets-and-layouts/styles.qdoc | 2123 ++++++++++ doc/src/widgets-and-layouts/stylesheet.qdoc | 3962 ++++++++++++++++++ doc/src/widgets-and-layouts/widgets.qdoc | 187 + doc/src/wince-customization.qdoc | 264 -- doc/src/wince-introduction.qdoc | 110 - doc/src/wince-opengl.qdoc | 98 - doc/src/windows-and-dialogs/dialogs.qdoc | 76 + doc/src/windows-and-dialogs/mainwindow.qdoc | 279 ++ doc/src/winsystem.qdoc | 99 - doc/src/xml-processing/xml-patterns.qdoc | 904 ++++ doc/src/xml-processing/xml-processing.qdoc | 631 +++ doc/src/xml-processing/xquery-introduction.qdoc | 1023 +++++ doc/src/xquery-introduction.qdoc | 1024 ----- src/3rdparty/easing/legal.qdoc | 2 +- src/3rdparty/webkit/WebKit/qt/Api/qwebdatabase.cpp | 2 + src/3rdparty/webkit/WebKit/qt/Api/qwebelement.cpp | 2 +- src/3rdparty/webkit/WebKit/qt/Api/qwebframe.cpp | 4 + src/3rdparty/webkit/WebKit/qt/Api/qwebhistory.cpp | 4 + .../webkit/WebKit/qt/Api/qwebhistoryinterface.cpp | 2 + src/3rdparty/webkit/WebKit/qt/Api/qwebpage.cpp | 8 + .../webkit/WebKit/qt/Api/qwebpluginfactory.cpp | 10 + .../webkit/WebKit/qt/Api/qwebsecurityorigin.cpp | 2 + src/3rdparty/webkit/WebKit/qt/Api/qwebsettings.cpp | 2 + src/3rdparty/webkit/WebKit/qt/Api/qwebview.cpp | 2 + src/3rdparty/webkit/WebKit/qt/docs/qtwebkit.qdoc | 110 +- src/corelib/animation/qpropertyanimation.cpp | 2 +- src/corelib/codecs/codecs.qdoc | 546 +++ src/corelib/concurrent/qfuture.cpp | 6 +- src/corelib/concurrent/qfuturesynchronizer.cpp | 6 +- src/corelib/concurrent/qfuturewatcher.cpp | 4 +- src/corelib/concurrent/qrunnable.cpp | 2 + src/corelib/concurrent/qtconcurrentfilter.cpp | 4 +- src/corelib/concurrent/qtconcurrentmap.cpp | 10 +- src/corelib/concurrent/qtconcurrentrun.cpp | 6 +- src/corelib/concurrent/qthreadpool.cpp | 4 +- src/corelib/global/qendian.qdoc | 168 + src/corelib/global/qglobal.cpp | 4 +- src/corelib/global/qlibraryinfo.cpp | 3 - src/corelib/global/qnamespace.qdoc | 2754 +++++++++++++ src/corelib/io/qdatastream.cpp | 2 +- src/corelib/io/qdebug.cpp | 3 +- src/corelib/io/qdir.cpp | 2 +- src/corelib/io/qfile.cpp | 2 +- src/corelib/io/qprocess.cpp | 3 +- src/corelib/io/qresource.cpp | 2 +- src/corelib/io/qsettings.cpp | 3 +- src/corelib/io/qtemporaryfile.cpp | 2 +- src/corelib/io/qtextstream.cpp | 6 +- src/corelib/io/qurl.cpp | 4 +- src/corelib/kernel/qabstracteventdispatcher.cpp | 1 - src/corelib/kernel/qabstractitemmodel.cpp | 4 +- src/corelib/kernel/qbasictimer.cpp | 1 - src/corelib/kernel/qcoreapplication.cpp | 3 - src/corelib/kernel/qcoreevent.cpp | 1 - src/corelib/kernel/qobject.cpp | 2 +- src/corelib/kernel/qpointer.cpp | 2 +- src/corelib/kernel/qsharedmemory.cpp | 1 - src/corelib/kernel/qsignalmapper.cpp | 4 +- src/corelib/kernel/qsocketnotifier.cpp | 1 + src/corelib/kernel/qsystemsemaphore.cpp | 1 - src/corelib/kernel/qtimer.cpp | 3 +- src/corelib/kernel/qtranslator.cpp | 2 - src/corelib/kernel/qvariant.cpp | 3 +- src/corelib/kernel/qwineventnotifier_p.cpp | 2 - src/corelib/plugin/qlibrary.cpp | 2 +- src/corelib/plugin/qplugin.qdoc | 135 + src/corelib/plugin/qpluginloader.cpp | 2 +- src/corelib/plugin/quuid.cpp | 1 - src/corelib/thread/qmutex.cpp | 3 - src/corelib/thread/qreadwritelock.cpp | 3 - src/corelib/thread/qsemaphore.cpp | 1 - src/corelib/thread/qthread.cpp | 2 - src/corelib/thread/qthreadstorage.cpp | 2 - src/corelib/thread/qwaitcondition.qdoc | 187 + src/corelib/tools/qalgorithms.qdoc | 651 +++ src/corelib/tools/qbytearray.cpp | 4 +- src/corelib/tools/qbytearraymatcher.cpp | 2 +- src/corelib/tools/qcache.qdoc | 244 ++ src/corelib/tools/qchar.cpp | 4 +- src/corelib/tools/qdatetime.cpp | 6 - src/corelib/tools/qhash.cpp | 4 +- src/corelib/tools/qiterator.qdoc | 1431 +++++++ src/corelib/tools/qline.cpp | 4 +- src/corelib/tools/qlinkedlist.cpp | 2 +- src/corelib/tools/qlistdata.cpp | 2 +- src/corelib/tools/qlocale.cpp | 4 +- src/corelib/tools/qmap.cpp | 4 +- src/corelib/tools/qpair.qdoc | 229 ++ src/corelib/tools/qpoint.cpp | 4 +- src/corelib/tools/qqueue.cpp | 2 +- src/corelib/tools/qrect.cpp | 4 +- src/corelib/tools/qregexp.cpp | 3 +- src/corelib/tools/qset.qdoc | 953 +++++ src/corelib/tools/qshareddata.cpp | 663 ++- src/corelib/tools/qsharedpointer.cpp | 2 - src/corelib/tools/qsize.cpp | 4 +- src/corelib/tools/qstack.cpp | 2 +- src/corelib/tools/qstring.cpp | 10 +- src/corelib/tools/qstringbuilder.cpp | 8 +- src/corelib/tools/qstringlist.cpp | 4 +- src/corelib/tools/qstringmatcher.cpp | 2 +- src/corelib/tools/qtextboundaryfinder.cpp | 2 +- src/corelib/tools/qtimeline.cpp | 2 +- src/corelib/tools/qvarlengtharray.qdoc | 274 ++ src/corelib/tools/qvector.cpp | 2 +- src/corelib/xml/qxmlstream.cpp | 4 +- src/gui/accessible/qaccessible.cpp | 2 +- src/gui/dialogs/qabstractprintdialog.cpp | 5 +- src/gui/dialogs/qcolordialog.cpp | 4 +- src/gui/dialogs/qdialog.cpp | 4 +- src/gui/dialogs/qerrormessage.cpp | 3 +- src/gui/dialogs/qfiledialog.cpp | 4 +- src/gui/dialogs/qfontdialog.cpp | 5 +- src/gui/dialogs/qinputdialog.cpp | 4 +- src/gui/dialogs/qmessagebox.cpp | 4 +- src/gui/dialogs/qpagesetupdialog.cpp | 46 + src/gui/dialogs/qprintdialog.qdoc | 72 + src/gui/dialogs/qprintpreviewdialog.cpp | 3 + src/gui/dialogs/qprogressdialog.cpp | 4 +- src/gui/embedded/qdirectpainter_qws.cpp | 2 +- src/gui/embedded/qlock.cpp | 1 - src/gui/graphicsview/qgraphicsgridlayout.cpp | 2 +- src/gui/graphicsview/qgraphicsitem.cpp | 13 +- src/gui/graphicsview/qgraphicsitemanimation.cpp | 1 - src/gui/graphicsview/qgraphicslayout.cpp | 1 - src/gui/graphicsview/qgraphicslayoutitem.cpp | 1 - src/gui/graphicsview/qgraphicslinearlayout.cpp | 1 - src/gui/graphicsview/qgraphicsproxywidget.cpp | 1 - src/gui/graphicsview/qgraphicsscene.cpp | 3 +- .../graphicsview/qgraphicsscenebsptreeindex.cpp | 3 +- src/gui/graphicsview/qgraphicssceneevent.cpp | 9 - src/gui/graphicsview/qgraphicssceneindex.cpp | 3 +- src/gui/graphicsview/qgraphicstransform.cpp | 1 + src/gui/graphicsview/qgraphicsview.cpp | 3 +- src/gui/graphicsview/qgraphicswidget.cpp | 1 - src/gui/image/qbitmap.cpp | 2 +- src/gui/image/qicon.cpp | 4 +- src/gui/image/qiconengine.cpp | 4 +- src/gui/image/qimage.cpp | 4 +- src/gui/image/qimagereader.cpp | 2 +- src/gui/image/qimagewriter.cpp | 2 +- src/gui/image/qmovie.cpp | 2 +- src/gui/image/qpicture.cpp | 6 +- src/gui/image/qpixmap.cpp | 4 +- src/gui/image/qpixmapcache.cpp | 3 +- src/gui/image/qpixmapfilter.cpp | 8 +- src/gui/inputmethod/qinputcontextfactory.cpp | 1 - src/gui/itemviews/qabstractitemdelegate.cpp | 2 +- src/gui/itemviews/qabstractitemview.cpp | 2 +- src/gui/itemviews/qcolumnview.cpp | 2 +- src/gui/itemviews/qheaderview.cpp | 2 +- src/gui/itemviews/qitemdelegate.cpp | 2 +- src/gui/itemviews/qlistview.cpp | 2 +- src/gui/itemviews/qlistwidget.cpp | 2 +- src/gui/itemviews/qstringlistmodel.cpp | 2 +- src/gui/itemviews/qstyleditemdelegate.cpp | 2 +- src/gui/itemviews/qtableview.cpp | 2 +- src/gui/itemviews/qtablewidget.cpp | 2 +- src/gui/itemviews/qtreeview.cpp | 2 +- src/gui/itemviews/qtreewidget.cpp | 4 +- src/gui/kernel/qaction.cpp | 4 +- src/gui/kernel/qactiongroup.cpp | 2 +- src/gui/kernel/qapplication.cpp | 6 - src/gui/kernel/qboxlayout.cpp | 5 - src/gui/kernel/qclipboard.cpp | 4 - src/gui/kernel/qcursor.cpp | 2 +- src/gui/kernel/qdesktopwidget.qdoc | 264 ++ src/gui/kernel/qformlayout.cpp | 2 - src/gui/kernel/qgridlayout.cpp | 3 +- src/gui/kernel/qkeymapper.cpp | 1 - src/gui/kernel/qkeysequence.cpp | 3 +- src/gui/kernel/qlayout.cpp | 1 - src/gui/kernel/qlayoutitem.cpp | 3 - src/gui/kernel/qmime_mac.cpp | 3 +- src/gui/kernel/qmime_win.cpp | 2 - src/gui/kernel/qpalette.cpp | 4 +- src/gui/kernel/qshortcut.cpp | 2 +- src/gui/kernel/qsizepolicy.qdoc | 521 +++ src/gui/kernel/qsound.cpp | 2 +- src/gui/kernel/qstackedlayout.cpp | 2 - src/gui/kernel/qtooltip.cpp | 2 +- src/gui/kernel/qwhatsthis.cpp | 2 +- src/gui/kernel/qwidget.cpp | 44 +- src/gui/kernel/qwidgetaction.cpp | 5 +- src/gui/math3d/qgenericmatrix.cpp | 2 + src/gui/math3d/qmatrix4x4.cpp | 1 + src/gui/math3d/qquaternion.cpp | 1 + src/gui/math3d/qvector2d.cpp | 2 + src/gui/math3d/qvector3d.cpp | 1 + src/gui/math3d/qvector4d.cpp | 1 + src/gui/painting/qbrush.cpp | 10 +- src/gui/painting/qcolor.cpp | 4 +- src/gui/painting/qcolormap.qdoc | 152 + src/gui/painting/qmatrix.cpp | 2 +- src/gui/painting/qpaintdevice.qdoc | 289 ++ src/gui/painting/qpaintengine.cpp | 2 +- src/gui/painting/qpainter.cpp | 4 +- src/gui/painting/qpainterpath.cpp | 4 +- src/gui/painting/qpen.cpp | 4 +- src/gui/painting/qpolygon.cpp | 4 +- src/gui/painting/qprinter.cpp | 6 +- src/gui/painting/qprinterinfo.qdoc | 139 + src/gui/painting/qregion.cpp | 2 +- src/gui/painting/qstylepainter.cpp | 2 +- src/gui/painting/qtransform.cpp | 2 +- src/gui/styles/qmacstyle.qdoc | 261 ++ src/gui/styles/qstyleoption.cpp | 2 +- src/gui/text/qabstracttextdocumentlayout.cpp | 2 +- src/gui/text/qfont.cpp | 9 +- src/gui/text/qfontdatabase.cpp | 6 +- src/gui/text/qfontmetrics.cpp | 6 +- src/gui/text/qsyntaxhighlighter.cpp | 2 +- src/gui/text/qtextcursor.cpp | 4 +- src/gui/text/qtextdocument.cpp | 4 +- src/gui/text/qtextdocumentfragment.cpp | 2 +- src/gui/text/qtextdocumentwriter.cpp | 2 +- src/gui/text/qtextformat.cpp | 20 +- src/gui/text/qtextlayout.cpp | 6 +- src/gui/text/qtextlist.cpp | 2 +- src/gui/text/qtextobject.cpp | 16 +- src/gui/text/qtextoption.cpp | 2 +- src/gui/text/qtexttable.cpp | 4 +- src/gui/util/qsystemtrayicon.cpp | 1 - src/gui/util/qundogroup.cpp | 1 - src/gui/util/qundostack.cpp | 2 - src/gui/util/qundoview.cpp | 2 +- src/gui/widgets/qbuttongroup.cpp | 2 - src/gui/widgets/qcalendarwidget.cpp | 2 +- src/gui/widgets/qcheckbox.cpp | 2 +- src/gui/widgets/qcombobox.cpp | 2 +- src/gui/widgets/qcommandlinkbutton.cpp | 2 +- src/gui/widgets/qdatetimeedit.cpp | 6 +- src/gui/widgets/qdial.cpp | 2 +- src/gui/widgets/qdialogbuttonbox.cpp | 4 +- src/gui/widgets/qdockwidget.cpp | 2 +- src/gui/widgets/qfocusframe.cpp | 2 +- src/gui/widgets/qfontcombobox.cpp | 1 - src/gui/widgets/qframe.cpp | 2 +- src/gui/widgets/qgroupbox.cpp | 2 - src/gui/widgets/qlabel.cpp | 2 - src/gui/widgets/qlcdnumber.cpp | 2 +- src/gui/widgets/qlineedit.cpp | 2 +- src/gui/widgets/qmainwindow.cpp | 4 +- src/gui/widgets/qmdiarea.cpp | 4 +- src/gui/widgets/qmdisubwindow.cpp | 4 +- src/gui/widgets/qmenu.cpp | 4 +- src/gui/widgets/qmenubar.cpp | 5 +- src/gui/widgets/qplaintextedit.cpp | 7 +- src/gui/widgets/qprintpreviewwidget.cpp | 2 +- src/gui/widgets/qprogressbar.cpp | 2 +- src/gui/widgets/qpushbutton.cpp | 2 +- src/gui/widgets/qradiobutton.cpp | 2 +- src/gui/widgets/qrubberband.cpp | 3 - src/gui/widgets/qscrollarea.cpp | 2 +- src/gui/widgets/qsizegrip.cpp | 3 +- src/gui/widgets/qslider.cpp | 2 +- src/gui/widgets/qspinbox.cpp | 4 +- src/gui/widgets/qsplashscreen.cpp | 3 - src/gui/widgets/qsplitter.cpp | 2 +- src/gui/widgets/qstackedwidget.cpp | 3 +- src/gui/widgets/qstatusbar.cpp | 4 +- src/gui/widgets/qtabbar.cpp | 2 +- src/gui/widgets/qtabwidget.cpp | 2 +- src/gui/widgets/qtextbrowser.cpp | 2 +- src/gui/widgets/qtextedit.cpp | 4 +- src/gui/widgets/qtoolbar.cpp | 4 +- src/gui/widgets/qtoolbox.cpp | 2 +- src/gui/widgets/qtoolbutton.cpp | 2 +- src/gui/widgets/qvalidator.cpp | 9 - src/gui/widgets/qworkspace.cpp | 1 - src/network/access/qftp.cpp | 4 +- src/network/access/qhttp.cpp | 10 +- src/network/access/qnetworkrequest.cpp | 2 +- src/network/kernel/qauthenticator.cpp | 2 +- src/network/kernel/qhostaddress.cpp | 2 +- src/network/kernel/qhostinfo.cpp | 2 +- src/network/kernel/qnetworkinterface.cpp | 4 +- src/network/kernel/qnetworkproxy.cpp | 4 +- src/network/kernel/qurlinfo.cpp | 2 +- src/network/socket/qabstractsocket.cpp | 2 +- src/network/socket/qnativesocketengine.cpp | 2 +- src/network/socket/qtcpserver.cpp | 2 +- src/network/socket/qtcpsocket.cpp | 2 +- src/network/socket/qudpsocket.cpp | 2 +- src/network/ssl/qssl.cpp | 3 +- src/network/ssl/qsslcertificate.cpp | 2 +- src/network/ssl/qsslcipher.cpp | 2 +- src/network/ssl/qsslconfiguration.cpp | 2 +- src/network/ssl/qsslerror.cpp | 2 +- src/network/ssl/qsslkey.cpp | 2 +- src/network/ssl/qsslsocket.cpp | 2 +- src/opengl/qgl.cpp | 10 +- src/opengl/qglcolormap.cpp | 2 +- src/opengl/qglframebufferobject.cpp | 4 +- src/opengl/qglpixelbuffer.cpp | 2 +- src/opengl/qglshaderprogram.cpp | 2 + src/qt3support/sql/q3sqlfieldinfo.qdoc | 234 ++ src/qt3support/sql/q3sqlrecordinfo.qdoc | 89 + src/qt3support/tools/q3asciicache.qdoc | 465 +++ src/qt3support/tools/q3asciidict.qdoc | 416 ++ src/qt3support/tools/q3cache.qdoc | 461 +++ src/qt3support/tools/q3dict.qdoc | 446 ++ src/qt3support/tools/q3intcache.qdoc | 446 ++ src/qt3support/tools/q3intdict.qdoc | 390 ++ src/qt3support/tools/q3memarray.qdoc | 523 +++ src/qt3support/tools/q3ptrdict.qdoc | 388 ++ src/qt3support/tools/q3ptrlist.qdoc | 1157 ++++++ src/qt3support/tools/q3ptrqueue.qdoc | 230 ++ src/qt3support/tools/q3ptrstack.qdoc | 217 + src/qt3support/tools/q3ptrvector.qdoc | 427 ++ src/qt3support/tools/q3valuelist.qdoc | 569 +++ src/qt3support/tools/q3valuestack.qdoc | 149 + src/qt3support/tools/q3valuevector.qdoc | 274 ++ src/qt3support/widgets/q3popupmenu.cpp | 37 + src/script/qscriptable.cpp | 2 +- src/script/qscriptclass.cpp | 2 +- src/script/qscriptcontext.cpp | 2 +- src/script/qscriptcontextinfo.cpp | 2 +- src/script/qscriptengine.cpp | 8 +- src/script/qscriptengineagent.cpp | 2 +- src/script/qscriptstring.cpp | 2 +- src/script/qscriptvalue.cpp | 2 +- src/script/qscriptvalueiterator.cpp | 2 +- src/scripttools/debugging/qscriptdebugger.cpp | 4 +- .../debugging/qscriptenginedebugger.cpp | 4 +- src/sql/kernel/qsql.qdoc | 139 + src/sql/kernel/qsqldatabase.cpp | 2 +- src/sql/kernel/qsqlquery.cpp | 2 +- src/svg/qgraphicssvgitem.cpp | 1 - src/svg/qsvggenerator.cpp | 2 +- src/svg/qsvgrenderer.cpp | 2 +- src/svg/qsvgwidget.cpp | 2 +- src/testlib/qsignalspy.qdoc | 98 + src/testlib/qtestevent.qdoc | 191 + src/xml/dom/qdom.cpp | 4 +- src/xml/sax/qxml.cpp | 2 +- src/xmlpatterns/api/qabstractxmlnodemodel.cpp | 3 +- src/xmlpatterns/api/qxmlquery.cpp | 4 +- src/xmlpatterns/utils/qautoptr.cpp | 2 - tools/assistant/compat/lib/qassistantclient.cpp | 1 - tools/designer/src/lib/sdk/abstractdnditem.qdoc | 112 + tools/designer/src/lib/sdk/abstracticoncache.qdoc | 130 + .../designer/src/lib/sdk/dynamicpropertysheet.qdoc | 94 + tools/designer/src/lib/sdk/layoutdecoration.qdoc | 163 + tools/designer/src/lib/sdk/membersheet.qdoc | 263 ++ tools/designer/src/lib/sdk/propertysheet.qdoc | 302 ++ tools/designer/src/lib/sdk/taskmenu.qdoc | 152 + tools/designer/src/lib/uilib/container.qdoc | 186 + tools/designer/src/lib/uilib/customwidget.qdoc | 309 ++ tools/qdoc3/test/classic.css | 21 +- tools/qdoc3/test/qt-html-templates.qdocconf | 48 +- 748 files changed, 89173 insertions(+), 88412 deletions(-) delete mode 100644 doc/src/accelerators.qdoc delete mode 100644 doc/src/accessible.qdoc delete mode 100644 doc/src/activeqt-dumpcpp.qdoc delete mode 100644 doc/src/activeqt-dumpdoc.qdoc delete mode 100644 doc/src/activeqt-idc.qdoc delete mode 100644 doc/src/activeqt-testcon.qdoc delete mode 100644 doc/src/activeqt.qdoc delete mode 100644 doc/src/animation.qdoc delete mode 100644 doc/src/appicon.qdoc delete mode 100644 doc/src/assistant-manual.qdoc delete mode 100644 doc/src/atomic-operations.qdoc create mode 100644 doc/src/classes/exportedfunctions.qdoc create mode 100644 doc/src/classes/phonon-namespace.qdoc delete mode 100644 doc/src/classes/q3asciicache.qdoc delete mode 100644 doc/src/classes/q3asciidict.qdoc delete mode 100644 doc/src/classes/q3cache.qdoc delete mode 100644 doc/src/classes/q3dict.qdoc delete mode 100644 doc/src/classes/q3intcache.qdoc delete mode 100644 doc/src/classes/q3intdict.qdoc delete mode 100644 doc/src/classes/q3memarray.qdoc delete mode 100644 doc/src/classes/q3popupmenu.qdoc delete mode 100644 doc/src/classes/q3ptrdict.qdoc delete mode 100644 doc/src/classes/q3ptrlist.qdoc delete mode 100644 doc/src/classes/q3ptrqueue.qdoc delete mode 100644 doc/src/classes/q3ptrstack.qdoc delete mode 100644 doc/src/classes/q3ptrvector.qdoc delete mode 100644 doc/src/classes/q3sqlfieldinfo.qdoc delete mode 100644 doc/src/classes/q3sqlrecordinfo.qdoc delete mode 100644 doc/src/classes/q3valuelist.qdoc delete mode 100644 doc/src/classes/q3valuestack.qdoc delete mode 100644 doc/src/classes/q3valuevector.qdoc delete mode 100644 doc/src/classes/qalgorithms.qdoc delete mode 100644 doc/src/classes/qcache.qdoc delete mode 100644 doc/src/classes/qcolormap.qdoc delete mode 100644 doc/src/classes/qdesktopwidget.qdoc delete mode 100644 doc/src/classes/qiterator.qdoc delete mode 100644 doc/src/classes/qmacstyle.qdoc delete mode 100644 doc/src/classes/qnamespace.qdoc delete mode 100644 doc/src/classes/qpagesetupdialog.qdoc delete mode 100644 doc/src/classes/qpaintdevice.qdoc delete mode 100644 doc/src/classes/qpair.qdoc delete mode 100644 doc/src/classes/qplugin.qdoc delete mode 100644 doc/src/classes/qprintdialog.qdoc delete mode 100644 doc/src/classes/qprinterinfo.qdoc delete mode 100644 doc/src/classes/qset.qdoc delete mode 100644 doc/src/classes/qsignalspy.qdoc delete mode 100644 doc/src/classes/qsizepolicy.qdoc delete mode 100644 doc/src/classes/qtdesigner-api.qdoc delete mode 100644 doc/src/classes/qtendian.qdoc delete mode 100644 doc/src/classes/qtestevent.qdoc delete mode 100644 doc/src/classes/qvarlengtharray.qdoc delete mode 100644 doc/src/classes/qwaitcondition.qdoc delete mode 100644 doc/src/codecs.qdoc delete mode 100644 doc/src/compiler-notes.qdoc delete mode 100644 doc/src/containers.qdoc delete mode 100644 doc/src/coordsys.qdoc delete mode 100644 doc/src/custom-types.qdoc delete mode 100644 doc/src/datastreamformat.qdoc delete mode 100644 doc/src/debug.qdoc delete mode 100644 doc/src/demos.qdoc create mode 100644 doc/src/demos/qtdemo.qdoc delete mode 100644 doc/src/deployment.qdoc create mode 100644 doc/src/deployment/deployment-plugins.qdoc create mode 100644 doc/src/deployment/deployment.qdoc create mode 100644 doc/src/deployment/qt-conf.qdoc create mode 100644 doc/src/deployment/qtconfig.qdoc delete mode 100644 doc/src/designer-manual.qdoc delete mode 100644 doc/src/desktop-integration.qdoc delete mode 100644 doc/src/developing-on-mac.qdoc create mode 100644 doc/src/development/activeqt-dumpcpp.qdoc create mode 100644 doc/src/development/activeqt-dumpdoc.qdoc create mode 100644 doc/src/development/activeqt-idc.qdoc create mode 100644 doc/src/development/activeqt-testcon.qdoc create mode 100644 doc/src/development/assistant-manual.qdoc create mode 100644 doc/src/development/debug.qdoc create mode 100644 doc/src/development/designer-manual.qdoc create mode 100644 doc/src/development/developing-on-mac.qdoc create mode 100644 doc/src/development/developing-with-qt.qdoc create mode 100644 doc/src/development/moc.qdoc create mode 100644 doc/src/development/qmake-manual.qdoc create mode 100644 doc/src/development/qmsdev.qdoc create mode 100644 doc/src/development/qtestlib.qdoc create mode 100644 doc/src/development/rcc.qdoc create mode 100644 doc/src/development/tools-list.qdoc create mode 100644 doc/src/development/uic.qdoc delete mode 100644 doc/src/distributingqt.qdoc delete mode 100644 doc/src/dnd.qdoc delete mode 100644 doc/src/ecmascript.qdoc delete mode 100644 doc/src/emb-accel.qdoc delete mode 100644 doc/src/emb-charinput.qdoc delete mode 100644 doc/src/emb-crosscompiling.qdoc delete mode 100644 doc/src/emb-deployment.qdoc delete mode 100644 doc/src/emb-differences.qdoc delete mode 100644 doc/src/emb-envvars.qdoc delete mode 100644 doc/src/emb-features.qdoc delete mode 100644 doc/src/emb-fonts.qdoc delete mode 100644 doc/src/emb-framebuffer-howto.qdoc delete mode 100644 doc/src/emb-install.qdoc delete mode 100644 doc/src/emb-kmap2qmap.qdoc delete mode 100644 doc/src/emb-makeqpf.qdoc delete mode 100644 doc/src/emb-performance.qdoc delete mode 100644 doc/src/emb-pointer.qdoc delete mode 100644 doc/src/emb-porting.qdoc delete mode 100644 doc/src/emb-qvfb.qdoc delete mode 100644 doc/src/emb-running.qdoc delete mode 100644 doc/src/emb-vnc.qdoc delete mode 100644 doc/src/eventsandfilters.qdoc delete mode 100644 doc/src/examples-overview.qdoc delete mode 100644 doc/src/examples.qdoc delete mode 100644 doc/src/exportedfunctions.qdoc create mode 100644 doc/src/files-and-resources/datastreamformat.qdoc create mode 100644 doc/src/files-and-resources/resources.qdoc delete mode 100644 doc/src/focus.qdoc create mode 100644 doc/src/frameworks-technologies/accessible.qdoc create mode 100644 doc/src/frameworks-technologies/activeqt-container.qdoc create mode 100644 doc/src/frameworks-technologies/activeqt-server.qdoc create mode 100644 doc/src/frameworks-technologies/activeqt.qdoc create mode 100644 doc/src/frameworks-technologies/animation.qdoc create mode 100644 doc/src/frameworks-technologies/containers.qdoc create mode 100644 doc/src/frameworks-technologies/dbus-adaptors.qdoc create mode 100644 doc/src/frameworks-technologies/dbus-intro.qdoc create mode 100644 doc/src/frameworks-technologies/desktop-integration.qdoc create mode 100644 doc/src/frameworks-technologies/dnd.qdoc create mode 100644 doc/src/frameworks-technologies/eventsandfilters.qdoc create mode 100644 doc/src/frameworks-technologies/gestures.qdoc create mode 100644 doc/src/frameworks-technologies/graphicsview.qdoc create mode 100644 doc/src/frameworks-technologies/implicit-sharing.qdoc create mode 100644 doc/src/frameworks-technologies/ipc.qdoc create mode 100644 doc/src/frameworks-technologies/model-view-programming.qdoc create mode 100644 doc/src/frameworks-technologies/phonon.qdoc create mode 100644 doc/src/frameworks-technologies/plugins-howto.qdoc create mode 100644 doc/src/frameworks-technologies/qthelp.qdoc create mode 100644 doc/src/frameworks-technologies/qundo.qdoc create mode 100644 doc/src/frameworks-technologies/richtext.qdoc create mode 100644 doc/src/frameworks-technologies/statemachine.qdoc create mode 100644 doc/src/frameworks-technologies/templates.qdoc create mode 100644 doc/src/frameworks-technologies/threads.qdoc create mode 100644 doc/src/frameworks-technologies/unicode.qdoc delete mode 100644 doc/src/gallery-cde.qdoc delete mode 100644 doc/src/gallery-cleanlooks.qdoc delete mode 100644 doc/src/gallery-gtk.qdoc delete mode 100644 doc/src/gallery-macintosh.qdoc delete mode 100644 doc/src/gallery-motif.qdoc delete mode 100644 doc/src/gallery-plastique.qdoc delete mode 100644 doc/src/gallery-windows.qdoc delete mode 100644 doc/src/gallery-windowsvista.qdoc delete mode 100644 doc/src/gallery-windowsxp.qdoc delete mode 100644 doc/src/gallery.qdoc delete mode 100644 doc/src/geometry.qdoc delete mode 100644 doc/src/gestures.qdoc create mode 100644 doc/src/getting-started/demos.qdoc create mode 100644 doc/src/getting-started/examples.qdoc create mode 100644 doc/src/getting-started/how-to-learn-qt.qdoc create mode 100644 doc/src/getting-started/installation.qdoc create mode 100644 doc/src/getting-started/known-issues.qdoc create mode 100644 doc/src/getting-started/tutorials.qdoc delete mode 100644 doc/src/graphicsview.qdoc delete mode 100644 doc/src/groups.qdoc delete mode 100644 doc/src/guibooks.qdoc delete mode 100644 doc/src/how-to-learn-qt.qdoc create mode 100644 doc/src/howtos/accelerators.qdoc create mode 100644 doc/src/howtos/appicon.qdoc create mode 100644 doc/src/howtos/custom-types.qdoc create mode 100644 doc/src/howtos/guibooks.qdoc create mode 100644 doc/src/howtos/openvg.qdoc create mode 100644 doc/src/howtos/qtdesigner.qdoc create mode 100644 doc/src/howtos/restoring-geometry.qdoc create mode 100644 doc/src/howtos/session.qdoc create mode 100644 doc/src/howtos/sharedlibrary.qdoc create mode 100644 doc/src/howtos/timers.qdoc create mode 100644 doc/src/howtos/unix-signal-handlers.qdoc delete mode 100644 doc/src/i18n.qdoc create mode 100644 doc/src/images/activeqt-examples.png create mode 100644 doc/src/images/animation-examples.png create mode 100644 doc/src/images/ipc-examples.png create mode 100644 doc/src/images/qq-thumbnail.png create mode 100644 doc/src/images/statemachine-examples.png delete mode 100644 doc/src/implicit-sharing.qdoc delete mode 100644 doc/src/installation.qdoc create mode 100644 doc/src/internationalization/i18n.qdoc create mode 100644 doc/src/internationalization/linguist-manual.qdoc delete mode 100644 doc/src/introtodbus.qdoc delete mode 100644 doc/src/ipc.qdoc delete mode 100644 doc/src/known-issues.qdoc delete mode 100644 doc/src/layout.qdoc delete mode 100644 doc/src/linguist-manual.qdoc delete mode 100644 doc/src/mac-differences.qdoc delete mode 100644 doc/src/metaobjects.qdoc delete mode 100644 doc/src/moc.qdoc delete mode 100644 doc/src/model-view-programming.qdoc create mode 100644 doc/src/network-programming/qtnetwork.qdoc create mode 100644 doc/src/network-programming/ssl.qdoc delete mode 100644 doc/src/object.qdoc create mode 100644 doc/src/objectmodel/metaobjects.qdoc create mode 100644 doc/src/objectmodel/object.qdoc create mode 100644 doc/src/objectmodel/objecttrees.qdoc create mode 100644 doc/src/objectmodel/properties.qdoc create mode 100644 doc/src/objectmodel/signalsandslots.qdoc delete mode 100644 doc/src/objecttrees.qdoc create mode 100644 doc/src/painting-and-printing/coordsys.qdoc create mode 100644 doc/src/painting-and-printing/paintsystem.qdoc create mode 100644 doc/src/painting-and-printing/printing.qdoc delete mode 100644 doc/src/paintsystem.qdoc delete mode 100644 doc/src/phonon.qdoc delete mode 100644 doc/src/platform-notes-rtos.qdoc delete mode 100644 doc/src/platform-notes.qdoc create mode 100644 doc/src/platforms/atomic-operations.qdoc create mode 100644 doc/src/platforms/compiler-notes.qdoc create mode 100644 doc/src/platforms/emb-accel.qdoc create mode 100644 doc/src/platforms/emb-architecture.qdoc create mode 100644 doc/src/platforms/emb-charinput.qdoc create mode 100644 doc/src/platforms/emb-crosscompiling.qdoc create mode 100644 doc/src/platforms/emb-deployment.qdoc create mode 100644 doc/src/platforms/emb-differences.qdoc create mode 100644 doc/src/platforms/emb-displaymanagement.qdoc create mode 100644 doc/src/platforms/emb-envvars.qdoc create mode 100644 doc/src/platforms/emb-features.qdoc create mode 100644 doc/src/platforms/emb-fonts.qdoc create mode 100644 doc/src/platforms/emb-framebuffer-howto.qdoc create mode 100644 doc/src/platforms/emb-install.qdoc create mode 100644 doc/src/platforms/emb-kmap2qmap.qdoc create mode 100644 doc/src/platforms/emb-makeqpf.qdoc create mode 100644 doc/src/platforms/emb-opengl.qdoc create mode 100644 doc/src/platforms/emb-performance.qdoc create mode 100644 doc/src/platforms/emb-pointer.qdoc create mode 100644 doc/src/platforms/emb-porting.qdoc create mode 100644 doc/src/platforms/emb-qvfb.qdoc create mode 100644 doc/src/platforms/emb-running.qdoc create mode 100644 doc/src/platforms/emb-vnc.qdoc create mode 100644 doc/src/platforms/mac-differences.qdoc create mode 100644 doc/src/platforms/platform-notes-rtos.qdoc create mode 100644 doc/src/platforms/platform-notes.qdoc create mode 100644 doc/src/platforms/qt-embedded-linux.qdoc create mode 100644 doc/src/platforms/qt-embedded.qdoc create mode 100644 doc/src/platforms/qtmac-as-native.qdoc create mode 100644 doc/src/platforms/supported-platforms.qdoc create mode 100644 doc/src/platforms/wince-customization.qdoc create mode 100644 doc/src/platforms/wince-introduction.qdoc create mode 100644 doc/src/platforms/wince-opengl.qdoc create mode 100644 doc/src/platforms/winsystem.qdoc create mode 100644 doc/src/platforms/x11overlays.qdoc delete mode 100644 doc/src/plugins-howto.qdoc delete mode 100644 doc/src/porting-qsa.qdoc create mode 100644 doc/src/porting/porting-qsa.qdoc create mode 100644 doc/src/porting/porting4-canvas.qdoc create mode 100644 doc/src/porting/porting4-designer.qdoc create mode 100644 doc/src/porting/porting4-dnd.qdoc create mode 100644 doc/src/porting/porting4-modifiedvirtual.qdocinc create mode 100644 doc/src/porting/porting4-obsoletedmechanism.qdocinc create mode 100644 doc/src/porting/porting4-overview.qdoc create mode 100644 doc/src/porting/porting4-removedenumvalues.qdocinc create mode 100644 doc/src/porting/porting4-removedtypes.qdocinc create mode 100644 doc/src/porting/porting4-removedvariantfunctions.qdocinc create mode 100644 doc/src/porting/porting4-removedvirtual.qdocinc create mode 100644 doc/src/porting/porting4-renamedclasses.qdocinc create mode 100644 doc/src/porting/porting4-renamedenumvalues.qdocinc create mode 100644 doc/src/porting/porting4-renamedfunctions.qdocinc create mode 100644 doc/src/porting/porting4-renamedstatic.qdocinc create mode 100644 doc/src/porting/porting4-renamedtypes.qdocinc create mode 100644 doc/src/porting/porting4.qdoc create mode 100644 doc/src/porting/qt3to4.qdoc create mode 100644 doc/src/porting/qt4-accessibility.qdoc create mode 100644 doc/src/porting/qt4-arthur.qdoc create mode 100644 doc/src/porting/qt4-designer.qdoc create mode 100644 doc/src/porting/qt4-interview.qdoc create mode 100644 doc/src/porting/qt4-mainwindow.qdoc create mode 100644 doc/src/porting/qt4-network.qdoc create mode 100644 doc/src/porting/qt4-scribe.qdoc create mode 100644 doc/src/porting/qt4-sql.qdoc create mode 100644 doc/src/porting/qt4-styles.qdoc create mode 100644 doc/src/porting/qt4-threads.qdoc create mode 100644 doc/src/porting/qt4-tulip.qdoc delete mode 100644 doc/src/porting4-canvas.qdoc delete mode 100644 doc/src/porting4-designer.qdoc delete mode 100644 doc/src/porting4-modifiedvirtual.qdocinc delete mode 100644 doc/src/porting4-obsoletedmechanism.qdocinc delete mode 100644 doc/src/porting4-overview.qdoc delete mode 100644 doc/src/porting4-removedenumvalues.qdocinc delete mode 100644 doc/src/porting4-removedtypes.qdocinc delete mode 100644 doc/src/porting4-removedvariantfunctions.qdocinc delete mode 100644 doc/src/porting4-removedvirtual.qdocinc delete mode 100644 doc/src/porting4-renamedclasses.qdocinc delete mode 100644 doc/src/porting4-renamedenumvalues.qdocinc delete mode 100644 doc/src/porting4-renamedfunctions.qdocinc delete mode 100644 doc/src/porting4-renamedstatic.qdocinc delete mode 100644 doc/src/porting4-renamedtypes.qdocinc delete mode 100644 doc/src/porting4.qdoc delete mode 100644 doc/src/printing.qdoc delete mode 100644 doc/src/properties.qdoc delete mode 100644 doc/src/qaxcontainer.qdoc delete mode 100644 doc/src/qaxserver.qdoc delete mode 100644 doc/src/qdbusadaptors.qdoc delete mode 100644 doc/src/qmake-manual.qdoc delete mode 100644 doc/src/qmsdev.qdoc delete mode 100644 doc/src/qsql.qdoc delete mode 100644 doc/src/qsqldatatype-table.qdoc delete mode 100644 doc/src/qt-conf.qdoc delete mode 100644 doc/src/qt-embedded.qdoc create mode 100644 doc/src/qt-webpages.qdoc delete mode 100644 doc/src/qt3support.qdoc delete mode 100644 doc/src/qt3to4.qdoc delete mode 100644 doc/src/qt4-accessibility.qdoc delete mode 100644 doc/src/qt4-arthur.qdoc delete mode 100644 doc/src/qt4-designer.qdoc delete mode 100644 doc/src/qt4-interview.qdoc delete mode 100644 doc/src/qt4-mainwindow.qdoc delete mode 100644 doc/src/qt4-network.qdoc delete mode 100644 doc/src/qt4-scribe.qdoc delete mode 100644 doc/src/qt4-sql.qdoc delete mode 100644 doc/src/qt4-styles.qdoc delete mode 100644 doc/src/qt4-threads.qdoc delete mode 100644 doc/src/qt4-tulip.qdoc delete mode 100644 doc/src/qtassistant.qdoc delete mode 100644 doc/src/qtconfig.qdoc delete mode 100644 doc/src/qtcore.qdoc delete mode 100644 doc/src/qtdbus.qdoc delete mode 100644 doc/src/qtdemo.qdoc delete mode 100644 doc/src/qtdesigner.qdoc delete mode 100644 doc/src/qtestlib.qdoc delete mode 100644 doc/src/qtgui.qdoc delete mode 100644 doc/src/qthelp.qdoc delete mode 100644 doc/src/qtmac-as-native.qdoc delete mode 100644 doc/src/qtmain.qdoc delete mode 100644 doc/src/qtnetwork.qdoc delete mode 100644 doc/src/qtopengl.qdoc delete mode 100644 doc/src/qtopenvg.qdoc delete mode 100644 doc/src/qtopiacore-architecture.qdoc delete mode 100644 doc/src/qtopiacore-displaymanagement.qdoc delete mode 100644 doc/src/qtopiacore-opengl.qdoc delete mode 100644 doc/src/qtopiacore.qdoc delete mode 100644 doc/src/qtscript.qdoc delete mode 100644 doc/src/qtscriptdebugger-manual.qdoc delete mode 100644 doc/src/qtscriptextensions.qdoc delete mode 100644 doc/src/qtscripttools.qdoc delete mode 100644 doc/src/qtsql.qdoc delete mode 100644 doc/src/qtsvg.qdoc delete mode 100644 doc/src/qttest.qdoc delete mode 100644 doc/src/qtuiloader.qdoc delete mode 100644 doc/src/qtxml.qdoc delete mode 100644 doc/src/qtxmlpatterns.qdoc delete mode 100644 doc/src/qundo.qdoc delete mode 100644 doc/src/rcc.qdoc delete mode 100644 doc/src/resources.qdoc delete mode 100644 doc/src/richtext.qdoc create mode 100644 doc/src/scripting/ecmascript.qdoc create mode 100644 doc/src/scripting/qtscriptdebugger-manual.qdoc create mode 100644 doc/src/scripting/qtscriptextensions.qdoc create mode 100644 doc/src/scripting/scripting.qdoc delete mode 100644 doc/src/session.qdoc delete mode 100644 doc/src/sharedlibrary.qdoc delete mode 100644 doc/src/signalsandslots.qdoc create mode 100644 doc/src/snippets/code/doc_src_qtmultimedia.qdoc delete mode 100644 doc/src/sql-driver.qdoc create mode 100644 doc/src/sql-programming/qsqldatatype-table.qdoc create mode 100644 doc/src/sql-programming/sql-driver.qdoc create mode 100644 doc/src/sql-programming/sql-programming.qdoc delete mode 100644 doc/src/statemachine.qdoc delete mode 100644 doc/src/styles.qdoc delete mode 100644 doc/src/stylesheet.qdoc delete mode 100644 doc/src/supported-platforms.qdoc delete mode 100644 doc/src/templates.qdoc delete mode 100644 doc/src/threads.qdoc delete mode 100644 doc/src/timers.qdoc delete mode 100644 doc/src/tools-list.qdoc delete mode 100644 doc/src/topics.qdoc delete mode 100644 doc/src/trolltech-webpages.qdoc delete mode 100644 doc/src/uic.qdoc delete mode 100644 doc/src/unicode.qdoc delete mode 100644 doc/src/unix-signal-handlers.qdoc create mode 100644 doc/src/widgets-and-layouts/focus.qdoc create mode 100644 doc/src/widgets-and-layouts/gallery-cde.qdoc create mode 100644 doc/src/widgets-and-layouts/gallery-cleanlooks.qdoc create mode 100644 doc/src/widgets-and-layouts/gallery-gtk.qdoc create mode 100644 doc/src/widgets-and-layouts/gallery-macintosh.qdoc create mode 100644 doc/src/widgets-and-layouts/gallery-motif.qdoc create mode 100644 doc/src/widgets-and-layouts/gallery-plastique.qdoc create mode 100644 doc/src/widgets-and-layouts/gallery-windows.qdoc create mode 100644 doc/src/widgets-and-layouts/gallery-windowsvista.qdoc create mode 100644 doc/src/widgets-and-layouts/gallery-windowsxp.qdoc create mode 100644 doc/src/widgets-and-layouts/gallery.qdoc create mode 100644 doc/src/widgets-and-layouts/layout.qdoc create mode 100644 doc/src/widgets-and-layouts/styles.qdoc create mode 100644 doc/src/widgets-and-layouts/stylesheet.qdoc create mode 100644 doc/src/widgets-and-layouts/widgets.qdoc delete mode 100644 doc/src/wince-customization.qdoc delete mode 100644 doc/src/wince-introduction.qdoc delete mode 100644 doc/src/wince-opengl.qdoc create mode 100644 doc/src/windows-and-dialogs/dialogs.qdoc create mode 100644 doc/src/windows-and-dialogs/mainwindow.qdoc delete mode 100644 doc/src/winsystem.qdoc create mode 100644 doc/src/xml-processing/xml-patterns.qdoc create mode 100644 doc/src/xml-processing/xml-processing.qdoc create mode 100644 doc/src/xml-processing/xquery-introduction.qdoc delete mode 100644 doc/src/xquery-introduction.qdoc create mode 100644 src/corelib/codecs/codecs.qdoc create mode 100644 src/corelib/global/qendian.qdoc create mode 100644 src/corelib/global/qnamespace.qdoc create mode 100644 src/corelib/plugin/qplugin.qdoc create mode 100644 src/corelib/thread/qwaitcondition.qdoc create mode 100644 src/corelib/tools/qalgorithms.qdoc create mode 100644 src/corelib/tools/qcache.qdoc create mode 100644 src/corelib/tools/qiterator.qdoc create mode 100644 src/corelib/tools/qpair.qdoc create mode 100644 src/corelib/tools/qset.qdoc create mode 100644 src/corelib/tools/qvarlengtharray.qdoc create mode 100644 src/gui/dialogs/qprintdialog.qdoc create mode 100644 src/gui/kernel/qdesktopwidget.qdoc create mode 100644 src/gui/kernel/qsizepolicy.qdoc create mode 100644 src/gui/painting/qcolormap.qdoc create mode 100644 src/gui/painting/qpaintdevice.qdoc create mode 100644 src/gui/painting/qprinterinfo.qdoc create mode 100644 src/gui/styles/qmacstyle.qdoc create mode 100644 src/qt3support/sql/q3sqlfieldinfo.qdoc create mode 100644 src/qt3support/sql/q3sqlrecordinfo.qdoc create mode 100644 src/qt3support/tools/q3asciicache.qdoc create mode 100644 src/qt3support/tools/q3asciidict.qdoc create mode 100644 src/qt3support/tools/q3cache.qdoc create mode 100644 src/qt3support/tools/q3dict.qdoc create mode 100644 src/qt3support/tools/q3intcache.qdoc create mode 100644 src/qt3support/tools/q3intdict.qdoc create mode 100644 src/qt3support/tools/q3memarray.qdoc create mode 100644 src/qt3support/tools/q3ptrdict.qdoc create mode 100644 src/qt3support/tools/q3ptrlist.qdoc create mode 100644 src/qt3support/tools/q3ptrqueue.qdoc create mode 100644 src/qt3support/tools/q3ptrstack.qdoc create mode 100644 src/qt3support/tools/q3ptrvector.qdoc create mode 100644 src/qt3support/tools/q3valuelist.qdoc create mode 100644 src/qt3support/tools/q3valuestack.qdoc create mode 100644 src/qt3support/tools/q3valuevector.qdoc create mode 100644 src/sql/kernel/qsql.qdoc create mode 100644 src/testlib/qsignalspy.qdoc create mode 100644 src/testlib/qtestevent.qdoc create mode 100644 tools/designer/src/lib/sdk/abstractdnditem.qdoc create mode 100644 tools/designer/src/lib/sdk/abstracticoncache.qdoc create mode 100644 tools/designer/src/lib/sdk/dynamicpropertysheet.qdoc create mode 100644 tools/designer/src/lib/sdk/layoutdecoration.qdoc create mode 100644 tools/designer/src/lib/sdk/membersheet.qdoc create mode 100644 tools/designer/src/lib/sdk/propertysheet.qdoc create mode 100644 tools/designer/src/lib/sdk/taskmenu.qdoc create mode 100644 tools/designer/src/lib/uilib/container.qdoc create mode 100644 tools/designer/src/lib/uilib/customwidget.qdoc diff --git a/doc/src/accelerators.qdoc b/doc/src/accelerators.qdoc deleted file mode 100644 index 4376730..0000000 --- a/doc/src/accelerators.qdoc +++ /dev/null @@ -1,137 +0,0 @@ -/**************************************************************************** -** -** 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 accelerators.html - \title Standard Accelerator Keys - \ingroup gui-programming - - Applications invariably need to define accelerator keys for actions. - Qt fully supports accelerators, for example with \l Q3Accel::shortcutKey(). - - Here are Microsoft's recommendations for accelerator keys, with - comments about the Open Group's recommendations where they exist - and differ. For most commands, the Open Group either has no advice or - agrees with Microsoft. - - The emboldened letter plus Alt is Microsoft's recommended choice, and - we recommend supporting it. For an Apply button, for example, we - recommend QAbstractButton::setText(\link QWidget::tr() tr \endlink("&Apply")); - - If you have conflicting commands (e.g. About and Apply buttons in the - same dialog), you must decide for yourself. - - \list - \i \bold{\underline{A}}bout - \i Always on \bold{\underline{T}}op - \i \bold{\underline{A}}pply - \i \bold{\underline{B}}ack - \i \bold{\underline{B}}rowse - \i \bold{\underline{C}}lose (CDE: Alt+F4; Alt+F4 is "close window" in Windows) - \i \bold{\underline{C}}opy (CDE: Ctrl+C, Ctrl+Insert) - \i \bold{\underline{C}}opy Here - \i Create \bold{\underline{S}}hortcut - \i Create \bold{\underline{S}}hortcut Here - \i Cu\bold{\underline{t}} - \i \bold{\underline{D}}elete - \i \bold{\underline{E}}dit - \i \bold{\underline{E}}xit (CDE: E\bold{\underline{x}}it) - \i \bold{\underline{E}}xplore - \i \bold{\underline{F}}ile - \i \bold{\underline{F}}ind - \i \bold{\underline{H}}elp - \i Help \bold{\underline{T}}opics - \i \bold{\underline{H}}ide - \i \bold{\underline{I}}nsert - \i Insert \bold{\underline{O}}bject - \i \bold{\underline{L}}ink Here - \i Ma\bold{\underline{x}}imize - \i Mi\bold{\underline{n}}imize - \i \bold{\underline{M}}ove - \i \bold{\underline{M}}ove Here - \i \bold{\underline{N}}ew - \i \bold{\underline{N}}ext - \i \bold{\underline{N}}o - \i \bold{\underline{O}}pen - \i Open \bold{\underline{W}}ith - \i Page Set\bold{\underline{u}}p - \i \bold{\underline{P}}aste - \i Paste \bold{\underline{L}}ink - \i Paste \bold{\underline{S}}hortcut - \i Paste \bold{\underline{S}}pecial - \i \bold{\underline{P}}ause - \i \bold{\underline{P}}lay - \i \bold{\underline{P}}rint - \i \bold{\underline{P}}rint Here - \i P\bold{\underline{r}}operties - \i \bold{\underline{Q}}uick View - \i \bold{\underline{R}}edo (CDE: Ctrl+Y, Shift+Alt+Backspace) - \i \bold{\underline{R}}epeat - \i \bold{\underline{R}}estore - \i \bold{\underline{R}}esume - \i \bold{\underline{R}}etry - \i \bold{\underline{R}}un - \i \bold{\underline{S}}ave - \i Save \bold{\underline{A}}s - \i Select \bold{\underline{A}}ll - \i Se\bold{\underline{n}}d To - \i \bold{\underline{S}}how - \i \bold{\underline{S}}ize - \i S\bold{\underline{p}}lit - \i \bold{\underline{S}}top - \i \bold{\underline{U}}ndo (CDE: Ctrl+Z or Alt+Backspace) - \i \bold{\underline{V}}iew - \i \bold{\underline{W}}hat's This? - \i \bold{\underline{W}}indow - \i \bold{\underline{Y}}es - \endlist - - There are also a lot of other keys and actions (that use other - modifier keys than Alt). See the Microsoft and The Open Group - documentation for details. - - The - \l{http://www.amazon.com/exec/obidos/ASIN/0735605661/trolltech/t}{Microsoft book} - has ISBN 0735605661. The corresponding Open Group - book is very hard to find, rather expensive and we cannot recommend - it. However, if you really want it, ogpubs@opengroup.org might be able - to help. Ask them for ISBN 1859121047. -*/ diff --git a/doc/src/accessible.qdoc b/doc/src/accessible.qdoc deleted file mode 100644 index 8daff5a..0000000 --- a/doc/src/accessible.qdoc +++ /dev/null @@ -1,600 +0,0 @@ -/**************************************************************************** -** -** 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 accessible.html - \title Accessibility - \ingroup accessibility - - \tableofcontents - - \section1 Introduction - - Accessibility in computer software is making applications usable - for people with disabilities. This could be achieved by providing - keyboard shortcuts, a high-contrast user interface that uses - specially selected colors and fonts, or support for assistive tools - such as screen readers and braille displays. - - An application does not usually communicate directly with - assistive tools but through an assistive technology, which is a - bridge for exchange of information between the applications and - the tools. Information about user interface elements, such - as buttons and scroll bars, is exposed to the assistive technologies. - Qt supports Microsoft Active Accessibility (MSAA) on Windows and - Mac OS X Accessibility on Mac OS X. - On Unix/X11, support is preliminary. The individual technologies - are abstracted from Qt, and there is only a single interface to - consider. We will use MSAA throughout this document when we need - to address technology related issues. - - In this overview document, we will examine the overall Qt - accessibility architecture, and how to implement accessibility for - custom widgets and elements. - - \section1 Architecture - - Providing accessibility is a collaboration between accessibility - compliant applications, the assistive technology, and the - assistive tools. - - \image accessibilityarchitecture.png - - Accessibility compliant applications are called AT-Servers while - assistive tools are called AT-Clients. A Qt application will - typically be an AT-Server, but specialized programs might also - function like AT-Clients. We will refer to clients and servers - when talking about AT-Clients and AT-Servers in the rest of this - document. - - We will from now on focus on the Qt accessibility interface and - how it is implemented to create Qt applications that support - accessibility. - - \section2 Accessibility in Qt - - When we communicate with the assistive technologies, we need to - describe Qt's user interface in a way that they can understand. Qt - applications use QAccessibleInterface to expose information about the - individual UI elements. Currently, Qt provides support for its widgets - and widget parts, e.g., slider handles, but the interface could - also be implemented for any QObject if necessary. QAccessible - contains enums that describe the UI. The description is mainly - based on MSAA and is independent of Qt. We will examine the enums - in the course of this document. - - The structure of the UI is represented as a tree of - QAccessibleInterface subclasses. You can think of this as a - representation of a UI like the QObject tree built by Qt. Objects - can be widgets or widget parts (such as scroll bar handles). We - examine the tree in detail in the next section. - - Servers notify clients through \l{QAccessible::}{updateAccessibility()} - about changes in objects by sending events, and the clients - register to receive the events. The available events are defined - by the QAccessible::Event enum. The clients may then query for - the object that generated the event through - QAccessible::queryAccessibleInterface(). - - Three of the enums in QAccessible help clients query and alter - accessible objects: - - \list - \o \l{QAccessible::}{Role}: Describes the role the object - fills in the user interface, e.g., if it is a main - window, a text caret, or a cell in an item view. - \o \l{QAccessible::}{Action}: The actions that the - clients can perform on the objects, e.g., pushing a - button. - \o \l{QAccessible::}{Relation}: Describes the relationship - between objects in the object tree. - This is used for navigation. - \endlist - - The clients also have some possibilities to get the content of - objects, e.g., a button's text; the object provides strings - defined by the QAccessible::Text enum, that give information - about content. - - The objects can be in a number of different states as defined by - the \l{QAccessible::}{State} enum. Examples of states are whether - the object is disabled, if it has focus, or if it provides a pop-up - menu. - - \section2 The Accessible Object Tree - - As mentioned, a tree structure is built from the accessible - objects of an application. By navigating through the tree, the - clients can access all elements in the UI. Object relations give - clients information about the UI. For instance, a slider handle is - a child of the slider to which it belongs. QAccessible::Relation - describes the various relationships the clients can ask objects - for. - - Note that there are no direct mapping between the Qt QObject tree - and the accessible object tree. For instance, scroll bar handles - are accessible objects but are not widgets or objects in Qt. - - AT-Clients have access to the accessibility object tree through - the root object in the tree, which is the QApplication. They can - query other objects through QAccessible::navigate(), which fetches - objects based on \l{QAccessible::}{Relation}s. The children of any - node is 1-based numbered. The child numbered 0 is the object - itself. The children of all interfaces are numbered this way, - i.e., it is not a fixed numbering from the root node in the entire - tree. - - Qt provides accessible interfaces for its widgets. Interfaces for - any QObject subclass can be requested through - QAccessible::queryInterface(). A default implementation is - provided if a more specialized interface is not defined. An - AT-Client cannot acquire an interface for accessible objects that - do not have an equivalent QObject, e.g., scroll bar handles, but - they appear as normal objects through interfaces of parent - accessible objects, e.g., you can query their relationships with - QAccessible::relationTo(). - - To illustrate, we present an image of an accessible object tree. - Beneath the tree is a table with examples of object relationships. - - \image accessibleobjecttree.png - - The labels in top-down order are: the QAccessibleInterface class - name, the widget for which an interface is provided, and the - \l{QAccessible::}{Role} of the object. The Position, PageLeft and - PageRight correspond to the slider handle, the slider groove left - and the slider groove right, respectively. These accessible objects - do not have an equivalent QObject. - - \table 40% - \header - \o Source Object - \o Target Object - \o Relation - \row - \o Slider - \o Indicator - \o Controller - \row - \o Indicator - \o Slider - \o Controlled - \row - \o Slider - \o Application - \o Ancestor - \row - \o Application - \o Slider - \o Child - \row - \o PushButton - \o Indicator - \o Sibling - \endtable - - \section2 The Static QAccessible Functions - - The accessibility is managed by QAccessible's static functions, - which we will examine shortly. They produce QAccessible - interfaces, build the object tree, and initiate the connection - with MSAA or the other platform specific technologies. If you are - only interested in learning how to make your application - accessible, you can safely skip over this section to - \l{Implementing Accessibility}. - - The communication between clients and the server is initiated when - \l{QAccessible::}{setRootObject()} is called. This is done when - the QApplication instance is instantiated and you should not have - to do this yourself. - - When a QObject calls \l{QAccessible::}{updateAccessibility()}, - clients that are listening to events are notified of the - change. The function is used to post events to the assistive - technology, and accessible \l{QAccessible::Event}{events} are - posted by \l{QAccessible::}{updateAccessibility()}. - - \l{QAccessible::}{queryAccessibleInterface()} returns accessible - interfaces for \l{QObject}s. All widgets in Qt provide interfaces; - if you need interfaces to control the behavior of other \l{QObject} - subclasses, you must implement the interfaces yourself, although - the QAccessibleObject convenience class implements parts of the - functionality for you. - - The factory that produces accessibility interfaces for QObjects is - a function of type QAccessible::InterfaceFactory. It is possible - to have several factories installed. The last factory installed - will be the first to be asked for interfaces. - \l{QAccessible::}{queryAccessibleInterface()} uses the factories - to create interfaces for \l{QObject}s. Normally, you need not be - concerned about factories because you can implement plugins that - produce interfaces. We will give examples of both approaches - later. - - \section1 Implementing Accessibility - - To provide accessibility support for a widget or other user - interface element, you need to implement the QAccessibleInterface - and distribute it in a QAccessiblePlugin. It is also possible to - compile the interface into the application and provide a - QAccessible::InterfaceFactory for it. The factory can be used if - you link statically or do not want the added complexity of - plugins. This can be an advantage if you, for instance, are - delivering a 3-rd party library. - - All widgets and other user interface elements should have - interfaces and plugins. If you want your application to support - accessibility, you will need to consider the following: - - \list - \o Qt already implements accessibility for its own widgets. - We therefore recommend that you use Qt widgets where possible. - \o A QAccessibleInterface needs to be implemented for each element - that you want to make available to accessibility clients. - \o You need to send accessibility events from the custom - user interface elements that you implement. - \endlist - - In general, it is recommended that you are somewhat familiar with - MSAA, which Qt originally was built for. You should also study - the enum values of QAccessible, which describe the roles, actions, - relationships, and events that you need to consider. - - Note that you can examine how Qt's widgets implement their - accessibility. One major problem with the MSAA standard is that - interfaces are often implemented in an inconsistent way. This - makes life difficult for clients and often leads to guesswork on - object functionality. - - It is possible to implement interfaces by inheriting - QAccessibleInterface and implementing its pure virtual functions. - In practice, however, it is usually preferable to inherit - QAccessibleObject or QAccessibleWidget, which implement part of - the functionality for you. In the next section, we will see an - example of implementing accessibility for a widget by inheriting - the QAccessibleWidget class. - - \section2 The QAccessibleObject and QAccessibleWidget Convenience Classes - - When implementing an accessibility interface for widgets, one would - as a rule inherit QAccessibleWidget, which is a convenience class - for widgets. Another available convenience class, which is - inherited by QAccessibleWidget, is the QAccessibleObject, which - implements part of the interface for QObjects. - - The QAccessibleWidget provides the following functionality: - - \list - \o It handles the navigation of the tree and - hit testing of the objects. - \o It handles events, roles, and actions that are common for all - \l{QWidget}s. - \o It handles action and methods that can be performed on - all widgets. - \o It calculates bounding rectangles with - \l{QAccessibleInterface::}{rect()}. - \o It gives \l{QAccessibleInterface::}{text()} strings that are - appropriate for a generic widget. - \o It sets the \l{QAccessible::State}{states} that - are common for all widgets. - \endlist - - \section2 QAccessibleWidget Example - - Instead of creating a custom widget and implementing an interface - for it, we will show how accessibility can be implemented for one of - Qt's standard widgets: QSlider. Making this widget accessible - demonstrates many of the issues that need to be faced when making - a custom widget accessible. - - The slider is a complex control that functions as a - \l{QAccessible::}{Controller} for its accessible children. - This relationship must be known by the interface (for - \l{QAccessibleInterface::}{relationTo()} and - \l{QAccessibleInterface::}{navigate()}). This can be done - using a controlling signal, which is a mechanism provided by - QAccessibleWidget. We do this in the constructor: - - \snippet doc/src/snippets/accessibilityslidersnippet.cpp 0 - - The choice of signal shown is not important; the same principles - apply to all signals that are declared in this way. Note that we - use QLatin1String to ensure that the signal name is correctly - specified. - - When an accessible object is changed in a way that users need - to know about, it notifies clients of the change by sending them - an event via the accessible interface. This is how QSlider calls - \l{QAccessibleInterface::}{updateAccessibility()} to indicate that - its value has changed: - - \snippet doc/src/snippets/qabstractsliderisnippet.cpp 0 - \dots - \snippet doc/src/snippets/qabstractsliderisnippet.cpp 1 - \dots - \snippet doc/src/snippets/qabstractsliderisnippet.cpp 2 - - Note that the call is made after the value of the slider has - changed because clients may query the new value immediately after - receiving the event. - - The interface must be able to calculate bounding rectangles of - itself and any children that do not provide an interface of their - own. The \c QAccessibleSlider has three such children identified by - the private enum, \c SliderElements, which has the following values: - \c PageLeft (the rectangle on the left hand side of the slider - handle), \c PageRight (the rectangle on the right hand side of the - handle), and \c Position (the slider handle). Here is the - implementation of \l{QAccessibleInterface::}{rect()}: - - \snippet doc/src/snippets/accessibilityslidersnippet.cpp 1 - \dots - \snippet doc/src/snippets/accessibilityslidersnippet.cpp 2 - \dots - - The first part of the function, which we have omitted, uses the - current \l{QStyle}{style} to calculate the slider handle's - bounding rectangle; it is stored in \c srect. Notice that child 0, - covered in the default case in the above code, is the slider itself, - so we can simply return the QSlider bounding rectangle obtained - from the superclass, which is effectively the value obtained from - QAccessibleWidget::rect(). - - \snippet doc/src/snippets/accessibilityslidersnippet.cpp 3 - - Before the rectangle is returned it must be mapped to screen - coordinates. - - The QAccessibleSlider must reimplement - QAccessibleInterface::childCount() since it manages children - without interfaces. - - The \l{QAccessibleInterface::}{text()} function returns the - QAccessible::Text strings for the slider: - - \snippet doc/src/snippets/accessibilityslidersnippet.cpp 4 - - The \c slider() function returns a pointer to the interface's - QSlider. Some values are left for the superclass's implementation. - Not all values are appropriate for all accessible objects, as you - can see for QAccessible::Value case. You should just return an - empty string for those values where no relevant text can be - provided. - - The implementation of the \l{QAccessibleInterface::}{role()} - function is straightforward: - - \snippet doc/src/snippets/accessibilityslidersnippet.cpp 5 - - The role function should be reimplemented by all objects and - describes the role of themselves and the children that do not - provide accessible interfaces of their own. - - Next, the accessible interface needs to return the - \l{QAccessible::State}{states} that the slider can be in. We look - at parts of the \c state() implementation to show how just a few - of the states are handled: - - \snippet doc/src/snippets/accessibilityslidersnippet.cpp 6 - \dots - \snippet doc/src/snippets/accessibilityslidersnippet.cpp 7 - - The superclass implementation of - \l{QAccessibleInterface::}{state()}, uses the - QAccessibleInterface::state() implementation. We simply need to - disable the buttons if the slider is at its minimum or maximum. - - We have now exposed the information we have about the slider to - the clients. For the clients to be able to alter the slider - for - example, to change its value - we must provide information about - the actions that can be performed and perform them upon request. - We discuss this in the next section. - - \section2 Handling Action Requests from Clients - - QAccessible provides a number of \l{QAccessible::}{Action}s - that can be performed on request from clients. If an - accessible object supports actions, it should reimplement the - following functions from QAccessibleInterface: - - \list - \o \l{QAccessibleInterface::}{actionText()} returns - strings that describe each action. The descriptions - to be made available are one for each - \l{QAccessible::}{Text} enum value. - \o \l{QAccessibleInterface::}{doAction()} executes requests - from clients to perform actions. - \endlist - - Note that a client can request any action from an object. If - the object does not support the action, it returns false from - \l{QAccessibleInterface::}{doAction()}. - - None of the standard actions take any parameters. It is possible - to provide user-defined actions that can take parameters. - The interface must then also reimplement - \l{QAccessibleInterface::}{userActionCount()}. Since this is not - defined in the MSAA specification, it is probably only useful to - use this if you know which specific AT-Clients will use the - application. - - QAccessibleInterface gives another technique for clients to handle - accessible objects. It works basically the same way, but uses the - concept of methods in place of actions. The available methods are - defined by the QAccessible::Method enum. The following functions - need to be reimplemented from QAccessibleInterface if the - accessible object is to support methods: - - \list - \o \l{QAccessibleInterface::}{supportedMethods()} returns - a QSet of \l{QAccessible::}{Method} values that are - supported by the object. - \o \l{QAccessibleInterface::}{invokeMethod()} executes - methods requested by clients. - \endlist - - The action mechanism will probably be substituted by providing - methods in place of the standard actions. - - To see examples on how to implement actions and methods, you - could examine the QAccessibleObject and QAccessibleWidget - implementations. You might also want to take a look at the - MSAA documentation. - - \section2 Implementing Accessible Plugins - - In this section we will explain the procedure of implementing - accessible plugins for your interfaces. A plugin is a class stored - in a shared library that can be loaded at run-time. It is - convenient to distribute interfaces as plugins since they will only - be loaded when required. - - Creating an accessible plugin is achieved by inheriting - QAccessiblePlugin, reimplementing \l{QAccessiblePlugin::}{keys()} - and \l{QAccessiblePlugin::}{create()} from that class, and adding - one or two macros. The \c .pro file must be altered to use the - plugin template, and the library containing the plugin must be - placed on a path where Qt searches for accessible plugins. - - We will go through the implementation of \c SliderPlugin, which is an - accessible plugin that produces interfaces for the - QAccessibleSlider we implemented in the \l{QAccessibleWidget Example}. - We start with the \c key() function: - - \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 0 - - We simply need to return the class name of the single interface - our plugin can create an accessible interface for. A plugin - can support any number of classes; just add more class names - to the string list. We move on to the \c create() function: - - \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 1 - - We check whether the interface requested is for the QSlider; if it - is, we create and return an interface for it. Note that \c object - will always be an instance of \c classname. You must return 0 if - you do not support the class. - \l{QAccessible::}{updateAccessibility()} checks with the - available accessibility plugins until it finds one that does not - return 0. - - Finally, you need to include macros in the cpp file: - - \snippet doc/src/snippets/accessibilitypluginsnippet.cpp 2 - - The Q_EXPORT_PLUGIN2 macro exports the plugin in the \c - SliderPlugin class into the \c acc_sliderplugin library. The first - argument is the name of the plugin library file, excluding the - file suffix, and the second is the class name. For more information - on plugins, consult the plugins \l{How to Create Qt - Plugins}{overview document}. - - You can omit the first macro unless you want the plugin - to be statically linked with the application. - - \section2 Implementing Interface Factories - - If you do not want to provide plugins for your accessibility - interfaces, you can use an interface factory - (QAccessible::InterfaceFactory), which is the recommended way to - provide accessible interfaces in a statically-linked application. - - A factory is a function pointer for a function that takes the same - parameters as \l{QAccessiblePlugin}'s - \l{QAccessiblePlugin::}{create()} - a QString and a QObject. It - also works the same way. You install the factory with the - \l{QAccessible::}{installFactory()} function. We give an example - of how to create a factory for the \c SliderPlugin class: - - \snippet doc/src/snippets/accessibilityfactorysnippet.cpp 0 - \dots - \snippet doc/src/snippets/accessibilityfactorysnippet.cpp 1 - - \omit - - \section1 Implementing Bridges for Other Assistive Technologies - - An accessibility bridge provides the means for an assistive - technology to talk to Qt. On Windows and Mac, the built-in bridges - will be used. On UNIX, however, there are no built-in standard - assistive technology, and it might therefore be necessary to - implement an accessible bridge. - - A bridge is implemented by inheriting QAccessibleBridge for the - technology to support. The class defines the interface that Qt - needs an assistive technology to support: - - \list - \o A root object. This is the root in the accessible - object tree and is of type QAccessibleInterface. - \o Receive events from from accessible objects. - \endlist - - The root object is set with the - \l{QAccessibleBridge::}{setRootObject()}. In the case of Qt, this - will always be an interface for the QApplication instance of the - application. - - Event notification is sent through - \l{QAccessibleBridge::}{notifyAccessibilityUpdate()}. This - function is called by \l{QAccessible::}{updateAccessibility()}. Even - though the bridge needs only to implement these two functions, it - must be able to communicate the entire QAccessibleInterface to the - underlying technology. How this is achieved is, naturally, up to - the individual bridge and none of Qt's concern. - - As with accessible interfaces, you distribute accessible bridges - in plugins. Accessible bridge plugins are subclasses of the - QAccessibleBridgePlugin class; the class defines the functions - \l{QAccessibleBridgePlugin::}{create()} and - \l{QAccessibleBridgePlugin::}{keys()}, which must me - reimplemented. If Qt finds a built-in bridge to use, it will - ignore any available plugins. - - \endomit - - \section1 Further Reading - - The \l{Cross-Platform Accessibility Support in Qt 4} document contains a more - general overview of Qt's accessibility features and discusses how it is - used on each platform. - issues -*/ diff --git a/doc/src/activeqt-dumpcpp.qdoc b/doc/src/activeqt-dumpcpp.qdoc deleted file mode 100644 index 63e35ee..0000000 --- a/doc/src/activeqt-dumpcpp.qdoc +++ /dev/null @@ -1,143 +0,0 @@ -/**************************************************************************** -** -** 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/activeqt-dumpdoc.qdoc b/doc/src/activeqt-dumpdoc.qdoc deleted file mode 100644 index 55ab2d7..0000000 --- a/doc/src/activeqt-dumpdoc.qdoc +++ /dev/null @@ -1,83 +0,0 @@ -/**************************************************************************** -** -** 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/activeqt-idc.qdoc b/doc/src/activeqt-idc.qdoc deleted file mode 100644 index 974eddc..0000000 --- a/doc/src/activeqt-idc.qdoc +++ /dev/null @@ -1,82 +0,0 @@ -/**************************************************************************** -** -** 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/activeqt-testcon.qdoc b/doc/src/activeqt-testcon.qdoc deleted file mode 100644 index 9fcfed6..0000000 --- a/doc/src/activeqt-testcon.qdoc +++ /dev/null @@ -1,77 +0,0 @@ -/**************************************************************************** -** -** 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/activeqt.qdoc b/doc/src/activeqt.qdoc deleted file mode 100644 index b3f0856..0000000 --- a/doc/src/activeqt.qdoc +++ /dev/null @@ -1,88 +0,0 @@ -/**************************************************************************** -** -** 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.html - \title ActiveQt Framework - \brief An overview of Qt's ActiveX and COM integration on Windows. - - \ingroup platform-notes - \keyword ActiveQt - - Qt's ActiveX and COM support allows Qt for Windows developers to: - - \list 1 - \o Access and use ActiveX controls and COM objects provided by any - ActiveX server in their Qt applications. - \o Make their Qt applications available as COM servers, with - any number of Qt objects and widgets as COM objects and ActiveX - controls. - \endlist - - The ActiveQt framework consists of two modules: - - \list - \o The \l QAxContainer module is a static - library implementing QObject and QWidget subclasses, QAxObject and - QAxWidget, that act as containers for COM objects and ActiveX - controls. - \o The \l QAxServer module is a static library that implements - functionality for in-process and executable COM servers. This - module provides the QAxAggregated, QAxBindable and QAxFactory - classes. - \endlist - - To build the static libraries, change into the \c activeqt directory - (usually \c QTDIR/src/activeqt), and run \c qmake and your make - tool in both the \c container and the \c control subdirectory. - The libraries \c qaxcontainer.lib and \c qaxserver.lib will be linked - into \c QTDIR/lib. - - If you are using a shared configuration of Qt enter the \c plugin - subdirectory and run \c qmake and your make tool to build a - plugin that integrates the QAxContainer module into \l{Qt - Designer}. - - The ActiveQt modules are part of the \l{Qt Full Framework Edition} and - the \l{Open Source Versions of Qt}. - - \sa {QAxContainer Module}, {QAxServer Module} -*/ diff --git a/doc/src/animation.qdoc b/doc/src/animation.qdoc deleted file mode 100644 index 7fd7850..0000000 --- a/doc/src/animation.qdoc +++ /dev/null @@ -1,364 +0,0 @@ -/**************************************************************************** -** -** 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 animation-overview.html - \title The Animation Framework - \ingroup architecture - \ingroup animation - \brief An overview of the Animation Framework - - \keyword Animation - - The animation framework is part of the Kinetic project, and aims - to provide an easy way for creating animated and smooth GUI's. By - animating Qt properties, the framework provides great freedom for - animating widgets and other \l{QObject}s. The framework can also - be used with the Graphics View framework. - - In this overview, we explain the basics of its architecture. We - also show examples of the most common techniques that the - framework allows for animating QObjects and graphics items. - - \tableofcontents - - \section1 The Animation Architecture - - We will in this section take a high-level look at the animation - framework's architecture and how it is used to animate Qt - properties. The following diagram shows the most important classes - in the animation framework. - - \image animations-architecture.png - - The animation framework foundation consists of the base class - QAbstractAnimation, and its two subclasses QVariantAnimation and - QAnimationGroup. QAbstractAnimation is the ancestor of all - animations. It represents basic properties that are common for all - animations in the framework; notably, the ability to start, stop, - and pause an animation. It is also receives the time change - notifications. - - The animation framework further provides the QPropertyAnimation - class, which inherits QVariantAnimation and performs animation of - a Qt property, which is part of Qt's \l{Meta-Object - System}{meta-object system}. The class performs an interpolation - over the property using an easing curve. So when you want to - animate a value, you can declare it as a property and make your - class a QObject. Note that this gives us great freedom in - animating already existing widgets and other \l{QObject}s. - - Complex animations can be constructed by building a tree structure - of \l{QAbstractAnimation}s. The tree is built by using - \l{QAnimationGroup}s, which function as containers for other - animations. Note also that the groups are subclasses of - QAbstractAnimation, so groups can themselves contain other groups. - - The animation framework can be used on its own, but is also - designed to be part of the state machine framework (See the - \l{The State Machine Framework}{state machine framework} for an - introduction to the Qt state machine). The state machine provides - a special state that can play an animation. A QState can also set - properties when the state is entered or exited, and this special - animation state will interpolate between these values when given a - QPropertyAnimation. We will look more closely at this later. - - Behind the scenes, the animations are controlled by a global - timer, which sends \l{QAbstractAnimation::updateCurrentTime()}{updates} to - all animations that are playing. - - For detailed descriptions of the classes' function and roles in - the framework, please look up their class descriptions. - - \section1 Animating Qt Properties - - As mentioned in the previous section, the QPropertyAnimation class - can interpolate over Qt properties. It is this class that should - be used for animation of values; in fact, its superclass, - QVariantAnimation, is an abstract class, and cannot be used - directly. - - A major reason we chose to animate Qt properties is that it - presents us with freedom to animate already existing classes in - the Qt API. Notably, the QWidget class (which we can also embed in - a QGraphicsView) has properties for its bounds, colors, etc. - Let's look at a small example: - - \code - QPushButton button("Animated Button"); - button.show(); - - QPropertyAnimation animation(&button, "geometry"); - animation.setDuration(10000); - animation.setStartValue(QRect(0, 0, 100, 30)); - animation.setEndValue(QRect(250, 250, 100, 30)); - - animation.start(); - \endcode - - This code will move \c button from the top left corner of the - screen to the position (250, 250) in 10 seconds (10000 milliseconds). - - The example above will do a linear interpolation between the - start and end value. It is also possible to set values - situated between the start and end value. The interpolation - will then go by these points. - - \code - QPushButton button("Animated Button"); - button.show(); - - QPropertyAnimation animation(&button, "geometry"); - animation.setDuration(10000); - - animation.setKeyValueAt(0, QRect(0, 0, 100, 30)); - animation.setKeyValueAt(0.8, QRect(250, 250, 100, 30)); - animation.setKeyValueAt(1, QRect(0, 0, 100, 30)); - - animation.start(); - \endcode - - In this example, the animation will take the button to (250, 250) - in 8 seconds, and then move it back to its original position in - the remaining 2 seconds. The movement will be linearly - interpolated between these points. - - You also have the possibility to animate values of a QObject - that is not declared as a Qt property. The only requirement is - that this value has a setter. You can then subclass the class - containing the value and declare a property that uses this setter. - Note that each Qt property requires a getter, so you will need to - provide a getter yourself if this is not defined. - - \code - class MyGraphicsRectItem : public QObject, public QGraphicsRectItem - { - Q_OBJECT - Q_PROPERTY(QRectF geometry READ geometry WRITE setGeometry) - }; - \endcode - - In the above code example, we subclass QGraphicsRectItem and - define a geometry property. We can now animate the widgets - geometry even if QGraphicsRectItem does not provide the geometry - property. - - For a general introduction to the Qt property system, see its - \l{Qt's Property System}{overview}. - - \section1 Animations and the Graphics View Framework - - When you want to animate \l{QGraphicsItem}s, you also use - QPropertyAnimation. However, QGraphicsItem does not inherit QObject. - A good solution is to subclass the graphics item you wish to animate. - This class will then also inherit QObject. - This way, QPropertyAnimation can be used for \l{QGraphicsItem}s. - The example below shows how this is done. Another possibility is - to inherit QGraphicsWidget, which already is a QObject. - - \code - class Pixmap : public QObject, public QGraphicsPixmapItem - { - Q_OBJECT - Q_PROPERTY(QPointF pos READ pos WRITE setPos) - ... - \endcode - - As described in the previous section, we need to define - properties that we wish to animate. - - Note that QObject must be the first class inherited as the - meta-object system demands this. - - \section1 Easing Curves - - As mentioned, QPropertyAnimation performs an interpolation between - the start and end property value. In addition to adding more key - values to the animation, you can also use an easing curve. Easing - curves describe a function that controls how the speed of the - interpolation between 0 and 1 should be, and are useful if you - want to control the speed of an animation without changing the - path of the interpolation. - - \code - QPushButton button("Animated Button"); - button.show(); - - QPropertyAnimation animation(&button, "geometry"); - animation.setDuration(3000); - animation.setStartValue(QRect(0, 0, 100, 30)); - animation.setEndValue(QRect(250, 250, 100, 30)); - - animation.setEasingCurve(QEasingCurve::OutBounce); - - animation.start(); - \endcode - - Here the animation will follow a curve that makes it bounce like a - ball as if it was dropped from the start to the end position. - QEasingCurve has a large collection of curves for you to choose - from. These are defined by the QEasingCurve::Type enum. If you are - in need of another curve, you can also implement one yourself, and - register it with QEasingCurve. - - \omit Drop this for the first Lab release - (Example of custom easing curve (without the actual impl of - the function I expect) - \endomit - - \section1 Putting Animations Together - - An application will often contain more than one animation. For - instance, you might want to move more than one graphics item - simultaneously or move them in sequence after each other. - - The subclasses of QAnimationGroup (QSequentialAnimationGroup and - QParallelAnimationGroup) are containers for other animations so - that these animations can be animated either in sequence or - parallel. The QAnimationGroup is an example of an animation that - does not animate properties, but it gets notified of time changes - periodically. This enables it to forward those time changes to its - contained animations, and thereby controlling when its animations - are played. - - Let's look at code examples that use both - QSequentialAnimationGroup and QParallelAnimationGroup, starting - off with the latter. - - \code - QPushButton *bonnie = new QPushButton("Bonnie"); - bonnie->show(); - - QPushButton *clyde = new QPushButton("Clyde"); - clyde->show(); - - QPropertyAnimation *anim1 = new QPropertyAnimation(bonnie, "geometry"); - // Set up anim1 - - QPropertyAnimation *anim2 = new QPropertyAnimation(clyde, "geometry"); - // Set up anim2 - - QParallelAnimationGroup *group = new QParallelAnimationGroup; - group->addAnimation(anim1); - group->addAnimation(anim2); - - group->start(); - \endcode - - A parallel group plays more than one animation at the same time. - Calling its \l{QAbstractAnimation::}{start()} function will start - all animations it governs. - - \code - QPushButton button("Animated Button"); - button.show(); - - QPropertyAnimation anim1(&button, "geometry"); - anim1.setDuration(3000); - anim1.setStartValue(QRect(0, 0, 100, 30)); - anim1.setEndValue(QRect(500, 500, 100, 30)); - - QPropertyAnimation anim2(&button, "geometry"); - anim2.setDuration(3000); - anim2.setStartValue(QRect(500, 500, 100, 30)); - anim2.setEndValue(QRect(1000, 500, 100, 30)); - - QSequentialAnimationGroup group; - - group.addAnimation(&anim1); - group.addAnimation(&anim2); - - group.start(); - \endcode - - As you no doubt have guessed, QSequentialAnimationGroup plays - its animations in sequence. It starts the next animation in - the list after the previous is finished. - - Since an animation group is an animation itself, you can add - it to another group. This way, you can build a tree structure - of animations which specifies when the animations are played - in relation to each other. - - \section1 Animations and States - - When using a \l{The State Machine Framework}{state machine}, we - can associate one or more animations to a transition between states - using a QSignalTransition or QEventTransition class. These classes - are both derived from QAbstractTransition, which defines the - convenience function \l{QAbstractTransition::}{addAnimation()} that - enables the appending of one or more animations triggered when the - transition occurs. - - We also have the possibility to associate properties with the - states rather than setting the start and end values ourselves. - Below is a complete code example that animates the geometry of a - QPushButton. - - \code - QPushButton *button = new QPushButton("Animated Button"); - button->show(); - - QStateMachine *machine = new QStateMachine; - - QState *state1 = new QState(machine->rootState()); - state1->assignProperty(button, "geometry", QRect(0, 0, 100, 30)); - machine->setInitialState(state1); - - QState *state2 = new QState(machine->rootState()); - state2->assignProperty(button, "geometry", QRect(250, 250, 100, 30)); - - QSignalTransition *transition1 = state1->addTransition(button, - SIGNAL(clicked()), state2); - transition1->addAnimation(new QPropertyAnimation(button, "geometry")); - - QSignalTransition *transition2 = state2->addTransition(button, - SIGNAL(clicked()), state1); - transition2->addAnimation(new QPropertyAnimation(button, "geometry")); - - machine->start(); - \endcode - - For a more comprehensive example of how to use the state machine - framework for animations, see the states example (it lives in the - \c{examples/animation/states} directory). -*/ - diff --git a/doc/src/appicon.qdoc b/doc/src/appicon.qdoc deleted file mode 100644 index 901b854..0000000 --- a/doc/src/appicon.qdoc +++ /dev/null @@ -1,226 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/**************************************************************************** -** -** Qt Application Icon Usage Documentation. -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - -/*! - \page appicon.html - \title Setting the Application Icon - \ingroup gui-programming - - The application icon, typically displayed in the top-left corner of an - application's top-level windows, is set by calling the - QWidget::setWindowIcon() method on top-level widgets. - - In order to change the icon of the executable application file - itself, as it is presented on the desktop (i.e., prior to - application execution), it is necessary to employ another, - platform-dependent technique. - - \tableofcontents - - \section1 Setting the Application Icon on Windows - - First, create an ICO format bitmap file that contains the icon - image. This can be done with e.g. Microsoft Visual C++: Select - \menu{File|New}, then select the \menu{File} tab in the dialog - that appears, and choose \menu{Icon}. (Note that you do not need - to load your application into Visual C++; here we are only using - the icon editor.) - - Store the ICO file in your application's source code directory, - for example, with the name \c myappico.ico. Then, create a text - file called, say, \c myapp.rc in which you put a single line of - text: - - \snippet doc/src/snippets/code/doc_src_appicon.qdoc 0 - - Finally, assuming you are using \c qmake to generate your - makefiles, add this line to your \c myapp.pro file: - - \snippet doc/src/snippets/code/doc_src_appicon.qdoc 1 - - Regenerate your makefile and your application. The \c .exe file - will now be represented with your icon in Explorer. - - If you do not use \c qmake, the necessary steps are: first, run - the \c rc program on the \c .rc file, then link your application - with the resulting \c .res file. - - \section1 Setting the Application Icon on Mac OS X - - The application icon, typically displayed in the application dock - area, is set by calling QWidget::setWindowIcon() on a top-level - widget. It is possible that the program could appear in the - application dock area before the function call, in which case a - default icon will appear during the bouncing animation. - - To ensure that the correct icon appears, both when the application is - being launched, and in the Finder, it is necessary to employ a - platform-dependent technique. - - Although many programs can create icon files (\c .icns), the - recommended approach is to use the \e{Icon Composer} program - supplied by Apple (in the \c Developer/Application folder). - \e{Icon Composer} allows you to import several different sized - icons (for use in different contexts) as well as the masks that - go with them. Save the set of icons to a file in your project - directory. - - If you are using qmake to generate your makefiles, you only need - to add a single line to your \c .pro project file. For example, - if the name of your icon file is \c{myapp.icns}, and your project - file is \c{myapp.pro}, add this line to \c{myapp.pro}: - - \snippet doc/src/snippets/code/doc_src_appicon.qdoc 2 - - This will ensure that \c qmake puts your icons in the proper - place and creates an \c{Info.plist} entry for the icon. - - If you do not use \c qmake, you must do the following manually: - \list 1 - \i Create an \c Info.plist file for your application (using the - \c PropertyListEditor, found in \c Developer/Applications). - \i Associate your \c .icns record with the \c CFBundleIconFile record in the - \c Info.plist file (again, using the \c PropertyListEditor). - \i Copy the \c Info.plist file into your application bundle's \c Contents - directory. - \i Copy the \c .icns file into your application bundle's \c Contents/Resources - directory. - \endlist - - \section1 Setting the Application Icon on Common Linux Desktops - - In this section we briefly describe the issues involved in providing - icons for applications for two common Linux desktop environments: - \l{http://www.kde.org/}{KDE} and \l{http://www.gnome.org/}{GNOME}. - The core technology used to describe application icons - is the same for both desktops, and may also apply to others, but there - are details which are specific to each. The main source of information - on the standards used by these Linux desktops is - \l{http://www.freedesktop.org/}{freedesktop.org}. For information - on other Linux desktops please refer to the documentation for the - desktops you are interested in. - - Often, users do not use executable files directly, but instead launch - applications by clicking icons on the desktop. These icons are - representations of "desktop entry files" that contain a description of - the application that includes information about its icon. Both desktop - environments are able to retrieve the information in these files, and - they use it to generate shortcuts to applications on the desktop, in - the start menu, and on the panel. - - More information about desktop entry files can be found in the - \l{http://www.freedesktop.org/Standards/desktop-entry-spec}{Desktop Entry - Specification}. - - Although desktop entry files can usefully encapsulate the application's details, - we still need to store the icons in the conventional location for each desktop - environment. A number of locations for icons are given in the - \l{http://www.freedesktop.org/Standards/icon-theme-spec}{Icon Theme - Specification}. - - Although the path used to locate icons depends on the desktop in use, - and on its configuration, the directory structure beneath each of - these should follow the same pattern: subdirectories are arranged by - theme, icon size, and application type. Generally, application icons - are added to the hicolor theme, so a square application icon 32 pixels - in size would be stored in the \c hicolor/32x32/apps directory beneath - the icon path. - - \section2 K Desktop Environment (KDE) - - Application icons can be installed for use by all users, or on a per-user basis. - A user currently logged into their KDE desktop can discover these locations - by using \l{http://developer.kde.org/documentation/other/kde-config.html}{kde-config}, - for example, by typing the following in a terminal window: - - \snippet doc/src/snippets/code/doc_src_appicon.qdoc 3 - - Typically, the list of colon-separated paths printed to stdout includes the - user-specific icon path and the system-wide path. Beneath these - directories, it should be possible to locate and install icons according - to the conventions described in the - \l{http://www.freedesktop.org/Standards/icon-theme-spec}{Icon Theme Specification}. - - If you are developing exclusively for KDE, you may wish to take - advantage of the \link - http://developer.kde.org/documentation/other/makefile_am_howto.html - KDE build system\endlink to configure your application. This ensures - that your icons are installed in the appropriate locations for KDE. - - The KDE developer website is at \l{http://developer.kde.org/}. - - \section2 GNOME - - Application icons are stored within a standard system-wide - directory containing architecture-independent files. This - location can be determined by using \c gnome-config, for example - by typing the following in a terminal window: - - \snippet doc/src/snippets/code/doc_src_appicon.qdoc 4 - - The path printed on stdout refers to a location that should contain a directory - called \c{pixmaps}; the directory structure within the \c pixmaps - directory is described in the \link - http://www.freedesktop.org/Standards/icon-theme-spec Icon Theme - Specification \endlink. - - If you are developing exclusively for GNOME, you may wish to use - the standard set of \link - http://developer.gnome.org/tools/build.html GNU Build Tools\endlink, - also described in the relevant section of - the \link http://developer.gnome.org/doc/GGAD/ggad.html GTK+/Gnome - Application Development book\endlink. This ensures that your icons are - installed in the appropriate locations for GNOME. - - The GNOME developer website is at \l{http://developer.gnome.org/}. -*/ diff --git a/doc/src/assistant-manual.qdoc b/doc/src/assistant-manual.qdoc deleted file mode 100644 index 1b82b1a..0000000 --- a/doc/src/assistant-manual.qdoc +++ /dev/null @@ -1,810 +0,0 @@ -/**************************************************************************** -** -** 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 - \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 - \o Shows the specified dockwidget which can be "contents", "index", - "bookmarks" or "search". - \row - \o -hide - \o Hides the specified dockwidget which can be "contents", "index", - "bookmarks" or "search. - \row - \o -activate - \o Activates the specified dockwidget which can be "contents", - "index", "bookmarks" or "search. - \row - \o -register - \o Registers the specified compressed help file in the given help - collection. - \row - \o -unregister - \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{} - \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{QtHelp Module#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/atomic-operations.qdoc b/doc/src/atomic-operations.qdoc deleted file mode 100644 index d0f5978..0000000 --- a/doc/src/atomic-operations.qdoc +++ /dev/null @@ -1,89 +0,0 @@ -/**************************************************************************** -** -** 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 atomic-operations.html - \title Implementing Atomic Operations - \ingroup architecture - \ingroup qt-embedded-linux - \brief A guide to implementing atomic operations on new architectures. - - Qt uses an optimization called \l {Implicitly Shared - Classes}{implicit sharing} for many of its value classes. - - Starting with Qt 4, all of Qt's implicitly shared classes can - safely be copied across threads like any other value classes, - i.e., they are fully \l {Thread Support in Qt#Reentrancy and - Thread-Safety}{reentrant}. This is accomplished by implementing - reference counting operations using atomic hardware instructions - on all the different platforms supported by Qt. - - To support a new architecture, it is important to ensure that - these platform-specific atomic operations are implemented in a - corresponding header file (\c qatomic_ARCH.h), and that this file - is located in Qt's \c src/corelib/arch directory. For example, the - Intel 80386 implementation is located in \c - src/corelib/arch/qatomic_i386.h. - - Currently, Qt provides two classes providing several atomic - operations, QAtomicInt and QAtomicPointer. These classes inherit - from QBasicAtomicInt and QBasicAtomicPointer, respectively. - - When porting Qt to a new architecture, the QBasicAtomicInt and - QBasicAtomicPointer classes must be implemented, \e not QAtomicInt - and QAtomicPointer. The former classes do not have constructors, - which makes them POD (plain-old-data). Both classes only have a - single member variable called \c _q_value, which stores the - value. This is the value that all of the atomic operations read - and modify. - - All of the member functions mentioned in the QAtomicInt and - QAtomicPointer API documentation must be implemented. Note that - these the implementations of the atomic operations in these - classes must be atomic with respect to both interrupts and - multiple processors. - - \warning The QBasicAtomicInt and QBasicAtomicPointer classes - mentioned in this document are used internally by Qt and are not - part of the public API. They may change in future versions of - Qt. The purpose of this document is to aid people interested in - porting Qt to a new architecture. -*/ diff --git a/doc/src/bughowto.qdoc b/doc/src/bughowto.qdoc index b6520f3..645154b 100644 --- a/doc/src/bughowto.qdoc +++ b/doc/src/bughowto.qdoc @@ -43,7 +43,6 @@ \page bughowto.html \title How to Report a Bug \brief Information about ways to report bugs in Qt. - \ingroup howto If you think you have found a bug in Qt, we would like to hear about it so that we can fix it. diff --git a/doc/src/classes.qdoc b/doc/src/classes.qdoc index d9a0ae9..864445f 100644 --- a/doc/src/classes.qdoc +++ b/doc/src/classes.qdoc @@ -40,6 +40,18 @@ ****************************************************************************/ /*! + \group classlists + \title Class and Function Indexes + \brief Collections of classes and functions grouped together into lists. + + The following documents contain collections of classes, grouped by + subject area or related to particular functionality, or comprehensive + lists of classes and functions. + + \generatelist{related} +*/ + +/*! \group groups \title Grouped Classes \ingroup classlists @@ -56,11 +68,9 @@ \title Qt's Classes \ingroup classlists - This is a list of all Qt classes. For a shorter list of the most - frequently used Qt classes, see \l{Qt's Main Classes}. For a list - of the classes provided for compatibility with Qt3, see \l{Qt 3 - compatibility classes}. For classes that have been deprecated, see - the \l{Obsolete Classes} list. + This is a list of all Qt classes. For a list of the classes provided + for compatibility with Qt3, see \l{Qt 3 compatibility classes}. For + classes that have been deprecated, see the \l{Obsolete Classes} list. \generatelist classes @@ -128,17 +138,6 @@ */ /*! - \page mainclasses.html - \title Qt's Main Classes - \ingroup classlists - - These are the most frequently used Qt classes. For the complete - list see \link classes.html Qt's Classes \endlink. - - \generatelist mainclasses -*/ - -/*! \page compatclasses.html \title Qt 3 Compatibility Classes \ingroup classlists diff --git a/doc/src/classes/exportedfunctions.qdoc b/doc/src/classes/exportedfunctions.qdoc new file mode 100644 index 0000000..c51ace4 --- /dev/null +++ b/doc/src/classes/exportedfunctions.qdoc @@ -0,0 +1,139 @@ +/**************************************************************************** +** +** 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 exportedfunctions.html + \title Special-Purpose Global Functions Exported by Qt + \ingroup classlists + + Qt provides a few low-level global functions for fine-tuning + applications. Most of these perform very specific tasks and are + platform-specific. In general, we recommend that you try using + Qt's public API before resorting to using any functions mentioned + here. + + These functions are exported by \l QtCore and \l QtGui, but most + of them aren't declared in Qt's header files. To use them in your + application, you must declare them before calling them. For + example: + + \snippet doc/src/snippets/code/doc_src_exportedfunctions.qdoc 0 + + These functions will remain as part of Qt for the lifetime of Qt + 4. + + Functions: + + \tableofcontents + + \section1 void qt_set_library_config_file(const QString &\e{fileName}) + + Specifies the location of the Qt configuration file. You must + call this function before constructing a QApplication or + QCoreApplication object. If no location is specified, Qt + automatically finds an appropriate location. + + \section1 void qt_set_sequence_auto_mnemonic(bool \e{enable}) + + Specifies whether mnemonics for menu items, labels, etc., should + be honored or not. On Windows and X11, this feature is + on by default; on Mac OS X, it is off. When this feature is off, + the QKeySequence::mnemonic() function always returns an empty + string. This feature is also enabled on embedded Linux. + + \section1 void qt_x11_wait_for_window_manager(QWidget *\e{widget}) + + Blocks until the X11 window manager has shown the widget after a + call to QWidget::show(). + + \section1 void qt_mac_secure_keyboard(bool \e{enable}) + + Turns the Mac OS X secure keyboard feature on or off. QLineEdit + uses this when the echo mode is QLineEdit::Password or + QLineEdit::NoEcho to guard the editor against keyboard sniffing. + If you implement your own password editor, you might want to turn + on this feature in your editor's + \l{QWidget::focusInEvent()}{focusInEvent()} and turn it off in + \l{QWidget::focusOutEvent()}{focusOutEvent()}. + + \section1 void qt_mac_set_dock_menu(QMenu *\e{menu}) + + Sets the menu to display in the Mac OS X Dock for the + application. This menu is shown when the user attempts a + press-and-hold operation on the application's dock icon or + \key{Ctrl}-clicks on it while the application is running. + + The menu will be turned into a Mac menu and the items added to the default + Dock menu. There is no merging of the Qt menu items with the items that are + in the Dock menu (i.e., it is not recommended to include actions that + duplicate functionality of items already in the Dock menu). + + \section1 void qt_mac_set_menubar_icons(bool \e{enable}) + + Specifies whether icons associated to menu items for the + application's menu bar should be shown on Mac OS X. By default, + icons are shown on Mac OS X just like on the other platforms. + + In Qt 4.4, this is equivalent to + \c { QApplication::instance()->setAttribute(Qt::AA_DontShowIconsInMenus); }. + + \section1 void qt_mac_set_menubar_merge(bool \e{enable}) + + Specifies whether Qt should attempt to relocate standard menu + items (such as \gui Quit, \gui Preferences, and \gui About) to + the application menu on Mac OS X. This feature is on by default. + See \l{Qt for Mac OS X - Specific Issues} for the list of menu items for + which this applies. + + \section1 void qt_mac_set_native_menubar(bool \e{enable}) + + Specifies whether the application should use the native menu bar + on Mac OS X or be part of the main window. This feature is on by + default. + + In Qt 4.6, this is equivalent to + \c { QApplication::instance()->setAttribute(Qt::AA_DontUseNativeMenuBar); }. + + \section1 void qt_mac_set_press_and_hold_context(bool \e{enable}) + + Turns emulation of the right mouse button by clicking and holding + the left mouse button on or off. This feature is off by default. +*/ diff --git a/doc/src/classes/phonon-namespace.qdoc b/doc/src/classes/phonon-namespace.qdoc new file mode 100644 index 0000000..8007ddf --- /dev/null +++ b/doc/src/classes/phonon-namespace.qdoc @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \namespace Phonon + \brief The Phonon namespace contains classes and functions for multimedia applications. + \since 4.4 + + This namespace contains classes to access multimedia functions for + audio and video playback. Those classes are not dependent on any specific + framework, but rather use exchangeable backends to do the work. + + See the \l{Phonon Module} page for general information about the + framework and the \l{Phonon Overview} for an introductory tour of its + features. +*/ diff --git a/doc/src/classes/q3asciicache.qdoc b/doc/src/classes/q3asciicache.qdoc deleted file mode 100644 index b86113f..0000000 --- a/doc/src/classes/q3asciicache.qdoc +++ /dev/null @@ -1,465 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3AsciiCache - \brief The Q3AsciiCache class is a template class that provides a cache based on char* keys. - \compat - - Q3AsciiCache is implemented as a template class. Define a template - instance Q3AsciiCache\<X\> to create a cache that operates on - pointers to X (X*). - - A cache is a least recently used (LRU) list of cache items. The - cache items are accessed via \c char* keys. For Unicode keys use - the Q3Cache template instead, which uses QString keys. A Q3Cache - has the same performace as a Q3AsciiCache. - - Each cache item has a cost. The sum of item costs, totalCost(), - will not exceed the maximum cache cost, maxCost(). If inserting a - new item would cause the total cost to exceed the maximum cost, - the least recently used items in the cache are removed. - - Apart from insert(), by far the most important function is find() - (which also exists as operator[]()). This function looks up an - item, returns it, and by default marks it as being the most - recently used item. - - There are also methods to remove() or take() an object from the - cache. Calling \link Q3PtrCollection::setAutoDelete() - setAutoDelete(TRUE)\endlink tells the cache to delete items that - are removed. The default is to not delete items when then are - removed (i.e., remove() and take() are equivalent). - - When inserting an item into the cache, only the pointer is copied, - not the item itself. This is called a shallow copy. It is possible - to make the cache copy all of the item's data (known as a deep - copy) when an item is inserted. insert() calls the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a cache and reimplement newItem() if you want deep copies. - - When removing a cache item the virtual function - Q3PtrCollection::deleteItem() is called. Its default implementation - in Q3AsciiCache is to delete the item if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - There is a Q3AsciiCacheIterator which may be used to traverse the - items in the cache in arbitrary order. - - \sa Q3AsciiCacheIterator, Q3Cache, Q3IntCache -*/ - -/*! - \fn Q3AsciiCache::Q3AsciiCache( const Q3AsciiCache<type> &c ) - - \internal - - Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. -*/ - - -/*! - \fn Q3AsciiCache::Q3AsciiCache( int maxCost, int size, bool caseSensitive, bool copyKeys ) - - Constructs a cache whose contents will never have a total cost - greater than \a maxCost and which is expected to contain less than - \a size items. - - \a size is actually the size of an internal hash array; it's - usually best to make it prime and at least 50% bigger than the - largest expected number of items in the cache. - - Each inserted item has an associated cost. When inserting a new - item, if the total cost of all items in the cache will exceed \a - maxCost, the cache will start throwing out the older (least - recently used) items until there is enough room for the new item - to be inserted. - - If \a caseSensitive is TRUE (the default), the cache keys are case - sensitive; if it is FALSE, they are case-insensitive. - Case-insensitive comparison only affects the 26 letters in - US-ASCII. If \a copyKeys is TRUE (the default), Q3AsciiCache makes - a copy of the cache keys, otherwise it copies just the const char - * pointer - slightly faster if you can guarantee that the keys - will never change, but very risky. -*/ - -/*! - \fn Q3AsciiCache::~Q3AsciiCache() - - Removes all items from the cache and destroys it. - All iterators that access this cache will be reset. -*/ - -/*! - \fn Q3AsciiCache<type>& Q3AsciiCache::operator=( const Q3AsciiCache<type> &c ) - - \internal - - Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version. -*/ - -/*! - \fn int Q3AsciiCache::maxCost() const - - Returns the maximum allowed total cost of the cache. - - \sa setMaxCost() totalCost() -*/ - -/*! - \fn int Q3AsciiCache::totalCost() const - - Returns the total cost of the items in the cache. This is an - integer in the range 0 to maxCost(). - - \sa setMaxCost() -*/ - -/*! - \fn void Q3AsciiCache::setMaxCost( int m ) - - Sets the maximum allowed total cost of the cache to \a m. If the - current total cost is greater than \a m, some items are removed - immediately. - - \sa maxCost() totalCost() -*/ - -/*! - \fn uint Q3AsciiCache::count() const - - Returns the number of items in the cache. - - \sa totalCost() size() -*/ - -/*! - \fn uint Q3AsciiCache::size() const - - Returns the size of the hash array used to implement the cache. - This should be a bit bigger than count() is likely to be. -*/ - -/*! - \fn bool Q3AsciiCache::isEmpty() const - - Returns TRUE if the cache is empty; otherwise returns FALSE. -*/ - -/*! - \fn bool Q3AsciiCache::insert( const char *k, const type *d, int c, int p ) - - Inserts the item \a d into the cache using key \a k, and with an - associated cost of \a c. Returns TRUE if the item is successfully - inserted. Returns FALSE if the item is not inserted, for example, - if the cost of the item exceeds maxCost(). - - The cache's size is limited, and if the total cost is too high, - Q3AsciiCache will remove old, least recently used items until there - is room for this new item. - - Items with duplicate keys can be inserted. - - The parameter \a p is internal and should be left at the default - value (0). - - \warning If this function returns FALSE, you must delete \a d - yourself. Additionally, be very careful about using \a d after - calling this function, because any other insertions into the - cache, from anywhere in the application or within Qt itself, could - cause the object to be discarded from the cache and the pointer to - become invalid. -*/ - -/*! - \fn bool Q3AsciiCache::remove( const char *k ) - - Removes the item with key \a k and returns TRUE if the item was - present in the cache; otherwise returns FALSE. - - The item is deleted if auto-deletion has been enabled, i.e., if - you have called \link Q3PtrCollection::setAutoDelete() - setAutoDelete(TRUE)\endlink. - - If there are two or more items with equal keys, the one that was - inserted last is removed. - - All iterators that refer to the removed item are set to point to - the next item in the cache's traversal order. - - \sa take(), clear() -*/ - -/*! - \fn type *Q3AsciiCache::take( const char *k ) - - Takes the item associated with \a k out of the cache without - deleting it and returns a pointer to the item taken out, or 0 - if the key does not exist in the cache. - - If there are two or more items with equal keys, the one that was - inserted last is taken. - - All iterators that refer to the taken item are set to point to the - next item in the cache's traversal order. - - \sa remove(), clear() -*/ - -/*! - \fn void Q3AsciiCache::clear() - - Removes all items from the cache, and deletes them if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink has been - enabled. - - All cache iterators that operate on this cache are reset. - - \sa remove() take() -*/ - -/*! - \fn type *Q3AsciiCache::find( const char *k, bool ref ) const - - Returns the item with key \a k, or 0 if the key does not exist - in the cache. If \a ref is TRUE (the default), the item is moved - to the front of the least recently used list. - - If there are two or more items with equal keys, the one that was - inserted last is returned. -*/ - -/*! - \fn type *Q3AsciiCache::operator[]( const char *k ) const - - Returns the item with key \a k, or 0 if \a k does not exist in - the cache, and moves the item to the front of the least recently - used list. - - If there are two or more items with equal keys, the one that was - inserted last is returned. - - This is the same as find( k, TRUE ). - - \sa find() -*/ - -/*! - \fn void Q3AsciiCache::statistics() const - - A debug-only utility function. Prints out cache usage, hit/miss, - and distribution information using qDebug(). This function does - nothing in the release library. -*/ - -/*! - \class Q3AsciiCacheIterator - \brief The Q3AsciiCacheIterator class provides an iterator for Q3AsciiCache collections. - \compat - - Note that the traversal order is arbitrary; you are not guaranteed - any particular order. If new objects are inserted into the cache - while the iterator is active, the iterator may or may not see - them. - - Multiple iterators are completely independent, even when they - operate on the same Q3AsciiCache. Q3AsciiCache updates all iterators - that refer an item when that item is removed. - - Q3AsciiCacheIterator provides an operator++() and an operator+=() - to traverse the cache; current() and currentKey() to access the - current cache item and its key. It also provides atFirst() and - atLast(), which return TRUE if the iterator points to the first or - last item in the cache respectively. The isEmpty() function - returns TRUE if the cache is empty; and count() returns the number - of items in the cache. - - Note that atFirst() and atLast() refer to the iterator's arbitrary - ordering, not to the cache's internal least recently used list. - - \sa Q3AsciiCache -*/ - -/*! - \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator( const Q3AsciiCache<type> &cache ) - - Constructs an iterator for \a cache. The current iterator item is - set to point to the first item in the \a cache. -*/ - -/*! - \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator (const Q3AsciiCacheIterator<type> & ci) - - Constructs an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current() but moves - independently from there on. -*/ - -/*! - \fn Q3AsciiCacheIterator<type>& Q3AsciiCacheIterator::operator=( const Q3AsciiCacheIterator<type> &ci ) - - Makes this an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently thereafter. -*/ - -/*! - \fn uint Q3AsciiCacheIterator::count() const - - Returns the number of items in the cache over which this iterator - operates. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3AsciiCacheIterator::isEmpty() const - - Returns TRUE if the cache is empty, i.e. count() == 0; otherwise - returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3AsciiCacheIterator::atFirst() const - - Returns TRUE if the iterator points to the first item in the - cache; otherwise returns FALSE. Note that this refers to the - iterator's arbitrary ordering, not to the cache's internal least - recently used list. - - \sa toFirst(), atLast() -*/ - -/*! - \fn bool Q3AsciiCacheIterator::atLast() const - - Returns TRUE if the iterator points to the last item in the cache; - otherwise returns FALSE. Note that this refers to the iterator's - arbitrary ordering, not to the cache's internal least recently - used list. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3AsciiCacheIterator::toFirst() - - Sets the iterator to point to the first item in the cache and - returns a pointer to the item. - - Sets the iterator to 0 and returns 0 if the cache is empty. - - \sa toLast() isEmpty() -*/ - -/*! - \fn type *Q3AsciiCacheIterator::toLast() - - Sets the iterator to point to the last item in the cache and - returns a pointer to the item. - - Sets the iterator to 0 and returns 0 if the cache is empty. - - \sa toFirst() isEmpty() -*/ - -/*! - \fn Q3AsciiCacheIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3AsciiCacheIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn const char *Q3AsciiCacheIterator::currentKey() const - - Returns the key for the current iterator item. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the cache or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator+=( uint jump ) - - Returns the item \a jump positions after the current item, or 0 - if it is beyond the last item. Makes this the current item. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator-=( uint jump ) - - Returns the item \a jump positions before the current item, or 0 - if it is before the first item. Makes this the current item. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator++() - - Prefix ++ makes the iterator point to the item just after - current(), and makes that the new current item for the iterator. If - current() was the last item, operator++() returns 0. -*/ - -/*! - \fn type *Q3AsciiCacheIterator::operator--() - - Prefix -- makes the iterator point to the item just before - current(), and makes that the new current item for the iterator. If - current() was the first item, operator--() returns 0. -*/ - diff --git a/doc/src/classes/q3asciidict.qdoc b/doc/src/classes/q3asciidict.qdoc deleted file mode 100644 index 1262a37..0000000 --- a/doc/src/classes/q3asciidict.qdoc +++ /dev/null @@ -1,416 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3AsciiDict - \brief The Q3AsciiDict class is a template class that provides a dictionary based on char* keys. - \compat - - Q3AsciiDict is implemented as a template class. Define a template - instance Q3AsciiDict\<X\> to create a dictionary that operates on - pointers to X (X*). - - A dictionary is a collection of key-value pairs. The key is a - char* used for insertion, removal and lookup. The value is a - pointer. Dictionaries provide very fast insertion and lookup. - - Q3AsciiDict cannot handle Unicode keys; use the Q3Dict template - instead, which uses QString keys. A Q3Dict has the same - performace as a Q3AsciiDict. - - Example: - \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 0 - In this example we use a dictionary to keep track of the line - edits we're using. We insert each line edit into the dictionary - with a unique name and then access the line edits via the - dictionary. See Q3PtrDict, Q3IntDict and Q3Dict. - - See Q3Dict for full details, including the choice of dictionary - size, and how deletions are handled. - - \sa Q3AsciiDictIterator, Q3Dict, Q3IntDict, Q3PtrDict -*/ - - -/*! - \fn Q3AsciiDict::Q3AsciiDict( int size, bool caseSensitive, bool copyKeys ) - - Constructs a dictionary optimized for less than \a size entries. - - We recommend setting \a size to a suitably large prime number (a - bit larger than the expected number of entries). This makes the - hash distribution better and will improve lookup performance. - - When \a caseSensitive is TRUE (the default) Q3AsciiDict treats - "abc" and "Abc" as different keys; when it is FALSE "abc" and - "Abc" are the same. Case-insensitive comparison only considers the - 26 letters in US-ASCII. - - If \a copyKeys is TRUE (the default), the dictionary copies keys - using strcpy(); if it is FALSE, the dictionary just copies the - pointers. -*/ - -/*! - \fn Q3AsciiDict::Q3AsciiDict( const Q3AsciiDict<type> &dict ) - - Constructs a copy of \a dict. - - Each item in \a dict is inserted into this dictionary. Only the - pointers are copied (shallow copy). -*/ - -/*! - \fn Q3AsciiDict::~Q3AsciiDict() - - Removes all items from the dictionary and destroys it. - - The items are deleted if auto-delete is enabled. - - All iterators that access this dictionary will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3AsciiDict<type> &Q3AsciiDict::operator=(const Q3AsciiDict<type> &dict) - - Assigns \a dict to this dictionary and returns a reference to this - dictionary. - - This dictionary is first cleared and then each item in \a dict is - inserted into this dictionary. Only the pointers are copied - (shallow copy) unless newItem() has been reimplemented(). -*/ - -/*! - \fn uint Q3AsciiDict::count() const - - Returns the number of items in the dictionary. - - \sa isEmpty() -*/ - -/*! - \fn uint Q3AsciiDict::size() const - - Returns the size of the internal hash array (as specified in the - constructor). - - \sa count() -*/ - -/*! - \fn void Q3AsciiDict::resize( uint newsize ) - - Changes the size of the hashtable to \a newsize. The contents of - the dictionary are preserved but all iterators on the dictionary - become invalid. -*/ - -/*! - \fn bool Q3AsciiDict::isEmpty() const - - Returns TRUE if the dictionary is empty, i.e. count() == 0; - otherwise it returns FALSE. - - \sa count() -*/ - -/*! - \fn void Q3AsciiDict::insert( const char *key, const type *item ) - - Inserts the \a key with the \a item into the dictionary. - - Multiple items can have the same key, in which case only the last - item will be accessible using \l operator[](). - - \a item may not be 0. - - \sa replace() -*/ - -/*! - \fn void Q3AsciiDict::replace( const char *key, const type *item ) - - Replaces an item that has a key equal to \a key with \a item. - - If the item does not already exist, it will be inserted. - - \a item may not be 0. - - Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 1 - - If there are two or more items with equal keys, then the most - recently inserted item will be replaced. - - \sa insert() -*/ - -/*! - \fn bool Q3AsciiDict::remove( const char *key ) - - Removes the item associated with \a key from the dictionary. - Returns TRUE if successful, i.e. if the key existed in the - dictionary; otherwise returns FALSE. - - If there are two or more items with equal keys, then the most - recently inserted item will be removed. - - The removed item is deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that refer to the removed item will be - set to point to the next item in the dictionary traversal order. - - \sa take(), clear(), setAutoDelete() -*/ - -/*! - \fn type *Q3AsciiDict::take( const char *key ) - - Takes the item associated with \a key out of the dictionary - without deleting it (even if \link Q3PtrCollection::setAutoDelete() - auto-deletion\endlink is enabled). - - If there are two or more items with equal keys, then the most - recently inserted item will be taken. - - Returns a pointer to the item taken out, or 0 if the key does not - exist in the dictionary. - - All dictionary iterators that refer to the taken item will be set - to point to the next item in the dictionary traversal order. - - \sa remove(), clear(), setAutoDelete() -*/ - -/*! - \fn void Q3AsciiDict::clear() - - Removes all items from the dictionary. - - The removed items are deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that operate on dictionary are reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn type *Q3AsciiDict::find( const char *key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - This function uses an internal hashing algorithm to optimize - lookup. - - If there are two or more items with equal keys, then the item that - was most recently inserted will be found. - - Equivalent to the [] operator. - - \sa operator[]() -*/ - -/*! - \fn type *Q3AsciiDict::operator[]( const char *key ) const - - Returns the item associated with \a key, or 0 if the key does - not exist in the dictionary. - - This function uses an internal hashing algorithm to optimize - lookup. - - If there are two or more items with equal keys, then the item that - was most recently inserted will be found. - - Equivalent to the find() function. - - \sa find() -*/ - -/*! - \fn void Q3AsciiDict::statistics() const - - Debugging-only function that prints out the dictionary - distribution using qDebug(). -*/ - -/*! - \fn QDataStream& Q3AsciiDict::read( QDataStream &s, - Q3PtrCollection::Item &item ) - - Reads a dictionary item from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3AsciiDict::write(QDataStream &s, Q3PtrCollection::Item item) const - - Writes a dictionary \a item to the stream \a s and returns a - reference to the stream. - - \sa read() -*/ - -/*! - \class Q3AsciiDictIterator - \brief The Q3AsciiDictIterator class provides an iterator for Q3AsciiDict collections. - \compat - - Q3AsciiDictIterator is implemented as a template class. Define a - template instance Q3AsciiDictIterator\<X\> to create a dictionary - iterator that operates on Q3AsciiDict\<X\> (dictionary of X*). - - Example: - \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 2 - In the example we insert some line edits into a dictionary, then - iterate over the dictionary printing the strings associated with - those line edits. - - Note that the traversal order is arbitrary; you are not guaranteed - any particular order. - - Multiple iterators may independently traverse the same dictionary. - A Q3AsciiDict knows about all the iterators that are operating on - the dictionary. When an item is removed from the dictionary, - Q3AsciiDict updates all the iterators that are referring to the - removed item to point to the next item in the (arbitrary) - traversal order. - - \sa Q3AsciiDict -*/ - -/*! - \fn Q3AsciiDictIterator::Q3AsciiDictIterator( const Q3AsciiDict<type> &dict ) - - Constructs an iterator for \a dict. The current iterator item is - set to point on the first item in the \a dict. -*/ - -/*! - \fn Q3AsciiDictIterator::~Q3AsciiDictIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3AsciiDictIterator::count() const - - Returns the number of items in the dictionary this iterator - operates over. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3AsciiDictIterator::isEmpty() const - - Returns TRUE if the dictionary is empty, i.e. count() == 0, - otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn type *Q3AsciiDictIterator::toFirst() - - Sets the current iterator item to point to the first item in the - dictionary and returns a pointer to the item. If the dictionary is - empty it sets the current item to 0 and returns 0. -*/ - -/*! - \fn Q3AsciiDictIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3AsciiDictIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn const char *Q3AsciiDictIterator::currentKey() const - - Returns a pointer to the key for the current iterator item. -*/ - -/*! - \fn type *Q3AsciiDictIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3AsciiDictIterator::operator++() - - Prefix ++ makes the succeeding item current and returns the new - current item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3AsciiDictIterator::operator+=( uint jump ) - - Sets the current item to the item \a jump positions after the - current item, and returns a pointer to that item. - - If that item is beyond the last item or if the dictionary is - empty, it sets the current item to 0 and returns 0. -*/ diff --git a/doc/src/classes/q3cache.qdoc b/doc/src/classes/q3cache.qdoc deleted file mode 100644 index 20b777f..0000000 --- a/doc/src/classes/q3cache.qdoc +++ /dev/null @@ -1,461 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3Cache - \brief The Q3Cache class is a template class that provides a cache based on QString keys. - \compat - - A cache is a least recently used (LRU) list of cache items. Each - cache item has a key and a certain cost. The sum of item costs, - totalCost(), never exceeds the maximum cache cost, maxCost(). If - inserting a new item would cause the total cost to exceed the - maximum cost, the least recently used items in the cache are - removed. - - Q3Cache is a template class. Q3Cache\<X\> defines a cache that - operates on pointers to X, or X*. - - Apart from insert(), by far the most important function is find() - (which also exists as operator[]()). This function looks up an - item, returns it, and by default marks it as being the most - recently used item. - - There are also methods to remove() or take() an object from the - cache. Calling setAutoDelete(TRUE) for a cache tells it to delete - items that are removed. The default is to not delete items when - they are removed (i.e., remove() and take() are equivalent). - - When inserting an item into the cache, only the pointer is copied, - not the item itself. This is called a shallow copy. It is possible - to make the cache copy all of the item's data (known as a deep - copy) when an item is inserted. insert() calls the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a cache and reimplement newItem() if you want deep copies. - - When removing a cache item, the virtual function - Q3PtrCollection::deleteItem() is called. The default - implementation deletes the item if auto-deletion is enabled, and - does nothing otherwise. - - There is a Q3CacheIterator that can be used to traverse the items - in the cache in arbitrary order. - - In Q3Cache, the cache items are accessed via QString keys, which - are Unicode strings. If you want to use non-Unicode, plain 8-bit - \c char* keys, use the Q3AsciiCache template. A Q3Cache has the - same performance as a Q3AsciiCache. - - \sa Q3CacheIterator, Q3AsciiCache, Q3IntCache -*/ - -/*! - \fn Q3Cache::Q3Cache( const Q3Cache<type> &c ) - - \internal - - Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. -*/ - - -/*! - \fn Q3Cache::Q3Cache( int maxCost, int size, bool caseSensitive ) - - Constructs a cache whose contents will never have a total cost - greater than \a maxCost and which is expected to contain less than - \a size items. - - \a size is actually the size of an internal hash array; it's - usually best to make it a prime number and at least 50% bigger - than the largest expected number of items in the cache. - - Each inserted item has an associated cost. When inserting a new - item, if the total cost of all items in the cache will exceed \a - maxCost, the cache will start throwing out the older (least - recently used) items until there is enough room for the new item - to be inserted. - - If \a caseSensitive is TRUE (the default), the cache keys are case - sensitive; if it is FALSE, they are case-insensitive. - Case-insensitive comparison considers all Unicode letters. -*/ - -/*! - \fn Q3Cache::~Q3Cache() - - Removes all items from the cache and destroys it. All iterators - that access this cache will be reset. -*/ - -/*! - \fn Q3Cache<type>& Q3Cache::operator=( const Q3Cache<type> &c ) - - \internal - - Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. -*/ - -/*! - \fn int Q3Cache::maxCost() const - - Returns the maximum allowed total cost of the cache. - - \sa setMaxCost() totalCost() -*/ - -/*! - \fn int Q3Cache::totalCost() const - - Returns the total cost of the items in the cache. This is an - integer in the range 0 to maxCost(). - - \sa setMaxCost() -*/ - -/*! - \fn void Q3Cache::setMaxCost( int m ) - - Sets the maximum allowed total cost of the cache to \a m. If the - current total cost is greater than \a m, some items are deleted - immediately. - - \sa maxCost() totalCost() -*/ - -/*! - \fn uint Q3Cache::count() const - - Returns the number of items in the cache. - - \sa totalCost() -*/ - -/*! - \fn uint Q3Cache::size() const - - Returns the size of the hash array used to implement the cache. - This should be a bit bigger than count() is likely to be. -*/ - -/*! - \fn bool Q3Cache::isEmpty() const - - Returns TRUE if the cache is empty; otherwise returns FALSE. -*/ - -/*! - \fn bool Q3Cache::insert( const QString &k, const type *d, int c, int p ) - - Inserts the item \a d into the cache with key \a k and associated - cost, \a c. Returns TRUE if it is successfully inserted; otherwise - returns FALSE. - - The cache's size is limited, and if the total cost is too high, - Q3Cache will remove old, least recently used items until there is - room for this new item. - - The parameter \a p is internal and should be left at the default - value (0). - - \warning If this function returns FALSE (which could happen, e.g. - if the cost of this item alone exceeds maxCost()) you must delete - \a d yourself. Additionally, be very careful about using \a d - after calling this function because any other insertions into the - cache, from anywhere in the application or within Qt itself, could - cause the object to be discarded from the cache and the pointer to - become invalid. -*/ - -/*! - \fn bool Q3Cache::remove( const QString &k ) - - Removes the item associated with \a k, and returns TRUE if the - item was present in the cache; otherwise returns FALSE. - - The item is deleted if auto-deletion has been enabled, i.e., if - you have called setAutoDelete(TRUE). - - If there are two or more items with equal keys, the one that was - inserted last is removed. - - All iterators that refer to the removed item are set to point to - the next item in the cache's traversal order. - - \sa take(), clear() -*/ - -/*! - \fn type *Q3Cache::take( const QString &k ) - - Takes the item associated with \a k out of the cache without - deleting it, and returns a pointer to the item taken out, or 0 - if the key does not exist in the cache. - - If there are two or more items with equal keys, the one that was - inserted last is taken. - - All iterators that refer to the taken item are set to point to the - next item in the cache's traversal order. - - \sa remove(), clear() -*/ - -/*! - \fn void Q3Cache::clear() - - Removes all items from the cache and deletes them if auto-deletion - has been enabled. - - All cache iterators that operate this on cache are reset. - - \sa remove() take() -*/ - -/*! - \fn type *Q3Cache::find( const QString &k, bool ref ) const - - Returns the item associated with key \a k, or 0 if the key does - not exist in the cache. If \a ref is TRUE (the default), the item - is moved to the front of the least recently used list. - - If there are two or more items with equal keys, the one that was - inserted last is returned. -*/ - -/*! - \fn type *Q3Cache::operator[]( const QString &k ) const - - Returns the item associated with key \a k, or 0 if \a k does not - exist in the cache, and moves the item to the front of the least - recently used list. - - If there are two or more items with equal keys, the one that was - inserted last is returned. - - This is the same as find( k, TRUE ). - - \sa find() -*/ - -/*! - \fn void Q3Cache::statistics() const - - A debug-only utility function. Prints out cache usage, hit/miss, - and distribution information using qDebug(). This function does - nothing in the release library. -*/ - -/***************************************************************************** - Q3CacheIterator documentation - *****************************************************************************/ - -/*! - \class Q3CacheIterator qcache.h - \brief The Q3CacheIterator class provides an iterator for Q3Cache collections. - \compat - - Note that the traversal order is arbitrary; you are not guaranteed - any particular order. If new objects are inserted into the cache - while the iterator is active, the iterator may or may not see - them. - - Multiple iterators are completely independent, even when they - operate on the same Q3Cache. Q3Cache updates all iterators that - refer an item when that item is removed. - - Q3CacheIterator provides an operator++(), and an operator+=() to - traverse the cache. The current() and currentKey() functions are - used to access the current cache item and its key. The atFirst() - and atLast() return TRUE if the iterator points to the first or - last item in the cache respectively. The isEmpty() function - returns TRUE if the cache is empty, and count() returns the number - of items in the cache. - - Note that atFirst() and atLast() refer to the iterator's arbitrary - ordering, not to the cache's internal least recently used list. - - \sa Q3Cache -*/ - -/*! - \fn Q3CacheIterator::Q3CacheIterator( const Q3Cache<type> &cache ) - - Constructs an iterator for \a cache. The current iterator item is - set to point to the first item in the \a cache. -*/ - -/*! - \fn Q3CacheIterator::Q3CacheIterator (const Q3CacheIterator<type> & ci) - - Constructs an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently from there on. -*/ - -/*! - \fn Q3CacheIterator<type>& Q3CacheIterator::operator=( const Q3CacheIterator<type> &ci ) - - Makes this an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently thereafter. -*/ - -/*! - \fn uint Q3CacheIterator::count() const - - Returns the number of items in the cache on which this iterator - operates. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3CacheIterator::isEmpty() const - - Returns TRUE if the cache is empty, i.e. count() == 0; otherwise - it returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3CacheIterator::atFirst() const - - Returns TRUE if the iterator points to the first item in the - cache; otherwise returns FALSE. Note that this refers to the - iterator's arbitrary ordering, not to the cache's internal least - recently used list. - - \sa toFirst(), atLast() -*/ - -/*! - \fn bool Q3CacheIterator::atLast() const - - Returns TRUE if the iterator points to the last item in the cache; - otherwise returns FALSE. Note that this refers to the iterator's - arbitrary ordering, not to the cache's internal least recently - used list. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3CacheIterator::toFirst() - - Sets the iterator to point to the first item in the cache and - returns a pointer to the item. - - Sets the iterator to 0 and returns 0 if the cache is empty. - - \sa toLast() isEmpty() -*/ - -/*! - \fn type *Q3CacheIterator::toLast() - - Sets the iterator to point to the last item in the cache and - returns a pointer to the item. - - Sets the iterator to 0 and returns 0 if the cache is empty. - - \sa toFirst() isEmpty() -*/ - -/*! - \fn Q3CacheIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3CacheIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn QString Q3CacheIterator::currentKey() const - - Returns the key for the current iterator item. -*/ - -/*! - \fn type *Q3CacheIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the cache or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3CacheIterator::operator+=( uint jump ) - - Returns the item \a jump positions after the current item, or 0 if - it is beyond the last item. Makes this the current item. -*/ - -/*! - \fn type *Q3CacheIterator::operator-=( uint jump ) - - Returns the item \a jump positions before the current item, or 0 - if it is before the first item. Makes this the current item. -*/ - -/*! - \fn type *Q3CacheIterator::operator++() - - Prefix++ makes the iterator point to the item just after current() - and makes that the new current item for the iterator. If current() - was the last item, operator++() returns 0. -*/ - -/*! - \fn type *Q3CacheIterator::operator--() - - Prefix-- makes the iterator point to the item just before - current() and makes that the new current item for the iterator. If - current() was the first item, operator--() returns 0. -*/ - diff --git a/doc/src/classes/q3dict.qdoc b/doc/src/classes/q3dict.qdoc deleted file mode 100644 index 2234c2d..0000000 --- a/doc/src/classes/q3dict.qdoc +++ /dev/null @@ -1,446 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3Dict - \brief The Q3Dict class is a template class that provides a - dictionary based on QString keys. - \compat - - Q3Dict is implemented as a template class. Define a template - instance Q3Dict\<X\> to create a dictionary that operates on - pointers to X (X *). - - A dictionary is a collection of key-value pairs. The key is a - QString used for insertion, removal and lookup. The value is a - pointer. Dictionaries provide very fast insertion and lookup. - - If you want to use non-Unicode, plain 8-bit \c char* keys, use the - Q3AsciiDict template. A Q3Dict has the same performance as a - Q3AsciiDict. If you want to have a dictionary that maps QStrings to - QStrings use QMap. - - The size() of the dictionary is very important. In order to get - good performance, you should use a suitably large prime number. - Suitable means equal to or larger than the maximum expected number - of dictionary items. Size is set in the constructor but may be - changed with resize(). - - Items are inserted with insert(); 0 pointers cannot be inserted. - Items are removed with remove(). All the items in a dictionary can - be removed with clear(). The number of items in the dictionary is - returned by count(). If the dictionary contains no items isEmpty() - returns TRUE. You can change an item's value with replace(). Items - are looked up with operator[](), or with find() which return a - pointer to the value or 0 if the given key does not exist. You can - take an item out of the dictionary with take(). - - Calling setAutoDelete(TRUE) for a dictionary tells it to delete - items that are removed. The default behavior is not to delete - items when they are removed. - - When an item is inserted, the key is converted (hashed) to an - integer index into an internal hash array. This makes lookup very - fast. - - Items with equal keys are allowed. When inserting two items with - the same key, only the last inserted item will be accessible (last - in, first out) until it is removed. - - The Q3DictIterator class can traverse the dictionary, but only in - an arbitrary order. Multiple iterators may independently traverse - the same dictionary. - - When inserting an item into a dictionary, only the pointer is - copied, not the item itself, i.e. a shallow copy is made. It is - possible to make the dictionary copy all of the item's data (a - deep copy) when an item is inserted. insert() calls the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a dictionary and reimplement newItem() if you want deep - copies. - - When removing a dictionary item, the virtual function - Q3PtrCollection::deleteItem() is called. Q3Dict's default - implementation is to delete the item if auto-deletion is enabled. - - \sa Q3DictIterator, Q3AsciiDict, Q3IntDict, Q3PtrDict -*/ - - -/*! - \fn Q3Dict::Q3Dict( int size, bool caseSensitive ) - - Constructs a dictionary optimized for less than \a size entries. - - We recommend setting \a size to a suitably large prime number - (e.g. a prime that's slightly larger than the expected number of - entries). This makes the hash distribution better which will lead - to faster lookup. - - If \a caseSensitive is TRUE (the default), keys which differ only - by case are considered different. -*/ - -/*! - \fn Q3Dict::Q3Dict( const Q3Dict<type> &dict ) - - Constructs a copy of \a dict. - - Each item in \a dict is inserted into this dictionary. Only the - pointers are copied (shallow copy). -*/ - -/*! - \fn Q3Dict::~Q3Dict() - - Removes all items from the dictionary and destroys it. If - setAutoDelete() is TRUE, each value is deleted. All iterators that - access this dictionary will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3Dict<type> &Q3Dict::operator=(const Q3Dict<type> &dict) - - Assigns \a dict to this dictionary and returns a reference to this - dictionary. - - This dictionary is first cleared, then each item in \a dict is - inserted into this dictionary. Only the pointers are copied - (shallow copy), unless newItem() has been reimplemented. -*/ - -/*! - \fn uint Q3Dict::count() const - - Returns the number of items in the dictionary. - - \sa isEmpty() -*/ - -/*! - \fn uint Q3Dict::size() const - - Returns the size of the internal hash array (as specified in the - constructor). - - \sa count() -*/ - -/*! - \fn void Q3Dict::resize( uint newsize ) - - Changes the size of the hash table to \a newsize. The contents of - the dictionary are preserved, but all iterators on the dictionary - become invalid. -*/ - -/*! - \fn bool Q3Dict::isEmpty() const - - Returns TRUE if the dictionary is empty, i.e. count() == 0; - otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn void Q3Dict::insert( const QString &key, const type *item ) - - Inserts the key \a key with value \a item into the dictionary. - - Multiple items can have the same key, in which case only the last - item will be accessible using \l operator[](). - - \a item may not be 0. - - \sa replace() -*/ - -/*! - \fn void Q3Dict::replace( const QString &key, const type *item ) - - Replaces the value of the key, \a key with \a item. - - If the item does not already exist, it will be inserted. - - \a item may not be 0. - - Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 0 - - If there are two or more items with equal keys, then the last item - that was inserted will be replaced. - - \sa insert() -*/ - -/*! - \fn bool Q3Dict::remove( const QString &key ) - - Removes the item with \a key from the dictionary. Returns TRUE if - successful, i.e. if the item is in the dictionary; otherwise - returns FALSE. - - If there are two or more items with equal keys, then the last item - that was inserted will be removed. - - The removed item is deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that refer to the removed item will be - set to point to the next item in the dictionary's traversal order. - - \sa take(), clear(), setAutoDelete() -*/ - -/*! - \fn type *Q3Dict::take( const QString &key ) - - Takes the item with \a key out of the dictionary without deleting - it (even if \link Q3PtrCollection::setAutoDelete() - auto-deletion\endlink is enabled). - - If there are two or more items with equal keys, then the last item - that was inserted will be taken. - - Returns a pointer to the item taken out, or 0 if the key does not - exist in the dictionary. - - All dictionary iterators that refer to the taken item will be set - to point to the next item in the dictionary traversal order. - - \sa remove(), clear(), setAutoDelete() -*/ - -/*! - \fn void Q3Dict::clear() - - Removes all items from the dictionary. - - The removed items are deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that operate on the dictionary are reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn type *Q3Dict::find( const QString &key ) const - - Returns the item with key \a key, or 0 if the key does not exist - in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to the [] operator. - - \sa operator[]() -*/ - -/*! - \fn type *Q3Dict::operator[]( const QString &key ) const - - Returns the item with key \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to the find() function. - - \sa find() -*/ - -/*! - \fn void Q3Dict::statistics() const - - Debugging-only function that prints out the dictionary - distribution using qDebug(). -*/ - -/*! - \fn QDataStream& Q3Dict::read( QDataStream &s, Q3PtrCollection::Item &item ) - - Reads a dictionary item from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3Dict::write( QDataStream &s, Q3PtrCollection::Item item ) const - - Writes a dictionary \a item to the stream \a s and returns a - reference to the stream. - - \sa read() -*/ - -/*! - \class Q3DictIterator - \brief The Q3DictIterator class provides an iterator for Q3Dict collections. - \compat - - Q3DictIterator is implemented as a template class. Define a - template instance Q3DictIterator\<X\> to create a dictionary - iterator that operates on Q3Dict\<X\> (dictionary of X*). - - The traversal order is arbitrary; when we speak of the "first", - "last" and "next" item we are talking in terms of this arbitrary - order. - - Multiple iterators may independently traverse the same dictionary. - A Q3Dict knows about all the iterators that are operating on the - dictionary. When an item is removed from the dictionary, Q3Dict - updates all iterators that are referring to the removed item to - point to the next item in the (arbitrary) traversal order. - - Example: - \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 1 - In the example we insert some pointers to line edits into a - dictionary, then iterate over the dictionary printing the strings - associated with the line edits. - - \sa Q3Dict -*/ - -/*! - \fn Q3DictIterator::Q3DictIterator( const Q3Dict<type> &dict ) - - Constructs an iterator for \a dict. The current iterator item is - set to point to the first item in the dictionary, \a dict. First - in this context means first in the arbitrary traversal order. -*/ - -/*! - \fn Q3DictIterator::~Q3DictIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3DictIterator::count() const - - Returns the number of items in the dictionary over which the - iterator is operating. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3DictIterator::isEmpty() const - - Returns TRUE if the dictionary is empty, i.e. count() == 0; - otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn type *Q3DictIterator::toFirst() - - Resets the iterator, making the first item the first current item. - First in this context means first in the arbitrary traversal - order. Returns a pointer to this item. - - If the dictionary is empty it sets the current item to 0 and - returns 0. -*/ - -/*! - \fn type *Q3DictIterator::operator*() - \internal -*/ - -/*! - \fn Q3DictIterator::operator type*() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - - -/*! - \fn type *Q3DictIterator::current() const - - Returns a pointer to the current iterator item's value. -*/ - -/*! - \fn QString Q3DictIterator::currentKey() const - - Returns the current iterator item's key. -*/ - -/*! - \fn type *Q3DictIterator::operator()() - - Makes the next item current and returns the original current item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3DictIterator::operator++() - - Prefix ++ makes the next item current and returns the new current - item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3DictIterator::operator+=( uint jump ) - \internal - Sets the current item to the item \a jump positions after the current item, - and returns a pointer to that item. - - If that item is beyond the last item or if the dictionary is empty, - it sets the current item to 0 and returns 0. -*/ diff --git a/doc/src/classes/q3intcache.qdoc b/doc/src/classes/q3intcache.qdoc deleted file mode 100644 index 770532e..0000000 --- a/doc/src/classes/q3intcache.qdoc +++ /dev/null @@ -1,446 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3IntCache - \brief The Q3IntCache class is a template class that provides a cache based on long keys. - \compat - - Q3IntCache is implemented as a template class. Define a template - instance Q3IntCache\<X\> to create a cache that operates on - pointers to X, or X*. - - A cache is a least recently used (LRU) list of cache items, - accessed via \c long keys. Each cache item has a cost. The sum - of item costs, totalCost(), will not exceed the maximum cache - cost, maxCost(). If inserting a new item would cause the total - cost to exceed the maximum cost, the least recently used items in - the cache are removed. - - Apart from insert(), by far the most important function is find() - (which also exists as operator[]). This function looks up an - item, returns it, and by default marks it as being the most - recently used item. - - There are also methods to remove() or take() an object from the - cache. Calling setAutoDelete(TRUE) for a cache tells it to delete - items that are removed. The default is to not delete items when - they are removed (i.e. remove() and take() are equivalent). - - When inserting an item into the cache, only the pointer is copied, - not the item itself. This is called a shallow copy. It is possible - to make the cache copy all of the item's data (known as a deep - copy) when an item is inserted. insert() calls the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a dictionary and reimplement newItem() if you want deep - copies. - - When removing a cache item, the item will be automatically - deleted if auto-deletion is enabled. - - There is a Q3IntCacheIterator which may be used to traverse the - items in the cache in arbitrary order. - - \sa Q3IntCacheIterator, Q3Cache, Q3AsciiCache -*/ - -/*! - \fn Q3IntCache::Q3IntCache( const Q3IntCache<type> &c ) - - \internal - - Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version. -*/ - -/*! - \fn Q3IntCache::Q3IntCache( int maxCost, int size ) - - Constructs a cache whose contents will never have a total cost - greater than \a maxCost and which is expected to contain less than - \a size items. - - \a size is actually the size of an internal hash array; it's - usually best to make it prime and at least 50% bigger than the - largest expected number of items in the cache. - - Each inserted item is associated with a cost. When inserting a new - item, if the total cost of all items in the cache will exceed \a - maxCost, the cache will start throwing out the older (least - recently used) items until there is enough room for the new item - to be inserted. -*/ - -/*! - \fn Q3IntCache::~Q3IntCache() - - Removes all items from the cache and then destroys the int cache. - If auto-deletion is enabled the cache's items are deleted. All - iterators that access this cache will be reset. -*/ - -/*! - \fn Q3IntCache<type>& Q3IntCache::operator=( const Q3IntCache<type> &c ) - - \internal - - Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version. -*/ - -/*! - \fn int Q3IntCache::maxCost() const - - Returns the maximum allowed total cost of the cache. - - \sa setMaxCost() totalCost() -*/ - -/*! - \fn int Q3IntCache::totalCost() const - - Returns the total cost of the items in the cache. This is an - integer in the range 0 to maxCost(). - - \sa setMaxCost() -*/ - -/*! - \fn void Q3IntCache::setMaxCost( int m ) - - Sets the maximum allowed total cost of the cache to \a m. If the - current total cost is greater than \a m, some items are removed - immediately. - - \sa maxCost() totalCost() -*/ - -/*! - \fn uint Q3IntCache::count() const - - Returns the number of items in the cache. - - \sa totalCost() -*/ - -/*! - \fn uint Q3IntCache::size() const - - Returns the size of the hash array used to implement the cache. - This should be a bit larger than count() is likely to be. -*/ - -/*! - \fn bool Q3IntCache::isEmpty() const - - Returns TRUE if the cache is empty; otherwise returns FALSE. -*/ - -/*! - \fn bool Q3IntCache::insert( long k, const type *d, int c, int p ) - - Inserts the item \a d into the cache with key \a k and assigns it - a cost of \a c (default 1). Returns TRUE if it succeeds; otherwise - returns FALSE. - - The cache's size is limited, and if the total cost is too high, - Q3IntCache will remove old, least-used items until there is room - for this new item. - - The parameter \a p is internal and should be left at the default - value (0). - - \warning If this function returns FALSE (for example, the cost \c, - exceeds maxCost()), you must delete \a d yourself. Additionally, - be very careful about using \a d after calling this function. Any - other insertions into the cache, from anywhere in the application - or within Qt itself, could cause the object to be discarded from - the cache and the pointer to become invalid. -*/ - -/*! - \fn bool Q3IntCache::remove( long k ) - - Removes the item associated with \a k, and returns TRUE if the - item was present in the cache; otherwise returns FALSE. - - The item is deleted if auto-deletion has been enabled, i.e. if you - have called setAutoDelete(TRUE). - - If there are two or more items with equal keys, the one that was - inserted most recently is removed. - - All iterators that refer to the removed item are set to point to - the next item in the cache's traversal order. - - \sa take(), clear() -*/ - -/*! - \fn type * Q3IntCache::take( long k ) - - Takes the item associated with \a k out of the cache without - deleting it, and returns a pointer to the item taken out or 0 if - the key does not exist in the cache. - - If there are two or more items with equal keys, the one that was - inserted most recently is taken. - - All iterators that refer to the taken item are set to point to the - next item in the cache's traversal order. - - \sa remove(), clear() -*/ - -/*! - \fn void Q3IntCache::clear() - - Removes all items from the cache, and deletes them if - auto-deletion has been enabled. - - All cache iterators that operate this on cache are reset. - - \sa remove() take() -*/ - -/*! - \fn type * Q3IntCache::find( long k, bool ref ) const - - Returns the item associated with \a k, or 0 if the key does not - exist in the cache. If \a ref is TRUE (the default), the item is - moved to the front of the least recently used list. - - If there are two or more items with equal keys, the one that was - inserted most recently is returned. -*/ - -/*! - \fn type * Q3IntCache::operator[]( long k ) const - - Returns the item associated with \a k, or 0 if \a k does not exist - in the cache, and moves the item to the front of the least - recently used list. - - If there are two or more items with equal keys, the one that was - inserted most recently is returned. - - This is the same as find( k, TRUE ). - - \sa find() -*/ - -/*! - \fn void Q3IntCache::statistics() const - - A debug-only utility function. Prints out cache usage, hit/miss, - and distribution information using qDebug(). This function does - nothing in the release library. -*/ - -/*! - \class Q3IntCacheIterator - \brief The Q3IntCacheIterator class provides an iterator for Q3IntCache collections. - \compat - - Note that the traversal order is arbitrary; you are not guaranteed - any particular order. If new objects are inserted into the cache - while the iterator is active, the iterator may or may not see - them. - - Multiple iterators are completely independent, even when they - operate on the same Q3IntCache. Q3IntCache updates all iterators - that refer an item when that item is removed. - - Q3IntCacheIterator provides an operator++(), and an operator+=() to - traverse the cache; current() and currentKey() to access the - current cache item and its key; atFirst() atLast(), which return - TRUE if the iterator points to the first/last item in the cache; - isEmpty(), which returns TRUE if the cache is empty; and count(), - which returns the number of items in the cache. - - Note that atFirst() and atLast() refer to the iterator's arbitrary - ordering, not to the cache's internal least recently used list. - - \sa Q3IntCache -*/ - -/*! - \fn Q3IntCacheIterator::Q3IntCacheIterator( const Q3IntCache<type> &cache ) - - Constructs an iterator for \a cache. The current iterator item is - set to point to the first item in the \a cache (or rather, the - first item is defined to be the item at which this constructor - sets the iterator to point). -*/ - -/*! - \fn Q3IntCacheIterator::Q3IntCacheIterator (const Q3IntCacheIterator<type> & ci) - - Constructs an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently from there on. -*/ - -/*! - \fn Q3IntCacheIterator<type>& Q3IntCacheIterator::operator=( const Q3IntCacheIterator<type> &ci ) - - Makes this an iterator for the same cache as \a ci. The new - iterator starts at the same item as ci.current(), but moves - independently thereafter. -*/ - -/*! - \fn uint Q3IntCacheIterator::count() const - - Returns the number of items in the cache on which this iterator - operates. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3IntCacheIterator::isEmpty() const - - Returns TRUE if the cache is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3IntCacheIterator::atFirst() const - - Returns TRUE if the iterator points to the first item in the - cache; otherwise returns FALSE. Note that this refers to the - iterator's arbitrary ordering, not to the cache's internal least - recently used list. - - \sa toFirst(), atLast() -*/ - -/*! - \fn bool Q3IntCacheIterator::atLast() const - - Returns TRUE if the iterator points to the last item in the cache; - otherwise returns FALSE. Note that this refers to the iterator's - arbitrary ordering, not to the cache's internal least recently - used list. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3IntCacheIterator::toFirst() - - Sets the iterator to point to the first item in the cache and - returns a pointer to the item. - - Sets the iterator to 0, and returns 0, if the cache is empty. - - \sa toLast() isEmpty() -*/ - -/*! - \fn type *Q3IntCacheIterator::toLast() - - Sets the iterator to point to the last item in the cache and - returns a pointer to the item. - - Sets the iterator to 0, and returns 0, if the cache is empty. - - \sa toFirst() isEmpty() -*/ - -/*! - \fn Q3IntCacheIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3IntCacheIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn long Q3IntCacheIterator::currentKey() const - - Returns the key for the current iterator item. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the cache or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator+=( uint jump ) - - Returns the item \a jump positions after the current item, or 0 if - it is beyond the last item. Makes this the current item. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator-=( uint jump ) - - Returns the item \a jump positions before the current item, or 0 - if it is beyond the first item. Makes this the current item. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator++() - - Prefix ++ makes the iterator point to the item just after - current(), and makes it the new current item for the iterator. If - current() was the last item, operator--() returns 0. -*/ - -/*! - \fn type *Q3IntCacheIterator::operator--() - - Prefix -- makes the iterator point to the item just before - current(), and makes it the new current item for the iterator. If - current() was the first item, operator--() returns 0. -*/ diff --git a/doc/src/classes/q3intdict.qdoc b/doc/src/classes/q3intdict.qdoc deleted file mode 100644 index 731050d..0000000 --- a/doc/src/classes/q3intdict.qdoc +++ /dev/null @@ -1,390 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3IntDict - \brief The Q3IntDict class is a template class that provides a dictionary based on long keys.\ - \compat - - Q3IntDict is implemented as a template class. Define a template - instance Q3IntDict\<X\> to create a dictionary that operates on - pointers to X (X*). - - A dictionary is a collection of key-value pairs. The key is an \c - long used for insertion, removal and lookup. The value is a - pointer. Dictionaries provide very fast insertion and lookup. - - Example: - \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 0 - - See Q3Dict for full details, including the choice of dictionary - size, and how deletions are handled. - - \sa Q3IntDictIterator, Q3Dict, Q3AsciiDict, Q3PtrDict -*/ - - -/*! - \fn Q3IntDict::Q3IntDict( int size ) - - Constructs a dictionary using an internal hash array of size \a - size. - - Setting \a size to a suitably large prime number (equal to or - greater than the expected number of entries) makes the hash - distribution better which leads to faster lookup. -*/ - -/*! - \fn Q3IntDict::Q3IntDict( const Q3IntDict<type> &dict ) - - Constructs a copy of \a dict. - - Each item in \a dict is inserted into this dictionary. Only the - pointers are copied (shallow copy). -*/ - -/*! - \fn Q3IntDict::~Q3IntDict() - - Removes all items from the dictionary and destroys it. - - All iterators that access this dictionary will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3IntDict<type> &Q3IntDict::operator=(const Q3IntDict<type> &dict) - - Assigns \a dict to this dictionary and returns a reference to this - dictionary. - - This dictionary is first cleared and then each item in \a dict is - inserted into this dictionary. Only the pointers are copied - (shallow copy), unless newItem() has been reimplemented. -*/ - -/*! - \fn uint Q3IntDict::count() const - - Returns the number of items in the dictionary. - - \sa isEmpty() -*/ - -/*! - \fn uint Q3IntDict::size() const - - Returns the size of the internal hash array (as specified in the - constructor). - - \sa count() -*/ - -/*! - \fn void Q3IntDict::resize( uint newsize ) - - Changes the size of the hashtable to \a newsize. The contents of - the dictionary are preserved, but all iterators on the dictionary - become invalid. -*/ - -/*! - \fn bool Q3IntDict::isEmpty() const - - Returns TRUE if the dictionary is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn void Q3IntDict::insert( long key, const type *item ) - - Insert item \a item into the dictionary using key \a key. - - Multiple items can have the same key, in which case only the last - item will be accessible using \l operator[](). - - \a item may not be 0. - - \sa replace() -*/ - -/*! - \fn void Q3IntDict::replace( long key, const type *item ) - - If the dictionary has key \a key, this key's item is replaced with - \a item. If the dictionary doesn't contain key \a key, \a item is - inserted into the dictionary using key \a key. - - \a item may not be 0. - - Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 1 - - If there are two or more items with equal keys, then the most - recently inserted item will be replaced. - - \sa insert() -*/ - -/*! - \fn bool Q3IntDict::remove( long key ) - - Removes the item associated with \a key from the dictionary. - Returns TRUE if successful, i.e. if the \a key is in the - dictionary; otherwise returns FALSE. - - If there are two or more items with equal keys, then the most - recently inserted item will be removed. - - The removed item is deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that refer to the removed item will be - set to point to the next item in the dictionary's traversal - order. - - \sa take(), clear(), setAutoDelete() -*/ - -/*! - \fn type *Q3IntDict::take( long key ) - - Takes the item associated with \a key out of the dictionary - without deleting it (even if \link Q3PtrCollection::setAutoDelete() - auto-deletion\endlink is enabled). - - If there are two or more items with equal keys, then the most - recently inserted item will be taken. - - Returns a pointer to the item taken out, or 0 if the key does not - exist in the dictionary. - - All dictionary iterators that refer to the taken item will be set - to point to the next item in the dictionary's traversing order. - - \sa remove(), clear(), setAutoDelete() -*/ - -/*! - \fn void Q3IntDict::clear() - - Removes all items from the dictionary. - - The removed items are deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that access this dictionary will be reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn type *Q3IntDict::find( long key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to operator[]. - - \sa operator[]() -*/ - -/*! - \fn type *Q3IntDict::operator[]( long key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to the find() function. - - \sa find() -*/ - -/*! - \fn void Q3IntDict::statistics() const - - Debugging-only function that prints out the dictionary - distribution using qDebug(). -*/ - -/*! - \fn QDataStream& Q3IntDict::read( QDataStream &s, Q3PtrCollection::Item &item ) - - Reads a dictionary item from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3IntDict::write( QDataStream &s, Q3PtrCollection::Item item ) const - - Writes a dictionary \a item to the stream \a s and returns a - reference to the stream. - - \sa read() -*/ - -/*! - \class Q3IntDictIterator - \brief The Q3IntDictIterator class provides an iterator for Q3IntDict collections. - \compat - - Q3IntDictIterator is implemented as a template class. Define a - template instance Q3IntDictIterator\<X\> to create a dictionary - iterator that operates on Q3IntDict\<X\> (dictionary of X*). - - Example: - \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 2 - - Note that the traversal order is arbitrary; you are not guaranteed the - order shown above. - - Multiple iterators may independently traverse the same dictionary. - A Q3IntDict knows about all the iterators that are operating on the - dictionary. When an item is removed from the dictionary, Q3IntDict - updates all iterators that refer the removed item to point to the - next item in the traversal order. - - \sa Q3IntDict -*/ - -/*! - \fn Q3IntDictIterator::Q3IntDictIterator( const Q3IntDict<type> &dict ) - - Constructs an iterator for \a dict. The current iterator item is - set to point to the 'first' item in the \a dict. The first item - refers to the first item in the dictionary's arbitrary internal - ordering. -*/ - -/*! - \fn Q3IntDictIterator::~Q3IntDictIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3IntDictIterator::count() const - - Returns the number of items in the dictionary this iterator - operates over. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3IntDictIterator::isEmpty() const - - Returns TRUE if the dictionary is empty; otherwise eturns FALSE. - - \sa count() -*/ - -/*! - \fn type *Q3IntDictIterator::toFirst() - - Sets the current iterator item to point to the first item in the - dictionary and returns a pointer to the item. The first item - refers to the first item in the dictionary's arbitrary internal - ordering. If the dictionary is empty it sets the current item to - 0 and returns 0. -*/ - -/*! - \fn Q3IntDictIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3IntDictIterator::current() const - - Returns a pointer to the current iterator item. -*/ - -/*! - \fn long Q3IntDictIterator::currentKey() const - - Returns the key for the current iterator item. -*/ - -/*! - \fn type *Q3IntDictIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3IntDictIterator::operator++() - - Prefix ++ makes the succeeding item current and returns the new - current item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3IntDictIterator::operator+=( uint jump ) - - Sets the current item to the item \a jump positions after the - current item, and returns a pointer to that item. - - If that item is beyond the last item or if the dictionary is - empty, it sets the current item to 0 and returns 0. -*/ diff --git a/doc/src/classes/q3memarray.qdoc b/doc/src/classes/q3memarray.qdoc deleted file mode 100644 index eb0648c..0000000 --- a/doc/src/classes/q3memarray.qdoc +++ /dev/null @@ -1,523 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3MemArray - \brief The Q3MemArray class is a template class that provides arrays of simple types. - \compat - - Q3MemArray is implemented as a template class. Define a template - instance Q3MemArray\<X\> to create an array that contains X items. - - Q3MemArray stores the array elements directly in the array. It can - only deal with simple types (i.e. C++ types, structs, and classes - that have no constructors, destructors, or virtual functions). - Q3MemArray uses bitwise operations to copy and compare array - elements. - - The Q3PtrVector collection class is also a kind of array. Like most - old Qt collection classes, it uses pointers to the contained items. - - Q3MemArray uses explicit sharing with a - reference count. If more than one array shares common data and one - of the arrays is modified, all the arrays are modified. - - The benefit of sharing is that a program does not need to duplicate - data when it is not required, which results in lower memory use - and less copying of data. - - Example: - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 0 - - Program output: - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 1 - - Note concerning the use of Q3MemArray for manipulating structs or - classes: Compilers will often pad the size of structs of odd sizes - up to the nearest word boundary. This will then be the size - Q3MemArray will use for its bitwise element comparisons. Because - the remaining bytes will typically be uninitialized, this can - cause find() etc. to fail to find the element. Example: - - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 2 - - To work around this, make sure that you use a struct where - sizeof() returns the same as the sum of the sizes of the members - either by changing the types of the struct members or by adding - dummy members. - - Q3MemArray data can be traversed by iterators (see begin() and - end()). The number of items is returned by count(). The array can - be resized with resize() and filled using fill(). - - You can make a shallow copy of the array with assign() (or - operator=()) and a deep copy with duplicate(). - - Search for values in the array with find() and contains(). For - sorted arrays (see sort()) you can search using bsearch(). - - You can set the data directly using setRawData() and - resetRawData(), although this requires care. -*/ - -/*! \fn Q3MemArray::operator QVector<type>() const - - Automatically converts the Q3MemArray<type> into a QVector<type>. -*/ - -/*! \typedef Q3MemArray::Iterator - A Q3MemArray iterator. - \sa begin() end() -*/ -/*! \typedef Q3MemArray::ConstIterator - A const Q3MemArray iterator. - \sa begin() end() -*/ -/*! \typedef Q3MemArray::ValueType - \internal -*/ - -/*! - \fn Q3MemArray::Q3MemArray() - - Constructs a null array. - - \sa isNull() -*/ - -/*! - \fn Q3MemArray::Q3MemArray( int size ) - - Constructs an array with room for \a size elements. Makes a null - array if \a size == 0. - - The elements are left uninitialized. - - \sa resize(), isNull() -*/ - -/*! - \fn Q3MemArray::Q3MemArray( const Q3MemArray<type> &a ) - - Constructs a shallow copy of \a a. - - \sa assign() -*/ - -/*! - \fn Q3MemArray::Q3MemArray(const QVector<type> &vector) - - Constructs a copy of \a vector. -*/ - -/*! - \fn Q3MemArray::Q3MemArray(int arg1, int arg2) - - Constructs an array \e{without allocating} array space. The - arguments \a arg1 and \a arg2 should be zero. Use at your own - risk. -*/ - -/*! - \fn Q3MemArray::~Q3MemArray() - - Dereferences the array data and deletes it if this was the last - reference. -*/ - -/*! - \fn Q3MemArray<type> &Q3MemArray::operator=( const Q3MemArray<type> &a ) - - Assigns a shallow copy of \a a to this array and returns a - reference to this array. - - Equivalent to assign( a ). -*/ - -/*! - \fn type *Q3MemArray::data() const - - Returns a pointer to the actual array data. - - The array is a null array if data() == 0 (null pointer). - - \sa isNull() -*/ - -/*! - \fn uint Q3MemArray::nrefs() const - - Returns the reference count for the shared array data. This - reference count is always greater than zero. -*/ - -/*! - \fn uint Q3MemArray::size() const - - Returns the size of the array (maximum number of elements). - - The array is a null array if size() == 0. - - \sa isNull(), resize() -*/ - -/*! - \fn uint Q3MemArray::count() const - - Returns the same as size(). - - \sa size() -*/ - -/*! - \fn bool Q3MemArray::isEmpty() const - - Returns TRUE if the array is empty; otherwise returns FALSE. - - isEmpty() is equivalent to isNull() for Q3MemArray (unlike - QString). -*/ - -/*! - \fn bool Q3MemArray::isNull() const - - Returns TRUE if the array is null; otherwise returns FALSE. - - A null array has size() == 0 and data() == 0. -*/ - -/*! - \fn bool Q3MemArray::resize( uint size, Optimization optim ) - - Resizes (expands or shrinks) the array to \a size elements. The - array becomes a null array if \a size == 0. - - Returns TRUE if successful, or FALSE if the memory cannot be - allocated. - - New elements are not initialized. - - \a optim is either Q3GArray::MemOptim (the default) or - Q3GArray::SpeedOptim. When optimizing for speed rather than memory - consumption, the array uses a smart grow and shrink algorithm that - might allocate more memory than is actually needed for \a size - elements. This speeds up subsequent resize operations, for example - when appending many elements to an array, since the space has - already been allocated. - - \sa size() -*/ - -/*! - \fn bool Q3MemArray::resize( uint size ) - - \overload - - Resizes (expands or shrinks) the array to \a size elements. The - array becomes a null array if \a size == 0. - - Returns TRUE if successful, i.e. if the memory can be allocated; - otherwise returns FALSE. - - New elements are not initialized. - - \sa size() -*/ - -/*! - \fn bool Q3MemArray::truncate( uint pos ) - - Truncates the array at position \a pos. - - Returns TRUE if successful, i.e. if the memory can be allocated; - otherwise returns FALSE. - - Equivalent to resize(\a pos). - - \sa resize() -*/ - -/*! - \fn bool Q3MemArray::fill( const type &v, int size ) - - Fills the array with the value \a v. If \a size is specified as - different from -1, then the array will be resized before being - filled. - - Returns TRUE if successful, i.e. if \a size is -1, or \a size is - != -1 and the memory can be allocated; otherwise returns FALSE. - - \sa resize() -*/ - -/*! - \fn void Q3MemArray::detach() - - Detaches this array from shared array data; i.e. it makes a - private, deep copy of the data. - - Copying will be performed only if the \link nrefs() reference - count\endlink is greater than one. - - \sa copy() -*/ - -/*! - \fn Q3MemArray<type> Q3MemArray::copy() const - - Returns a deep copy of this array. - - \sa detach(), duplicate() -*/ - -/*! - \fn Q3MemArray<type> &Q3MemArray::assign( const Q3MemArray<type> &a ) - - Shallow copy. Dereferences the current array and references the - data contained in \a a instead. Returns a reference to this array. - - \sa operator=() -*/ - -/*! - \fn Q3MemArray<type> &Q3MemArray::assign( const type *data, uint size ) - - \overload - - Shallow copy. Dereferences the current array and references the - array data \a data, which contains \a size elements. Returns a - reference to this array. - - Do not delete \a data later; Q3MemArray will call free() on it - at the right time. -*/ - -/*! - \fn Q3MemArray<type> &Q3MemArray::duplicate( const Q3MemArray<type> &a ) - - Deep copy. Dereferences the current array and obtains a copy of - the data contained in \a a instead. Returns a reference to this - array. - - \sa copy() -*/ - -/*! - \fn Q3MemArray<type> &Q3MemArray::duplicate( const type *data, uint size ) - - \overload - - Deep copy. Dereferences the current array and obtains a copy of - the array data \a data instead. Returns a reference to this array. - The size of the array is given by \a size. - - \sa copy() -*/ - -/*! - \fn Q3MemArray<type> &Q3MemArray::setRawData( const type *data, uint size ) - - Sets raw data and returns a reference to the array. - - Dereferences the current array and sets the new array data to \a - data and the new array size to \a size. Do not attempt to resize - or re-assign the array data when raw data has been set. Call - resetRawData(\a data, \a size) to reset the array. - - Setting raw data is useful because it sets Q3MemArray data without - allocating memory or copying data. - - Example I (intended use): - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 3 - - Example II (you don't want to do this): - \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 4 - - \warning If you do not call resetRawData(), Q3MemArray will attempt - to deallocate or reallocate the raw data, which might not be too - good. Be careful. - - \sa resetRawData() -*/ - -/*! - \fn void Q3MemArray::resetRawData( const type *data, uint size ) - - Removes internal references to the raw data that was set using - setRawData(). This means that Q3MemArray no longer has access to - the \a data, so you are free to manipulate \a data as you wish. - You can now use the Q3MemArray without affecting the original \a - data, for example by calling setRawData() with a pointer to some - other data. - - The arguments must be the \a data and length, \a size, that were - passed to setRawData(). This is for consistency checking. - - \sa setRawData() -*/ - -/*! - \fn int Q3MemArray::find( const type &v, uint index ) const - - Finds the first occurrence of \a v, starting at position \a index. - - Returns the position of \a v, or -1 if \a v could not be found. - - \sa contains() -*/ - -/*! - \fn int Q3MemArray::contains( const type &v ) const - - Returns the number of times \a v occurs in the array. - - \sa find() -*/ - -/*! - \fn void Q3MemArray::sort() - - Sorts the array elements in ascending order, using bitwise - comparison (memcmp()). - - \sa bsearch() -*/ - -/*! - \fn int Q3MemArray::bsearch( const type &v ) const - - In a sorted array (as sorted by sort()), finds the first - occurrence of \a v by using a binary search. For a sorted - array this is generally much faster than find(), which does - a linear search. - - Returns the position of \a v, or -1 if \a v could not be found. - - \sa sort(), find() -*/ - -/*! - \fn type &Q3MemArray::operator[]( int index ) const - - Returns a reference to the element at position \a index in the - array. - - This can be used to both read and set an element. Equivalent to - at(). - - \sa at() -*/ - -/*! - \fn type &Q3MemArray::at( uint index ) const - - Returns a reference to the element at position \a index in the array. - - This can be used to both read and set an element. - - \sa operator[]() -*/ - -/*! - \fn Q3MemArray::operator const type *() const - - Cast operator. Returns a pointer to the array. - - \sa data() -*/ - -/*! - \fn bool Q3MemArray::operator==( const Q3MemArray<type> &a ) const - - Returns TRUE if this array is equal to \a a; otherwise returns - FALSE. - - The two arrays are compared bitwise. - - \sa operator!=() -*/ - -/*! - \fn bool Q3MemArray::operator!=( const Q3MemArray<type> &a ) const - - Returns TRUE if this array is different from \a a; otherwise - returns FALSE. - - The two arrays are compared bitwise. - - \sa operator==() -*/ - -/*! - \fn Iterator Q3MemArray::begin() - - Returns an iterator pointing at the beginning of this array. This - iterator can be used in the same way as the iterators of - Q3ValueList and QMap, for example. -*/ - -/*! - \fn Iterator Q3MemArray::end() - - Returns an iterator pointing behind the last element of this - array. This iterator can be used in the same way as the iterators - of Q3ValueList and QMap, for example. -*/ - -/*! - \fn ConstIterator Q3MemArray::begin() const - - \overload - - Returns a const iterator pointing at the beginning of this array. - This iterator can be used in the same way as the iterators of - Q3ValueList and QMap, for example. -*/ - -/*! - \fn ConstIterator Q3MemArray::end() const - - \overload - - Returns a const iterator pointing behind the last element of this - array. This iterator can be used in the same way as the iterators - of Q3ValueList and QMap, for example. -*/ diff --git a/doc/src/classes/q3popupmenu.qdoc b/doc/src/classes/q3popupmenu.qdoc deleted file mode 100644 index c20dadc..0000000 --- a/doc/src/classes/q3popupmenu.qdoc +++ /dev/null @@ -1,76 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3PopupMenu - \brief The Q3PopupMenu class is a thin compatibility wrapper around QMenu. - \compat - - Use QMenu in new applications. Note that the menu's actions must - be \l {Q3Action}s. -*/ - -/*! - \fn Q3PopupMenu::Q3PopupMenu(QWidget *parent, const char *name) - - Constructs a menu with the given \a parent and \a name. -*/ - -/*! - \fn int Q3PopupMenu::exec() - - Pops up the menu and returns the ID of the action that was - selected. - - \sa QMenu::exec() -*/ - -/*! - \fn int Q3PopupMenu::exec(const QPoint & pos, int indexAtPoint) - - Pops up the menu at coordinate \a pos and returns the ID of the - action that was selected. - - If \a indexAtPoint is specified, the menu will pop up with the - item at index \a indexAtPoint under the mouse cursor. - - \sa QMenu::exec() -*/ diff --git a/doc/src/classes/q3ptrdict.qdoc b/doc/src/classes/q3ptrdict.qdoc deleted file mode 100644 index 531b085..0000000 --- a/doc/src/classes/q3ptrdict.qdoc +++ /dev/null @@ -1,388 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3PtrDict - \brief The Q3PtrDict class is a template class that provides a dictionary based on void* keys. - \compat - - Q3PtrDict is implemented as a template class. Define a template - instance Q3PtrDict\<X\> to create a dictionary that operates on - pointers to X (X*). - - A dictionary is a collection of key-value pairs. The key is a - void* used for insertion, removal and lookup. The value is a - pointer. Dictionaries provide very fast insertion and lookup. - - Example: - \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 0 - In this example we use a dictionary to add an extra property (a - char*) to the line edits we're using. - - See Q3Dict for full details, including the choice of dictionary - size, and how deletions are handled. - - \sa Q3PtrDictIterator, Q3Dict, Q3AsciiDict, Q3IntDict -*/ - - -/*! - \fn Q3PtrDict::Q3PtrDict( int size ) - - Constructs a dictionary using an internal hash array with the size - \a size. - - Setting \a size to a suitably large prime number (equal to or - greater than the expected number of entries) makes the hash - distribution better and improves lookup performance. -*/ - -/*! - \fn Q3PtrDict::Q3PtrDict( const Q3PtrDict<type> &dict ) - - Constructs a copy of \a dict. - - Each item in \a dict is inserted into this dictionary. Only the - pointers are copied (shallow copy). -*/ - -/*! - \fn Q3PtrDict::~Q3PtrDict() - - Removes all items from the dictionary and destroys it. - - All iterators that access this dictionary will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3PtrDict<type> &Q3PtrDict::operator=(const Q3PtrDict<type> &dict) - - Assigns \a dict to this dictionary and returns a reference to this - dictionary. - - This dictionary is first cleared and then each item in \a dict is - inserted into the dictionary. Only the pointers are copied - (shallow copy), unless newItem() has been reimplemented. -*/ - -/*! - \fn uint Q3PtrDict::count() const - - Returns the number of items in the dictionary. - - \sa isEmpty() -*/ - -/*! - \fn uint Q3PtrDict::size() const - - Returns the size of the internal hash table (as specified in the - constructor). - - \sa count() -*/ - -/*! - \fn void Q3PtrDict::resize( uint newsize ) - - Changes the size of the hash table to \a newsize. The contents of - the dictionary are preserved, but all iterators on the dictionary - become invalid. -*/ - -/*! - \fn bool Q3PtrDict::isEmpty() const - - Returns TRUE if the dictionary is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn void Q3PtrDict::insert( void *key, const type *item ) - - Inserts the \a key with the \a item into the dictionary. - - Multiple items can have the same key, in which case only the last - item will be accessible using \l operator[](). - - \a item may not be 0. - - \sa replace() -*/ - -/*! - \fn void Q3PtrDict::replace( void *key, const type *item ) - - If the dictionary has key \a key, this key's item is replaced with - \a item. If the dictionary doesn't contain key \a key, \a item is - inserted into the dictionary using key \a key. - - \a item may not be 0. - - Equivalent to - \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 1 - - If there are two or more items with equal keys, then the most - recently inserted item will be replaced. - - \sa insert() -*/ - -/*! - \fn bool Q3PtrDict::remove( void *key ) - - Removes the item associated with \a key from the dictionary. - Returns TRUE if successful, i.e. if \a key is in the dictionary; - otherwise returns FALSE. - - If there are two or more items with equal keys, then the most - recently inserted item will be removed. - - The removed item is deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that refer to the removed item will be - set to point to the next item in the dictionary traversal order. - - \sa take(), clear(), setAutoDelete() -*/ - -/*! - \fn type *Q3PtrDict::take( void *key ) - - Takes the item associated with \a key out of the dictionary - without deleting it (even if \link Q3PtrCollection::setAutoDelete() - auto-deletion\endlink is enabled). - - If there are two or more items with equal keys, then the most - recently inserted item will be removed. - - Returns a pointer to the item taken out, or 0 if the key does not - exist in the dictionary. - - All dictionary iterators that refer to the taken item will be set - to point to the next item in the dictionary traversal order. - - \sa remove(), clear(), setAutoDelete() -*/ - -/*! - \fn void Q3PtrDict::clear() - - Removes all items from the dictionary. - - The removed items are deleted if \link - Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. - - All dictionary iterators that access this dictionary will be - reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn type *Q3PtrDict::find( void *key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to operator[]. - - \sa operator[]() -*/ - -/*! - \fn type *Q3PtrDict::operator[]( void *key ) const - - Returns the item associated with \a key, or 0 if the key does not - exist in the dictionary. - - If there are two or more items with equal keys, then the most - recently inserted item will be found. - - Equivalent to the find() function. - - \sa find() -*/ - -/*! - \fn void Q3PtrDict::statistics() const - - Debugging-only function that prints out the dictionary - distribution using qDebug(). -*/ - -/*! - \fn QDataStream& Q3PtrDict::read( QDataStream &s, Q3PtrCollection::Item &item ) - - Reads a dictionary item from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrDict::write( QDataStream &s, Q3PtrCollection::Item item) const - - Writes a dictionary \a item to the stream \a s and returns a - reference to the stream. - - \sa read() -*/ - -/*! - \class Q3PtrDictIterator - \brief The Q3PtrDictIterator class provides an iterator for Q3PtrDict collections. - \compat - - Q3PtrDictIterator is implemented as a template class. Define a - template instance Q3PtrDictIterator\<X\> to create a dictionary - iterator that operates on Q3PtrDict\<X\> (dictionary of X*). - - Example: - \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 2 - In the example we insert some line edits into a dictionary, - associating a string with each. We then iterate over the - dictionary printing the associated strings. - - Multiple iterators may independently traverse the same dictionary. - A Q3PtrDict knows about all the iterators that are operating on the - dictionary. When an item is removed from the dictionary, Q3PtrDict - updates all iterators that refer the removed item to point to the - next item in the traversing order. - - \sa Q3PtrDict -*/ - -/*! - \fn Q3PtrDictIterator::Q3PtrDictIterator( const Q3PtrDict<type> &dict ) - - Constructs an iterator for \a dict. The current iterator item is - set to point on the first item in the \a dict. -*/ - -/*! - \fn Q3PtrDictIterator::~Q3PtrDictIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3PtrDictIterator::count() const - - Returns the number of items in the dictionary this iterator - operates on. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3PtrDictIterator::isEmpty() const - - Returns TRUE if the dictionary is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn type *Q3PtrDictIterator::toFirst() - - Sets the current iterator item to point to the first item in the - dictionary and returns a pointer to the item. If the dictionary is - empty, it sets the current item to 0 and returns 0. -*/ - -/*! - \fn Q3PtrDictIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3PtrDictIterator::current() const - - Returns a pointer to the current iterator item's value. -*/ - -/*! - \fn void *Q3PtrDictIterator::currentKey() const - - Returns the current iterator item's key. -*/ - -/*! - \fn type *Q3PtrDictIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrDictIterator::operator++() - - Prefix ++ makes the succeeding item current and returns the new - current item. - - If the current iterator item was the last item in the dictionary - or if it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrDictIterator::operator+=( uint jump ) - - Sets the current item to the item \a jump positions after the - current item and returns a pointer to that item. - - If that item is beyond the last item or if the dictionary is - empty, it sets the current item to 0 and returns 0. -*/ diff --git a/doc/src/classes/q3ptrlist.qdoc b/doc/src/classes/q3ptrlist.qdoc deleted file mode 100644 index b2b9c3f..0000000 --- a/doc/src/classes/q3ptrlist.qdoc +++ /dev/null @@ -1,1157 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3PtrList - \brief The Q3PtrList class is a template class that provides a list. - \compat - - Q3ValueList is an STL-compatible alternative to this class. - - Define a template instance Q3PtrList\<X\> to create a list that - operates on pointers to X (X*). - - The list class is indexable and has a \link at() current - index\endlink and a \link current() current item\endlink. The - first item corresponds to index position 0. The current index is - -1 if the current item is 0. - - Items are inserted with prepend(), insert() or append(). Items are - removed with remove(), removeRef(), removeFirst() and - removeLast(). You can search for an item using find(), findNext(), - findRef() or findNextRef(). The list can be sorted with sort(). - You can count the number of occurrences of an item with contains() - or containsRef(). You can get a pointer to the current item with - current(), to an item at a particular index position in the list - with at() or to the first or last item with getFirst() and - getLast(). You can also iterate over the list with first(), - last(), next() and prev() (which all update current()). The list's - deletion property is set with setAutoDelete(). - - \target example - Example: - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 0 - - The output is - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 1 - - Q3PtrList has several member functions for traversing the list, but - using a Q3PtrListIterator can be more practical. Multiple list - iterators may traverse the same list, independently of each other - and of the current list item. - - In the example above we make the call setAutoDelete(true). - Enabling auto-deletion tells the list to delete items that are - removed. The default is to not delete items when they are removed - but this would cause a memory leak in the example because there - are no other references to the list items. - - When inserting an item into a list only the pointer is copied, not - the item itself, i.e. a shallow copy. It is possible to make the - list copy all of the item's data (deep copy) when an item is - inserted. insert(), inSort() and append() call the virtual - function Q3PtrCollection::newItem() for the item to be inserted. - Inherit a list and reimplement newItem() to have deep copies. - - When removing an item from a list, the virtual function - Q3PtrCollection::deleteItem() is called. Q3PtrList's default - implementation is to delete the item if auto-deletion is enabled. - - The virtual function compareItems() can be reimplemented to - compare two list items. This function is called from all list - functions that need to compare list items, for instance - remove(const type*). If you only want to deal with pointers, there - are functions that compare pointers instead, for instance - removeRef(const type*). These functions are somewhat faster than - those that call compareItems(). - - List items are stored as \c void* in an internal Q3LNode, which - also holds pointers to the next and previous list items. The - functions currentNode(), removeNode(), and takeNode() operate - directly on the Q3LNode, but they should be used with care. The - data component of the node is available through Q3LNode::getData(). - - The Q3StrList class is a list of \c char*. - It reimplements newItem(), deleteItem() and compareItems(). (But - see QStringList for a list of Unicode QStrings.) - - \sa Q3PtrListIterator -*/ - - -/*! - \fn Q3PtrList::Q3PtrList() - - Constructs an empty list. -*/ - -/*! - \fn Q3PtrList::Q3PtrList( const Q3PtrList<type> &list ) - - Constructs a copy of \a list. - - Each item in \a list is \link append() appended\endlink to this - list. Only the pointers are copied (shallow copy). -*/ - -/*! - \fn Q3PtrList::~Q3PtrList() - - Removes all items from the list and destroys the list. - - All list iterators that access this list will be reset. - - \sa setAutoDelete() -*/ - -/*! - \fn Q3PtrList<type> &Q3PtrList::operator=(const Q3PtrList<type> &list) - - Assigns \a list to this list and returns a reference to this list. - - This list is first cleared and then each item in \a list is \link - append() appended\endlink to this list. Only the pointers are - copied (shallow copy) unless newItem() has been reimplemented. -*/ - -/*! - \fn bool Q3PtrList::operator==(const Q3PtrList<type> &list ) const - - Compares this list with \a list. Returns TRUE if the lists contain - the same data; otherwise returns FALSE. -*/ - -/*! - \fn uint Q3PtrList::count() const - - Returns the number of items in the list. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3PtrList::operator!=(const Q3PtrList<type> &list ) const - - Compares this list with \a list. Returns TRUE if the lists contain - different data; otherwise returns FALSE. -*/ - - -/*! - \fn void Q3PtrList::sort() - - Sorts the list by the result of the virtual compareItems() - function. - - The heap sort algorithm is used for sorting. It sorts n items with - O(n*log n) comparisons. This is the asymptotic optimal solution of - the sorting problem. - - If the items in your list support operator<() and operator==(), - you might be better off with Q3SortedList because it implements the - compareItems() function for you using these two operators. - - \sa inSort() -*/ - -/*! - \fn bool Q3PtrList::isEmpty() const - - Returns TRUE if the list is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3PtrList::insert( uint index, const type *item ) - - Inserts the \a item at position \a index in the list. - - Returns TRUE if successful, i.e. if \a index is in range; - otherwise returns FALSE. The valid range is 0 to count() - (inclusively). The item is appended if \a index == count(). - - The inserted item becomes the current list item. - - \a item must not be 0. - - \sa append(), current(), replace() -*/ - -/*! - \fn bool Q3PtrList::replace( uint index, const type *item ) - - Replaces the item at position \a index with the new \a item. - - Returns TRUE if successful, i.e. \a index is in the range 0 to - count()-1. - - \sa append(), current(), insert() -*/ - -/*! - \fn void Q3PtrList::inSort( const type *item ) - - Inserts the \a item at its sorted position in the list. - - The sort order depends on the virtual compareItems() function. All - items must be inserted with inSort() to maintain the sorting - order. - - The inserted item becomes the current list item. - - \a item must not be 0. - - \warning Using inSort() is slow. An alternative, especially if you - have lots of items, is to simply append() or insert() them and - then use sort(). inSort() takes up to O(n) compares. That means - inserting n items in your list will need O(n^2) compares whereas - sort() only needs O(n*log n) for the same task. So use inSort() - only if you already have a presorted list and want to insert just - a few additional items. - - \sa insert(), compareItems(), current(), sort() -*/ - -/*! - \fn void Q3PtrList::append( const type *item ) - - Inserts the \a item at the end of the list. - - The inserted item becomes the current list item. This is - equivalent to \c{insert( count(), item )}. - - \a item must not be 0. - - \sa insert(), current(), prepend() -*/ - -/*! - \fn void Q3PtrList::prepend( const type *item ) - - Inserts the \a item at the start of the list. - - The inserted item becomes the current list item. This is - equivalent to \c{insert( 0, item )}. - - \a item must not be 0. - - \sa append(), insert(), current() -*/ - -/*! - \fn bool Q3PtrList::remove( uint index ) - - Removes the item at position \a index in the list. - - Returns TRUE if successful, i.e. if \a index is in range; - otherwise returns FALSE. The valid range is \c{0..(count() - 1)} - inclusive. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa take(), clear(), setAutoDelete(), current() removeRef() -*/ - -/*! - \fn bool Q3PtrList::remove() - - \overload - - Removes the current list item. - - Returns TRUE if successful, i.e. if the current item isn't 0; - otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa take(), clear(), setAutoDelete(), current() removeRef() -*/ - -/*! - \fn bool Q3PtrList::remove( const type *item ) - - \overload - - Removes the first occurrence of \a item from the list. - - Returns TRUE if successful, i.e. if \a item is in the list; - otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The compareItems() function is called when searching for the item - in the list. If compareItems() is not reimplemented, it is more - efficient to call removeRef(). - - If \a item is NULL then the current item is removed from the list. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa removeRef(), take(), clear(), setAutoDelete(), compareItems(), - current() -*/ - -/*! - \fn bool Q3PtrList::removeRef( const type *item ) - - Removes the first occurrence of \a item from the list. - - Returns TRUE if successful, i.e. if \a item is in the list; - otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - Equivalent to: - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 2 - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa remove(), clear(), setAutoDelete(), current() -*/ - -/*! - \fn void Q3PtrList::removeNode( Q3LNode *node ) - - Removes the \a node from the list. - - This node must exist in the list, otherwise the program may crash. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The first item in the list will become the new current list item. - The current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the item succeeding this item or to the preceding item if - the removed item was the last item. - - \warning Do not call this function unless you are an expert. - - \sa takeNode(), currentNode() remove() removeRef() -*/ - -/*! - \fn bool Q3PtrList::removeFirst() - - Removes the first item from the list. Returns TRUE if successful, - i.e. if the list isn't empty; otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The first item in the list becomes the new current list item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa removeLast(), setAutoDelete(), current() remove() -*/ - -/*! - \fn bool Q3PtrList::removeLast() - - Removes the last item from the list. Returns TRUE if successful, - i.e. if the list isn't empty; otherwise returns FALSE. - - The removed item is deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - The last item in the list becomes the new current list item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the removed item will be set to - point to the new current item. - - \sa removeFirst(), setAutoDelete(), current() -*/ - -/*! - \fn type *Q3PtrList::take( uint index ) - - Takes the item at position \a index out of the list without - deleting it (even if \link setAutoDelete() auto-deletion\endlink - is enabled). - - Returns a pointer to the item taken out of the list, or 0 if the - index is out of range. The valid range is \c{0..(count() - 1)} - inclusive. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the taken item will be set to - point to the new current item. - - \sa remove(), clear(), current() -*/ - -/*! - \fn type *Q3PtrList::take() - - \overload - - Takes the current item out of the list without deleting it (even - if \link setAutoDelete() auto-deletion\endlink is enabled). - - Returns a pointer to the item taken out of the list, or 0 if - the current item is 0. - - The item after the removed item becomes the new current list item - if the removed item is not the last item in the list. If the last - item is removed, the new last item becomes the current item. The - current item is set to 0 if the list becomes empty. - - All list iterators that refer to the taken item will be set to - point to the new current item. - - \sa remove(), clear(), current() -*/ - -/*! - \fn type *Q3PtrList::takeNode( Q3LNode *node ) - - Takes the \a node out of the list without deleting its item (even - if \link setAutoDelete() auto-deletion\endlink is enabled). - Returns a pointer to the item taken out of the list. - - This node must exist in the list, otherwise the program may crash. - - The first item in the list becomes the new current list item. - - All list iterators that refer to the taken item will be set to - point to the item succeeding this item or to the preceding item if - the taken item was the last item. - - \warning Do not call this function unless you are an expert. - - \sa removeNode(), currentNode() -*/ - -/*! - \fn void Q3PtrList::clear() - - Removes all items from the list. - - The removed items are deleted if \link setAutoDelete() - auto-deletion\endlink is enabled. - - All list iterators that access this list will be reset. - - \sa remove(), take(), setAutoDelete() -*/ - -/*! - \fn int Q3PtrList::find( const type *item ) - - Finds the first occurrence of \a item in the list. - - If the item is found, the list sets the current item to point to - the found item and returns the index of this item. If the item is - not found, the list sets the current item to 0, the current - index to -1, and returns -1. - - The compareItems() function is called when searching for the item - in the list. If compareItems() is not reimplemented, it is more - efficient to call findRef(). - - \sa findNext(), findRef(), compareItems(), current() -*/ - -/*! - \fn int Q3PtrList::findNext( const type *item ) - - Finds the next occurrence of \a item in the list, starting from - the current list item. - - If the item is found, the list sets the current item to point to - the found item and returns the index of this item. If the item is - not found, the list sets the current item to 0, the current - index to -1, and returns -1. - - The compareItems() function is called when searching for the item - in the list. If compareItems() is not reimplemented, it is more - efficient to call findNextRef(). - - \sa find(), findNextRef(), compareItems(), current() -*/ - -/*! - \fn int Q3PtrList::findRef( const type *item ) - - Finds the first occurrence of \a item in the list. - - If the item is found, the list sets the current item to point to - the found item and returns the index of this item. If the item is - not found, the list sets the current item to 0, the current - index to -1, and returns -1. - - Calling this function is much faster than find() because find() - compares \a item with each list item using compareItems(), whereas - this function only compares the pointers. - - \sa findNextRef(), find(), current() -*/ - -/*! - \fn int Q3PtrList::findNextRef( const type *item ) - - Finds the next occurrence of \a item in the list, starting from - the current list item. - - If the item is found, the list sets the current item to point to - the found item and returns the index of this item. If the item is - not found, the list sets the current item to 0, the current - index to -1, and returns -1. - - Calling this function is much faster than findNext() because - findNext() compares \a item with each list item using - compareItems(), whereas this function only compares the pointers. - - \sa findRef(), findNext(), current() -*/ - -/*! - \fn uint Q3PtrList::contains( const type *item ) const - - Returns the number of occurrences of \a item in the list. - - The compareItems() function is called when looking for the \a item - in the list. If compareItems() is not reimplemented, it is more - efficient to call containsRef(). - - This function does not affect the current list item. - - \sa containsRef(), compareItems() -*/ - -/*! - \fn uint Q3PtrList::containsRef( const type *item ) const - - Returns the number of occurrences of \a item in the list. - - Calling this function is much faster than contains() because - contains() compares \a item with each list item using - compareItems(), whereas his function only compares the pointers. - - This function does not affect the current list item. - - \sa contains() -*/ - -/*! - \fn type *Q3PtrList::at( uint index ) - - Returns a pointer to the item at position \a index in the list, or - 0 if the index is out of range. - - Sets the current list item to this item if \a index is valid. The - valid range is \c{0..(count() - 1)} inclusive. - - This function is very efficient. It starts scanning from the first - item, last item, or current item, whichever is closest to \a - index. - - \sa current() -*/ - -/*! - \fn int Q3PtrList::at() const - - \overload - - Returns the index of the current list item. The returned value is - -1 if the current item is 0. - - \sa current() -*/ - -/*! - \fn type *Q3PtrList::current() const - - Returns a pointer to the current list item. The current item may - be 0 (implies that the current index is -1). - - \sa at() -*/ - -/*! - \fn Q3LNode *Q3PtrList::currentNode() const - - Returns a pointer to the current list node. - - The node can be kept and removed later using removeNode(). The - advantage is that the item can be removed directly without - searching the list. - - \warning Do not call this function unless you are an expert. - - \sa removeNode(), takeNode(), current() -*/ - -/*! - \fn type *Q3PtrList::getFirst() const - - Returns a pointer to the first item in the list, or 0 if the list - is empty. - - This function does not affect the current list item. - - \sa first(), getLast() -*/ - -/*! - \fn type *Q3PtrList::getLast() const - - Returns a pointer to the last item in the list, or 0 if the list - is empty. - - This function does not affect the current list item. - - \sa last(), getFirst() -*/ - -/*! - \fn type *Q3PtrList::first() - - Returns a pointer to the first item in the list and makes this the - current list item; returns 0 if the list is empty. - - \sa getFirst(), last(), next(), prev(), current() -*/ - -/*! - \fn type *Q3PtrList::last() - - Returns a pointer to the last item in the list and makes this the - current list item; returns 0 if the list is empty. - - \sa getLast(), first(), next(), prev(), current() -*/ - -/*! - \fn type *Q3PtrList::next() - - Returns a pointer to the item succeeding the current item. Returns - 0 if the current item is 0 or equal to the last item. - - Makes the succeeding item current. If the current item before this - function call was the last item, the current item will be set to - 0. If the current item was 0, this function does nothing. - - \sa first(), last(), prev(), current() -*/ - -/*! - \fn type *Q3PtrList::prev() - - Returns a pointer to the item preceding the current item. Returns - 0 if the current item is 0 or equal to the first item. - - Makes the preceding item current. If the current item before this - function call was the first item, the current item will be set to - 0. If the current item was 0, this function does nothing. - - \sa first(), last(), next(), current() -*/ - -/*! - \fn void Q3PtrList::toVector( Q3GVector *vec ) const - - Stores all list items in the vector \a vec. - - The vector must be of the same item type, otherwise the result - will be undefined. -*/ - -/*! - \typedef Q3PtrList::iterator - - \internal -*/ - -/*! - \typedef Q3PtrList::Iterator - - \internal -*/ - -/*! - \typedef Q3PtrList::ConstIterator - - \internal -*/ - -/*! - \typedef Q3PtrList::const_iterator - - \internal -*/ - -/*! - \fn Q3PtrList::constBegin() const - - \internal -*/ - -/*! - \fn Q3PtrList::constEnd() const - - \internal -*/ - -/*! - \fn Q3PtrList::erase(Iterator) - - \internal -*/ - - -/***************************************************************************** - Q3PtrListIterator documentation - *****************************************************************************/ - -/*! - \class Q3PtrListIterator - \brief The Q3PtrListIterator class provides an iterator for - Q3PtrList collections. - \compat - - Define a template instance Q3PtrListIterator\<X\> to create a list - iterator that operates on Q3PtrList\<X\> (list of X*). - - The following example is similar to the - example in the Q3PtrList class documentation, - but it uses Q3PtrListIterator. The class Employee is - defined there. - - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 3 - - The output is - \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 4 - - Using a list iterator is a more robust way of traversing the list - than using the Q3PtrList member functions \link Q3PtrList::first() - first\endlink(), \link Q3PtrList::next() next\endlink(), \link - Q3PtrList::current() current\endlink(), etc., as many iterators can - traverse the same list independently. - - An iterator has its own current list item and can get the next and - previous list items. It doesn't modify the list in any way. - - When an item is removed from the list, all iterators that point to - that item are updated to point to Q3PtrList::current() instead to - avoid dangling references. - - \sa Q3PtrList -*/ - -/*! - \fn Q3PtrListIterator::Q3PtrListIterator( const Q3PtrList<type> &list ) - - Constructs an iterator for \a list. The current iterator item is - set to point on the first item in the \a list. -*/ - -/*! - \fn Q3PtrListIterator::~Q3PtrListIterator() - - Destroys the iterator. -*/ - -/*! - \fn uint Q3PtrListIterator::count() const - - Returns the number of items in the list this iterator operates on. - - \sa isEmpty() -*/ - -/*! - \fn bool Q3PtrListIterator::isEmpty() const - - Returns TRUE if the list is empty; otherwise returns FALSE. - - \sa count() -*/ - -/*! - \fn bool Q3PtrListIterator::atFirst() const - - Returns TRUE if the current iterator item is the first list item; - otherwise returns FALSE. - - \sa toFirst(), atLast() -*/ - -/*! - \fn bool Q3PtrListIterator::atLast() const - - Returns TRUE if the current iterator item is the last list item; - otherwise returns FALSE. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3PtrListIterator::toFirst() - - Sets the current iterator item to point to the first list item and - returns a pointer to the item. Sets the current item to 0 and - returns 0 if the list is empty. - - \sa toLast(), atFirst() -*/ - -/*! - \fn type *Q3PtrListIterator::toLast() - - Sets the current iterator item to point to the last list item and - returns a pointer to the item. Sets the current item to 0 and - returns 0 if the list is empty. - - \sa toFirst(), atLast() -*/ - -/*! - \fn Q3PtrListIterator::operator type *() const - - Cast operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3PtrListIterator::operator*() - - Asterisk operator. Returns a pointer to the current iterator item. - Same as current(). -*/ - -/*! - \fn type *Q3PtrListIterator::current() const - - Returns a pointer to the current iterator item. If the iterator is - positioned before the first item in the list or after the last - item in the list, 0 is returned. -*/ - -/*! - \fn type *Q3PtrListIterator::operator()() - - Makes the succeeding item current and returns the original current - item. - - If the current iterator item was the last item in the list or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrListIterator::operator++() - - Prefix ++ makes the succeeding item current and returns the new - current item. - - If the current iterator item was the last item in the list or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrListIterator::operator+=( uint jump ) - - Sets the current item to the item \a jump positions after the - current item and returns a pointer to that item. - - If that item is beyond the last item or if the list is empty, it - sets the current item to 0 and returns 0 -*/ - -/*! - \fn type *Q3PtrListIterator::operator--() - - Prefix - makes the preceding item current and returns the new - current item. - - If the current iterator item was the first item in the list or if - it was 0, 0 is returned. -*/ - -/*! - \fn type *Q3PtrListIterator::operator-=( uint jump ) - - Returns the item \a jump positions before the current item or 0 - if it is beyond the first item. Makes this the current item. -*/ - -/*! - \fn Q3PtrListIterator<type>& Q3PtrListIterator::operator=( const Q3PtrListIterator<type> &it ) - - Assignment. Makes a copy of the iterator \a it and returns a - reference to this iterator. -*/ - -/*! - \class Q3StrList - \brief The Q3StrList class provides a doubly-linked list of char*. - \compat - - If you want a string list of \l{QString}s use QStringList. - - This class is a Q3PtrList\<char\> instance (a list of char*). - - Q3StrList can make deep or shallow copies of the strings that are - inserted. - - A deep copy means that memory is allocated for the string and then - the string data is copied into that memory. A shallow copy is just - a copy of the pointer value and not of the string data itself. - - The disadvantage of shallow copies is that because a pointer can - be deleted only once, the program must put all strings in a - central place and know when it is safe to delete them (i.e. when - the strings are no longer referenced by other parts of the - program). This can make the program more complex. The advantage of - shallow copies is that they consume far less memory than deep - copies. It is also much faster to copy a pointer (typically 4 or 8 - bytes) than to copy string data. - - A Q3StrList that operates on deep copies will, by default, turn on - auto-deletion (see setAutoDelete()). Thus, by default Q3StrList - will deallocate any string copies it allocates. - - The virtual compareItems() function is reimplemented and does a - case-sensitive string comparison. The inSort() function will - insert strings in sorted order. In general it is fastest to insert - the strings as they come and sort() at the end; inSort() is useful - when you just have to add a few extra strings to an already sorted - list. - - The Q3StrListIterator class is an iterator for Q3StrList. -*/ - -/*! - \fn Q3StrList::operator QList<QByteArray>() const - - Automatically converts a Q3StrList into a QList<QByteArray>. -*/ - -/*! - \fn Q3StrList::Q3StrList( bool deepCopies ) - - Constructs an empty list of strings. Will make deep copies of all - inserted strings if \a deepCopies is TRUE, or use shallow copies - if \a deepCopies is FALSE. -*/ - -/*! - \fn Q3StrList::Q3StrList(const Q3StrList &list) - \fn Q3StrList::Q3StrList(const QList<QByteArray> &list) - - Constructs a copy of \a list. -*/ - -/*! - \fn Q3StrList::~Q3StrList() - - Destroys the list. All strings are removed. -*/ - -/*! - \fn Q3StrList& Q3StrList::operator=(const Q3StrList& list) - \fn Q3StrList &Q3StrList::operator=(const QList<QByteArray> &list) - - Assigns \a list to this list and returns a reference to this list. -*/ - -/*! - \class Q3StrIList - \brief The Q3StrIList class provides a doubly-linked list of char* - with case-insensitive comparison. - \compat - - This class is a Q3PtrList\<char\> instance (a list of char*). - - Q3StrIList is identical to Q3StrList except that the virtual - compareItems() function is reimplemented to compare strings - case-insensitively. The inSort() function inserts strings in a - sorted order. In general it is fastest to insert the strings as - they come and sort() at the end; inSort() is useful when you just - have to add a few extra strings to an already sorted list. - - The Q3StrListIterator class works for Q3StrIList. - - \sa QStringList -*/ - -/*! - \fn Q3StrIList::Q3StrIList( bool deepCopies ) - - Constructs a list of strings. Will make deep copies of all - inserted strings if \a deepCopies is TRUE, or use shallow copies - if \a deepCopies is FALSE. -*/ - -/*! - \fn Q3StrIList::~Q3StrIList() - - Destroys the list. All strings are removed. -*/ - -/*! - \fn int Q3PtrList::compareItems( Q3PtrCollection::Item item1, - Q3PtrCollection::Item item2 ) - - This virtual function compares two list items. - - Returns: - \list - \i zero if \a item1 == \a item2 - \i nonzero if \a item1 != \a item2 - \endlist - - This function returns \e int rather than \e bool so that - reimplementations can return three values and use it to sort by: - - \list - \i 0 if \a item1 == \a item2 - \i \> 0 (positive integer) if \a item1 \> \a item2 - \i \< 0 (negative integer) if \a item1 \< \a item2 - \endlist - - inSort() requires that compareItems() is implemented as described - here. - - This function should not modify the list because some const - functions call compareItems(). - - The default implementation compares the pointers. -*/ - -/*! - \fn QDataStream& Q3PtrList::read( QDataStream& s, - Q3PtrCollection::Item& item ) - - Reads a list item from the stream \a s and returns a reference to - the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrList::write( QDataStream& s, - Q3PtrCollection::Item item ) const - - Writes a list item, \a item to the stream \a s and returns a - reference to the stream. - - The default implementation does nothing. - - \sa read() -*/ - -/*! \fn iterator Q3PtrList::begin() -\internal -*/ -/*! \fn const_iterator Q3PtrList::begin() const -\internal -*/ -/*! \fn iterator Q3PtrList::end() -\internal -*/ -/*! \fn const_iterator Q3PtrList::end() const -\internal -*/ - -/*! - \class Q3StrListIterator - \brief The Q3StrListIterator class is an iterator for the Q3StrList - and Q3StrIList classes. - \compat - - This class is a Q3PtrListIterator\<char\> instance. It can traverse - the strings in the Q3StrList and Q3StrIList classes. -*/ - - -/* - \class Q3PtrListAutoDelete - \brief The Q3PtrListAutoDelete class is a template class that provides a list that auto-deletes its data. - \compat - - A Q3PtrListAutoDelete is identical to a Q3PtrList with - setAutoDelete(TRUE). -*/ diff --git a/doc/src/classes/q3ptrqueue.qdoc b/doc/src/classes/q3ptrqueue.qdoc deleted file mode 100644 index c60193c..0000000 --- a/doc/src/classes/q3ptrqueue.qdoc +++ /dev/null @@ -1,230 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3PtrQueue - \brief The Q3PtrQueue class is a template class that provides a queue. - \compat - - Q3ValueVector can be used as an STL-compatible alternative to this - class. - - A template instance Q3PtrQueue\<X\> is a queue that operates on - pointers to X (X*). - - A queue is a first in, first out structure. Items are added to the - tail of the queue with enqueue() and retrieved from the head with - dequeue(). You can peek at the head item without dequeing it using - head(). - - You can control the queue's deletion policy with setAutoDelete(). - - For compatibility with the Q3PtrCollection classes, current() and - remove() are provided; both operate on the head(). - - \sa Q3PtrList Q3PtrStack -*/ - -/*! - \fn Q3PtrQueue::Q3PtrQueue () - - Creates an empty queue with autoDelete() set to FALSE. -*/ - -/*! - \fn Q3PtrQueue::Q3PtrQueue( const Q3PtrQueue<type>& queue ) - - Creates a queue from \a queue. - - Only the pointers are copied; the items are not. The autoDelete() - flag is set to FALSE. -*/ - -/*! - \fn Q3PtrQueue::~Q3PtrQueue() - - Destroys the queue. Items in the queue are deleted if autoDelete() - is TRUE. -*/ - -/*! - \fn Q3PtrQueue<type>& Q3PtrQueue::operator= (const Q3PtrQueue<type>& queue) - - Assigns \a queue to this queue and returns a reference to this - queue. - - This queue is first cleared and then each item in \a queue is - enqueued to this queue. Only the pointers are copied. - - \warning The autoDelete() flag is not modified. If it is TRUE for - both \a queue and this queue, deleting the two lists will cause \e - double-deletion of the items. -*/ - -/*! - \fn bool Q3PtrQueue::isEmpty() const - - Returns TRUE if the queue is empty; otherwise returns FALSE. - - \sa count() dequeue() head() -*/ - -/*! - \fn void Q3PtrQueue::enqueue (const type* d) - - Adds item \a d to the tail of the queue. - - \sa count() dequeue() -*/ - -/*! - \fn type* Q3PtrQueue::dequeue () - - Takes the head item from the queue and returns a pointer to it. - Returns 0 if the queue is empty. - - \sa enqueue() count() -*/ - -/*! - \fn bool Q3PtrQueue::remove() - - Removes the head item from the queue, and returns TRUE if there - was an item, i.e. the queue wasn't empty; otherwise returns FALSE. - - The item is deleted if autoDelete() is TRUE. - - \sa head() isEmpty() dequeue() -*/ - -/*! - \fn void Q3PtrQueue::clear() - - Removes all items from the queue, and deletes them if autoDelete() - is TRUE. - - \sa remove() -*/ - -/*! - \fn uint Q3PtrQueue::count() const - - Returns the number of items in the queue. - - \sa isEmpty() -*/ - -/*! - \fn type* Q3PtrQueue::head() const - - Returns a pointer to the head item in the queue. The queue is not - changed. Returns 0 if the queue is empty. - - \sa dequeue() isEmpty() -*/ - -/*! - \fn Q3PtrQueue::operator type*() const - - Returns a pointer to the head item in the queue. The queue is not - changed. Returns 0 if the queue is empty. - - \sa dequeue() isEmpty() -*/ - -/*! - \fn type* Q3PtrQueue::current() const - - Returns a pointer to the head item in the queue. The queue is not - changed. Returns 0 if the queue is empty. - - \sa dequeue() isEmpty() -*/ - -/*! - \fn bool Q3PtrQueue::autoDelete() const - - Returns the setting of the auto-delete option. The default is - FALSE. - - \sa setAutoDelete() -*/ - -/*! - \fn void Q3PtrQueue::setAutoDelete( bool enable ) - - Sets the queue to auto-delete its contents if \a enable is TRUE - and not to delete them if \a enable is FALSE. - - If auto-deleting is turned on, all the items in a queue are - deleted when the queue itself is deleted. This can be quite - convenient if the queue has the only pointer to the items. - - The default setting is FALSE, for safety. If you turn it on, be - careful about copying the queue: you might find yourself with two - queues deleting the same items. - - \sa autoDelete() -*/ - -/*! - \fn QDataStream& Q3PtrQueue::read( QDataStream& s, - Q3PtrCollection::Item& item ) - - Reads a queue item, \a item, from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrQueue::write( QDataStream& s, - Q3PtrCollection::Item item ) const - - Writes a queue item, \a item, to the stream \a s and returns a - reference to the stream. - - The default implementation does nothing. - - \sa read() -*/ diff --git a/doc/src/classes/q3ptrstack.qdoc b/doc/src/classes/q3ptrstack.qdoc deleted file mode 100644 index 071fcd0..0000000 --- a/doc/src/classes/q3ptrstack.qdoc +++ /dev/null @@ -1,217 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3PtrStack - \brief The Q3PtrStack class is a template class that provides a stack. - \compat - - Q3ValueStack is an STL-compatible alternative to this class. - - Define a template instance Q3PtrStack\<X\> to create a stack that - operates on pointers to X, (X*). - - A stack is a last in, first out (LIFO) structure. Items are added - to the top of the stack with push() and retrieved from the top - with pop(). Use top() to get a reference to the top element - without changing the stack. - - You can control the stack's deletion policy with setAutoDelete(). - - For compatibility with the Q3PtrCollection classes current() and - remove() are provided; they both operate on the top(). - - \sa Q3PtrList Q3PtrQueue -*/ - -/*! - \fn Q3PtrStack::Q3PtrStack () - - Creates an empty stack. -*/ - -/*! - \fn Q3PtrStack::Q3PtrStack (const Q3PtrStack<type>& s) - - Creates a stack by making a shallow copy of another stack \a s. -*/ - -/*! - \fn Q3PtrStack::~Q3PtrStack () - - Destroys the stack. All items will be deleted if autoDelete() is - true. -*/ - -/*! - \fn Q3PtrStack<type>& Q3PtrStack::operator= (const Q3PtrStack<type>& s) - - Sets the contents of this stack by making a shallow copy of - another stack \a s. Elements currently in this stack will be - deleted if autoDelete() is true. -*/ - -/*! - \fn bool Q3PtrStack::isEmpty () const - - Returns true if the stack contains no elements; otherwise returns - false. -*/ - -/*! - \fn void Q3PtrStack::push (const type* d) - - Adds an element \a d to the top of the stack. Last in, first out. -*/ - -/*! - \fn type* Q3PtrStack::pop () - - Removes the top item from the stack and returns it. The stack must - not be empty. -*/ - -/*! - \fn bool Q3PtrStack::remove () - - Removes the top item from the stack and deletes it if autoDelete() - is true. Returns true if there was an item to pop; otherwise - returns false. - - \sa clear() -*/ - -/*! - \fn void Q3PtrStack::clear() - - Removes all items from the stack, deleting them if autoDelete() is - true. - - \sa remove() -*/ - -/*! - \fn uint Q3PtrStack::count() const - - Returns the number of items in the stack. - - \sa isEmpty() -*/ - -/*! - \fn type* Q3PtrStack::top () const - - Returns a pointer to the top item on the stack (most recently - pushed). The stack is not changed. Returns 0 if the stack is - empty. -*/ - -/*! - \fn Q3PtrStack::operator type* ()const - - Returns a pointer to the top item on the stack (most recently - pushed). The stack is not changed. Returns 0 if the stack is - empty. -*/ - -/*! - \fn type* Q3PtrStack::current () const - - Returns a pointer to the top item on the stack (most recently - pushed). The stack is not changed. Returns 0 if the stack is - empty. -*/ - -/*! - \fn bool Q3PtrStack::autoDelete() const - - The same as Q3PtrCollection::autoDelete(). Returns true if - the auto-delete option is set. If the option is set, the - stack auto-deletes its contents. - - \sa setAutoDelete() -*/ - -/*! - \fn void Q3PtrStack::setAutoDelete(bool enable) - - Defines whether this stack auto-deletes its contents. The same as - Q3PtrCollection::setAutoDelete(). If \a enable is true, auto-delete - is turned on. - - If auto-deleting is turned on, all the items in the stack are - deleted when the stack itself is deleted. This is convenient if - the stack has the only pointers to the items. - - The default setting is false, for safety. If you turn it on, be - careful about copying the stack, or you might find yourself with - two stacks deleting the same items. - - Note that the auto-delete setting may also affect other functions in - subclasses. For example, a subclass that has a remove() function - will remove the item from its data structure, and if auto-delete is - enabled, will also delete the item. - - \sa autoDelete() -*/ - -/*! - \fn QDataStream& Q3PtrStack::read(QDataStream& s, Q3PtrCollection::Item& item) - - Reads a stack item, \a item, from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrStack::write(QDataStream& s, - Q3PtrCollection::Item item) const - - Writes a stack item, \a item, to the stream \a s and returns a - reference to the stream. - - The default implementation does nothing. - - \sa read() -*/ diff --git a/doc/src/classes/q3ptrvector.qdoc b/doc/src/classes/q3ptrvector.qdoc deleted file mode 100644 index c734064..0000000 --- a/doc/src/classes/q3ptrvector.qdoc +++ /dev/null @@ -1,427 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3PtrVector - \brief The Q3PtrVector class is a template collection class that - provides a vector (array). - \compat - - Q3ValueVector is an STL-compatible alternative to this class. - - Q3PtrVector is implemented as a template class. Defines a template - instance Q3PtrVector\<X\> to create a vector that contains pointers - to X (X*). - - A vector is the same as an array. The main difference between - Q3PtrVector and Q3MemArray is that Q3PtrVector stores pointers to the - elements, whereas Q3MemArray stores the elements themselves (i.e. - Q3MemArray is value-based and Q3PtrVector is pointer-based). - - Items are added to the vector using insert() or fill(). Items are - removed with remove(). You can get a pointer to an item at a - particular index position using at(). - - Unless otherwise stated, all functions that remove items from the - vector will also delete the element pointed to if \link - setAutoDelete() auto-deletion\endlink is enabled. By default, - auto-deletion is disabled; see setAutoDelete(). This behavior can - be changed in a subclass by reimplementing the virtual function - deleteItem(). - - Functions that compare items (find() and sort() for example) will - do so using the virtual function compareItems(). The default - implementation of this function only compares the pointer values. - Reimplement compareItems() in a subclass to get searching and - sorting based on the item contents. You can perform a linear - search for a pointer in the vector using findRef(), or a binary - search (of a sorted vector) using bsearch(). You can count the - number of times an item appears in the vector with contains() or - containsRef(). - - \sa Q3MemArray -*/ - -/*! - \fn Q3PtrVector::Q3PtrVector() - - Constructs a null vector. - - \sa isNull() -*/ - -/*! - \fn Q3PtrVector::Q3PtrVector(uint size) - - Constructs an vector with room for \a size items. Makes a null - vector if \a size == 0. - - All \a size positions in the vector are initialized to 0. - - \sa size(), resize(), isNull() -*/ - -/*! - \fn Q3PtrVector::Q3PtrVector(const Q3PtrVector<type> &v) - - Constructs a copy of \a v. Only the pointers are copied (i.e. - shallow copy). -*/ - -/*! - \fn Q3PtrVector::~Q3PtrVector() - - Removes all items from the vector, and destroys the vector itself. - - \sa clear() -*/ - -/*! - \fn Q3PtrVector<type> &Q3PtrVector::operator=(const Q3PtrVector<type> &v) - - Assigns \a v to this vector and returns a reference to this - vector. - - This vector is first cleared and then all the items from \a v are - copied into the vector. Only the pointers are copied (i.e. shallow - copy). - - \sa clear() -*/ - -/*! - \fn type **Q3PtrVector::data() const - - Returns a pointer to the actual vector data, which is an array of - type*. - - The vector is a null vector if data() == 0 (null pointer). - - \sa isNull() -*/ - -/*! - \fn uint Q3PtrVector::size() const - - Returns the size of the vector, i.e. the number of vector - positions. This is also the maximum number of items the vector can - hold. - - The vector is a null vector if size() == 0. - - \sa isNull(), resize(), count() -*/ - -/*! - \fn uint Q3PtrVector::count() const - - Returns the number of items in the vector. The vector is empty if - count() == 0. - - \sa isEmpty(), size(), isNull() -*/ - -/*! - \fn bool Q3PtrVector::isEmpty() const - - Returns true if the vector is empty; otherwise returns false. - - \sa count() -*/ - -/*! - \fn bool Q3PtrVector::isNull() const - - Returns true if the vector is null; otherwise returns false. - - A null vector has size() == 0 and data() == 0. - - \sa size() -*/ - -/*! - \fn bool Q3PtrVector::resize(uint size) - - Resizes (expands or shrinks) the vector to \a size elements. The - vector becomes a null vector if \a size == 0. - - Any items at position \a size or beyond in the vector are removed. - New positions are initialized to 0. - - Returns true if successful, i.e. if the memory was successfully - allocated; otherwise returns false. - - \sa size(), isNull() -*/ - -/*! - \fn bool Q3PtrVector::insert(uint i, const type *d) - - Sets position \a i in the vector to contain the item \a d. \a i - must be less than size(). Any previous element in position \a i is - removed. - - Returns true if \a i is within range; otherwise returns false. - - \sa at() -*/ - -/*! - \fn bool Q3PtrVector::remove(uint i) - - Removes the item at position \a i in the vector, if there is one. - \a i must be less than size(). - - Returns true if \a i is within range; otherwise returns false. - - \sa take(), at() -*/ - -/*! - \fn type* Q3PtrVector::take(uint i) - - Returns the item at position \a i in the vector, and removes that - item from the vector. \a i must be less than size(). If there is - no item at position \a i, 0 is returned. - - Unlike remove(), this function does \e not call deleteItem() for - the removed item. - - \sa remove(), at() -*/ - -/*! - \fn void Q3PtrVector::clear() - - Removes all items from the vector, and destroys the vector itself. - - The vector becomes a null vector. - - \sa isNull() -*/ - -/*! - \fn bool Q3PtrVector::fill(const type *d, int size) - - Inserts item \a d in all positions in the vector. Any existing - items are removed. If \a d is 0, the vector becomes empty. - - If \a size >= 0, the vector is first resized to \a size. By - default, \a size is -1. - - Returns true if successful, i.e. \a size is the same as the - current size, or \a size is larger and the memory has successfully - been allocated; otherwise returns false. - - \sa resize(), insert(), isEmpty() -*/ - -/*! - \fn void Q3PtrVector::sort() - - Sorts the items in ascending order. Any empty positions will be - put last. - - Compares items using the virtual function compareItems(). - - \sa bsearch() -*/ - -/*! - \fn int Q3PtrVector::bsearch(const type* d) const - - In a sorted array, finds the first occurrence of \a d using a - binary search. For a sorted array, this is generally much faster - than find(), which performs a linear search. - - Returns the position of \a d, or -1 if \a d could not be found. \a - d must not be 0. - - Compares items using the virtual function compareItems(). - - \sa sort(), find() -*/ - - -/*! - \fn int Q3PtrVector::findRef(const type *d, uint i) const - - Finds the first occurrence of the item pointer \a d in the vector - using a linear search. The search starts at position \a i, which - must be less than size(). \a i is by default 0; i.e. the search - starts at the start of the vector. - - Returns the position of \a d, or -1 if \a d could not be found. - - This function does \e not use compareItems() to compare items. - - Use the much faster bsearch() to search a sorted vector. - - \sa find(), bsearch() -*/ - -/*! - \fn int Q3PtrVector::find(const type *d, uint i) const - - Finds the first occurrence of item \a d in the vector using a - linear search. The search starts at position \a i, which must be - less than size(). \a i is by default 0; i.e. the search starts at - the start of the vector. - - Returns the position of \a d, or -1 if \a d could not be found. - - Compares items using the virtual function compareItems(). - - Use the much faster bsearch() to search a sorted vector. - - \sa findRef(), bsearch() -*/ - - -/*! - \fn uint Q3PtrVector::containsRef(const type *d) const - - Returns the number of occurrences of the item pointer \a d in the - vector. - - This function does \e not use compareItems() to compare items. - - \sa findRef() -*/ - -/*! - \fn uint Q3PtrVector::contains(const type *d) const - - Returns the number of occurrences of item \a d in the vector. - - Compares items using the virtual function compareItems(). - - \sa containsRef() -*/ - -/*! - \fn type *Q3PtrVector::operator[](int i) const - - Returns the item at position \a i, or 0 if there is no item at - that position. \a i must be less than size(). - - Equivalent to at(\a i). - - \sa at() -*/ - -/*! - \fn type *Q3PtrVector::at(uint i) const - - Returns the item at position \a i, or 0 if there is no item at - that position. \a i must be less than size(). -*/ - - -/*! - \fn void Q3PtrVector::toList(Q3GList *list) const - - \internal - - Copies all items in this vector to the list \a list. \a list is - first cleared and then all items are appended to \a list. - - \sa Q3PtrList, Q3PtrStack, Q3PtrQueue -*/ - -/*! - \fn int Q3PtrVector::compareItems(Q3PtrCollection::Item d1, - Q3PtrCollection::Item d2) - - This virtual function compares two list items. - - Returns: - \list - \i zero if \a d1 == \a d2 - \i nonzero if \a d1 != \a d2 - \endlist - - This function returns \e int rather than \e bool so that - reimplementations can return one of three values and use it to - sort by: - \list - \i 0 if \a d1 == \a d2 - \i \> 0 (positive integer) if \a d1 \> \a d2 - \i \< 0 (negative integer) if \a d1 \< \a d2 - \endlist - - The sort() and bsearch() functions require compareItems() to be - implemented as described here. - - This function should not modify the vector because some const - functions call compareItems(). -*/ - -/*! - \fn QDataStream& Q3PtrVector::read(QDataStream &s, - Q3PtrCollection::Item &item) - - Reads a vector item, \a item, from the stream \a s and returns a - reference to the stream. - - The default implementation sets \a item to 0. - - \sa write() -*/ - -/*! - \fn QDataStream& Q3PtrVector::write(QDataStream &s, - Q3PtrCollection::Item item) const - - Writes a vector item, \a item, to the stream \a s and returns a - reference to the stream. - - The default implementation does nothing. - - \sa read() -*/ - -/*! - \fn bool Q3PtrVector::operator==(const Q3PtrVector<type> &v) const - - Returns true if this vector and \a v are equal; otherwise returns - false. -*/ diff --git a/doc/src/classes/q3sqlfieldinfo.qdoc b/doc/src/classes/q3sqlfieldinfo.qdoc deleted file mode 100644 index 6f6f359..0000000 --- a/doc/src/classes/q3sqlfieldinfo.qdoc +++ /dev/null @@ -1,234 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3SqlFieldInfo - \brief The Q3SqlFieldInfo class stores meta data associated with a SQL field. - - \compat - - Q3SqlFieldInfo objects only store meta data; field values are - stored in QSqlField objects. - - All values must be set in the constructor, and may be retrieved - using isRequired(), type(), length(), precision(), defaultValue(), - name(), isGenerated() and typeID(). - - \sa Q3SqlRecordInfo -*/ - -/*! - \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QString& name, - QVariant::Type typ, - int required, - int len, - int prec, - const QVariant& defValue, - int typeID, - bool generated, - bool trim, - bool calculated) - - Constructs a Q3SqlFieldInfo with the following parameters: - \table - \row \i \a name \i the name of the field. - \row \i \a typ \i the field's type in a QVariant. - \row \i \a required \i greater than 0 if the field is required, 0 - if its value can be NULL and less than 0 if it cannot be - determined whether the field is required or not. - \row \i \a len \i the length of the field. Note that for - non-character types some databases return either the length in - bytes or the number of digits. -1 signifies that the length cannot - be determined. - \row \i \a prec \i the precision of the field, or -1 if the field - has no precision or it cannot be determined. - \row \i \a defValue \i the default value that is inserted into - the table if none is specified by the user. QVariant() if there is - no default value or it cannot be determined. - \row \i \a typeID \i the internal typeID of the database system - (only useful for low-level programming). 0 if unknown. - \row \i \a generated \i TRUE indicates that this field should be - included in auto-generated SQL statments, e.g. in Q3SqlCursor. - \row \i \a trim \i TRUE indicates that widgets should remove - trailing whitespace from character fields. This does not affect - the field value but only its representation inside widgets. - \row \i \a calculated \i TRUE indicates that the value of this - field is calculated. The value of calculated fields can by - modified by subclassing Q3SqlCursor and overriding - Q3SqlCursor::calculateField(). - \endtable -*/ - -/*! - \fn Q3SqlFieldInfo::~Q3SqlFieldInfo() - - Destroys the object and frees any allocated resources. -*/ - -/*! - \fn Q3SqlFieldInfo::Q3SqlFieldInfo(const QSqlField & other) - - Creates a Q3SqlFieldInfo object with the type and the name of the - QSqlField \a other. -*/ - -/*! - \fn bool Q3SqlFieldInfo::operator==(const Q3SqlFieldInfo& other) const - - Assigns \a other to this field info and returns a reference to it. -*/ - -/*! - \fn QSqlField Q3SqlFieldInfo::toField() const - - Returns an empty QSqlField based on the information in this - Q3SqlFieldInfo. -*/ - -/*! - \fn int Q3SqlFieldInfo::isRequired() const - - Returns a value greater than 0 if the field is required (NULL - values are not allowed), 0 if it isn't required (NULL values are - allowed) or less than 0 if it cannot be determined whether the - field is required or not. -*/ - -/*! - \fn QVariant::Type Q3SqlFieldInfo::type() const - - Returns the field's type or QVariant::Invalid if the type is - unknown. -*/ - -/*! - \fn int Q3SqlFieldInfo::length() const - - Returns the field's length. For fields storing text the return - value is the maximum number of characters the field can hold. For - non-character fields some database systems return the number of - bytes needed or the number of digits allowed. If the length cannot - be determined -1 is returned. -*/ - -/*! - \fn int Q3SqlFieldInfo::precision() const - - Returns the field's precision or -1 if the field has no precision - or it cannot be determined. -*/ - -/*! - \fn QVariant Q3SqlFieldInfo::defaultValue() const - - Returns the field's default value or an empty QVariant if the - field has no default value or the value couldn't be determined. - The default value is the value inserted in the database when it - is not explicitly specified by the user. -*/ - -/*! - \fn QString Q3SqlFieldInfo::name() const - - Returns the name of the field in the SQL table. -*/ - -/*! - \fn int Q3SqlFieldInfo::typeID() const - - Returns the internal type identifier as returned from the database - system. The return value is 0 if the type is unknown. -*/ - -/*! - \fn bool Q3SqlFieldInfo::isGenerated() const - - Returns TRUE if the field should be included in auto-generated - SQL statments, e.g. in Q3SqlCursor; otherwise returns FALSE. - - \sa setGenerated() -*/ - -/*! - \fn bool Q3SqlFieldInfo::isTrim() const - - Returns TRUE if trailing whitespace should be removed from - character fields; otherwise returns FALSE. - - \sa setTrim() -*/ - -/*! - \fn bool Q3SqlFieldInfo::isCalculated() const - - Returns TRUE if the field is calculated; otherwise returns FALSE. - - \sa setCalculated() -*/ - -/*! - \fn void Q3SqlFieldInfo::setTrim(bool trim) - - If \a trim is TRUE widgets should remove trailing whitespace from - character fields. This does not affect the field value but only - its representation inside widgets. - - \sa isTrim() -*/ - -/*! - \fn void Q3SqlFieldInfo::setGenerated(bool generated) - - \a generated set to FALSE indicates that this field should not appear - in auto-generated SQL statements (for example in Q3SqlCursor). - - \sa isGenerated() -*/ - -/*! - \fn void Q3SqlFieldInfo::setCalculated(bool calculated) - - \a calculated set to TRUE indicates that this field is a calculated - field. The value of calculated fields can by modified by subclassing - Q3SqlCursor and overriding Q3SqlCursor::calculateField(). - - \sa isCalculated() -*/ diff --git a/doc/src/classes/q3sqlrecordinfo.qdoc b/doc/src/classes/q3sqlrecordinfo.qdoc deleted file mode 100644 index ce60f6d..0000000 --- a/doc/src/classes/q3sqlrecordinfo.qdoc +++ /dev/null @@ -1,89 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3SqlRecordInfo - \brief The Q3SqlRecordInfo class encapsulates a set of database field meta data. - - \compat - - This class is a list that holds a set of database field meta - data. Use contains() to see if a given field name exists in the - record, and use find() to get a QSqlFieldInfo record for a named - field. - - \sa Q3SqlFieldInfo -*/ - -/*! - \fn Q3SqlRecordInfo::Q3SqlRecordInfo() - - Constructs an empty record info object. -*/ - -/*! - \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const Q3SqlFieldInfoList& other) - \fn Q3SqlRecordInfo::Q3SqlRecordInfo(const QSqlRecord& other) - - Constructs a copy of \a other. -*/ - -/*! - \fn size_type Q3SqlRecordInfo::contains(const QString& fieldName) const - - Returns the number of times a field called \a fieldName occurs in - the record. Returns 0 if no field by that name could be found. -*/ - -/*! - \fn Q3SqlFieldInfo Q3SqlRecordInfo::find(const QString& fieldName) const - - Returns a QSqlFieldInfo object for the first field in the record - which has the field name \a fieldName. If no matching field is - found then an empty QSqlFieldInfo object is returned. -*/ - -/*! - \fn QSqlRecord Q3SqlRecordInfo::toRecord() const - - Returns an empty QSqlRecord based on the field information - in this Q3SqlRecordInfo. -*/ diff --git a/doc/src/classes/q3valuelist.qdoc b/doc/src/classes/q3valuelist.qdoc deleted file mode 100644 index 062a9da..0000000 --- a/doc/src/classes/q3valuelist.qdoc +++ /dev/null @@ -1,569 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3ValueList - \brief The Q3ValueList class is a value-based template class that - provides lists. - \compat - - Q3ValueList is a Qt implementation of an STL-like list container. - It can be used in your application if the standard \c list is not - available for your target platforms. - - Q3ValueList\<T\> defines a template instance to create a list of - values that all have the class T. Note that Q3ValueList does not - store pointers to the members of the list; it holds a copy of - every member. This is why these kinds of classes are called "value - based"; Q3PtrList and Q3Dict are "pointer based". - - Q3ValueList contains and manages a collection of objects of type T - and provides iterators that allow the contained objects to be - addressed. Q3ValueList owns the contained items. For more relaxed - ownership semantics, see Q3PtrCollection and friends which are - pointer-based containers. - - Some classes cannot be used within a Q3ValueList, for example, all - classes derived from QObject and thus all classes that implement - widgets. Only values can be used in a Q3ValueList. To qualify as a - value the class must provide: - \list - \i a copy constructor; - \i an assignment operator; - \i a default constructor, i.e. a constructor that does not take any arguments. - \endlist - - Note that C++ defaults to field-by-field assignment operators and - copy constructors if no explicit version is supplied. In many - cases this is sufficient. - - In addition, some compilers (e.g. Sun CC) might require that the - class provides an equality operator (operator==()). - - Q3ValueList's function naming is consistent with the other Qt - classes (e.g. count(), isEmpty()). Q3ValueList also provides extra - functions for compatibility with STL algorithms, such as size() - and empty(). Programmers already familiar with the STL \c list may - prefer to use the STL-compatible functions. - - Example: - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 0 - - - Notice that the latest changes to Mary's salary did not affect the - value in the list because the list created a copy of Mary's entry. - - There are several ways to find items in the list. The begin() and - end() functions return iterators to the beginning and end of the - list. The advantage of getting an iterator is that you can move - forward or backward from this position by - incrementing/decrementing the iterator. The iterator returned by - end() points to the item which is one \e past the last item in the - container. The past-the-end iterator is still associated with the - list it belongs to, however it is \e not dereferenceable; - operator*() will not return a well-defined value. If the list is - empty(), the iterator returned by begin() will equal the iterator - returned by end(). - - It is safe to have multiple iterators a the list at the same - time. If some member of the list is removed, only iterators - pointing to the removed member become invalid. Inserting into the - list does not invalidate any iterator. For convenience, the - function last() returns a reference to the last item in the list, - and first() returns a reference to the first item. If the - list is empty(), both last() and first() have undefined behavior - (your application will crash or do unpredictable things). Use - last() and first() with caution, for example: - - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 1 - - Because Q3ValueList is value-based there is no need to be careful - about deleting items in the list. The list holds its own copies - and will free them if the corresponding member or the list itself - is deleted. You can force the list to free all of its items with - clear(). - - Q3ValueList is shared implicitly, which means it can be copied in - constant time, i.e. O(1). If multiple Q3ValueList instances share - the same data and one needs to modify its contents, this modifying - instance makes a copy and modifies its private copy; therefore it - does not affect the other instances; this takes O(n) time. This is - often called "copy on write". If a Q3ValueList is being used in a - multi-threaded program, you must protect all access to the list. - See \l QMutex. - - There are several ways to insert items into the list. The - prepend() and append() functions insert items at the beginning and - the end of the list respectively. The insert() function comes in - several flavors and can be used to add one or more items at - specific positions within the list. - - Items can also be removed from the list in several ways. There - are several variants of the remove() function, which removes a - specific item from the list. The remove() function will find and - remove items according to a specific item value. - - \sa Q3ValueListIterator -*/ - -/*! \typedef Q3ValueList::iterator - The list's iterator type, Q3ValueListIterator. */ -/*! \typedef Q3ValueList::const_iterator - The list's const iterator type, Q3ValueListConstIterator. */ -/*! \typedef Q3ValueList::value_type - The type of the object stored in the list, T. */ -/*! \typedef Q3ValueList::pointer - The pointer to T type. */ -/*! \typedef Q3ValueList::const_pointer - The const pointer to T type. */ -/*! \typedef Q3ValueList::reference - The reference to T type. */ -/*! \typedef Q3ValueList::const_reference - The const reference to T type. */ -/*! \typedef Q3ValueList::size_type - An unsigned integral type, used to represent various sizes. */ -/*! \typedef Q3ValueList::difference_type - \internal -*/ -/*! - \fn Q3ValueList::Q3ValueList() - - Constructs an empty list. -*/ - -/*! - \fn Q3ValueList::Q3ValueList( const Q3ValueList<T>& l ) - \fn Q3ValueList::Q3ValueList( const QList<T>& l ) - \fn Q3ValueList::Q3ValueList( const QLinkedList<T>& l ) - - Constructs a copy of \a l. -*/ - -/*! - \fn Q3ValueList::Q3ValueList( const std::list<T>& l ) - - Contructs a copy of \a l. - - This constructor is provided for compatibility with STL - containers. -*/ - -/*! - \fn Q3ValueList::~Q3ValueList() - - Destroys the list. References to the values in the list and all - iterators of this list become invalidated. Note that it is - impossible for an iterator to check whether or not it is valid: - Q3ValueList is highly tuned for performance, not for error - checking. -*/ - -/*! - \fn bool Q3ValueList::operator== ( const Q3ValueList<T>& l ) const - - Compares both lists. - - Returns TRUE if this list and \a l are equal; otherwise returns - FALSE. -*/ - -/*! - \fn bool Q3ValueList::operator== ( const std::list<T>& l ) const - - \overload - - Returns TRUE if this list and \a l are equal; otherwise returns - FALSE. - - This operator is provided for compatibility with STL containers. -*/ - -/*! - \fn Q3ValueList<T>& Q3ValueList::operator= ( const Q3ValueList<T>& l ) - - Assigns \a l to this list and returns a reference to this list. - - All iterators of the current list become invalidated by this - operation. The cost of such an assignment is O(1) since Q3ValueList - is implicitly shared. -*/ - -/*! - \fn Q3ValueList<T>& Q3ValueList::operator= ( const QList<T>& l ) - - Assigns \a l to this list and returns a reference to this list. - - All iterators of the current list become invalidated by this - operation. -*/ - -/*! - \fn Q3ValueList<T>& Q3ValueList::operator= ( const std::list<T>& l ) - - \overload - - Assigns the contents of \a l to the list. - - All iterators of the current list become invalidated by this - operation. -*/ - -/*! - \fn bool Q3ValueList::operator!= ( const Q3ValueList<T>& l ) const - - Compares both lists. - - Returns TRUE if this list and \a l are unequal; otherwise returns - FALSE. -*/ - -/*! - \fn iterator Q3ValueList::insert( typename Q3ValueList<T>::Iterator it, const T& x ) - - Inserts the value \a x in front of the item pointed to by the - iterator, \a it. - - Returns an iterator pointing at the inserted item. - - \sa append(), prepend() -*/ - -/*! - \fn uint Q3ValueList::remove( const T& x ) - - \overload - - Removes all items that have value \a x and returns the number of - removed items. -*/ - -/*! - \fn QDataStream& operator>>( QDataStream& s, Q3ValueList<T>& l ) - - \relates Q3ValueList - - Reads a list, \a l, from the stream \a s. The type T stored in the - list must implement the streaming operator. -*/ - -/*! - \fn QDataStream& operator<<( QDataStream& s, const Q3ValueList<T>& l ) - - \overload - \relates Q3ValueList - - Writes a list, \a l, to the stream \a s. The type T stored in the - list must implement the streaming operator. -*/ - -/*! - \fn void Q3ValueList::insert( typename Q3ValueList<T>::Iterator pos, - typename Q3ValueList<T>::size_type n, const T& x ) - - \overload - - Inserts \a n copies of \a x before position \a pos. -*/ - -/*! - \fn Q3ValueList<T>& Q3ValueList::operator<< ( const T& x ) - - Adds the value \a x to the end of the list. - - Returns a reference to the list. -*/ - -/*! - \fn const T& Q3ValueList::operator[] ( typename Q3ValueList<T>::size_type i ) const - - Returns a const reference to the item with index \a i in the list. - It is up to you to check whether this item really exists. You can - do that easily with the count() function. However this operator - does not check whether \a i is in range and will deliver undefined - results if it does not exist. - - \warning This function uses a linear search and can be extremely - slow for large lists. Q3ValueList is not optimized for random item - access. If you need random access use a different container, such - as Q3ValueVector. -*/ - -/*! - \fn T& Q3ValueList::operator[] ( typename Q3ValueList<T>::size_type i ) - - \overload - - Returns a non-const reference to the item with index \a i. -*/ - -/*! - \fn const_iterator Q3ValueList::at( typename Q3ValueList<T>::size_type i ) const - - Returns an iterator pointing to the item at position \a i in the - list, or an undefined value if the index is out of range. - - \warning This function uses a linear search and can be extremely - slow for large lists. Q3ValueList is not optimized for random item - access. If you need random access use a different container, such - as Q3ValueVector. -*/ - -/*! - \fn iterator Q3ValueList::at( typename Q3ValueList<T>::size_type i ) - - \overload - - Returns an iterator pointing to the item at position \a i in the - list, or an undefined value if the index is out of range. - -*/ - -/*! - \fn iterator Q3ValueList::fromLast() - - \overload - - Returns an iterator to the last item in the list, or end() if - there is no last item. - - Use the end() function instead. For example: - - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 2 - -*/ - -/*! - \fn const_iterator Q3ValueList::fromLast() const - - Returns an iterator to the last item in the list, or end() if - there is no last item. - - Use the end() function instead. For example: - - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 3 - -*/ - -/*! - \fn Q3ValueList<T> Q3ValueList::operator+( const Q3ValueList<T>& l ) const - - Creates a new list and fills it with the items of this list. Then - the items of \a l are appended. Returns the new list. -*/ - -/*! - \fn Q3ValueList<T>& Q3ValueList::operator+= ( const Q3ValueList<T>& l ) - - Appends the items of \a l to this list. Returns a reference to - this list. -*/ - -/*! - \fn Q3ValueList<T>& Q3ValueList::operator+= ( const T& x ) - - \overload - - Appends the value \a x to the list. Returns a reference to the - list. -*/ - -/*! - \fn iterator Q3ValueList::append( const T& x ) - - Inserts \a x at the end of the list. - - \sa insert(), prepend() -*/ - -/*! - \fn iterator Q3ValueList::prepend( const T& x ) - - Inserts \a x at the beginning of the list. - - \sa insert(), append() -*/ - -/*! - \fn iterator Q3ValueList::remove( typename Q3ValueList<T>::Iterator it ) - - Removes the item pointed to by \a it from the list. No iterators - other than \a it or other iterators pointing at the same item as - \a it are invalidated. Returns an iterator to the next item after - \a it, or end() if there is no such item. - - \sa clear() -*/ - -/*! - \fn uint Q3ValueList::contains( const T& x ) const - - Returns the number of occurrences of the value \a x in the list. -*/ - -/*! - \class Q3ValueListIterator - \brief The Q3ValueListIterator class provides an iterator for Q3ValueList. - \compat - - An iterator is a class for accessing the items of a container - class: a generalization of the index in an array. A pointer - into a "const char *" and an index into an "int[]" are both - iterators, and the general idea is to provide that functionality - for any data structure. - - The Q3ValueListIterator class is an iterator for Q3ValueList - instantiations. You can create the appropriate iterator type by - using the \c iterator typedef provided by Q3ValueList. - - The only way to access the items in a Q3ValueList is to use an - iterator. - - Example (see Q3ValueList for the complete code): - \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 4 - - Q3ValueList is highly optimized for performance and memory usage. - This means that you must be careful: Q3ValueList does not know - about all its iterators and the iterators don't know to which list - they belong. This makes things very fast, but if you're not - careful, you can get spectacular bugs. Always make sure iterators - are valid before dereferencing them or using them as parameters to - generic algorithms in the STL. - - Using an invalid iterator is undefined (your application will - probably crash). Many Qt functions return const value lists; to - iterate over these you should make a copy and iterate over the - copy. - - For every Iterator there is a ConstIterator. When accessing a - Q3ValueList in a const environment or if the reference or pointer - to the list is itself const, then you must use the ConstIterator. - Its semantics are the same as the Iterator, but it only returns - const references. - - \sa Q3ValueList, Q3ValueListConstIterator -*/ - -/*! - \fn Q3ValueListIterator::Q3ValueListIterator() - - Constructs an unitialized iterator. -*/ - -/*! - \fn Q3ValueListIterator::Q3ValueListIterator(const Q3ValueListIterator &o) - \fn Q3ValueListIterator::Q3ValueListIterator(const typename QLinkedList<T>::iterator &o) - - Constucts a copy of iterator \a o. -*/ - -/*! - \class Q3ValueListConstIterator - \brief The Q3ValueListConstIterator class provides a const iterator - for Q3ValueList. - \compat - - In contrast to Q3ValueListIterator, this class is used to iterate - over a const list. It does not allow modification of the values of - the list since that would break const semantics. - - You can create the appropriate const iterator type by using the \c - const_iterator typedef provided by Q3ValueList. - - For more information on Q3ValueList iterators, see - Q3ValueListIterator. - - \sa Q3ValueListIterator, Q3ValueList -*/ - -/*! - \fn Q3ValueListConstIterator::Q3ValueListConstIterator() - - Constructs an unitialized iterator. -*/ - -/*! - \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const Q3ValueListConstIterator &o) - \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList<T>::const_iterator &o) - \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList<T>::iterator &o) - - Constructs a copy of iterator \a o. -*/ - -/*! - \typedef Q3ValueList::Iterator - - This iterator is an instantiation of Q3ValueListIterator for the - same type as this Q3ValueList. In other words, if you instantiate - Q3ValueList<int>, Iterator is a Q3ValueListIterator<int>. Several - member function use it, such as Q3ValueList::begin(), which returns - an iterator pointing to the first item in the list. - - Functionally, this is almost the same as ConstIterator. The only - difference is that you cannot use ConstIterator for non-const - operations, and that the compiler can often generate better code - if you use ConstIterator. - - \sa Q3ValueListIterator ConstIterator -*/ - -/*! - \typedef Q3ValueList::ConstIterator - - This iterator is an instantiation of Q3ValueListConstIterator for - the same type as this Q3ValueList. In other words, if you - instantiate Q3ValueList<int>, ConstIterator is a - Q3ValueListConstIterator<int>. Several member function use it, such - as Q3ValueList::begin(), which returns an iterator pointing to the - first item in the list. - - Functionally, this is almost the same as Iterator. The only - difference is you cannot use ConstIterator for non-const - operations, and that the compiler can often generate better code - if you use ConstIterator. - - \sa Q3ValueListIterator Iterator -*/ - -/*! - \fn Q3ValueList::operator QList<T>() const - - Automatically converts a Q3ValueList<T> into a QList<T>. -*/ diff --git a/doc/src/classes/q3valuestack.qdoc b/doc/src/classes/q3valuestack.qdoc deleted file mode 100644 index bc44235..0000000 --- a/doc/src/classes/q3valuestack.qdoc +++ /dev/null @@ -1,149 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3ValueStack - \brief The Q3ValueStack class is a value-based template class that provides a stack. - \compat - - Define a template instance Q3ValueStack\<X\> to create a stack of - values that all have the class X. - - Note that Q3ValueStack does not store pointers to the members of - the stack; it holds a copy of every member. That is why these - kinds of classes are called "value based"; Q3PtrStack, Q3PtrList, - Q3Dict, etc., are "pointer based". - - A stack is a last in, first out (LIFO) structure. Items are added - to the top of the stack with push() and retrieved from the top - with pop(). The top() function provides access to the topmost item - without removing it. - - Example: - \snippet doc/src/snippets/code/doc_src_q3valuestack.qdoc 0 - - Q3ValueStack is a specialized Q3ValueList provided for convenience. - All of Q3ValueList's functionality also applies to Q3PtrStack, for - example the facility to iterate over all elements using - Q3ValueStack<T>::Iterator. See Q3ValueListIterator for further - details. - - Some classes cannot be used within a Q3ValueStack, for example - everything derived from QObject and thus all classes that - implement widgets. Only values can be used in a Q3ValueStack. To - qualify as a value, the class must provide - \list - \i a copy constructor; - \i an assignment operator; - \i a default constructor, i.e. a constructor that does not take any arguments. - \endlist - - Note that C++ defaults to field-by-field assignment operators and - copy constructors if no explicit version is supplied. In many - cases this is sufficient. -*/ - - -/*! - \fn Q3ValueStack::Q3ValueStack() - - Constructs an empty stack. -*/ - -/*! - \fn Q3ValueStack::~Q3ValueStack() - - Destroys the stack. References to the values in the stack and all - iterators of this stack become invalidated. Because Q3ValueStack is - highly tuned for performance, you won't see warnings if you use - invalid iterators because it is impossible for an iterator to - check whether or not it is valid. -*/ - - -/*! - \fn void Q3ValueStack::push( const T& d ) - - Adds element, \a d, to the top of the stack. Last in, first out. - - This function is equivalent to append(). - - \sa pop(), top() -*/ - -/*! - \fn T& Q3ValueStack::top() - - Returns a reference to the top item of the stack or the item - referenced by end() if no such item exists. Note that you must not - change the value the end() iterator points to. - - This function is equivalent to last(). - - \sa pop(), push(), Q3ValueList::fromLast() -*/ - - -/*! - \fn const T& Q3ValueStack::top() const - - \overload - - Returns a reference to the top item of the stack or the item - referenced by end() if no such item exists. - - This function is equivalent to last(). - - \sa pop(), push(), Q3ValueList::fromLast() -*/ - -/*! - \fn T Q3ValueStack::pop() - - Removes the top item from the stack and returns it. - - \sa top() push() -*/ - - - - - diff --git a/doc/src/classes/q3valuevector.qdoc b/doc/src/classes/q3valuevector.qdoc deleted file mode 100644 index 4ab8896..0000000 --- a/doc/src/classes/q3valuevector.qdoc +++ /dev/null @@ -1,274 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class Q3ValueVector - \brief The Q3ValueVector class is a value-based template class that provides a dynamic array. - \compat - - Q3ValueVector is a Qt implementation of an STL-like vector - container. It can be used in your application if the standard \c - vector is not available for your target platforms. - - Q3ValueVector\<T\> defines a template instance to create a vector - of values that all have the class T. Q3ValueVector does not store - pointers to the members of the vector; it holds a copy of every - member. Q3ValueVector is said to be value based; in contrast, - Q3PtrList and Q3Dict are pointer based. - - Q3ValueVector contains and manages a collection of objects of type - T and provides random access iterators that allow the contained - objects to be addressed. Q3ValueVector owns the contained - elements. For more relaxed ownership semantics, see Q3PtrCollection - and friends, which are pointer-based containers. - - Q3ValueVector provides good performance if you append or remove - elements from the end of the vector. If you insert or remove - elements from anywhere but the end, performance is very bad. The - reason for this is that elements must to be copied into new - positions. - - Some classes cannot be used within a Q3ValueVector: for example, - all classes derived from QObject and thus all classes that - implement widgets. Only values can be used in a Q3ValueVector. To - qualify as a value the class must provide: - \list - \i a copy constructor; - \i an assignment operator; - \i a default constructor, i.e., a constructor that does not take any arguments. - \endlist - - Note that C++ defaults to field-by-field assignment operators and - copy constructors if no explicit version is supplied. In many - cases this is sufficient. - - Q3ValueVector uses an STL-like syntax to manipulate and address the - objects it contains. - - Example: - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 0 - - Program output: - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 1 - - As you can see, the most recent change to Joe's salary did not - affect the value in the vector because the vector created a copy - of Joe's entry. - - Many Qt functions return const value vectors; to iterate over - these you should make a copy and iterate over the copy. - - There are several ways to find items in the vector. The begin() - and end() functions return iterators to the beginning and end of - the vector. The advantage of getting an iterator is that you can - move forward or backward from this position by - incrementing/decrementing the iterator. The iterator returned by - end() points to the element which is one past the last element in - the container. The past-the-end iterator is still associated with - the vector it belongs to, however it is \e not dereferenceable; - operator*() will not return a well-defined value. If the vector is - empty(), the iterator returned by begin() will equal the iterator - returned by end(). - - The fastest way to access an element of a vector is by using - operator[]. This function provides random access and will return - a reference to the element located at the specified index. Thus, - you can access every element directly, in constant time, providing - you know the location of the element. It is undefined to access - an element that does not exist (your application will probably - crash). For example: - - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 2 - - Whenever inserting, removing or referencing elements in a vector, - always make sure you are referring to valid positions. For - example: - - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 3 - - The iterators provided by vector are random access iterators, - therefore you can use them with many generic algorithms, for - example, algorithms provided by the STL. - - It is safe to have multiple iterators on the vector at the same - time. Since Q3ValueVector manages memory dynamically, all iterators - can become invalid if a memory reallocation occurs. For example, - if some member of the vector is removed, iterators that point to - the removed element and to all following elements become - invalidated. Inserting into the middle of the vector will - invalidate all iterators. For convenience, the function back() - returns a reference to the last element in the vector, and front() - returns a reference to the first element. If the vector is - empty(), both back() and front() have undefined behavior (your - application will crash or do unpredictable things). Use back() and - front() with caution, for example: - - \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 4 - - Because Q3ValueVector manages memory dynamically, it is recommended - that you contruct a vector with an initial size. Inserting and - removing elements happens fastest when: - \list - \i Inserting or removing elements happens at the end() of the - vector; - \i The vector does not need to allocate additional memory. - \endlist - - By creating a Q3ValueVector with a sufficiently large initial size, - there will be less memory allocations. Do not use an initial size - that is too big, since it will still take time to construct all - the empty entries, and the extra space will be wasted if it is - never used. - - Because Q3ValueVector is value-based there is no need to be careful - about deleting elements in the vector. The vector holds its own - copies and will free them if the corresponding member or the - vector itself is deleted. You can force the vector to free all of - its items with clear(). - - Q3ValueVector is shared implicitly, which means it can be copied in - constant time. If multiple Q3ValueVector instances share the same - data and one needs to modify its contents, this modifying instance - makes a copy and modifies its private copy; it thus does not - affect the other instances. This is often called "copy on write". - If a Q3ValueVector is being used in a multi-threaded program, you - must protect all access to the vector. See QMutex. - - There are several ways to insert elements into the vector. The - push_back() function insert elements into the end of the vector, - and is usually fastest. The insert() function can be used to add - elements at specific positions within the vector. - - Items can be also be removed from the vector in several ways. - There are several variants of the erase() function which removes a - specific element, or range of elements, from the vector. - - Q3ValueVector stores its elements in contiguous memory. This means - that you can use a Q3ValueVector in any situation that requires an - array. -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector() - - Constructs an empty vector without any elements. To create a - vector which reserves an initial amount of space for elements, use - \c Q3ValueVector(size_type n). -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector( const Q3ValueVector<T>& v ) - - Constructs a copy of \a v. - - This operation costs O(1) time because Q3ValueVector is implicitly - shared. - - The first modification to the vector does takes O(n) time, because - the elements must be copied. -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector( const std::vector<T>& v ) - - This operation costs O(n) time because \a v is copied. -*/ - -/*! - \fn Q3ValueVector::Q3ValueVector( QVector<T>::size_type n, const T& val ) - - Constructs a vector with an initial size of \a n elements. Each - element is initialized with the value of \a val. -*/ - -/*! - \fn Q3ValueVector<T>& Q3ValueVector::operator=( const Q3ValueVector<T>& v ) - - Assigns \a v to this vector and returns a reference to this vector. - - All iterators of the current vector become invalidated by this - operation. The cost of such an assignment is O(1) since - Q3ValueVector is implicitly shared. -*/ - -/*! - \fn Q3ValueVector<T>& Q3ValueVector::operator=( const std::vector<T>& v ) - - \overload - - Assigns \a v to this vector and returns a reference to this vector. - - All iterators of the current vector become invalidated by this - operation. The cost of this assignment is O(n) since \a v is - copied. -*/ - -/*! - \fn T &Q3ValueVector::at( int i , bool* ok ) - - Returns a reference to the element with index \a i. If \a ok is - non-null, and the index \a i is out of range, *\a ok is set to - FALSE and the returned reference is undefined. If the index \a i - is within the range of the vector, and \a ok is non-null, *\a ok - is set to TRUE and the returned reference is well defined. -*/ - -/*! - \fn const T &Q3ValueVector::at( int i , bool* ok ) const - - \overload - - Returns a const reference to the element with index \a i. If \a ok - is non-null, and the index \a i is out of range, *\a ok is set to - FALSE and the returned reference is undefined. If the index \a i - is within the range of the vector, and \a ok is non-null, *\a ok - is set to TRUE and the returned reference is well defined. -*/ - -/*! - \fn void Q3ValueVector::resize( int n, const T& val = T() ) - - Changes the size of the vector to \a n. If \a n is greater than - the current size(), elements are added to the end and initialized - with the value of \a val. If \a n is less than size(), elements - are removed from the end. If \a n is equal to size() nothing - happens. -*/ diff --git a/doc/src/classes/qalgorithms.qdoc b/doc/src/classes/qalgorithms.qdoc deleted file mode 100644 index 0b30879..0000000 --- a/doc/src/classes/qalgorithms.qdoc +++ /dev/null @@ -1,651 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \headerfile <QtAlgorithms> - \title Generic Algorithms - \ingroup architecture - - \brief The <QtAlgorithms> header provides generic template-based algorithms. - - Qt provides a number of global template functions in \c - <QtAlgorithms> that work on containers and perform well-know - algorithms. You can use these algorithms with any \l {container - class} that provides STL-style iterators, including Qt's QList, - QLinkedList, QVector, QMap, and QHash classes. - - These functions have taken their inspiration from similar - functions available in the STL \c <algorithm> header. Most of them - have a direct STL equivalent; for example, qCopyBackward() is the - same as STL's copy_backward() algorithm. - - If STL is available on all your target platforms, you can use the - STL algorithms instead of their Qt counterparts. One reason why - you might want to use the STL algorithms is that STL provides - dozens and dozens of algorithms, whereas Qt only provides the most - important ones, making no attempt to duplicate functionality that - is already provided by the C++ standard. - - Most algorithms take \l {STL-style iterators} as parameters. The - algorithms are generic in the sense that they aren't bound to a - specific iterator class; you can use them with any iterators that - meet a certain set of requirements. - - Let's take the qFill() algorithm as an example. Unlike QVector, - QList has no fill() function that can be used to fill a list with - a particular value. If you need that functionality, you can use - qFill(): - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 0 - - qFill() takes a begin iterator, an end iterator, and a value. - In the example above, we pass \c list.begin() and \c list.end() - as the begin and end iterators, but this doesn't have to be - the case: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 1 - - Different algorithms can have different requirements for the - iterators they accept. For example, qFill() accepts two - \l {forward iterators}. The iterator types required are specified - for each algorithm. If an iterator of the wrong type is passed (for - example, if QList::ConstIterator is passed as an \l {output - iterator}), you will always get a compiler error, although not - necessarily a very informative one. - - Some algorithms have special requirements on the value type - stored in the containers. For example, qEqual() requires that the - value type supports operator==(), which it uses to compare items. - Similarly, qDeleteAll() requires that the value type is a - non-const pointer type (for example, QWidget *). The value type - requirements are specified for each algorithm, and the compiler - will produce an error if a requirement isn't met. - - \target binaryFind example - - The generic algorithms can be used on other container classes - than those provided by Qt and STL. The syntax of STL-style - iterators is modeled after C++ pointers, so it's possible to use - plain arrays as containers and plain pointers as iterators. A - common idiom is to use qBinaryFind() together with two static - arrays: one that contains a list of keys, and another that - contains a list of associated values. For example, the following - code will look up an HTML entity (e.g., \c &) in the \c - name_table array and return the corresponding Unicode value from - the \c value_table if the entity is recognized: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 2 - - This kind of code is for advanced users only; for most - applications, a QMap- or QHash-based approach would work just as - well: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 3 - - \section1 Types of Iterators - - The algorithms have certain requirements on the iterator types - they accept, and these are specified individually for each - function. The compiler will produce an error if a requirement - isn't met. - - \section2 Input Iterators - - An \e{input iterator} is an iterator that can be used for reading - data sequentially from a container. It must provide the following - operators: \c{==} and \c{!=} for comparing two iterators, unary - \c{*} for retrieving the value stored in the item, and prefix - \c{++} for advancing to the next item. - - The Qt containers' iterator types (const and non-const) are all - input iterators. - - \section2 Output Iterators - - An \e{output iterator} is an iterator that can be used for - writing data sequentially to a container or to some output - stream. It must provide the following operators: unary \c{*} for - writing a value (i.e., \c{*it = val}) and prefix \c{++} for - advancing to the next item. - - The Qt containers' non-const iterator types are all output - iterators. - - \section2 Forward Iterators - - A \e{forward iterator} is an iterator that meets the requirements - of both input iterators and output iterators. - - The Qt containers' non-const iterator types are all forward - iterators. - - \section2 Bidirectional Iterators - - A \e{bidirectional iterator} is an iterator that meets the - requirements of forward iterators but that in addition supports - prefix \c{--} for iterating backward. - - The Qt containers' non-const iterator types are all bidirectional - iterators. - - \section2 Random Access Iterators - - The last category, \e{random access iterators}, is the most - powerful type of iterator. It supports all the requirements of a - bidirectional iterator, and supports the following operations: - - \table - \row \i \c{i += n} \i advances iterator \c i by \c n positions - \row \i \c{i -= n} \i moves iterator \c i back by \c n positions - \row \i \c{i + n} or \c{n + i} \i returns the iterator for the item \c - n positions ahead of iterator \c i - \row \i \c{i - n} \i returns the iterator for the item \c n positions behind of iterator \c i - \row \i \c{i - j} \i returns the number of items between iterators \c i and \c j - \row \i \c{i[n]} \i same as \c{*(i + n)} - \row \i \c{i < j} \i returns true if iterator \c j comes after iterator \c i - \endtable - - QList and QVector's non-const iterator types are random access iterators. - - \sa {container classes}, <QtGlobal> -*/ - -/*! \fn OutputIterator qCopy(InputIterator begin1, InputIterator end1, OutputIterator begin2) - \relates <QtAlgorithms> - - Copies the items from range [\a begin1, \a end1) to range [\a - begin2, ...), in the order in which they appear. - - The item at position \a begin1 is assigned to that at position \a - begin2; the item at position \a begin1 + 1 is assigned to that at - position \a begin2 + 1; and so on. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 4 - - \sa qCopyBackward(), {input iterators}, {output iterators} -*/ - -/*! \fn BiIterator2 qCopyBackward(BiIterator1 begin1, BiIterator1 end1, BiIterator2 end2) - \relates <QtAlgorithms> - - Copies the items from range [\a begin1, \a end1) to range [..., - \a end2). - - The item at position \a end1 - 1 is assigned to that at position - \a end2 - 1; the item at position \a end1 - 2 is assigned to that - at position \a end2 - 2; and so on. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 5 - - \sa qCopy(), {bidirectional iterators} -*/ - -/*! \fn bool qEqual(InputIterator1 begin1, InputIterator1 end1, InputIterator2 begin2) - \relates <QtAlgorithms> - - Compares the items in the range [\a begin1, \a end1) with the - items in the range [\a begin2, ...). Returns true if all the - items compare equal; otherwise returns false. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 6 - - This function requires the item type (in the example above, - QString) to implement \c operator==(). - - \sa {input iterators} -*/ - -/*! \fn void qFill(ForwardIterator begin, ForwardIterator end, const T &value) - \relates <QtAlgorithms> - - Fills the range [\a begin, \a end) with \a value. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 7 - - \sa qCopy(), {forward iterators} -*/ - -/*! \fn void qFill(Container &container, const T &value) - \relates <QtAlgorithms> - - \overload - - This is the same as qFill(\a{container}.begin(), \a{container}.end(), \a value); -*/ - -/*! \fn InputIterator qFind(InputIterator begin, InputIterator end, const T &value) - \relates <QtAlgorithms> - - Returns an iterator to the first occurrence of \a value in a - container in the range [\a begin, \a end). Returns \a end if \a - value isn't found. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 8 - - This function requires the item type (in the example above, - QString) to implement \c operator==(). - - If the items in the range are in ascending order, you can get - faster results by using qLowerBound() or qBinaryFind() instead of - qFind(). - - \sa qBinaryFind(), {input iterators} -*/ - -/*! \fn void qFind(const Container &container, const T &value) - \relates <QtAlgorithms> - - \overload - - This is the same as qFind(\a{container}.begin(), \a{container}.end(), value); -*/ - -/*! \fn void qCount(InputIterator begin, InputIterator end, const T &value, Size &n) - \relates <QtAlgorithms> - - Returns the number of occurrences of \a value in the range [\a begin, \a end), - which is returned in \a n. \a n is never initialized, the count is added to \a n. - It is the caller's responsibility to initialize \a n. - - Example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 9 - - This function requires the item type (in the example above, - \c int) to implement \c operator==(). - - \sa {input iterators} -*/ - -/*! \fn void qCount(const Container &container, const T &value, Size &n) -\relates <QtAlgorithms> - -\overload - -Instead of operating on iterators, as in the other overload, this function -operates on the specified \a container to obtain the number of instances -of \a value in the variable passed as a reference in argument \a n. -*/ - -/*! \fn void qSwap(T &var1, T &var2) - \relates <QtAlgorithms> - - Exchanges the values of variables \a var1 and \a var2. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 10 -*/ - -/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end) - \relates <QtAlgorithms> - - Sorts the items in range [\a begin, \a end) in ascending order - using the quicksort algorithm. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 11 - - The sort algorithm is efficient on large data sets. It operates - in \l {linear-logarithmic time}, O(\e{n} log \e{n}). - - This function requires the item type (in the example above, - \c{int}) to implement \c operator<(). - - If neither of the two items is "less than" the other, the items are - taken to be equal. It is then undefined which one of the two - items will appear before the other after the sort. - - \sa qStableSort(), {random access iterators} -*/ - -/*! \fn void qSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan) - \relates <QtAlgorithms> - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - For example, here's how to sort the strings in a QStringList - in case-insensitive alphabetical order: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 12 - - To sort values in reverse order, pass - \l{qGreater()}{qGreater<T>()} as the \a lessThan parameter. For - example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 13 - - If neither of the two items is "less than" the other, the items are - taken to be equal. It is then undefined which one of the two - items will appear before the other after the sort. - - An alternative to using qSort() is to put the items to sort in a - QMap, using the sort key as the QMap key. This is often more - convenient than defining a \a lessThan function. For example, the - following code shows how to sort a list of strings case - insensitively using QMap: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 14 - - \sa QMap -*/ - -/*! \fn void qSort(Container &container) - \relates <QtAlgorithms> - - \overload - - This is the same as qSort(\a{container}.begin(), \a{container}.end()); -*/ - -/*! - \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end) - \relates <QtAlgorithms> - - Sorts the items in range [\a begin, \a end) in ascending order - using a stable sorting algorithm. - - If neither of the two items is "less than" the other, the items are - taken to be equal. The item that appeared before the other in the - original container will still appear first after the sort. This - property is often useful when sorting user-visible data. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 15 - - The sort algorithm is efficient on large data sets. It operates - in \l {linear-logarithmic time}, O(\e{n} log \e{n}). - - This function requires the item type (in the example above, - \c{int}) to implement \c operator<(). - - \sa qSort(), {random access iterators} -*/ - -/*! - \fn void qStableSort(RandomAccessIterator begin, RandomAccessIterator end, LessThan lessThan) - \relates <QtAlgorithms> - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - For example, here's how to sort the strings in a QStringList - in case-insensitive alphabetical order: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 16 - - Note that earlier versions of Qt allowed using a lessThan function that took its - arguments by non-const reference. From 4.3 and on this is no longer possible, - the arguments has to be passed by const reference or value. - - To sort values in reverse order, pass - \l{qGreater()}{qGreater<T>()} as the \a lessThan parameter. For - example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 17 - - If neither of the two items is "less than" the other, the items are - taken to be equal. The item that appeared before the other in the - original container will still appear first after the sort. This - property is often useful when sorting user-visible data. -*/ - -/*! - \fn void qStableSort(Container &container) - \relates <QtAlgorithms> - - \overload - - This is the same as qStableSort(\a{container}.begin(), \a{container}.end()); -*/ - -/*! \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) - \relates <QtAlgorithms> - - Performs a binary search of the range [\a begin, \a end) and - returns the position of the first ocurrence of \a value. If no - such item is found, returns the position where it should be - inserted. - - The items in the range [\a begin, \e end) must be sorted in - ascending order; see qSort(). - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 18 - - This function requires the item type (in the example above, - \c{int}) to implement \c operator<(). - - qLowerBound() can be used in conjunction with qUpperBound() to - iterate over all occurrences of the same value: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 19 - - \sa qUpperBound(), qBinaryFind() -*/ - -/*! - \fn RandomAccessIterator qLowerBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) - \relates <QtAlgorithms> - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - Note that the items in the range must be sorted according to the order - specified by the \a lessThan object. -*/ - -/*! - \fn void qLowerBound(const Container &container, const T &value) - \relates <QtAlgorithms> - - \overload - - For read-only iteration over containers, this function is broadly equivalent to - qLowerBound(\a{container}.begin(), \a{container}.end(), value). However, since it - returns a const iterator, you cannot use it to modify the container; for example, - to insert items. -*/ - -/*! \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value) - \relates <QtAlgorithms> - - Performs a binary search of the range [\a begin, \a end) and - returns the position of the one-past-the-last occurrence of \a - value. If no such item is found, returns the position where the - item should be inserted. - - The items in the range [\a begin, \e end) must be sorted in - ascending order; see qSort(). - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 20 - - This function requires the item type (in the example above, - \c{int}) to implement \c operator<(). - - qUpperBound() can be used in conjunction with qLowerBound() to - iterate over all occurrences of the same value: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 21 - - \sa qLowerBound(), qBinaryFind() -*/ - -/*! - \fn RandomAccessIterator qUpperBound(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) - \relates <QtAlgorithms> - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - Note that the items in the range must be sorted according to the order - specified by the \a lessThan object. -*/ - -/*! - \fn void qUpperBound(const Container &container, const T &value) - \relates <QtAlgorithms> - - \overload - - This is the same as qUpperBound(\a{container}.begin(), \a{container}.end(), value); -*/ - - -/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value) - \relates <QtAlgorithms> - - Performs a binary search of the range [\a begin, \a end) and - returns the position of an occurrence of \a value. If there are - no occurrences of \a value, returns \a end. - - The items in the range [\a begin, \a end) must be sorted in - ascending order; see qSort(). - - If there are many occurrences of the same value, any one of them - could be returned. Use qLowerBound() or qUpperBound() if you need - finer control. - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 22 - - This function requires the item type (in the example above, - QString) to implement \c operator<(). - - See the \l{<QtAlgorithms>#binaryFind example}{detailed - description} for an example usage. - - \sa qLowerBound(), qUpperBound(), {random access iterators} -*/ - -/*! \fn RandomAccessIterator qBinaryFind(RandomAccessIterator begin, RandomAccessIterator end, const T &value, LessThan lessThan) - \relates <QtAlgorithms> - - \overload - - Uses the \a lessThan function instead of \c operator<() to - compare the items. - - Note that the items in the range must be sorted according to the order - specified by the \a lessThan object. -*/ - -/*! - \fn void qBinaryFind(const Container &container, const T &value) - \relates <QtAlgorithms> - - \overload - - This is the same as qBinaryFind(\a{container}.begin(), \a{container}.end(), value); -*/ - - -/*! - \fn void qDeleteAll(ForwardIterator begin, ForwardIterator end) - \relates <QtAlgorithms> - - Deletes all the items in the range [\a begin, \a end) using the - C++ \c delete operator. The item type must be a pointer type (for - example, \c{QWidget *}). - - Example: - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 23 - - Notice that qDeleteAll() doesn't remove the items from the - container; it merely calls \c delete on them. In the example - above, we call clear() on the container to remove the items. - - This function can also be used to delete items stored in - associative containers, such as QMap and QHash. Only the objects - stored in each container will be deleted by this function; objects - used as keys will not be deleted. - - \sa {forward iterators} -*/ - -/*! - \fn void qDeleteAll(const Container &c) - \relates <QtAlgorithms> - - \overload - - This is the same as qDeleteAll(\a{c}.begin(), \a{c}.end()). -*/ - -/*! \fn LessThan qLess() - \relates <QtAlgorithms> - - Returns a functional object, or functor, that can be passed to qSort() - or qStableSort(). - - Example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 24 - - \sa {qGreater()}{qGreater<T>()} -*/ - -/*! \fn LessThan qGreater() - \relates <QtAlgorithms> - - Returns a functional object, or functor, that can be passed to qSort() - or qStableSort(). - - Example: - - \snippet doc/src/snippets/code/doc_src_qalgorithms.qdoc 25 - - \sa {qLess()}{qLess<T>()} -*/ diff --git a/doc/src/classes/qcache.qdoc b/doc/src/classes/qcache.qdoc deleted file mode 100644 index b79eba8..0000000 --- a/doc/src/classes/qcache.qdoc +++ /dev/null @@ -1,244 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QCache - \brief The QCache class is a template class that provides a cache. - - \ingroup tools - \ingroup shared - \mainclass - \reentrant - - QCache\<Key, T\> defines a cache that stores objects of type T - associated with keys of type Key. For example, here's the - definition of a cache that stores objects of type Employee - associated with an integer key: - - \snippet doc/src/snippets/code/doc_src_qcache.qdoc 0 - - Here's how to insert an object in the cache: - - \snippet doc/src/snippets/code/doc_src_qcache.qdoc 1 - - The advantage of using QCache over some other key-based data - structure (such as QMap or QHash) is that QCache automatically - takes ownership of the objects that are inserted into the cache and - deletes them to make room for new objects, if necessary. When - inserting an object into the cache, you can specify a \e{cost}, - which should bear some approximate relationship to the amount of - memory taken by the object. When the sum of all objects' costs - (totalCost()) exceeds the cache's limit (maxCost()), QCache starts - deleting objects in the cache to keep under the limit, starting with - less recently accessed objects. - - By default, QCache's maxCost() is 100. You can specify a - different value in the QCache constructor: - - \snippet doc/src/snippets/code/doc_src_qcache.qdoc 2 - - Each time you call insert(), you can specify a cost as third - argument (after the key and a pointer to the object to insert). - After the call, the inserted object is owned by the QCache, which - may delete it at any time to make room for other objects. - - To look up objects in the cache, use object() or - operator[](). This function looks up an object by its key, and - returns either a pointer to the cached object (which is owned by - the cache) or 0. - - If you want to remove an object from the cache for a particular key, - call remove(). This will also delete the object. If you want to - remove an object from the cache without the QCache deleting it, use - take(). - - \sa QPixmapCache, QHash, QMap -*/ - -/*! \fn QCache::QCache(int maxCost = 100) - - Constructs a cache whose contents will never have a total cost - greater than \a maxCost. -*/ - -/*! \fn QCache::~QCache() - - Destroys the cache. Deletes all the objects in the cache. -*/ - -/*! \fn int QCache::maxCost() const - - Returns the maximum allowed total cost of the cache. - - \sa setMaxCost(), totalCost() -*/ - -/*! \fn void QCache::setMaxCost(int cost) - - Sets the maximum allowed total cost of the cache to \a cost. If - the current total cost is greater than \a cost, some objects are - deleted immediately. - - \sa maxCost(), totalCost() -*/ - -/*! \fn int QCache::totalCost() const - - Returns the total cost of the objects in the cache. - - This value is normally below maxCost(), but QCache makes an - exception for Qt's \l{implicitly shared} classes. If a cached - object shares its internal data with another instance, QCache may - keep the object lying around, possibly contributing to making - totalCost() larger than maxCost(). - - \sa setMaxCost() -*/ - -/*! \fn int QCache::size() const - - Returns the number of objects in the cache. - - \sa isEmpty() -*/ - -/*! \fn int QCache::count() const - - Same as size(). -*/ - -/*! \fn bool QCache::isEmpty() const - - Returns true if the cache contains no objects; otherwise - returns false. - - \sa size() -*/ - -/*! \fn QList<Key> QCache::keys() const - - Returns a list of the keys in the cache. -*/ - -/*! \fn void QCache::clear(); - - Deletes all the objects in the cache. - - \sa remove(), take() -*/ - - -/*! \fn bool QCache::insert(const Key &key, T *object, int cost = 1) - - Inserts \a object into the cache with key \a key and - associated cost \a cost. Any object with the same key already in - the cache will be removed. - - After this call, \a object is owned by the QCache and may be - deleted at any time. In particular, if \a cost is greater than - maxCost(), the object will be deleted immediately. - - The function returns true if the object was inserted into the - cache; otherwise it returns false. - - \sa take(), remove() -*/ - -/*! \fn T *QCache::object(const Key &key) const - - Returns the object associated with key \a key, or 0 if the key does - not exist in the cache. - - \warning The returned object is owned by QCache and may be - deleted at any time. - - \sa take(), remove() -*/ - -/*! \fn bool QCache::contains(const Key &key) const - - Returns true if the cache contains an object associated with key \a - key; otherwise returns false. - - \sa take(), remove() -*/ - -/*! \fn T *QCache::operator[](const Key &key) const - - Returns the object associated with key \a key, or 0 if the key does - not exist in the cache. - - This is the same as object(). - - \warning The returned object is owned by QCache and may be - deleted at any time. -*/ - -/*! \fn bool QCache::remove(const Key &key) - - Deletes the object associated with key \a key. Returns true if the - object was found in the cache; otherwise returns false. - - \sa take(), clear() -*/ - -/*! \fn T *QCache::take(const Key &key) - - Takes the object associated with key \a key out of the cache - without deleting it. Returns a pointer to the object taken out, or - 0 if the key does not exist in the cache. - - The ownership of the returned object is passed to the caller. - - \sa remove() -*/ - -/*! - \fn QCache::QCache(int maxCost, int dummy) - - Use QCache(int) instead. -*/ - -/*! - \fn T *QCache::find(const Key &key) const - - Use object() instead. -*/ diff --git a/doc/src/classes/qcolormap.qdoc b/doc/src/classes/qcolormap.qdoc deleted file mode 100644 index 5536137..0000000 --- a/doc/src/classes/qcolormap.qdoc +++ /dev/null @@ -1,152 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QColormap - \ingroup multimedia - - \brief The QColormap class maps device independent QColors to device - dependent pixel values. -*/ - -/*! \enum QColormap::Mode - - This enum describes how QColormap maps device independent RGB - values to device dependent pixel values. - - \value Direct Pixel values are derived directly from the RGB - values, also known as "True Color." - - \value Indexed Pixel values represent indexes into a vector of - available colors, i.e. QColormap uses the index of the color that - most closely matches an RGB value. - - \value Gray Similar to \c Indexed, pixel values represent a vector - of available gray tones. QColormap uses the index of the gray - tone that most closely matches the computed gray tone of an RGB - value. -*/ - -/*! - \fn QColormap QColormap::instance(int screen) - - Returns the colormap for the specified \a screen. If \a screen is - -1, this function returns the colormap for the default screen. -*/ - -/*! - \fn QColormap::QColormap(const QColormap &colormap) - - Constructs a copy of another \a colormap. -*/ - -/*! - \fn QColormap::~QColormap() - - Destroys the colormap. -*/ - -/*! - \fn int QColormap::size() const - - Returns the size of the colormap for \c Indexed and \c Gray modes; - Returns -1 for \c Direct mode. - - \sa colormap() -*/ - -/*! - \fn uint QColormap::pixel(const QColor &color) const - - Returns a device dependent pixel value for the \a color. - - \sa colorAt() -*/ - -/*! - \fn int QColormap::depth() const - - Returns the depth of the device. - - \sa size() -*/ - -/*! - \fn QColormap::Mode QColormap::mode() const - - Returns the mode of this colormap. - - \sa QColormap::Mode -*/ - -/*! - \fn const QColor QColormap::colorAt(uint pixel) const - - Returns a QColor for the \a pixel. - - \sa pixel() -*/ - -/*! - \fn const QVector<QColor> QColormap::colormap() const - - Returns a vector of colors which represents the devices colormap - for \c Indexed and \c Gray modes. This function returns an empty - vector for \c Direct mode. - - \sa size() -*/ - -/*! \fn HPALETTE QColormap::hPal() - - This function is only available on Windows. - - Returns an handle to the HPALETTE used by this colormap. If no - HPALETTE is being used, this function returns zero. -*/ - -/*! \since 4.2 - - \fn QColormap &QColormap::operator=(const QColormap &colormap) - - Assigns the given \a colormap to \e this color map and returns - a reference to \e this color map. -*/ diff --git a/doc/src/classes/qdesktopwidget.qdoc b/doc/src/classes/qdesktopwidget.qdoc deleted file mode 100644 index 4717e3a..0000000 --- a/doc/src/classes/qdesktopwidget.qdoc +++ /dev/null @@ -1,266 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QDesktopWidget - \brief The QDesktopWidget class provides access to screen information on multi-head systems. - - \ingroup advanced - \ingroup desktop - \ingroup environment - \mainclass - - QApplication::desktop() function should be used to get an instance - of the QDesktopWidget. - - Systems with more than one graphics card and monitor can manage the - physical screen space available either as multiple desktops, or as a - large virtual desktop, which usually has the size of the bounding - rectangle of all the screens (see virtualDesktop). For an - application, one of the available screens is the primary screen, i.e. - the screen where the main widget resides (see primaryScreen). All - windows opened in the context of the application should be - constrained to the boundaries of the primary screen; for example, - it would be inconvenient if a dialog box popped up on a different - screen, or split over two screens. - - The QDesktopWidget provides information about the geometry of the - available screens with screenGeometry(). The number of screens - available is returned by screenCount, and the screenCountChanged - signal is emitted when screens are added or removed during runtime. - The screen number that a particular point or widget is located in - is returned by screenNumber(). - - Widgets provided by Qt use this class, for example, to place - tooltips, menus and dialog boxes according to the parent or - application widget. Applications can use this class to save window - positions, or to place child widgets and dialogs on one particular - screen. - - \img qdesktopwidget.png Managing Multiple Screens - - In the illustration above, Application One's primary screen is - screen 0, and App Two's primary screen is screen 1. - - \target multiple screens note - \note QDesktopWidget inherits the QWidget properties, width() and - height(), which specify the size of the desktop. However, for - desktops with multiple screens, the size of the desktop is the union - of all the screen sizes, so width() and height() should \e not be - used for computing the size of a widget to be placed on one of the - screens. The correct width and height values are obtained using - availableGeometry() or screenGeometry() for a particular screen. - - \sa QApplication, QApplication::desktop(), QX11Info::appRootWindow() -*/ - -/*! - \fn QDesktopWidget::QDesktopWidget() - - \internal - - Creates the desktop widget. - - If the system supports a virtual desktop, this widget will have - the size of the virtual desktop; otherwise this widget will have - the size of the primary screen. - - Instead of using QDesktopWidget directly, use QApplication::desktop(). -*/ - -/*! - \fn QDesktopWidget::~QDesktopWidget() - - \internal - - Destroys the desktop widget and frees any allocated resources. -*/ - -/*! - \fn int QDesktopWidget::numScreens() const - - Returns the number of available screens. - - \obsolete - - This function is deprecated. Use screenCount instead. - - \sa primaryScreen -*/ - -/*! - \fn QWidget *QDesktopWidget::screen(int screen) - - Returns a widget that represents the screen with index \a screen - (a value of -1 means the default screen). - - If the system uses a virtual desktop, the returned widget will - have the geometry of the entire virtual desktop; i.e., bounding - every \a screen. - - \sa primaryScreen, screenCount, virtualDesktop -*/ - -/*! - \fn const QRect QDesktopWidget::availableGeometry(int screen) const - - Returns the available geometry of the screen with index \a screen. What - is available will be subrect of screenGeometry() based on what the - platform decides is available (for example excludes the dock and menu bar - on Mac OS X, or the task bar on Windows). The default screen is used if - \a screen is -1. - - \sa screenNumber(), screenGeometry() -*/ - -/*! - \fn const QRect QDesktopWidget::availableGeometry(const QWidget *widget) const - \overload - - Returns the available geometry of the screen which contains \a widget. - - \sa screenGeometry() -*/ - -/*! - \fn const QRect QDesktopWidget::availableGeometry(const QPoint &p) const - \overload - - Returns the available geometry of the screen which contains \a p. - - \sa screenGeometry() -*/ - - -/*! - \fn const QRect QDesktopWidget::screenGeometry(int screen) const - - Returns the geometry of the screen with index \a screen. The default - screen is used if \a screen is -1. - - \sa screenNumber() -*/ - -/*! - \fn const QRect QDesktopWidget::screenGeometry(const QWidget *widget) const - \overload - - Returns the geometry of the screen which contains \a widget. -*/ - -/*! - \fn const QRect QDesktopWidget::screenGeometry(const QPoint &p) const - \overload - - Returns the geometry of the screen which contains \a p. -*/ - - -/*! - \fn int QDesktopWidget::screenNumber(const QWidget *widget) const - - Returns the index of the screen that contains the largest - part of \a widget, or -1 if the widget not on a screen. - - \sa primaryScreen -*/ - -/*! - \fn int QDesktopWidget::screenNumber(const QPoint &point) const - - \overload - Returns the index of the screen that contains the \a point, or the - screen which is the shortest distance from the \a point. - - \sa primaryScreen -*/ - -/*! - \fn void QDesktopWidget::resizeEvent(QResizeEvent *event) - \reimp -*/ - -/*! - \fn void QDesktopWidget::resized(int screen) - - This signal is emitted when the size of \a screen changes. -*/ - -/*! - \fn void QDesktopWidget::workAreaResized(int screen) - - This signal is emitted when the work area available on \a screen changes. -*/ - -/*! - \property QDesktopWidget::screenCount - \brief the number of screens currently available on the system. - - \since 4.6 - - \sa screenCountChanged() -*/ - -/*! - \property QDesktopWidget::primaryScreen - \brief the index of the screen that is configured to be the primary screen - on the system. -*/ - -/*! - \property QDesktopWidget::virtualDesktop - - \brief if the system manages the available screens in a virtual desktop. - - For virtual desktops, screen() will always return the same widget. - The size of the virtual desktop is the size of this desktop - widget. -*/ - -/*! - \fn void QDesktopWidget::screenCountChanged(int newCount) - - \since 4.6 - - This signal is emitted when the number of screens changes to \a newCount. - - \sa screenCount -*/ diff --git a/doc/src/classes/qiterator.qdoc b/doc/src/classes/qiterator.qdoc deleted file mode 100644 index c767be3..0000000 --- a/doc/src/classes/qiterator.qdoc +++ /dev/null @@ -1,1431 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QListIterator - \inmodule QtCore - - \brief The QListIterator class provides a Java-style const iterator for QList and QQueue. - - QList has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - An alternative to using iterators is to use index positions. Most - QList member functions take an index as their first parameter, - making it possible to access, modify, and remove items without - using iterators. - - QListIterator\<T\> allows you to iterate over a QList\<T\> (or a - QQueue\<T\>). If you want to modify the list as you iterate over - it, use QMutableListIterator\<T\> instead. - - The QListIterator constructor takes a QList as argument. After - construction, the iterator is located at the very beginning of - the list (before the first item). Here's how to iterate over all - the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 0 - - The next() function returns the next item in the list and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, and returns the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 1 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - Multiple iterators can be used on the same list. If the list is - modified while a QListIterator is active, the QListIterator will - continue iterating over the original list, ignoring the modified - copy. - - \sa QMutableListIterator, QList::const_iterator -*/ - -/*! - \class QLinkedListIterator - \inmodule QtCore - - \brief The QLinkedListIterator class provides a Java-style const iterator for QLinkedList. - - QLinkedList has both \l{Java-style iterators} and - \l{STL-style iterators}. The Java-style iterators are more - high-level and easier to use than the STL-style iterators; on the - other hand, they are slightly less efficient. - - QLinkedListIterator\<T\> allows you to iterate over a - QLinkedList\<T\>. If you want to modify the list as you iterate - over it, use QMutableLinkedListIterator\<T\> instead. - - The QLinkedListIterator constructor takes a QLinkedList as - argument. After construction, the iterator is located at the very - beginning of the list (before the first item). Here's how to - iterate over all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 2 - - The next() function returns the next item in the list and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, and returns the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 3 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - Multiple iterators can be used on the same list. If the list is - modified while a QLinkedListIterator is active, the - QLinkedListIterator will continue iterating over the original - list, ignoring the modified copy. - - \sa QMutableLinkedListIterator, QLinkedList::const_iterator -*/ - -/*! - \class QVectorIterator - \inmodule QtCore - \brief The QVectorIterator class provides a Java-style const iterator for QVector and QStack. - - QVector has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - An alternative to using iterators is to use index positions. Most - QVector member functions take an index as their first parameter, - making it possible to access, insert, and remove items without - using iterators. - - QVectorIterator\<T\> allows you to iterate over a QVector\<T\> - (or a QStack\<T\>). If you want to modify the vector as you - iterate over it, use QMutableVectorIterator\<T\> instead. - - The QVectorIterator constructor takes a QVector as argument. - After construction, the iterator is located at the very beginning - of the vector (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 4 - - The next() function returns the next item in the vector and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 5 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - Multiple iterators can be used on the same vector. If the vector - is modified while a QVectorIterator is active, the QVectorIterator - will continue iterating over the original vector, ignoring the - modified copy. - - \sa QMutableVectorIterator, QVector::const_iterator -*/ - -/*! - \class QSetIterator - \inmodule QtCore - \brief The QSetIterator class provides a Java-style const iterator for QSet. - - QSet supports both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QSetIterator\<T\> allows you to iterate over a QSet\<T\>. If you - want to modify the set as you iterate over it, use - QMutableSetIterator\<T\> instead. - - The constructor takes a QSet as argument. After construction, the - iterator is located at the very beginning of the set (before - the first item). Here's how to iterate over all the elements - sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 6 - - The next() function returns the next item in the set and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 7 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - Multiple iterators can be used on the same set. If the set - is modified while a QSetIterator is active, the QSetIterator - will continue iterating over the original set, ignoring the - modified copy. - - \sa QMutableSetIterator, QSet::const_iterator -*/ - -/*! - \class QMutableListIterator - \inmodule QtCore - - \brief The QMutableListIterator class provides a Java-style non-const iterator for QList and QQueue. - - QList has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - An alternative to using iterators is to use index positions. Most - QList member functions take an index as their first parameter, - making it possible to access, insert, and remove items without - using iterators. - - QMutableListIterator\<T\> allows you to iterate over a QList\<T\> - (or a QQueue\<T\>) and modify the list. If you don't want to - modify the list (or have a const QList), use the slightly faster - QListIterator\<T\> instead. - - The QMutableListIterator constructor takes a QList as argument. - After construction, the iterator is located at the very beginning - of the list (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 8 - - The next() function returns the next item in the list and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 9 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - If you want to remove items as you iterate over the list, use - remove(). If you want to modify the value of an item, use - setValue(). If you want to insert a new item in the list, use - insert(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 10 - - The example traverses a list, replacing negative numbers with - their absolute values, and eliminating zeroes. - - Only one mutable iterator can be active on a given list at any - time. Furthermore, no changes should be done directly to the list - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QListIterator, QList::iterator -*/ - -/*! - \class QMutableLinkedListIterator - \inmodule QtCore - - \brief The QMutableLinkedListIterator class provides a Java-style non-const iterator for QLinkedList. - - QLinkedList has both \l{Java-style iterators} and - \l{STL-style iterators}. The Java-style iterators are more - high-level and easier to use than the STL-style iterators; on the - other hand, they are slightly less efficient. - - QMutableLinkedListIterator\<T\> allows you to iterate over a - QLinkedList\<T\> and modify the list. If you don't want to modify - the list (or have a const QLinkedList), use the slightly faster - QLinkedListIterator\<T\> instead. - - The QMutableLinkedListIterator constructor takes a QLinkedList as - argument. After construction, the iterator is located at the very - beginning of the list (before the first item). Here's how to - iterate over all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 11 - - The next() function returns the next item in the list and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 12 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - If you want to remove items as you iterate over the list, use - remove(). If you want to modify the value of an item, use - setValue(). If you want to insert a new item in the list, use - insert(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 13 - - The example traverses a list, replacing negative numbers with - their absolute values, and eliminating zeroes. - - Only one mutable iterator can be active on a given list at any - time. Furthermore, no changes should be done directly to the list - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QLinkedListIterator, QLinkedList::iterator -*/ - -/*! - \class QMutableVectorIterator - \inmodule QtCore - - \brief The QMutableVectorIterator class provides a Java-style non-const iterator for QVector and QStack. - - QVector has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - An alternative to using iterators is to use index positions. Most - QVector member functions take an index as their first parameter, - making it possible to access, insert, and remove items without - using iterators. - - QMutableVectorIterator\<T\> allows you to iterate over a - QVector\<T\> and modify the vector. If you don't want to modify - the vector (or have a const QVector), use the slightly faster - QVectorIterator\<T\> instead. - - The QMutableVectorIterator constructor takes a QVector as - argument. After construction, the iterator is located at the very - beginning of the list (before the first item). Here's how to - iterate over all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 14 - - The next() function returns the next item in the vector and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 15 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. - - If you want to remove items as you iterate over the vector, use - remove(). If you want to modify the value of an item, use - setValue(). If you want to insert a new item in the vector, use - insert(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 16 - - The example traverses a vector, replacing negative numbers with - their absolute values, and eliminating zeroes. - - Only one mutable iterator can be active on a given vector at any - time. Furthermore, no changes should be done directly to the - vector while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QVectorIterator, QVector::iterator -*/ - -/*! - \class QMutableSetIterator - \inmodule QtCore - \since 4.2 - - \brief The QMutableSetIterator class provides a Java-style non-const iterator for QSet. - - QSet has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QMutableSetIterator\<T\> allows you to iterate over a QSet\<T\> - and remove items from the set as you iterate. If you don't want - to modify the set (or have a const QSet), use the slightly faster - QSetIterator\<T\> instead. - - The QMutableSetIterator constructor takes a QSet as argument. - After construction, the iterator is located at the very beginning - of the set (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 17 - - The next() function returns the next item in the set and - advances the iterator. Unlike STL-style iterators, Java-style - iterators point \e between items rather than directly \e at - items. The first call to next() advances the iterator to the - position between the first and second item, and returns the first - item; the second call to next() advances the iterator to the - position between the second and third item, returning the second - item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 18 - - If you want to remove items as you iterate over the set, use - remove(). - - Only one mutable iterator can be active on a given set at any - time. Furthermore, no changes should be done directly to the set - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QSetIterator, QSet::iterator -*/ - -/*! - \fn QListIterator::QListIterator(const QList<T> &list) - \fn QLinkedListIterator::QLinkedListIterator(const QLinkedList<T> &list) - \fn QMutableListIterator::QMutableListIterator(QList<T> &list) - \fn QMutableLinkedListIterator::QMutableLinkedListIterator(QLinkedList<T> &list) - - Constructs an iterator for traversing \a list. The iterator is - set to be at the front of the list (before the first item). - - \sa operator=() -*/ - -/*! - \fn QVectorIterator::QVectorIterator(const QVector<T> &vector) - \fn QMutableVectorIterator::QMutableVectorIterator(QVector<T> &vector) - - Constructs an iterator for traversing \a vector. The iterator is - set to be at the front of the vector (before the first item). - - \sa operator=() -*/ - -/*! - \fn QSetIterator::QSetIterator(const QSet<T> &set) - \fn QMutableSetIterator::QMutableSetIterator(QSet<T> &set) - - Constructs an iterator for traversing \a set. The iterator is - set to be at the front of the set (before the first item). - - \sa operator=() -*/ - -/*! - \fn QMutableListIterator::~QMutableListIterator() - \fn QMutableLinkedListIterator::~QMutableLinkedListIterator() - \fn QMutableVectorIterator::~QMutableVectorIterator() - \fn QMutableSetIterator::~QMutableSetIterator() - - Destroys the iterator. - - \sa operator=() -*/ - -/*! \fn QMutableListIterator &QMutableListIterator::operator=(QList<T> &list) - \fn QMutableLinkedListIterator &QMutableLinkedListIterator::operator=(QLinkedList<T> &list) - \fn QListIterator &QListIterator::operator=(const QList<T> &list) - \fn QLinkedListIterator &QLinkedListIterator::operator=(const QLinkedList<T> &list) - - Makes the iterator operate on \a list. The iterator is set to be - at the front of the list (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn QVectorIterator &QVectorIterator::operator=(const QVector<T> &vector) - \fn QMutableVectorIterator &QMutableVectorIterator::operator=(QVector<T> &vector) - - Makes the iterator operate on \a vector. The iterator is set to be - at the front of the vector (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn QSetIterator &QSetIterator::operator=(const QSet<T> &set) - \fn QMutableSetIterator &QMutableSetIterator::operator=(QSet<T> &set) - - Makes the iterator operate on \a set. The iterator is set to be - at the front of the set (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn void QListIterator::toFront() - \fn void QLinkedListIterator::toFront() - \fn void QVectorIterator::toFront() - \fn void QSetIterator::toFront() - \fn void QMutableListIterator::toFront() - \fn void QMutableLinkedListIterator::toFront() - \fn void QMutableVectorIterator::toFront() - \fn void QMutableSetIterator::toFront() - - Moves the iterator to the front of the container (before the - first item). - - \sa toBack(), next() -*/ - -/*! \fn void QListIterator::toBack() - \fn void QLinkedListIterator::toBack() - \fn void QVectorIterator::toBack() - \fn void QSetIterator::toBack() - \fn void QMutableListIterator::toBack() - \fn void QMutableLinkedListIterator::toBack() - \fn void QMutableVectorIterator::toBack() - \fn void QMutableSetIterator::toBack() - - Moves the iterator to the back of the container (after the last - item). - - \sa toFront(), previous() -*/ - -/*! \fn bool QListIterator::hasNext() const - \fn bool QLinkedListIterator::hasNext() const - \fn bool QVectorIterator::hasNext() const - \fn bool QSetIterator::hasNext() const - \fn bool QMutableListIterator::hasNext() const - \fn bool QMutableLinkedListIterator::hasNext() const - \fn bool QMutableVectorIterator::hasNext() const - \fn bool QMutableSetIterator::hasNext() const - - Returns true if there is at least one item ahead of the iterator, - i.e. the iterator is \e not at the back of the container; - otherwise returns false. - - \sa hasPrevious(), next() -*/ - -/*! \fn const T &QListIterator::next() - \fn const T &QLinkedListIterator::next() - \fn const T &QVectorIterator::next() - \fn const T &QSetIterator::next() - \fn const T &QMutableSetIterator::next() - - Returns the next item and advances the iterator by one position. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), peekNext(), previous() -*/ - -/*! \fn T &QMutableListIterator::next() - \fn T &QMutableLinkedListIterator::next() - \fn T &QMutableVectorIterator::next() - - Returns a reference to the next item, and advances the iterator - by one position. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), peekNext(), previous() -*/ - -/*! \fn const T &QListIterator::peekNext() const - \fn const T &QLinkedListIterator::peekNext() const - \fn const T &QVectorIterator::peekNext() const - \fn const T &QSetIterator::peekNext() const - \fn const T &QMutableSetIterator::peekNext() const - - Returns the next item without moving the iterator. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), next(), peekPrevious() -*/ - -/*! \fn T &QMutableListIterator::peekNext() const - \fn T &QMutableLinkedListIterator::peekNext() const - \fn T &QMutableVectorIterator::peekNext() const - - Returns a reference to the next item, without moving the iterator. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), next(), peekPrevious() -*/ - -/*! \fn bool QListIterator::hasPrevious() const - \fn bool QLinkedListIterator::hasPrevious() const - \fn bool QVectorIterator::hasPrevious() const - \fn bool QSetIterator::hasPrevious() const - \fn bool QMutableListIterator::hasPrevious() const - \fn bool QMutableLinkedListIterator::hasPrevious() const - \fn bool QMutableVectorIterator::hasPrevious() const - \fn bool QMutableSetIterator::hasPrevious() const - - Returns true if there is at least one item behind the iterator, - i.e. the iterator is \e not at the front of the container; - otherwise returns false. - - \sa hasNext(), previous() -*/ - -/*! \fn const T &QListIterator::previous() - \fn const T &QLinkedListIterator::previous() - \fn const T &QVectorIterator::previous() - \fn const T &QSetIterator::previous() - \fn const T &QMutableSetIterator::previous() - - Returns the previous item and moves the iterator back by one - position. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! \fn T &QMutableListIterator::previous() - \fn T &QMutableLinkedListIterator::previous() - \fn T &QMutableVectorIterator::previous() - - Returns a reference to the previous item and moves the iterator - back by one position. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! \fn const T &QListIterator::peekPrevious() const - \fn const T &QLinkedListIterator::peekPrevious() const - \fn const T &QVectorIterator::peekPrevious() const - \fn const T &QSetIterator::peekPrevious() const - \fn const T &QMutableSetIterator::peekPrevious() const - - Returns the previous item without moving the iterator. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! \fn T &QMutableListIterator::peekPrevious() const - \fn T &QMutableLinkedListIterator::peekPrevious() const - \fn T &QMutableVectorIterator::peekPrevious() const - - Returns a reference to the previous item, without moving the iterator. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! \fn bool QListIterator::findNext(const T &value) - \fn bool QLinkedListIterator::findNext(const T &value) - \fn bool QVectorIterator::findNext(const T &value) - \fn bool QSetIterator::findNext(const T &value) - \fn bool QMutableListIterator::findNext(const T &value) - \fn bool QMutableLinkedListIterator::findNext(const T &value) - \fn bool QMutableVectorIterator::findNext(const T &value) - \fn bool QMutableSetIterator::findNext(const T &value) - - Searches for \a value starting from the current iterator position - forward. Returns true if \a value is found; otherwise returns false. - - After the call, if \a value was found, the iterator is positioned - just after the matching item; otherwise, the iterator is - positioned at the back of the container. - - \sa findPrevious() -*/ - -/*! \fn bool QListIterator::findPrevious(const T &value) - \fn bool QLinkedListIterator::findPrevious(const T &value) - \fn bool QVectorIterator::findPrevious(const T &value) - \fn bool QSetIterator::findPrevious(const T &value) - \fn bool QMutableListIterator::findPrevious(const T &value) - \fn bool QMutableLinkedListIterator::findPrevious(const T &value) - \fn bool QMutableVectorIterator::findPrevious(const T &value) - \fn bool QMutableSetIterator::findPrevious(const T &value) - - Searches for \a value starting from the current iterator position - backward. Returns true if \a value is found; otherwise returns - false. - - After the call, if \a value was found, the iterator is positioned - just before the matching item; otherwise, the iterator is - positioned at the front of the container. - - \sa findNext() -*/ - -/*! \fn void QMutableListIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 19 - - \sa insert(), setValue() -*/ - -/*! \fn void QMutableLinkedListIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 20 - - \sa insert(), setValue() -*/ - -/*! \fn void QMutableVectorIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 21 - - \sa insert(), setValue() -*/ - -/*! \fn void QMutableSetIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 22 - - \sa value() -*/ - -/*! \fn void QMutableListIterator::setValue(const T &value) const - - Replaces the value of the last item that was jumped over using - one of the traversal functions with \a value. - - The traversal functions are next(), previous(), findNext(), and - findPrevious(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 23 - - \sa value(), remove(), insert() -*/ - -/*! \fn void QMutableLinkedListIterator::setValue(const T &value) const - - Replaces the value of the last item that was jumped over using - one of the traversal functions with \a value. - - The traversal functions are next(), previous(), findNext(), and - findPrevious(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 24 - - \sa value(), remove(), insert() -*/ - -/*! \fn void QMutableVectorIterator::setValue(const T &value) const - - Replaces the value of the last item that was jumped over using - one of the traversal functions with \a value. - - The traversal functions are next(), previous(), findNext(), and - findPrevious(). - - Example: - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 25 - - \sa value(), remove(), insert() -*/ - -/*! \fn const T &QMutableListIterator::value() const - \fn const T &QMutableLinkedListIterator::value() const - \fn const T &QMutableVectorIterator::value() const - \fn const T &QMutableSetIterator::value() const - - Returns the value of the last item that was jumped over using one - of the traversal functions (next(), previous(), findNext(), - findPrevious()). - - After a call to next() or findNext(), value() is equivalent to - peekPrevious(). After a call to previous() or findPrevious(), value() is - equivalent to peekNext(). -*/ - -/*! - \fn T &QMutableListIterator::value() - \fn T &QMutableLinkedListIterator::value() - \fn T &QMutableVectorIterator::value() - \overload - - Returns a non-const reference to the value of the last item that - was jumped over using one of the traversal functions. -*/ - -/*! \fn void QMutableListIterator::insert(const T &value) - \fn void QMutableLinkedListIterator::insert(const T &value) - \fn void QMutableVectorIterator::insert(const T &value) - - Inserts \a value at the current iterator position. After the - call, the iterator is located just after the inserted item. - - \sa remove(), setValue() -*/ - -/*! - \class QMapIterator - \inmodule QtCore - - \brief The QMapIterator class provides a Java-style const iterator for QMap and QMultiMap. - - QMap has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QMapIterator\<Key, T\> allows you to iterate over a QMap (or a - QMultiMap). If you want to modify the map as you iterate over - it, use QMutableMapIterator instead. - - The QMapIterator constructor takes a QMap as argument. After - construction, the iterator is located at the very beginning of - the map (before the first item). Here's how to iterate over all - the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 26 - - The next() function returns the next item in the map and - advances the iterator. The key() and value() functions return the - key and value of the last item that was jumped over. - - Unlike STL-style iterators, Java-style iterators point \e between - items rather than directly \e at items. The first call to next() - advances the iterator to the position between the first and - second item, and returns the first item; the second call to - next() advances the iterator to the position between the second - and third item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 27 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 28 - - Multiple iterators can be used on the same map. If the map is - modified while a QMapIterator is active, the QMapIterator will - continue iterating over the original map, ignoring the modified - copy. - - \sa QMutableMapIterator, QMap::const_iterator -*/ - -/*! - \class QHashIterator - \inmodule QtCore - - \brief The QHashIterator class provides a Java-style const iterator for QHash and QMultiHash. - - QHash has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QHashIterator\<Key, T\> allows you to iterate over a QHash (or a - QMultiHash). If you want to modify the hash as you iterate over - it, use QMutableHashIterator instead. - - The QHashIterator constructor takes a QHash as argument. After - construction, the iterator is located at the very beginning of - the hash (before the first item). Here's how to iterate over all - the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 29 - - The next() function returns the next item in the hash and - advances the iterator. The key() and value() functions return the - key and value of the last item that was jumped over. - - Unlike STL-style iterators, Java-style iterators point \e between - items rather than directly \e at items. The first call to next() - advances the iterator to the position between the first and - second item, and returns the first item; the second call to - next() advances the iterator to the position between the second - and third item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 30 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 31 - - Multiple iterators can be used on the same hash. If the hash is - modified while a QHashIterator is active, the QHashIterator will - continue iterating over the original hash, ignoring the modified - copy. - - \sa QMutableHashIterator, QHash::const_iterator -*/ - -/*! - \class QMutableMapIterator - \inmodule QtCore - - \brief The QMutableMapIterator class provides a Java-style non-const iterator for QMap and QMultiMap. - - QMap has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QMutableMapIterator\<Key, T\> allows you to iterate over a QMap - (or a QMultiMap) and modify the map. If you don't want to modify - the map (or have a const QMap), use the slightly faster - QMapIterator instead. - - The QMutableMapIterator constructor takes a QMap as argument. - After construction, the iterator is located at the very beginning - of the map (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 32 - - The next() function returns the next item in the map and - advances the iterator. The key() and value() functions return the - key and value of the last item that was jumped over. - - Unlike STL-style iterators, Java-style iterators point \e between - items rather than directly \e at items. The first call to next() - advances the iterator to the position between the first and - second item, and returns the first item; the second call to - next() advances the iterator to the position between the second - and third item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 33 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 34 - - If you want to remove items as you iterate over the map, use - remove(). If you want to modify the value of an item, use - setValue(). - - Example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 35 - - The example removes all (key, value) pairs where the key and the - value are the same. - - Only one mutable iterator can be active on a given map at any - time. Furthermore, no changes should be done directly to the map - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QMapIterator, QMap::iterator -*/ - -/*! - \class QMutableHashIterator - \inmodule QtCore - - \brief The QMutableHashIterator class provides a Java-style non-const iterator for QHash and QMultiHash. - - QHash has both \l{Java-style iterators} and \l{STL-style - iterators}. The Java-style iterators are more high-level and - easier to use than the STL-style iterators; on the other hand, - they are slightly less efficient. - - QMutableHashIterator\<Key, T\> allows you to iterate over a QHash - (or a QMultiHash) and modify the hash. If you don't want to modify - the hash (or have a const QHash), use the slightly faster - QHashIterator instead. - - The QMutableHashIterator constructor takes a QHash as argument. - After construction, the iterator is located at the very beginning - of the hash (before the first item). Here's how to iterate over - all the elements sequentially: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 36 - - The next() function returns the next item in the hash and - advances the iterator. The key() and value() functions return the - key and value of the last item that was jumped over. - - Unlike STL-style iterators, Java-style iterators point \e between - items rather than directly \e at items. The first call to next() - advances the iterator to the position between the first and - second item, and returns the first item; the second call to - next() advances the iterator to the position between the second - and third item; and so on. - - \img javaiterators1.png - - Here's how to iterate over the elements in reverse order: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 37 - - If you want to find all occurrences of a particular value, use - findNext() or findPrevious() in a loop. For example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 38 - - If you want to remove items as you iterate over the hash, use - remove(). If you want to modify the value of an item, use - setValue(). - - Example: - - \snippet doc/src/snippets/code/doc_src_qiterator.qdoc 39 - - The example removes all (key, value) pairs where the key and the - value are the same. - - Only one mutable iterator can be active on a given hash at any - time. Furthermore, no changes should be done directly to the hash - while the iterator is active (as opposed to through the - iterator), since this could invalidate the iterator and lead to - undefined behavior. - - \sa QHashIterator, QHash::iterator -*/ - -/*! \fn QMapIterator::QMapIterator(const QMap<Key, T> &map) - \fn QMutableMapIterator::QMutableMapIterator(QMap<Key, T> &map) - - Constructs an iterator for traversing \a map. The iterator is set - to be at the front of the map (before the first item). - - \sa operator=() -*/ - -/*! \fn QHashIterator::QHashIterator(const QHash<Key, T> &hash) - \fn QMutableHashIterator::QMutableHashIterator(QHash<Key, T> &hash) - - Constructs an iterator for traversing \a hash. The iterator is - set to be at the front of the hash (before the first item). - - \sa operator=() -*/ - -/*! - \fn QMutableMapIterator::~QMutableMapIterator() - \fn QMutableHashIterator::~QMutableHashIterator() - - Destroys the iterator. - - \sa operator=() -*/ - -/*! \fn QMapIterator &QMapIterator::operator=(const QMap<Key, T> &map) - \fn QMutableMapIterator &QMutableMapIterator::operator=(QMap<Key, T> &map) - - Makes the iterator operate on \a map. The iterator is set to be - at the front of the map (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn QHashIterator &QHashIterator::operator=(const QHash<Key, T> &hash) - \fn QMutableHashIterator &QMutableHashIterator::operator=(QHash<Key, T> &hash) - - Makes the iterator operate on \a hash. The iterator is set to be - at the front of the hash (before the first item). - - \sa toFront(), toBack() -*/ - -/*! \fn void QMapIterator::toFront() - \fn void QHashIterator::toFront() - \fn void QMutableMapIterator::toFront() - \fn void QMutableHashIterator::toFront() - - Moves the iterator to the front of the container (before the - first item). - - \sa toBack(), next() -*/ - -/*! \fn void QMapIterator::toBack() - \fn void QHashIterator::toBack() - \fn void QMutableMapIterator::toBack() - \fn void QMutableHashIterator::toBack() - - Moves the iterator to the back of the container (after the last - item). - - \sa toFront(), previous() -*/ - -/*! \fn bool QMapIterator::hasNext() const - \fn bool QHashIterator::hasNext() const - \fn bool QMutableMapIterator::hasNext() const - \fn bool QMutableHashIterator::hasNext() const - - Returns true if there is at least one item ahead of the iterator, - i.e. the iterator is \e not at the back of the container; - otherwise returns false. - - \sa hasPrevious(), next() -*/ - -/*! \fn QMapIterator::Item QMapIterator::next() - \fn QHashIterator::Item QHashIterator::next() - - Returns the next item and advances the iterator by one position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), peekNext(), previous() -*/ - -/*! \fn QMutableMapIterator::Item QMutableMapIterator::next() - \fn QMutableHashIterator::Item QMutableHashIterator::next() - - Returns the next item and advances the iterator by one position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), peekNext(), previous() -*/ - -/*! \fn QMapIterator::Item QMapIterator::peekNext() const - \fn QHashIterator::Item QHashIterator::peekNext() const - - Returns the next item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), next(), peekPrevious() -*/ - -/*! \fn QMutableMapIterator::Item QMutableMapIterator::peekNext() const - \fn QMutableHashIterator::Item QMutableHashIterator::peekNext() const - - Returns a reference to the next item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the back of the - container leads to undefined results. - - \sa hasNext(), next(), peekPrevious() -*/ - -/*! \fn bool QMapIterator::hasPrevious() const - \fn bool QHashIterator::hasPrevious() const - \fn bool QMutableMapIterator::hasPrevious() const - \fn bool QMutableHashIterator::hasPrevious() const - - Returns true if there is at least one item behind the iterator, - i.e. the iterator is \e not at the front of the container; - otherwise returns false. - - \sa hasNext(), previous() -*/ - -/*! \fn QMapIterator::Item QMapIterator::previous() - \fn QHashIterator::Item QHashIterator::previous() - - Returns the previous item and moves the iterator back by one - position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! \fn QMutableMapIterator::Item QMutableMapIterator::previous() - \fn QMutableHashIterator::Item QMutableHashIterator::previous() - - Returns the previous item and moves the iterator back by one - position. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), peekPrevious(), next() -*/ - -/*! \fn QMapIterator::Item QMapIterator::peekPrevious() const - \fn QHashIterator::Item QHashIterator::peekPrevious() const - - Returns the previous item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! \fn QMutableMapIterator::Item QMutableMapIterator::peekPrevious() const - \fn QMutableHashIterator::Item QMutableHashIterator::peekPrevious() const - - Returns the previous item without moving the iterator. - - Call key() on the return value to obtain the item's key, and - value() to obtain the value. - - Calling this function on an iterator located at the front of the - container leads to undefined results. - - \sa hasPrevious(), previous(), peekNext() -*/ - -/*! \fn const T &QMapIterator::value() const - \fn const T &QHashIterator::value() const - - Returns the value of the last item that was jumped over using one - of the traversal functions (next(), previous(), findNext(), - findPrevious()). - - After a call to next() or findNext(), value() is - equivalent to peekPrevious().value(). After a call to previous() - or findPrevious(), value() is equivalent to peekNext().value(). - - \sa key() -*/ - -/*! - \fn const T &QMutableMapIterator::value() const - \fn const T &QMutableHashIterator::value() const - - Returns the value of the last item that was jumped over using one - of the traversal functions (next(), previous(), findNext(), - findPrevious()). - - After a call to next() or findNext(), value() is - equivalent to peekPrevious().value(). After a call to previous() - or findPrevious(), value() is equivalent to peekNext().value(). - - \sa key(), setValue() -*/ - -/*! - \fn T &QMutableMapIterator::value() - \fn T &QMutableHashIterator::value() - \overload - - Returns a non-const reference to the value of - the last item that was jumped over using one - of the traversal functions. -*/ - -/*! \fn const Key &QMapIterator::key() const - \fn const Key &QHashIterator::key() const - \fn const Key &QMutableMapIterator::key() const - \fn const Key &QMutableHashIterator::key() const - - Returns the key of the last item that was jumped over using one - of the traversal functions (next(), previous(), findNext(), - findPrevious()). - - After a call to next() or findNext(), key() is - equivalent to peekPrevious().key(). After a call to previous() or - findPrevious(), key() is equivalent to peekNext().key(). - - \sa value() -*/ - -/*! \fn bool QMapIterator::findNext(const T &value) - \fn bool QHashIterator::findNext(const T &value) - \fn bool QMutableMapIterator::findNext(const T &value) - \fn bool QMutableHashIterator::findNext(const T &value) - - Searches for \a value starting from the current iterator position - forward. Returns true if a (key, value) pair with value \a value - is found; otherwise returns false. - - After the call, if \a value was found, the iterator is positioned - just after the matching item; otherwise, the iterator is - positioned at the back of the container. - - \sa findPrevious() -*/ - -/*! \fn bool QMapIterator::findPrevious(const T &value) - \fn bool QHashIterator::findPrevious(const T &value) - \fn bool QMutableMapIterator::findPrevious(const T &value) - \fn bool QMutableHashIterator::findPrevious(const T &value) - - Searches for \a value starting from the current iterator position - backward. Returns true if a (key, value) pair with value \a value - is found; otherwise returns false. - - After the call, if \a value was found, the iterator is positioned - just before the matching item; otherwise, the iterator is - positioned at the front of the container. - - \sa findNext() -*/ - -/*! \fn void QMutableMapIterator::remove() - \fn void QMutableHashIterator::remove() - - Removes the last item that was jumped over using one of the - traversal functions (next(), previous(), findNext(), findPrevious()). - - \sa setValue() -*/ - -/*! \fn void QMutableMapIterator::setValue(const T &value) - \fn void QMutableHashIterator::setValue(const T &value) - - Replaces the value of the last item that was jumped over using - one of the traversal functions with \a value. - - The traversal functions are next(), previous(), findNext(), and - findPrevious(). - - \sa key(), value(), remove() -*/ diff --git a/doc/src/classes/qmacstyle.qdoc b/doc/src/classes/qmacstyle.qdoc deleted file mode 100644 index 171ddb0..0000000 --- a/doc/src/classes/qmacstyle.qdoc +++ /dev/null @@ -1,261 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - - -/*! - \class QMacStyle - \brief The QMacStyle class provides a Mac OS X style using the Apple Appearance Manager. - - \ingroup appearance - - This class is implemented as a wrapper to the HITheme - APIs, allowing applications to be styled according to the current - theme in use on Mac OS X. This is done by having primitives - in QStyle implemented in terms of what Mac OS X would normally theme. - - \warning This style is only available on Mac OS X because it relies on the - HITheme APIs. - - There are additional issues that should be taken - into consideration to make an application compatible with the - \link http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html - Apple Human Interface Guidelines \endlink. Some of these issues are outlined - below. - - \list - - \i Layout - The restrictions on window layout are such that some - aspects of layout that are style-dependent cannot be achieved - using QLayout. Changes are being considered (and feedback would be - appreciated) to make layouts QStyle-able. Some of the restrictions - involve horizontal and vertical widget alignment and widget size - (covered below). - - \i Widget size - Mac OS X allows widgets to have specific fixed sizes. Qt - does not fully implement this behavior so as to maintain cross-platform - compatibility. As a result some widgets sizes may be inappropriate (and - subsequently not rendered correctly by the HITheme APIs).The - QWidget::sizeHint() will return the appropriate size for many - managed widgets (widgets enumerated in \l QStyle::ContentsType). - - \i Effects - QMacStyle uses HITheme for performing most of the drawing, but - also uses emulation in a few cases where HITheme does not provide the - required functionality (for example, tab bars on Panther, the toolbar - separator, etc). We tried to make the emulation as close to the original as - possible. Please report any issues you see in effects or non-standard - widgets. - - \endlist - - There are other issues that need to be considered in the feel of - your application (including the general color scheme to match the - Aqua colors). The Guidelines mentioned above will remain current - with new advances and design suggestions for Mac OS X. - - Note that the functions provided by QMacStyle are - reimplementations of QStyle functions; see QStyle for their - documentation. - - \img qmacstyle.png - \sa QWindowsXPStyle, QWindowsStyle, QPlastiqueStyle, QCDEStyle, QMotifStyle -*/ - - -/*! - \enum QMacStyle::WidgetSizePolicy - - \value SizeSmall - \value SizeLarge - \value SizeMini - \value SizeDefault - \omitvalue SizeNone -*/ - -/*! \fn QMacStyle::QMacStyle() - Constructs a QMacStyle object. -*/ - -/*! \fn QMacStyle::~QMacStyle() - Destructs a QMacStyle object. -*/ - -/*! \fn void QMacStyle::polish(QPalette &pal) - \reimp -*/ - -/*! \fn void QMacStyle::polish(QApplication *) - \reimp -*/ - -/*! \fn void QMacStyle::unpolish(QApplication *) - \reimp -*/ - -/*! \fn void QMacStyle::polish(QWidget* w) - \reimp -*/ - -/*! \fn void QMacStyle::unpolish(QWidget* w) - \reimp -*/ - -/*! \fn int QMacStyle::pixelMetric(PixelMetric metric, const QStyleOption *opt, const QWidget *widget) const - \reimp -*/ - -/*! \fn QPalette QMacStyle::standardPalette() const - \reimp -*/ - -/*! \fn int QMacStyle::styleHint(StyleHint sh, const QStyleOption *opt, const QWidget *w, QStyleHintReturn *hret) const - \reimp -*/ - -/*! \fn QPixmap QMacStyle::generatedIconPixmap(QIcon::Mode iconMode, const QPixmap &pixmap, const QStyleOption *opt) const - \reimp -*/ - -/*! \fn QPixmap QMacStyle::standardPixmap(StandardPixmap standardPixmap, const QStyleOption *opt, const QWidget *widget) const - \reimp -*/ - -/*! - \enum QMacStyle::FocusRectPolicy - - This type is used to signify a widget's focus rectangle policy. - - \value FocusEnabled show a focus rectangle when the widget has focus. - \value FocusDisabled never show a focus rectangle for the widget. - \value FocusDefault show a focus rectangle when the widget has - focus and the widget is a QSpinWidget, QDateTimeEdit, QLineEdit, - QListBox, QListView, editable QTextEdit, or one of their - subclasses. -*/ - -/*! \fn void QMacStyle::setFocusRectPolicy(QWidget *w, FocusRectPolicy policy) - \obsolete - Sets the focus rectangle policy of \a w. The \a policy can be one of - \l{QMacStyle::FocusRectPolicy}. - - This is now simply an interface to the Qt::WA_MacShowFocusRect attribute and the - FocusDefault value does nothing anymore. If you want to set a widget back - to its default value, you must save the old value of the attribute before - you change it. - - \sa focusRectPolicy() QWidget::setAttribute() -*/ - -/*! \fn QMacStyle::FocusRectPolicy QMacStyle::focusRectPolicy(const QWidget *w) - \obsolete - Returns the focus rectangle policy for the widget \a w. - - The focus rectangle policy can be one of \l{QMacStyle::FocusRectPolicy}. - - In 4.3 and up this function will simply test for the - Qt::WA_MacShowFocusRect attribute and will never return - QMacStyle::FocusDefault. - - \sa setFocusRectPolicy(), QWidget::testAttribute() -*/ - -/*! \fn void QMacStyle::setWidgetSizePolicy(const QWidget *widget, WidgetSizePolicy policy) - - \obsolete - - Call QWidget::setAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, - or Qt::WA_MacNormalSize instead. -*/ - -/*! \fn QMacStyle::WidgetSizePolicy QMacStyle::widgetSizePolicy(const QWidget *widget) - \obsolete - - Call QWidget::testAttribute() with Qt::WA_MacMiniSize, Qt::WA_MacSmallSize, - or Qt::WA_MacNormalSize instead. -*/ - -/*! \fn void QMacStyle::drawPrimitive(PrimitiveElement pe, const QStyleOption *opt, QPainter *p, const QWidget *w) const - - \reimp -*/ - -/*! \fn void QMacStyle::drawControl(ControlElement ce, const QStyleOption *opt, QPainter *p, const QWidget *w) const - - \reimp -*/ - -/*! \fn QRect QMacStyle::subElementRect(SubElement sr, const QStyleOption *opt, const QWidget *widget) const - - \reimp -*/ - -/*! \fn void QMacStyle::drawComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, QPainter *p, const QWidget *widget) const - \reimp -*/ - -/*! \fn QStyle::SubControl QMacStyle::hitTestComplexControl(ComplexControl cc, const QStyleOptionComplex *opt, const QPoint &pt, const QWidget *widget) const - \reimp -*/ - -/*! \fn QRect QMacStyle::subControlRect(ComplexControl cc, const QStyleOptionComplex *opt, SubControl sc, const QWidget *widget) const - \reimp -*/ - -/*! \fn QSize QMacStyle::sizeFromContents(ContentsType ct, const QStyleOption *opt, const QSize &csz, const QWidget *widget) const - \reimp -*/ - -/*! \fn void QMacStyle::drawItemText(QPainter *p, const QRect &r, int flags, const QPalette &pal, bool enabled, const QString &text, QPalette::ColorRole textRole) const - \reimp -*/ - -/*! \fn bool QMacStyle::event(QEvent *e) - \reimp -*/ - -/*! \fn QIcon QMacStyle::standardIconImplementation(StandardPixmap standardIcon, const QStyleOption *opt, const QWidget *widget) const - \internal -*/ - -/*! \fn int QMacStyle::layoutSpacingImplementation(QSizePolicy::ControlType control1, QSizePolicy::ControlType control2, Qt::Orientation orientation, const QStyleOption *option, const QWidget *widget) const - - \internal -*/ - diff --git a/doc/src/classes/qnamespace.qdoc b/doc/src/classes/qnamespace.qdoc deleted file mode 100644 index 79a4560..0000000 --- a/doc/src/classes/qnamespace.qdoc +++ /dev/null @@ -1,2756 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \namespace Qt - \inmodule QtCore - - \brief The Qt namespace contains miscellaneous identifiers - used throughout the Qt library. - - \ingroup misc -*/ - -/*! - \enum Qt::Orientation - - This type is used to signify an object's orientation. - - \value Horizontal - \value Vertical - - Orientation is used with QScrollBar for example. -*/ - -/*! - \enum Qt::AlignmentFlag - - This enum type is used to describe alignment. It contains - horizontal and vertical flags that can be combined to produce - the required effect. - - The \l{TextElideMode} enum can also be used in many situations - to fine-tune the appearance of aligned text. - - The horizontal flags are: - - \value AlignLeft Aligns with the left edge. - \value AlignRight Aligns with the right edge. - \value AlignHCenter Centers horizontally in the available space. - \value AlignJustify Justifies the text in the available space. - \omitvalue AlignAuto - - The vertical flags are: - - \value AlignTop Aligns with the top. - \value AlignBottom Aligns with the bottom. - \value AlignVCenter Centers vertically in the available space. - - You can use only one of the horizontal flags at a time. There is - one two-dimensional flag: - - \value AlignCenter Centers in both dimensions. - - You can use at most one horizontal and one vertical flag at a - time. Qt::AlignCenter counts as both horizontal and vertical. - - Three enum values are useful in applications that can be run in - right-to-left mode: - - \value AlignAbsolute If the widget's layout direction is - Qt::RightToLeft (instead of Qt::LeftToRight, the default), - Qt::AlignLeft refers to the \e right edge and Qt::AlignRight - to the \e left edge. This is normally the desired behavior. - If you want Qt::AlignLeft to always mean "left" and - Qt::AlignRight to always mean "right", combine the flag with - Qt::AlignAbsolute. - \value AlignLeading Synonym for Qt::AlignLeft. - \value AlignTrailing Synonym for Qt::AlignRight. - - Masks: - - \value AlignHorizontal_Mask - \value AlignVertical_Mask - - Conflicting combinations of flags have undefined meanings. -*/ - -/*! - \enum Qt::ApplicationAttribute - - This enum describes attributes that change the behavior of - application-wide features. These are enabled and disabled using - QCoreApplication::setAttribute(), and can be tested for with - QCoreApplication::testAttribute(). - - \value AA_ImmediateWidgetCreation Ensures that widgets are created - as soon as they are constructed. By default, resources for - widgets are allocated on demand to improve efficiency and - minimize resource usage. Setting or clearing this attribute - affects widgets constructed after the change. Setting it - tells Qt to create toplevel windows immediately. - Therefore, if it is important to minimize resource - consumption, do not set this attribute. - - \value AA_MSWindowsUseDirect3DByDefault This value is obsolete and - has no effect. - - \value AA_DontShowIconsInMenus Actions with the Icon property won't be - shown in any menus unless specifically set by the - QAction::iconVisibleInMenu property. - - Menus that are currently open or menus already created in the native - Mac OS X menubar \e{may not} pick up a change in this attribute. Changes - in the QAction::iconVisibleInMenu property will always be picked up. - - \value AA_NativeWindows Ensures that widgets have native windows. - - \value AA_DontCreateNativeWidgetSiblings Ensures that siblings of native - widgets stay non-native unless specifically set by the - Qt::WA_NativeWindow attribute. - - \value AA_MacPluginApplication Stops the Qt mac application from doing - specific initializations that do not necessarily make sense when using Qt - to author a plugin. This includes avoiding loading our nib for the main - menu and not taking possession of the native menu bar. When setting this - attribute to true will also set the AA_DontUseNativeMenuBar attribute - to true. - - \value AA_DontUseNativeMenuBar All menubars created while this attribute is - set to true won't be used as a native menubar (e.g, the menubar at - the top of the main screen on Mac OS X or at the bottom in Windows CE). - - \value AA_MacDontSwapCtrlAndMeta On Mac OS X by default, Qt swaps the - Control and Meta (Command) keys (i.e., whenever Control is pressed, Qt - sends Meta and whenever Meta is pressed Control is sent. When this - attribute is true, Qt will not do the flip. QKeySequence::StandardShortcuts - will also flip accordingly (i.e., QKeySequence::Copy will be - Command+C on the keyboard regardless of the value set, though what is output for - QKeySequence::toString(QKeySequence::PortableText) will be different). - - \omitvalue AA_AttributeCount -*/ - -/*! - \enum Qt::MouseButton - - This enum type describes the different mouse buttons. - - \value NoButton The button state does not refer to any - button (see QMouseEvent::button()). - \value LeftButton The left button is pressed, or an event refers - to the left button. (The left button may be the right button on - left-handed mice.) - \value RightButton The right button. - \value MidButton The middle button. - \value XButton1 The first X button. - \value XButton2 The second X button. - - \omitvalue MouseButtonMask - - \sa KeyboardModifier Modifier -*/ - -/*! - \enum Qt::KeyboardModifier - - This enum describes the modifier keys. - - \value NoModifier No modifier key is pressed. - \value ShiftModifier A Shift key on the keyboard is pressed. - \value ControlModifier A Ctrl key on the keyboard is pressed. - \value AltModifier An Alt key on the keyboard is pressed. - \value MetaModifier A Meta key on the keyboard is pressed. - \value KeypadModifier A keypad button is pressed. - \value GroupSwitchModifier X11 only. A Mode_switch key on the keyboard is pressed. - - \omitvalue KeyboardModifierMask - - \note On Mac OS X, the \c ControlModifier value corresponds to - the Command keys on the Macintosh keyboard, and the \c MetaModifier value - corresponds to the Control keys. The \c KeypadModifier value will also be set - when an arrow key is pressed as the arrow keys are considered part of the - keypad. - - \note On Windows Keyboards, Qt::MetaModifier and Qt::Key_Meta are mapped - to the Windows key. - - \sa MouseButton Modifier -*/ - -/*! - \enum Qt::Modifier - - This enum provides shorter names for the keyboard modifier keys - supported by Qt. - - \bold{Note:} On Mac OS X, the \c CTRL value corresponds to - the Command keys on the Macintosh keyboard, and the \c META value - corresponds to the Control keys. - - \value SHIFT The Shift keys provided on all standard keyboards. - \value META The Meta keys. - \value CTRL The Ctrl keys. - \value ALT The normal Alt keys, but not keys like AltGr. - \value UNICODE_ACCEL The shortcut is specified as a Unicode code - point, not as a Qt Key. - \omitvalue MODIFIER_MASK - - \sa KeyboardModifier MouseButton -*/ - -/*! - \enum Qt::GlobalColor - - \raw HTML - <style type="text/css" id="colorstyles"> - #white { background-color: #ffffff; color: #000000 } - #black { background-color: #000000; color: #ffffff } - #red { background-color: #ff0000; color: #000000 } - #darkRed { background-color: #800000; color: #ffffff } - #green { background-color: #00ff00; color: #000000 } - #darkGreen { background-color: #008000; color: #ffffff } - #blue { background-color: #0000ff; color: #ffffff } - #darkBlue { background-color: #000080; color: #ffffff } - #cyan { background-color: #00ffff; color: #000000 } - #darkCyan { background-color: #008080; color: #ffffff } - #magenta { background-color: #ff00ff; color: #000000 } - #darkMagenta { background-color: #800080; color: #ffffff } - #yellow { background-color: #ffff00; color: #000000 } - #darkYellow { background-color: #808000; color: #ffffff } - #gray { background-color: #a0a0a4; color: #000000 } - #darkGray { background-color: #808080; color: #ffffff } - #lightGray { background-color: #c0c0c0; color: #000000 } - </style> - \endraw - - Qt's predefined QColor objects: - - \value white \raw HTML - White <tt id="white">(#ffffff)</tt> - \endraw - \value black \raw HTML - Black <tt id="black">(#000000)</tt> - \endraw - \value red \raw HTML - Red <tt id="red">(#ff0000)</tt> - \endraw - \value darkRed \raw HTML - Dark red <tt id="darkRed">(#800000)</tt> - \endraw - \value green \raw HTML - Green <tt id="green">(#00ff00)</tt> - \endraw - \value darkGreen \raw HTML - Dark green <tt id="darkGreen">(#008000)</tt> - \endraw - \value blue \raw HTML - Blue <tt id="blue">(#0000ff)</tt> - \endraw - \value darkBlue \raw HTML - Dark blue <tt id="darkBlue">(#000080)</tt> - \endraw - \value cyan \raw HTML - Cyan <tt id="cyan">(#00ffff)</tt> - \endraw - \value darkCyan \raw HTML - Dark cyan <tt id="darkCyan">(#008080)</tt> - \endraw - \value magenta \raw HTML - Magenta <tt id="magenta">(#ff00ff)</tt> - \endraw - \value darkMagenta \raw HTML - Dark magenta <tt id="darkMagenta">(#800080)</tt> - \endraw - \value yellow \raw HTML - Yellow <tt id="yellow">(#ffff00)</tt> - \endraw - \value darkYellow \raw HTML - Dark yellow <tt id="darkYellow">(#808000)</tt> - \endraw - \value gray \raw HTML - Gray <tt id="gray">(#a0a0a4)</tt> - \endraw - \value darkGray \raw HTML - Dark gray <tt id="darkGray">(#808080)</tt> - \endraw - \value lightGray \raw HTML - Light gray <tt id="lightGray">(#c0c0c0)</tt> - \endraw - \value transparent a transparent black value (i.e., QColor(0, 0, 0, 0)) - \value color0 0 pixel value (for bitmaps) - \value color1 1 pixel value (for bitmaps) - - \sa QColor - -*/ - -/*! - \enum Qt::PenStyle - - This enum type defines the pen styles that can be drawn using - QPainter. The styles are: - - \table - \row - \o \inlineimage qpen-solid.png - \o \inlineimage qpen-dash.png - \o \inlineimage qpen-dot.png - \row - \o Qt::SolidLine - \o Qt::DashLine - \o Qt::DotLine - \row - \o \inlineimage qpen-dashdot.png - \o \inlineimage qpen-dashdotdot.png - \o \inlineimage qpen-custom.png - \row - \o Qt::DashDotLine - \o Qt::DashDotDotLine - \o Qt::CustomDashLine - \endtable - - \value NoPen no line at all. For example, QPainter::drawRect() - fills but does not draw any boundary line. - - \value SolidLine A plain line. - \value DashLine Dashes separated by a few pixels. - \value DotLine Dots separated by a few pixels. - \value DashDotLine Alternate dots and dashes. - \value DashDotDotLine One dash, two dots, one dash, two dots. - \value CustomDashLine A custom pattern defined using - QPainterPathStroker::setDashPattern(). - - \omitvalue MPenStyle - - \sa QPen -*/ - -/*! - \enum Qt::PenCapStyle - - This enum type defines the pen cap styles supported by Qt, i.e. - the line end caps that can be drawn using QPainter. - - \table - \row - \o \inlineimage qpen-square.png - \o \inlineimage qpen-flat.png - \o \inlineimage qpen-roundcap.png - \row - \o Qt::SquareCap - \o Qt::FlatCap - \o Qt::RoundCap - \endtable - - \value FlatCap a square line end that does not cover the end - point of the line. - \value SquareCap a square line end that covers the end point and - extends beyond it by half the line width. - \value RoundCap a rounded line end. - \omitvalue MPenCapStyle - - \sa QPen -*/ - -/*! - \enum Qt::PenJoinStyle - - This enum type defines the pen join styles supported by Qt, i.e. - which joins between two connected lines can be drawn using - QPainter. - - \table - \row - \o \inlineimage qpen-bevel.png - \o \inlineimage qpen-miter.png - \o \inlineimage qpen-roundjoin.png - \row - \o Qt::BevelJoin - \o Qt::MiterJoin - \o Qt::RoundJoin - \endtable - - \value MiterJoin The outer edges of the lines are extended to - meet at an angle, and this area is filled. - \value BevelJoin The triangular notch between the two lines is filled. - \value RoundJoin A circular arc between the two lines is filled. - \value SvgMiterJoin A miter join corresponding to the definition of - a miter join in the \l{SVG 1.2 Tiny} specification. - \omitvalue MPenJoinStyle - - \sa QPen -*/ - -/*! - \enum Qt::BrushStyle - - This enum type defines the brush styles supported by Qt, i.e. the - fill pattern of shapes drawn using QPainter. - - \image brush-styles.png Brush Styles - - \value NoBrush No brush pattern. - \value SolidPattern Uniform color. - \value Dense1Pattern Extremely dense brush pattern. - \value Dense2Pattern Very dense brush pattern. - \value Dense3Pattern Somewhat dense brush pattern. - \value Dense4Pattern Half dense brush pattern. - \value Dense5Pattern Somewhat sparse brush pattern. - \value Dense6Pattern Very sparse brush pattern. - \value Dense7Pattern Extremely sparse brush pattern. - \value HorPattern Horizontal lines. - \value VerPattern Vertical lines. - \value CrossPattern Crossing horizontal and vertical lines. - \value BDiagPattern Backward diagonal lines. - \value FDiagPattern Forward diagonal lines. - \value DiagCrossPattern Crossing diagonal lines. - \value LinearGradientPattern Linear gradient (set using a dedicated QBrush constructor). - \value ConicalGradientPattern Conical gradient (set using a dedicated QBrush constructor). - \value RadialGradientPattern Radial gradient (set using a dedicated QBrush constructor). - \value TexturePattern Custom pattern (see QBrush::setTexture()). - - \omitvalue CustomPattern - - \sa QBrush -*/ - -/*! - \enum Qt::TextFlag - - This enum type is used to define some modifier flags. Some of - these flags only make sense in the context of printing: - - \value TextSingleLine Treats all whitespace as spaces and prints just - one line. - \value TextDontClip If it's impossible to stay within the given bounds, - it prints outside. - \value TextExpandTabs Makes the U+0009 (ASCII tab) character move to - the next tab stop. - \value TextShowMnemonic Displays the string "\&P" as \underline{P} - (see QButton for an example). For an ampersand, use "\&\&". - \value TextWordWrap Breaks lines at appropriate points, e.g. at word - boundaries. - \value TextWrapAnywhere Breaks lines anywhere, even within words. - \value TextHideMnemonic Same as Qt::TextShowMnemonic but doesn't draw the underlines. - \value TextDontPrint Treat this text as "hidden" and don't print - it. - \value IncludeTrailingSpaces When this option is set, QTextLine::naturalTextWidth() and naturalTextRect() will - return a value that includes the width of trailing spaces in the text; otherwise - this width is excluded. - \value TextIncludeTrailingSpaces Same as IncludeTrailingSpaces - \value TextJustificationForced Ensures that text lines are justified. - - \omitvalue BreakAnywhere - \omitvalue DontClip - \omitvalue DontPrint - \omitvalue ExpandTabs - \omitvalue IncludeTrailingSpaces - \omitvalue NoAccel - \omitvalue ShowPrefix - \omitvalue SingleLine - \omitvalue WordBreak - \omitvalue TextForceLeftToRight - \omitvalue TextForceRightToLeft - \omitvalue TextLongestVariant Always use the longest variant when computing the size of a multi-variant string - - You can use as many modifier flags as you want, except that - Qt::TextSingleLine and Qt::TextWordWrap cannot be combined. - - Flags that are inappropriate for a given use are generally - ignored. -*/ - -/*! - \enum Qt::BGMode - - Background mode: - - \value TransparentMode - \value OpaqueMode -*/ - -/*! - \enum Qt::ConnectionType - - This enum describes the types of connection that can be used between signals and - slots. In particular, it determines whether a particular signal is delivered to a - slot immediately or queued for delivery at a later time. - - \value DirectConnection When emitted, the signal is immediately delivered to the slot. - \value QueuedConnection When emitted, the signal is queued until the event loop is - able to deliver it to the slot. - \value BlockingQueuedConnection - Same as QueuedConnection, except that the current thread blocks - until the slot has been delivered. This connection type should - only be used for receivers in a different thread. Note that misuse - of this type can lead to deadlocks in your application. - \value AutoConnection If the signal is emitted from the thread - in which the receiving object lives, the - slot is invoked directly, as with - Qt::DirectConnection; otherwise the - signal is queued, as with - Qt::QueuedConnection. - \value UniqueConnection Same as AutoConnection, but there will be a check that the signal is - not already connected to the same slot before connecting, otherwise, - the connection will fail. - This value was introduced in Qt 4.6. - \value AutoCompatConnection - The default connection type for signals and slots when Qt 3 support - is enabled. Equivalent to AutoConnection for connections but will cause warnings - to be output under certain circumstances. See - \l{Porting to Qt 4#Compatibility Signals and Slots}{Compatibility Signals and Slots} - for further information. - - With queued connections, the parameters must be of types that are known to - Qt's meta-object system, because Qt needs to copy the arguments to store them - in an event behind the scenes. If you try to use a queued connection and - get the error message - - \snippet doc/src/snippets/code/doc_src_qnamespace.qdoc 0 - - call qRegisterMetaType() to register the data type before you - establish the connection. - - \sa {Thread Support in Qt}, QObject::connect(), qRegisterMetaType() -*/ - -/*! - \enum Qt::DateFormat - - \value TextDate The default Qt format, which includes the day and month name, - the day number in the month, and the year in full. The day and month names will - be short, localized names. This is basically equivalent to using the date format - string, "ddd MMM d yyyy". See QDate::toString() for more information. - - \value ISODate ISO 8601 extended format: either \c{YYYY-MM-DD} for dates or - \c{YYYY-MM-DDTHH:MM:SS} for combined dates and times. - - \value SystemLocaleShortDate The \l{QLocale::ShortFormat}{short format} used - by the \l{QLocale::system()}{operating system}. - - \value SystemLocaleLongDate The \l{QLocale::LongFormat}{long format} used - by the \l{QLocale::system()}{operating system}. - - \value DefaultLocaleShortDate The \l{QLocale::ShortFormat}{short format} specified - by the \l{QLocale::setDefault()}{application's locale}. - - \value DefaultLocaleLongDate The \l{QLocale::LongFormat}{long format} used - by the \l{QLocale::setDefault()}{application's locale}. - - \value SystemLocaleDate \e{This enum value is deprecated.} Use Qt::SystemLocaleShortDate - instead (or Qt::SystemLocaleLongDate if you want long dates). - - \value LocaleDate \e{This enum value is deprecated.} Use Qt::DefaultLocaleShortDate - instead (or Qt::DefaultLocaleLongDate if you want long dates). - - \value LocalDate \e{This enum value is deprecated.} Use Qt::SystemLocaleShortDate - instead (or Qt::SystemLocaleLongDate if you want long dates). - - \note For \c ISODate formats, each \c Y, \c M and \c D represents a single digit - of the year, month and day used to specify the date. Each \c H, \c M and \c S - represents a single digit of the hour, minute and second used to specify the time. - The presence of a literal \c T character is used to separate the date and time when - both are specified. -*/ - - -/*! - \enum Qt::TimeSpec - - \value LocalTime Locale dependent time (Timezones and Daylight Savings Time). - \value UTC Coordinated Universal Time, replaces Greenwich Mean Time. - \value OffsetFromUTC An offset in seconds from Coordinated Universal Time. -*/ - -/*! - \enum Qt::DayOfWeek - - \value Monday - \value Tuesday - \value Wednesday - \value Thursday - \value Friday - \value Saturday - \value Sunday -*/ - -/*! - \enum Qt::CaseSensitivity - - \value CaseInsensitive - \value CaseSensitive -*/ - -/*! - \enum Qt::ToolBarArea - - \value LeftToolBarArea - \value RightToolBarArea - \value TopToolBarArea - \value BottomToolBarArea - \value AllToolBarAreas - \value NoToolBarArea - - \omitvalue ToolBarArea_Mask -*/ - -/*! - \enum Qt::DockWidgetArea - - \value LeftDockWidgetArea - \value RightDockWidgetArea - \value TopDockWidgetArea - \value BottomDockWidgetArea - \value AllDockWidgetAreas - \value NoDockWidgetArea - - \omitvalue DockWidgetArea_Mask -*/ - -/*! - \enum Qt::BackgroundMode - - \compat - - \value FixedColor - \value FixedPixmap - \value NoBackground - \value PaletteForeground - \value PaletteButton - \value PaletteLight - \value PaletteMidlight - \value PaletteDark - \value PaletteMid - \value PaletteText - \value PaletteBrightText - \value PaletteBase - \value PaletteBackground - \value PaletteShadow - \value PaletteHighlight - \value PaletteHighlightedText - \value PaletteButtonText - \value PaletteLink - \value PaletteLinkVisited - \value X11ParentRelative -*/ - -/*! - \enum Qt::ImageConversionFlag - - The options marked "(default)" are set if no other values from - the list are included (since the defaults are zero): - - Color/Mono preference (ignored for QBitmap): - - \value AutoColor (default) - If the image has \link - QImage::depth() depth\endlink 1 and contains only - black and white pixels, the pixmap becomes monochrome. - \value ColorOnly The pixmap is dithered/converted to the - \link QPixmap::defaultDepth() native display depth\endlink. - \value MonoOnly The pixmap becomes monochrome. If necessary, - it is dithered using the chosen dithering algorithm. - - Dithering mode preference for RGB channels: - - \value DiffuseDither (default) - A high-quality dither. - \value OrderedDither A faster, more ordered dither. - \value ThresholdDither No dithering; closest color is used. - - Dithering mode preference for alpha channel: - - \value ThresholdAlphaDither (default) - No dithering. - \value OrderedAlphaDither A faster, more ordered dither. - \value DiffuseAlphaDither A high-quality dither. - \omitvalue NoAlpha - - Color matching versus dithering preference: - - \value PreferDither (default when converting to a pixmap) - Always dither - 32-bit images when the image is converted to 8 bits. - \value AvoidDither (default when converting for the purpose of saving to - file) - Dither 32-bit images only if the image has more than 256 - colors and it is being converted to 8 bits. - \omitvalue AutoDither - - \omitvalue ColorMode_Mask - \omitvalue Dither_Mask - \omitvalue AlphaDither_Mask - \omitvalue DitherMode_Mask - \omitvalue NoOpaqueDetection -*/ - -/*! \enum Qt::GUIStyle - - \compat - - \value WindowsStyle - \value MotifStyle - \value MacStyle - \value Win3Style - \value PMStyle -*/ - -/*! - \enum Qt::UIEffect - - This enum describes the available UI effects. - - By default, Qt will try to use the platform specific desktop - settings for each effect. Use the - QApplication::setDesktopSettingsAware() function (passing \c false - as argument) to prevent this, and the - QApplication::setEffectEnabled() to enable or disable a particular - effect. - - Note that all effects are disabled on screens running at less than - 16-bit color depth. - - \omitvalue UI_General - - \value UI_AnimateMenu Show animated menus. - \value UI_FadeMenu Show faded menus. - \value UI_AnimateCombo Show animated comboboxes. - \value UI_AnimateTooltip Show tooltip animations. - \value UI_FadeTooltip Show tooltip fading effects. - \value UI_AnimateToolBox Reserved - - \sa QApplication::setEffectEnabled(), QApplication::setDesktopSettingsAware() -*/ - -/*! \enum Qt::AspectRatioMode - - This enum type defines what happens to the aspect ratio when - scaling an rectangle. - - \image qimage-scaling.png - - \value IgnoreAspectRatio The size is scaled freely. The aspect - ratio is not preserved. - \value KeepAspectRatio The size is scaled to a rectangle as - large as possible inside a given - rectangle, preserving the aspect ratio. - \value KeepAspectRatioByExpanding The size is scaled to a - rectangle as small as possible - outside a given rectangle, - preserving the aspect ratio. - - \omitvalue ScaleFree - \omitvalue ScaleMin - \omitvalue ScaleMax - - \sa QSize::scale(), QImage::scaled() -*/ - -/*! \typedef Qt::ScaleMode - \compat - - Use Qt::AspectRatioMode instead. - - The enum values have been renamed as follows: - - \table - \row \i Old enum value \i New enum value - \row \i Qt::ScaleFree \i Qt::IgnoreAspectRatio - \row \i Qt::ScaleMin \i Qt::KeepAspectRatio - \row \i Qt::ScaleMax \i Qt::KeepAspectRatioByExpanding - \endtable -*/ - -/*! \enum Qt::TransformationMode - - This enum type defines whether image transformations (e.g., - scaling) should be smooth or not. - - \value FastTransformation The transformation is performed - quickly, with no smoothing. - \value SmoothTransformation The resulting image is transformed - using bilinear filtering. - - \sa QImage::scaled() -*/ - -/*! \enum Qt::Axis - - This enum type defines three values to represent the three - axes in the cartesian coordinate system. - - \value XAxis The X axis. - \value YAxis The Y axis. - \value ZAxis The Z axis. - - \sa QTransform::rotate(), QTransform::rotateRadians() - */ - -/*! - \enum Qt::WidgetAttribute - - \keyword widget attributes - - This enum type is used to specify various widget attributes. - Attributes are set and cleared with QWidget::setAttribute(), and - queried with QWidget::testAttribute(), although some have special - convenience functions which are mentioned below. - - \value WA_AcceptDrops Allows data from drag and drop operations - to be dropped onto the widget (see QWidget::setAcceptDrops()). - - \value WA_AlwaysShowToolTips Enables tooltips for inactive windows. - - \value WA_ContentsPropagated This flag is superfluous and - obsolete; it no longer has any effect. Since Qt 4.1, all widgets - that do not set WA_PaintOnScreen propagate their contents. - - \value WA_CustomWhatsThis Indicates that the widget wants to - continue operating normally in "What's This?" mode. This is set by the - widget's author. - - \value WA_DeleteOnClose Makes Qt delete this widget when the - widget has accepted the close event (see QWidget::closeEvent()). - - \value WA_Disabled Indicates that the widget is disabled, i.e. - it does not receive any mouse or keyboard events. There is also a - getter functions QWidget::isEnabled(). This is set/cleared by the - Qt kernel. - - \omitvalue WA_DropSiteRegistered - \omitvalue WA_ForceAcceptDrops - - \value WA_ForceDisabled Indicates that the widget is - explicitly disabled, i.e. it will remain disabled even when all - its ancestors are set to the enabled state. This implies - WA_Disabled. This is set/cleared by QWidget::setEnabled() and - QWidget::setDisabled(). - - \value WA_ForceUpdatesDisabled Indicates that updates are - explicitly disabled for the widget; i.e. it will remain disabled - even when all its ancestors are set to the updates-enabled state. - This implies WA_UpdatesDisabled. This is set/cleared by - QWidget::setUpdatesEnabled(). - - \value WA_GroupLeader - \e{This attribute has been deprecated.} Use QWidget::windowModality - instead. - - \value WA_Hover Forces Qt to generate paint events when the mouse - enters or leaves the widget. This feature is typically used when - implementing custom styles; see the \l{widgets/styles}{Styles} - example for details. - - \value WA_InputMethodEnabled Enables input methods for Asian languages. - Must be set when creating custom text editing widgets. - On Windows CE this flag can be used in addition to - QApplication::autoSipEnabled to automatically display the SIP when - entering a widget. - - \value WA_KeyboardFocusChange Set on a toplevel window when - the users changes focus with the keyboard (tab, backtab, or shortcut). - - \value WA_KeyCompression Enables key event compression if set, - and disables it if not set. By default key compression is off, so - widgets receive one key press event for each key press (or more, - since autorepeat is usually on). If you turn it on and your - program doesn't keep up with key input, Qt may try to compress key - events so that more than one character can be processed in each - event. - For example, a word processor widget might receive 2, 3 or more - characters in each QKeyEvent::text(), if the layout recalculation - takes too long for the CPU. - If a widget supports multiple character unicode input, it is - always safe to turn the compression on. - Qt performs key event compression only for printable characters. - Qt::Modifier keys, cursor movement keys, function keys and - miscellaneous action keys (e.g. Escape, Enter, Backspace, - PrintScreen) will stop key event compression, even if there are - more compressible key events available. - Platforms other than Mac and X11 do not support this compression, - in which case turning it on will have no effect. - This is set/cleared by the widget's author. - - \value WA_LayoutOnEntireRect Indicates that the widget - wants QLayout to operate on the entire QWidget::rect(), not only - on QWidget::contentsRect(). This is set by the widget's author. - - \value WA_LayoutUsesWidgetRect Ignore the layout item rect from the style - when laying out this widget with QLayout. This makes a difference in - QMacStyle and QPlastiqueStyle for some widgets. - - \value WA_MacNoClickThrough When a widget that has this attribute set - is clicked, and its window is inactive, the click will make the window - active but won't be seen by the widget. Typical use of this attribute - is on widgets with "destructive" actions, such as a "Delete" button. - WA_MacNoClickThrough also applies to all child widgets of the widget - that has it set. - - \value WA_MacOpaqueSizeGrip Indicates that the native Carbon size grip - should be opaque instead of transparent (the default). This attribute - is only applicable to Mac OS X and is set by the widget's author. - - \value WA_MacShowFocusRect Indicates that this widget should get a - QFocusFrame around it. Some widgets draw their own focus halo - regardless of this attribute. Not that the QWidget::focusPolicy - also plays the main role in whether something is given focus or - not, this only controls whether or not this gets the focus - frame. This attribute is only applicable to Mac OS X. - - \value WA_MacNormalSize Indicates the widget should have the - normal size for widgets in Mac OS X. This attribute is only - applicable to Mac OS X. - - \value WA_MacSmallSize Indicates the widget should have the small - size for widgets in Mac OS X. This attribute is only applicable to - Mac OS X. - - \value WA_MacMiniSize Indicates the widget should have the mini - size for widgets in Mac OS X. This attribute is only applicable to - Mac OS X. - - \value WA_MacVariableSize Indicates the widget can choose between - alternative sizes for widgets to avoid clipping. - This attribute is only applicable to Mac OS X. - - \value WA_MacBrushedMetal Indicates the widget should be drawn in - the brushed metal style as supported by the windowing system. This - attribute is only applicable to Mac OS X. - - \omitvalue WA_MacMetalStyle - - \value WA_Mapped Indicates that the widget is mapped on screen. - This is set/cleared by the Qt kernel. - - \value WA_MouseNoMask Makes the widget receive mouse events for - the entire widget regardless of the currently set mask, - overriding QWidget::setMask(). This is not applicable for - top-level windows. - - \value WA_MouseTracking Indicates that the widget has mouse - tracking enabled. See QWidget::mouseTracking. - - \value WA_Moved Indicates that the widget has an explicit - position. This is set/cleared by QWidget::move() and - by QWidget::setGeometry(). - - \value WA_MSWindowsUseDirect3D This value is obsolete and has no - effect. - - \value WA_NoBackground This value is obsolete. Use - WA_OpaquePaintEvent instead. - - \value WA_NoChildEventsForParent Indicates that the widget does - not want ChildAdded or ChildRemoved events sent to its - parent. This is rarely necessary but can help to avoid automatic - insertion widgets like splitters and layouts. This is set by a - widget's author. - - \value WA_NoChildEventsFromChildren Indicates that the widget does - not want to receive ChildAdded or ChildRemoved events sent from its - children. This is set by a widget's author. - - \value WA_NoMouseReplay Used for pop-up widgets. Indicates that the most - recent mouse press event should not be replayed when the pop-up widget - closes. The flag is set by the widget's author and cleared by the Qt kernel - every time the widget receives a new mouse event. - - \value WA_NoMousePropagation Prohibits mouse events from being propagated - to the widget's parent. This attribute is disabled by default. - - \value WA_TransparentForMouseEvents When enabled, this attribute disables - the delivery of mouse events to the widget and its children. Mouse events - are delivered to other widgets as if the widget and its children were not - present in the widget hierarchy; mouse clicks and other events effectively - "pass through" them. This attribute is disabled by default. - - \value WA_NoSystemBackground Indicates that the widget has no background, - i.e. when the widget receives paint events, the background is not - automatically repainted. \note Unlike WA_OpaquePaintEvent, newly exposed - areas are \bold never filled with the background (e.g., after showing a - window for the first time the user can see "through" it until the - application processes the paint events). This flag is set or cleared by the - widget's author. - - \value WA_OpaquePaintEvent Indicates that the widget paints all its pixels - when it receives a paint event. Thus, it is not required for operations - like updating, resizing, scrolling and focus changes to erase the widget - before generating paint events. The use of WA_OpaquePaintEvent provides a - small optimization by helping to reduce flicker on systems that do not - support double buffering and avoiding computational cycles necessary to - erase the background prior to painting. \note Unlike - WA_NoSystemBackground, WA_OpaquePaintEvent makes an effort to avoid - transparent window backgrounds. This flag is set or cleared by the widget's - author. - - \value WA_OutsideWSRange Indicates that the widget is outside - the valid range of the window system's coordinate system. A widget - outside the valid range cannot be mapped on screen. This is - set/cleared by the Qt kernel. - - \value WA_PaintOnScreen Indicates that the widget wants to draw directly - onto the screen. Widgets with this attribute set do not participate in - composition management, i.e. they cannot be semi-transparent or shine - through semi-transparent overlapping widgets. \note This flag is only - supported on X11 and it disables double buffering. On Qt for Embedded - Linux, the flag only works when set on a top-level widget and it relies on - support from the active screen driver. This flag is set or cleared by the - widget's author. To render outside of Qt's paint system, e.g., if you - require native painting primitives, you need to reimplement - QWidget::paintEngine() to return 0 and set this flag. - - \value WA_PaintOutsidePaintEvent Makes it possible to use QPainter to - paint on the widget outside \l{QWidget::paintEvent()}{paintEvent()}. This - flag is not supported on Windows, Mac OS X or Embedded Linux. We recommend - that you use it only when porting Qt 3 code to Qt 4. - - \value WA_PaintUnclipped Makes all painters operating on this widget - unclipped. Children of this widget or other widgets in front of it do not - clip the area the painter can paint on. This flag is only supported for - widgets with the WA_PaintOnScreen flag set. The preferred way to do this in - a cross platform way is to create a transparent widget that lies in front - of the other widgets. - - \value WA_PendingMoveEvent Indicates that a move event is pending, e.g., - when a hidden widget was moved. This flag is set or cleared by the Qt - kernel. - - \value WA_PendingResizeEvent Indicates that a resize event is pending, - e.g., when a hidden widget was resized. This flag is set or cleared by the - Qt kernel. - - \value WA_QuitOnClose Makes Qt quit the application when the last widget - with the attribute set has accepted closeEvent(). This behavior can be - modified with the QApplication::quitOnLastWindowClosed property. By default - this attribute is set for all widgets of type Qt::Window. - - \value WA_Resized Indicates that the widget has an explicit size. This flag - is set or cleared by QWidget::resize() and QWidget::setGeometry(). - - \value WA_RightToLeft Indicates that the layout direction for the widget - is right to left. - - \value WA_SetCursor Indicates that the widget has a cursor of its own. This - flag is set or cleared by QWidget::setCursor() and QWidget::unsetCursor(). - - \value WA_SetFont Indicates that the widget has a font of its own. This - flag is set or cleared by QWidget::setFont(). - - \value WA_SetPalette Indicates that the widget has a palette of its own. - This flag is set or cleared by QWidget::setPalette(). - - \value WA_SetStyle Indicates that the widget has a style of its own. This - flag is set or cleared by QWidget::setStyle(). - - \value WA_ShowModal \e{This attribute has been deprecated.} Use - QWidget::windowModality instead. - - \value WA_StaticContents Indicates that the widget contents are north-west - aligned and static. On resize, such a widget will receive paint events only - for parts of itself that are newly visible. This flag is set or cleared by - the widget's author. - - \value WA_StyleSheet Indicates that the widget is styled using a - \l{Qt Style Sheets}{style sheet}. - - \value WA_TranslucentBackground Indicates that the widget should have a - translucent background, i.e., any non-opaque regions of the widgets will be - translucent because the widget will have an alpha channel. Setting this - flag causes WA_NoSystemBackground to be set. On Windows the - widget also needs the Qt::FramelessWindowHint window flag to be set. - This flag is set or cleared by the widget's author. - - \value WA_UnderMouse Indicates that the widget is under the mouse cursor. - The value is not updated correctly during drag and drop operations. There - is also a getter function, QWidget::underMouse(). This flag is set or - cleared by the Qt kernel. - - \value WA_UpdatesDisabled Indicates that updates are blocked (including the - system background). This flag is set or cleared by the Qt kernel. - \warning This flag must \e never be set or cleared by the widget's author. - - \value WA_WindowModified Indicates that the window is marked as modified. - On some platforms this flag will do nothing, on others (including Mac OS X - and Windows) the window will take a modified appearance. This flag is set - or cleared by QWidget::setWindowModified(). - - \value WA_WindowPropagation Makes a toplevel window inherit font and - palette from its parent. - - \value WA_MacAlwaysShowToolWindow On Mac OS X, show the tool window even - when the application is not active. By default, all tool windows are - hidden when the application is inactive. - - \value WA_SetLocale Indicates the locale should be taken into consideration - in the widget. - - \value WA_StyledBackground Indicates the widget should be drawn using a - styled background. - - \value WA_ShowWithoutActivating Show the widget without making it active. - - \value WA_NativeWindow Indicates that a native window is created for the - widget. Enabling this flag will also force a native window for the widget's - ancestors unless Qt::WA_DontCreateNativeAncestors is set. - - \value WA_DontCreateNativeAncestors Indicates that the widget's ancestors - are kept non-native even though the widget itself is native. - - \value WA_X11NetWmWindowTypeDesktop Adds _NET_WM_WINDOW_TYPE_DESKTOP to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. - - \value WA_X11NetWmWindowTypeDock Adds _NET_WM_WINDOW_TYPE_DOCK to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. - - \value WA_X11NetWmWindowTypeToolBar Adds _NET_WM_WINDOW_TYPE_TOOLBAR to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automaticaly sets this - attribute for QToolBar. - - \value WA_X11NetWmWindowTypeMenu Adds _NET_WM_WINDOW_TYPE_MENU to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute for QMenu when torn-off. - - \value WA_X11NetWmWindowTypeUtility Adds _NET_WM_WINDOW_TYPE_UTILITY to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute for the Qt::Tool window type. - - \value WA_X11NetWmWindowTypeSplash Adds _NET_WM_WINDOW_TYPE_SPLASH to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute for the Qt::SplashScreen window type. - - \value WA_X11NetWmWindowTypeDialog Adds _NET_WM_WINDOW_TYPE_DIALOG - to the window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This - attribute has no effect on non-X11 platforms. \note Qt automatically sets - this attribute for the Qt::Dialog and Qt::Sheet window types. - - \value WA_X11NetWmWindowTypeDropDownMenu Adds - _NET_WM_WINDOW_TYPE_DROPDOWN_MENU to the window's - _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This - attribute has no effect on non-X11 platforms. \note Qt - automatically sets this attribute for QMenus added to a QMenuBar. - - \value WA_X11NetWmWindowTypePopupMenu Adds _NET_WM_WINDOW_TYPE_POPUP_MENU - to the window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute for QMenu. - - \value WA_X11NetWmWindowTypeToolTip Adds _NET_WM_WINDOW_TYPE_TOOLTIP to the - window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute for the Qt::ToolTip window type. - - \value WA_X11NetWmWindowTypeNotification Adds - _NET_WM_WINDOW_TYPE_NOTIFICATION to the window's _NET_WM_WINDOW_TYPE X11 - window property. See http://standards.freedesktop.org/wm-spec/ for more - details. This attribute has no effect on non-X11 platforms. - - \value WA_X11NetWmWindowTypeCombo Adds _NET_WM_WINDOW_TYPE_COMBO - to the window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute for the QComboBox pop-up. - - \value WA_X11NetWmWindowTypeDND Adds _NET_WM_WINDOW_TYPE_DND to - the window's _NET_WM_WINDOW_TYPE X11 window property. See - http://standards.freedesktop.org/wm-spec/ for more details. This attribute - has no effect on non-X11 platforms. \note Qt automatically sets this - attribute on the feedback widget used during a drag. - - \value WA_MacFrameworkScaled Enables resolution independence aware mode - on Mac when using Carbon. This attribute has no effect on Cocoa. - The attribute is off by default and can be enabled on a per-window basis. - - \value WA_AcceptTouchEvents Allows touch events (see QTouchEvent) - to be sent to the widget. Must be set on all widgets that can - handle touch events. Without this attribute set, events from a - touch device will be sent as mouse events. - - \value WA_TouchPadAcceptSingleTouchEvents Allows touchpad single - touch events to be sent to the widget. - - \omitvalue WA_SetLayoutDirection - \omitvalue WA_InputMethodTransparent - \omitvalue WA_WState_CompressKeys - \omitvalue WA_WState_ConfigPending - \omitvalue WA_WState_Created - \omitvalue WA_WState_DND - \omitvalue WA_WState_ExplicitShowHide - \omitvalue WA_WState_Hidden - \omitvalue WA_WState_InPaintEvent - \omitvalue WA_WState_OwnSizePolicy - \omitvalue WA_WState_Polished - \omitvalue WA_WState_Reparented - \omitvalue WA_WState_Visible - \omitvalue WA_SetWindowIcon - \omitvalue WA_PendingUpdate - \omitvalue WA_LaidOut - \omitvalue WA_GrabbedShortcut - \omitvalue WA_DontShowOnScreen - \omitvalue WA_InvalidSize - \omitvalue WA_ForceUpdatesDisabled - \omitvalue WA_NoX11EventCompression - \omitvalue WA_TintedBackground - \omitvalue WA_X11OpenGLOverlay - \omitvalue WA_CanHostQMdiSubWindowTitleBar - \omitvalue WA_AttributeCount - \omitvalue WA_StyleSheet - \omitvalue WA_X11BypassTransientForHint - \omitvalue WA_SetWindowModality - \omitvalue WA_WState_WindowOpacitySet - \omitvalue WA_WState_AcceptedTouchBeginEvent -*/ - -/*! \typedef Qt::HANDLE - - Platform-specific handle type for system objects. This is - equivalent to \c{void *} on Mac OS X and embedded Linux, - and to \c{unsigned long} on X11. On Windows it is the - DWORD returned by the Win32 function getCurrentThreadId(). - - \warning Using this type is not portable. -*/ - -/*! - \enum Qt::Key - - The key names used by Qt. - - \value Key_Escape - \value Key_Tab - \value Key_Backtab - \omitvalue Key_BackTab - \value Key_Backspace - \omitvalue Key_BackSpace - \value Key_Return - \value Key_Enter Typically located on the keypad. - \value Key_Insert - \value Key_Delete - \value Key_Pause - \value Key_Print - \value Key_SysReq - \value Key_Clear - \value Key_Home - \value Key_End - \value Key_Left - \value Key_Up - \value Key_Right - \value Key_Down - \value Key_PageUp - \omitvalue Key_Prior - \value Key_PageDown - \omitvalue Key_Next - \value Key_Shift - \value Key_Control On Mac OS X, this corresponds to the Command keys. - \value Key_Meta On Mac OS X, this corresponds to the Control keys. - On Windows keyboards, this key is mapped to the - Windows key. - \value Key_Alt - \value Key_AltGr On Windows, when the KeyDown event for this key is - sent, the Ctrl+Alt modifiers are also set. - \value Key_CapsLock - \value Key_NumLock - \value Key_ScrollLock - \value Key_F1 - \value Key_F2 - \value Key_F3 - \value Key_F4 - \value Key_F5 - \value Key_F6 - \value Key_F7 - \value Key_F8 - \value Key_F9 - \value Key_F10 - \value Key_F11 - \value Key_F12 - \value Key_F13 - \value Key_F14 - \value Key_F15 - \value Key_F16 - \value Key_F17 - \value Key_F18 - \value Key_F19 - \value Key_F20 - \value Key_F21 - \value Key_F22 - \value Key_F23 - \value Key_F24 - \value Key_F25 - \value Key_F26 - \value Key_F27 - \value Key_F28 - \value Key_F29 - \value Key_F30 - \value Key_F31 - \value Key_F32 - \value Key_F33 - \value Key_F34 - \value Key_F35 - \value Key_Super_L - \value Key_Super_R - \value Key_Menu - \value Key_Hyper_L - \value Key_Hyper_R - \value Key_Help - \value Key_Direction_L - \value Key_Direction_R - \value Key_Space - \value Key_Any - \value Key_Exclam - \value Key_QuoteDbl - \value Key_NumberSign - \value Key_Dollar - \value Key_Percent - \value Key_Ampersand - \value Key_Apostrophe - \value Key_ParenLeft - \value Key_ParenRight - \value Key_Asterisk - \value Key_Plus - \value Key_Comma - \value Key_Minus - \value Key_Period - \value Key_Slash - \value Key_0 - \value Key_1 - \value Key_2 - \value Key_3 - \value Key_4 - \value Key_5 - \value Key_6 - \value Key_7 - \value Key_8 - \value Key_9 - \value Key_Colon - \value Key_Semicolon - \value Key_Less - \value Key_Equal - \value Key_Greater - \value Key_Question - \value Key_At - \value Key_A - \value Key_B - \value Key_C - \value Key_D - \value Key_E - \value Key_F - \value Key_G - \value Key_H - \value Key_I - \value Key_J - \value Key_K - \value Key_L - \value Key_M - \value Key_N - \value Key_O - \value Key_P - \value Key_Q - \value Key_R - \value Key_S - \value Key_T - \value Key_U - \value Key_V - \value Key_W - \value Key_X - \value Key_Y - \value Key_Z - \value Key_BracketLeft - \value Key_Backslash - \value Key_BracketRight - \value Key_AsciiCircum - \value Key_Underscore - \value Key_QuoteLeft - \value Key_BraceLeft - \value Key_Bar - \value Key_BraceRight - \value Key_AsciiTilde - \value Key_nobreakspace - \value Key_exclamdown - \value Key_cent - \value Key_sterling - \value Key_currency - \value Key_yen - \value Key_brokenbar - \value Key_section - \value Key_diaeresis - \value Key_copyright - \value Key_ordfeminine - \value Key_guillemotleft - \value Key_notsign - \value Key_hyphen - \value Key_registered - \value Key_macron - \value Key_degree - \value Key_plusminus - \value Key_twosuperior - \value Key_threesuperior - \value Key_acute - \value Key_mu - \value Key_paragraph - \value Key_periodcentered - \value Key_cedilla - \value Key_onesuperior - \value Key_masculine - \value Key_guillemotright - \value Key_onequarter - \value Key_onehalf - \value Key_threequarters - \value Key_questiondown - \value Key_Agrave - \value Key_Aacute - \value Key_Acircumflex - \value Key_Atilde - \value Key_Adiaeresis - \value Key_Aring - \value Key_AE - \value Key_Ccedilla - \value Key_Egrave - \value Key_Eacute - \value Key_Ecircumflex - \value Key_Ediaeresis - \value Key_Igrave - \value Key_Iacute - \value Key_Icircumflex - \value Key_Idiaeresis - \value Key_ETH - \value Key_Ntilde - \value Key_Ograve - \value Key_Oacute - \value Key_Ocircumflex - \value Key_Otilde - \value Key_Odiaeresis - \value Key_multiply - \value Key_Ooblique - \value Key_Ugrave - \value Key_Uacute - \value Key_Ucircumflex - \value Key_Udiaeresis - \value Key_Yacute - \value Key_THORN - \value Key_ssharp - \omitvalue Key_agrave - \omitvalue Key_aacute - \omitvalue Key_acircumflex - \omitvalue Key_atilde - \omitvalue Key_adiaeresis - \omitvalue Key_aring - \omitvalue Key_ae - \omitvalue Key_ccedilla - \omitvalue Key_egrave - \omitvalue Key_eacute - \omitvalue Key_ecircumflex - \omitvalue Key_ediaeresis - \omitvalue Key_igrave - \omitvalue Key_iacute - \omitvalue Key_icircumflex - \omitvalue Key_idiaeresis - \omitvalue Key_eth - \omitvalue Key_ntilde - \omitvalue Key_ograve - \omitvalue Key_oacute - \omitvalue Key_ocircumflex - \omitvalue Key_otilde - \omitvalue Key_odiaeresis - \value Key_division - \omitvalue Key_oslash - \omitvalue Key_ugrave - \omitvalue Key_uacute - \omitvalue Key_ucircumflex - \omitvalue Key_udiaeresis - \omitvalue Key_yacute - \omitvalue Key_thorn - \value Key_ydiaeresis - \value Key_Multi_key - \value Key_Codeinput - \value Key_SingleCandidate - \value Key_MultipleCandidate - \value Key_PreviousCandidate - \value Key_Mode_switch - \value Key_Kanji - \value Key_Muhenkan - \value Key_Henkan - \value Key_Romaji - \value Key_Hiragana - \value Key_Katakana - \value Key_Hiragana_Katakana - \value Key_Zenkaku - \value Key_Hankaku - \value Key_Zenkaku_Hankaku - \value Key_Touroku - \value Key_Massyo - \value Key_Kana_Lock - \value Key_Kana_Shift - \value Key_Eisu_Shift - \value Key_Eisu_toggle - \value Key_Hangul - \value Key_Hangul_Start - \value Key_Hangul_End - \value Key_Hangul_Hanja - \value Key_Hangul_Jamo - \value Key_Hangul_Romaja - \value Key_Hangul_Jeonja - \value Key_Hangul_Banja - \value Key_Hangul_PreHanja - \value Key_Hangul_PostHanja - \value Key_Hangul_Special - \value Key_Dead_Grave - \value Key_Dead_Acute - \value Key_Dead_Circumflex - \value Key_Dead_Tilde - \value Key_Dead_Macron - \value Key_Dead_Breve - \value Key_Dead_Abovedot - \value Key_Dead_Diaeresis - \value Key_Dead_Abovering - \value Key_Dead_Doubleacute - \value Key_Dead_Caron - \value Key_Dead_Cedilla - \value Key_Dead_Ogonek - \value Key_Dead_Iota - \value Key_Dead_Voiced_Sound - \value Key_Dead_Semivoiced_Sound - \value Key_Dead_Belowdot - \value Key_Dead_Hook - \value Key_Dead_Horn - \value Key_Back - \value Key_Forward - \value Key_Stop - \value Key_Refresh - \value Key_VolumeDown - \value Key_VolumeMute - \value Key_VolumeUp - \value Key_BassBoost - \value Key_BassUp - \value Key_BassDown - \value Key_TrebleUp - \value Key_TrebleDown - \value Key_MediaPlay - \value Key_MediaStop - \value Key_MediaPrevious - \omitvalue Key_MediaPrev - \value Key_MediaNext - \value Key_MediaRecord - \value Key_HomePage - \value Key_Favorites - \value Key_Search - \value Key_Standby - \value Key_OpenUrl - \value Key_LaunchMail - \value Key_LaunchMedia - \value Key_Launch0 - \value Key_Launch1 - \value Key_Launch2 - \value Key_Launch3 - \value Key_Launch4 - \value Key_Launch5 - \value Key_Launch6 - \value Key_Launch7 - \value Key_Launch8 - \value Key_Launch9 - \value Key_LaunchA - \value Key_LaunchB - \value Key_LaunchC - \value Key_LaunchD - \value Key_LaunchE - \value Key_LaunchF - \value Key_MediaLast - \value Key_unknown - - \value Key_Call - \value Key_Context1 - \value Key_Context2 - \value Key_Context3 - \value Key_Context4 - \value Key_Flip - \value Key_Hangup - \value Key_No - \value Key_Select - \value Key_Yes - - \value Key_Execute - \value Key_Printer - \value Key_Play - \value Key_Sleep - \value Key_Zoom - \value Key_Cancel - - \sa QKeyEvent::key() -*/ - -/*! - \enum Qt::HitTestAccuracy - - This enum contains the types of accuracy that can be used by the - QTextDocument class when testing for mouse clicks on text documents. - - \value ExactHit The point at which input occurred must coincide - exactly with input-sensitive parts of the document. - \value FuzzyHit The point at which input occurred can lie close to - input-sensitive parts of the document. - - This enum is defined in the \c <QTextDocument> header file. -*/ - -/*! - \enum Qt::WhiteSpaceMode - - This enum describes the types of whitespace mode that are used by - the QTextDocument class to meet the requirements of different kinds - of textual information. - - \value WhiteSpaceNormal The whitespace mode used to display - normal word wrapped text in paragraphs. - \value WhiteSpacePre A preformatted text mode in which - whitespace is reproduced exactly. - \value WhiteSpaceNoWrap - - \omitvalue WhiteSpaceModeUndefined - - This enum is defined in the \c <QTextDocument> header file. -*/ - -/*! - \enum Qt::ButtonState_enum - \compat - \value ShiftButton - \value ControlButton - \value AltButton - \value MetaButton - \value Keypad - \value KeyButtonMask - - Use Qt::KeyboardModifier instead. -*/ - -/*! - \typedef Qt::ButtonState - \compat - - Use Qt::KeyboardModifier instead. -*/ - -/*! - \enum Qt::CheckState - - This enum describes the state of checkable items, controls, and widgets. - - \value Unchecked The item is unchecked. - \value PartiallyChecked The item is partially checked. Items in hierarchical models - may be partially checked if some, but not all, of their - children are checked. - \value Checked The item is checked. - - \sa QCheckBox, Qt::ItemFlags, Qt::ItemDataRole -*/ - - -/*! - \enum Qt::ToolButtonStyle - - The style of the tool button, describing how the button's text and - icon should be displayed. - - \value ToolButtonIconOnly Only display the icon. - \value ToolButtonTextOnly Only display the text. - \value ToolButtonTextBesideIcon The text appears beside the icon. - \value ToolButtonTextUnderIcon The text appears under the icon. - \value ToolButtonFollowStyle Follow the \l{QStyle::SH_ToolButtonStyle}{style}. -*/ - -/*! - \enum Qt::Corner - - This enum type specifies a corner in a rectangle: - - \value TopLeftCorner The top-left corner of the rectangle. - \value TopRightCorner The top-right corner of the rectangle. - \value BottomLeftCorner The bottom-left corner of the rectangle. - \value BottomRightCorner The bottom-right corner of the rectangle. - - \omitvalue TopLeft - \omitvalue TopRight - \omitvalue BottomLeft - \omitvalue BottomRight -*/ - -/*! - \enum Qt::ScrollBarPolicy - - This enum type describes the various modes of QAbstractScrollArea's scroll - bars. - - \value ScrollBarAsNeeded QAbstractScrollArea shows a scroll bar when the - content is too large to fit and not otherwise. This is the - default. - - \value ScrollBarAlwaysOff QAbstractScrollArea never shows a scroll bar. - - \value ScrollBarAlwaysOn QAbstractScrollArea always shows a scroll bar. - - (The modes for the horizontal and vertical scroll bars are - independent.) -*/ - -/*! - \enum Qt::ArrowType - - \value NoArrow - \value UpArrow - \value DownArrow - \value LeftArrow - \value RightArrow -*/ - -/*! - \enum Qt::FocusReason - - This enum specifies why the focus changed. It will be passed - through QWidget::setFocus and can be retrieved in the QFocusEvent - sent to the widget upon focus change. - - \value MouseFocusReason A mouse action occurred. - \value TabFocusReason The Tab key was pressed. - \value BacktabFocusReason A Backtab occurred. The input for this may - include the Shift or Control keys; - e.g. Shift+Tab. - \value ActiveWindowFocusReason The window system made this window either - active or inactive. - \value PopupFocusReason The application opened/closed a pop-up that - grabbed/released the keyboard focus. - \value ShortcutFocusReason The user typed a label's buddy shortcut - \value MenuBarFocusReason The menu bar took focus. - \value OtherFocusReason Another reason, usually application-specific. - - \omitvalue NoFocusReason - - \sa {Keyboard Focus} -*/ - -/*! - \enum Qt::WindowState - - \keyword window state - - This enum type is used to specify the current state of a top-level - window. - - The states are - - \value WindowNoState The window has no state set (in normal state). - \value WindowMinimized The window is minimized (i.e. iconified). - \value WindowMaximized The window is maximized with a frame around it. - \value WindowFullScreen The window fills the entire screen without any frame around it. - \value WindowActive The window is the active window, i.e. it has keyboard focus. - -*/ - -/*! - \enum Qt::ContextMenuPolicy - - This enum type defines the various policies a widget can have with - respect to showing a context menu. - - \value NoContextMenu the widget does not feature a context menu, - context menu handling is deferred to the widget's parent. - \value PreventContextMenu the widget does not feature a context - menu, and in contrast to \c NoContextMenu, the handling is \e not - deferred to the widget's parent. This means that all right mouse - button events are guaranteed to be delivered to the widget itself - through mousePressEvent(), and mouseReleaseEvent(). - \value DefaultContextMenu the widget's QWidget::contextMenuEvent() handler is called. - \value ActionsContextMenu the widget displays its QWidget::actions() as context menu. - \value CustomContextMenu the widget emits the QWidget::customContextMenuRequested() signal. -*/ - -/*! - \enum Qt::FocusPolicy - - This enum type defines the various policies a widget can have with - respect to acquiring keyboard focus. - - \value TabFocus the widget accepts focus by tabbing. - \value ClickFocus the widget accepts focus by clicking. - \value StrongFocus the widget accepts focus by both tabbing - and clicking. On Mac OS X this will also - be indicate that the widget accepts tab focus - when in 'Text/List focus mode'. - \value WheelFocus like Qt::StrongFocus plus the widget accepts - focus by using the mouse wheel. - \value NoFocus the widget does not accept focus. - -*/ - -/*! - \enum Qt::ShortcutContext - - For a QEvent::Shortcut event to occur, the shortcut's key sequence - must be entered by the user in a context where the shortcut is - active. The possible contexts are these: - - \value WidgetShortcut The shortcut is active when its - parent widget has focus. - \value WidgetWithChildrenShortcut The shortcut is active - when its parent widget, or any of its children has focus. - Children which are top-level widgets, except pop-ups, are - not affected by this shortcut context. - \value WindowShortcut The shortcut is active when its - parent widget is a logical subwidget of the - active top-level window. - \value ApplicationShortcut The shortcut is active when one of - the applications windows are active. -*/ - -/*! - \typedef Qt::WFlags - - Synonym for Qt::WindowFlags. -*/ - -/*! - \enum Qt::WindowType - - \keyword window flag - - This enum type is used to specify various window-system properties - for the widget. They are fairly unusual but necessary in a few - cases. Some of these flags depend on whether the underlying window - manager supports them. - - The main types are - - \value Widget This is the default type for QWidget. Widgets of - this type are child widgets if they have a parent, - and independent windows if they have no parent. - See also Qt::Window and Qt::SubWindow. - - \value Window Indicates that the widget is a window, usually - with a window system frame and a title bar, - irrespective of whether the widget has a parent or - not. Note that it is not possible to unset this - flag if the widget does not have a parent. - - \value Dialog Indicates that the widget is a window that should - be decorated as a dialog (i.e., typically no - maximize or minimize buttons in the title bar). - This is the default type for QDialog. If you want - to use it as a modal dialog, it should be launched - from another window, or have a parent and used - with the QWidget::windowModality property. If you make - it modal, the dialog will prevent other top-level - windows in the application from getting any input. - We refer to a top-level window that has a parent - as a \e secondary window. - - \value Sheet Indicates that the window is a Macintosh sheet. Since - using a sheet implies window modality, the recommended - way is to use QWidget::setWindowModality(), or - QDialog::open(), instead. - - \value Drawer Indicates that the widget is a Macintosh drawer. - - \value Popup Indicates that the widget is a pop-up top-level - window, i.e. that it is modal, but has a window - system frame appropriate for pop-up menus. - - \value Tool Indicates that the widget is a tool window. A tool - window is often a small window with a smaller than - usual title bar and decoration, typically used for - collections of tool buttons. It there is a parent, - the tool window will always be kept on top of it. - If there isn't a parent, you may consider using - Qt::WindowStaysOnTopHint as well. If the window - system supports it, a tool window can be decorated - with a somewhat lighter frame. It can also be - combined with Qt::FramelessWindowHint. - \br - \br - On Mac OS X, tool windows correspond to the - \l{http://developer.apple.com/documentation/Carbon/Conceptual/HandlingWindowsControls/hitb-wind_cont_concept/chapter_2_section_2.html}{Floating} - class of windows. This means that the window lives on a - level above normal windows; it impossible to put a normal - window on top of it. By default, tool windows will disappear - when the application is inactive. This can be controlled by - the Qt::WA_MacAlwaysShowToolWindow attribute. - - \value ToolTip Indicates that the widget is a tooltip. This is - used internally to implement - \l{QWidget::toolTip}{tooltips}. - - \value SplashScreen Indicates that the window is a splash screen. - This is the default type for QSplashScreen. - - \value Desktop Indicates that this widget is the desktop. This - is the type for QDesktopWidget. - - \value SubWindow Indicates that this widget is a sub-window, such - as a QMdiSubWindow widget. - - There are also a number of flags which you can use to customize - the appearance of top-level windows. These have no effect on other - windows: - - \value MSWindowsFixedSizeDialogHint Gives the window a thin dialog border on Windows. - This style is traditionally used for fixed-size dialogs. - - \value MSWindowsOwnDC Gives the window its own display - context on Windows. - - \value X11BypassWindowManagerHint Bypass the window - manager completely. This results in a borderless window - that is not managed at all (i.e., no keyboard input unless - you call QWidget::activateWindow() manually). - - \value FramelessWindowHint Produces a borderless window. - The user cannot move or resize a borderless window via the window - system. On X11, the result of the flag is dependent on the window manager and its - ability to understand Motif and/or NETWM hints. Most existing - modern window managers can handle this. - - The \c CustomizeWindowHint flag is used to enable customization of - the window controls. This flag must be set to allow the \c - WindowTitleHint, \c WindowSystemMenuHint, \c - WindowMinimizeButtonHint, \c WindowMaximizeButtonHint and \c - WindowCloseButtonHint flags to be changed. - - \value CustomizeWindowHint Turns off the default window title hints. - - \value WindowTitleHint Gives the window a title bar. - - \value WindowSystemMenuHint Adds a window system menu, and - possibly a close button (for example on Mac). If you need to hide - or show a close button, it is more portable to use \c - WindowCloseButtonHint. - - \value WindowMinimizeButtonHint Adds a minimize button. On - some platforms this implies Qt::WindowSystemMenuHint for it to work. - - \value WindowMaximizeButtonHint Adds a maximize button. On - some platforms this implies Qt::WindowSystemMenuHint for it to work. - - \value WindowMinMaxButtonsHint Adds a minimize and a maximize - button. On some platforms this implies Qt::WindowSystemMenuHint for it to work. - - \value WindowCloseButtonHint Adds a close button. On - some platforms this implies Qt::WindowSystemMenuHint for it - to work. - - \value WindowContextHelpButtonHint Adds a context help button to dialogs. - On some platforms this implies Qt::WindowSystemMenuHint for it to work. - - \value MacWindowToolBarButtonHint On Mac OS X adds a tool bar button (i.e., - the oblong button that is on the top right of windows that have toolbars. - - \value BypassGraphicsProxyWidget Prevents the window and its children from - automatically embedding themselves into a QGraphicsProxyWidget if the - parent widget is already embedded. You can set this flag if you - want your widget to always be a toplevel widget on the desktop, - regardless of whether the parent widget is embedded in a scene or - not. - - \value WindowShadeButtonHint - - \value WindowStaysOnTopHint Informs the window system that the - window should stay on top of all other windows. Note that - on some window managers on X11 you also have to pass - Qt::X11BypassWindowManagerHint for this flag to work - correctly. - - \value WindowStaysOnBottomHint Informs the window system that the - window should stay on bottom of all other windows. Note - that on X11 this hint will work only in window managers - that support _NET_WM_STATE_BELOW atom. If a window always - on the bottom has a parent, the parent will also be left on - the bottom. This window hint is currently not implemented - for Mac OS X. - - \value WindowOkButtonHint Adds an OK button to the window decoration of a dialog. - Only supported for Windows CE. - - \value WindowCancelButtonHint Adds a Cancel button to the window decoration of a dialog. - Only supported for Windows CE. - - \value WindowType_Mask A mask for extracting the window type - part of the window flags. - - Obsolete flags: - - \value WMouseNoMask Use Qt::WA_MouseNoMask instead. - \value WDestructiveClose Use Qt::WA_DeleteOnClose instead. - \value WStaticContents Use Qt::WA_StaticContents instead. - \value WGroupLeader No longer needed. - \value WShowModal Use QWidget::windowModality instead. - \value WNoMousePropagation Use Qt::WA_NoMousePropagation instead. - \value WType_TopLevel Use Qt::Window instead. - \value WType_Dialog Use Qt::Dialog instead. - \value WType_Popup Use Qt::Popup instead. - \value WType_Desktop Use Qt::Desktop instead. - \value WType_Mask Use Qt::WindowType_Mask instead. - - \value WStyle_Customize No longer needed. - \value WStyle_NormalBorder No longer needed. - \value WStyle_DialogBorder Use Qt::MSWindowsFixedSizeDialogHint instead. - \value WStyle_NoBorder Use Qt::FramelessWindowHint instead. - \value WStyle_Title Use Qt::WindowTitleHint instead. - \value WStyle_SysMenu Use Qt::WindowSystemMenuHint instead. - \value WStyle_Minimize Use Qt::WindowMinimizeButtonHint instead. - \value WStyle_Maximize Use Qt::WindowMaximizeButtonHint instead. - \value WStyle_MinMax Use Qt::WindowMinMaxButtonsHint instead. - \value WStyle_Tool Use Qt::Tool instead. - \value WStyle_StaysOnTop Use Qt::WindowStaysOnTopHint instead. - \value WStyle_ContextHelp Use Qt::WindowContextHelpButtonHint instead. - - \value WPaintDesktop No longer needed. - \value WPaintClever No longer needed. - - \value WX11BypassWM Use Qt::X11BypassWindowManagerHint instead. - \value WWinOwnDC Use Qt::MSWindowsOwnDC instead. - \value WMacSheet Use Qt::Sheet instead. - \value WMacDrawer Use Qt::Drawer instead. - - \value WStyle_Splash Use Qt::SplashScreen instead. - - \value WNoAutoErase No longer needed. - \value WRepaintNoErase No longer needed. - \value WNorthWestGravity Use Qt::WA_StaticContents instead. - \value WType_Modal Use Qt::Dialog and QWidget::windowModality instead. - \value WStyle_Dialog Use Qt::Dialog instead. - \value WStyle_NoBorderEx Use Qt::FramelessWindowHint instead. - \value WResizeNoErase No longer needed. - \value WMacNoSheet No longer needed. - - \sa QWidget::windowFlags, {Window Flags Example} -*/ - -/*! - \enum Qt::DropAction - - \value CopyAction Copy the data to the target. - \value MoveAction Move the data from the source to the target. - \value LinkAction Create a link from the source to the target. - \value ActionMask - \value IgnoreAction Ignore the action (do nothing with the data). - \value TargetMoveAction On Windows, this value is used when the ownership of the D&D data - should be taken over by the target application, - i.e., the source application should not delete - the data. - \br - On X11 this value is used to do a move. - \br - TargetMoveAction is not used on the Mac. -*/ - -#if defined(Q_OS_WIN) && defined(QT3_SUPPORT) -/*! - \enum Qt::WindowsVersion - \compat - - \value WV_32s - \value WV_95 - \value WV_98 - \value WV_Me - \value WV_DOS_based - \value WV_NT - \value WV_2000 - \value WV_XP - \value WV_2003 - \value WV_NT_based - \value WV_CE - \value WV_CENET - \value WV_CE_based - \value WV_CE_5 - \value WV_CE_6 -*/ -#endif - -#if defined(Q_OS_MAC) && defined(QT3_SUPPORT) -/*! - \enum Qt::MacintoshVersion - \compat - - \value MV_Unknown Use QSysInfo::MV_Unknown instead. - \value MV_9 Use QSysInfo::MV_9 instead. - \value MV_10_DOT_0 Use QSysInfo::MV_10_0 instead. - \value MV_10_DOT_1 Use QSysInfo::MV_10_1 instead. - \value MV_10_DOT_2 Use QSysInfo::MV_10_2 instead. - \value MV_10_DOT_3 Use QSysInfo::MV_10_3 instead. - \value MV_10_DOT_4 Use QSysInfo::MV_10_4 instead. - - \value MV_CHEETAH Use QSysInfo::MV_10_0 instead. - \value MV_PUMA Use QSysInfo::MV_10_1 instead. - \value MV_JAGUAR Use QSysInfo::MV_10_2 instead. - \value MV_PANTHER Use QSysInfo::MV_10_3 instead. - \value MV_TIGER Use QSysInfo::MV_10_4 instead. - - \sa QSysInfo::MacVersion -*/ -#endif - -/*! \typedef Qt::ToolBarDock - \compat - - Use Qt::Dock instead. -*/ - -/*! - \enum Qt::Dock - \compat - - Each dock window can be in one of the following positions: - - \value DockUnmanaged not managed by a Q3MainWindow. - - \value DockTornOff the dock window floats as its own top level - window which always stays on top of the main window. - - \value DockTop above the central widget, below the menu bar. - - \value DockBottom below the central widget, above the status bar. - - \value DockRight to the right of the central widget. - - \value DockLeft to the left of the central widget. - - \value DockMinimized the dock window is not shown (this is - effectively a 'hidden' dock area); the handles of all minimized - dock windows are drawn in one row below the menu bar. - - \omitvalue Bottom - \omitvalue Left - \omitvalue Minimized - \omitvalue Right - \omitvalue Top - \omitvalue TornOff - \omitvalue Unmanaged -*/ - -/*! - \enum Qt::AnchorAttribute - - An anchor has one or more of the following attributes: - - \value AnchorName the name attribute of the anchor. This attribute is - used when scrolling to an anchor in the document. - - \value AnchorHref the href attribute of the anchor. This attribute is - used when a link is clicked to determine what content to load. -*/ - -/*! - \enum Qt::SortOrder - - This enum describes how the items in a widget are sorted. - - \value AscendingOrder The items are sorted ascending e.g. starts with - 'AAA' ends with 'ZZZ' in Latin-1 locales - - \value DescendingOrder The items are sorted descending e.g. starts with - 'ZZZ' ends with 'AAA' in Latin-1 locales - - \omitvalue Ascending - \omitvalue Descending -*/ - -/*! - \enum Qt::ClipOperation - - \value NoClip This operation turns clipping off. - - \value ReplaceClip Replaces the current clip path/rect/region with - the one supplied in the function call. - - \value IntersectClip Intersects the current clip path/rect/region - with the one supplied in the function call. - - \value UniteClip Unites the current clip path/rect/region with the - one supplied in the function call. -*/ - -/*! - \enum Qt::ItemSelectionMode - - This enum is used in QGraphicsItem, QGraphicsScene and QGraphicsView to - specify how items are selected, or how to determine if a shapes and items - collide. - - \value ContainsItemShape The output list contains only items whose - \l{QGraphicsItem::shape()}{shape} is fully contained inside the - selection area. Items that intersect with the area's outline are - not included. - - \value IntersectsItemShape The output list contains both items whose - \l{QGraphicsItem::shape()}{shape} is fully contained inside the - selection area, and items that intersect with the area's - outline. This is a common mode for rubber band selection. - - \value ContainsItemBoundingRect The output list contains only items whose - \l{QGraphicsItem::boundingRect()}{bounding rectangle} is fully - contained inside the selection area. Items that intersect with the - area's outline are not included. - - \value IntersectsItemBoundingRect The output list contains both items - whose \l{QGraphicsItem::boundingRect()}{bounding rectangle} is - fully contained inside the selection area, and items that intersect - with the area's outline. This method is commonly used for - determining areas that need redrawing. - - \sa QGraphicsScene::items(), QGraphicsScene::collidingItems(), - QGraphicsView::items(), QGraphicsItem::collidesWithItem(), - QGraphicsItem::collidesWithPath() -*/ - -/*! - \enum Qt::FillRule - - Specifies which method should be used to fill the paths and polygons. - - \value OddEvenFill Specifies that the region is filled using the - odd even fill rule. With this rule, we determine whether a point - is inside the shape by using the following method. - Draw a horizontal line from the point to a location outside the shape, - and count the number of intersections. If the number of intersections - is an odd number, the point is inside the shape. This mode is the - default. - - \value WindingFill Specifies that the region is filled using the - non zero winding rule. With this rule, we determine whether a - point is inside the shape by using the following method. - Draw a horizontal line from the point to a location outside the shape. - Determine whether the direction of the line at each intersection point - is up or down. The winding number is determined by summing the - direction of each intersection. If the number is non zero, the point - is inside the shape. This fill mode can also in most cases be considered - as the intersection of closed shapes. -*/ - -/*! - \enum Qt::PaintUnit - - \compat - - \value PixelUnit - \value LoMetricUnit Obsolete - \value HiMetricUnit Obsolete - \value LoEnglishUnit Obsolete - \value HiEnglishUnit Obsolete - \value TwipsUnit Obsolete -*/ - -/*! - \enum Qt::TextFormat - - This enum is used in widgets that can display both plain text and - rich text, e.g. QLabel. It is used for deciding whether a text - string should be interpreted as one or the other. This is normally - done by passing one of the enum values to a setTextFormat() - function. - - \value PlainText The text string is interpreted as a plain text - string. - - \value RichText The text string is interpreted as a rich text - string. - - \value AutoText The text string is interpreted as for - Qt::RichText if Qt::mightBeRichText() returns true, otherwise - as Qt::PlainText. - - \value LogText A special, limited text format which is only used - by Q3TextEdit in an optimized mode. -*/ - -/*! - \enum Qt::CursorShape - - This enum type defines the various cursors that can be used. - - The standard arrow cursor is the default for widgets in a normal state. - - \value ArrowCursor \inlineimage cursor-arrow.png - The standard arrow cursor. - \value UpArrowCursor \inlineimage cursor-uparrow.png - An arrow pointing upwards toward the top of the screen. - \value CrossCursor \inlineimage cursor-cross.png - A crosshair cursor, typically used to help the - user accurately select a point on the screen. - \value WaitCursor \inlineimage cursor-wait.png - An hourglass or watch cursor, usually shown during - operations that prevent the user from interacting with - the application. - \value IBeamCursor \inlineimage cursor-ibeam.png - A caret or ibeam cursor, indicating that a widget can - accept and display text input. - \value SizeVerCursor \inlineimage cursor-sizev.png - A cursor used for elements that are used to vertically - resize top-level windows. - \value SizeHorCursor \inlineimage cursor-sizeh.png - A cursor used for elements that are used to horizontally - resize top-level windows. - \value SizeBDiagCursor \inlineimage cursor-sizeb.png - A cursor used for elements that are used to diagonally - resize top-level windows at their top-right and - bottom-left corners. - \value SizeFDiagCursor \inlineimage cursor-sizef.png - A cursor used for elements that are used to diagonally - resize top-level windows at their top-left and - bottom-right corners. - \value SizeAllCursor \inlineimage cursor-sizeall.png - A cursor used for elements that are used to resize - top-level windows in any direction. - \value BlankCursor A blank/invisible cursor, typically used when the cursor - shape needs to be hidden. - \value SplitVCursor \inlineimage cursor-vsplit.png - A cursor used for vertical splitters, indicating that - a handle can be dragged horizontally to adjust the use - of available space. - \value SplitHCursor \inlineimage cursor-hsplit.png - A cursor used for horizontal splitters, indicating that - a handle can be dragged vertically to adjust the use - of available space. - \value PointingHandCursor \inlineimage cursor-hand.png - A pointing hand cursor that is typically used for - clickable elements such as hyperlinks. - \value ForbiddenCursor \inlineimage cursor-forbidden.png - A slashed circle cursor, typically used during drag - and drop operations to indicate that dragged content - cannot be dropped on particular widgets or inside - certain regions. - \value OpenHandCursor \inlineimage cursor-openhand.png - A cursor representing an open hand, typically used to - indicate that the area under the cursor is the visible - part of a canvas that the user can click and drag in - order to scroll around. - \value ClosedHandCursor \inlineimage cursor-closedhand.png - A cursor representing a closed hand, typically used to - indicate that a dragging operation is in progress that - involves scrolling. - \value WhatsThisCursor \inlineimage cursor-whatsthis.png - An arrow with a question mark, typically used to indicate - the presence of What's This? help for a widget. - \value BusyCursor \inlineimage cursor-wait.png - An hourglass or watch cursor, usually shown during - operations that allow the user to interact with - the application while they are performed in the - background. - \value BitmapCursor - \omitvalue LastCursor - \omitvalue CustomCursor - - \omitvalue arrowCursor - \omitvalue upArrowCursor - \omitvalue crossCursor - \omitvalue waitCursor - \omitvalue ibeamCursor - \omitvalue sizeVerCursor - \omitvalue sizeHorCursor - \omitvalue sizeBDiagCursor - \omitvalue sizeFDiagCursor - \omitvalue sizeAllCursor - \omitvalue blankCursor - \omitvalue splitVCursor - \omitvalue splitHCursor - \omitvalue pointingHandCursor - \omitvalue forbiddenCursor - \omitvalue whatsThisCursor -*/ - -/*! - \typedef Qt::TextFlags - \compat - - Use Qt::TextFlag instead. -*/ - -/*! - \enum Qt::LayoutDirection - - Specifies the direction of Qt's layouts: - - \value LeftToRight Left-to-right layout. - \value RightToLeft Right-to-left layout. - - Right-to-left layouts are necessary for certain languages, - notably Arabic and Hebrew. - - \sa QApplication::setLayoutDirection(), QWidget::setLayoutDirection() -*/ - -/*! - \enum Qt::InputMethodHint - - \value ImhNone No hints. - \value ImhHiddenText Characters should be hidden, as is typically used when entering passwords. - This is automatically set when setting QLineEdit::echoMode to \c Password. - \value ImhNumbersOnly Only number input is allowed. - \value ImhUppercaseOnly Only upper case letter input is allowed. - \value ImhLowercaseOnly Only lower case letter input is allowed. - \value ImhNoAutoUppercase The input method should not try to automatically switch to upper case - when a sentence ends. - \value ImhPreferNumbers Numbers are preferred (but not required). - \value ImhPreferUppercase Upper case letters are preferred (but not required). - \value ImhPreferLowercase Lower case letters are preferred (but not required). - \value ImhNoPredictiveText Do not use predictive text (i.e. dictionary lookup) while typing. - \value ImhDialableCharactersOnly Only characters suitable for phone dialling are allowed. - - \note If several flags ending with \c Only are ORed together, the resulting character set will - consist of the union of the specified sets. For instance specifying \c ImhNumbersOnly and - \c ImhUppercaseOnly would yield a set consisting of numbers and uppercase letters. - - \sa QGraphicsItem::inputMethodHints() -*/ - -/*! - \enum Qt::InputMethodQuery - - \value ImMicroFocus The rectangle covering the area of the input cursor in widget coordinates. - \value ImFont The currently used font for text input. - \value ImCursorPosition The logical position of the cursor within the text surrounding the input area (see ImSurroundingText). - If any text is selected, the position returned will be at the logical end of the - selection, even if the real cursor is located at the logical start. - \value ImSurroundingText The plain text around the input area, for example the current paragraph. - \value ImCurrentSelection The currently selected text. -*/ - -/*! - \enum Qt::ItemDataRole - - Each item in the model has a set of data elements associated with - it, each with its own role. The roles are used by the view to indicate - to the model which type of data it needs. Custom models should return - data in these types. - - The general purpose roles (and the associated types) are: - - \value DisplayRole The key data to be rendered in the form of text. (QString) - \value DecorationRole The data to be rendered as a decoration in the form - of an icon. (QColor) - \value EditRole The data in a form suitable for editing in an - editor. (QString) - \value ToolTipRole The data displayed in the item's tooltip. (QString) - \value StatusTipRole The data displayed in the status bar. (QString) - \value WhatsThisRole The data displayed for the item in "What's This?" - mode. (QString) - \value SizeHintRole The size hint for the item that will be supplied - to views. (QSize) - - Roles describing appearance and meta data (with associated types): - - \value FontRole The font used for items rendered with the default - delegate. (QFont) - \value TextAlignmentRole The alignment of the text for items rendered with the - default delegate. (Qt::AlignmentFlag) - \value BackgroundRole The background brush used for items rendered with - the default delegate. (QBrush) - \value BackgroundColorRole This role is obsolete. Use BackgroundRole instead. - \value ForegroundRole The foreground brush (text color, typically) - used for items rendered with the default delegate. - (QBrush) - \value TextColorRole This role is obsolete. Use ForegroundRole instead. - \value CheckStateRole This role is used to obtain the checked state of - an item. (Qt::CheckState) - - Accessibility roles (with associated types): - - \value AccessibleTextRole The text to be used by accessibility - extensions and plugins, such as screen - readers. (QString) - \value AccessibleDescriptionRole A description of the item for accessibility - purposes. (QString) - - User roles: - - \value UserRole The first role that can be used for application-specific purposes. - - \omitvalue DisplayPropertyRole - \omitvalue DecorationPropertyRole - \omitvalue ToolTipPropertyRole - \omitvalue StatusTipPropertyRole - \omitvalue WhatsThisPropertyRole - - For user roles, it is up to the developer to decide which types to use and ensure that - components use the correct types when accessing and setting data. -*/ - -/*! - \enum Qt::ItemFlag - - This enum describes the properties of an item: - - \value NoItemFlags It does not have any properties set. - \value ItemIsSelectable It can be selected. - \value ItemIsEditable It can be edited. - \value ItemIsDragEnabled It can be dragged. - \value ItemIsDropEnabled It can be used as a drop target. - \value ItemIsUserCheckable It can be checked or unchecked by the user. - \value ItemIsEnabled The user can interact with the item. - \value ItemIsTristate The item is checkable with three separate states. - - Note that checkable items need to be given both a suitable set of flags - and an initial state, indicating whether the item is checked or not. - This is handled automatically for model/view components, but needs - to be explicitly set for instances of QListWidgetItem, QTableWidgetItem, - and QTreeWidgetItem. - - \sa QAbstractItemModel -*/ - -/*! - \enum Qt::MatchFlag - - This enum describes the type of matches that can be used when searching - for items in a model. - - \value MatchExactly Performs QVariant-based matching. - \value MatchFixedString Performs string-based matching. - String-based comparisons are case-insensitive unless the - \c MatchCaseSensitive flag is also specified. - \value MatchContains The search term is contained in the item. - \value MatchStartsWith The search term matches the start of the item. - \value MatchEndsWith The search term matches the end of the item. - \value MatchCaseSensitive The search is case sensitive. - \value MatchRegExp Performs string-based matching using a regular - expression as the search term. - \value MatchWildcard Performs string-based matching using a string with - wildcards as the search term. - \value MatchWrap Perform a search that wraps around, so that when - the search reaches the last item in the model, it begins again at - the first item and continues until all items have been examined. - \value MatchRecursive Searches the entire hierarchy. - - \sa QString::compare(), QRegExp -*/ - -/*! - \enum Qt::TextElideMode - - This enum specifies where the ellipsis should appear when - displaying texts that don't fit: - - \value ElideLeft The ellipsis should appear at the beginning of the text. - \value ElideRight The ellipsis should appear at the end of the text. - \value ElideMiddle The ellipsis should appear in the middle of the text. - \value ElideNone Ellipsis should NOT appear in the text. - - Qt::ElideMiddle is normally the most appropriate choice for URLs (e.g., - "\l{http://qt.nokia.com/careers/movingto/brisbane/}{http://qt.nok...ovingto/brisbane/}"), - whereas Qt::ElideRight is appropriate - for other strings (e.g., - "\l{http://qt.nokia.com/doc/qq/qq09-mac-deployment.html}{Deploying Applications on Ma...}"). - - \sa QAbstractItemView::textElideMode, QFontMetrics::elidedText(), AlignmentFlag QTabBar::elideMode -*/ - -/*! - \enum Qt::WindowModality - - \keyword modal - - This enum specifies the behavior of a modal window. A modal window - is one that blocks input to other windows. Note that windows that - are children of a modal window are not blocked. - - The values are: - \value NonModal The window is not modal and does not block input to other windows. - \value WindowModal The window is modal to a single window hierarchy and blocks input to its parent window, all grandparent windows, and all siblings of its parent and grandparent windows. - \value ApplicationModal The window is modal to the application and blocks input to all windows. - - \sa QWidget::windowModality, QDialog -*/ - -/*! - \enum Qt::TextInteractionFlag - - This enum specifies how a text displaying widget reacts to user input. - - \value NoTextInteraction No interaction with the text is possible. - \value TextSelectableByMouse Text can be selected with the mouse and copied to the clipboard using - a context menu or standard keyboard shortcuts. - \value TextSelectableByKeyboard Text can be selected with the cursor keys on the keyboard. A text cursor is shown. - \value LinksAccessibleByMouse Links can be highlighted and activated with the mouse. - \value LinksAccessibleByKeyboard Links can be focused using tab and activated with enter. - \value TextEditable The text is fully editable. - - \value TextEditorInteraction The default for a text editor. - \value TextBrowserInteraction The default for QTextBrowser. -*/ - -/*! - \enum Qt::MaskMode - - This enum specifies the behavior of the - QPixmap::createMaskFromColor() and QImage::createMaskFromColor() - functions. - - \value MaskInColor Creates a mask where all pixels matching the given color are opaque. - \value MaskOutColor Creates a mask where all pixels matching the given color are transparent. -*/ - -/*! - \enum Qt::DockWidgetAreaSizes - \internal -*/ - -/*! - \enum Qt::ToolBarAreaSizes - \internal -*/ - -/*! - \enum Qt::EventPriority - - This enum can be used to specify event priorities. - - \value HighEventPriority Events with this priority are sent before - events with NormalEventPriority or LowEventPriority. - - \value NormalEventPriority Events with this priority are sent - after events with HighEventPriority, but before events with - LowEventPriority. - - \value LowEventPriority Events with this priority are sent after - events with HighEventPriority or NormalEventPriority. - - Note that these values are provided purely for convenience, since - event priorities can be any value between \c INT_MAX and \c - INT_MIN, inclusive. For example, you can define custom priorities - as being relative to each other: - - \snippet doc/src/snippets/code/doc_src_qnamespace.qdoc 1 - - \sa QCoreApplication::postEvent() -*/ -/*! - \enum Qt::SizeHint - \since 4.4 - - This enum is used by QGraphicsLayoutItem::sizeHint() - - \value MinimumSize is used to specify the minimum size of a graphics layout item. - \value PreferredSize is used to specify the preferred size of a graphics layout item. - \value MaximumSize is used to specify the maximum size of a graphics layout item. - \value MinimumDescent is used to specify the minimum descent of a text string in a graphics layout item. - \omitvalue NSizeHints - - \sa QGraphicsLayoutItem::sizeHint() -*/ - -/*! - \enum Qt::SizeMode - \since 4.4 - - This enum is used by QPainter::drawRoundedRect() and QPainterPath::addRoundedRect() - functions to specify the radii of rectangle corners with respect to the dimensions - of the bounding rectangles specified. - - \value AbsoluteSize Specifies the size using absolute measurements. - \value RelativeSize Specifies the size relative to the bounding rectangle, - typically using percentage measurements. -*/ - -/*! - \enum Qt::WindowFrameSection - \since 4.4 - - This enum is used to describe parts of a window frame. It is returned by - QGraphicsWidget::windowFrameSectionAt() to describe what section of the window - frame is under the mouse. - - \value NoSection - \value LeftSection - \value TopLeftSection - \value TopSection - \value TopRightSection - \value RightSection - \value BottomRightSection - \value BottomSection - \value BottomLeftSection - \value TitleBarArea - - \sa QGraphicsWidget::windowFrameEvent() - \sa QGraphicsWidget::paintWindowFrame() - \sa QGraphicsWidget::windowFrameSectionAt() - -*/ - -/*! - \enum Qt::TileRule - \since 4.6 - - This enum describes how to repeat or stretch the parts of an image - when drawing. - - \value Stretch Scale the image to fit to the available area. - - \value Repeat Tile the image until there is no more space. May crop - the last image. - - \value Round Like Repeat, but scales the images down to ensure that - the last image is not cropped. -*/ - -/*! - \enum Qt::Initialization - \internal -*/ - -/*! - \enum Qt::GestureState - \since 4.6 - - This enum type describes the state of a gesture. - - \value NoGesture Initial state - \value GestureStarted A continuous gesture has started. - \value GestureUpdated A gesture continues. - \value GestureFinished A gesture has finished. - - \sa QGesture -*/ diff --git a/doc/src/classes/qpagesetupdialog.qdoc b/doc/src/classes/qpagesetupdialog.qdoc deleted file mode 100644 index 5715fa8..0000000 --- a/doc/src/classes/qpagesetupdialog.qdoc +++ /dev/null @@ -1,84 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QPageSetupDialog - - \brief The QPageSetupDialog class provides a configuration dialog - for the page-related options on a printer. - - On Windows and Mac OS X the page setup dialog is implemented using - the native page setup dialogs. - - Note that on Windows and Mac OS X custom paper sizes won't be - reflected in the native page setup dialogs. Additionally, custom - page margins set on a QPrinter won't show in the native Mac OS X - page setup dialog. - - \sa QPrinter, QPrintDialog -*/ - - -/*! - \fn QPageSetupDialog::QPageSetupDialog(QPrinter *printer, QWidget *parent) - - Constructs a page setup dialog that configures \a printer with \a - parent as the parent widget. -*/ - -/*! - \since 4.5 - - \fn QPageSetupDialog::QPageSetupDialog(QWidget *parent) - - Constructs a page setup dialog that configures a default-constructed - QPrinter with \a parent as the parent widget. - - \sa printer() -*/ - -/*! - \fn QPrinter *QPageSetupDialog::printer() - - Returns the printer that was passed to the QPageSetupDialog - constructor. -*/ - diff --git a/doc/src/classes/qpaintdevice.qdoc b/doc/src/classes/qpaintdevice.qdoc deleted file mode 100644 index 6e7c561..0000000 --- a/doc/src/classes/qpaintdevice.qdoc +++ /dev/null @@ -1,289 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QPaintDevice - \brief The QPaintDevice class is the base class of objects that - can be painted. - - \ingroup multimedia - - A paint device is an abstraction of a two-dimensional space that - can be drawn using a QPainter. Its default coordinate system has - its origin located at the top-left position. X increases to the - right and Y increases downwards. The unit is one pixel. - - The drawing capabilities of QPaintDevice are currently implemented - by the QWidget, QImage, QPixmap, QGLPixelBuffer, QPicture, and - QPrinter subclasses. - - To implement support for a new backend, you must derive from - QPaintDevice and reimplement the virtual paintEngine() function to - tell QPainter which paint engine should be used to draw on this - particular device. Note that you also must create a corresponding - paint engine to be able to draw on the device, i.e derive from - QPaintEngine and reimplement its virtual functions. - - \warning Qt requires that a QApplication object exists before - any paint devices can be created. Paint devices access window - system resources, and these resources are not initialized before - an application object is created. - - The QPaintDevice class provides several functions returning the - various device metrics: The depth() function returns its bit depth - (number of bit planes). The height() function returns its height - in default coordinate system units (e.g. pixels for QPixmap and - QWidget) while heightMM() returns the height of the device in - millimeters. Similiarily, the width() and widthMM() functions - return the width of the device in default coordinate system units - and in millimeters, respectively. Alternatively, the protected - metric() function can be used to retrieve the metric information - by specifying the desired PaintDeviceMetric as argument. - - The logicalDpiX() and logicalDpiY() functions return the - horizontal and vertical resolution of the device in dots per - inch. The physicalDpiX() and physicalDpiY() functions also return - the resolution of the device in dots per inch, but note that if - the logical and vertical resolution differ, the corresponding - QPaintEngine must handle the mapping. Finally, the numColors() - function returns the number of different colors available for the - paint device. - - \sa QPaintEngine, QPainter, {The Coordinate System}, {The Paint - System} -*/ - -/*! - \enum QPaintDevice::PaintDeviceMetric - - Describes the various metrics of a paint device. - - \value PdmWidth The width of the paint device in default - coordinate system units (e.g. pixels for QPixmap and QWidget). See - also width(). - - \value PdmHeight The height of the paint device in default - coordinate system units (e.g. pixels for QPixmap and QWidget). See - also height(). - - \value PdmWidthMM The width of the paint device in millimeters. See - also widthMM(). - - \value PdmHeightMM The height of the paint device in millimeters. See - also heightMM(). - - \value PdmNumColors The number of different colors available for - the paint device. See also numColors(). - - \value PdmDepth The bit depth (number of bit planes) of the paint - device. See also depth(). - - \value PdmDpiX The horizontal resolution of the device in dots per - inch. See also logicalDpiX(). - - \value PdmDpiY The vertical resolution of the device in dots per inch. See - also logicalDpiY(). - - \value PdmPhysicalDpiX The horizontal resolution of the device in - dots per inch. See also physicalDpiX(). - - \value PdmPhysicalDpiY The vertical resolution of the device in - dots per inch. See also physicalDpiY(). - - \sa metric() -*/ - -/*! - \fn QPaintDevice::QPaintDevice() - - Constructs a paint device. This constructor can be invoked only from - subclasses of QPaintDevice. -*/ - -/*! - \fn QPaintDevice::~QPaintDevice() - - Destroys the paint device and frees window system resources. -*/ - -/*! - \fn int QPaintDevice::devType() const - - \internal - - Returns the device type identifier, which is QInternal::Widget - if the device is a QWidget, QInternal::Pixmap if it's a - QPixmap, QInternal::Printer if it's a QPrinter, - QInternal::Picture if it's a QPicture, or - QInternal::UnknownDevice in other cases. -*/ - -/*! - \fn bool QPaintDevice::paintingActive() const - - Returns true if the device is currently being painted on, i.e. someone has - called QPainter::begin() but not yet called QPainter::end() for - this device; otherwise returns false. - - \sa QPainter::isActive() -*/ - -/*! - \fn QPaintEngine *QPaintDevice::paintEngine() const - - Returns a pointer to the paint engine used for drawing on the - device. -*/ - -/*! - \fn int QPaintDevice::metric(PaintDeviceMetric metric) const - - Returns the metric information for the given paint device \a metric. - - \sa PaintDeviceMetric -*/ - -/*! - \fn int QPaintDevice::width() const - - Returns the width of the paint device in default coordinate system - units (e.g. pixels for QPixmap and QWidget). - - \sa widthMM() -*/ - -/*! - \fn int QPaintDevice::height() const - - Returns the height of the paint device in default coordinate - system units (e.g. pixels for QPixmap and QWidget). - - \sa heightMM() -*/ - -/*! - \fn int QPaintDevice::widthMM() const - - Returns the width of the paint device in millimeters. Due to platform - limitations it may not be possible to use this function to determine - the actual physical size of a widget on the screen. - - \sa width() -*/ - -/*! - \fn int QPaintDevice::heightMM() const - - Returns the height of the paint device in millimeters. Due to platform - limitations it may not be possible to use this function to determine - the actual physical size of a widget on the screen. - - \sa height() -*/ - -/*! - \fn int QPaintDevice::numColors() const - - Returns the number of different colors available for the paint - device. Since this value is an int, it will not be sufficient to represent - the number of colors on 32 bit displays, in this case INT_MAX is - returned instead. -*/ - -/*! - \fn int QPaintDevice::depth() const - - Returns the bit depth (number of bit planes) of the paint device. -*/ - -/*! - \fn int QPaintDevice::logicalDpiX() const - - Returns the horizontal resolution of the device in dots per inch, - which is used when computing font sizes. For X11, this is usually - the same as could be computed from widthMM(). - - Note that if the logicalDpiX() doesn't equal the physicalDpiX(), - the corresponding QPaintEngine must handle the resolution mapping. - - \sa logicalDpiY(), physicalDpiX() -*/ - -/*! - \fn int QPaintDevice::logicalDpiY() const - - Returns the vertical resolution of the device in dots per inch, - which is used when computing font sizes. For X11, this is usually - the same as could be computed from heightMM(). - - Note that if the logicalDpiY() doesn't equal the physicalDpiY(), - the corresponding QPaintEngine must handle the resolution mapping. - - \sa logicalDpiX(), physicalDpiY() -*/ - -/*! - \fn int QPaintDevice::physicalDpiX() const - - Returns the horizontal resolution of the device in dots per inch. - For example, when printing, this resolution refers to the physical - printer's resolution. The logical DPI on the other hand, refers to - the resolution used by the actual paint engine. - - Note that if the physicalDpiX() doesn't equal the logicalDpiX(), - the corresponding QPaintEngine must handle the resolution mapping. - - \sa physicalDpiY(), logicalDpiX() -*/ - -/*! - \fn int QPaintDevice::physicalDpiY() const - - Returns the horizontal resolution of the device in dots per inch. - For example, when printing, this resolution refers to the physical - printer's resolution. The logical DPI on the other hand, refers to - the resolution used by the actual paint engine. - - Note that if the physicalDpiY() doesn't equal the logicalDpiY(), - the corresponding QPaintEngine must handle the resolution mapping. - - \sa physicalDpiX(), logicalDpiY() -*/ diff --git a/doc/src/classes/qpair.qdoc b/doc/src/classes/qpair.qdoc deleted file mode 100644 index 9c8ac89..0000000 --- a/doc/src/classes/qpair.qdoc +++ /dev/null @@ -1,229 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QPair - \brief The QPair class is a template class that stores a pair of items. - - \ingroup tools - - QPair\<T1, T2\> can be used in your application if the STL \c - pair type is not available. It stores one value of type T1 and - one value of type T2. It can be used as a return value for a - function that needs to return two values, or as the value type of - a \l{generic container}. - - Here's an example of a QPair that stores one QString and one \c - double value: - - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 0 - - The components are accessible as public data members called \l - first and \l second. For example: - - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 1 - - QPair's template data types (T1 and T2) must be \l{assignable - data types}. You cannot, for example, store a QWidget as a value; - instead, store a QWidget *. A few functions have additional - requirements; these requirements are documented on a per-function - basis. - - \sa {Generic Containers} -*/ - -/*! \typedef QPair::first_type - - The type of the first element in the pair (T1). - - \sa first -*/ - -/*! \typedef QPair::second_type - - The type of the second element in the pair (T2). - - \sa second -*/ - -/*! \variable QPair::first - - The first element in the pair. -*/ - -/*! \variable QPair::second - - The second element in the pair. -*/ - -/*! \fn QPair::QPair() - - Constructs an empty pair. The \c first and \c second elements are - initialized with \l{default-constructed values}. -*/ - -/*! - \fn QPair::QPair(const T1 &value1, const T2 &value2) - - Constructs a pair and initializes the \c first element with \a - value1 and the \c second element with \a value2. - - \sa qMakePair() -*/ - -/*! - \fn QPair<T1, T2> &QPair::operator=(const QPair<T1, T2> &other) - - Assigns \a other to this pair. -*/ - -/*! \fn bool operator==(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) - - \relates QPair - - Returns true if \a p1 is equal to \a p2; otherwise returns false. - Two pairs compare equal if their \c first data members compare - equal and if their \c second data members compare equal. - - This function requires the T1 and T2 types to have an - implementation of \c operator==(). -*/ - -/*! \fn bool operator!=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) - - \relates QPair - - Returns true if \a p1 is not equal to \a p2; otherwise returns - false. Two pairs compare as not equal if their \c first data - members are not equal or if their \c second data members are not - equal. - - This function requires the T1 and T2 types to have an - implementation of \c operator==(). -*/ - -/*! \fn bool operator<(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) - - \relates QPair - - Returns true if \a p1 is less than \a p2; otherwise returns - false. The comparison is done on the \c first members of \a p1 - and \a p2; if they compare equal, the \c second members are - compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! \fn bool operator>(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) - - \relates QPair - - Returns true if \a p1 is greater than \a p2; otherwise returns - false. The comparison is done on the \c first members of \a p1 - and \a p2; if they compare equal, the \c second members are - compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! \fn bool operator<=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) - - \relates QPair - - Returns true if \a p1 is less than or equal to \a p2; otherwise - returns false. The comparison is done on the \c first members of - \a p1 and \a p2; if they compare equal, the \c second members are - compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! \fn bool operator>=(const QPair<T1, T2> &p1, const QPair<T1, T2> &p2) - - \relates QPair - - Returns true if \a p1 is greater than or equal to \a p2; - otherwise returns false. The comparison is done on the \c first - members of \a p1 and \a p2; if they compare equal, the \c second - members are compared to break the tie. - - This function requires the T1 and T2 types to have an - implementation of \c operator<(). -*/ - -/*! - \fn QPair<T1, T2> qMakePair(const T1 &value1, const T2 &value2) - - \relates QPair - - Returns a QPair\<T1, T2\> that contains \a value1 and \a value2. - Example: - - \snippet doc/src/snippets/code/doc_src_qpair.qdoc 2 - - This is equivalent to QPair<T1, T2>(\a value1, \a value2), but - usually requires less typing. -*/ - -/*! \fn QDataStream &operator>>(QDataStream &in, QPair<T1, T2> &pair) - - \relates QPair - - Reads a pair from stream \a in into \a pair. - - This function requires the T1 and T2 types to implement \c operator>>(). - - \sa {Format of the QDataStream operators} -*/ - -/*! \fn QDataStream &operator<<(QDataStream &out, const QPair<T1, T2> &pair) - - \relates QPair - - Writes the pair \a pair to stream \a out. - - This function requires the T1 and T2 types to implement \c operator<<(). - - \sa {Format of the QDataStream operators} -*/ diff --git a/doc/src/classes/qplugin.qdoc b/doc/src/classes/qplugin.qdoc deleted file mode 100644 index 3b8f1b0..0000000 --- a/doc/src/classes/qplugin.qdoc +++ /dev/null @@ -1,135 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \headerfile <QtPlugin> - \title Macros for Defining Plugins - - \brief The <QtPlugin> header files defines macros for defining plugins. - - \sa {How to Create Qt Plugins} -*/ - -/*! - \macro Q_DECLARE_INTERFACE(ClassName, Identifier) - \relates <QtPlugin> - - This macro associates the given \a Identifier (a string literal) - to the interface class called \a ClassName. The \a Identifier must - be unique. For example: - - \snippet examples/tools/plugandpaint/interfaces.h 3 - - This macro is normally used right after the class definition for - \a ClassName, in a header file. See the - \l{tools/plugandpaint}{Plug & Paint} example for details. - - If you want to use Q_DECLARE_INTERFACE with interface classes - declared in a namespace then you have to make sure the Q_DECLARE_INTERFACE - is not inside a namespace though. For example: - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 0 - - \sa Q_INTERFACES(), Q_EXPORT_PLUGIN2(), {How to Create Qt Plugins} -*/ - -/*! - \macro Q_EXPORT_PLUGIN(ClassName) - \relates <QtPlugin> - \obsolete - - Use Q_EXPORT_PLUGIN2() instead. This macro is equivalent to - Q_EXPORT_PLUGIN2(\a ClassName, \a ClassName). -*/ - -/*! - \macro Q_EXPORT_PLUGIN2(PluginName, ClassName) - \relates <QtPlugin> - \since 4.1 - \keyword Q_EXPORT_PLUGIN2 - - This macro exports the plugin class \a ClassName for the plugin specified - by \a PluginName. The value of \a PluginName should correspond to the - \l{qmake Variable Reference#TARGET}{TARGET} specified in the plugin's - project file. - - There should be exactly one occurrence of this macro in the source code - for a Qt plugin, and it should be used where the implementation is written - rather than in a header file. - - Example: - - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 1 - - See the \l{tools/plugandpaint}{Plug & Paint} example for details. - - \sa Q_DECLARE_INTERFACE(), {How to Create Qt Plugins} -*/ - -/*! - \macro Q_IMPORT_PLUGIN(PluginName) - \relates <QtPlugin> - - This macro imports the plugin named \a PluginName, corresponding - to the \l{qmake Variable Reference#TARGET}{TARGET} specified in the - plugin's project file. - - Inserting this macro into your application's source code will allow - you to make use of a static plugin. - - Example: - - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 2 - - Static plugins must also be included by the linker when your - application is built. For Qt's predefined plugins, - you can use the \c QTPLUGIN to add - the required plugins to your build. For example: - - \snippet doc/src/snippets/code/doc_src_qplugin.qdoc 3 - - \sa {Static Plugins}, {How to Create Qt Plugins}, {Using qmake} -*/ - -/*! - \macro Q_EXPORT_STATIC_PLUGIN(ClassName) - \relates <QtPlugin> - \internal -*/ diff --git a/doc/src/classes/qprintdialog.qdoc b/doc/src/classes/qprintdialog.qdoc deleted file mode 100644 index b52edff..0000000 --- a/doc/src/classes/qprintdialog.qdoc +++ /dev/null @@ -1,72 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -#ifdef QT3_SUPPORT -/*! - \fn QPrinter *QPrintDialog::printer() const - - Returns a pointer to the printer this dialog configures, or 0 if - this dialog does not operate on any printer. - - This function is available for Unix platforms only. -*/ - -/*! - \fn void QPrintDialog::setPrinter(QPrinter *printer, bool pickupSettings) - - Sets this dialog to configure printer \a printer, or no printer if \a printer - is null. If \a pickupSettings is true, the dialog reads most of - its settings from \a printer. If \a pickupSettings is false (the - default) the dialog keeps its old settings. - - This function is available for Unix platforms only. -*/ - -/*! - \fn void QPrintDialog::addButton(QPushButton *button) - - Adds the \a button to the layout of the print dialog. The added - buttons are arranged from the left to the right below the - last groupbox of the printdialog. - - This function is available for Unix platforms only. -*/ -#endif diff --git a/doc/src/classes/qprinterinfo.qdoc b/doc/src/classes/qprinterinfo.qdoc deleted file mode 100644 index 7507e8a..0000000 --- a/doc/src/classes/qprinterinfo.qdoc +++ /dev/null @@ -1,137 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QPrinterInfo - - \brief The QPrinterInfo class gives access to information about - existing printers. - - Use the static functions to generate a list of QPrinterInfo - objects. Each QPrinterInfo object in the list represents a single - printer and can be queried for name, supported paper sizes, and - whether or not it is the default printer. - - \since 4.4 -*/ - -/*! - \fn QList<QPrinterInfo> QPrinterInfo::availablePrinters() - - Returns a list of available printers on the system. -*/ - -/*! - \fn QPrinterInfo QPrinterInfo::defaultPrinter() - - Returns the default printer on the system. - - The return value should be checked using isNull() before being - used, in case there is no default printer. - - \sa isNull() -*/ - -/*! - \fn QPrinterInfo::QPrinterInfo() - - Constructs an empty QPrinterInfo object. - - \sa isNull() -*/ - -/*! - \fn QPrinterInfo::QPrinterInfo(const QPrinterInfo& src) - - Constructs a copy of \a src. -*/ - -/*! - \fn QPrinterInfo::QPrinterInfo(const QPrinter& printer) - - Constructs a QPrinterInfo object from \a printer. -*/ - -/*! - \fn QPrinterInfo::~QPrinterInfo() - - Destroys the QPrinterInfo object. References to the values in the - object become invalid. -*/ - -/*! - \fn QPrinterInfo& QPrinterInfo::operator=(const QPrinterInfo& src) - - Sets the QPrinterInfo object to be equal to \a src. -*/ - -/*! - \fn QString QPrinterInfo::printerName() const - - Returns the name of the printer. - - \sa QPrinter::setPrinterName() -*/ - -/*! - \fn bool QPrinterInfo::isNull() const - - Returns whether this QPrinterInfo object holds a printer definition. - - An empty QPrinterInfo object could result for example from calling - defaultPrinter() when there are no printers on the system. -*/ - -/*! - \fn bool QPrinterInfo::isDefault() const - - Returns whether this printer is the default printer. -*/ - -/*! - \fn QList< QPrinter::PaperSize> QPrinterInfo::supportedPaperSizes() const - \since 4.4 - - Returns a list of supported paper sizes by the printer. - - Not all printer drivers support this query, so the list may be empty. - On Mac OS X 10.3, this function always returns an empty list. -*/ diff --git a/doc/src/classes/qset.qdoc b/doc/src/classes/qset.qdoc deleted file mode 100644 index 8409e13..0000000 --- a/doc/src/classes/qset.qdoc +++ /dev/null @@ -1,953 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QSet - \brief The QSet class is a template class that provides a hash-table-based set. - - \ingroup tools - \ingroup shared - \reentrant - \mainclass - - QSet<T> is one of Qt's generic \l{container classes}. It stores - values in an unspecified order and provides very fast lookup of - the values. Internally, QSet<T> is implemented as a QHash. - - Here's an example QSet with QString values: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 0 - - To insert a value into the set, use insert(): - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 1 - - Another way to insert items into the set is to use operator<<(): - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 2 - - To test whether an item belongs to the set or not, use contains(): - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 3 - - If you want to navigate through all the values stored in a QSet, - you can use an iterator. QSet supports both \l{Java-style - iterators} (QSetIterator and QMutableSetIterator) and \l{STL-style - iterators} (QSet::iterator and QSet::const_iterator). Here's how - to iterate over a QSet<QWidget *> using a Java-style iterator: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 4 - - Here's the same code, but using an STL-style iterator: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 5 - - QSet is unordered, so an iterator's sequence cannot be assumed to - be predictable. If ordering by key is required, use a QMap. - - To navigate through a QSet, you can also use \l{foreach}: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 6 - - Items can be removed from the set using remove(). There is also a - clear() function that removes all items. - - QSet's value data type must be an \l{assignable data type}. You - cannot, for example, store a QWidget as a value; instead, store a - QWidget *. In addition, the type must provide \c operator==(), and - there must also be a global qHash() function that returns a hash - value for an argument of the key's type. See the QHash - documentation for a list of types supported by qHash(). - - Internally, QSet uses a hash table to perform lookups. The hash - table automatically grows and shrinks to provide fast lookups - without wasting memory. You can still control the size of the hash - table by calling reserve(), if you already know approximately how - many elements the QSet will contain, but this isn't necessary to - obtain good performance. You can also call capacity() to retrieve - the hash table's size. - - \sa QSetIterator, QMutableSetIterator, QHash, QMap -*/ - -/*! - \fn QSet::QSet() - - Constructs an empty set. - - \sa clear() -*/ - -/*! - \fn QSet::QSet(const QSet<T> &other) - - Constructs a copy of \a other. - - This operation occurs in \l{constant time}, because QSet is - \l{implicitly shared}. This makes returning a QSet from a - function very fast. If a shared instance is modified, it will be - copied (copy-on-write), and this takes \l{linear time}. - - \sa operator=() -*/ - -/*! - \fn QSet<T> &QSet::operator=(const QSet<T> &other) - - Assigns the \a other set to this set and returns a reference to - this set. -*/ - -/*! - \fn bool QSet::operator==(const QSet<T> &other) const - - Returns true if the \a other set is equal to this set; otherwise - returns false. - - Two sets are considered equal if they contain the same elements. - - This function requires the value type to implement \c operator==(). - - \sa operator!=() -*/ - -/*! - \fn bool QSet::operator!=(const QSet<T> &other) const - - Returns true if the \a other set is not equal to this set; otherwise - returns false. - - Two sets are considered equal if they contain the same elements. - - This function requires the value type to implement \c operator==(). - - \sa operator==() -*/ - -/*! - \fn int QSet::size() const - - Returns the number of items in the set. - - \sa isEmpty(), count() -*/ - -/*! - \fn bool QSet::isEmpty() const - - Returns true if the set contains no elements; otherwise returns - false. - - \sa size() -*/ - -/*! - \fn int QSet::capacity() const - - Returns the number of buckets in the set's internal hash - table. - - The sole purpose of this function is to provide a means of fine - tuning QSet's memory usage. In general, you will rarely ever need - to call this function. If you want to know how many items are in - the set, call size(). - - \sa reserve(), squeeze() -*/ - -/*! \fn void QSet::reserve(int size) - - Ensures that the set's internal hash table consists of at - least \a size buckets. - - This function is useful for code that needs to build a huge set - and wants to avoid repeated reallocation. For example: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 7 - - Ideally, \a size should be slightly more than the maximum number - of elements expected in the set. \a size doesn't have to be prime, - because QSet will use a prime number internally anyway. If \a size - is an underestimate, the worst that will happen is that the QSet - will be a bit slower. - - In general, you will rarely ever need to call this function. - QSet's internal hash table automatically shrinks or grows to - provide good performance without wasting too much memory. - - \sa squeeze(), capacity() -*/ - -/*! - \fn void QSet::squeeze() - - Reduces the size of the set's internal hash table to save - memory. - - The sole purpose of this function is to provide a means of fine - tuning QSet's memory usage. In general, you will rarely ever - need to call this function. - - \sa reserve(), capacity() -*/ - -/*! - \fn void QSet::detach() - - \internal - - Detaches this set from any other sets with which it may share - data. - - \sa isDetached() -*/ - -/*! \fn bool QSet::isDetached() const - - \internal - - Returns true if the set's internal data isn't shared with any - other set object; otherwise returns false. - - \sa detach() -*/ - -/*! - \fn void QSet::setSharable(bool sharable) - \internal -*/ - -/*! - \fn void QSet::clear() - - Removes all elements from the set. - - \sa remove() -*/ - -/*! - \fn bool QSet::remove(const T &value) - - Removes any occurrence of item \a value from the set. Returns - true if an item was actually removed; otherwise returns false. - - \sa contains(), insert() -*/ - -/*! - \fn QSet::iterator QSet::erase(iterator pos) - \since 4.2 - - Removes the item at the iterator position \a pos from the set, and - returns an iterator positioned at the next item in the set. - - Unlike remove(), this function never causes QSet to rehash its - internal data structure. This means that it can safely be called - while iterating, and won't affect the order of items in the set. - - \sa remove(), find() -*/ - -/*! \fn QSet::const_iterator QSet::find(const T &value) const - \since 4.2 - - Returns a const iterator positioned at the item \a value in the - set. If the set contains no item \a value, the function returns - constEnd(). - - \sa constFind(), contains() -*/ - -/*! \fn QSet::iterator QSet::find(const T &value) - \since 4.2 - \overload - - Returns a non-const iterator positioned at the item \a value in - the set. If the set contains no item \a value, the function - returns end(). -*/ - -/*! \fn QSet::const_iterator QSet::constFind(const T &value) const - \since 4.2 - - Returns a const iterator positioned at the item \a value in the - set. If the set contains no item \a value, the function returns - constEnd(). - - \sa find(), contains() -*/ - -/*! - \fn bool QSet::contains(const T &value) const - - Returns true if the set contains item \a value; otherwise returns - false. - - \sa insert(), remove(), find() -*/ - -/*! - \fn bool QSet::contains(const QSet<T> &other) const - \since 4.6 - - Returns true if the set contains all items from the \a other set; - otherwise returns false. - - \sa insert(), remove(), find() -*/ - -/*! \fn QSet::const_iterator QSet::begin() const - - Returns a const \l{STL-style iterator} positioned at the first - item in the set. - - \sa constBegin(), end() -*/ - -/*! \fn QSet::iterator QSet::begin() - \since 4.2 - \overload - - Returns a non-const \l{STL-style iterator} positioned at the first - item in the set. -*/ - -/*! \fn QSet::const_iterator QSet::constBegin() const - - Returns a const \l{STL-style iterator} positioned at the first - item in the set. - - \sa begin(), constEnd() -*/ - -/*! \fn QSet::const_iterator QSet::end() const - - Returns a const \l{STL-style iterator} positioned at the imaginary - item after the last item in the set. - - \sa constEnd(), begin() -*/ - -/*! \fn QSet::iterator QSet::end() - \since 4.2 - \overload - - Returns a non-const \l{STL-style iterator} pointing to the - imaginary item after the last item in the set. -*/ - -/*! \fn QSet::const_iterator QSet::constEnd() const - - Returns a const \l{STL-style iterator} pointing to the imaginary - item after the last item in the set. - - \sa constBegin(), end() -*/ - -/*! - \typedef QSet::Iterator - \since 4.2 - - Qt-style synonym for QSet::iterator. -*/ - -/*! - \typedef QSet::ConstIterator - - Qt-style synonym for QSet::const_iterator. -*/ - -/*! - \typedef QSet::const_pointer - - Typedef for const T *. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::const_reference - - Typedef for const T &. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::difference_type - - Typedef for const ptrdiff_t. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::key_type - - Typedef for T. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::pointer - - Typedef for T *. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::reference - - Typedef for T &. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::size_type - - Typedef for int. Provided for STL compatibility. -*/ - -/*! - \typedef QSet::value_type - - Typedef for T. Provided for STL compatibility. -*/ - -/*! - \fn QSet::const_iterator QSet::insert(const T &value) - - Inserts item \a value into the set, if \a value isn't already - in the set, and returns an iterator pointing at the inserted - item. - - \sa operator<<(), remove(), contains() -*/ - -/*! - \fn QSet<T> &QSet::unite(const QSet<T> &other) - - Each item in the \a other set that isn't already in this set is - inserted into this set. A reference to this set is returned. - - \sa operator|=(), intersect(), subtract() -*/ - -/*! - \fn QSet<T> &QSet::intersect(const QSet<T> &other) - - Removes all items from this set that are not contained in the - \a other set. A reference to this set is returned. - - \sa operator&=(), unite(), subtract() -*/ - -/*! - \fn QSet<T> &QSet::subtract(const QSet<T> &other) - - Removes all items from this set that are contained in the - \a other set. Returns a reference to this set. - - \sa operator-=(), unite(), intersect() -*/ - -/*! - \fn bool QSet::empty() const - - Returns true if the set is empty. This function is provided - for STL compatibility. It is equivalent to isEmpty(). -*/ - -/*! - \fn bool QSet::count() const - - Same as size(). -*/ - -/*! - \fn QSet<T> &QSet::operator<<(const T &value) - \fn QSet<T> &QSet::operator+=(const T &value) - \fn QSet<T> &QSet::operator|=(const T &value) - - Inserts a new item \a value and returns a reference to the set. - If \a value already exists in the set, the set is left unchanged. - - \sa insert() -*/ - -/*! - \fn QSet<T> &QSet::operator-=(const T &value) - - Removes the occurrence of item \a value from the set, if - it is found, and returns a reference to the set. If the - \a value is not contained the set, nothing is removed. - - \sa remove() -*/ - -/*! - \fn QSet<T> &QSet::operator|=(const QSet<T> &other) - \fn QSet<T> &QSet::operator+=(const QSet<T> &other) - - Same as unite(\a other). - - \sa operator|(), operator&=(), operator-=() -*/ - -/*! - \fn QSet<T> &QSet::operator&=(const QSet<T> &other) - - Same as intersect(\a other). - - \sa operator&(), operator|=(), operator-=() -*/ - -/*! - \fn QSet<T> &QSet::operator&=(const T &value) - - \overload - - Same as intersect(\e{other}), if we consider \e{other} to be a set - that contains the singleton \a value. -*/ - - -/*! - \fn QSet<T> &QSet::operator-=(const QSet<T> &other) - - Same as subtract(\a{other}). - - \sa operator-(), operator|=(), operator&=() -*/ - -/*! - \fn QSet<T> QSet::operator|(const QSet<T> &other) const - \fn QSet<T> QSet::operator+(const QSet<T> &other) const - - Returns a new QSet that is the union of this set and the - \a other set. - - \sa unite(), operator|=(), operator&(), operator-() -*/ - -/*! - \fn QSet<T> QSet::operator&(const QSet<T> &other) const - - Returns a new QSet that is the intersection of this set and the - \a other set. - - \sa intersect(), operator&=(), operator|(), operator-() -*/ - -/*! - \fn QSet<T> QSet::operator-(const QSet<T> &other) const - - Returns a new QSet that is the set difference of this set and - the \a other set, i.e., this set - \a other set. - - \sa subtract(), operator-=(), operator|(), operator&() -*/ - -/*! - \fn QSet<T> QSet::operator-(const QSet<T> &other) - \fn QSet<T> QSet::operator|(const QSet<T> &other) - \fn QSet<T> QSet::operator+(const QSet<T> &other) - \fn QSet<T> QSet::operator&(const QSet<T> &other) - \internal - - These will go away in Qt 5. -*/ - -/*! - \class QSet::iterator - \since 4.2 - \brief The QSet::iterator class provides an STL-style non-const iterator for QSet. - - QSet features both \l{STL-style iterators} and - \l{Java-style iterators}. The STL-style iterators are more - low-level and more cumbersome to use; on the other hand, they are - slightly faster and, for developers who already know STL, have - the advantage of familiarity. - - QSet<T>::iterator allows you to iterate over a QSet and to remove - items (using QSet::erase()) while you iterate. (QSet doesn't let - you \e modify a value through an iterator, because that - would potentially require moving the value in the internal hash - table used by QSet.) If you want to iterate over a const QSet, - you should use QSet::const_iterator. It is generally good - practice to use QSet::const_iterator on a non-const QSet as well, - unless you need to change the QSet through the iterator. Const - iterators are slightly faster, and can improve code readability. - - QSet\<T\>::iterator allows you to iterate over a QSet\<T\> and - modify it as you go (using QSet::erase()). However, - - The default QSet::iterator constructor creates an uninitialized - iterator. You must initialize it using a function like - QSet::begin(), QSet::end(), or QSet::insert() before you can - start iterating. Here's a typical loop that prints all the items - stored in a set: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 8 - - Here's a loop that removes certain items (all those that start - with 'J') from a set while iterating: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 9 - - STL-style iterators can be used as arguments to \l{generic - algorithms}. For example, here's how to find an item in the set - using the qFind() algorithm: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 10 - - Multiple iterators can be used on the same set. However, you may - not attempt to modify the container while iterating on it. - - \sa QSet::const_iterator, QMutableSetIterator -*/ - -/*! - \class QSet::const_iterator - \brief The QSet::const_iterator class provides an STL-style const iterator for QSet. - \since 4.2 - - QSet features both \l{STL-style iterators} and - \l{Java-style iterators}. The STL-style iterators are more - low-level and more cumbersome to use; on the other hand, they are - slightly faster and, for developers who already know STL, have - the advantage of familiarity. - - QSet\<Key, T\>::const_iterator allows you to iterate over a QSet. - If you want to modify the QSet as you iterate over it, you must - use QSet::iterator instead. It is generally good practice to use - QSet::const_iterator on a non-const QSet as well, unless you need - to change the QSet through the iterator. Const iterators are - slightly faster, and can improve code readability. - - The default QSet::const_iterator constructor creates an - uninitialized iterator. You must initialize it using a function - like QSet::begin(), QSet::end(), or QSet::insert() before you can - start iterating. Here's a typical loop that prints all the items - stored in a set: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 11 - - STL-style iterators can be used as arguments to \l{generic - algorithms}. For example, here's how to find an item in the set - using the qFind() algorithm: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 12 - - Multiple iterators can be used on the same set. However, you may - not attempt to modify the container while iterating on it. - - \sa QSet::iterator, QSetIterator -*/ - -/*! - \fn QSet::iterator::iterator() - \fn QSet::const_iterator::const_iterator() - - Constructs an uninitialized iterator. - - Functions like operator*() and operator++() should not be called - on an uninitialized iterator. Use operator=() to assign a value - to it before using it. - - \sa QSet::begin(), QSet::end() -*/ - -/*! - \fn QSet::iterator::iterator(typename Hash::iterator i) - \fn QSet::const_iterator::const_iterator(typename Hash::const_iterator i) - - \internal -*/ - -/*! - \typedef QSet::iterator::iterator_category - \typedef QSet::const_iterator::iterator_category - - Synonyms for \e {std::bidirectional_iterator_tag} indicating - these iterators are bidirectional iterators. - */ - -/*! - \typedef QSet::iterator::difference_type - \typedef QSet::const_iterator::difference_type - - \internal -*/ - -/*! - \typedef QSet::iterator::value_type - \typedef QSet::const_iterator::value_type - - \internal -*/ - -/*! - \typedef QSet::iterator::pointer - \typedef QSet::const_iterator::pointer - - \internal -*/ - -/*! - \typedef QSet::iterator::reference - \typedef QSet::const_iterator::reference - - \internal -*/ - -/*! - \fn QSet::iterator::iterator(const iterator &other) - \fn QSet::const_iterator::const_iterator(const const_iterator &other) - - Constructs a copy of \a other. -*/ - -/*! - \fn QSet::const_iterator::const_iterator(const iterator &other) - \since 4.2 - \overload - - Constructs a copy of \a other. -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator=(const iterator &other) - \fn QSet::const_iterator &QSet::const_iterator::operator=(const const_iterator &other) - - Assigns \a other to this iterator. -*/ - -/*! - \fn const T &QSet::iterator::operator*() const - \fn const T &QSet::const_iterator::operator*() const - - Returns a reference to the current item. - - \sa operator->() -*/ - -/*! - \fn const T *QSet::iterator::operator->() const - \fn const T *QSet::const_iterator::operator->() const - - Returns a pointer to the current item. - - \sa operator*() -*/ - -/*! - \fn bool QSet::iterator::operator==(const iterator &other) const - \fn bool QSet::const_iterator::operator==(const const_iterator &other) const - - Returns true if \a other points to the same item as this - iterator; otherwise returns false. - - \sa operator!=() -*/ - -/*! - \fn bool QSet::iterator::operator==(const const_iterator &other) const - \fn bool QSet::iterator::operator!=(const const_iterator &other) const - - \overload -*/ - -/*! - \fn bool QSet::iterator::operator!=(const iterator &other) const - \fn bool QSet::const_iterator::operator!=(const const_iterator &other) const - - Returns true if \a other points to a different item than this - iterator; otherwise returns false. - - \sa operator==() -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator++() - \fn QSet::const_iterator &QSet::const_iterator::operator++() - - The prefix ++ operator (\c{++it}) advances the iterator to the - next item in the set and returns an iterator to the new current - item. - - Calling this function on QSet::constEnd() leads to - undefined results. - - \sa operator--() -*/ - -/*! - \fn QSet::iterator QSet::iterator::operator++(int) - \fn QSet::const_iterator QSet::const_iterator::operator++(int) - - \overload - - The postfix ++ operator (\c{it++}) advances the iterator to the - next item in the set and returns an iterator to the previously - current item. -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator--() - \fn QSet::const_iterator &QSet::const_iterator::operator--() - - The prefix -- operator (\c{--it}) makes the preceding item - current and returns an iterator to the new current item. - - Calling this function on QSet::begin() leads to undefined - results. - - \sa operator++() -*/ - -/*! - \fn QSet::iterator QSet::iterator::operator--(int) - \fn QSet::const_iterator QSet::const_iterator::operator--(int) - - \overload - - The postfix -- operator (\c{it--}) makes the preceding item - current and returns an iterator to the previously current item. -*/ - -/*! - \fn QSet::iterator QSet::iterator::operator+(int j) const - \fn QSet::const_iterator QSet::const_iterator::operator+(int j) const - - Returns an iterator to the item at \a j positions forward from - this iterator. (If \a j is negative, the iterator goes backward.) - - This operation can be slow for large \a j values. - - \sa operator-() -*/ - -/*! - \fn QSet::iterator QSet::iterator::operator-(int j) const - \fn QSet::const_iterator QSet::const_iterator::operator-(int j) const - - Returns an iterator to the item at \a j positions backward from - this iterator. (If \a j is negative, the iterator goes forward.) - - This operation can be slow for large \a j values. - - \sa operator+() -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator+=(int j) - \fn QSet::const_iterator &QSet::const_iterator::operator+=(int j) - - Advances the iterator by \a j items. (If \a j is negative, the - iterator goes backward.) - - This operation can be slow for large \a j values. - - \sa operator-=(), operator+() -*/ - -/*! - \fn QSet::iterator &QSet::iterator::operator-=(int j) - \fn QSet::const_iterator &QSet::const_iterator::operator-=(int j) - - Makes the iterator go back by \a j items. (If \a j is negative, - the iterator goes forward.) - - This operation can be slow for large \a j values. - - \sa operator+=(), operator-() -*/ - -/*! \fn QList<T> QSet<T>::toList() const - - Returns a new QList containing the elements in the set. The - order of the elements in the QList is undefined. - - Example: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 13 - - \sa fromList(), QList::fromSet(), qSort() -*/ - -/*! \fn QList<T> QSet<T>::values() const - - Returns a new QList containing the elements in the set. The - order of the elements in the QList is undefined. - - This is the same as toList(). - - \sa fromList(), QList::fromSet(), qSort() -*/ - - -/*! \fn QSet<T> QSet<T>::fromList(const QList<T> &list) - - Returns a new QSet object containing the data contained in \a - list. Since QSet doesn't allow duplicates, the resulting QSet - might be smaller than the \a list, because QList can contain - duplicates. - - Example: - - \snippet doc/src/snippets/code/doc_src_qset.qdoc 14 - - \sa toList(), QList::toSet() -*/ - -/*! - \fn QDataStream &operator<<(QDataStream &out, const QSet<T> &set) - \relates QSet - - Writes the \a set to stream \a out. - - This function requires the value type to implement \c operator<<(). - - \sa \link datastreamformat.html Format of the QDataStream operators \endlink -*/ - -/*! - \fn QDataStream &operator>>(QDataStream &in, QSet<T> &set) - \relates QSet - - Reads a set from stream \a in into \a set. - - This function requires the value type to implement \c operator>>(). - - \sa \link datastreamformat.html Format of the QDataStream operators \endlink -*/ diff --git a/doc/src/classes/qsignalspy.qdoc b/doc/src/classes/qsignalspy.qdoc deleted file mode 100644 index 02cb771..0000000 --- a/doc/src/classes/qsignalspy.qdoc +++ /dev/null @@ -1,98 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QSignalSpy - \inmodule QtTest - - \brief The QSignalSpy class enables introspection of signal emission. - - QSignalSpy can connect to any signal of any object and records its emission. - QSignalSpy itself is a list of QVariant lists. Each emission of the signal - will append one item to the list, containing the arguments of the signal. - - The following example records all signal emissions for the \c clicked() signal - of a QCheckBox: - - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 0 - - \c{spy.takeFirst()} returns the arguments for the first emitted signal, as a - list of QVariant objects. The \c clicked() signal has a single bool argument, - which is stored as the first entry in the list of arguments. - - The example below catches a signal from a custom object: - - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 1 - - \bold {Note:} Non-standard data types need to be registered, using - the qRegisterMetaType() function, before you can create a - QSignalSpy. For example: - - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 2 - - To retrieve the \c QModelIndex, you can use qvariant_cast: - - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 3 - */ - -/*! \fn QSignalSpy::QSignalSpy(QObject *object, const char *signal) - - Constructs a new QSignalSpy that listens for emissions of the \a signal - from the QObject \a object. Neither \a signal nor \a object can be null. - - Example: - \snippet doc/src/snippets/code/doc_src_qsignalspy.qdoc 4 -*/ - -/*! \fn QSignalSpy::isValid() const - - Returns true if the signal spy listens to a valid signal, otherwise false. -*/ - -/*! \fn QSignalSpy::signal() const - - Returns the normalized signal the spy is currently listening to. -*/ - -/*! \fn int QSignalSpy::qt_metacall(QMetaObject::Call call, int id, void **a) - \internal -*/ - diff --git a/doc/src/classes/qsizepolicy.qdoc b/doc/src/classes/qsizepolicy.qdoc deleted file mode 100644 index f7366c5..0000000 --- a/doc/src/classes/qsizepolicy.qdoc +++ /dev/null @@ -1,522 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QSizePolicy - \brief The QSizePolicy class is a layout attribute describing horizontal - and vertical resizing policy. - - \ingroup appearance - \ingroup geomanagement - - The size policy of a widget is an expression of its willingness to - be resized in various ways, and affects how the widget is treated - by the \l{Layout Management}{layout engine}. Each widget returns a - QSizePolicy that describes the horizontal and vertical resizing - policy it prefers when being laid out. You can change this for - a specific widget by changing its QWidget::sizePolicy property. - - QSizePolicy contains two independent QSizePolicy::Policy values - and two stretch factors; one describes the widgets's horizontal - size policy, and the other describes its vertical size policy. It - also contains a flag to indicate whether the height and width of - its preferred size are related. - - The horizontal and vertical policies can be set in the - constructor, and altered using the setHorizontalPolicy() and - setVerticalPolicy() functions. The stretch factors can be set - using the setHorizontalStretch() and setVerticalStretch() - functions. The flag indicating whether the widget's - \l{QWidget::sizeHint()}{sizeHint()} is width-dependent (such as a - menu bar or a word-wrapping label) can be set using the - setHeightForWidth() function. - - The current size policies and stretch factors be retrieved using - the horizontalPolicy(), verticalPolicy(), horizontalStretch() and - verticalStretch() functions. Alternatively, use the transpose() - function to swap the horizontal and vertical policies and - stretches. The hasHeightForWidth() function returns the current - status of the flag indicating the size hint dependencies. - - Use the expandingDirections() function to determine whether the - associated widget can make use of more space than its - \l{QWidget::sizeHint()}{sizeHint()} function indicates, as well as - find out in which directions it can expand. - - Finally, the QSizePolicy class provides operators comparing this - size policy to a given policy, as well as a QVariant operator - storing this QSizePolicy as a QVariant object. - - \sa QSize, QWidget::sizeHint(), QWidget::sizePolicy, - QLayoutItem::sizeHint() -*/ - -/*! - \enum QSizePolicy::PolicyFlag - - These flags are combined together to form the various \l{Policy} - values: - - \value GrowFlag The widget can grow beyond its size hint if necessary. - \value ExpandFlag The widget should get as much space as possible. - \value ShrinkFlag The widget can shrink below its size hint if necessary. - \value IgnoreFlag The widget's size hint is ignored. The widget will get - as much space as possible. - - \sa Policy -*/ - -/*! - \enum QSizePolicy::Policy - - This enum describes the various per-dimension sizing types used - when constructing a QSizePolicy. - - \value Fixed The QWidget::sizeHint() is the only acceptable - alternative, so the widget can never grow or shrink (e.g. the - vertical direction of a push button). - - \value Minimum The sizeHint() is minimal, and sufficient. The - widget can be expanded, but there is no advantage to it being - larger (e.g. the horizontal direction of a push button). - It cannot be smaller than the size provided by sizeHint(). - - \value Maximum The sizeHint() is a maximum. The widget can be - shrunk any amount without detriment if other widgets need the - space (e.g. a separator line). - It cannot be larger than the size provided by sizeHint(). - - \value Preferred The sizeHint() is best, but the widget can be - shrunk and still be useful. The widget can be expanded, but there - is no advantage to it being larger than sizeHint() (the default - QWidget policy). - - \value Expanding The sizeHint() is a sensible size, but the - widget can be shrunk and still be useful. The widget can make use - of extra space, so it should get as much space as possible (e.g. - the horizontal direction of a horizontal slider). - - \value MinimumExpanding The sizeHint() is minimal, and sufficient. - The widget can make use of extra space, so it should get as much - space as possible (e.g. the horizontal direction of a horizontal - slider). - - \value Ignored The sizeHint() is ignored. The widget will get as - much space as possible. - - \sa PolicyFlag, setHorizontalPolicy(), setVerticalPolicy() -*/ - -/*! - \fn QSizePolicy::QSizePolicy() - - Constructs a QSizePolicy object with \l Fixed as its horizontal - and vertical policies. - - The policies can be altered using the setHorizontalPolicy() and - setVerticalPolicy() functions. Use the setHeightForWidth() - function if the preferred height of the widget is dependent on the - width of the widget (for example, a QLabel with line wrapping). - - \sa setHorizontalStretch(), setVerticalStretch() -*/ - -/*! - \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical) - - Constructs a QSizePolicy object with the given \a horizontal and - \a vertical policies, and DefaultType as the control type. - - Use setHeightForWidth() if the preferred height of the widget is - dependent on the width of the widget (for example, a QLabel with - line wrapping). - - \sa setHorizontalStretch(), setVerticalStretch() -*/ - -/*! - \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, ControlType type) - \since 4.3 - - Constructs a QSizePolicy object with the given \a horizontal and - \a vertical policies, and the specified control \a type. - - Use setHeightForWidth() if the preferred height of the widget is - dependent on the width of the widget (for example, a QLabel with - line wrapping). - - \sa setHorizontalStretch(), setVerticalStretch(), controlType() -*/ - -/*! - \fn QSizePolicy::Policy QSizePolicy::horizontalPolicy() const - - Returns the horizontal component of the size policy. - - \sa setHorizontalPolicy(), verticalPolicy(), horizontalStretch() -*/ - -/*! - \fn QSizePolicy::Policy QSizePolicy::verticalPolicy() const - - Returns the vertical component of the size policy. - - \sa setVerticalPolicy(), horizontalPolicy(), verticalStretch() -*/ - -/*! - \fn void QSizePolicy::setHorizontalPolicy(Policy policy) - - Sets the horizontal component to the given \a policy. - - \sa horizontalPolicy(), setVerticalPolicy(), setHorizontalStretch() -*/ - -/*! - \fn void QSizePolicy::setVerticalPolicy(Policy policy) - - Sets the vertical component to the given \a policy. - - \sa verticalPolicy(), setHorizontalPolicy(), setVerticalStretch() -*/ - -/*! - \fn Qt::Orientations QSizePolicy::expandingDirections() const - - Returns whether a widget can make use of more space than the - QWidget::sizeHint() function indicates. - - A value of Qt::Horizontal or Qt::Vertical means that the widget - can grow horizontally or vertically (i.e., the horizontal or - vertical policy is \l Expanding or \l MinimumExpanding), whereas - Qt::Horizontal | Qt::Vertical means that it can grow in both - dimensions. - - \sa horizontalPolicy(), verticalPolicy() -*/ - -/*! - \fn ControlType QSizePolicy::controlType() const - \since 4.3 - - Returns the control type associated with the widget for which - this size policy applies. -*/ - -/*! - \fn void QSizePolicy::setControlType(ControlType type) - \since 4.3 - - Sets the control type associated with the widget for which this - size policy applies to \a type. - - The control type specifies the type of the widget for which this - size policy applies. It is used by some styles, notably - QMacStyle, to insert proper spacing between widgets. For example, - the Mac OS X Aqua guidelines specify that push buttons should be - separated by 12 pixels, whereas vertically stacked radio buttons - only require 6 pixels. - - \sa QStyle::layoutSpacing() -*/ - -/*! - \fn void QSizePolicy::setHeightForWidth(bool dependent) - - Sets the flag determining whether the widget's preferred height - depends on its width, to \a dependent. - - \sa hasHeightForWidth() -*/ - -/*! - \fn bool QSizePolicy::hasHeightForWidth() const - - Returns true if the widget's preferred height depends on its - width; otherwise returns false. - - \sa setHeightForWidth() -*/ - -/*! - \fn bool QSizePolicy::operator==(const QSizePolicy &other) const - - Returns true if this policy is equal to \a other; otherwise - returns false. - - \sa operator!=() -*/ - -/*! - \fn bool QSizePolicy::operator!=(const QSizePolicy &other) const - - Returns true if this policy is different from \a other; otherwise - returns false. - - \sa operator==() -*/ - -/*! - \fn int QSizePolicy::horizontalStretch() const - - Returns the horizontal stretch factor of the size policy. - - \sa setHorizontalStretch(), verticalStretch(), horizontalPolicy() -*/ - -/*! - \fn int QSizePolicy::verticalStretch() const - - Returns the vertical stretch factor of the size policy. - - \sa setVerticalStretch(), horizontalStretch(), verticalPolicy() -*/ - -/*! - \fn void QSizePolicy::setHorizontalStretch(uchar stretchFactor) - - Sets the horizontal stretch factor of the size policy to the given \a - stretchFactor. - - \sa horizontalStretch(), setVerticalStretch(), setHorizontalPolicy() -*/ - -/*! - \fn void QSizePolicy::setVerticalStretch(uchar stretchFactor) - - Sets the vertical stretch factor of the size policy to the given - \a stretchFactor. - - \sa verticalStretch(), setHorizontalStretch(), setVerticalPolicy() -*/ - -/*! - \fn void QSizePolicy::transpose() - - Swaps the horizontal and vertical policies and stretches. -*/ - -/*! - \enum QSizePolicy::ControlType - \since 4.3 - - This enum specifies the different types of widgets in terms of - layout interaction: - - \value DefaultType The default type, when none is specified. - \value ButtonBox A QDialogButtonBox instance. - \value CheckBox A QCheckBox instance. - \value ComboBox A QComboBox instance. - \value Frame A QFrame instance. - \value GroupBox A QGroupBox instance. - \value Label A QLabel instance. - \value Line A QFrame instance with QFrame::HLine or QFrame::VLine. - \value LineEdit A QLineEdit instance. - \value PushButton A QPushButton instance. - \value RadioButton A QRadioButton instance. - \value Slider A QAbstractSlider instance. - \value SpinBox A QAbstractSpinBox instance. - \value TabWidget A QTabWidget instance. - \value ToolButton A QToolButton instance. - - \sa setControlType(), controlType() -*/ - -#ifdef QT3_SUPPORT -/*! - \typedef QSizePolicy::SizeType - \compat - - Use the QSizePolicy::Policy enum instead. -*/ - -/*! - \enum QSizePolicy::ExpandData - \compat - - Use the Qt::Orientations enum instead. - - \value NoDirection Use 0 instead. - \value Horizontally Use Qt::Horizontal instead. - \value Vertically Use Qt::Vertical instead. - \value BothDirections Use Qt::Horizontal | Qt::Vertical instead. -*/ - -/*! - \fn bool QSizePolicy::mayShrinkHorizontally() const - - Use the horizontalPolicy() function combined with the - QSizePolicy::PolicyFlag enum instead. - - \oldcode - bool policy = mayShrinkHorizontally(); - \newcode - bool policy = horizontalPolicy() & QSizePolicy::ShrinkFlag; - \endcode -*/ - -/*! - \fn bool QSizePolicy::mayShrinkVertically() const - - Use the verticalPolicy() function combined with the - QSizePolicy::PolicyFlag enum instead. - - \oldcode - bool policy = mayShrinkVertically(); - \newcode - bool policy = verticalPolicy() & QSizePolicy::ShrinkFlag; - \endcode -*/ - -/*! - \fn bool QSizePolicy::mayGrowHorizontally() const - - Use the horizontalPolicy() function combined with the - QSizePolicy::PolicyFlag enum instead. - - \oldcode - bool policy = mayGrowHorizontally(); - \newcode - bool policy = horizontalPolicy() & QSizePolicy::GrowFlag; - \endcode -*/ - -/*! - \fn bool QSizePolicy::mayGrowVertically() const - - Use the verticalPolicy() function combined with the - QSizePolicy::PolicyFlag enum instead. - - \oldcode - bool policy = mayGrowVertically(); - \newcode - bool policy = verticalPolicy() & QSizePolicy::GrowFlag; - \endcode -*/ - -/*! - \fn Qt::QSizePolicy::Orientations QSizePolicy::expanding() const - - Use expandingDirections() instead. -*/ - -/*! - \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, bool dependent) - - Use the QSizePolicy() constructor and the setHeightForWidth() - function instead. - - \oldcode - QSizePolicy *policy = new QSizePolicy(horizontal, vertical, dependent); - \newcode - QSizePolicy *policy = new QSizePolicy(horizontal, vertical); - policy->setHeightForWidth(dependent); - \endcode -*/ - -/*! - \fn QSizePolicy::QSizePolicy(Policy horizontal, Policy vertical, uchar horizontalStretch, - uchar verticalStretch, bool dependent) - - Use the QSizePolicy() constructor and call the - setHorizontalStretch(), setVerticalStretch(), and - setHeightForWidth() functions instead. - - \oldcode - QSizePolicy *policy = new QSizePolicy(horizontal, vertical, - horizontalStretch, verticalStretch, - dependent); - \newcode - QSizePolicy *policy = new QSizePolicy(horizontal, vertical); - policy->setHorizontalStretch(horizontalStretch); - policy->setVerticalStretch(verticalStretch); - policy->setHeightForWidth(dependent); - \endcode -*/ - -/*! - \fn QSizePolicy::Policy QSizePolicy::horData() const - - Use horizontalPolicy() instead. -*/ - -/*! - \fn QSizePolicy::Policy QSizePolicy::verData() const - - Use verticalPolicy() instead. -*/ - -/*! - \fn void QSizePolicy::setHorData(Policy policy) - - Use setHorizontalPolicy() instead. -*/ - -/*! - \fn void QSizePolicy::setVerData(Policy policy) - - Use setVerticalPolicy() instead. -*/ - -/*! - \fn uint QSizePolicy::horStretch() const - - Use horizontalStretch() instead. -*/ - -/*! - \fn uint QSizePolicy::verStretch() const - - Use verticalStretch() instead. -*/ - -/*! - \fn void QSizePolicy::setHorStretch(uchar stretch) - - Use setHorizontalStretch() instead. -*/ - -/*! - \fn void QSizePolicy::setVerStretch(uchar stretch) - - Use setVerticalStretch() instead. -*/ -#endif diff --git a/doc/src/classes/qtdesigner-api.qdoc b/doc/src/classes/qtdesigner-api.qdoc deleted file mode 100644 index 60dd9f8..0000000 --- a/doc/src/classes/qtdesigner-api.qdoc +++ /dev/null @@ -1,1413 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QDesignerMemberSheetExtension - - \brief The QDesignerMemberSheetExtension class allows you to - manipulate a widget's member functions which is displayed when - configuring connections using Qt Designer's mode for editing - signals and slots. - - \inmodule QtDesigner - - QDesignerMemberSheetExtension is a collection of functions that is - typically used to query a widget's member functions, and to - manipulate the member functions' appearance in \QD's signals and - slots editing mode. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 2 - - When implementing a custom widget plugin, a pointer to \QD's - current QDesignerFormEditorInterface object (\c formEditor in the - example above) is provided by the - QDesignerCustomWidgetInterface::initialize() function's parameter. - - The member sheet (and any other extension), can be retrieved by - querying \QD's extension manager using the qt_extension() - function. When you want to release the extension, you only need to - delete the pointer. - - All widgets have a default member sheet used in \QD's signals and - slots editing mode with the widget's member functions. But - QDesignerMemberSheetExtension also provides an interface for - creating custom member sheet extensions. - - \warning \QD uses the QDesignerMemberSheetExtension to facilitate - the signal and slot editing mode. Whenever a connection between - two widgets is requested, \QD will query for the widgets' member - sheet extensions. If a widget has an implemented member sheet - extension, this extension will override the default member sheet. - - To create a member sheet extension, your extension class must - inherit from both QObject and QDesignerMemberSheetExtension. Then, - since we are implementing an interface, we must ensure that it's - made known to the meta object system using the Q_INTERFACES() - macro: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 3 - - This enables \QD to use qobject_cast() to query for - supported interfaces using nothing but a QObject pointer. - - In \QD the extensions are not created until they are - required. For that reason, when implementing a member sheet - extension, you must also create a QExtensionFactory, i.e a class - that is able to make an instance of your extension, and register - it using \QD's \l {QExtensionManager}{extension manager}. - - When a widget's member sheet extension is required, \QD's \l - {QExtensionManager}{extension manager} will run through all its - registered factories calling QExtensionFactory::createExtension() - for each until the first one that is able to create a member sheet - extension for that widget, is found. This factory will then make - an instance of the extension. If no such factory is found, \QD - will use the default member sheet. - - There are four available types of extensions in \QD: - QDesignerContainerExtension, QDesignerMemberSheetExtension, - QDesignerPropertySheetExtension and - QDesignerTaskMenuExtension. \QD's behavior is the same whether the - requested extension is associated with a multi page container, a - member sheet, a property sheet or a task menu. - - The QExtensionFactory class provides a standard extension - factory, and can also be used as an interface for custom - extension factories. You can either create a new - QExtensionFactory and reimplement the - QExtensionFactory::createExtension() function. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 4 - - Or you can use an existing factory, expanding the - QExtensionFactory::createExtension() function to make the factory - able to create a member sheet extension as well. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 5 - - For a complete example using an extension class, see \l - {designer/taskmenuextension}{Task Menu Extension example}. The - example shows how to create a custom widget plugin for Qt - Designer, and how to to use the QDesignerTaskMenuExtension class - to add custom items to \QD's task menu. - - \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget - Extensions} -*/ - -/*! - \fn QDesignerMemberSheetExtension::~QDesignerMemberSheetExtension() - - Destroys the member sheet extension. -*/ - -/*! - \fn int QDesignerMemberSheetExtension::count() const - - Returns the extension's number of member functions. -*/ - -/*! - \fn int QDesignerMemberSheetExtension::indexOf(const QString &name) const - - Returns the index of the member function specified by the given \a - name. - - \sa memberName() -*/ - -/*! - \fn QString QDesignerMemberSheetExtension::memberName(int index) const - - Returns the name of the member function with the given \a index. - - \sa indexOf() -*/ - -/*! - \fn QString QDesignerMemberSheetExtension::memberGroup(int index) const - - Returns the name of the member group specified for the function - with the given \a index. - - \sa indexOf(), setMemberGroup() -*/ - -/*! - \fn void QDesignerMemberSheetExtension::setMemberGroup(int index, const QString &group) - - Sets the member group of the member function with the given \a - index, to \a group. - - \sa indexOf(), memberGroup() -*/ - -/*! - \fn bool QDesignerMemberSheetExtension::isVisible(int index) const - - Returns true if the member function with the given \a index is - visible in \QD's signal and slot editor, otherwise false. - - \sa indexOf(), setVisible() -*/ - -/*! - \fn void QDesignerMemberSheetExtension::setVisible(int index, bool visible) - - If \a visible is true, the member function with the given \a index - is visible in \QD's signals and slots editing mode; otherwise the - member function is hidden. - - \sa indexOf(), isVisible() -*/ - -/*! - \fn virtual bool QDesignerMemberSheetExtension::isSignal(int index) const - - Returns true if the member function with the given \a index is a - signal, otherwise false. - - \sa indexOf() -*/ - -/*! - \fn bool QDesignerMemberSheetExtension::isSlot(int index) const - - Returns true if the member function with the given \a index is a - slot, otherwise false. - - \sa indexOf() -*/ - -/*! - \fn bool QDesignerMemberSheetExtension::inheritedFromWidget(int index) const - - Returns true if the member function with the given \a index is - inherited from QWidget, otherwise false. - - \sa indexOf() -*/ - -/*! - \fn QString QDesignerMemberSheetExtension::declaredInClass(int index) const - - Returns the name of the class in which the member function with - the given \a index is declared. - - \sa indexOf() -*/ - -/*! - \fn QString QDesignerMemberSheetExtension::signature(int index) const - - Returns the signature of the member function with the given \a - index. - - \sa indexOf() -*/ - -/*! - \fn QList<QByteArray> QDesignerMemberSheetExtension::parameterTypes(int index) const - - Returns the parameter types of the member function with the given - \a index, as a QByteArray list. - - \sa indexOf(), parameterNames() -*/ - -/*! - \fn QList<QByteArray> QDesignerMemberSheetExtension::parameterNames(int index) const - - Returns the parameter names of the member function with the given - \a index, as a QByteArray list. - - \sa indexOf(), parameterTypes() -*/ - - -// Doc: Interface only - -/*! - \class QDesignerLayoutDecorationExtension - \brief The QDesignerLayoutDecorationExtension class provides an extension to a layout in \QD. - \inmodule QtDesigner - \internal -*/ - -/*! - \enum QDesignerLayoutDecorationExtension::InsertMode - - This enum describes the modes that are used to insert items into a layout. - - \value InsertWidgetMode Widgets are inserted into empty cells in a layout. - \value InsertRowMode Whole rows are inserted into a vertical or grid layout. - \value InsertColumnMode Whole columns are inserted into a horizontal or grid layout. -*/ - -/*! - \fn virtual QDesignerLayoutDecorationExtension::~QDesignerLayoutDecorationExtension() - - Destroys the extension. -*/ - -/*! - \fn virtual QList<QWidget*> QDesignerLayoutDecorationExtension::widgets(QLayout *layout) const - - Returns the widgets that are managed by the given \a layout. - - \sa insertWidget(), removeWidget() -*/ - -/*! - \fn QRect QDesignerLayoutDecorationExtension::itemInfo(int index) const - - Returns the rectangle covered by the item at the given \a index in the layout. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::indexOf(QWidget *widget) const - - Returns the index of the specified \a widget in the layout. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::indexOf(QLayoutItem *item) const - - Returns the index of the specified layout \a item. -*/ - -/*! - \fn QDesignerLayoutDecorationExtension::InsertMode QDesignerLayoutDecorationExtension::currentInsertMode() const - - Returns the current insertion mode. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::currentIndex() const - - Returns the current index in the layout. -*/ - -/*! - \fn QPair<int, int> QDesignerLayoutDecorationExtension::currentCell() const - - Returns a pair containing the row and column of the current cell in the layout. -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::insertWidget(QWidget *widget, const QPair<int, int> &cell) - - Inserts the given \a widget into the specified \a cell in the layout. - - \sa removeWidget() -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::removeWidget(QWidget *widget) - - Removes the specified \a widget from the layout. - - \sa insertWidget() -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::insertRow(int row) - - Inserts a new row into the form at the position specified by \a row. -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::insertColumn(int column) - - Inserts a new column into the form at the position specified by \a column. -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::simplify() - - Simplifies the layout by removing unnecessary empty rows and columns, and by changing the - number of rows or columns spanned by widgets. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::findItemAt(const QPoint &position) const - - Returns the index of the item in the layout that covers the given \a position. -*/ - -/*! - \fn int QDesignerLayoutDecorationExtension::findItemAt(int row, int column) const - - Returns the item in the layout that occupies the specified \a row and \a column in the layout. - - Currently, this only applies to grid layouts. -*/ - -/*! - \fn void QDesignerLayoutDecorationExtension::adjustIndicator(const QPoint &position, int index) - - Adjusts the indicator for the item specified by \a index so that - it lies at the given \a position on the form. -*/ - - -// Doc: Interface only - -/*! - \class QDesignerContainerExtension - \brief The QDesignerContainerExtension class allows you to add pages to - a custom multi-page container in Qt Designer's workspace. - \inmodule QtDesigner - - QDesignerContainerExtension provide an interface for creating - custom container extensions. A container extension consists of a - collection of functions that \QD needs to manage a multi-page - container plugin, and a list of the container's pages. - - \image containerextension-example.png - - \warning This is \e not an extension for container plugins in - general, only custom \e multi-page containers. - - To create a container extension, your extension class must inherit - from both QObject and QDesignerContainerExtension. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 6 - - Since we are implementing an interface, we must ensure that it's - made known to the meta object system using the Q_INTERFACES() - macro. This enables \QD to use the qobject_cast() function to - query for supported interfaces using nothing but a QObject - pointer. - - You must reimplement several functions to enable \QD to manage a - custom multi-page container widget: \QD uses count() to keep track - of the number pages in your container, widget() to return the page - at a given index in the list of the container's pages, and - currentIndex() to return the list index of the selected page. \QD - uses the addWidget() function to add a given page to the - container, expecting it to be appended to the list of pages, while - it expects the insertWidget() function to add a given page to the - container by inserting it at a given index. - - In \QD the extensions are not created until they are - required. For that reason you must also create a - QExtensionFactory, i.e a class that is able to make an instance of - your extension, and register it using \QD's \l - {QExtensionManager}{extension manager}. - - When a container extension is required, \QD's \l - {QExtensionManager}{extension manager} will run through all its - registered factories calling QExtensionFactory::createExtension() - for each until the first one that is able to create a container - extension, is found. This factory will then create the extension - for the plugin. - - There are four available types of extensions in \QD: - QDesignerContainerExtension , QDesignerMemberSheetExtension, - QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. - \QD's behavior is the same whether the requested extension is - associated with a multi page container, a member sheet, a property - sheet or a task menu. - - The QExtensionFactory class provides a standard extension factory, - and can also be used as an interface for custom extension - factories. You can either create a new QExtensionFactory and - reimplement the QExtensionFactory::createExtension() function. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 7 - - Or you can use an existing factory, expanding the - QExtensionFactory::createExtension() function to make the factory - able to create a container extension as well. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 8 - - For a complete example using the QDesignerContainerExtension - class, see the \l {designer/containerextension}{Container - Extension example}. The example shows how to create a custom - multi-page plugin for \QD. - - \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget - Extensions} -*/ - -/*! - \fn QDesignerContainerExtension::~QDesignerContainerExtension() - - Destroys the extension. -*/ - -/*! - \fn int QDesignerContainerExtension::count() const - - Returns the number of pages in the container. -*/ - -/*! - \fn QWidget *QDesignerContainerExtension::widget(int index) const - - Returns the page at the given \a index in the extension's list of - pages. - - \sa addWidget(), insertWidget() -*/ - -/*! - \fn int QDesignerContainerExtension::currentIndex() const - - Returns the index of the currently selected page in the - container. - - \sa setCurrentIndex() -*/ - -/*! - \fn void QDesignerContainerExtension::setCurrentIndex(int index) - - Sets the currently selected page in the container to be the - page at the given \a index in the extension's list of pages. - - \sa currentIndex() -*/ - -/*! - \fn void QDesignerContainerExtension::addWidget(QWidget *page) - - Adds the given \a page to the container by appending it to the - extension's list of pages. - - \sa insertWidget(), remove(), widget() -*/ - -/*! - \fn void QDesignerContainerExtension::insertWidget(int index, QWidget *page) - - Adds the given \a page to the container by inserting it at the - given \a index in the extension's list of pages. - - \sa addWidget(), remove(), widget() -*/ - -/*! - \fn void QDesignerContainerExtension::remove(int index) - - Removes the page at the given \a index from the extension's list - of pages. - - \sa addWidget(), insertWidget() -*/ - - -// Doc: Interface only - -/*! - \class QDesignerTaskMenuExtension - \brief The QDesignerTaskMenuExtension class allows you to add custom - menu entries to Qt Designer's task menu. - \inmodule QtDesigner - - QDesignerTaskMenuExtension provides an interface for creating - custom task menu extensions. It is typically used to create task - menu entries that are specific to a plugin in \QD. - - \QD uses the QDesignerTaskMenuExtension to feed its task - menu. Whenever a task menu is requested, \QD will query - for the selected widget's task menu extension. - - \image taskmenuextension-example-faded.png - - A task menu extension is a collection of QActions. The actions - appear as entries in the task menu when the plugin with the - specified extension is selected. The image above shows the custom - \gui {Edit State...} action which appears in addition to \QD's - default task menu entries: \gui Cut, \gui Copy, \gui Paste etc. - - To create a custom task menu extension, your extension class must - inherit from both QObject and QDesignerTaskMenuExtension. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 9 - - Since we are implementing an interface, we must ensure that it - is made known to the meta-object system using the Q_INTERFACES() - macro. This enables \QD to use the qobject_cast() function to - query for supported interfaces using nothing but a QObject - pointer. - - You must reimplement the taskActions() function to return a list - of actions that will be included in \QD task menu. Optionally, you - can reimplement the preferredEditAction() function to set the - action that is invoked when selecting your plugin and pressing - \key F2. The preferred edit action must be one of the actions - returned by taskActions() and, if it's not defined, pressing the - \key F2 key will simply be ignored. - - In \QD, extensions are not created until they are required. A - task menu extension, for example, is created when you click the - right mouse button over a widget in \QD's workspace. For that - reason you must also construct an extension factory, using either - QExtensionFactory or a subclass, and register it using \QD's - \l {QExtensionManager}{extension manager}. - - When a task menu extension is required, \QD's \l - {QExtensionManager}{extension manager} will run through all its - registered factories calling QExtensionFactory::createExtension() - for each until it finds one that is able to create a task menu - extension for the selected widget. This factory will then make an - instance of the extension. - - There are four available types of extensions in \QD: - QDesignerContainerExtension, QDesignerMemberSheetExtension, - QDesignerPropertySheetExtension, and QDesignerTaskMenuExtension. - \QD's behavior is the same whether the requested extension is - associated with a container, a member sheet, a property sheet or a - task menu. - - The QExtensionFactory class provides a standard extension factory, - and can also be used as an interface for custom extension - factories. You can either create a new QExtensionFactory and - reimplement the QExtensionFactory::createExtension() function. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 10 - - Or you can use an existing factory, expanding the - QExtensionFactory::createExtension() function to make the factory - able to create a task menu extension as well. For example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 11 - - For a complete example using the QDesignerTaskMenuExtension class, - see the \l {designer/taskmenuextension}{Task Menu Extension - example}. The example shows how to create a custom widget plugin - for \QD, and how to to use the QDesignerTaskMenuExtension - class to add custom items to \QD's task menu. - - \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget - Extensions} -*/ - -/*! - \fn QDesignerTaskMenuExtension::~QDesignerTaskMenuExtension() - - Destroys the task menu extension. -*/ - -/*! - \fn QAction *QDesignerTaskMenuExtension::preferredEditAction() const - - Returns the action that is invoked when selecting a plugin with - the specified extension and pressing \key F2. - - The action must be one of the actions returned by taskActions(). -*/ - -/*! - \fn QList<QAction*> QDesignerTaskMenuExtension::taskActions() const - - Returns the task menu extension as a list of actions which will be - included in \QD's task menu when a plugin with the specified - extension is selected. - - The function must be reimplemented to add actions to the list. -*/ - - -// Doc: Interface only - -/*! - \class QDesignerCustomWidgetCollectionInterface - - \brief The QDesignerCustomWidgetCollectionInterface class allows - you to include several custom widgets in one single library. - - \inmodule QtDesigner - - When implementing a custom widget plugin, you build it as a - separate library. If you want to include several custom widget - plugins in the same library, you must in addition subclass - QDesignerCustomWidgetCollectionInterface. - - QDesignerCustomWidgetCollectionInterface contains one single - function returning a list of the collection's - QDesignerCustomWidgetInterface objects. For example, if you have - several custom widgets \c CustomWidgetOne, \c CustomWidgetTwo and - \c CustomWidgetThree, the class definition may look like this: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 12 - - In the class constructor you add the interfaces to your custom - widgets to the list which you return in the customWidgets() - function: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 13 - - Note that instead of exporting each custom widget plugin using the - Q_EXPORT_PLUGIN2() macro, you export the entire collection. The - Q_EXPORT_PLUGIN2() macro ensures that \QD can access and construct - the custom widgets. Without this macro, there is no way for \QD to - use them. - - \sa QDesignerCustomWidgetInterface, {Creating Custom Widgets for - Qt Designer} -*/ - -/*! - \fn QDesignerCustomWidgetCollectionInterface::~QDesignerCustomWidgetCollectionInterface() { - - Destroys the custom widget collection interface. -*/ - -/*! - \fn QList<QDesignerCustomWidgetInterface*> QDesignerCustomWidgetCollectionInterface::customWidgets() const - - Returns a list of interfaces to the collection's custom widgets. -*/ - - -// Doc: Interface only - -/*! - \class QDesignerCustomWidgetInterface - - \brief The QDesignerCustomWidgetInterface class enables Qt Designer - to access and construct custom widgets. - - \inmodule QtDesigner - - QDesignerCustomWidgetInterface provides a custom widget with an - interface. The class contains a set of functions that must be subclassed - to return basic information about the widget, such as its class name and - the name of its header file. Other functions must be implemented to - initialize the plugin when it is loaded, and to construct instances of - the custom widget for \QD to use. - - When implementing a custom widget you must subclass - QDesignerCustomWidgetInterface to expose your widget to \QD. For - example, this is the declaration for the plugin used in the - \l{Custom Widget Plugin Example}{Custom Widget Plugin example} that - enables an analog clock custom widget to be used by \QD: - - \snippet examples/designer/customwidgetplugin/customwidgetplugin.h 0 - - Note that the only part of the class definition that is specific - to this particular custom widget is the class name. In addition, - since we are implementing an interface, we must ensure that it's - made known to the meta object system using the Q_INTERFACES() - macro. This enables \QD to use the qobject_cast() function to - query for supported interfaces using nothing but a QObject - pointer. - - After \QD loads a custom widget plugin, it calls the interface's - initialize() function to enable it to set up any resources that it - may need. This function is called with a QDesignerFormEditorInterface - parameter that provides the plugin with a gateway to all of \QD's API. - - \QD constructs instances of the custom widget by calling the plugin's - createWidget() function with a suitable parent widget. Plugins must - construct and return an instance of a custom widget with the specified - parent widget. - - In the implementation of the class you must remember to export - your custom widget plugin to \QD using the Q_EXPORT_PLUGIN2() - macro. For example, if a library called \c libcustomwidgetplugin.so - (on Unix) or \c libcustomwidget.dll (on Windows) contains a widget - class called \c MyCustomWidget, we can export it by adding the - following line to the file containing the plugin implementation: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 14 - - This macro ensures that \QD can access and construct the custom widget. - Without this macro, there is no way for \QD to use it. - - When implementing a custom widget plugin, you build it as a - separate library. If you want to include several custom widget - plugins in the same library, you must in addition subclass - QDesignerCustomWidgetCollectionInterface. - - \warning If your custom widget plugin contains QVariant - properties, be aware that only the following \l - {QVariant::Type}{types} are supported: - - \list - \o QVariant::ByteArray - \o QVariant::Bool - \o QVariant::Color - \o QVariant::Cursor - \o QVariant::Date - \o QVariant::DateTime - \o QVariant::Double - \o QVariant::Int - \o QVariant::Point - \o QVariant::Rect - \o QVariant::Size - \o QVariant::SizePolicy - \o QVariant::String - \o QVariant::Time - \o QVariant::UInt - \endlist - - For a complete example using the QDesignerCustomWidgetInterface - class, see the \l {designer/customwidgetplugin}{Custom Widget - Example}. The example shows how to create a custom widget plugin - for \QD. - - \sa QDesignerCustomWidgetCollectionInterface {Creating Custom - Widgets for Qt Designer} -*/ - -/*! - \fn QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface() - - Destroys the custom widget interface. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::name() const - - Returns the class name of the custom widget supplied by the interface. - - The name returned \e must be identical to the class name used for the - custom widget. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::group() const - - Returns the name of the group to which the custom widget belongs. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::toolTip() const - - Returns a short description of the widget that can be used by \QD - in a tool tip. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::whatsThis() const - - Returns a description of the widget that can be used by \QD in - "What's This?" help for the widget. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::includeFile() const - - Returns the path to the include file that \l uic uses when - creating code for the custom widget. -*/ - -/*! - \fn QIcon QDesignerCustomWidgetInterface::icon() const - - Returns the icon used to represent the custom widget in \QD's - widget box. -*/ - -/*! - \fn bool QDesignerCustomWidgetInterface::isContainer() const - - Returns true if the custom widget is intended to be used as a - container; otherwise returns false. - - Most custom widgets are not used to hold other widgets, so their - implementations of this function will return false, but custom - containers will return true to ensure that they behave correctly - in \QD. -*/ - -/*! - \fn QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent) - - Returns a new instance of the custom widget, with the given \a - parent. -*/ - -/*! - \fn bool QDesignerCustomWidgetInterface::isInitialized() const - - Returns true if the widget has been initialized; otherwise returns - false. - - \sa initialize() -*/ - -/*! - \fn void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor) - - Initializes the widget for use with the specified \a formEditor - interface. - - \sa isInitialized() -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::domXml() const - - Returns the XML that is used to describe the custom widget's - properties to \QD. -*/ - -/*! - \fn QString QDesignerCustomWidgetInterface::codeTemplate() const - - This function is reserved for future use by \QD. - - \omit - Returns the code template that \QD includes in forms that contain - the custom widget when they are saved. - \endomit -*/ - -/*! - \macro QDESIGNER_WIDGET_EXPORT - \relates QDesignerCustomWidgetInterface - \since 4.1 - - This macro is used when defining custom widgets to ensure that they are - correctly exported from plugins for use with \QD. - - On some platforms, the symbols required by \QD to create new widgets - are removed from plugins by the build system, making them unusable. - Using this macro ensures that the symbols are retained on those platforms, - and has no side effects on other platforms. - - For example, the \l{designer/worldtimeclockplugin}{World Time Clock Plugin} - example exports a custom widget class with the following declaration: - - \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 0 - \dots - \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 2 - - \sa {Creating Custom Widgets for Qt Designer} -*/ - - -// Doc: Abstract class - -/*! - \class QDesignerDnDItemInterface - \brief The QDesignerDnDItemInterface class provides an interface that is used to manage items - during a drag and drop operation. - \inmodule QtDesigner - \internal -*/ - -/*! - \enum QDesignerDnDItemInterface::DropType - - This enum describes the result of a drag and drop operation. - - \value MoveDrop The item was moved. - \value CopyDrop The item was copied. -*/ - -/*! - \fn QDesignerDnDItemInterface::QDesignerDnDItemInterface() - - Constructs a new interface to a drag and drop item. -*/ - -/*! - \fn QDesignerDnDItemInterface::~QDesignerDnDItemInterface() - - Destroys the interface to the item. -*/ - -/*! - \fn DomUI *QDesignerDnDItemInterface::domUi() const - - Returns a user interface object for the item. -*/ - -/*! - \fn QWidget *QDesignerDnDItemInterface::widget() const - - Returns the widget being copied or moved in the drag and drop operation. - - \sa source() -*/ - -/*! - \fn QWidget *QDesignerDnDItemInterface::decoration() const - - Returns the widget used to represent the item. -*/ - -/*! - \fn QPoint QDesignerDnDItemInterface::hotSpot() const - - Returns the cursor's hotspot. - - \sa QDrag::hotSpot() -*/ - -/*! - \fn DropType QDesignerDnDItemInterface::type() const - - Returns the type of drag and drop operation in progress. -*/ - -/*! - \fn QWidget *QDesignerDnDItemInterface::source() const - - Returns the widget that is the source of the drag and drop operation; i.e. the original - container of the widget being dragged. - - \sa widget() -*/ - - -// Doc: Abstract class - -/*! - \class QDesignerIconCacheInterface - \brief The QDesignerIconCacheInterface class provides an interface to \QD's icon cache. - \inmodule QtDesigner - \internal -*/ - -/*! - \fn QDesignerIconCacheInterface::QDesignerIconCacheInterface(QObject *parent) - - Constructs a new interface with the given \a parent. -*/ - -/*! - \fn QIcon QDesignerIconCacheInterface::nameToIcon(const QString &filePath, const QString &qrcPath) - - Returns the icon associated with the name specified by \a filePath in the resource - file specified by \a qrcPath. - - If \a qrcPath refers to a valid resource file, the name used for the file path is a path - within those resources; otherwise the file path refers to a local file. - - \sa {The Qt Resource System}, nameToPixmap() -*/ - -/*! - \fn QPixmap QDesignerIconCacheInterface::nameToPixmap(const QString &filePath, const QString &qrcPath) - - Returns the pixmap associated with the name specified by \a filePath in the resource - file specified by \a qrcPath. - - If \a qrcPath refers to a valid resource file, the name used for the file path is a path - within those resources; otherwise the file path refers to a local file. - - \sa {The Qt Resource System}, nameToIcon() -*/ - -/*! - \fn QString QDesignerIconCacheInterface::iconToFilePath(const QIcon &icon) const - - Returns the file path associated with the given \a icon. The file path is a path within - an application resources. -*/ - -/*! - \fn QString QDesignerIconCacheInterface::iconToQrcPath(const QIcon &icon) const - - Returns the path to the resource file that refers to the specified \a icon. The resource - path refers to a local file. -*/ - -/*! - \fn QString QDesignerIconCacheInterface::pixmapToFilePath(const QPixmap &pixmap) const - - Returns the file path associated with the given \a pixmap. The file path is a path within - an application resources. -*/ - -/*! - \fn QString QDesignerIconCacheInterface::pixmapToQrcPath(const QPixmap &pixmap) const - - Returns the path to the resource file that refers to the specified \a pixmap. The resource - path refers to a local file. -*/ - -/*! - \fn QList<QPixmap> QDesignerIconCacheInterface::pixmapList() const - - Returns a list of pixmaps for the icons provided by the icon cache. -*/ - -/*! - \fn QList<QIcon> QDesignerIconCacheInterface::iconList() const - - Returns a list of icons provided by the icon cache. -*/ - -/*! - \fn QString QDesignerIconCacheInterface::resolveQrcPath(const QString &filePath, const QString &qrcPath, const QString &workingDirectory) const - - Returns a path to a resource specified by the \a filePath within - the resource file located at \a qrcPath. If \a workingDirectory is - a valid path to a directory, the path returned will be relative to - that directory; otherwise an absolute path is returned. - - \omit - ### Needs checking - \endomit -*/ - - -// Doc: Interface only - -/*! - \class QDesignerPropertySheetExtension - - \brief The QDesignerPropertySheetExtension class allows you to - manipulate a widget's properties which is displayed in Qt - Designer's property editor. - - \sa QDesignerDynamicPropertySheetExtension - - \inmodule QtDesigner - - QDesignerPropertySheetExtension provides a collection of functions that - are typically used to query a widget's properties, and to - manipulate the properties' appearance in the property editor. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 15 - - Note that if you change the value of a property using the - QDesignerPropertySheetExtension::setProperty() function, the undo - stack is not updated. To ensure that a property's value can be - reverted using the undo stack, you must use the - QDesignerFormWindowCursorInterface::setProperty() function, or its - buddy \l - {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()}, - instead. - - When implementing a custom widget plugin, a pointer to \QD's - current QDesignerFormEditorInterface object (\c formEditor in the - example above) is provided by the - QDesignerCustomWidgetInterface::initialize() function's parameter. - - The property sheet, or any other extension, can be retrieved by - querying \QD's extension manager using the qt_extension() - function. When you want to release the extension, you only need to - delete the pointer. - - All widgets have a default property sheet which populates \QD's - property editor with the widget's properties (i.e the ones defined - with the Q_PROPERTY() macro). But QDesignerPropertySheetExtension - also provides an interface for creating custom property sheet - extensions. - - \warning \QD uses the QDesignerPropertySheetExtension to feed its - property editor. Whenever a widget is selected in its workspace, - \QD will query for the widget's property sheet extension. If the - selected widget has an implemented property sheet extension, this - extension will override the default property sheet. - - To create a property sheet extension, your extension class must - inherit from both QObject and - QDesignerPropertySheetExtension. Then, since we are implementing - an interface, we must ensure that it's made known to the meta - object system using the Q_INTERFACES() macro: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 16 - - This enables \QD to use qobject_cast() to query for supported - interfaces using nothing but a QObject pointer. - - In \QD the extensions are not created until they are - required. For that reason, when implementing a property sheet - extension, you must also create a QExtensionFactory, i.e a class - that is able to make an instance of your extension, and register - it using \QD's \l {QExtensionManager}{extension manager}. - - When a property sheet extension is required, \QD's \l - {QExtensionManager}{extension manager} will run through all its - registered factories calling QExtensionFactory::createExtension() - for each until the first one that is able to create a property - sheet extension for the selected widget, is found. This factory - will then make an instance of the extension. If no such factory - can be found, \QD will use the default property sheet. - - There are four available types of extensions in \QD: - QDesignerContainerExtension, QDesignerMemberSheetExtension, - QDesignerPropertySheetExtension and QDesignerTaskMenuExtension. Qt - Designer's behavior is the same whether the requested extension is - associated with a multi page container, a member sheet, a property - sheet or a task menu. - - The QExtensionFactory class provides a standard extension factory, - and can also be used as an interface for custom extension - factories. You can either create a new QExtensionFactory and - reimplement the QExtensionFactory::createExtension() function. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 17 - - Or you can use an existing factory, expanding the - QExtensionFactory::createExtension() function to make the factory - able to create a property sheet extension extension as well. For - example: - - \snippet doc/src/snippets/code/doc_src_qtdesigner.qdoc 18 - - For a complete example using an extension class, see the \l - {designer/taskmenuextension}{Task Menu Extension example}. The - example shows how to create a custom widget plugin for Qt - Designer, and how to to use the QDesignerTaskMenuExtension class - to add custom items to \QD's task menu. - - \sa QExtensionFactory, QExtensionManager, {Creating Custom Widget - Extensions} -*/ - -/*! - \fn QDesignerPropertySheetExtension::~QDesignerPropertySheetExtension() - - Destroys the property sheet extension. -*/ - -/*! - \fn int QDesignerPropertySheetExtension::count() const - - Returns the selected widget's number of properties. -*/ - -/*! - \fn int QDesignerPropertySheetExtension::indexOf(const QString &name) const - - Returns the index for a given property \a name. - - \sa propertyName() -*/ - -/*! - \fn QString QDesignerPropertySheetExtension::propertyName(int index) const - - Returns the name of the property at the given \a index. - - \sa indexOf() -*/ - -/*! - \fn QString QDesignerPropertySheetExtension::propertyGroup(int index) const - - Returns the property group for the property at the given \a index. - - \QD's property editor supports property groups, i.e. sections of - related properties. A property can be related to a group using the - setPropertyGroup() function. The default group of any property is - the name of the class that defines it. For example, the - QObject::objectName property appears within the QObject property - group. - - \sa indexOf(), setPropertyGroup() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setPropertyGroup(int index, const QString &group) - - Sets the property group for the property at the given \a index to - \a group. - - Relating a property to a group makes it appear within that group's - section in the property editor. The default property group of any - property is the name of the class that defines it. For example, - the QObject::objectName property appears within the QObject - property group. - - \sa indexOf(), property(), propertyGroup() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::hasReset(int index) const - - Returns true if the property at the given \a index has a reset - button in \QD's property editor, otherwise false. - - \sa indexOf(), reset() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::reset(int index) - - Resets the value of the property at the given \a index, to the - default value. Returns true if a default value could be found, otherwise false. - - \sa indexOf(), hasReset(), isChanged() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::isVisible(int index) const - - Returns true if the property at the given \a index is visible in - \QD's property editor, otherwise false. - - \sa indexOf(), setVisible() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setVisible(int index, bool visible) - - If \a visible is true, the property at the given \a index is - visible in \QD's property editor; otherwise the property is - hidden. - - \sa indexOf(), isVisible() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::isAttribute(int index) const - - Returns true if the property at the given \a index is an attribute, - which will be \e excluded from the UI file, otherwise false. - - \sa indexOf(), setAttribute() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setAttribute(int index, bool attribute) - - If \a attribute is true, the property at the given \a index is - made an attribute which will be \e excluded from the UI file; - otherwise it will be included. - - \sa indexOf(), isAttribute() -*/ - -/*! - \fn QVariant QDesignerPropertySheetExtension::property(int index) const - - Returns the value of the property at the given \a index. - - \sa indexOf(), setProperty(), propertyGroup() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setProperty(int index, const QVariant &value) - - Sets the \a value of the property at the given \a index. - - \warning If you change the value of a property using this - function, the undo stack is not updated. To ensure that a - property's value can be reverted using the undo stack, you must - use the QDesignerFormWindowCursorInterface::setProperty() - function, or its buddy \l - {QDesignerFormWindowCursorInterface::setWidgetProperty()}{setWidgetProperty()}, - instead. - - \sa indexOf(), property(), propertyGroup() -*/ - -/*! - \fn bool QDesignerPropertySheetExtension::isChanged(int index) const - - Returns true if the value of the property at the given \a index - differs from the property's default value, otherwise false. - - \sa indexOf(), setChanged(), reset() -*/ - -/*! - \fn void QDesignerPropertySheetExtension::setChanged(int index, bool changed) - - Sets whether the property at the given \a index is different from - its default value, or not, depending on the \a changed parameter. - - \sa indexOf(), isChanged() -*/ - -// Doc: Interface only - -/*! - \class QDesignerDynamicPropertySheetExtension - - \brief The QDesignerDynamicPropertySheetExtension class allows you to - manipulate a widget's dynamic properties in Qt Designer's property editor. - - \sa QDesignerPropertySheetExtension, {QObject#Dynamic Properties}{Dynamic Properties} - - \inmodule QtDesigner - \since 4.3 -*/ - -/*! - \fn QDesignerDynamicPropertySheetExtension::~QDesignerDynamicPropertySheetExtension() - - Destroys the dynamic property sheet extension. -*/ - -/*! - \fn bool QDesignerDynamicPropertySheetExtension::dynamicPropertiesAllowed() const - - Returns true if the widget supports dynamic properties; otherwise returns false. -*/ - -/*! - \fn int QDesignerDynamicPropertySheetExtension::addDynamicProperty(const QString &propertyName, const QVariant &value) - - Adds a dynamic property named \a propertyName and sets its value to \a value. - Returns the index of the property if it was added successfully; otherwise returns -1 to - indicate failure. -*/ - -/*! - \fn bool QDesignerDynamicPropertySheetExtension::removeDynamicProperty(int index) - - Removes the dynamic property at the given \a index. - Returns true if the operation succeeds; otherwise returns false. -*/ - -/*! - \fn bool QDesignerDynamicPropertySheetExtension::isDynamicProperty(int index) const - - Returns true if the property at the given \a index is a dynamic property; otherwise - returns false. -*/ - -/*! - \fn bool QDesignerDynamicPropertySheetExtension::canAddDynamicProperty(const QString &propertyName) const - - Returns true if \a propertyName is a valid, unique name for a dynamic - property; otherwise returns false. - -*/ diff --git a/doc/src/classes/qtendian.qdoc b/doc/src/classes/qtendian.qdoc deleted file mode 100644 index e96ba0f..0000000 --- a/doc/src/classes/qtendian.qdoc +++ /dev/null @@ -1,168 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \headerfile <QtEndian> - \title Endian Conversion Functions - \ingroup architecture - \brief The <QtEndian> header provides functions to convert between - little and big endian representations of numbers. -*/ - -/*! - \fn T qFromBigEndian(const uchar *src) - \since 4.3 - \relates <QtEndian> - - Reads a big-endian number from memory location \a src and returns the number in the - host byte order representation. - On CPU architectures where the host byte order is little-endian (such as x86) this - will swap the byte order; otherwise it will just read from \a src. - - \note Template type \c{T} can either be a qint16, qint32 or qint64. Other types of - integers, e.g., qlong, are not applicable. - - There are no data alignment constraints for \a src. - - \sa qFromLittleEndian() - \sa qToBigEndian() - \sa qToLittleEndian() -*/ -/*! - \fn T qFromBigEndian(T src) - \since 4.3 - \relates <QtEndian> - \overload - - Converts \a src from big-endian byte order and returns the number in host byte order - representation of that number. - On CPU architectures where the host byte order is little-endian (such as x86) this - will return \a src with the byte order swapped; otherwise it will return \a src - unmodified. -*/ -/*! - \fn T qFromLittleEndian(const uchar *src) - \since 4.3 - \relates <QtEndian> - - Reads a little-endian number from memory location \a src and returns the number in - the host byte order representation. - On CPU architectures where the host byte order is big-endian (such as PowerPC) this - will swap the byte order; otherwise it will just read from \a src. - - \note Template type \c{T} can either be a qint16, qint32 or qint64. Other types of - integers, e.g., qlong, are not applicable. - - There are no data alignment constraints for \a src. - - \sa qFromBigEndian() - \sa qToBigEndian() - \sa qToLittleEndian() -*/ -/*! - \fn T qFromLittleEndian(T src) - \since 4.3 - \relates <QtEndian> - \overload - - Converts \a src from little-endian byte order and returns the number in host byte - order representation of that number. - On CPU architectures where the host byte order is big-endian (such as PowerPC) this - will return \a src with the byte order swapped; otherwise it will return \a src - unmodified. -*/ -/*! - \fn void qToBigEndian(T src, uchar *dest) - \since 4.3 - \relates <QtEndian> - - Writes the number \a src with template type \c{T} to the memory location at \a dest - in big-endian byte order. - - Note that template type \c{T} can only be an integer data type (signed or unsigned). - - There are no data alignment constraints for \a dest. - - \sa qFromBigEndian() - \sa qFromLittleEndian() - \sa qToLittleEndian() -*/ -/*! - \fn T qToBigEndian(T src) - \since 4.3 - \relates <QtEndian> - \overload - - Converts \a src from host byte order and returns the number in big-endian byte order - representation of that number. - On CPU architectures where the host byte order is little-endian (such as x86) this - will return \a src with the byte order swapped; otherwise it will return \a src - unmodified. -*/ -/*! - \fn void qToLittleEndian(T src, uchar *dest) - \since 4.3 - \relates <QtEndian> - - Writes the number \a src with template type \c{T} to the memory location at \a dest - in little-endian byte order. - - Note that template type \c{T} can only be an integer data type (signed or unsigned). - - There are no data alignment constraints for \a dest. - - \sa qFromBigEndian() - \sa qFromLittleEndian() - \sa qToBigEndian() -*/ -/*! - \fn T qToLittleEndian(T src) - \since 4.3 - \relates <QtEndian> - \overload - - Converts \a src from host byte order and returns the number in little-endian byte - order representation of that number. - On CPU architectures where the host byte order is big-endian (such as PowerPC) this - will return \a src with the byte order swapped; otherwise it will return \a src - unmodified. -*/ - diff --git a/doc/src/classes/qtestevent.qdoc b/doc/src/classes/qtestevent.qdoc deleted file mode 100644 index 7c67d95..0000000 --- a/doc/src/classes/qtestevent.qdoc +++ /dev/null @@ -1,191 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QTestEventList - \inmodule QtTest - - \brief The QTestEventList class provides a list of GUI events. - - QTestEventList inherits from QList<QTestEvent *>, and provides - convenience functions for populating the list. - - A QTestEventList can be populated with GUI events that can be - stored as test data for later usage, or be replayed on any - QWidget. - - Example: - \snippet doc/src/snippets/code/doc_src_qtestevent.qdoc 0 - - The example above simulates the user entering the character \c a - followed by a backspace, waiting for 200 milliseconds and - repeating it. -*/ - -/*! \fn QTestEventList::QTestEventList() - - Constructs an empty QTestEventList. -*/ - -/*! \fn QTestEventList::QTestEventList(const QTestEventList &other) - - Constructs a new QTestEventList as a copy of \a other. -*/ - -/*! \fn QTestEventList::~QTestEventList() - - Empties the list and destroys all stored events. -*/ - -/*! \fn void QTestEventList::clear() - - Removes all events from the list. -*/ - -/*! \fn void QTestEventList::addKeyClick(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - Adds a new key click to the list. The event will simulate the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyClick() -*/ - -/*! \fn void QTestEventList::addKeyPress(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - Adds a new key press to the list. The event will press the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyPress() -*/ - -/*! \fn void QTestEventList::addKeyRelease(Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - Adds a new key release to the list. The event will release the key \a qtKey with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyRelease() - -*/ - -/*! \fn void QTestEventList::addKeyEvent(QTest::KeyAction action, Qt::Key qtKey, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - \internal -*/ - -/*! \fn void QTestEventList::addKeyClick(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - \overload - - Adds a new key click to the list. The event will simulate the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyClick() - -*/ - -/*! \fn void QTestEventList::addKeyPress(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - \overload - - Adds a new key press to the list. The event will press the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyPress() -*/ - -/*! \fn void QTestEventList::addKeyRelease(char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - \overload - - Adds a new key release to the list. The event will release the key \a ascii with the modifier \a modifiers and then wait for \a msecs milliseconds. - - \sa QTest::keyRelease() -*/ - -/*! \fn void QTestEventList::addKeyClicks(const QString &keys, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - - Adds new keyboard entries to the list. The event will press the \a keys with the \a modifiers and wait \a msecs milliseconds between each key. - - \sa QTest::keyClicks() -*/ - -/*! \fn void QTestEventList::addKeyEvent(QTest::KeyAction action, char ascii, Qt::KeyboardModifiers modifiers = Qt::NoModifier, int msecs = -1) - \internal -*/ - -/*! \fn void QTestEventList::addDelay(int msecs) - - Adds a \a msecs milliseconds delay. - - \sa QTest::qWait() -*/ - -/*! \fn void QTestEventList::simulate(QWidget *w) - - Simulates the events from the list one by one on the widget \a w. - For an example, please read the \l QTestEventList class documentation. -*/ - -/*! \fn void QTestEventList::addMousePress(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) - - Add a mouse press to the list. The event will press the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. - - \sa QTest::mousePress() -*/ -/*! \fn void QTestEventList::addMouseRelease(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) - - Add a mouse release to the list. The event will release the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. - - \sa QTest::mouseRelease() -*/ -/*! \fn void QTestEventList::addMouseClick(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) - - Add a mouse click to the list. The event will click the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. - - \sa QTest::mouseClick() -*/ -/*! \fn void QTestEventList::addMouseDClick(Qt::MouseButton button, Qt::KeyboardModifiers modifiers = 0, QPoint pos = QPoint(), int delay=-1) - - Add a double mouse click to the list. The event will double click the \a button with optional \a modifiers at the position \a pos with an optional \a delay. The default position is the center of the widget. - - \sa QTest::mousePress() -*/ -/*! \fn void QTestEventList::addMouseMove(QPoint pos = QPoint(), int delay=-1) - - Adds a mouse move to the list. The event will move the mouse to the position \a pos. If a \a delay (in milliseconds) is set, the test will wait after moving the mouse. The default position is the center of the widget. - - \sa QTest::mousePress() -*/ - diff --git a/doc/src/classes/qvarlengtharray.qdoc b/doc/src/classes/qvarlengtharray.qdoc deleted file mode 100644 index 9cc7bef..0000000 --- a/doc/src/classes/qvarlengtharray.qdoc +++ /dev/null @@ -1,274 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QVarLengthArray - \brief The QVarLengthArray class provides a low-level variable-length array. - - \ingroup tools - \reentrant - - The C++ language doesn't support variable-length arrays on the stack. - For example, the following code won't compile: - - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 0 - - The alternative is to allocate the array on the heap (with - \c{new}): - - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 1 - - However, if myfunc() is called very frequently from the - application's inner loop, heap allocation can be a major source - of slowdown. - - QVarLengthArray is an attempt to work around this gap in the C++ - language. It allocates a certain number of elements on the stack, - and if you resize the array to a larger size, it automatically - uses the heap instead. Stack allocation has the advantage that - it is much faster than heap allocation. - - Example: - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 2 - - In the example above, QVarLengthArray will preallocate 1024 - elements on the stack and use them unless \c{n + 1} is greater - than 1024. If you omit the second template argument, - QVarLengthArray's default of 256 is used. - - QVarLengthArray's value type must be an \l{assignable data type}. - This covers most data types that are commonly used, but the - compiler won't let you, for example, store a QWidget as a value; - instead, store a QWidget *. - - QVarLengthArray, like QVector, provides a resizable array data - structure. The main differences between the two classes are: - - \list - \o QVarLengthArray's API is much more low-level. It provides no - iterators and lacks much of QVector's functionality. - - \o QVarLengthArray doesn't initialize the memory if the value is - a basic type. (QVector always does.) - - \o QVector uses \l{implicit sharing} as a memory optimization. - QVarLengthArray doesn't provide that feature; however, it - usually produces slightly better performance due to reduced - overhead, especially in tight loops. - \endlist - - In summary, QVarLengthArray is a low-level optimization class - that only makes sense in very specific cases. It is used a few - places inside Qt and was added to Qt's public API for the - convenience of advanced users. - - \sa QVector, QList, QLinkedList -*/ - -/*! \fn QVarLengthArray::QVarLengthArray(int size) - - Constructs an array with an initial size of \a size elements. - - If the value type is a primitive type (e.g., char, int, float) or - a pointer type (e.g., QWidget *), the elements are not - initialized. For other types, the elements are initialized with a - \l{default-constructed value}. -*/ - -/*! \fn QVarLengthArray::~QVarLengthArray() - - Destroys the array. -*/ - -/*! \fn int QVarLengthArray::size() const - - Returns the number of elements in the array. - - \sa isEmpty(), resize() -*/ - -/*! \fn int QVarLengthArray::count() const - - Same as size(). - - \sa isEmpty(), resize() -*/ - -/*! \fn bool QVarLengthArray::isEmpty() const - - Returns true if the array has size 0; otherwise returns false. - - \sa size(), resize() -*/ - -/*! \fn void QVarLengthArray::clear() - - Removes all the elements from the array. - - Same as resize(0). -*/ - -/*! \fn void QVarLengthArray::resize(int size) - - Sets the size of the array to \a size. If \a size is greater than - the current size, elements are added to the end. If \a size is - less than the current size, elements are removed from the end. - - If the value type is a primitive type (e.g., char, int, float) or - a pointer type (e.g., QWidget *), new elements are not - initialized. For other types, the elements are initialized with a - \l{default-constructed value}. - - \sa size() -*/ - -/*! \fn int QVarLengthArray::capacity() const - - Returns the maximum number of elements that can be stored in the - array without forcing a reallocation. - - The sole purpose of this function is to provide a means of fine - tuning QVarLengthArray's memory usage. In general, you will rarely ever - need to call this function. If you want to know how many items are - in the array, call size(). - - \sa reserve() -*/ - -/*! \fn void QVarLengthArray::reserve(int size) - - Attempts to allocate memory for at least \a size elements. If you - know in advance how large the array can get, you can call this - function and if you call resize() often, you are likely to get - better performance. If \a size is an underestimate, the worst - that will happen is that the QVarLengthArray will be a bit - slower. - - The sole purpose of this function is to provide a means of fine - tuning QVarLengthArray's memory usage. In general, you will - rarely ever need to call this function. If you want to change the - size of the array, call resize(). - - \sa capacity() -*/ - -/*! \fn T &QVarLengthArray::operator[](int i) - - Returns a reference to the item at index position \a i. - - \a i must be a valid index position in the array (i.e., 0 <= \a i - < size()). - - \sa data() -*/ - -/*! \fn const T &QVarLengthArray::operator[](int i) const - - \overload -*/ - - -/*! - \fn void QVarLengthArray::append(const T &t) - - Appends item \a t to the array, extending the array if necessary. - - \sa removeLast() -*/ - - -/*! - \fn inline void QVarLengthArray::removeLast() - \since 4.5 - - Decreases the size of the array by one. The allocated size is not changed. - - \sa append() -*/ - -/*! - \fn void QVarLengthArray::append(const T *buf, int size) - - Appends \a size amount of items referenced by \a buf to this array. -*/ - - -/*! \fn T *QVarLengthArray::data() - - Returns a pointer to the data stored in the array. The pointer can - be used to access and modify the items in the array. - - Example: - \snippet doc/src/snippets/code/doc_src_qvarlengtharray.qdoc 3 - - The pointer remains valid as long as the array isn't reallocated. - - This function is mostly useful to pass an array to a function - that accepts a plain C++ array. - - \sa constData(), operator[]() -*/ - -/*! \fn const T *QVarLengthArray::data() const - - \overload -*/ - -/*! \fn const T *QVarLengthArray::constData() const - - Returns a const pointer to the data stored in the array. The - pointer can be used to access the items in the array. The - pointer remains valid as long as the array isn't reallocated. - - This function is mostly useful to pass an array to a function - that accepts a plain C++ array. - - \sa data(), operator[]() -*/ - -/*! \fn QVarLengthArray<T, Prealloc> &QVarLengthArray::operator=(const QVarLengthArray<T, Prealloc> &other) - Assigns \a other to this array and returns a reference to this array. - */ - -/*! \fn QVarLengthArray::QVarLengthArray(const QVarLengthArray<T, Prealloc> &other) - Constructs a copy of \a other. - */ - diff --git a/doc/src/classes/qwaitcondition.qdoc b/doc/src/classes/qwaitcondition.qdoc deleted file mode 100644 index f19f51e..0000000 --- a/doc/src/classes/qwaitcondition.qdoc +++ /dev/null @@ -1,188 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/*! - \class QWaitCondition - \brief The QWaitCondition class provides a condition variable for - synchronizing threads. - - \threadsafe - - \ingroup thread - \ingroup environment - - QWaitCondition allows a thread to tell other threads that some - sort of condition has been met. One or many threads can block - waiting for a QWaitCondition to set a condition with wakeOne() or - wakeAll(). Use wakeOne() to wake one randomly selected condition or - wakeAll() to wake them all. - - For example, let's suppose that we have three tasks that should - be performed whenever the user presses a key. Each task could be - split into a thread, each of which would have a - \l{QThread::run()}{run()} body like this: - - \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 0 - - Here, the \c keyPressed variable is a global variable of type - QWaitCondition. - - A fourth thread would read key presses and wake the other three - threads up every time it receives one, like this: - - \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 1 - - The order in which the three threads are woken up is undefined. - Also, if some of the threads are still in \c do_something() when - the key is pressed, they won't be woken up (since they're not - waiting on the condition variable) and so the task will not be - performed for that key press. This issue can be solved using a - counter and a QMutex to guard it. For example, here's the new - code for the worker threads: - - \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 2 - - Here's the code for the fourth thread: - - \snippet doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp 3 - - The mutex is necessary because the results of two threads - attempting to change the value of the same variable - simultaneously are unpredictable. - - Wait conditions are a powerful thread synchronization primitive. - The \l{threads/waitconditions}{Wait Conditions} example shows how - to use QWaitCondition as an alternative to QSemaphore for - controlling access to a circular buffer shared by a producer - thread and a consumer thread. - - \sa QMutex, QSemaphore, QThread, {Wait Conditions Example} -*/ - -/*! - \fn QWaitCondition::QWaitCondition() - - Constructs a new wait condition object. -*/ - -/*! - \fn QWaitCondition::~QWaitCondition() - - Destroys the wait condition object. -*/ - -/*! - \fn void QWaitCondition::wakeOne() - - Wakes one thread waiting on the wait condition. The thread that - is woken up depends on the operating system's scheduling - policies, and cannot be controlled or predicted. - - If you want to wake up a specific thread, the solution is - typically to use different wait conditions and have different - threads wait on different conditions. - - \sa wakeAll() -*/ - -/*! - \fn void QWaitCondition::wakeAll() - - Wakes all threads waiting on the wait condition. The order in - which the threads are woken up depends on the operating system's - scheduling policies and cannot be controlled or predicted. - - \sa wakeOne() -*/ - -/*! - \fn bool QWaitCondition::wait(QMutex *mutex, unsigned long time) - - Releases the locked \a mutex and waits on the wait condition. The - \a mutex must be initially locked by the calling thread. If \a - mutex is not in a locked state, this function returns - immediately. If \a mutex is a recursive mutex, this function - returns immediately. The \a mutex will be unlocked, and the - calling thread will block until either of these conditions is met: - - \list - \o Another thread signals it using wakeOne() or wakeAll(). This - function will return true in this case. - \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX - (the default), then the wait will never timeout (the event - must be signalled). This function will return false if the - wait timed out. - \endlist - - The mutex will be returned to the same locked state. This - function is provided to allow the atomic transition from the - locked state to the wait state. - - \sa wakeOne(), wakeAll() -*/ - -/*! - \fn bool QWaitCondition::wait(QReadWriteLock *readWriteLock, unsigned long time) - \since 4.4 - - Releases the locked \a readWriteLock and waits on the wait - condition. The \a readWriteLock must be initially locked by the - calling thread. If \a readWriteLock is not in a locked state, this - function returns immediately. The \a readWriteLock must not be - locked recursively, otherwise this function will not release the - lock properly. The \a readWriteLock will be unlocked, and the - calling thread will block until either of these conditions is met: - - \list - \o Another thread signals it using wakeOne() or wakeAll(). This - function will return true in this case. - \o \a time milliseconds has elapsed. If \a time is \c ULONG_MAX - (the default), then the wait will never timeout (the event - must be signalled). This function will return false if the - wait timed out. - \endlist - - The \a readWriteLock will be returned to the same locked - state. This function is provided to allow the atomic transition - from the locked state to the wait state. - - \sa wakeOne(), wakeAll() -*/ diff --git a/doc/src/codecs.qdoc b/doc/src/codecs.qdoc deleted file mode 100644 index 7359b79..0000000 --- a/doc/src/codecs.qdoc +++ /dev/null @@ -1,534 +0,0 @@ -/**************************************************************************** -** -** 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 codec-big5.html - \title Big5 Text Codec - \ingroup codecs - - The Big5 codec provides conversion to and from the Big5 encoding. - The code was originally contributed by Ming-Che Chuang - \<mingche@cobra.ee.ntu.edu.tw\> for the Big-5+ encoding, and was - included in Qt with the author's permission, and the grateful - thanks of the Qt team. (Note: Ming-Che's code is QPL'd, as - per an mail to qt-info@nokia.com.) - - However, since Big-5+ was never formally approved, and was never - used by anyone, the Taiwan Free Software community and the Li18nux - Big5 Standard Subgroup agree that the de-facto standard Big5-ETen - (zh_TW.Big5 or zh_TW.TW-Big5) be used instead. - - The Big5 is currently implemented as a pure subset of the - Big5-HKSCS codec, so more fine-tuning is needed to make it - identical to the standard Big5 mapping as determined by - Li18nux-Big5. See \l{http://www.autrijus.org/xml/} for the draft - Big5 (2002) standard. - - James Su \<suzhe@turbolinux.com.cn\> \<suzhe@gnuchina.org\> - generated the Big5-HKSCS-to-Unicode tables with a very - space-efficient algorithm. He generously donated his code to glibc - in May 2002. Subsequently, James has kindly allowed Anthony Fok - \<anthony@thizlinux.com\> \<foka@debian.org\> to adapt the code - for Qt. - - \legalese - Copyright (C) 2000 Ming-Che Chuang \BR - Copyright (C) 2002 James Su, Turbolinux Inc. \BR - Copyright (C) 2002 Anthony Fok, ThizLinux Laboratory Ltd. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codec-big5hkscs.html - \title Big5-HKSCS Text Codec - \ingroup codecs - - The Big5-HKSCS codec provides conversion to and from the - Big5-HKSCS encoding. - - The codec grew out of the QBig5Codec originally contributed by - Ming-Che Chuang \<mingche@cobra.ee.ntu.edu.tw\>. James Su - \<suzhe@turbolinux.com.cn\> \<suzhe@gnuchina.org\> and Anthony Fok - \<anthony@thizlinux.com\> \<foka@debian.org\> implemented HKSCS-1999 - QBig5hkscsCodec for Qt-2.3.x, but it was too late in Qt development - schedule to be officially included in the Qt-2.3.x series. - - Wu Yi \<wuyi@hancom.com\> ported the HKSCS-1999 QBig5hkscsCodec to - Qt-3.0.1 in March 2002. - - With the advent of the new HKSCS-2001 standard, James Su - \<suzhe@turbolinux.com.cn\> \<suzhe@gnuchina.org\> generated the - Big5-HKSCS<->Unicode tables with a very space-efficient algorithm. - He generously donated his code to glibc in May 2002. Subsequently, - James has generously allowed Anthony Fok to adapt the code for - Qt-3.0.5. - - Currently, the Big5-HKSCS tables are generated from the following - sources, and with the Euro character added: - \list 1 - \o \l{http://www.microsoft.com/typography/unicode/950.txt} - \o \l{http://www.info.gov.hk/digital21/chi/hkscs/download/big5-iso.txt} - \o \l{http://www.info.gov.hk/digital21/chi/hkscs/download/big5cmp.txt} - \endlist - - There may be more fine-tuning to the QBig5hkscsCodec to maximize its - compatibility with the standard Big5 (2002) mapping as determined by - Li18nux Big5 Standard Subgroup. See \l{http://www.autrijus.org/xml/} - for the various Big5 CharMapML tables. - - \legalese - Copyright (C) 2000 Ming-Che Chuang \BR - Copyright (C) 2001, 2002 James Su, Turbolinux Inc. \BR - Copyright (C) 2002 WU Yi, HancomLinux Inc. \BR - Copyright (C) 2001, 2002 Anthony Fok, ThizLinux Laboratory Ltd. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codec-eucjp.html - \title EUC-JP Text Codec - \ingroup codecs - - The EUC-JP codec provides conversion to and from EUC-JP, the main - legacy encoding for Unix machines in Japan. - - The environment variable \c UNICODEMAP_JP can be used to - fine-tune the JIS, Shift-JIS, and EUC-JP codecs. The \l{ISO - 2022-JP (JIS) Text Codec} documentation describes how to use this - variable. - - Most of the code here was written by Serika Kurusugawa, - a.k.a. Junji Takagi, and is included in Qt with the author's - permission and the grateful thanks of the Qt team. Here is - the copyright statement for that code: - - \legalese - - Copyright (C) 1999 Serika Kurusugawa. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS". - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codec-euckr.html - \title EUC-KR Text Codec - \ingroup codecs - - The EUC-KR codec provides conversion to and from EUC-KR, KR, the - main legacy encoding for Unix machines in Korea. - - It was largely written by Mizi Research Inc. Here is the - copyright statement for the code as it was at the point of - contribution. The subsequent modifications are covered by - the usual copyright for Qt. - - \legalese - - Copyright (C) 1999-2000 Mizi Research Inc. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codec-gbk.html - \title GBK Text Codec - \ingroup codecs - - The GBK codec provides conversion to and from the Chinese - GB18030/GBK/GB2312 encoding. - - GBK, formally the Chinese Internal Code Specification, is a commonly - used extension of GB 2312-80. Microsoft Windows uses it under the - name codepage 936. - - GBK has been superseded by the new Chinese national standard - GB 18030-2000, which added a 4-byte encoding while remaining - compatible with GB2312 and GBK. The new GB 18030-2000 may be described - as a special encoding of Unicode 3.x and ISO-10646-1. - - Special thanks to charset gurus Markus Scherer (IBM), - Dirk Meyer (Adobe Systems) and Ken Lunde (Adobe Systems) for publishing - an excellent GB 18030-2000 summary and specification on the Internet. - Some must-read documents are: - - \list - \o \l{ftp://ftp.oreilly.com/pub/examples/nutshell/cjkv/pdf/GB18030_Summary.pdf} - \o \l{http://oss.software.ibm.com/cvs/icu/~checkout~/charset/source/gb18030/gb18030.html} - \o \l{http://oss.software.ibm.com/cvs/icu/~checkout~/charset/data/xml/gb-18030-2000.xml} - \endlist - - The GBK codec was contributed to Qt by - Justin Yu \<justiny@turbolinux.com.cn\> and - Sean Chen \<seanc@turbolinux.com.cn\>. They may also be reached at - Yu Mingjian \<yumj@sun.ihep.ac.cn\>, \<yumingjian@china.com\> - Chen Xiangyang \<chenxy@sun.ihep.ac.cn\> - - The GB18030 codec Qt functions were contributed to Qt by - James Su \<suzhe@gnuchina.org\>, \<suzhe@turbolinux.com.cn\> - who pioneered much of GB18030 development on GNU/Linux systems. - - The GB18030 codec was contributed to Qt by - Anthony Fok \<anthony@thizlinux.com\>, \<foka@debian.org\> - using a Perl script to generate C++ tables from gb-18030-2000.xml - while merging contributions from James Su, Justin Yu and Sean Chen. - A copy of the source Perl script is available at - \l{http://people.debian.org/~foka/gb18030/gen-qgb18030codec.pl} - - The copyright notice for their code follows: - - \legalese - Copyright (C) 2000 TurboLinux, Inc. Written by Justin Yu and Sean Chen. \BR - Copyright (C) 2001, 2002 Turbolinux, Inc. Written by James Su. \BR - Copyright (C) 2001, 2002 ThizLinux Laboratory Ltd. Written by Anthony Fok. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codecs-jis.html - \title ISO 2022-JP (JIS) Text Codec - \ingroup codecs - - The JIS codec provides conversion to and from ISO 2022-JP. - - The environment variable \c UNICODEMAP_JP can be used to - fine-tune the JIS, Shift-JIS, and EUC-JP codecs. The mapping - names are as for the Japanese XML working group's \link - http://www.y-adagio.com/public/standards/tr_xml_jpf/toc.htm XML - Japanese Profile\endlink, because it names and explains all the - widely used mappings. Here are brief descriptions, written by - Serika Kurusugawa: - - \list - - \o "unicode-0.9" or "unicode-0201" for Unicode style. This assumes - JISX0201 for 0x00-0x7f. (0.9 is a table version of jisx02xx mapping - used for Unicode 1.1.) - - \o "unicode-ascii" This assumes US-ASCII for 0x00-0x7f; some - chars (JISX0208 0x2140 and JISX0212 0x2237) are different from - Unicode 1.1 to avoid conflict. - - \o "open-19970715-0201" ("open-0201" for convenience) or - "jisx0221-1995" for JISX0221-JISX0201 style. JIS X 0221 is JIS - version of Unicode, but a few chars (0x5c, 0x7e, 0x2140, 0x216f, - 0x2131) are different from Unicode 1.1. This is used when 0x5c is - treated as YEN SIGN. - - \o "open-19970715-ascii" ("open-ascii" for convenience) for - JISX0221-ASCII style. This is used when 0x5c is treated as REVERSE - SOLIDUS. - - \o "open-19970715-ms" ("open-ms" for convenience) or "cp932" for - Microsoft Windows style. Windows Code Page 932. Some chars (0x2140, - 0x2141, 0x2142, 0x215d, 0x2171, 0x2172) are different from Unicode - 1.1. - - \o "jdk1.1.7" for Sun's JDK style. Same as Unicode 1.1, except that - JIS 0x2140 is mapped to UFF3C. Either ASCII or JISX0201 can be used - for 0x00-0x7f. - - \endlist - - In addition, the extensions "nec-vdc", "ibm-vdc" and "udc" are - supported. - - For example, if you want to use Unicode style conversion but with - NEC's extension, set \c UNICODEMAP_JP to \c {unicode-0.9, - nec-vdc}. (You will probably need to quote that in a shell - command.) - - Most of the code here was written by Serika Kurusugawa, - a.k.a. Junji Takagi, and is included in Qt with the author's - permission and the grateful thanks of the Qt team. Here is - the copyright statement for that code: - - \legalese - - Copyright (C) 1999 Serika Kurusugawa. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS". - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codec-sjis.html - \title Shift-JIS Text Codec - \ingroup codecs - - The Shift-JIS codec provides conversion to and from Shift-JIS, an - encoding of JIS X 0201 Latin, JIS X 0201 Kana and JIS X 0208. - - The environment variable \c UNICODEMAP_JP can be used to - fine-tune the codec. The \l{ISO 2022-JP (JIS) Text Codec} - documentation describes how to use this variable. - - Most of the code here was written by Serika Kurusugawa, a.k.a. - Junji Takagi, and is included in Qt with the author's permission - and the grateful thanks of the Qt team. Here is the - copyright statement for the code as it was at the point of - contribution. The subsequent modifications are covered by - the usual copyright for Qt. - - \legalese - - Copyright (C) 1999 Serika Kurusugawa. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS". - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ - -/*! - \page codec-tscii.html - \title TSCII Text Codec - \ingroup codecs - - The TSCII codec provides conversion to and from the Tamil TSCII - encoding. - - TSCII, formally the Tamil Standard Code Information Interchange - specification, is a commonly used charset for Tamils. The - official page for the standard is at - \link http://www.tamil.net/tscii/ http://www.tamil.net/tscii/\endlink - - This codec uses the mapping table found at - \link http://www.geocities.com/Athens/5180/tsciiset.html - http://www.geocities.com/Athens/5180/tsciiset.html\endlink. - Tamil uses composed Unicode which might cause some - problems if you are using Unicode fonts instead of TSCII fonts. - - Most of the code was written by Hans Petter Bieker and is - included in Qt with the author's permission and the grateful - thanks of the Qt team. Here is the copyright statement for - the code as it was at the point of contribution. The - subsequent modifications are covered by the usual copyright for - Qt: - - \legalese - - Copyright (c) 2000 Hans Petter Bieker. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - \list 1 - \o Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - \o Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. - \endlist - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. - \endlegalese -*/ diff --git a/doc/src/compiler-notes.qdoc b/doc/src/compiler-notes.qdoc deleted file mode 100644 index 4873cf5..0000000 --- a/doc/src/compiler-notes.qdoc +++ /dev/null @@ -1,278 +0,0 @@ -/**************************************************************************** -** -** 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 compiler-notes.html - \ingroup platform-notes - \title Compiler Notes - \brief Information about the C++ compilers and tools used to build Qt. - - This page contains information about the C++ compilers and tools used - to build Qt on various platforms. - - \tableofcontents - - Please refer to the \l{Platform Notes} for information on the platforms - Qt is currently known to run on, and see the \l{Supported Platforms} - page for information about the status of each platform. - - If you have anything to add to this list or any of the platform or - compiler-specific pages, please submit it via the \l{Bug Report Form} - or through the \l{Public Qt Repository}. - - \section1 Supported Features - - Not all compilers used to build Qt are able to compile all modules. The following table - shows the compiler support for five modules that are not uniformly available for all - platforms and compilers. - - \table - \header \o Compiler \o{5,1} Features - \header \o \o Concurrent \o XmlPatterns \o WebKit \o CLucene \o Phonon - \row \o g++ 3.3 \o \o \bold{X} \o \o \bold{X} \o \bold{X} - \row \o g++ 3.4 and up \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} - \row - \row \o SunCC 5.5 \o \o \o \o \bold{X} \o \bold{X} - \row - \row \o aCC series 3 \o \o \o \o \bold{X} \o \bold{X} - \row \o aCC series 6 \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} - \row \o xlC 6 \o \o \o \o \bold{X} \o \bold{X} - \row \o Intel CC 10 \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} - \row - \row \o MSVC 2003 \o \bold{X} \o \bold{X} \o \o \bold{X} \o \bold{X} - \row \o MSVC 2005 and up \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} \o \bold{X} - \endtable - - \target GCC - \section1 GCC - - \section2 GCC on Windows (MinGW) - - We have tested Qt with this compiler on Windows XP. - The minimal version of MinGW supported is: - - \list - \o GCC 3.4.2 - \o MinGW runtime 3.7 - \o win32api 3.2 - \o binutils 2.15.91 - \o mingw32-make 3.80.0-3 - \endlist - - \section2 GCC 4.0.0 - - The released package of the compiler has some bugs that lead to miscompilations. - We recommend using GCC 4.0.1 or later, or to use a recent CVS snapshot of the - GCC 4.0 branch. The version of GCC 4.0.0 that is shipped with Mac OS X 10.4 - "Tiger" is known to work with Qt for Mac OS X. - - \section2 HP-UX - - The hpux-g++ platform is tested with GCC 3.4.4. - - \section2 Solaris - - Please use GCC 3.4.2 or later. - - \section2 Mac OS X - - Please use the latest GCC 3.3 from Apple or a later version of GCC 3. - The gcc 3.3 that is provided with Xcode 1.5 is known to generate bad code. - Use the November 2004 GCC 3.3 updater \l{http://connect.apple.com}{available from Apple}. - - \section2 GCC 3.4.6 (Debian 3.4.6-5) on AMD64 (x86_64) - - This compiler is known to miscompile some parts of Qt when doing a - release build. There are several workarounds: - - \list 1 - \o Use a debug build instead. - \o For each miscompilation encountered, recompile the file, removing the -O2 option. - \o Add -fno-gcse to the QMAKE_CXXFLAGS_RELEASE. - \endlist - - \section1 HP ANSI C++ (aCC) - - The hpux-acc-32 and hpux-acc-64 platforms are tested with aCC A.03.57. The - hpuxi-acc-32 and hpuxi-acc-64 platforms are tested with aCC A.06.10. - - \section1 Intel C++ Compiler - - Qt supports the Intel C++ compiler on both Windows and Linux. - However, there are a few issues on Linux (see the following - section). - - \section2 Intel C++ Compiler for Linux - - Nokia currently tests the following compilers: - - \list - - \o Intel(R) C++ Compiler for applications running on IA-32, - Version 10.1 Build 20080602 Package ID: l_cc_p_10.1.017 - - \o Intel(R) C++ Compiler for applications running on Intel(R) 64, - Version 10.1 Build 20080602 Package ID: l_cc_p_10.1.017 - - \endlist - - We do not currently test the IA-64 (Itanium) compiler. - - \section2 Known Issues with Intel C++ Compiler for Linux - - \list - - \o Precompiled header support does not work in version 10.0.025 - and older. For these compilers, you should configure Qt with - -no-pch. Precompiled header support works properly in version - 10.0.026 and later. - \o Version 10.0.026 for Intel 64 is known to miscompile qmake when - building in release mode. For now, configure Qt with - -debug. Version 10.1.008 and later can compile qmake in release - mode. - \o Versions 10.1.008 to 10.1.015 for both IA-32 and Intel 64 are - known crash with "(0): internal error: 0_47021" when compiling - QtXmlPatterns, QtWebKit, and Designer in release mode. Version - 10.1.017 compiles these modules correctly in release mode. - \endlist - - \section2 Intel C++ Compiler (Windows, Altix) - - Qt 4 has been tested successfully with: - - \list - \o Windows - Intel(R) C++ Compiler for 32-bit applications, - Version 8.1 Build 20050309Z Package ID: W_CC_PC_8.1.026 - \o Altix - Intel(R) C++ Itanium(R) Compiler for Itanium(R)-based - applications Version 8.1 Build 20050406 Package ID: l_cc_pc_8.1.030 - \endlist - - We currently only test the Intel compiler on 32-bit Windows versions. - - \section1 MIPSpro (IRIX) - - \bold{IRIX is an unsupported platform. See the \l{Supported Platforms} page - and Qt's Software's online \l{Platform Support Policy} page for details.} - - Qt 4.4.x requires MIPSpro version 7.4.2m. - - Note that MIPSpro version 7.4.4m is currently not supported, since it has - introduced a number of problems that have not yet been resolved. - We recommend using 7.4.2m for Qt development. However, please note the - unsupported status of this platform. - - \target Sun Studio - \section1 Forte Developer / Sun Studio (Solaris) - - \section2 Sun Studio - - Qt is tested using Sun Studio 8 (Sun CC 5.5). Go to - \l{Sun Studio Patches} page on Sun's Web site to download - the latest patches for your Sun compiler. - - \section2 Sun WorkShop 5.0 - - Sun WorkShop 5.0 is not supported with Qt 4. - - \section1 Visual Studio (Windows) - - We do most of our Windows development on Windows XP, using Microsoft - Visual Studio .NET 2005 and Visual Studio 2008 (both the 32- and 64-bit - versions). - - Qt works with the Standard Edition, the Professional Edition and Team - System Edition of Visual Studio 2005. - - We also test Qt 4 on Windows XP with Visual Studio .NET and Visual Studio 2003. - - In order to use Qt with the Visual Studio 2005/2008 Express Edition you need - to download and install the platform SDK. Due to limitations in the - Express Edition it is not possible for us to install the Qt Visual - Studio Integration. You will need to use our command line tools to - build Qt applications with this edition. - - The Visual C++ Linker doesn't understand filenames with spaces (as in - \c{C:\Program files\Qt\}) so you will have to move it to another place, - or explicitly set the path yourself; for example: - - \snippet doc/src/snippets/code/doc_src_compiler-notes.qdoc 0 - - If you are experiencing strange problems with using special flags that - modify the alignment of structure and union members (such as \c{/Zp2}) - then you will need to recompile Qt with the flags set for the - application as well. - - If you're using Visual Studio .NET (2002) Standard Edition, you should be - using the Qt binary package provided, and not the source package. - As the Standard Edition does not optimize compiled code, your compiled - version of Qt would perform suboptimally with respect to speed. - - With Visual Studio 2005 Service Pack 1 a bug was introduced which - causes Qt not to compile, this has been fixed with a hotfix available - from Microsoft. See this - \l{http://qt.nokia.com/developer/faqs/faq.2006-12-18.3281869860}{Knowledge Base entry} - for more information. - - \section1 IBM xlC (AIX) - - The makeC++SharedLib utility must be in your PATH and be up to date to - build shared libraries. From IBM's - \l{http://www.redbooks.ibm.com/abstracts/sg245674.html}{C and C++ Application Development on AIX} - Redbook: - - \list - \o "The second step is to use the makeC++SharedLib command to create the - shared object. The command has many optional arguments, but in its - simplest form, can be used as follows:" - \snippet doc/src/snippets/code/doc_src_compiler-notes.qdoc 1 - \o "The full path name to the command is not required; however, to avoid - this, you will have to add the directory in which it is located to - your PATH environment variable. The command is located in the - /usr/vacpp/bin directory with the VisualAge C++ Professional for AIX, - Version 5 compiler." - \endlist - - \section2 VisualAge C++ for AIX, Version 6.0 - - Make sure you have the - \l{http://www-1.ibm.com/support/search.wss?rs=32&tc=SSEP5D&dc=D400}{latest upgrades} - installed. -*/ diff --git a/doc/src/containers.qdoc b/doc/src/containers.qdoc deleted file mode 100644 index 49dae63..0000000 --- a/doc/src/containers.qdoc +++ /dev/null @@ -1,775 +0,0 @@ -/**************************************************************************** -** -** 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 containers - \title Generic Containers - \ingroup architecture - \ingroup groups - \keyword container class - \keyword container classes - - \brief Qt's template-based container classes. - - \tableofcontents - - \section1 Introduction - - The Qt library provides a set of general purpose template-based - container classes. These classes can be used to store items of a - specified type. For example, if you need a resizable array of - \l{QString}s, use QVector<QString>. - - These container classes are designed to be lighter, safer, and - easier to use than the STL containers. If you are unfamiliar with - the STL, or prefer to do things the "Qt way", you can use these - classes instead of the STL classes. - - The container classes are \l{implicitly shared}, they are - \l{reentrant}, and they are optimized for speed, low memory - consumption, and minimal inline code expansion, resulting in - smaller executables. In addition, they are \l{thread-safe} - in situations where they are used as read-only containers - by all threads used to access them. - - For traversing the items stored in a container, you can use one - of two types of iterators: \l{Java-style iterators} and - \l{STL-style iterators}. The Java-style iterators are easier to - use and provide high-level functionality, whereas the STL-style - iterators are slightly more efficient and can be used together - with Qt's and STL's \l{generic algorithms}. - - Qt also offers a \l{foreach} keyword that make it very - easy to iterate over all the items stored in a container. - - \section1 The Container Classes - - Qt provides the following container classes: - - \table - \header \o Class \o Summary - - \row \o \l{QList}<T> - \o This is by far the most commonly used container class. It - stores a list of values of a given type (T) that can be accessed - by index. Internally, the QList is implemented using an array, - ensuring that index-based access is very fast. - - Items can be added at either end of the list using - QList::append() and QList::prepend(), or they can be inserted in - the middle using QList::insert(). More than any other container - class, QList is highly optimized to expand to as little code as - possible in the executable. QStringList inherits from - QList<QString>. - - \row \o \l{QLinkedList}<T> - \o This is similar to QList, except that it uses - iterators rather than integer indexes to access items. It also - provides better performance than QList when inserting in the - middle of a huge list, and it has nicer iterator semantics. - (Iterators pointing to an item in a QLinkedList remain valid as - long as the item exists, whereas iterators to a QList can become - invalid after any insertion or removal.) - - \row \o \l{QVector}<T> - \o This stores an array of values of a given type at adjacent - positions in memory. Inserting at the front or in the middle of - a vector can be quite slow, because it can lead to large numbers - of items having to be moved by one position in memory. - - \row \o \l{QStack}<T> - \o This is a convenience subclass of QVector that provides - "last in, first out" (LIFO) semantics. It adds the following - functions to those already present in QVector: - \l{QStack::push()}{push()}, \l{QStack::pop()}{pop()}, - and \l{QStack::top()}{top()}. - - \row \o \l{QQueue}<T> - \o This is a convenience subclass of QList that provides - "first in, first out" (FIFO) semantics. It adds the following - functions to those already present in QList: - \l{QQueue::enqueue()}{enqueue()}, - \l{QQueue::dequeue()}{dequeue()}, and \l{QQueue::head()}{head()}. - - \row \o \l{QSet}<T> - \o This provides a single-valued mathematical set with fast - lookups. - - \row \o \l{QMap}<Key, T> - \o This provides a dictionary (associative array) that maps keys - of type Key to values of type T. Normally each key is associated - with a single value. QMap stores its data in Key order; if order - doesn't matter QHash is a faster alternative. - - \row \o \l{QMultiMap}<Key, T> - \o This is a convenience subclass of QMap that provides a nice - interface for multi-valued maps, i.e. maps where one key can be - associated with multiple values. - - \row \o \l{QHash}<Key, T> - \o This has almost the same API as QMap, but provides - significantly faster lookups. QHash stores its data in an - arbitrary order. - - \row \o \l{QMultiHash}<Key, T> - \o This is a convenience subclass of QHash that - provides a nice interface for multi-valued hashes. - - \endtable - - Containers can be nested. For example, it is perfectly possible - to use a QMap<QString, QList<int> >, where the key type is - QString and the value type QList<int>. The only pitfall is that - you must insert a space between the closing angle brackets (>); - otherwise the C++ compiler will misinterpret the two >'s as a - right-shift operator (>>) and report a syntax error. - - The containers are defined in individual header files with the - same name as the container (e.g., \c <QLinkedList>). For - convenience, the containers are forward declared in \c - <QtContainerFwd>. - - \keyword assignable data type - \keyword assignable data types - - The values stored in the various containers can be of any - \e{assignable data type}. To qualify, a type must provide a - default constructor, a copy constructor, and an assignment - operator. This covers most data types you are likely to want to - store in a container, including basic types such as \c int and \c - double, pointer types, and Qt data types such as QString, QDate, - and QTime, but it doesn't cover QObject or any QObject subclass - (QWidget, QDialog, QTimer, etc.). If you attempt to instantiate a - QList<QWidget>, the compiler will complain that QWidget's copy - constructor and assignment operators are disabled. If you want to - store these kinds of objects in a container, store them as - pointers, for example as QList<QWidget *>. - - Here's an example custom data type that meets the requirement of - an assignable data type: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 0 - - If we don't provide a copy constructor or an assignment operator, - C++ provides a default implementation that performs a - member-by-member copy. In the example above, that would have been - sufficient. Also, if you don't provide any constructors, C++ - provides a default constructor that initializes its member using - default constructors. Although it doesn't provide any - explicit constructors or assignment operator, the following data - type can be stored in a container: - - \snippet doc/src/snippets/streaming/main.cpp 0 - - Some containers have additional requirements for the data types - they can store. For example, the Key type of a QMap<Key, T> must - provide \c operator<(). Such special requirements are documented - in a class's detailed description. In some cases, specific - functions have special requirements; these are described on a - per-function basis. The compiler will always emit an error if a - requirement isn't met. - - Qt's containers provide operator<<() and operator>>() so that they - can easily be read and written using a QDataStream. This means - that the data types stored in the container must also support - operator<<() and operator>>(). Providing such support is - straightforward; here's how we could do it for the Movie struct - above: - - \snippet doc/src/snippets/streaming/main.cpp 1 - \codeline - \snippet doc/src/snippets/streaming/main.cpp 2 - - \keyword default-constructed values - - The documentation of certain container class functions refer to - \e{default-constructed values}; for example, QVector - automatically initializes its items with default-constructed - values, and QMap::value() returns a default-constructed value if - the specified key isn't in the map. For most value types, this - simply means that a value is created using the default - constructor (e.g. an empty string for QString). But for primitive - types like \c{int} and \c{double}, as well as for pointer types, - the C++ language doesn't specify any initialization; in those - cases, Qt's containers automatically initialize the value to 0. - - \section1 The Iterator Classes - - Iterators provide a uniform means to access items in a container. - Qt's container classes provide two types of iterators: Java-style - iterators and STL-style iterators. - - \section2 Java-Style Iterators - - The Java-style iterators are new in Qt 4 and are the standard - ones used in Qt applications. They are more convenient to use than - the STL-style iterators, at the price of being slightly less - efficient. Their API is modelled on Java's iterator classes. - - For each container class, there are two Java-style iterator data - types: one that provides read-only access and one that provides - read-write access. - - \table - \header \o Containers \o Read-only iterator - \o Read-write iterator - \row \o QList<T>, QQueue<T> \o QListIterator<T> - \o QMutableListIterator<T> - \row \o QLinkedList<T> \o QLinkedListIterator<T> - \o QMutableLinkedListIterator<T> - \row \o QVector<T>, QStack<T> \o QVectorIterator<T> - \o QMutableVectorIterator<T> - \row \o QSet<T> \o QSetIterator<T> - \o QMutableSetIterator<T> - \row \o QMap<Key, T>, QMultiMap<Key, T> \o QMapIterator<Key, T> - \o QMutableMapIterator<Key, T> - \row \o QHash<Key, T>, QMultiHash<Key, T> \o QHashIterator<Key, T> - \o QMutableHashIterator<Key, T> - \endtable - - In this discussion, we will concentrate on QList and QMap. The - iterator types for QLinkedList, QVector, and QSet have exactly - the same interface as QList's iterators; similarly, the iterator - types for QHash have the same interface as QMap's iterators. - - Unlike STL-style iterators (covered \l{STL-style - iterators}{below}), Java-style iterators point \e between items - rather than directly \e at items. For this reason, they are - either pointing to the very beginning of the container (before - the first item), at the very end of the container (after the last - item), or between two items. The diagram below shows the valid - iterator positions as red arrows for a list containing four - items: - - \img javaiterators1.png - - Here's a typical loop for iterating through all the elements of a - QList<QString> in order and printing them to the console: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 1 - - It works as follows: The QList to iterate over is passed to the - QListIterator constructor. At that point, the iterator is located - just in front of the first item in the list (before item "A"). - Then we call \l{QListIterator::hasNext()}{hasNext()} to - check whether there is an item after the iterator. If there is, we - call \l{QListIterator::next()}{next()} to jump over that - item. The next() function returns the item that it jumps over. For - a QList<QString>, that item is of type QString. - - Here's how to iterate backward in a QList: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 2 - - The code is symmetric with iterating forward, except that we - start by calling \l{QListIterator::toBack()}{toBack()} - to move the iterator after the last item in the list. - - The diagram below illustrates the effect of calling - \l{QListIterator::next()}{next()} and - \l{QListIterator::previous()}{previous()} on an iterator: - - \img javaiterators2.png - - The following table summarizes the QListIterator API: - - \table - \header \o Function \o Behavior - \row \o \l{QListIterator::toFront()}{toFront()} - \o Moves the iterator to the front of the list (before the first item) - \row \o \l{QListIterator::toBack()}{toBack()} - \o Moves the iterator to the back of the list (after the last item) - \row \o \l{QListIterator::hasNext()}{hasNext()} - \o Returns true if the iterator isn't at the back of the list - \row \o \l{QListIterator::next()}{next()} - \o Returns the next item and advances the iterator by one position - \row \o \l{QListIterator::peekNext()}{peekNext()} - \o Returns the next item without moving the iterator - \row \o \l{QListIterator::hasPrevious()}{hasPrevious()} - \o Returns true if the iterator isn't at the front of the list - \row \o \l{QListIterator::previous()}{previous()} - \o Returns the previous item and moves the iterator back by one position - \row \o \l{QListIterator::peekPrevious()}{peekPrevious()} - \o Returns the previous item without moving the iterator - \endtable - - QListIterator provides no functions to insert or remove items - from the list as we iterate. To accomplish this, you must use - QMutableListIterator. Here's an example where we remove all - odd numbers from a QList<int> using QMutableListIterator: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 3 - - The next() call in the loop is made every time. It jumps over the - next item in the list. The - \l{QMutableListIterator::remove()}{remove()} function removes the - last item that we jumped over from the list. The call to - \l{QMutableListIterator::remove()}{remove()} does not invalidate - the iterator, so it is safe to continue using it. This works just - as well when iterating backward: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 4 - - If we just want to modify the value of an existing item, we can - use \l{QMutableListIterator::setValue()}{setValue()}. In the code - below, we replace any value larger than 128 with 128: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 5 - - Just like \l{QMutableListIterator::remove()}{remove()}, - \l{QMutableListIterator::setValue()}{setValue()} operates on the - last item that we jumped over. If we iterate forward, this is the - item just before the iterator; if we iterate backward, this is - the item just after the iterator. - - The \l{QMutableListIterator::next()}{next()} function returns a - non-const reference to the item in the list. For simple - operations, we don't even need - \l{QMutableListIterator::setValue()}{setValue()}: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 6 - - As mentioned above, QLinkedList's, QVector's, and QSet's iterator - classes have exactly the same API as QList's. We will now turn to - QMapIterator, which is somewhat different because it iterates on - (key, value) pairs. - - Like QListIterator, QMapIterator provides - \l{QMapIterator::toFront()}{toFront()}, - \l{QMapIterator::toBack()}{toBack()}, - \l{QMapIterator::hasNext()}{hasNext()}, - \l{QMapIterator::next()}{next()}, - \l{QMapIterator::peekNext()}{peekNext()}, - \l{QMapIterator::hasPrevious()}{hasPrevious()}, - \l{QMapIterator::previous()}{previous()}, and - \l{QMapIterator::peekPrevious()}{peekPrevious()}. The key and - value components are extracted by calling key() and value() on - the object returned by next(), peekNext(), previous(), or - peekPrevious(). - - The following example removes all (capital, country) pairs where - the capital's name ends with "City": - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 7 - - QMapIterator also provides a key() and a value() function that - operate directly on the iterator and that return the key and - value of the last item that the iterator jumped above. For - example, the following code copies the contents of a QMap into a - QHash: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 8 - - If we want to iterate through all the items with the same - value, we can use \l{QMapIterator::findNext()}{findNext()} - or \l{QMapIterator::findPrevious()}{findPrevious()}. - Here's an example where we remove all the items with a particular - value: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 9 - - \section2 STL-Style Iterators - - STL-style iterators have been available since the release of Qt - 2.0. They are compatible with Qt's and STL's \l{generic - algorithms} and are optimized for speed. - - For each container class, there are two STL-style iterator types: - one that provides read-only access and one that provides - read-write access. Read-only iterators should be used wherever - possible because they are faster than read-write iterators. - - \table - \header \o Containers \o Read-only iterator - \o Read-write iterator - \row \o QList<T>, QQueue<T> \o QList<T>::const_iterator - \o QList<T>::iterator - \row \o QLinkedList<T> \o QLinkedList<T>::const_iterator - \o QLinkedList<T>::iterator - \row \o QVector<T>, QStack<T> \o QVector<T>::const_iterator - \o QVector<T>::iterator - \row \o QSet<T> \o QSet<T>::const_iterator - \o QSet<T>::iterator - \row \o QMap<Key, T>, QMultiMap<Key, T> \o QMap<Key, T>::const_iterator - \o QMap<Key, T>::iterator - \row \o QHash<Key, T>, QMultiHash<Key, T> \o QHash<Key, T>::const_iterator - \o QHash<Key, T>::iterator - \endtable - - The API of the STL iterators is modelled on pointers in an array. - For example, the \c ++ operator advances the iterator to the next - item, and the \c * operator returns the item that the iterator - points to. In fact, for QVector and QStack, which store their - items at adjacent memory positions, the - \l{QVector::iterator}{iterator} type is just a typedef for \c{T *}, - and the \l{QVector::iterator}{const_iterator} type is - just a typedef for \c{const T *}. - - In this discussion, we will concentrate on QList and QMap. The - iterator types for QLinkedList, QVector, and QSet have exactly - the same interface as QList's iterators; similarly, the iterator - types for QHash have the same interface as QMap's iterators. - - Here's a typical loop for iterating through all the elements of a - QList<QString> in order and converting them to lowercase: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 10 - - Unlike \l{Java-style iterators}, STL-style iterators point - directly at items. The begin() function of a container returns an - iterator that points to the first item in the container. The - end() function of a container returns an iterator to the - imaginary item one position past the last item in the container. - end() marks an invalid position; it must never be dereferenced. - It is typically used in a loop's break condition. If the list is - empty, begin() equals end(), so we never execute the loop. - - The diagram below shows the valid iterator positions as red - arrows for a vector containing four items: - - \img stliterators1.png - - Iterating backward with an STL-style iterator requires us to - decrement the iterator \e before we access the item. This - requires a \c while loop: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 11 - - In the code snippets so far, we used the unary \c * operator to - retrieve the item (of type QString) stored at a certain iterator - position, and we then called QString::toLower() on it. Most C++ - compilers also allow us to write \c{i->toLower()}, but some - don't. - - For read-only access, you can use const_iterator, constBegin(), - and constEnd(). For example: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 12 - - The following table summarizes the STL-style iterators' API: - - \table - \header \o Expression \o Behavior - \row \o \c{*i} \o Returns the current item - \row \o \c{++i} \o Advances the iterator to the next item - \row \o \c{i += n} \o Advances the iterator by \c n items - \row \o \c{--i} \o Moves the iterator back by one item - \row \o \c{i -= n} \o Moves the iterator back by \c n items - \row \o \c{i - j} \o Returns the number of items between iterators \c i and \c j - \endtable - - The \c{++} and \c{--} operators are available both as prefix - (\c{++i}, \c{--i}) and postfix (\c{i++}, \c{i--}) operators. The - prefix versions modify the iterators and return a reference to - the modified iterator; the postfix versions take a copy of the - iterator before they modify it, and return that copy. In - expressions where the return value is ignored, we recommend that - you use the prefix operators (\c{++i}, \c{--i}), as these are - slightly faster. - - For non-const iterator types, the return value of the unary \c{*} - operator can be used on the left side of the assignment operator. - - For QMap and QHash, the \c{*} operator returns the value - component of an item. If you want to retrieve the key, call key() - on the iterator. For symmetry, the iterator types also provide a - value() function to retrieve the value. For example, here's how - we would print all items in a QMap to the console: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 13 - - Thanks to \l{implicit sharing}, it is very inexpensive for a - function to return a container per value. The Qt API contains - dozens of functions that return a QList or QStringList per value - (e.g., QSplitter::sizes()). If you want to iterate over these - using an STL iterator, you should always take a copy of the - container and iterate over the copy. For example: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 14 - - This problem doesn't occur with functions that return a const or - non-const reference to a container. - - \l{Implicit sharing} has another consequence on STL-style - iterators: You must not take a copy of a container while - non-const iterators are active on that container. Java-style - iterators don't suffer from that limitation. - - \keyword foreach - \section1 The foreach Keyword - - If you just want to iterate over all the items in a container - in order, you can use Qt's \c foreach keyword. The keyword is a - Qt-specific addition to the C++ language, and is implemented - using the preprocessor. - - Its syntax is: \c foreach (\e variable, \e container) \e - statement. For example, here's how to use \c foreach to iterate - over a QLinkedList<QString>: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 15 - - The \c foreach code is significantly shorter than the equivalent - code that uses iterators: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 16 - - Unless the data type contains a comma (e.g., \c{QPair<int, - int>}), the variable used for iteration can be defined within the - \c foreach statement: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 17 - - And like any other C++ loop construct, you can use braces around - the body of a \c foreach loop, and you can use \c break to leave - the loop: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 18 - - With QMap and QHash, \c foreach accesses the value component of - the (key, value) pairs. If you want to iterate over both the keys - and the values, you can use iterators (which are fastest), or you - can write code like this: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 19 - - For a multi-valued map: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 20 - - Qt automatically takes a copy of the container when it enters a - \c foreach loop. If you modify the container as you are - iterating, that won't affect the loop. (If you don't modify the - container, the copy still takes place, but thanks to \l{implicit - sharing} copying a container is very fast.) Similarly, declaring - the variable to be a non-const reference, in order to modify the - current item in the list will not work either. - - In addition to \c foreach, Qt also provides a \c forever - pseudo-keyword for infinite loops: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 21 - - If you're worried about namespace pollution, you can disable - these macros by adding the following line to your \c .pro file: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 22 - - \section1 Other Container-Like Classes - - Qt includes three template classes that resemble containers in - some respects. These classes don't provide iterators and cannot - be used with the \c foreach keyword. - - \list - \o QVarLengthArray<T, Prealloc> provides a low-level - variable-length array. It can be used instead of QVector in - places where speed is particularly important. - - \o QCache<Key, T> provides a cache to store objects of a certain - type T associated with keys of type Key. - - \o QPair<T1, T2> stores a pair of elements. - \endlist - - Additional non-template types that compete with Qt's template - containers are QBitArray, QByteArray, QString, and QStringList. - - \section1 Algorithmic Complexity - - Algorithmic complexity is concerned about how fast (or slow) each - function is as the number of items in the container grow. For - example, inserting an item in the middle of a QLinkedList is an - extremely fast operation, irrespective of the number of items - stored in the QLinkedList. On the other hand, inserting an item - in the middle of a QVector is potentially very expensive if the - QVector contains many items, since half of the items must be - moved one position in memory. - - To describe algorithmic complexity, we use the following - terminology, based on the "big Oh" notation: - - \keyword constant time - \keyword logarithmic time - \keyword linear time - \keyword linear-logarithmic time - \keyword quadratic time - - \list - \o \bold{Constant time:} O(1). A function is said to run in constant - time if it requires the same amount of time no matter how many - items are present in the container. One example is - QLinkedList::insert(). - - \o \bold{Logarithmic time:} O(log \e n). A function that runs in - logarithmic time is a function whose running time is - proportional to the logarithm of the number of items in the - container. One example is qBinaryFind(). - - \o \bold{Linear time:} O(\e n). A function that runs in linear time - will execute in a time directly proportional to the number of - items stored in the container. One example is - QVector::insert(). - - \o \bold{Linear-logarithmic time:} O(\e{n} log \e n). A function - that runs in linear-logarithmic time is asymptotically slower - than a linear-time function, but faster than a quadratic-time - function. - - \o \bold{Quadratic time:} O(\e{n}\unicode{178}). A quadratic-time function - executes in a time that is proportional to the square of the - number of items stored in the container. - \endlist - - The following table summarizes the algorithmic complexity of Qt's - sequential container classes: - - \table - \header \o \o Index lookup \o Insertion \o Prepending \o Appending - \row \o QLinkedList<T> \o O(\e n) \o O(1) \o O(1) \o O(1) - \row \o QList<T> \o O(1) \o O(n) \o Amort. O(1) \o Amort. O(1) - \row \o QVector<T> \o O(1) \o O(n) \o O(n) \o Amort. O(1) - \endtable - - In the table, "Amort." stands for "amortized behavior". For - example, "Amort. O(1)" means that if you call the function - only once, you might get O(\e n) behavior, but if you call it - multiple times (e.g., \e n times), the average behavior will be - O(1). - - The following table summarizes the algorithmic complexity of Qt's - associative containers and sets: - - \table - \header \o{1,2} \o{2,1} Key lookup \o{2,1} Insertion - \header \o Average \o Worst case \o Average \o Worst case - \row \o QMap<Key, T> \o O(log \e n) \o O(log \e n) \o O(log \e n) \o O(log \e n) - \row \o QMultiMap<Key, T> \o O(log \e n) \o O(log \e n) \o O(log \e n) \o O(log \e n) - \row \o QHash<Key, T> \o Amort. O(1) \o O(\e n) \o Amort. O(1) \o O(\e n) - \row \o QSet<Key> \o Amort. O(1) \o O(\e n) \o Amort. O(1) \o O(\e n) - \endtable - - With QVector, QHash, and QSet, the performance of appending items - is amortized O(log \e n). It can be brought down to O(1) by - calling QVector::reserve(), QHash::reserve(), or QSet::reserve() - with the expected number of items before you insert the items. - The next section discusses this topic in more depth. - - \section1 Growth Strategies - - QVector<T>, QString, and QByteArray store their items - contiguously in memory; QList<T> maintains an array of pointers - to the items it stores to provide fast index-based access (unless - T is a pointer type or a basic type of the size of a pointer, in - which case the value itself is stored in the array); QHash<Key, - T> keeps a hash table whose size is proportional to the number - of items in the hash. To avoid reallocating the data every single - time an item is added at the end of the container, these classes - typically allocate more memory than necessary. - - Consider the following code, which builds a QString from another - QString: - - \snippet doc/src/snippets/code/doc_src_containers.qdoc 23 - - We build the string \c out dynamically by appending one character - to it at a time. Let's assume that we append 15000 characters to - the QString string. Then the following 18 reallocations (out of a - possible 15000) occur when QString runs out of space: 4, 8, 12, - 16, 20, 52, 116, 244, 500, 1012, 2036, 4084, 6132, 8180, 10228, - 12276, 14324, 16372. At the end, the QString has 16372 Unicode - characters allocated, 15000 of which are occupied. - - The values above may seem a bit strange, but here are the guiding - principles: - \list - \o QString allocates 4 characters at a time until it reaches size 20. - \o From 20 to 4084, it advances by doubling the size each time. - More precisely, it advances to the next power of two, minus - 12. (Some memory allocators perform worst when requested exact - powers of two, because they use a few bytes per block for - book-keeping.) - \o From 4084 on, it advances by blocks of 2048 characters (4096 - bytes). This makes sense because modern operating systems - don't copy the entire data when reallocating a buffer; the - physical memory pages are simply reordered, and only the data - on the first and last pages actually needs to be copied. - \endlist - - QByteArray and QList<T> use more or less the same algorithm as - QString. - - QVector<T> also uses that algorithm for data types that can be - moved around in memory using memcpy() (including the basic C++ - types, the pointer types, and Qt's \l{shared classes}) but uses a - different algorithm for data types that can only be moved by - calling the copy constructor and a destructor. Since the cost of - reallocating is higher in that case, QVector<T> reduces the - number of reallocations by always doubling the memory when - running out of space. - - QHash<Key, T> is a totally different case. QHash's internal hash - table grows by powers of two, and each time it grows, the items - are relocated in a new bucket, computed as qHash(\e key) % - QHash::capacity() (the number of buckets). This remark applies to - QSet<T> and QCache<Key, T> as well. - - For most applications, the default growing algorithm provided by - Qt does the trick. If you need more control, QVector<T>, - QHash<Key, T>, QSet<T>, QString, and QByteArray provide a trio of - functions that allow you to check and specify how much memory to - use to store the items: - - \list - \o \l{QString::capacity()}{capacity()} returns the - number of items for which memory is allocated (for QHash and - QSet, the number of buckets in the hash table). - \o \l{QString::reserve()}{reserve}(\e size) explicitly - preallocates memory for \e size items. - \o \l{QString::squeeze()}{squeeze()} frees any memory - not required to store the items. - \endlist - - If you know approximately how many items you will store in a - container, you can start by calling reserve(), and when you are - done populating the container, you can call squeeze() to release - the extra preallocated memory. -*/ diff --git a/doc/src/coordsys.qdoc b/doc/src/coordsys.qdoc deleted file mode 100644 index 6042300..0000000 --- a/doc/src/coordsys.qdoc +++ /dev/null @@ -1,486 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/**************************************************************************** -** -** Qt Coordinate System Documentation. -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - -/*! - \page coordsys.html - \title The Coordinate System - \ingroup architecture - \brief Information about the coordinate system used by the paint - system. - - The coordinate system is controlled by the QPainter - class. Together with the QPaintDevice and QPaintEngine classes, - QPainter form the basis of Qt's painting system, Arthur. QPainter - is used to perform drawing operations, QPaintDevice is an - abstraction of a two-dimensional space that can be painted on - using a QPainter, and QPaintEngine provides the interface that the - painter uses to draw onto different types of devices. - - The QPaintDevice class is the base class of objects that can be - painted: Its drawing capabilities are inherited by the QWidget, - QPixmap, QPicture, QImage, and QPrinter classes. The default - coordinate system of a paint device has its origin at the top-left - corner. The \e x values increase to the right and the \e y values - increase downwards. The default unit is one pixel on pixel-based - devices and one point (1/72 of an inch) on printers. - - The mapping of the logical QPainter coordinates to the physical - QPaintDevice coordinates are handled by QPainter's transformation - matrix, viewport and "window". The logical and physical coordinate - systems coincide by default. QPainter also supports coordinate - transformations (e.g. rotation and scaling). - - \tableofcontents - - \section1 Rendering - - \section2 Logical Representation - - The size (width and height) of a graphics primitive always - correspond to its mathematical model, ignoring the width of the - pen it is rendered with: - - \table - \row - \o \inlineimage coordinatesystem-rect.png - \o \inlineimage coordinatesystem-line.png - \row - \o QRect(1, 2, 6, 4) - \o QLine(2, 7, 6, 1) - \endtable - - \section2 Aliased Painting - - When drawing, the pixel rendering is controlled by the - QPainter::Antialiasing render hint. - - The \l {QPainter::RenderHint}{RenderHint} enum is used to specify - flags to QPainter that may or may not be respected by any given - engine. The QPainter::Antialiasing value indicates that the engine - should antialias edges of primitives if possible, i.e. smoothing - the edges by using different color intensities. - - But by default the painter is \e aliased and other rules apply: - When rendering with a one pixel wide pen the pixels will be - rendered to the \e {right and below the mathematically defined - points}. For example: - - \table - \row - \o \inlineimage coordinatesystem-rect-raster.png - \o \inlineimage coordinatesystem-line-raster.png - - \row - \o - \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 0 - - \o - \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 1 - \endtable - - When rendering with a pen with an even number of pixels, the - pixels will be rendered symetrically around the mathematical - defined points, while rendering with a pen with an odd number of - pixels, the spare pixel will be rendered to the right and below - the mathematical point as in the one pixel case. See the QRectF - diagrams below for concrete examples. - - \table - \header - \o {3,1} QRectF - \row - \o \inlineimage qrect-diagram-zero.png - \o \inlineimage qrectf-diagram-one.png - \row - \o Logical representation - \o One pixel wide pen - \row - \o \inlineimage qrectf-diagram-two.png - \o \inlineimage qrectf-diagram-three.png - \row - \o Two pixel wide pen - \o Three pixel wide pen - \endtable - - Note that for historical reasons the return value of the - QRect::right() and QRect::bottom() functions deviate from the true - bottom-right corner of the rectangle. - - QRect's \l {QRect::right()}{right()} function returns \l - {QRect::left()}{left()} + \l {QRect::width()}{width()} - 1 and the - \l {QRect::bottom()}{bottom()} function returns \l - {QRect::top()}{top()} + \l {QRect::height()}{height()} - 1. The - bottom-right green point in the diagrams shows the return - coordinates of these functions. - - We recommend that you simply use QRectF instead: The QRectF class - defines a rectangle in the plane using floating point coordinates - for accuracy (QRect uses integer coordinates), and the - QRectF::right() and QRectF::bottom() functions \e do return the - true bottom-right corner. - - Alternatively, using QRect, apply \l {QRect::x()}{x()} + \l - {QRect::width()}{width()} and \l {QRect::y()}{y()} + \l - {QRect::height()}{height()} to find the bottom-right corner, and - avoid the \l {QRect::right()}{right()} and \l - {QRect::bottom()}{bottom()} functions. - - \section2 Anti-aliased Painting - - If you set QPainter's \l {QPainter::Antialiasing}{anti-aliasing} - render hint, the pixels will be rendered symetrically on both - sides of the mathematically defined points: - - \table - \row - \o \inlineimage coordinatesystem-rect-antialias.png - \o \inlineimage coordinatesystem-line-antialias.png - \row - \o - - \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 2 - - \o - \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 3 - \endtable - - \section1 Transformations - - By default, the QPainter operates on the associated device's own - coordinate system, but it also has complete support for affine - coordinate transformations. - - You can scale the coordinate system by a given offset using the - QPainter::scale() function, you can rotate it clockwise using the - QPainter::rotate() function and you can translate it (i.e. adding - a given offset to the points) using the QPainter::translate() - function. - - \table - \row - \o \inlineimage qpainter-clock.png - \o \inlineimage qpainter-rotation.png - \o \inlineimage qpainter-scale.png - \o \inlineimage qpainter-translation.png - \row - \o nop - \o \l {QPainter::rotate()}{rotate()} - \o \l {QPainter::scale()}{scale()} - \o \l {QPainter::translate()}{translate()} - \endtable - - You can also twist the coordinate system around the origin using - the QPainter::shear() function. See the \l {demos/affine}{Affine - Transformations} demo for a visualization of a sheared coordinate - system. All the transformation operations operate on QPainter's - transformation matrix that you can retrieve using the - QPainter::worldTransform() function. A matrix transforms a point - in the plane to another point. - - If you need the same transformations over and over, you can also - use QTransform objects and the QPainter::worldTransform() and - QPainter::setWorldTransform() functions. You can at any time save the - QPainter's transformation matrix by calling the QPainter::save() - function which saves the matrix on an internal stack. The - QPainter::restore() function pops it back. - - One frequent need for the transformation matrix is when reusing - the same drawing code on a variety of paint devices. Without - transformations, the results are tightly bound to the resolution - of the paint device. Printers have high resolution, e.g. 600 dots - per inch, whereas screens often have between 72 and 100 dots per - inch. - - \table 100% - \header - \o {2,1} Analog Clock Example - \row - \o \inlineimage coordinatesystem-analogclock.png - \o - The Analog Clock example shows how to draw the contents of a - custom widget using QPainter's transformation matrix. - - Qt's example directory provides a complete walk-through of the - example. Here, we will only review the example's \l - {QWidget::paintEvent()}{paintEvent()} function to see how we can - use the transformation matrix (i.e. QPainter's matrix functions) - to draw the clock's face. - - We recommend compiling and running this example before you read - any further. In particular, try resizing the window to different - sizes. - - \row - \o {2,1} - - \snippet examples/widgets/analogclock/analogclock.cpp 9 - - First, we set up the painter. We translate the coordinate system - so that point (0, 0) is in the widget's center, instead of being - at the top-left corner. We also scale the system by \c side / 100, - where \c side is either the widget's width or the height, - whichever is shortest. We want the clock to be square, even if the - device isn't. - - This will give us a 200 x 200 square area, with the origin (0, 0) - in the center, that we can draw on. What we draw will show up in - the largest possible square that will fit in the widget. - - See also the \l {Window-Viewport Conversion} section. - - \snippet examples/widgets/analogclock/analogclock.cpp 18 - - We draw the clock's hour hand by rotating the coordinate system - and calling QPainter::drawConvexPolygon(). Thank's to the - rotation, it's drawn pointed in the right direction. - - The polygon is specified as an array of alternating \e x, \e y - values, stored in the \c hourHand static variable (defined at the - beginning of the function), which corresponds to the four points - (2, 0), (0, 2), (-2, 0), and (0, -25). - - The calls to QPainter::save() and QPainter::restore() surrounding - the code guarantees that the code that follows won't be disturbed - by the transformations we've used. - - \snippet examples/widgets/analogclock/analogclock.cpp 24 - - We do the same for the clock's minute hand, which is defined by - the four points (1, 0), (0, 1), (-1, 0), and (0, -40). These - coordinates specify a hand that is thinner and longer than the - minute hand. - - \snippet examples/widgets/analogclock/analogclock.cpp 27 - - Finally, we draw the clock face, which consists of twelve short - lines at 30-degree intervals. At the end of that, the painter is - rotated in a way which isn't very useful, but we're done with - painting so that doesn't matter. - \endtable - - For a demonstation of Qt's ability to perform affine - transformations on painting operations, see the \l - {demos/affine}{Affine Transformations} demo which allows the user - to experiment with the transformation operations. See also the \l - {painting/transformations}{Transformations} example which shows - how transformations influence the way that QPainter renders - graphics primitives. In particular, it shows how the order of - transformations affects the result. - - For more information about the transformation matrix, see the - QTransform documentation. - - \section1 Window-Viewport Conversion - - When drawing with QPainter, we specify points using logical - coordinates which then are converted into the physical coordinates - of the paint device. - - The mapping of the logical coordinates to the physical coordinates - are handled by QPainter's world transformation \l - {QPainter::worldTransform()}{worldTransform()} (described in the \l - Transformations section), and QPainter's \l - {QPainter::viewport()}{viewport()} and \l - {QPainter::window()}{window()}. The viewport represents the - physical coordinates specifying an arbitrary rectangle. The - "window" describes the same rectangle in logical coordinates. By - default the logical and physical coordinate systems coincide, and - are equivalent to the paint device's rectangle. - - Using window-viewport conversion you can make the logical - coordinate system fit your preferences. The mechanism can also be - used to make the drawing code independent of the paint device. You - can, for example, make the logical coordinates extend from (-50, - -50) to (50, 50) with (0, 0) in the center by calling the - QPainter::setWindow() function: - - \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 4 - - Now, the logical coordinates (-50,-50) correspond to the paint - device's physical coordinates (0, 0). Independent of the paint - device, your painting code will always operate on the specified - logical coordinates. - - By setting the "window" or viewport rectangle, you perform a - linear transformation of the coordinates. Note that each corner of - the "window" maps to the corresponding corner of the viewport, and - vice versa. For that reason it normally is a good idea to let the - viewport and "window" maintain the same aspect ratio to prevent - deformation: - - \snippet doc/src/snippets/code/doc_src_coordsys.qdoc 5 - - If we make the logical coordinate system a square, we should also - make the viewport a square using the QPainter::setViewport() - function. In the example above we make it equivalent to the - largest square that fit into the paint device's rectangle. By - taking the paint device's size into consideration when setting the - window or viewport, it is possible to keep the drawing code - independent of the paint device. - - Note that the window-viewport conversion is only a linear - transformation, i.e. it does not perform clipping. This means that - if you paint outside the currently set "window", your painting is - still transformed to the viewport using the same linear algebraic - approach. - - \image coordinatesystem-transformations.png - - The viewport, "window" and transformation matrix determine how - logical QPainter coordinates map to the paint device's physical - coordinates. By default the world transformation matrix is the - identity matrix, and the "window" and viewport settings are - equivalent to the paint device's settings, i.e. the world, - "window" and device coordinate systems are equivalent, but as we - have seen, the systems can be manipulated using transformation - operations and window-viewport conversion. The illustration above - describes the process. - - \omit - \section1 Related Classes - - Qt's paint system, Arthur, is primarily based on the QPainter, - QPaintDevice, and QPaintEngine classes: - - \table - \header \o Class \o Description - \row - \o QPainter - \o - The QPainter class performs low-level painting on widgets and - other paint devices. QPainter can operate on any object that - inherits the QPaintDevice class, using the same code. - \row - \o QPaintDevice - \o - The QPaintDevice class is the base class of objects that can be - painted. Qt provides several devices: QWidget, QImage, QPixmap, - QPrinter and QPicture, and other devices can also be defined by - subclassing QPaintDevice. - \row - \o QPaintEngine - \o - The QPaintEngine class provides an abstract definition of how - QPainter draws to a given device on a given platform. Qt 4 - provides several premade implementations of QPaintEngine for the - different painter backends we support; it provides one paint - engine for each supported window system and painting - frameworkt. You normally don't need to use this class directly. - \endtable - - The 2D transformations of the coordinate system are specified - using the QTransform class: - - \table - \header \o Class \o Description - \row - \o QTransform - \o - A 3 x 3 transformation matrix. Use QTransform to rotate, shear, - scale, or translate the coordinate system. - \endtable - - In addition Qt provides several graphics primitive classes. Some - of these classes exist in two versions: an \c{int}-based version - and a \c{qreal}-based version. For these, the \c qreal version's - name is suffixed with an \c F. - - \table - \header \o Class \o Description - \row - \o \l{QPoint}(\l{QPointF}{F}) - \o - A single 2D point in the coordinate system. Most functions in Qt - that deal with points can accept either a QPoint, a QPointF, two - \c{int}s, or two \c{qreal}s. - \row - \o \l{QSize}(\l{QSizeF}{F}) - \o - A single 2D vector. Internally, QPoint and QSize are the same, but - a point is not the same as a size, so both classes exist. Again, - most functions accept either QSizeF, a QSize, two \c{int}s, or two - \c{qreal}s. - \row - \o \l{QRect}(\l{QRectF}{F}) - \o - A 2D rectangle. Most functions accept either a QRectF, a QRect, - four \c{int}s, or four \c {qreal}s. - \row - \o \l{QLine}(\l{QLineF}{F}) - \o - A 2D finite-length line, characterized by a start point and an end - point. - \row - \o \l{QPolygon}(\l{QPolygonF}{F}) - \o - A 2D polygon. A polygon is a vector of \c{QPoint(F)}s. If the - first and last points are the same, the polygon is closed. - \row - \o QPainterPath - \o - A vectorial specification of a 2D shape. Painter paths are the - ultimate painting primitive, in the sense that any shape - (rectange, ellipse, spline) or combination of shapes can be - expressed as a path. A path specifies both an outline and an area. - \row - \o QRegion - \o - An area in a paint device, expressed as a list of - \l{QRect}s. In general, we recommend using the vectorial - QPainterPath class instead of QRegion for specifying areas, - because QPainterPath handles painter transformations much better. - \endtable - \endomit - - \sa {Analog Clock Example}, {Transformations Example} -*/ diff --git a/doc/src/custom-types.qdoc b/doc/src/custom-types.qdoc deleted file mode 100644 index aa7d386..0000000 --- a/doc/src/custom-types.qdoc +++ /dev/null @@ -1,178 +0,0 @@ -/**************************************************************************** -** -** 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 custom-types.html - \title Creating Custom Qt Types - \ingroup architecture - \brief How to create and register new types with Qt. - - \tableofcontents - - \section1 Overview - - When creating user interfaces with Qt, particularly those with specialized controls and - features, developers sometimes need to create new data types that can be used alongside - or in place of Qt's existing set of value types. - - Standard types such as QSize, QColor and QString can all be stored in QVariant objects, - used as the types of properties in QObject-based classes, and emitted in signal-slot - communication. - - In this document, we take a custom type and describe how to integrate it into Qt's object - model so that it can be stored in the same way as standard Qt types. We then show how to - register the custom type to allow it to be used in signals and slots connections. - - \section1 Creating a Custom Type - - Before we begin, we need to ensure that the custom type we are creating meets all the - requirements imposed by QMetaType. In other words, it must provide: - - \list - \o a public default constructor, - \o a public copy constructor, and - \o a public destructor. - \endlist - - The following \c Message class definition includes these members: - - \snippet examples/tools/customtype/message.h custom type definition - - The class also provides a constructor for normal use and two public member functions - that are used to obtain the private data. - - \section1 Declaring the Type with QMetaType - - The \c Message class only needs a suitable implementation in order to be usable. - However, Qt's type system will not be able to understand how to store, retrieve - and serialize instances of this class without some assistance. For example, we - will be unable to store \c Message values in QVariant. - - The class in Qt responsible for custom types is QMetaType. To make the type known - to this class, we invoke the Q_DECLARE_METATYPE() macro on the class in the header - file where it is defined: - - \snippet examples/tools/customtype/message.h custom type meta-type declaration - - This now makes it possible for \c Message values to be stored in QVariant objects - and retrieved later. See the \l{Custom Type Example} for code that demonstrates - this. - - The Q_DECLARE_METATYPE() macro also makes it possible for these values to be used as - arguments to signals, but \e{only in direct signal-slot connections}. - To make the custom type generally usable with the signals and slots mechanism, we - need to perform some extra work. - - \section1 Creating and Destroying Custom Objects - - Although the declaration in the previous section makes the type available for use - in direct signal-slot connections, it cannot be used for queued signal-slot - connections, such as those that are made between objects in different threads. - This is because the meta-object system does not know how to handle creation and - destruction of objects of the custom type at run-time. - - To enable creation of objects at run-time, call the qRegisterMetaType() template - function to register it with the meta-object system. This also makes the type - available for queued signal-slot communication as long as you call it before you - make the first connection that uses the type. - - The \l{Queued Custom Type Example} declares a \c Block class which is registered - in the \c{main.cpp} file: - - \snippet examples/threads/queuedcustomtype/main.cpp main start - \dots - \snippet examples/threads/queuedcustomtype/main.cpp register meta-type for queued communications - \dots - \snippet examples/threads/queuedcustomtype/main.cpp main finish - - This type is later used in a signal-slot connection in the \c{window.cpp} file: - - \snippet examples/threads/queuedcustomtype/window.cpp Window constructor start - \dots - \snippet examples/threads/queuedcustomtype/window.cpp connecting signal with custom type - \dots - \snippet examples/threads/queuedcustomtype/window.cpp Window constructor finish - - If a type is used in a queued connection without being registered, a warning will be - printed at the console; for example: - - \code - QObject::connect: Cannot queue arguments of type 'Block' - (Make sure 'Block' is registered using qRegisterMetaType().) - \endcode - - \section1 Making the Type Printable - - It is often quite useful to make a custom type printable for debugging purposes, - as in the following code: - - \snippet examples/tools/customtype/main.cpp printing a custom type - - This is achieved by creating a streaming operator for the type, which is often - defined in the header file for that type: - - \snippet examples/tools/customtype/message.h custom type streaming operator - - The implementation for the \c Message type in the \l{Custom Type Example} - goes to some effort to make the printable representation as readable as - possible: - - \snippet examples/tools/customtype/message.cpp custom type streaming operator - - The output sent to the debug stream can, of course, be made as simple or as - complicated as you like. Note that the value returned by this function is - the QDebug object itself, though this is often obtained by calling the - maybeSpace() member function of QDebug that pads out the stream with space - characters to make it more readable. - - \section1 Further Reading - - The Q_DECLARE_METATYPE() macro and qRegisterMetaType() function documentation - contain more detailed information about their uses and limitations. - - The \l{Custom Type Example}{Custom Type}, - \l{Custom Type Sending Example}{Custom Type Sending} - and \l{Queued Custom Type Example}{Queued Custom Type} examples show how to - implement a custom type with the features outlined in this document. - - The \l{Debugging Techniques} document provides an overview of the debugging - mechanisms discussed above. -*/ diff --git a/doc/src/datastreamformat.qdoc b/doc/src/datastreamformat.qdoc deleted file mode 100644 index eac550c..0000000 --- a/doc/src/datastreamformat.qdoc +++ /dev/null @@ -1,376 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/**************************************************************************** -** -** Documentation of the Format of the QDataStream operators. -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - -/*! - \page datastreamformat.html - \title Format of the QDataStream Operators - \ingroup architecture - \brief Representations of data types that can be serialized by QDataStream. - - The \l QDataStream allows you to serialize some of the Qt data types. - The table below lists the data types that QDataStream can serialize - and how they are represented. The format described below is - \l{QDataStream::setVersion()}{version 8}. - - It is always best to cast integers to a Qt integer type, such as - qint16 or quint32, when reading and writing. This ensures that - you always know exactly what size integers you are reading and - writing, no matter what the underlying platform and architecture - the application happens to be running on. - - \table - \row \o bool - \o \list - \o boolean - \endlist - \row \o qint8 - \o \list - \o signed byte - \endlist - \row \o qint16 - \o \list - \o signed 16-bit integer - \endlist - \row \o qint32 - \o \list - \o signed 32-bit integer - \endlist - \row \o qint64 - \o \list - \o signed 64-bit integer - \endlist - \row \o quint8 - \o \list - \o unsigned byte - \endlist - \row \o quint16 - \o \list - \o unsigned 16-bit integer - \endlist - \row \o quint32 - \o \list - \o unsigned 32-bit integer - \endlist - \row \o quint64 - \o \list - \o unsigned 64-bit integer - \endlist - \row \o \c float - \o \list - \o 32-bit floating point number using the standard IEEE 754 format - \endlist - \row \o \c double - \o \list - \o 64-bit floating point number using the standard IEEE 754 format - \endlist - \row \o \c {const char *} - \o \list - \o The string length (quint32) - \o The string bytes, excluding the terminating 0 - \endlist - \row \o QBitArray - \o \list - \o The array size (quint32) - \o The array bits, i.e. (size + 7)/8 bytes - \endlist - \row \o QBrush - \o \list - \o The brush style (quint8) - \o The brush color (QColor) - \o If style is CustomPattern, the brush pixmap (QPixmap) - \endlist - \row \o QByteArray - \o \list - \o If the byte array is null: 0xFFFFFFFF (quint32) - \o Otherwise: the array size (quint32) followed by the array bytes, i.e. size bytes - \endlist - \row \o \l QColor - \o \list - \o Color spec (qint8) - \o Alpha value (quint16) - \o Red value (quint16) - \o Green value (quint16) - \o Blue value (quint16) - \o Pad value (quint16) - \endlist - \row \o QCursor - \o \list - \o Shape ID (qint16) - \o If shape is BitmapCursor: The bitmap (QPixmap), mask (QPixmap), and hot spot (QPoint) - \endlist - \row \o QDate - \o \list - \o Julian day (quint32) - \endlist - \row \o QDateTime - \o \list - \o Date (QDate) - \o Time (QTime) - \o 0 for Qt::LocalTime, 1 for Qt::UTC (quint8) - \endlist - \row \o QFont - \o \list - \o The family (QString) - \o The point size (qint16) - \o The style hint (quint8) - \o The char set (quint8) - \o The weight (quint8) - \o The font bits (quint8) - \endlist - \row \o QHash<Key, T> - \o \list - \o The number of items (quint32) - \o For all items, the key (Key) and value (T) - \endlist - \row \o QIcon - \o \list - \o The number of pixmap entries (quint32) - \o For all pixmap entries: - \list - \o The pixmap (QPixmap) - \o The file name (QString) - \o The pixmap size (QSize) - \o The \l{QIcon::Mode}{mode} (quint32) - \o The \l{QIcon::State}{state} (quint32) - \endlist - \endlist - \row \o QImage - \o \list - \o If the image is null a "null image" marker is saved; - otherwise the image is saved in PNG or BMP format (depending - on the stream version). If you want control of the format, - stream the image into a QBuffer (using QImageIO) and stream - that. - \endlist - \row \o QKeySequence - \o \list - \o A QList<int>, where each integer is a key in the key sequence - \endlist - \row \o QLinkedList<T> - \o \list - \o The number of items (quint32) - \o The items (T) - \endlist - \row \o QList<T> - \o \list - \o The number of items (quint32) - \o The items (T) - \endlist - \row \o QMap<Key, T> - \o \list - \o The number of items (quint32) - \o For all items, the key (Key) and value (T) - \endlist - \row \o QMatrix - \o \list - \o m11 (double) - \o m12 (double) - \o m21 (double) - \o m22 (double) - \o dx (double) - \o dy (double) - \endlist - \row \o QMatrix4x4 - \o \list - \o m11 (double) - \o m12 (double) - \o m13 (double) - \o m14 (double) - \o m21 (double) - \o m22 (double) - \o m23 (double) - \o m24 (double) - \o m31 (double) - \o m32 (double) - \o m33 (double) - \o m34 (double) - \o m41 (double) - \o m42 (double) - \o m43 (double) - \o m44 (double) - \endlist - \row \o QPair<T1, T2> - \o \list - \o first (T1) - \o second (T2) - \endlist - \row \o QPalette - \o The disabled, active, and inactive color groups, each of which consists - of the following: - \list - \o foreground (QBrush) - \o button (QBrush) - \o light (QBrush) - \o midlight (QBrush) - \o dark (QBrush) - \o mid (QBrush) - \o text (QBrush) - \o brightText (QBrush) - \o buttonText (QBrush) - \o base (QBrush) - \o background (QBrush) - \o shadow (QBrush) - \o highlight (QBrush) - \o highlightedText (QBrush) - \o link (QBrush) - \o linkVisited (QBrush) - \endlist - \row \o QPen - \o \list - \o The pen styles (quint8) - \o The pen width (quint16) - \o The pen color (QColor) - \endlist - \row \o QPicture - \o \list - \o The size of the picture data (quint32) - \o The raw bytes of picture data (char) - \endlist - \row \o QPixmap - \o \list - \o Save it as a PNG image. - \endlist - \row \o QPoint - \o \list - \o The x coordinate (qint32) - \o The y coordinate (qint32) - \endlist - \row \o QQuaternion - \o \list - \o The scalar component (double) - \o The x coordinate (double) - \o The y coordinate (double) - \o The z coordinate (double) - \endlist - \row \o QRect - \o \list - \o left (qint32) - \o top (qint32) - \o right (qint32) - \o bottom (qint32) - \endlist - \row \o QRegExp - \o \list - \o The regexp pattern (QString) - \o Case sensitivity (quint8) - \o Regular expression syntax (quint8) - \o Minimal matching (quint8) - \endlist - \row \o QRegion - \o \list - \o The size of the data, i.e. 8 + 16 * (number of rectangles) (quint32) - \o 10 (qint32) - \o The number of rectangles (quint32) - \o The rectangles in sequential order (QRect) - \endlist - \row \o QSize - \o \list - \o width (qint32) - \o height (qint32) - \endlist - \row \o QString - \o \list - \o If the string is null: 0xFFFFFFFF (quint32) - \o Otherwise: The string length in bytes (quint32) followed by the data in UTF-16 - \endlist - \row \o QTime - \o \list - \o Milliseconds since midnight (quint32) - \endlist - \row \o QTransform - \o \list - \o m11 (double) - \o m12 (double) - \o m13 (double) - \o m21 (double) - \o m22 (double) - \o m23 (double) - \o m31 (double) - \o m32 (double) - \o m33 (double) - \endlist - \row \o QUrl - \o \list - \o Holds an URL (QString) - \endlist - \row \o QVariant - \o \list - \o The type of the data (quint32) - \o The null flag (qint8) - \o The data of the specified type - \endlist - \row \o QVector2D - \o \list - \o the x coordinate (double) - \o the y coordinate (double) - \endlist - \row \o QVector3D - \o \list - \o the x coordinate (double) - \o the y coordinate (double) - \o the z coordinate (double) - \endlist - \row \o QVector4D - \o \list - \o the x coordinate (double) - \o the y coordinate (double) - \o the z coordinate (double) - \o the w coordinate (double) - \endlist - \row \o QVector<T> - \o \list - \o The number of items (quint32) - \o The items (T) - \endlist - \endtable -*/ diff --git a/doc/src/debug.qdoc b/doc/src/debug.qdoc deleted file mode 100644 index bedf73d..0000000 --- a/doc/src/debug.qdoc +++ /dev/null @@ -1,256 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/**************************************************************************** -** -** Qt Debugging Techniques -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - -/*! - \page debug.html - \title Debugging Techniques - \ingroup buildsystem - - 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/demos.qdoc b/doc/src/demos.qdoc deleted file mode 100644 index 69a943a..0000000 --- a/doc/src/demos.qdoc +++ /dev/null @@ -1,151 +0,0 @@ -/**************************************************************************** -** -** 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 demos.html - \title Qt Demonstrations - \brief Information about the demonstration programs provided with Qt. - \ingroup howto - - This is the list of demonstrations in Qt's \c demos directory. - These are larger and more complicated programs than the - \l{Qt Examples} and are used to highlight certain features of - Qt. You can launch any of these programs from the - \l{Examples and Demos Launcher} application. - - If you are new to Qt, and want to start developing applications, - you should probably start by going through the \l{Tutorials}. - - \section1 Painting - - \list - \o \l{demos/composition}{Composition Modes} demonstrates the range of - composition modes available with Qt. - \o \l{demos/deform}{Vector Deformation} demonstrates effects that are made - possible with a vector-oriented paint engine. - \o \l{demos/gradients}{Gradients} shows the different types of gradients - that are available in Qt. - \o \l{demos/pathstroke}{Path Stroking} shows Qt's built-in dash patterns - and shows how custom patterns can be used to extend the range of - available patterns. - \o \l{demos/affine}{Affine Transformations} demonstrates the different - affine transformations that can be used to influence painting operations. - \o \l{demos/arthurplugin}{Arthur Plugin} shows the widgets from the - other painting demos packaged as a custom widget plugin for \QD. - \endlist - - \section1 Item Views - - \list - \o \l{demos/interview}{Interview} shows the same model and selection being - shared between three different views. - \o \l{demos/spreadsheet}{Spreadsheet} demonstrates the use of a table view - as a spreadsheet, using custom delegates to render each item according to - the type of data it contains. - \endlist - - \section1 SQL - - \list - \o \l{demos/books}{Books} shows how Qt's SQL support and model/view integration - enables the user to modify the contents of a database without requiring - knowledge of SQL. - \o \l{demos/sqlbrowser}{SQL Browser} demonstrates a console for executing SQL - statements on a live database and provides a data browser for interactively - visualizing the results. - \endlist - - \section1 Rich Text - - \list - \o \l{demos/textedit}{Text Edit} shows Qt's rich text editing features and provides - an environment for experimenting with them. - \endlist - - \section1 Main Window - - \list - \o \l{demos/mainwindow}{Main Window} shows Qt's extensive support for main window - features, such as tool bars, dock windows, and menus. - \o \l{demos/macmainwindow}{Mac Main Window} shows how to create main window applications that has - the same appearance as other Mac OS X applications. - \endlist - - \section1 Graphics View - - \list - \o \l{demos/chip}{40000 Chips} uses the - \l{The Graphics View Framework}{Graphics View} framework to efficiently - display a large number of individual graphical items on a scrolling canvas, - highlighting features such as rotation, zooming, level of detail control, - and item selection. - \o \l{demos/embeddeddialogs}{Embedded Dialogs} showcases Qt 4.4's \e{Widgets on - the Canvas} feature by embedding a multitude of fully-working dialogs into a - scene. - \o \l{demos/boxes}{Boxes} showcases Qt's OpenGL support and the - integration with the Graphics View framework. - \endlist - - \section1 Tools - - \list - \o \l{demos/undo}{Undo Framework} demonstrates how Qt's - \l{Overview of Qt's Undo Framework}{undo framework} is used to - provide advanced undo/redo functionality. - \endlist - - \section1 QtWebKit - - \list - \o \l{Web Browser} demonstrates how Qt's \l{QtWebKit Module}{WebKit module} - can be used to implement a small Web browser. - \endlist - - \section1 Phonon - - \list - \o \l{demos/mediaplayer}{Media Player} demonstrates how the \l{Phonon Module} can be - used to implement a basic media player application. - \endlist - - \note The Phonon demos are currently not available for the MinGW platform. - -*/ diff --git a/doc/src/demos/qtdemo.qdoc b/doc/src/demos/qtdemo.qdoc new file mode 100644 index 0000000..60f896a --- /dev/null +++ b/doc/src/demos/qtdemo.qdoc @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** 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 qtdemo.html + \title Examples and Demos Launcher + \ingroup qttools + \keyword qtdemo + + The Examples and Demos Launcher (\c qtdemo) allows the user to browse the + examples and demonstrations included with Qt, access the documentation + associated with each of them, and launch them as separate applications. + + \image qtdemo.png + + The \c qtdemo executable should be installed alongside the + \l{Qt's Tools}{other tools} supplied with Qt. + + \list + \i On Windows, click the Start button, open the \e Programs submenu, open + the \e{Qt 4} submenu, and click \e{Examples and Demos}. + \i On Unix or Linux, you may find a \c qtdemo icon on the desktop background or + in the desktop start menu under the \e Programming or \e Development + submenus. You can launch this application from this icon. Alternatively, you can + enter \c qtdemo in a terminal window. + \i On Mac OS X, navigate to the \c /Developer/Applications/Qt directory in the + Finder and double click on the \c qtdemo.app icon. + \endlist +*/ diff --git a/doc/src/deployment.qdoc b/doc/src/deployment.qdoc deleted file mode 100644 index 9f8ee8f..0000000 --- a/doc/src/deployment.qdoc +++ /dev/null @@ -1,1478 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - -/*! - \group deployment - \title Deploying Qt Applications - \ingroup buildsystem - - Deploying an Qt application does not require any C++ - programming. All you need to do is to build Qt and your - application in release mode, following the procedures described in - this documentation. We will demonstrate the procedures in terms of - deploying the \l {tools/plugandpaint}{Plug & Paint} application - that is provided in Qt's examples directory. - - \section1 Static vs. Shared Libraries - - There are two ways of deploying an application: - - \list - \o Static Linking - \o Shared Libraries (Frameworks on Mac) - \endlist - - Static linking results in a stand-alone executable. The advantage - is that you will only have a few files to deploy. The - disadvantages are that the executables are large and with no - flexibility (i.e a new version of the application, or of Qt, will - require that the deployment process is repeated), and that you - cannot deploy plugins. - - To deploy plugin-based applications, you can use the shared - library approach. Shared libraries also provide smaller, more - flexible executables. For example, using the shared library - approach, the user is able to independently upgrade the Qt library - used by the application. - - Another reason why you might want to use the shared library - approach, is if you want to use the same Qt libraries for a family - of applications. In fact, if you download the binary installation - of Qt, you get Qt as a shared library. - - The disadvantage with the shared library approach is that you - will get more files to deploy. For more information, see - \l{sharedlibrary.html}{Creating Shared Libraries}. - - \section1 Deploying Qt's Libraries - - \table - \header - \o {4,1} Qt's Libraries - \row - \o \l {QtAssistant} - \o \l {QAxContainer} - \o \l {QAxServer} - \o \l {QtCore} - \row - \o \l {QtDBus} - \o \l {QtDesigner} - \o \l {QtGui} - \o \l {QtHelp} - \row - \o \l {QtNetwork} - \o \l {QtOpenGL} - \o \l {QtScript} - \o \l {QtScriptTools} - \row - \o \l {QtSql} - \o \l {QtSvg} - \o \l {QtWebKit} - \o \l {QtXml} - \row - \o \l {QtXmlPatterns} - \o \l {Phonon Module}{Phonon} - \o \l {Qt3Support} - \endtable - - Since Qt is not a system library, it has to be redistributed along - with your application; the minimum is to redistribute the run-time - of the libraries used by the application. Using static linking, - however, the Qt run-time is compiled into the executable. - - In particular, you will need to deploy Qt plugins, such as - JPEG support or SQL drivers. For more information about plugins, - see the \l {plugins-howto.html}{How to Create Qt Plugins} - documentation. - - When deploying an application using the shared library approach - you must ensure that the Qt libraries will use the correct path to - find the Qt plugins, documentation, translation etc. To do this you - can use a \c qt.conf file. For more information, see the \l {Using - qt.conf} documentation. - - Depending on configuration, compiler specific libraries must be - redistributed as well. For more information, see the platform - specific Application Dependencies sections: \l - {deployment-x11.html#application-dependencies}{X11}, \l - {deployment-windows.html#application-dependencies}{Windows}, \l - {deployment-mac.html#application-dependencies}{Mac}. - - \section1 Licensing - - Some of Qt's libraries are based on third party libraries that are - not licensed using the same dual-license model as Qt. As a result, - care must be taken when deploying applications that use these - libraries, particularly when the application is statically linked - to them. - - The following table contains an inexhaustive summary of the issues - you should be aware of. - - \table - \header \o Qt Library \o Dependency - \o Licensing Issue - \row \o QtHelp \o CLucene - \o The version of clucene distributed with Qt is licensed - under the GNU LGPL version 2.1 or later. This has implications for - developers of closed source applications. Please see - \l{QtHelp Module#License Information}{the QtHelp module documentation} - for more information. - - \row \o QtNetwork \o OpenSSL - \o Some configurations of QtNetwork use OpenSSL at run-time. Deployment - of OpenSSL libraries is subject to both licensing and export restrictions. - More information can be found in the \l{Secure Sockets Layer (SSL) Classes} - documentation. - - \row \o QtWebKit \o WebKit - \o WebKit is licensed under the GNU LGPL version 2 or later. - This has implications for developers of closed source applications. - Please see \l{QtWebKit Module#License Information}{the QtWebKit module - documentation} for more information. - - \row \o \l{Phonon Module}{Phonon} \o Phonon - \o Phonon relies on the native multimedia engines on different platforms. - Phonon itself is licensed under the GNU LGPL version 2. Please see - \l{Phonon Module#License Information}{the Phonon module documentation} - for more information on licensing and the - \l{Phonon Overview#Backends}{Phonon Overview} for details of the backends - in use on different platforms. - \endtable - - \section1 Platform-Specific Notes - - The procedure of deploying Qt applications is different for the - various platforms: - - \list - \o \l{Deploying an Application on X11 Platforms}{Qt for X11 Platforms} - \o \l{Deploying an Application on Windows}{Qt for Windows} - \o \l{Deploying an Application on Mac OS X}{Qt for Mac OS X} - \o \l{Deploying Qt for Embedded Linux Applications}{Qt for Embedded Linux} - \endlist - - \sa Installation {Window System Specific Notes} -*/ - -/*! - \page deployment-x11.html - \contentspage Deploying Qt Applications - - \title Deploying an Application on X11 Platforms - \ingroup deployment - - Due to the proliferation of Unix systems (commercial Unices, Linux - distributions, etc.), deployment on Unix is a complex - topic. Before we start, be aware that programs compiled for one - Unix flavor will probably not run on a different Unix system. For - example, unless you use a cross-compiler, you cannot compile your - application on Irix and distribute it on AIX. - - Contents: - - \tableofcontents - - This documentation will describe how to determine which files you - should include in your distribution, and how to make sure that the - application will find them at run-time. We will demonstrate the - procedures in terms of deploying the \l {tools/plugandpaint}{Plug - & Paint} application that is provided in Qt's examples directory. - - \section1 Static Linking - - Static linking is often the safest and easiest way to distribute - an application on Unix since it relieves you from the task of - distributing the Qt libraries and ensuring that they are located - in the default search path for libraries on the target system. - - \section2 Building Qt Statically - - To use this approach, you must start by installing a static version - of the Qt library: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 0 - - We specify the prefix so that we do not overwrite the existing Qt - installation. The example above only builds the Qt libraries, - i.e. the examples and Qt Designer will not be built. When \c make - is done, you will find the Qt libraries in the \c /path/to/Qt/lib - directory. - - When linking your application against static Qt libraries, note - that you might need to add more libraries to the \c LIBS line in - your project file. For more information, see the \l {Application - Dependencies} section. - - \section2 Linking the Application to the Static Version of Qt - - Once Qt is built statically, the next step is to regenerate the - makefile and rebuild the application. First, we must go into the - directory that contains the application: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 1 - - Now run qmake to create a new makefile for the application, and do - a clean build to create the statically linked executable: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 2 - - You probably want to link against the release libraries, and you - can specify this when invoking \c qmake. Note that we must set the - path to the static Qt that we just built. - - To check that the application really links statically with Qt, run - the \c ldd tool (available on most Unices): - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 3 - - Verify that the Qt libraries are not mentioned in the output. - - Now, provided that everything compiled and linked without any - errors, we should have a \c plugandpaint file that is ready for - deployment. One easy way to check that the application really can - be run stand-alone is to copy it to a machine that doesn't have Qt - or any Qt applications installed, and run it on that machine. - - Remember that if your application depends on compiler specific - libraries, these must still be redistributed along with your - application. For more information, see the \l {Application - Dependencies} section. - - The \l {tools/plugandpaint}{Plug & Paint} example consists of - several components: The core application (\l - {tools/plugandpaint}{Plug & Paint}), and the \l - {tools/plugandpaintplugins/basictools}{Basic Tools} and \l - {tools/plugandpaintplugins/extrafilters}{Extra Filters} - plugins. Since we cannot deploy plugins using the static linking - approach, the executable we have prepared so far is - incomplete. The application will run, but the functionality will - be disabled due to the missing plugins. To deploy plugin-based - applications we should use the shared library approach. - - \section1 Shared Libraries - - We have two challenges when deploying the \l - {tools/plugandpaint}{Plug & Paint} application using the shared - libraries approach: The Qt runtime has to be correctly - redistributed along with the application executable, and the - plugins have to be installed in the correct location on the target - system so that the application can find them. - - \section2 Building Qt as a Shared Library - - We assume that you already have installed Qt as a shared library, - which is the default when installing Qt, in the \c /path/to/Qt - directory. For more information on how to build Qt, see the \l - {Installation} documentation. - - \section2 Linking the Application to Qt as a Shared Library - - After ensuring that Qt is built as a shared library, we can build - the \l {tools/plugandpaint}{Plug & Paint} application. First, we - must go into the directory that contains the application: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 4 - - Now run qmake to create a new makefile for the application, and do - a clean build to create the dynamically linked executable: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 5 - - This builds the core application, the following will build the - plugins: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 6 - - If everything compiled and linked without any errors, we will get - a \c plugandpaint executable and the \c libpnp_basictools.so and - \c libpnp_extrafilters.so plugin files. - - \section2 Creating the Application Package - - There is no standard package management on Unix, so the method we - present below is a generic solution. See the documentation for - your target system for information on how to create a package. - - To deploy the application, we must make sure that we copy the - relevant Qt libraries (corresponding to the Qt modules used in the - application) as well as the executable to the same - directory. Remember that if your application depends on compiler - specific libraries, these must also be redistributed along with - your application. For more information, see the \l {Application - Dependencies} section. - - We'll cover the plugins shortly, but the main issue with shared - libraries is that you must ensure that the dynamic linker will - find the Qt libraries. Unless told otherwise, the dynamic linker - doesn't search the directory where your application resides. There - are many ways to solve this: - - \list - \o You can install the Qt libraries in one of the system - library paths (e.g. \c /usr/lib on most systems). - - \o You can pass a predetermined path to the \c -rpath command-line - option when linking the application. This will tell the dynamic - linker to look in this directory when starting your application. - - \o You can write a startup script for your application, where you - modify the dynamic linker configuration (e.g. adding your - application's directory to the \c LD_LIBRARY_PATH environment - variable. \note If your application will be running with "Set - user ID on execution," and if it will be owned by root, then - LD_LIBRARY_PATH will be ignored on some platforms. In this - case, use of the LD_LIBRARY_PATH approach is not an option). - - \endlist - - The disadvantage of the first approach is that the user must have - super user privileges. The disadvantage of the second approach is - that the user may not have privileges to install into the - predetemined path. In either case, the users don't have the option - of installing to their home directory. We recommend using the - third approach since it is the most flexible. For example, a \c - plugandpaint.sh script will look like this: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 7 - - By running this script instead of the executable, you are sure - that the Qt libraries will be found by the dynamic linker. Note - that you only have to rename the script to use it with other - applications. - - When looking for plugins, the application searches in a plugins - subdirectory inside the directory of the application - executable. Either you have to manually copy the plugins into the - \c plugins directory, or you can set the \c DESTDIR in the - plugins' project files: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 8 - - An archive distributing all the Qt libraries, and all the plugins, - required to run the \l {tools/plugandpaint}{Plug & Paint} - application, would have to include the following files: - - \table 100% - \header - \o Component \o {2, 1} File Name - \row - \o The executable - \o {2, 1} \c plugandpaint - \row - \o The script to run the executable - \o {2, 1} \c plugandpaint.sh - \row - \o The Basic Tools plugin - \o {2, 1} \c plugins\libpnp_basictools.so - \row - \o The ExtraFilters plugin - \o {2, 1} \c plugins\libpnp_extrafilters.so - \row - \o The Qt Core module - \o {2, 1} \c libQtCore.so.4 - \row - \o The Qt GUI module - \o {2, 1} \c libQtGui.so.4 - \endtable - - On most systems, the extension for shared libraries is \c .so. A - notable exception is HP-UX, which uses \c .sl. - - Remember that if your application depends on compiler specific - libraries, these must still be redistributed along with your - application. For more information, see the \l {Application - Dependencies} section. - - To verify that the application now can be successfully deployed, - you can extract this archive on a machine without Qt and without - any compiler installed, and try to run it, i.e. run the \c - plugandpaint.sh script. - - An alternative to putting the plugins in the \c plugins - subdirectory is to add a custom search path when you start your - application using QApplication::addLibraryPath() or - QApplication::setLibraryPaths(). - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 9 - - \section1 Application Dependencies - - \section2 Additional Libraries - - To find out which libraries your application depends on, run the - \c ldd tool (available on most Unices): - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 10 - - This will list all the shared library dependencies for your - application. Depending on configuration, these libraries must be - redistributed along with your application. In particular, the - standard C++ library must be redistributed if you're compiling - your application with a compiler that is binary incompatible with - the system compiler. When possible, the safest solution is to link - against these libraries statically. - - You will probably want to link dynamically with the regular X11 - libraries, since some implementations will try to open other - shared libraries with \c dlopen(), and if this fails, the X11 - library might cause your application to crash. - - It's also worth mentioning that Qt will look for certain X11 - extensions, such as Xinerama and Xrandr, and possibly pull them - in, including all the libraries that they link against. If you - can't guarantee the presence of a certain extension, the safest - approach is to disable it when configuring Qt (e.g. \c {./configure - -no-xrandr}). - - FontConfig and FreeType are other examples of libraries that - aren't always available or that aren't always binary - compatible. As strange as it may sound, some software vendors have - had success by compiling their software on very old machines and - have been very careful not to upgrade any of the software running - on them. - - When linking your application against the static Qt libraries, you - must explicitly link with the dependent libraries mentioned - above. Do this by adding them to the \c LIBS variable in your - project file. - - \section2 Qt Plugins - - Your application may also depend on one or more Qt plugins, such - as the JPEG image format plugin or a SQL driver plugin. Be sure - to distribute any Qt plugins that you need with your application, - and note that each type of plugin should be located within a - specific subdirectory (such as \c imageformats or \c sqldrivers) - within your distribution directory, as described below. - - \note If you are deploying an application that uses QtWebKit to display - HTML pages from the World Wide Web, you should include all text codec - plugins to support as many HTML encodings possible. - - The search path for Qt plugins (as well as a few other paths) is - hard-coded into the QtCore library. By default, the first plugin - search path will be hard-coded as \c /path/to/Qt/plugins. As - mentioned above, using pre-determined paths has certain - disadvantages, so you need to examine various alternatives to make - sure that the Qt plugins are found: - - \list - - \o \l{qt-conf.html}{Using \c qt.conf}. This is the recommended - approach since it provides the most flexibility. - - \o Using QApplication::addLibraryPath() or - QApplication::setLibraryPaths(). - - \o Using a third party installation utility or the target system's - package manager to change the hard-coded paths in the QtCore - library. - - \endlist - - The \l{How to Create Qt Plugins} document outlines the issues you - need to pay attention to when building and deploying plugins for - Qt applications. -*/ - -/*! - \page deployment-windows.html - \contentspage Deploying Qt Applications - - \title Deploying an Application on Windows - \ingroup deployment - - This documentation will describe how to determine which files you - should include in your distribution, and how to make sure that the - application will find them at run-time. We will demonstrate the - procedures in terms of deploying the \l {tools/plugandpaint}{Plug - & Paint} application that is provided in Qt's examples directory. - - Contents: - - \tableofcontents - - \section1 Static Linking - - If you want to keep things simple by only having a few files to - deploy, i.e. a stand-alone executable with the associated compiler - specific DLLs, then you must build everything statically. - - \section2 Building Qt Statically - - Before we can build our application we must make sure that Qt is - built statically. To do this, go to a command prompt and type the - following: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 11 - - Remember to specify any other options you need, such as data base - drivers, as arguments to \c configure. Once \c configure has - finished, type the following: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 12 - - This will build Qt statically. Note that unlike with a dynamic build, - building Qt statically will result in libraries without version numbers; - e.g. \c QtCore4.lib will be \c QtCore.lib. Also, we have used \c nmake - in all the examples, but if you use MinGW you must use - \c mingw32-make instead. - - \note If you later need to reconfigure and rebuild Qt from the - same location, ensure that all traces of the previous configuration are - removed by entering the build directory and typing \c{nmake distclean} - before running \c configure again. - - \section2 Linking the Application to the Static Version of Qt - - Once Qt has finished building we can build the \l - {tools/plugandpaint}{Plug & Paint} application. First we must go - into the directory that contains the application: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 13 - - We must then run \c qmake to create a new makefile for the - application, and do a clean build to create the statically linked - executable: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 14 - - You probably want to link against the release libraries, and you - can specify this when invoking \c qmake. Now, provided that - everything compiled and linked without any errors, we should have - a \c plugandpaint.exe file that is ready for deployment. One easy - way to check that the application really can be run stand-alone is - to copy it to a machine that doesn't have Qt or any Qt - applications installed, and run it on that machine. - - Remember that if your application depends on compiler specific - libraries, these must still be redistributed along with your - application. You can check which libraries your application is - linking against by using the \c depends tool. For more - information, see the \l {Application Dependencies} section. - - The \l {tools/plugandpaint}{Plug & Paint} example consists of - several components: The application itself (\l - {tools/plugandpaint}{Plug & Paint}), and the \l - {tools/plugandpaintplugins/basictools}{Basic Tools} and \l - {tools/plugandpaintplugins/extrafilters}{Extra Filters} - plugins. Since we cannot deploy plugins using the static linking - approach, the application we have prepared is incomplete. It will - run, but the functionality will be disabled due to the missing - plugins. To deploy plugin-based applications we should use the - shared library approach. - - \section1 Shared Libraries - - We have two challenges when deploying the \l - {tools/plugandpaint}{Plug & Paint} application using the shared - libraries approach: The Qt runtime has to be correctly - redistributed along with the application executable, and the - plugins have to be installed in the correct location on the target - system so that the application can find them. - - \section2 Building Qt as a Shared Library - - We assume that you already have installed Qt as a shared library, - which is the default when installing Qt, in the \c C:\path\to\Qt - directory. For more information on how to build Qt, see the \l - {Installation} documentation. - - \section2 Linking the Application to Qt as a Shared Library - - After ensuring that Qt is built as a shared library, we can build - the \l {tools/plugandpaint}{Plug & Paint} application. First, we - must go into the directory that contains the application: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 15 - - Now run \c qmake to create a new makefile for the application, and - do a clean build to create the dynamically linked executable: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 16 - - This builds the core application, the following will build the - plugins: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 17 - - If everything compiled and linked without any errors, we will get - a \c plugandpaint.exe executable and the \c pnp_basictools.dll and - \c pnp_extrafilters.dll plugin files. - - \section2 Creating the Application Package - - To deploy the application, we must make sure that we copy the - relevant Qt DLL (corresponding to the Qt modules used in - the application) as well as the executable to the same directory - in the \c release subdirectory. - - Remember that if your application depends on compiler specific - libraries, these must be redistributed along with your - application. You can check which libraries your application is - linking against by using the \c depends tool. For more - information, see the \l {Application Dependencies} section. - - We'll cover the plugins shortly, but first we'll check that the - application will work in a deployed environment: Either copy the - executable and the Qt DLLs to a machine that doesn't have Qt - or any Qt applications installed, or if you want to test on the - build machine, ensure that the machine doesn't have Qt in its - environment. - - If the application starts without any problems, then we have - successfully made a dynamically linked version of the \l - {tools/plugandpaint}{Plug & Paint} application. But the - application's functionality will still be missing since we have - not yet deployed the associated plugins. - - Plugins work differently to normal DLLs, so we can't just - copy them into the same directory as our application's executable - as we did with the Qt DLLs. When looking for plugins, the - application searches in a \c plugins subdirectory inside the - directory of the application executable. - - So to make the plugins available to our application, we have to - create the \c plugins subdirectory and copy over the relevant DLLs: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 18 - - An archive distributing all the Qt DLLs and application - specific plugins required to run the \l {tools/plugandpaint}{Plug - & Paint} application, would have to include the following files: - - \table 100% - \header - \o Component \o {2, 1} File Name - \row - \o The executable - \o {2, 1} \c plugandpaint.exe - \row - \o The Basic Tools plugin - \o {2, 1} \c plugins\pnp_basictools.dll - \row - \o The ExtraFilters plugin - \o {2, 1} \c plugins\pnp_extrafilters.dll - \row - \o The Qt Core module - \o {2, 1} \c qtcore4.dll - \row - \o The Qt GUI module - \o {2, 1} \c qtgui4.dll - \endtable - - In addition, the archive must contain the following compiler - specific libraries depending on your version of Visual Studio: - - \table 100% - \header - \o \o VC++ 6.0 \o VC++ 7.1 (2003) \o VC++ 8.0 (2005) \o VC++ 9.0 (2008) - \row - \o The C run-time - \o \c msvcrt.dll - \o \c msvcr71.dll - \o \c msvcr80.dll - \o \c msvcr90.dll - \row - \o The C++ run-time - \o \c msvcp60.dll - \o \c msvcp71.dll - \o \c msvcp80.dll - \o \c msvcp90.dll - \endtable - - To verify that the application now can be successfully deployed, - you can extract this archive on a machine without Qt and without - any compiler installed, and try to run it. - - An alternative to putting the plugins in the plugins subdirectory - is to add a custom search path when you start your application - using QApplication::addLibraryPath() or - QApplication::setLibraryPaths(). - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 19 - - One benefit of using plugins is that they can easily be made - available to a whole family of applications. - - It's often most convenient to add the path in the application's \c - main() function, right after the QApplication object is - created. Once the path is added, the application will search it - for plugins, in addition to looking in the \c plugins subdirectory - in the application's own directory. Any number of additional paths - can be added. - - \section2 Visual Studio 2005 Onwards - - When deploying an application compiled with Visual Studio 2005 onwards, - there are some additional steps to be taken. - - First, we need to copy the manifest file created when linking the - application. This manifest file contains information about the - application's dependencies on side-by-side assemblies, such as the runtime - libraries. - - The manifest file needs to be copied into the \bold same folder as the - application executable. You do not need to copy the manifest files for - shared libraries (DLLs), since they are not used. - - If the shared library has dependencies that are different from the - application using it, the manifest file needs to be embedded into the DLL - binary. Since Qt 4.1.3, the follwoing \c CONFIG options are available for - embedding manifests: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 20 - - To use the options, add - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 21 - - to your .pro file. The \c embed_manifest_dll option is enabled by default. - - You can find more information about manifest files and side-by-side - assemblies at the - \l {http://msdn.microsoft.com/en-us/library/aa376307.aspx}{MSDN website}. - - There are two ways to include the run time libraries: by bundling them - directly with your application or by installing them on the end-user's - system. - - To bundle the run time libraries with your application, copy the directory - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 22 - - into the folder where your executable is, so that you are including a - \c Microsoft.VC80.CRT directory alongside your application's executable. If - you are bundling the runtimes and need to deploy plugins as well, you have - to remove the manifest from the plugins (embedded as a resource) by adding - the following line to the \c{.pro} file of the plugins you are compiling: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 23 - - \warning If you skip the step above, the plugins will not load on some - systems. - - To install the runtime libraries on the end-user's system, you need to - include the appropriate Visual C++ Redistributable Package (VCRedist) - executable with your application and ensure that it is executed when the - user installs your application. - - For example, on an 32-bit x86-based system, you would include the - \l{http://www.microsoft.com/downloads/details.aspx?FamilyId=32BC1BEE-A3F9-4C13-9C99-220B62A191EE}{vcredist_x86.exe} - executable. The \l{http://www.microsoft.com/downloads/details.aspx?familyid=526BF4A7-44E6-4A91-B328-A4594ADB70E5}{vcredist_IA64.exe} - and \l{http://www.microsoft.com/downloads/details.aspx?familyid=90548130-4468-4BBC-9673-D6ACABD5D13B}{vcredist_x64.exe} - executables provide the appropriate libraries for the IA64 and 64-bit x86 - architectures, respectively. - - \note The application you ship must be compiled with exactly the same - compiler version against the same C runtime version. This prevents - deploying errors caused by different versions of the C runtime libraries. - - - \section1 Application Dependencies - - \section2 Additional Libraries - - Depending on configuration, compiler specific libraries must be - redistributed along with your application. You can check which - libraries your application is linking against by using the - \l{Dependency Walker} tool. All you need to do is to run it like - this: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 24 - - This will provide a list of the libraries that your application - depends on and other information. - - \image deployment-windows-depends.png - - When looking at the release build of the Plug & Paint executable - (\c plugandpaint.exe) with the \c depends tool, the tool lists the - following immediate dependencies to non-system libraries: - - \table 100% - \header - \o Qt - \o VC++ 6.0 - \o VC++ 7.1 (2003) - \o VC++ 8.0 (2005) - \o MinGW - \row - \o \list - \o QTCORE4.DLL - The QtCore runtime - \o QTGUI4.DLL - The QtGui runtime - \endlist - \o \list - \o MSVCRT.DLL - The C runtime - \o MSVCP60.DLL - The C++ runtime (only when STL is installed) - \endlist - \o \list - \o MSVCR71.DLL - The C runtime - \o MSVCP71.DLL - The C++ runtime (only when STL is installed) - \endlist - \o \list - \o MSVCR80.DLL - The C runtime - \o MSVCP80.DLL - The C++ runtime (only when STL is installed) - \endlist - \o \list - \o MINGWM10.DLL - The MinGW run-time - \endlist - \endtable - - When looking at the plugin DLLs the exact same dependencies - are listed. - - \section2 Qt Plugins - - Your application may also depend on one or more Qt plugins, such - as the JPEG image format plugin or a SQL driver plugin. Be sure - to distribute any Qt plugins that you need with your application, - and note that each type of plugin should be located within a - specific subdirectory (such as \c imageformats or \c sqldrivers) - within your distribution directory, as described below. - - \note If you are deploying an application that uses QtWebKit to display - HTML pages from the World Wide Web, you should include all text codec - plugins to support as many HTML encodings possible. - - The search path for Qt plugins is hard-coded into the QtCore library. - By default, the plugins subdirectory of the Qt installation is the first - plugin search path. However, pre-determined paths like the default one - have certain disadvantages. For example, they may not exist on the target - machine. For that reason, you need to examine various alternatives to make - sure that the Qt plugins are found: - - \list - - \o \l{qt-conf.html}{Using \c qt.conf}. This approach is the recommended - if you have executables in different places sharing the same plugins. - - \o Using QApplication::addLibraryPath() or - QApplication::setLibraryPaths(). This approach is recommended if you only - have one executable that will use the plugin. - - \o Using a third party installation utility to change the - hard-coded paths in the QtCore library. - - \endlist - - If you add a custom path using QApplication::addLibraryPath it could - look like this: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 54 - - Then qApp->libraryPaths() would return something like this: - - "C:/customPath/plugins " - "C:/Qt/%VERSION%/plugins" - "E:/myApplication/directory/" - - The executable will look for the plugins in these directories and - the same order as the QStringList returned by qApp->libraryPaths(). - The newly added path is prepended to the qApp->libraryPaths() which - means that it will be searched through first. However, if you use - qApp->setLibraryPaths(), you will be able to determend which paths - and in which order they will be searched. - - The \l{How to Create Qt Plugins} document outlines the issues you - need to pay attention to when building and deploying plugins for - Qt applications. -*/ - -/*! - \page deployment-mac.html - \contentspage Deploying Qt Applications - - \title Deploying an Application on Mac OS X - \ingroup deployment - - Starting with version 4.5, Qt now includes a \l {macdeploy}{deployment tool} - that automates the prodecures described in this document. - - This documentation will describe how to create a bundle, and how - to make sure that the application will find the resources it needs - at run-time. We will demonstrate the procedures in terms of - deploying the \l {tools/plugandpaint}{Plug & Paint} application - that is provided in Qt's examples directory. - - \tableofcontents - - \section1 The Bundle - - On the Mac, a GUI application must be built and run from a - bundle. A bundle is a directory structure that appears as a single - entity when viewed in the Finder. A bundle for an application - typcially contains the executable and all the resources it - needs. See the image below: - - \image deployment-mac-bundlestructure.png - - The bundle provides many advantages to the user. One primary - advantage is that, since it is a single entity, it allows for - drag-and-drop installation. As a programmer you can access bundle - information in your own code. This is specific to Mac OS X and - beyond the scope of this document. More information about bundles - is available on \l - {http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/index.html}{Apple's Developer Website}. - - A Qt command line application on Mac OS X works similar to a - command line application on Unix and Windows. You probably don't - want to run it in a bundle: Add this to your application's .pro: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 26 - - This will tell \c qmake not to put the executable inside a - bundle. Please refer to the \l{Deploying an Application on - X11 Platforms}{X11 deployment documentation} for information about how - to deploy these "bundle-less" applications. - - \section1 Xcode - - We will only concern ourselves with command-line tools here. While - it is possible to use Xcode for this, Xcode has changed enough - between each version that it makes it difficult to document it - perfectly for each version. A future version of this document may - include more information for using Xcode in the deployment - process. - - \section1 Static Linking - - If you want to keep things simple by only having a few files to - deploy, then you must build everything statically. - - \section2 Building Qt Statically - - Start by installing a static version of the Qt library. Remember - that you will not be able to use plugins and you must build in all - the image formats, SQL drivers, etc.. - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 27 - - You can check the various options that are available by running \c - configure -help. - - \section2 Linking the Application to the Static Version of Qt - - Once Qt is built statically, the next step is to regenerate the - makefile and rebuild the application. First, we must go into the - directory that contains the application: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 28 - - Now run \c qmake to create a new makefile for the application, and do - a clean build to create the statically linked executable: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 29 - - You probably want to link against the release libraries, and you - can specify this when invoking \c qmake. If you have Xcode Tools - 1.5 or higher installed, you may want to take advantage of "dead - code stripping" to reduce the size of your binary even more. You - can do this by passing \c {LIBS+= -dead_strip} to \c qmake in - addition to the \c {-config release} parameter. This doesn't have - as large an effect if you are using GCC 4, since Qt will then have - function visibility hints built-in, but if you use GCC 3.3, it - could make a difference. - - Now, provided that everything compiled and linked without any - errors, we should have a \c plugandpaint.app bundle that is ready - for deployment. One easy way to check that the application really - can be run stand-alone is to copy the bundle to a machine that - doesn't have Qt or any Qt applications installed, and run the - application on that machine. - - You can check what other libraries your application links to using - the \c otool: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 30 - - Here is what the output looks like for the static \l - {tools/plugandpaint}{Plug & Paint}: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 31 - - For more information, see the \l {Application Dependencies} - section. - - If you see \e Qt libraries in the output, it probably - means that you have both dynamic and static Qt libraries installed - on your machine. The linker will always choose dynamic over - static. There are two solutions: Either move your Qt dynamic - libraries (\c .dylibs) away to another directory while you link - the application and then move them back, or edit the \c Makefile - and replace link lines for the Qt libraries with the absolute path - to the static libraries. For example, replace - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 32 - - with - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 33 - - The \l {tools/plugandpaint}{Plug & Paint} example consists of - several components: The core application (\l - {tools/plugandpaint}{Plug & Paint}), and the \l - {tools/plugandpaintplugins/basictools}{Basic Tools} and \l - {tools/plugandpaintplugins/extrafilters}{Extra Filters} - plugins. Since we cannot deploy plugins using the static linking - approach, the bundle we have prepared so far is incomplete. The - application will run, but the functionality will be disabled due - to the missing plugins. To deploy plugin-based applications we - should use the framework approach. - - \section1 Frameworks - - We have two challenges when deploying the \l - {tools/plugandpaint}{Plug & Paint} application using frameworks: - The Qt runtime has to be correctly redistributed along with the - application bundle, and the plugins have to be installed in the - correct location so that the application can find them. - - When distributing Qt with your application using frameworks, you - have two options: You can either distribute Qt as a private - framework within your application bundle, or you can distribute Qt - as a standard framework (alternatively use the Qt frameworks in - the installed binary). These two approaches are essentially the - same. The latter option is good if you have many Qt applications - and you would prefer to save memory. The former is good if you - have Qt built in a special way, or want to make sure the framework - is there. It just comes down to where you place the Qt frameworks. - - \section2 Building Qt as Frameworks - - We assume that you already have installed Qt as frameworks, which - is the default when installing Qt, in the /path/to/Qt - directory. For more information on how to build Qt, see the \l - Installation documentation. - - When installing, the identification name of the frameworks will - also be set. The identification name is what the dynamic linker - (\c dyld) uses to find the libraries for your application. - - \section2 Linking the Application to Qt as Frameworks - - After ensuring that Qt is built as frameworks, we can build the \l - {tools/plugandpaint}{Plug & Paint} application. First, we must go - into the directory that contains the application: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 34 - - Now run qmake to create a new makefile for the application, and do - a clean build to create the dynamically linked executable: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 35 - - This builds the core application, the following will build the - plugins: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 36 - - Now run the \c otool for the Qt frameworks, for example Qt Gui: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 37 - - You will get the following output: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 38 - - For the Qt frameworks, the first line (i.e. \c - {path/to/Qt/lib/QtGui.framework/Versions/4/QtGui (compatibility - version 4.0.0, current version 4.0.1)}) becomes the framework's - identification name which is used by the dynamic linker (\c dyld). - - But when you are deploying the application, your users may not - have the Qt frameworks installed in the specified location. For - that reason, you must either provide the frameworks in an agreed - upon location, or store the frameworks in the bundle itself. - Regardless of which solution you choose, you must make sure that - the frameworks return the proper identification name for - themselves, and that the application will look for these - names. Luckily we can control this with the \c install_name_tool - command-line tool. - - The \c install_name_tool works in two modes, \c -id and \c - -change. The \c -id mode is for libraries and frameworks, and - allows us to specify a new identification name. We use the \c - -change mode to change the paths in the application. - - Let's test this out by copying the Qt frameworks into the Plug & - Paint bundle. Looking at \c otool's output for the bundle, we can - see that we must copy both the QtCore and QtGui frameworks into - the bundle. We will assume that we are in the directory where we - built the bundle. - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 39 - - First we create a \c Frameworks directory inside the bundle. This - follows the Mac OS X application convention. We then copy the - frameworks into the new directory. Since frameworks contain - symbolic links, and we want to preserve them, we use the \c -R - option. - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 40 - - Then we run \c install_name_tool to set the identification names - for the frameworks. The first argument after \c -id is the new - name, and the second argument is the framework which - identification we wish to change. The text \c @executable_path is - a special \c dyld variable telling \c dyld to start looking where - the executable is located. The new names specifies that these - frameworks will be located "one directory up and over" in the \c - Frameworks directory. - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 41 - - Now, the dynamic linker knows where to look for QtCore and - QtGui. Then we must make the application aware of the library - locations as well using \c install_name_tool's \c -change mode. - This basically comes down to string replacement, to match the - identification names that we set for the frameworks. - - Finally, since the QtGui framework depends on QtCore, we must - remember to change the reference for QtGui: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 42 - - After all this we can run \c otool again and see that the - application will look in the right locations. - - Of course, the thing that makes the \l {tools/plugandpaint}{Plug & - Paint} example interesting are its plugins. The basic steps we - need to follow with plugins are: - - \list - \o Put the plugins inside the bundle - \o Make sure that the plugins use the correct library using the - \c install_name_tool - \o Make sure that the application knows where to get the plugins - \endlist - - While we can put the plugins anywhere we want in the bundle, the - best location to put them is under Contents/Plugins. When we built - the Plug & Paint plugins, the \c DESTDIR variable in their \c .pro - file put the plugins' \c .dylib files in a \c plugins subdirectory - in the \c plugandpaint directory. So, in this example, all we need - to do is move this directory: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 43 - - If we run \c otool on for example the \l - {tools/plugandpaintplugins/basictools}{Basic Tools} plugin's \c - .dylib file we get the following information. - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 44 - - Then we can see that the plugin links to the Qt frameworks it was - built against. Since we want the plugins to use the framework in - the application bundle we change them the same way as we did for - the application. For example for the Basic Tools plugin: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 45 - - - We must also modify the code in \c - tools/plugandpaint/mainwindow.cpp to \l {QDir::cdUp()}{cdUp()} one - directory since the plugins live in the bundle. Add the following - code to the \c mainwindow.cpp file: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 46 - - \table - \row - \o \inlineimage deployment-mac-application.png - \o - The additional code in \c tools/plugandpaint/mainwindow.cpp also - enables us to view the plugins in the Finder, as shown to the left. - - We can also add plugins extending Qt, for example adding SQL - drivers or image formats. We just need to follow the directory - structure outlined in plugin documentation, and make sure they are - included in the QCoreApplication::libraryPaths(). Let's quickly do - this with the image formats, following the approach from above. - - Copy Qt's image format plugins into the bundle: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 47 - - Use \c install_name_tool to link the plugins to the frameworks in - the bundle: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 48 - - Then we update the source code in \c tools/plugandpaint/main.cpp - to look for the new plugins. After constructing the - QApplication, we add the following code: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 49 - - First, we tell the application to only look for plugins in this - directory. In our case, this is what we want since we only want to - look for the plugins that we distribute with the bundle. If we - were part of a bigger Qt installation we could have used - QCoreApplication::addLibraryPath() instead. - - \endtable - - \warning When deploying plugins, and thus make changes to the - source code, the default identification names are reset when - rebuilding the application, and you must repeat the process of - making your application link to the Qt frameworks in the bundle - using \c install_name_tool. - - Now you should be able to move the application to another Mac OS X - machine and run it without Qt installed. Alternatively, you can - move your frameworks that live outside of the bundle to another - directory and see if the application still runs. - - If you store the frameworks in another location than in the - bundle, the technique of linking your application is similar; you - must make sure that the application and the frameworks agree where - to be looking for the Qt libraries as well as the plugins. - - \section2 Creating the Application Package - - When you are done linking your application to Qt, either - statically or as frameworks, the application is ready to be - distributed. Apple provides a fair bit of information about how to - do this and instead of repeating it here, we recommend that you - consult their \l - {http://developer.apple.com/documentation/DeveloperTools/Conceptual/SoftwareDistribution/index.html}{software delivery} - documentation. - - Although the process of deploying an application do have some - pitfalls, once you know the various issues you can easily create - packages that all your Mac OS X users will enjoy. - - \section1 Application Dependencies - - \section2 Qt Plugins - - Your application may also depend on one or more Qt plugins, such - as the JPEG image format plugin or a SQL driver plugin. Be sure - to distribute any Qt plugins that you need with your application, - and note that each type of plugin should be located within a - specific subdirectory (such as \c imageformats or \c sqldrivers) - within your distribution directory, as described below. - - \note If you are deploying an application that uses QtWebKit to display - HTML pages from the World Wide Web, you should include all text codec - plugins to support as many HTML encodings possible. - - The search path for Qt plugins (as well as a few other paths) is - hard-coded into the QtCore library. By default, the first plugin - search path will be hard-coded as \c /path/to/Qt/plugins. But - using pre-determined paths has certain disadvantages. For example, - they may not exist on the target machine. For that reason you need - to examine various alternatives to make sure that the Qt plugins - are found: - - \list - - \o \l{qt-conf.html}{Using \c qt.conf}. This is the recommended - approach since it provides the most flexibility. - - \o Using QApplication::addLibraryPath() or - QApplication::setLibraryPaths(). - - \o Using a third party installation utility to change the - hard-coded paths in the QtCore library. - - \endlist - - The \l{How to Create Qt Plugins} document outlines the issues you - need to pay attention to when building and deploying plugins for - Qt applications. - - \section2 Additional Libraries - - You can check which libraries your application is linking against - by using the \c otool tool. To use \c otool, all you need to do is - to run it like this: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 50 - - Unlike the deployment processes on \l {Deploying an Application on - X11 Platforms}{X11} and \l {Deploying an Application on - Windows}{Windows}, compiler specific libraries rarely have to - be redistributed along with your application. But since Qt can be - configured, built, and installed in several ways on Mac OS X, - there are also several ways to deploy applications. Typically your - goals help determine how you are going to deploy the - application. The last sections describe a couple of things to keep - in mind when you are deploying your application. - - \section2 Mac OS X Version Dependencies - - Qt 4.2 has been designed to be built and deployed on Mac OS X 10.3 - up until the current version as of this writing, Mac OS X 10.4 and - all their minor releases. Qt achieves this by using "weak - linking." This means that Qt tests if a function added in newer - versions of Mac OS X is available on the computer it is running on - before it uses it. This results in getting access to newer - features when running on newer versions of OS X while still - remaining compatible on older versions. - - For more information about cross development issues on Mac OS X, - see \l - {http://developer.apple.com/documentation/DeveloperTools/Conceptual/cross_development/index.html}{Apple's Developer Website}. - - Since the linker is set to be compatible with all OS X version, you have to - change the \c MACOSX_DEPLOYMENT_TARGET environment variable to get weak - linking to work for your application. You can add: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 51 - - to your .pro file and qmake will take care of this for you. - - However, there is a bit of a wrinkle to keep in mind when your are - deploying. Mac OS X 10.4 ("Tiger") ships GCC 4.0 as its default - compiler. This is also the GCC compiler we use for building the - binary Qt package. If you use GCC 4.0 to build your application, - it will link against a dynamic libstdc++ that is only available on - Mac OS X 10.4 and Mac OS X 10.3.9. The application will refuse to - run on older versions of the operating system. - - For more information about C++ runtime environment, see \l - {http://developer.apple.com/documentation/DeveloperTools/Conceptual/CppRuntimeEnv/index.html}{Apple's Developer Website} - - If you want to deploy to versions of Mac OS X earlier than 10.3.9, - you must build with GCC 3.3 which is the default on Mac OS X - 10.3. GCC 3.3 is also available on the Mac OS X 10.4 "Xcode Tools" - CD and as a download for earlier versions of Mac OS X from Apple - (\l {https://connect.apple.com/}{connect.apple.com}). You can use - Apple's \c gcc_select(1) command line tool to switch the default - complier on your system. - - \section3 Deploying Phonon Applications on Mac OS X - - \list - \o If you build your Phonon application on Tiger, it will work on - Tiger, Leopard and Panther. - \o If you build your application on Leopard, it will \bold not work - on Panther unless you rename the libraries with the following command - after you have built your application: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 51a - - This command must be invoked in the directory where - \c{libphonon_qt7.dylib} is located, usually in - \c{yourapp.app/Contents/plugins/phonon_backend/}. - \o The \l {macdeploy}{deployment tool} will perform this step for you. - - \o If you are using Leopard, but would like to build your application - against Tiger, you can use: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 51b - \endlist - - \section2 Architecture Dependencies - - The Qt for Mac OS X libraries, tools, and examples can be built "universal" - (i.e. they run natively on both Intel and PowerPC machines). This - is accomplished by passing \c -universal on the \c configure line - of the source package, and requires that you use GCC 4.0.x. On - PowerPC hardware you will need to pass the universal SDK as a - command line argument to the Qt configure command. For example: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 52 - - From 4.1.1 the Qt binary package is already universal. - - If you want to create a binary that runs on older versions of - PowerPC and x86, it is possible to build Qt for the PowerPC using - GCC 3.3, and for x86 one using GCC 4.0, and use Apple's \c lipo(1) - tool to stitch them together. This is beyond the scope of this - document and is not something we have tried, but Apple documents - it on their \l - {http://developer.apple.com/documentation/}{developer website}. - - Once you have a universal Qt, \a qmake will generate makefiles - that will build for its host architecture by default. If you want - to build for a specific architecture, you can control this with - the \c CONFIG line in your \c .pro file. Use \c CONFIG+=ppc for - PowerPC, and \c CONFIG+=x86 for x86. If you desire both, simply - add both to the \c CONFIG line. PowerPC users also need an - SDK. For example: - - \snippet doc/src/snippets/code/doc_src_deployment.qdoc 53 - - Besides \c lipo, you can also check your binaries with the \c file(1) - command line tool or the Finder. - - \section1 The Mac Deployment Tool - \target macdeploy - The Mac deployment tool can be found in QTDIR/bin/macdeployqt. It is - designed to automate the process of creating a deployable - application bundle that contains the Qt libraries as private - frameworks. - - The mac deployment tool also deploys the Qt plugins, according - to the following rules: - \list - \o Debug versions of the plugins are not deployed. - \o The designer plugins are not deployed. - \o The Image format plugins are always deployed. - \o SQL driver plugins are deployed if the application uses the QtSql module. - \o Script plugins are deployed if the application uses the QtScript module. - \o The Phonon backend plugin is deployed if the application uses the \l{Phonon Module} {Phonon} module. - \o The svg icon plugin is deployed if the application uses the QtSvg module. - \o The accessibility plugin is always deployed. - \o Accessibility for Qt3Support is deployed if the application uses the Qt3Support module. - \endlist - - macdeployqt supports the following options: - \list - \o -no-plugins: Skip plugin deployment - \o -dmg : Create a .dmg disk image - \o -no-strip : Don't run 'strip' on the binaries - \endlist -*/ diff --git a/doc/src/deployment/deployment-plugins.qdoc b/doc/src/deployment/deployment-plugins.qdoc new file mode 100644 index 0000000..b02bdd8 --- /dev/null +++ b/doc/src/deployment/deployment-plugins.qdoc @@ -0,0 +1,236 @@ +/**************************************************************************** +** +** 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 deployment-plugins.html + \title Deploying Plugins + \brief A guide to plugins-specific aspects of deploying Qt and Qt Application + + This document explains how to deploy plugin libraries that Qt or + your application should load at runtime. If you use + \l{How to Create Qt Plugins#Static Plugins}{static plugins}, then the + plugin code is already part of your application executable, and no + separate deployment steps are required. + + \tableofcontents + + \section1 The Plugin Directory + + When the application is run, Qt will first treat the application's + executable directory as the \c{pluginsbase}. For example if the + application is in \c{C:\Program Files\MyApp} and has a style plugin, + Qt will look in \c{C:\Program Files\MyApp\styles}. (See + QCoreApplication::applicationDirPath() for how to find out where + the application's executable is.) Qt will also look in the + directory specified by + QLibraryInfo::location(QLibraryInfo::PluginsPath), which typically + is located in \c QTDIR/plugins (where \c QTDIR is the directory + where Qt is installed). If you want Qt to look in additional + places you can add as many paths as you need with calls to + QCoreApplication::addLibraryPath(). And if you want to set your + own path or paths you can use QCoreApplication::setLibraryPaths(). + You can also use a \c qt.conf file to override the hard-coded + paths that are compiled into the Qt library. For more information, + see the \l {Using qt.conf} documentation. Yet another possibility + is to set the \c QT_PLUGIN_PATH environment variable before running + the application. If set, Qt will look for plugins in the + paths (separated by the system path separator) specified in the variable. + + \section1 Loading and Verifying Plugins Dynamically + + When loading plugins, the Qt library does some sanity checking to + determine whether or not the plugin can be loaded and used. This + provides the ability to have multiple versions and configurations of + the Qt library installed side by side. + + \list + \o Plugins linked with a Qt library that has a higher version number + will not be loaded by a library with a lower version number. + + \br + \bold{Example:} Qt 4.3.0 will \e{not} load a plugin built with Qt 4.3.1. + + \o Plugins linked with a Qt library that has a lower major version + number will not be loaded by a library with a higher major version + number. + + \br + \bold{Example:} Qt 4.3.1 will \e{not} load a plugin built with Qt 3.3.1. + \br + \bold{Example:} Qt 4.3.1 will load plugins built with Qt 4.3.0 and Qt 4.2.3. + + \o The Qt library and all plugins are built using a \e {build + key}. The build key in the Qt library is examined against the build + key in the plugin, and if they match, the plugin is loaded. If the + build keys do not match, then the Qt library refuses to load the + plugin. + + \br \bold{Rationale:} See the \l{#The Build Key}{The Build Key} section below. + \endlist + + When building plugins to extend an application, it is important to ensure + that the plugin is configured in the same way as the application. This means + that if the application was built in release mode, plugins should be built + in release mode, too. + + If you configure Qt to be built in both debug and release modes, + but only build applications in release mode, you need to ensure that your + plugins are also built in release mode. By default, if a debug build of Qt is + available, plugins will \e only be built in debug mode. To force the + plugins to be built in release mode, add the following line to the plugin's + project file: + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 3 + + This will ensure that the plugin is compatible with the version of the library + used in the application. + + \section2 The Build Key + + When loading plugins, Qt checks the build key of each plugin against its + own configuration to ensure that only compatible plugins are loaded; any + plugins that are configured differently are not loaded. + + The build key contains the following information: + \list + \o Architecture, operating system and compiler. + + \e {Rationale:} + In cases where different versions of the same compiler do not + produce binary compatible code, the version of the compiler is + also present in the build key. + + \o Configuration of the Qt library. The configuration is a list + of the missing features that affect the available API in the + library. + + \e {Rationale:} + Two different configurations of the same version of + the Qt library are not binary compatible. The Qt library that + loads the plugin uses the list of (missing) features to + determine if the plugin is binary compatible. + + \e {Note:} There are cases where a plugin can use features that are + available in two different configurations. However, the + developer writing plugins would need to know which features are + in use, both in their plugin and internally by the utility + classes in Qt. The Qt library would require complex feature + and dependency queries and verification when loading plugins. + Requiring this would place an unnecessary burden on the developer, and + increase the overhead of loading a plugin. To reduce both + development time and application runtime costs, a simple string + comparision of the build keys is used. + + \o Optionally, an extra string may be specified on the configure + script command line. + + \e {Rationale:} + When distributing binaries of the Qt library with an + application, this provides a way for developers to write + plugins that can only be loaded by the library with which the + plugins were linked. + \endlist + + For debugging purposes, it is possible to override the run-time build key + checks by configuring Qt with the \c QT_NO_PLUGIN_CHECK preprocessor macro + defined. + + \section1 The Plugin Cache + + In order to speed up loading and validation of plugins, some of + the information that is collected when plugins are loaded is cached + through QSettings. This includes information about whether or not + a plugin was successfully loaded, so that subsequent load operations + don't try to load an invalid plugin. However, if the "last modified" + timestamp of a plugin has changed, the plugin's cache entry is + invalidated and the plugin is reloaded regardless of the values in + the cache entry, and the cache entry itself is updated with the new + result. + + This also means that the timestamp must be updated each time the + plugin or any dependent resources (such as a shared library) is + updated, since the dependent resources might influence the result + of loading a plugin. + + Sometimes, when developing plugins, it is necessary to remove entries + from the plugin cache. Since Qt uses QSettings to manage the plugin + cache, the locations of plugins are platform-dependent; see + \l{QSettings#Platform-Specific Notes}{the QSettings documentation} + for more information about each platform. + + For example, on Windows the entries are stored in the registry, and the + paths for each plugin will typically begin with either of these two strings: + + \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 6 + + \section1 Debugging Plugins + + There are a number of issues that may prevent correctly-written plugins from + working with the applications that are designed to use them. Many of these + are related to differences in the way that plugins and applications have been + built, often arising from separate build systems and processes. + + The following table contains descriptions of the common causes of problems + developers experience when creating plugins: + + \table + \header \o Problem \o Cause \o Solution + \row \o Plugins sliently fail to load even when opened directly by the + application. \QD shows the plugin libraries in its + \gui{Help|About Plugins} dialog, but no plugins are listed under each + of them. + \o The application and its plugins are built in different modes. + \o Either share the same build information or build the plugins in both + debug and release modes by appending the \c debug_and_release to + the \l{qmake Variable Reference#CONFIG}{CONFIG} variable in each of + their project files. + \row \o A valid plugin that replaces an invalid (or broken) plugin fails to load. + \o The entry for the plugin in the plugin cache indicates that the original + plugin could not be loaded, causing Qt to ignore the replacement. + \o Either ensure that the plugin's timestamp is updated, or delete the + entry in the \l{#The Plugin Cache}{plugin cache}. + \endtable + + You can also use the \c QT_DEBUG_PLUGINS environment variable to obtain + diagnostic information from Qt about each plugin it tries to load. Set this + variable to a non-zero value in the environment from which your application is + launched. +*/ diff --git a/doc/src/deployment/deployment.qdoc b/doc/src/deployment/deployment.qdoc new file mode 100644 index 0000000..75b870f --- /dev/null +++ b/doc/src/deployment/deployment.qdoc @@ -0,0 +1,1464 @@ +/**************************************************************************** +** +** 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 deployment.html + \title Deploying Qt Applications + + Deploying an Qt application does not require any C++ + programming. All you need to do is to build Qt and your + application in release mode, following the procedures described in + this documentation. We will demonstrate the procedures in terms of + deploying the \l {tools/plugandpaint}{Plug & Paint} application + that is provided in Qt's examples directory. + + \section1 Static vs. Shared Libraries + + There are two ways of deploying an application: + + \list + \o Static Linking + \o Shared Libraries (Frameworks on Mac) + \endlist + + Static linking results in a stand-alone executable. The advantage + is that you will only have a few files to deploy. The + disadvantages are that the executables are large and with no + flexibility (i.e a new version of the application, or of Qt, will + require that the deployment process is repeated), and that you + cannot deploy plugins. + + To deploy plugin-based applications, you can use the shared + library approach. Shared libraries also provide smaller, more + flexible executables. For example, using the shared library + approach, the user is able to independently upgrade the Qt library + used by the application. + + Another reason why you might want to use the shared library + approach, is if you want to use the same Qt libraries for a family + of applications. In fact, if you download the binary installation + of Qt, you get Qt as a shared library. + + The disadvantage with the shared library approach is that you + will get more files to deploy. For more information, see + \l{sharedlibrary.html}{Creating Shared Libraries}. + + \section1 Deploying Qt's Libraries + + \table + \header + \o {4,1} Qt's Libraries + \row + \o \l {QtAssistant} + \o \l {QAxContainer} + \o \l {QAxServer} + \o \l {QtCore} + \row + \o \l {QtDBus} + \o \l {QtDesigner} + \o \l {QtGui} + \o \l {QtHelp} + \row + \o \l {QtNetwork} + \o \l {QtOpenGL} + \o \l {QtScript} + \o \l {QtScriptTools} + \row + \o \l {QtSql} + \o \l {QtSvg} + \o \l {QtWebKit} + \o \l {QtXml} + \row + \o \l {QtXmlPatterns} + \o \l {Phonon Module}{Phonon} + \o \l {Qt3Support} + \endtable + + Since Qt is not a system library, it has to be redistributed along + with your application; the minimum is to redistribute the run-time + of the libraries used by the application. Using static linking, + however, the Qt run-time is compiled into the executable. + + In particular, you will need to deploy Qt plugins, such as + JPEG support or SQL drivers. For more information about plugins, + see the \l {plugins-howto.html}{How to Create Qt Plugins} + documentation. + + When deploying an application using the shared library approach + you must ensure that the Qt libraries will use the correct path to + find the Qt plugins, documentation, translation etc. To do this you + can use a \c qt.conf file. For more information, see the \l {Using + qt.conf} documentation. + + Depending on configuration, compiler specific libraries must be + redistributed as well. For more information, see the platform + specific Application Dependencies sections: \l + {deployment-x11.html#application-dependencies}{X11}, \l + {deployment-windows.html#application-dependencies}{Windows}, \l + {deployment-mac.html#application-dependencies}{Mac}. + + \section1 Licensing + + Some of Qt's libraries are based on third party libraries that are + not licensed using the same dual-license model as Qt. As a result, + care must be taken when deploying applications that use these + libraries, particularly when the application is statically linked + to them. + + The following table contains an inexhaustive summary of the issues + you should be aware of. + + \table + \header \o Qt Library \o Dependency + \o Licensing Issue + \row \o QtHelp \o CLucene + \o The version of clucene distributed with Qt is licensed + under the GNU LGPL version 2.1 or later. This has implications for + developers of closed source applications. Please see + \l{QtHelp Module#License Information}{the QtHelp module documentation} + for more information. + + \row \o QtNetwork \o OpenSSL + \o Some configurations of QtNetwork use OpenSSL at run-time. Deployment + of OpenSSL libraries is subject to both licensing and export restrictions. + More information can be found in the \l{Secure Sockets Layer (SSL) Classes} + documentation. + + \row \o QtWebKit \o WebKit + \o WebKit is licensed under the GNU LGPL version 2 or later. + This has implications for developers of closed source applications. + Please see \l{QtWebKit Module#License Information}{the QtWebKit module + documentation} for more information. + + \row \o \l{Phonon Module}{Phonon} \o Phonon + \o Phonon relies on the native multimedia engines on different platforms. + Phonon itself is licensed under the GNU LGPL version 2. Please see + \l{Phonon Module#License Information}{the Phonon module documentation} + for more information on licensing and the + \l{Phonon Overview#Backends}{Phonon Overview} for details of the backends + in use on different platforms. + \endtable + + \section1 Platform-Specific Notes + + The procedure of deploying Qt applications is different for the + various platforms: + + \list + \o \l{Deploying an Application on X11 Platforms}{Qt for X11 Platforms} + \o \l{Deploying an Application on Windows}{Qt for Windows} + \o \l{Deploying an Application on Mac OS X}{Qt for Mac OS X} + \o \l{Deploying Qt for Embedded Linux Applications}{Qt for Embedded Linux} + \endlist + + \sa Installation {Platform-Specific Documentation} +*/ + +/*! + \page deployment-x11.html + \contentspage Deploying Qt Applications + + \title Deploying an Application on X11 Platforms + + Due to the proliferation of Unix systems (commercial Unices, Linux + distributions, etc.), deployment on Unix is a complex + topic. Before we start, be aware that programs compiled for one + Unix flavor will probably not run on a different Unix system. For + example, unless you use a cross-compiler, you cannot compile your + application on Irix and distribute it on AIX. + + Contents: + + \tableofcontents + + This documentation will describe how to determine which files you + should include in your distribution, and how to make sure that the + application will find them at run-time. We will demonstrate the + procedures in terms of deploying the \l {tools/plugandpaint}{Plug + & Paint} application that is provided in Qt's examples directory. + + \section1 Static Linking + + Static linking is often the safest and easiest way to distribute + an application on Unix since it relieves you from the task of + distributing the Qt libraries and ensuring that they are located + in the default search path for libraries on the target system. + + \section2 Building Qt Statically + + To use this approach, you must start by installing a static version + of the Qt library: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 0 + + We specify the prefix so that we do not overwrite the existing Qt + installation. The example above only builds the Qt libraries, + i.e. the examples and Qt Designer will not be built. When \c make + is done, you will find the Qt libraries in the \c /path/to/Qt/lib + directory. + + When linking your application against static Qt libraries, note + that you might need to add more libraries to the \c LIBS line in + your project file. For more information, see the \l {Application + Dependencies} section. + + \section2 Linking the Application to the Static Version of Qt + + Once Qt is built statically, the next step is to regenerate the + makefile and rebuild the application. First, we must go into the + directory that contains the application: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 1 + + Now run qmake to create a new makefile for the application, and do + a clean build to create the statically linked executable: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 2 + + You probably want to link against the release libraries, and you + can specify this when invoking \c qmake. Note that we must set the + path to the static Qt that we just built. + + To check that the application really links statically with Qt, run + the \c ldd tool (available on most Unices): + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 3 + + Verify that the Qt libraries are not mentioned in the output. + + Now, provided that everything compiled and linked without any + errors, we should have a \c plugandpaint file that is ready for + deployment. One easy way to check that the application really can + be run stand-alone is to copy it to a machine that doesn't have Qt + or any Qt applications installed, and run it on that machine. + + Remember that if your application depends on compiler specific + libraries, these must still be redistributed along with your + application. For more information, see the \l {Application + Dependencies} section. + + The \l {tools/plugandpaint}{Plug & Paint} example consists of + several components: The core application (\l + {tools/plugandpaint}{Plug & Paint}), and the \l + {tools/plugandpaintplugins/basictools}{Basic Tools} and \l + {tools/plugandpaintplugins/extrafilters}{Extra Filters} + plugins. Since we cannot deploy plugins using the static linking + approach, the executable we have prepared so far is + incomplete. The application will run, but the functionality will + be disabled due to the missing plugins. To deploy plugin-based + applications we should use the shared library approach. + + \section1 Shared Libraries + + We have two challenges when deploying the \l + {tools/plugandpaint}{Plug & Paint} application using the shared + libraries approach: The Qt runtime has to be correctly + redistributed along with the application executable, and the + plugins have to be installed in the correct location on the target + system so that the application can find them. + + \section2 Building Qt as a Shared Library + + We assume that you already have installed Qt as a shared library, + which is the default when installing Qt, in the \c /path/to/Qt + directory. For more information on how to build Qt, see the \l + {Installation} documentation. + + \section2 Linking the Application to Qt as a Shared Library + + After ensuring that Qt is built as a shared library, we can build + the \l {tools/plugandpaint}{Plug & Paint} application. First, we + must go into the directory that contains the application: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 4 + + Now run qmake to create a new makefile for the application, and do + a clean build to create the dynamically linked executable: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 5 + + This builds the core application, the following will build the + plugins: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 6 + + If everything compiled and linked without any errors, we will get + a \c plugandpaint executable and the \c libpnp_basictools.so and + \c libpnp_extrafilters.so plugin files. + + \section2 Creating the Application Package + + There is no standard package management on Unix, so the method we + present below is a generic solution. See the documentation for + your target system for information on how to create a package. + + To deploy the application, we must make sure that we copy the + relevant Qt libraries (corresponding to the Qt modules used in the + application) as well as the executable to the same + directory. Remember that if your application depends on compiler + specific libraries, these must also be redistributed along with + your application. For more information, see the \l {Application + Dependencies} section. + + We'll cover the plugins shortly, but the main issue with shared + libraries is that you must ensure that the dynamic linker will + find the Qt libraries. Unless told otherwise, the dynamic linker + doesn't search the directory where your application resides. There + are many ways to solve this: + + \list + \o You can install the Qt libraries in one of the system + library paths (e.g. \c /usr/lib on most systems). + + \o You can pass a predetermined path to the \c -rpath command-line + option when linking the application. This will tell the dynamic + linker to look in this directory when starting your application. + + \o You can write a startup script for your application, where you + modify the dynamic linker configuration (e.g. adding your + application's directory to the \c LD_LIBRARY_PATH environment + variable. \note If your application will be running with "Set + user ID on execution," and if it will be owned by root, then + LD_LIBRARY_PATH will be ignored on some platforms. In this + case, use of the LD_LIBRARY_PATH approach is not an option). + + \endlist + + The disadvantage of the first approach is that the user must have + super user privileges. The disadvantage of the second approach is + that the user may not have privileges to install into the + predetemined path. In either case, the users don't have the option + of installing to their home directory. We recommend using the + third approach since it is the most flexible. For example, a \c + plugandpaint.sh script will look like this: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 7 + + By running this script instead of the executable, you are sure + that the Qt libraries will be found by the dynamic linker. Note + that you only have to rename the script to use it with other + applications. + + When looking for plugins, the application searches in a plugins + subdirectory inside the directory of the application + executable. Either you have to manually copy the plugins into the + \c plugins directory, or you can set the \c DESTDIR in the + plugins' project files: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 8 + + An archive distributing all the Qt libraries, and all the plugins, + required to run the \l {tools/plugandpaint}{Plug & Paint} + application, would have to include the following files: + + \table 100% + \header + \o Component \o {2, 1} File Name + \row + \o The executable + \o {2, 1} \c plugandpaint + \row + \o The script to run the executable + \o {2, 1} \c plugandpaint.sh + \row + \o The Basic Tools plugin + \o {2, 1} \c plugins\libpnp_basictools.so + \row + \o The ExtraFilters plugin + \o {2, 1} \c plugins\libpnp_extrafilters.so + \row + \o The Qt Core module + \o {2, 1} \c libQtCore.so.4 + \row + \o The Qt GUI module + \o {2, 1} \c libQtGui.so.4 + \endtable + + On most systems, the extension for shared libraries is \c .so. A + notable exception is HP-UX, which uses \c .sl. + + Remember that if your application depends on compiler specific + libraries, these must still be redistributed along with your + application. For more information, see the \l {Application + Dependencies} section. + + To verify that the application now can be successfully deployed, + you can extract this archive on a machine without Qt and without + any compiler installed, and try to run it, i.e. run the \c + plugandpaint.sh script. + + An alternative to putting the plugins in the \c plugins + subdirectory is to add a custom search path when you start your + application using QApplication::addLibraryPath() or + QApplication::setLibraryPaths(). + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 9 + + \section1 Application Dependencies + + \section2 Additional Libraries + + To find out which libraries your application depends on, run the + \c ldd tool (available on most Unices): + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 10 + + This will list all the shared library dependencies for your + application. Depending on configuration, these libraries must be + redistributed along with your application. In particular, the + standard C++ library must be redistributed if you're compiling + your application with a compiler that is binary incompatible with + the system compiler. When possible, the safest solution is to link + against these libraries statically. + + You will probably want to link dynamically with the regular X11 + libraries, since some implementations will try to open other + shared libraries with \c dlopen(), and if this fails, the X11 + library might cause your application to crash. + + It's also worth mentioning that Qt will look for certain X11 + extensions, such as Xinerama and Xrandr, and possibly pull them + in, including all the libraries that they link against. If you + can't guarantee the presence of a certain extension, the safest + approach is to disable it when configuring Qt (e.g. \c {./configure + -no-xrandr}). + + FontConfig and FreeType are other examples of libraries that + aren't always available or that aren't always binary + compatible. As strange as it may sound, some software vendors have + had success by compiling their software on very old machines and + have been very careful not to upgrade any of the software running + on them. + + When linking your application against the static Qt libraries, you + must explicitly link with the dependent libraries mentioned + above. Do this by adding them to the \c LIBS variable in your + project file. + + \section2 Qt Plugins + + Your application may also depend on one or more Qt plugins, such + as the JPEG image format plugin or a SQL driver plugin. Be sure + to distribute any Qt plugins that you need with your application, + and note that each type of plugin should be located within a + specific subdirectory (such as \c imageformats or \c sqldrivers) + within your distribution directory, as described below. + + \note If you are deploying an application that uses QtWebKit to display + HTML pages from the World Wide Web, you should include all text codec + plugins to support as many HTML encodings possible. + + The search path for Qt plugins (as well as a few other paths) is + hard-coded into the QtCore library. By default, the first plugin + search path will be hard-coded as \c /path/to/Qt/plugins. As + mentioned above, using pre-determined paths has certain + disadvantages, so you need to examine various alternatives to make + sure that the Qt plugins are found: + + \list + + \o \l{qt-conf.html}{Using \c qt.conf}. This is the recommended + approach since it provides the most flexibility. + + \o Using QApplication::addLibraryPath() or + QApplication::setLibraryPaths(). + + \o Using a third party installation utility or the target system's + package manager to change the hard-coded paths in the QtCore + library. + + \endlist + + The \l{How to Create Qt Plugins} document outlines the issues you + need to pay attention to when building and deploying plugins for + Qt applications. +*/ + +/*! + \page deployment-windows.html + \contentspage Deploying Qt Applications + + \title Deploying an Application on Windows + + This documentation will describe how to determine which files you + should include in your distribution, and how to make sure that the + application will find them at run-time. We will demonstrate the + procedures in terms of deploying the \l {tools/plugandpaint}{Plug + & Paint} application that is provided in Qt's examples directory. + + Contents: + + \tableofcontents + + \section1 Static Linking + + If you want to keep things simple by only having a few files to + deploy, i.e. a stand-alone executable with the associated compiler + specific DLLs, then you must build everything statically. + + \section2 Building Qt Statically + + Before we can build our application we must make sure that Qt is + built statically. To do this, go to a command prompt and type the + following: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 11 + + Remember to specify any other options you need, such as data base + drivers, as arguments to \c configure. Once \c configure has + finished, type the following: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 12 + + This will build Qt statically. Note that unlike with a dynamic build, + building Qt statically will result in libraries without version numbers; + e.g. \c QtCore4.lib will be \c QtCore.lib. Also, we have used \c nmake + in all the examples, but if you use MinGW you must use + \c mingw32-make instead. + + \note If you later need to reconfigure and rebuild Qt from the + same location, ensure that all traces of the previous configuration are + removed by entering the build directory and typing \c{nmake distclean} + before running \c configure again. + + \section2 Linking the Application to the Static Version of Qt + + Once Qt has finished building we can build the \l + {tools/plugandpaint}{Plug & Paint} application. First we must go + into the directory that contains the application: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 13 + + We must then run \c qmake to create a new makefile for the + application, and do a clean build to create the statically linked + executable: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 14 + + You probably want to link against the release libraries, and you + can specify this when invoking \c qmake. Now, provided that + everything compiled and linked without any errors, we should have + a \c plugandpaint.exe file that is ready for deployment. One easy + way to check that the application really can be run stand-alone is + to copy it to a machine that doesn't have Qt or any Qt + applications installed, and run it on that machine. + + Remember that if your application depends on compiler specific + libraries, these must still be redistributed along with your + application. You can check which libraries your application is + linking against by using the \c depends tool. For more + information, see the \l {Application Dependencies} section. + + The \l {tools/plugandpaint}{Plug & Paint} example consists of + several components: The application itself (\l + {tools/plugandpaint}{Plug & Paint}), and the \l + {tools/plugandpaintplugins/basictools}{Basic Tools} and \l + {tools/plugandpaintplugins/extrafilters}{Extra Filters} + plugins. Since we cannot deploy plugins using the static linking + approach, the application we have prepared is incomplete. It will + run, but the functionality will be disabled due to the missing + plugins. To deploy plugin-based applications we should use the + shared library approach. + + \section1 Shared Libraries + + We have two challenges when deploying the \l + {tools/plugandpaint}{Plug & Paint} application using the shared + libraries approach: The Qt runtime has to be correctly + redistributed along with the application executable, and the + plugins have to be installed in the correct location on the target + system so that the application can find them. + + \section2 Building Qt as a Shared Library + + We assume that you already have installed Qt as a shared library, + which is the default when installing Qt, in the \c C:\path\to\Qt + directory. For more information on how to build Qt, see the \l + {Installation} documentation. + + \section2 Linking the Application to Qt as a Shared Library + + After ensuring that Qt is built as a shared library, we can build + the \l {tools/plugandpaint}{Plug & Paint} application. First, we + must go into the directory that contains the application: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 15 + + Now run \c qmake to create a new makefile for the application, and + do a clean build to create the dynamically linked executable: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 16 + + This builds the core application, the following will build the + plugins: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 17 + + If everything compiled and linked without any errors, we will get + a \c plugandpaint.exe executable and the \c pnp_basictools.dll and + \c pnp_extrafilters.dll plugin files. + + \section2 Creating the Application Package + + To deploy the application, we must make sure that we copy the + relevant Qt DLL (corresponding to the Qt modules used in + the application) as well as the executable to the same directory + in the \c release subdirectory. + + Remember that if your application depends on compiler specific + libraries, these must be redistributed along with your + application. You can check which libraries your application is + linking against by using the \c depends tool. For more + information, see the \l {Application Dependencies} section. + + We'll cover the plugins shortly, but first we'll check that the + application will work in a deployed environment: Either copy the + executable and the Qt DLLs to a machine that doesn't have Qt + or any Qt applications installed, or if you want to test on the + build machine, ensure that the machine doesn't have Qt in its + environment. + + If the application starts without any problems, then we have + successfully made a dynamically linked version of the \l + {tools/plugandpaint}{Plug & Paint} application. But the + application's functionality will still be missing since we have + not yet deployed the associated plugins. + + Plugins work differently to normal DLLs, so we can't just + copy them into the same directory as our application's executable + as we did with the Qt DLLs. When looking for plugins, the + application searches in a \c plugins subdirectory inside the + directory of the application executable. + + So to make the plugins available to our application, we have to + create the \c plugins subdirectory and copy over the relevant DLLs: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 18 + + An archive distributing all the Qt DLLs and application + specific plugins required to run the \l {tools/plugandpaint}{Plug + & Paint} application, would have to include the following files: + + \table 100% + \header + \o Component \o {2, 1} File Name + \row + \o The executable + \o {2, 1} \c plugandpaint.exe + \row + \o The Basic Tools plugin + \o {2, 1} \c plugins\pnp_basictools.dll + \row + \o The ExtraFilters plugin + \o {2, 1} \c plugins\pnp_extrafilters.dll + \row + \o The Qt Core module + \o {2, 1} \c qtcore4.dll + \row + \o The Qt GUI module + \o {2, 1} \c qtgui4.dll + \endtable + + In addition, the archive must contain the following compiler + specific libraries depending on your version of Visual Studio: + + \table 100% + \header + \o \o VC++ 6.0 \o VC++ 7.1 (2003) \o VC++ 8.0 (2005) \o VC++ 9.0 (2008) + \row + \o The C run-time + \o \c msvcrt.dll + \o \c msvcr71.dll + \o \c msvcr80.dll + \o \c msvcr90.dll + \row + \o The C++ run-time + \o \c msvcp60.dll + \o \c msvcp71.dll + \o \c msvcp80.dll + \o \c msvcp90.dll + \endtable + + To verify that the application now can be successfully deployed, + you can extract this archive on a machine without Qt and without + any compiler installed, and try to run it. + + An alternative to putting the plugins in the plugins subdirectory + is to add a custom search path when you start your application + using QApplication::addLibraryPath() or + QApplication::setLibraryPaths(). + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 19 + + One benefit of using plugins is that they can easily be made + available to a whole family of applications. + + It's often most convenient to add the path in the application's \c + main() function, right after the QApplication object is + created. Once the path is added, the application will search it + for plugins, in addition to looking in the \c plugins subdirectory + in the application's own directory. Any number of additional paths + can be added. + + \section2 Visual Studio 2005 Onwards + + When deploying an application compiled with Visual Studio 2005 onwards, + there are some additional steps to be taken. + + First, we need to copy the manifest file created when linking the + application. This manifest file contains information about the + application's dependencies on side-by-side assemblies, such as the runtime + libraries. + + The manifest file needs to be copied into the \bold same folder as the + application executable. You do not need to copy the manifest files for + shared libraries (DLLs), since they are not used. + + If the shared library has dependencies that are different from the + application using it, the manifest file needs to be embedded into the DLL + binary. Since Qt 4.1.3, the follwoing \c CONFIG options are available for + embedding manifests: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 20 + + To use the options, add + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 21 + + to your .pro file. The \c embed_manifest_dll option is enabled by default. + + You can find more information about manifest files and side-by-side + assemblies at the + \l {http://msdn.microsoft.com/en-us/library/aa376307.aspx}{MSDN website}. + + There are two ways to include the run time libraries: by bundling them + directly with your application or by installing them on the end-user's + system. + + To bundle the run time libraries with your application, copy the directory + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 22 + + into the folder where your executable is, so that you are including a + \c Microsoft.VC80.CRT directory alongside your application's executable. If + you are bundling the runtimes and need to deploy plugins as well, you have + to remove the manifest from the plugins (embedded as a resource) by adding + the following line to the \c{.pro} file of the plugins you are compiling: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 23 + + \warning If you skip the step above, the plugins will not load on some + systems. + + To install the runtime libraries on the end-user's system, you need to + include the appropriate Visual C++ Redistributable Package (VCRedist) + executable with your application and ensure that it is executed when the + user installs your application. + + For example, on an 32-bit x86-based system, you would include the + \l{http://www.microsoft.com/downloads/details.aspx?FamilyId=32BC1BEE-A3F9-4C13-9C99-220B62A191EE}{vcredist_x86.exe} + executable. The \l{http://www.microsoft.com/downloads/details.aspx?familyid=526BF4A7-44E6-4A91-B328-A4594ADB70E5}{vcredist_IA64.exe} + and \l{http://www.microsoft.com/downloads/details.aspx?familyid=90548130-4468-4BBC-9673-D6ACABD5D13B}{vcredist_x64.exe} + executables provide the appropriate libraries for the IA64 and 64-bit x86 + architectures, respectively. + + \note The application you ship must be compiled with exactly the same + compiler version against the same C runtime version. This prevents + deploying errors caused by different versions of the C runtime libraries. + + + \section1 Application Dependencies + + \section2 Additional Libraries + + Depending on configuration, compiler specific libraries must be + redistributed along with your application. You can check which + libraries your application is linking against by using the + \l{Dependency Walker} tool. All you need to do is to run it like + this: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 24 + + This will provide a list of the libraries that your application + depends on and other information. + + \image deployment-windows-depends.png + + When looking at the release build of the Plug & Paint executable + (\c plugandpaint.exe) with the \c depends tool, the tool lists the + following immediate dependencies to non-system libraries: + + \table 100% + \header + \o Qt + \o VC++ 6.0 + \o VC++ 7.1 (2003) + \o VC++ 8.0 (2005) + \o MinGW + \row + \o \list + \o QTCORE4.DLL - The QtCore runtime + \o QTGUI4.DLL - The QtGui runtime + \endlist + \o \list + \o MSVCRT.DLL - The C runtime + \o MSVCP60.DLL - The C++ runtime (only when STL is installed) + \endlist + \o \list + \o MSVCR71.DLL - The C runtime + \o MSVCP71.DLL - The C++ runtime (only when STL is installed) + \endlist + \o \list + \o MSVCR80.DLL - The C runtime + \o MSVCP80.DLL - The C++ runtime (only when STL is installed) + \endlist + \o \list + \o MINGWM10.DLL - The MinGW run-time + \endlist + \endtable + + When looking at the plugin DLLs the exact same dependencies + are listed. + + \section2 Qt Plugins + + Your application may also depend on one or more Qt plugins, such + as the JPEG image format plugin or a SQL driver plugin. Be sure + to distribute any Qt plugins that you need with your application, + and note that each type of plugin should be located within a + specific subdirectory (such as \c imageformats or \c sqldrivers) + within your distribution directory, as described below. + + \note If you are deploying an application that uses QtWebKit to display + HTML pages from the World Wide Web, you should include all text codec + plugins to support as many HTML encodings possible. + + The search path for Qt plugins is hard-coded into the QtCore library. + By default, the plugins subdirectory of the Qt installation is the first + plugin search path. However, pre-determined paths like the default one + have certain disadvantages. For example, they may not exist on the target + machine. For that reason, you need to examine various alternatives to make + sure that the Qt plugins are found: + + \list + + \o \l{qt-conf.html}{Using \c qt.conf}. This approach is the recommended + if you have executables in different places sharing the same plugins. + + \o Using QApplication::addLibraryPath() or + QApplication::setLibraryPaths(). This approach is recommended if you only + have one executable that will use the plugin. + + \o Using a third party installation utility to change the + hard-coded paths in the QtCore library. + + \endlist + + If you add a custom path using QApplication::addLibraryPath it could + look like this: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 54 + + Then qApp->libraryPaths() would return something like this: + + "C:/customPath/plugins " + "C:/Qt/%VERSION%/plugins" + "E:/myApplication/directory/" + + The executable will look for the plugins in these directories and + the same order as the QStringList returned by qApp->libraryPaths(). + The newly added path is prepended to the qApp->libraryPaths() which + means that it will be searched through first. However, if you use + qApp->setLibraryPaths(), you will be able to determend which paths + and in which order they will be searched. + + The \l{How to Create Qt Plugins} document outlines the issues you + need to pay attention to when building and deploying plugins for + Qt applications. +*/ + +/*! + \page deployment-mac.html + \contentspage Deploying Qt Applications + + \title Deploying an Application on Mac OS X + + Starting with version 4.5, Qt now includes a \l {macdeploy}{deployment tool} + that automates the prodecures described in this document. + + This documentation will describe how to create a bundle, and how + to make sure that the application will find the resources it needs + at run-time. We will demonstrate the procedures in terms of + deploying the \l {tools/plugandpaint}{Plug & Paint} application + that is provided in Qt's examples directory. + + \tableofcontents + + \section1 The Bundle + + On the Mac, a GUI application must be built and run from a + bundle. A bundle is a directory structure that appears as a single + entity when viewed in the Finder. A bundle for an application + typcially contains the executable and all the resources it + needs. See the image below: + + \image deployment-mac-bundlestructure.png + + The bundle provides many advantages to the user. One primary + advantage is that, since it is a single entity, it allows for + drag-and-drop installation. As a programmer you can access bundle + information in your own code. This is specific to Mac OS X and + beyond the scope of this document. More information about bundles + is available on \l + {http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/index.html}{Apple's Developer Website}. + + A Qt command line application on Mac OS X works similar to a + command line application on Unix and Windows. You probably don't + want to run it in a bundle: Add this to your application's .pro: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 26 + + This will tell \c qmake not to put the executable inside a + bundle. Please refer to the \l{Deploying an Application on + X11 Platforms}{X11 deployment documentation} for information about how + to deploy these "bundle-less" applications. + + \section1 Xcode + + We will only concern ourselves with command-line tools here. While + it is possible to use Xcode for this, Xcode has changed enough + between each version that it makes it difficult to document it + perfectly for each version. A future version of this document may + include more information for using Xcode in the deployment + process. + + \section1 Static Linking + + If you want to keep things simple by only having a few files to + deploy, then you must build everything statically. + + \section2 Building Qt Statically + + Start by installing a static version of the Qt library. Remember + that you will not be able to use plugins and you must build in all + the image formats, SQL drivers, etc.. + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 27 + + You can check the various options that are available by running \c + configure -help. + + \section2 Linking the Application to the Static Version of Qt + + Once Qt is built statically, the next step is to regenerate the + makefile and rebuild the application. First, we must go into the + directory that contains the application: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 28 + + Now run \c qmake to create a new makefile for the application, and do + a clean build to create the statically linked executable: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 29 + + You probably want to link against the release libraries, and you + can specify this when invoking \c qmake. If you have Xcode Tools + 1.5 or higher installed, you may want to take advantage of "dead + code stripping" to reduce the size of your binary even more. You + can do this by passing \c {LIBS+= -dead_strip} to \c qmake in + addition to the \c {-config release} parameter. This doesn't have + as large an effect if you are using GCC 4, since Qt will then have + function visibility hints built-in, but if you use GCC 3.3, it + could make a difference. + + Now, provided that everything compiled and linked without any + errors, we should have a \c plugandpaint.app bundle that is ready + for deployment. One easy way to check that the application really + can be run stand-alone is to copy the bundle to a machine that + doesn't have Qt or any Qt applications installed, and run the + application on that machine. + + You can check what other libraries your application links to using + the \c otool: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 30 + + Here is what the output looks like for the static \l + {tools/plugandpaint}{Plug & Paint}: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 31 + + For more information, see the \l {Application Dependencies} + section. + + If you see \e Qt libraries in the output, it probably + means that you have both dynamic and static Qt libraries installed + on your machine. The linker will always choose dynamic over + static. There are two solutions: Either move your Qt dynamic + libraries (\c .dylibs) away to another directory while you link + the application and then move them back, or edit the \c Makefile + and replace link lines for the Qt libraries with the absolute path + to the static libraries. For example, replace + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 32 + + with + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 33 + + The \l {tools/plugandpaint}{Plug & Paint} example consists of + several components: The core application (\l + {tools/plugandpaint}{Plug & Paint}), and the \l + {tools/plugandpaintplugins/basictools}{Basic Tools} and \l + {tools/plugandpaintplugins/extrafilters}{Extra Filters} + plugins. Since we cannot deploy plugins using the static linking + approach, the bundle we have prepared so far is incomplete. The + application will run, but the functionality will be disabled due + to the missing plugins. To deploy plugin-based applications we + should use the framework approach. + + \section1 Frameworks + + We have two challenges when deploying the \l + {tools/plugandpaint}{Plug & Paint} application using frameworks: + The Qt runtime has to be correctly redistributed along with the + application bundle, and the plugins have to be installed in the + correct location so that the application can find them. + + When distributing Qt with your application using frameworks, you + have two options: You can either distribute Qt as a private + framework within your application bundle, or you can distribute Qt + as a standard framework (alternatively use the Qt frameworks in + the installed binary). These two approaches are essentially the + same. The latter option is good if you have many Qt applications + and you would prefer to save memory. The former is good if you + have Qt built in a special way, or want to make sure the framework + is there. It just comes down to where you place the Qt frameworks. + + \section2 Building Qt as Frameworks + + We assume that you already have installed Qt as frameworks, which + is the default when installing Qt, in the /path/to/Qt + directory. For more information on how to build Qt, see the \l + Installation documentation. + + When installing, the identification name of the frameworks will + also be set. The identification name is what the dynamic linker + (\c dyld) uses to find the libraries for your application. + + \section2 Linking the Application to Qt as Frameworks + + After ensuring that Qt is built as frameworks, we can build the \l + {tools/plugandpaint}{Plug & Paint} application. First, we must go + into the directory that contains the application: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 34 + + Now run qmake to create a new makefile for the application, and do + a clean build to create the dynamically linked executable: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 35 + + This builds the core application, the following will build the + plugins: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 36 + + Now run the \c otool for the Qt frameworks, for example Qt Gui: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 37 + + You will get the following output: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 38 + + For the Qt frameworks, the first line (i.e. \c + {path/to/Qt/lib/QtGui.framework/Versions/4/QtGui (compatibility + version 4.0.0, current version 4.0.1)}) becomes the framework's + identification name which is used by the dynamic linker (\c dyld). + + But when you are deploying the application, your users may not + have the Qt frameworks installed in the specified location. For + that reason, you must either provide the frameworks in an agreed + upon location, or store the frameworks in the bundle itself. + Regardless of which solution you choose, you must make sure that + the frameworks return the proper identification name for + themselves, and that the application will look for these + names. Luckily we can control this with the \c install_name_tool + command-line tool. + + The \c install_name_tool works in two modes, \c -id and \c + -change. The \c -id mode is for libraries and frameworks, and + allows us to specify a new identification name. We use the \c + -change mode to change the paths in the application. + + Let's test this out by copying the Qt frameworks into the Plug & + Paint bundle. Looking at \c otool's output for the bundle, we can + see that we must copy both the QtCore and QtGui frameworks into + the bundle. We will assume that we are in the directory where we + built the bundle. + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 39 + + First we create a \c Frameworks directory inside the bundle. This + follows the Mac OS X application convention. We then copy the + frameworks into the new directory. Since frameworks contain + symbolic links, and we want to preserve them, we use the \c -R + option. + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 40 + + Then we run \c install_name_tool to set the identification names + for the frameworks. The first argument after \c -id is the new + name, and the second argument is the framework which + identification we wish to change. The text \c @executable_path is + a special \c dyld variable telling \c dyld to start looking where + the executable is located. The new names specifies that these + frameworks will be located "one directory up and over" in the \c + Frameworks directory. + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 41 + + Now, the dynamic linker knows where to look for QtCore and + QtGui. Then we must make the application aware of the library + locations as well using \c install_name_tool's \c -change mode. + This basically comes down to string replacement, to match the + identification names that we set for the frameworks. + + Finally, since the QtGui framework depends on QtCore, we must + remember to change the reference for QtGui: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 42 + + After all this we can run \c otool again and see that the + application will look in the right locations. + + Of course, the thing that makes the \l {tools/plugandpaint}{Plug & + Paint} example interesting are its plugins. The basic steps we + need to follow with plugins are: + + \list + \o Put the plugins inside the bundle + \o Make sure that the plugins use the correct library using the + \c install_name_tool + \o Make sure that the application knows where to get the plugins + \endlist + + While we can put the plugins anywhere we want in the bundle, the + best location to put them is under Contents/Plugins. When we built + the Plug & Paint plugins, the \c DESTDIR variable in their \c .pro + file put the plugins' \c .dylib files in a \c plugins subdirectory + in the \c plugandpaint directory. So, in this example, all we need + to do is move this directory: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 43 + + If we run \c otool on for example the \l + {tools/plugandpaintplugins/basictools}{Basic Tools} plugin's \c + .dylib file we get the following information. + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 44 + + Then we can see that the plugin links to the Qt frameworks it was + built against. Since we want the plugins to use the framework in + the application bundle we change them the same way as we did for + the application. For example for the Basic Tools plugin: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 45 + + + We must also modify the code in \c + tools/plugandpaint/mainwindow.cpp to \l {QDir::cdUp()}{cdUp()} one + directory since the plugins live in the bundle. Add the following + code to the \c mainwindow.cpp file: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 46 + + \table + \row + \o \inlineimage deployment-mac-application.png + \o + The additional code in \c tools/plugandpaint/mainwindow.cpp also + enables us to view the plugins in the Finder, as shown to the left. + + We can also add plugins extending Qt, for example adding SQL + drivers or image formats. We just need to follow the directory + structure outlined in plugin documentation, and make sure they are + included in the QCoreApplication::libraryPaths(). Let's quickly do + this with the image formats, following the approach from above. + + Copy Qt's image format plugins into the bundle: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 47 + + Use \c install_name_tool to link the plugins to the frameworks in + the bundle: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 48 + + Then we update the source code in \c tools/plugandpaint/main.cpp + to look for the new plugins. After constructing the + QApplication, we add the following code: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 49 + + First, we tell the application to only look for plugins in this + directory. In our case, this is what we want since we only want to + look for the plugins that we distribute with the bundle. If we + were part of a bigger Qt installation we could have used + QCoreApplication::addLibraryPath() instead. + + \endtable + + \warning When deploying plugins, and thus make changes to the + source code, the default identification names are reset when + rebuilding the application, and you must repeat the process of + making your application link to the Qt frameworks in the bundle + using \c install_name_tool. + + Now you should be able to move the application to another Mac OS X + machine and run it without Qt installed. Alternatively, you can + move your frameworks that live outside of the bundle to another + directory and see if the application still runs. + + If you store the frameworks in another location than in the + bundle, the technique of linking your application is similar; you + must make sure that the application and the frameworks agree where + to be looking for the Qt libraries as well as the plugins. + + \section2 Creating the Application Package + + When you are done linking your application to Qt, either + statically or as frameworks, the application is ready to be + distributed. Apple provides a fair bit of information about how to + do this and instead of repeating it here, we recommend that you + consult their \l + {http://developer.apple.com/documentation/DeveloperTools/Conceptual/SoftwareDistribution/index.html}{software delivery} + documentation. + + Although the process of deploying an application do have some + pitfalls, once you know the various issues you can easily create + packages that all your Mac OS X users will enjoy. + + \section1 Application Dependencies + + \section2 Qt Plugins + + Your application may also depend on one or more Qt plugins, such + as the JPEG image format plugin or a SQL driver plugin. Be sure + to distribute any Qt plugins that you need with your application, + and note that each type of plugin should be located within a + specific subdirectory (such as \c imageformats or \c sqldrivers) + within your distribution directory, as described below. + + \note If you are deploying an application that uses QtWebKit to display + HTML pages from the World Wide Web, you should include all text codec + plugins to support as many HTML encodings possible. + + The search path for Qt plugins (as well as a few other paths) is + hard-coded into the QtCore library. By default, the first plugin + search path will be hard-coded as \c /path/to/Qt/plugins. But + using pre-determined paths has certain disadvantages. For example, + they may not exist on the target machine. For that reason you need + to examine various alternatives to make sure that the Qt plugins + are found: + + \list + + \o \l{qt-conf.html}{Using \c qt.conf}. This is the recommended + approach since it provides the most flexibility. + + \o Using QApplication::addLibraryPath() or + QApplication::setLibraryPaths(). + + \o Using a third party installation utility to change the + hard-coded paths in the QtCore library. + + \endlist + + The \l{How to Create Qt Plugins} document outlines the issues you + need to pay attention to when building and deploying plugins for + Qt applications. + + \section2 Additional Libraries + + You can check which libraries your application is linking against + by using the \c otool tool. To use \c otool, all you need to do is + to run it like this: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 50 + + Unlike the deployment processes on \l {Deploying an Application on + X11 Platforms}{X11} and \l {Deploying an Application on + Windows}{Windows}, compiler specific libraries rarely have to + be redistributed along with your application. But since Qt can be + configured, built, and installed in several ways on Mac OS X, + there are also several ways to deploy applications. Typically your + goals help determine how you are going to deploy the + application. The last sections describe a couple of things to keep + in mind when you are deploying your application. + + \section2 Mac OS X Version Dependencies + + Qt 4.2 has been designed to be built and deployed on Mac OS X 10.3 + up until the current version as of this writing, Mac OS X 10.4 and + all their minor releases. Qt achieves this by using "weak + linking." This means that Qt tests if a function added in newer + versions of Mac OS X is available on the computer it is running on + before it uses it. This results in getting access to newer + features when running on newer versions of OS X while still + remaining compatible on older versions. + + For more information about cross development issues on Mac OS X, + see \l + {http://developer.apple.com/documentation/DeveloperTools/Conceptual/cross_development/index.html}{Apple's Developer Website}. + + Since the linker is set to be compatible with all OS X version, you have to + change the \c MACOSX_DEPLOYMENT_TARGET environment variable to get weak + linking to work for your application. You can add: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 51 + + to your .pro file and qmake will take care of this for you. + + However, there is a bit of a wrinkle to keep in mind when your are + deploying. Mac OS X 10.4 ("Tiger") ships GCC 4.0 as its default + compiler. This is also the GCC compiler we use for building the + binary Qt package. If you use GCC 4.0 to build your application, + it will link against a dynamic libstdc++ that is only available on + Mac OS X 10.4 and Mac OS X 10.3.9. The application will refuse to + run on older versions of the operating system. + + For more information about C++ runtime environment, see \l + {http://developer.apple.com/documentation/DeveloperTools/Conceptual/CppRuntimeEnv/index.html}{Apple's Developer Website} + + If you want to deploy to versions of Mac OS X earlier than 10.3.9, + you must build with GCC 3.3 which is the default on Mac OS X + 10.3. GCC 3.3 is also available on the Mac OS X 10.4 "Xcode Tools" + CD and as a download for earlier versions of Mac OS X from Apple + (\l {https://connect.apple.com/}{connect.apple.com}). You can use + Apple's \c gcc_select(1) command line tool to switch the default + complier on your system. + + \section3 Deploying Phonon Applications on Mac OS X + + \list + \o If you build your Phonon application on Tiger, it will work on + Tiger, Leopard and Panther. + \o If you build your application on Leopard, it will \bold not work + on Panther unless you rename the libraries with the following command + after you have built your application: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 51a + + This command must be invoked in the directory where + \c{libphonon_qt7.dylib} is located, usually in + \c{yourapp.app/Contents/plugins/phonon_backend/}. + \o The \l {macdeploy}{deployment tool} will perform this step for you. + + \o If you are using Leopard, but would like to build your application + against Tiger, you can use: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 51b + \endlist + + \section2 Architecture Dependencies + + The Qt for Mac OS X libraries, tools, and examples can be built "universal" + (i.e. they run natively on both Intel and PowerPC machines). This + is accomplished by passing \c -universal on the \c configure line + of the source package, and requires that you use GCC 4.0.x. On + PowerPC hardware you will need to pass the universal SDK as a + command line argument to the Qt configure command. For example: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 52 + + From 4.1.1 the Qt binary package is already universal. + + If you want to create a binary that runs on older versions of + PowerPC and x86, it is possible to build Qt for the PowerPC using + GCC 3.3, and for x86 one using GCC 4.0, and use Apple's \c lipo(1) + tool to stitch them together. This is beyond the scope of this + document and is not something we have tried, but Apple documents + it on their \l + {http://developer.apple.com/documentation/}{developer website}. + + Once you have a universal Qt, \a qmake will generate makefiles + that will build for its host architecture by default. If you want + to build for a specific architecture, you can control this with + the \c CONFIG line in your \c .pro file. Use \c CONFIG+=ppc for + PowerPC, and \c CONFIG+=x86 for x86. If you desire both, simply + add both to the \c CONFIG line. PowerPC users also need an + SDK. For example: + + \snippet doc/src/snippets/code/doc_src_deployment.qdoc 53 + + Besides \c lipo, you can also check your binaries with the \c file(1) + command line tool or the Finder. + + \section1 The Mac Deployment Tool + \target macdeploy + The Mac deployment tool can be found in QTDIR/bin/macdeployqt. It is + designed to automate the process of creating a deployable + application bundle that contains the Qt libraries as private + frameworks. + + The mac deployment tool also deploys the Qt plugins, according + to the following rules: + \list + \o Debug versions of the plugins are not deployed. + \o The designer plugins are not deployed. + \o The Image format plugins are always deployed. + \o SQL driver plugins are deployed if the application uses the QtSql module. + \o Script plugins are deployed if the application uses the QtScript module. + \o The Phonon backend plugin is deployed if the application uses the \l{Phonon Module} {Phonon} module. + \o The svg icon plugin is deployed if the application uses the QtSvg module. + \o The accessibility plugin is always deployed. + \o Accessibility for Qt3Support is deployed if the application uses the Qt3Support module. + \endlist + + macdeployqt supports the following options: + \list + \o -no-plugins: Skip plugin deployment + \o -dmg : Create a .dmg disk image + \o -no-strip : Don't run 'strip' on the binaries + \endlist +*/ diff --git a/doc/src/deployment/qt-conf.qdoc b/doc/src/deployment/qt-conf.qdoc new file mode 100644 index 0000000..229fa45 --- /dev/null +++ b/doc/src/deployment/qt-conf.qdoc @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** 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 qt-conf.html + + \title Using qt.conf + + The \c qt.conf file overrides the hard-coded paths that are + compiled into the Qt library. These paths are accessible using the + QLibraryInfo class. Without \c qt.conf, the functions in + QLibraryInfo return these hard-coded paths; otherwise they return + the paths as specified in \c qt.conf. + + Without \c qt.conf, the Qt libraries will use the hard-coded paths + to look for plugins, translations, and so on. These paths may not + exist on the target system, or they may not be + accesssible. Because of this, you need \c qt.conf to make the Qt + libraries look elsewhere. + + QLibraryInfo will load \c qt.conf from one of the following locations: + + \list 1 + + \o \c :/qt/etc/qt.conf using the resource system + + \o on Mac OS X, in the Resource directory inside the appliction + bundle, for example \c assistant.app/Contents/Resources/qt.conf + + \o in the directory containing the application executable, i.e. + QCoreApplication::applicationDirPath() + QDir::separator() + "qt.conf" + + \endlist + + The \c qt.conf file is an INI text file, as described in the \l + {QSettings::Format}{QSettings} documentation. The file should have + a \c Paths group which contains the entries that correspond to + each value of the QLibraryInfo::LibraryLocation enum. See the + QLibraryInfo documentation for details on the meaning of the + various locations. + + \table + + \header \o Entry \o Default Value + + \row \o Prefix \o QCoreApplication::applicationDirPath() + \row \o Documentation \o \c doc + \row \o Headers \o \c include + \row \o Libraries \o \c lib + \row \o Binaries \o \c bin + \row \o Plugins \o \c plugins + \row \o Data \o \c . + \row \o Translations \o \c translations + \row \o Settings \o \c . + \row \o Examples \o \c . + \row \o Demos \o \c . + + \endtable + + Absolute paths are used as specified in the \c qt.conf file. All + paths are relative to the \c Prefix. On Windows and X11, the \c + Prefix is relative to the directory containing the application + executable (QCoreApplication::applicationDirPath()). On Mac OS X, + the \c Prefix is relative to the \c Contents in the application + bundle. For example, \c application.app/Contents/plugins/ is the + default location for loading Qt plugins. Note that the plugins + need to be placed in specific sub-directories under the + \c{plugins} directory (see \l{How to Create Qt Plugins} for + details). + + For example, a \c qt.conf file could contain the following: + + \snippet doc/src/snippets/code/doc_src_qt-conf.qdoc 0 + + Subgroups of the \c Paths group may be used to specify locations + for specific versions of the Qt libraries. Such subgroups are of + the form \c Paths/x.y.z, where x is the major version of the Qt + libraries, y the minor, and z the patch level. The subgroup that + most closely matches the current Qt version is used. If no + subgroup matches, the \c Paths group is used as the fallback. The + minor and patch level values may be omitted, in which case they + default to zero. + + For example, given the following groups: + + \snippet doc/src/snippets/code/doc_src_qt-conf.qdoc 1 + + The current version will be matched as shown: + + \list + \o 4.0.1 matches \c Paths/4 + \o 4.1.5 matches \c Paths/4.1 + \o 4.6.3 matches \c Paths/4.2.5 + \o 5.0.0 matches \c Paths + \o 6.0.2 matches \c Paths/6 + \endlist +*/ diff --git a/doc/src/deployment/qtconfig.qdoc b/doc/src/deployment/qtconfig.qdoc new file mode 100644 index 0000000..2e02fe6 --- /dev/null +++ b/doc/src/deployment/qtconfig.qdoc @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** 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 qtconfig.html + \title Configuring Qt + \ingroup qttools + \keyword qtconfig + + The \c qtconfig tool allows users to customize the default settings for + Qt applications on a per-user basis, enabling features such as the widget + style to be changed without requiring applications to be recompiled. + + \c qtconfig is available on X11 platforms and should be installed alongside + the \l{Qt's Tools}{other tools} supplied with Qt. + + \image qtconfig-appearance.png +*/ diff --git a/doc/src/designer-manual.qdoc b/doc/src/designer-manual.qdoc deleted file mode 100644 index 5d8587a..0000000 --- a/doc/src/designer-manual.qdoc +++ /dev/null @@ -1,2836 +0,0 @@ -/**************************************************************************** -** -** 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/desktop-integration.qdoc b/doc/src/desktop-integration.qdoc deleted file mode 100644 index 1c10ed9..0000000 --- a/doc/src/desktop-integration.qdoc +++ /dev/null @@ -1,90 +0,0 @@ -/**************************************************************************** -** -** 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 desktop-integration.html - \title Desktop Integration - \ingroup gui-programming - - Various classes in Qt are designed to help developers integrate applications into - users' desktop environments. These classes enable developers to take advantage - of native services while still using a cross-platform API. - - \tableofcontents - - \section1 Opening External Resources - - Although Qt provides facilities to handle and display resources, such as - \l{QImageIOHandler}{common image formats} and \l{QTextDocument}{HTML}, - it is sometimes necessary to open files and external resources using external - applications. - - QDesktopServices provides an interface to services offered by the user's desktop - environment. In particular, the \l{QDesktopServices::}{openUrl()} function is - used to open resources using the appropriate application, which may have been - specifically configured by the user. - - \section1 System Tray Icons - - Many modern desktop environments feature docks or panels with \e{system trays} - in which applications can install icons. Applications often use system tray icons - to display status information, either by updating the icon itself or by showing - information in "balloon messages". Additionally, many applications provide - pop-up menus that can be accessed via their system tray icons. - - The QSystemTrayIcon class exposes all of the above features via an intuitive - Qt-style API that can be used on all desktop platforms. - - \section1 Desktop Widgets - - On systems where the user's desktop is displayed using more than one screen, - certain types of applications may need to obtain information about the - configuration of the user's workspace to ensure that new windows and dialogs - are opened in appropriate locations. - - The QDesktopWidget class can be used to monitor the positions of widgets and - notify applications about changes to the way the desktop is split over the - available screens. This enables applications to implement policies for - positioning new windows so that, for example, they do not distract a user - who is working on a specific task. - - -*/ diff --git a/doc/src/developing-on-mac.qdoc b/doc/src/developing-on-mac.qdoc deleted file mode 100644 index 2546ef1..0000000 --- a/doc/src/developing-on-mac.qdoc +++ /dev/null @@ -1,269 +0,0 @@ -/**************************************************************************** -** -** 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-notes - - \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/activeqt-dumpcpp.qdoc b/doc/src/development/activeqt-dumpcpp.qdoc new file mode 100644 index 0000000..8c743a1 --- /dev/null +++ b/doc/src/development/activeqt-dumpcpp.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page activeqt-dumpcpp.html + \title The dumpcpp Tool (ActiveQt) + + \ingroup activeqt-tools + + \keyword dumpcpp + + The \c dumpcpp tool generates a C++ namespace for a type library. + + To generate a C++ namespace for a type library, call \c dumpcpp with the following + command line parameters: + + \table + \header + \i Option + \i Result + \row + \i input + \i Generate documentation for \e input. \e input can specify a type library file or a type + library ID, or a CLSID or ProgID for an object + \row + \i -o file + \i Writes the class declaration to \e {file}.h and meta object infomation to \e {file}.cpp + \row + \i -n namespace + \i Generate a C++ namespace \e namespace + \row + \i -nometaobject + \i Do not generate a .cpp file with the meta object information. + The meta object is then generated in runtime. + \row + \i -getfile libid + \i Print the filename for the typelibrary \e libid to stdout + \row + \i -compat + \i Generate namespace with dynamicCall-compatible API + \row + \i -v + \i Print version information + \row + \i -h + \i Print help + \endtable + + \c dumpcpp can be integrated into the \c qmake build system. In your .pro file, list the type + libraries you want to use in the TYPELIBS variable: + + \snippet examples/activeqt/qutlook/qutlook.pro 0 + + The generated namespace will declare all enumerations, as well as one QAxObject subclass + for each \c coclass and \c interface declared in the type library. coclasses marked with + the \c control attribute will be wrapped by a QAxWidget subclass. + + Those classes that wrap creatable coclasses (i.e. coclasses that are not marked + as \c noncreatable) have a default constructor; this is typically a single class + of type \c Application. + + \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 0 + + All other classes can only be created by passing an IDispatch interface pointer + to the constructor; those classes should however not be created explicitly. + Instead, use the appropriate API of already created objects. + + \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 1 + + All coclass wrappers also have one constructors taking an interface wrapper class + for each interface implemented. + + \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 2 + + You have to create coclasses to be able to connect to signals of the subobject. + Note that the constructor deletes the interface object, so the following will + cause a segmentation fault: + + \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 3 + + If the return type is of a coclass or interface type declared in another type + library you have to include the namespace header for that other type library + before including the header for the namespace you want to use (both header have + to be generated with this tool). + + By default, methods and property returning subobjects will use the type as in + the type library. The caller of the function is responsible for deleting or + reparenting the object returned. If the \c -compat switch is set, properties + and method returning a COM object have the return type \c IDispatch*, and + the namespace will not declare wrapper classes for interfaces. + + In this case, create the correct wrapper class explicitly: + + \snippet doc/src/snippets/code/doc_src_activeqt-dumpcpp.qdoc 4 + + You can of course use the IDispatch* returned directly, in which case you have to + call \c Release() when finished with the interface. + + All classes in the namespace are tagged with a macro that allows you to export + or import them from a DLL. To do that, declare the macro to expand to + \c __declspec(dllimport/export) before including the header file. + + To build the tool you must first build the QAxContainer library. + Then run your make tool in \c tools/dumpcpp. +*/ diff --git a/doc/src/development/activeqt-dumpdoc.qdoc b/doc/src/development/activeqt-dumpdoc.qdoc new file mode 100644 index 0000000..55ab2d7 --- /dev/null +++ b/doc/src/development/activeqt-dumpdoc.qdoc @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page activeqt-dumpdoc.html + \title The dumpdoc Tool (ActiveQt) + + \ingroup activeqt-tools + + \keyword dumpdoc + + The \c dumpdoc tool generates Qt-style documentation for any + COM object and writes it into the file specified. + + Call \c dumpdoc with the following command line parameters: + + \table + \header + \i Option + \i Result + \row + \i -o file + \i Writes output to \e file + \row + \i object + \i Generate documentation for \e object + \row + \i -v + \i Print version information + \row + \i -h + \i Print help + \endtable + + \e object must be an object installed on the local machine (ie. + remote objects are not supported), and can include subobjects + accessible through properties, ie. + \c Outlook.Application/Session/CurrentUser + + The generated file will be an HTML file using Qt documentation + style. + + To build the tool you must first build the QAxContainer library. + Then run your make tool in \c tools/dumpdoc. +*/ diff --git a/doc/src/development/activeqt-idc.qdoc b/doc/src/development/activeqt-idc.qdoc new file mode 100644 index 0000000..974eddc --- /dev/null +++ b/doc/src/development/activeqt-idc.qdoc @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page activeqt-idc.html + \title IDC - The Interface Description Compiler (ActiveQt) + + \ingroup activeqt-tools + + \keyword idc + + The IDC tool is part of the ActiveQt build system and makes + it possible to turn any Qt binary into a full COM object server + with only a few lines of code. + + IDC understands the following command line parameters: + + \table + \header + \i Option + \i Result + \row + \i dll -idl idl -version x.y + \i Writes the IDL of the server \e dll to the file \e idl. The + type library wll have version x.y. + \row + \i dll -tlb tlb + \i Replaces the type library in \e dll with \e tlb + \row + \i -v + \i Print version information + \row + \i -regserver dll + \i Register the COM server \e dll + \row + \i -unregserver + \i Unregister the COM server \e dll + \endtable + + It is usually never necessary to invoke IDC manually, as the \c + qmake build system takes care of adding the required post + processing steps to the build process. See the \l{ActiveQt} + documentation for details. +*/ diff --git a/doc/src/development/activeqt-testcon.qdoc b/doc/src/development/activeqt-testcon.qdoc new file mode 100644 index 0000000..9fcfed6 --- /dev/null +++ b/doc/src/development/activeqt-testcon.qdoc @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page activeqt-testcon.html + \title testcon - An ActiveX Test Container (ActiveQt) + + \ingroup activeqt-tools + + \keyword testcon + + This application implements a generic test container for ActiveX + controls. You can insert ActiveX controls installed on your + system, and execute methods and modify properties. The container + will log information about events and property changes as well + as debug output in the log window. + + Parts of the code use internals of the Qt meta object and ActiveQt + framework and are not recommended to be used in application code. + + Use the application to view the slots, signals and porperties + available through the QAxWidget class when instantiated with a + certain ActiveX, and to test ActiveX controls you implement or + want to use in your Qt application. + + The application can load and execute script files in JavaScript, + VBScript, Perl and Python (if installed) to automate the controls + loaded. Example script files using the QAxWidget2 class are available + in the \c scripts subdirectory. + + Note that the qmake project of this example includes a resource file + \c testcon.rc with a version resource. This is required by some + ActiveX controls (ie. Shockwave ActiveX Controls), which might crash + or misbehave otherwise if such version information is missing. + + To build the tool you must first build the QAxContainer and the + QAxServer libraries. Then run your make tool in \c tools/testcon + and run the resulting \c testcon.exe. +*/ diff --git a/doc/src/development/assistant-manual.qdoc b/doc/src/development/assistant-manual.qdoc new file mode 100644 index 0000000..b26efcc --- /dev/null +++ b/doc/src/development/assistant-manual.qdoc @@ -0,0 +1,810 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page assistant-manual.html + \title Qt Assistant Manual + \ingroup qttools + + \startpage {index.html}{Qt Reference Documentation} + \nextpage Qt Assistant in More Detail + + \keyword Qt Assistant + + This document introduces \QA, a tool for presenting on-line + documentation. The document is divided into the following sections: + + Table of contents: + + \list + \o \l{The One-Minute Guide to Using Qt Assistant} + \o \l{Qt Assistant in More Detail} + \o \l{Using Qt Assistant as a Custom Help Viewer} + \endlist + + \chapter The One-Minute Guide to Using Qt Assistant + + Once you have installed Qt, \QA should be ready to run: + + \list + \o On Windows, \QA is available as a menu option on the Qt menu. + \o On Mac OS X, \QA is installed in the /Developer/Applications/Qt directory. + \o On Unix/Linux, open a terminal, type \c{assistant} and press \key{Enter}. + \endlist + + When you start up \QA, you will be presented with a standard main window + application, with a menu bar and toolbar. Below these, on the left hand + side are navigation windows called \e{Contents}, \e{Index} and \e{Bookmarks}. + On the right, taking up most of the space, is the \e{Documentation} window. + By default, \QA loads the Qt reference documentation along with the manuals + of other Qt tools, like \QD or \QL. + + \QA works in a similar way to a Web browser. If you click hyperlinks + (cross-references), the \e{Documentation} window will present the relevant + page. You can bookmark pages of particular interest and you can click the + \gui{Previous} and \gui{Next} toolbar buttons to navigate within the pages + you have visited. + + Although \QA can be used just like a Web browser to navigate through + the documentation, \QA offers a powerful means of navigation that Web + browsers do not provide. \QA uses an advanced full text search engine + to index all the pages in each compressed help file so that you can + search for particular words and phrases. + + To perform an index search, click the \gui{Index} tab on the Sidebar + (or press \key{Alt+I}). In the \gui{'Look For'} line edit enter a word; + e.g., 'homedirpath'. As you type, words are found and highlighted in a list + beneath the line edit. If the highlighted text matches what you're + looking for, double click it, (or press \key{Enter}) and the + \e{Documentation} window will display the relevant page. You rarely have + to type in the whole word before \QA finds a match. Note that for some + words there may be more than one possible page that is relevant. + + \QA also provides full text searching for finding specific words in + the documentation. To activate the full text search, either press \key(Alt+S) + or click on the \gui{Search} tab in the \e{Documentation} window. Then + enter the term you're looking for and hit the \gui{Search} button. All + documents containing the specified term will then be listed in the list box + below. +*/ + +/*! + \page assistant-details.html + \title Qt Assistant in More Detail + + \contentspage {Qt Assistant Manual}{Contents} + \previouspage Qt Assistant Manual + \nextpage Using Qt Assistant as a Custom Help Viewer + + \tableofcontents + + \img assistant-assistant.png + + \section1 Command Line Options + + \QA handles the following command line options: + + \table + \header + \o Command Line Option + \o Brief Description + \row + \o -collectionFile <file.qhc> + \o Uses the specified collection file instead of the default one. + \row + \o -showUrl URL + \o Shows the document referenced by URL. + \row + \o -enableRemoteControl + \o Enables \QA to be remotly controlled. + \row + \o -show <widget> + \o Shows the specified dockwidget which can be "contents", "index", + "bookmarks" or "search". + \row + \o -hide <widget> + \o Hides the specified dockwidget which can be "contents", "index", + "bookmarks" or "search. + \row + \o -activate <widget> + \o Activates the specified dockwidget which can be "contents", + "index", "bookmarks" or "search. + \row + \o -register <doc.qch> + \o Registers the specified compressed help file in the given help + collection. + \row + \o -unregister <doc.qch> + \o Unregisters the specified compressed help file from the given + collection file. + \row + \o -setCurrentFilter filter + \o Sets the given filter as the active filter. + \row + \o -quiet + \o Doesn't show any error, warning or success messages. + \endtable + + \section1 Tool Windows + + \img assistant-dockwidgets.png + + The tool windows provide four ways to navigate the documentation: + + \list + \o The \gui{Contents} window presents a table of contents implemented as a + tree view for the documentation that is available. If you click an item, + its documentation will appear in the \e{Documentation} window. If you double + click an item or click on the control to the left of it, the item's sub-items + will appear. Click a sub-item to make its page appear in the \e{Documentation} + window. Click on the control next to an open item to hide its sub-items. + \o The \gui{Index} window is used to look up key words or phrases. + See \l{The One-Minute Guide to Using Qt Assistant} for how to use this + window. + \o The \gui{Bookmarks} window lists any bookmarks you have made. Double + click a bookmark to make its page appear in the \e{Documentation} window. + The \gui{Bookmarks} window provides a context menu with \gui{Show Item}, + \gui{Delete Item} as well as \gui{Rename Item}. Click in the main menu + \menu{Bookmark|Add Bookmark...} (or press \key{Ctrl+B}) to bookmark the + page that is currently showing in the \e{Documentation} window. Right click + a bookmark in the list to rename or delete the highlighted bookmark. + \endlist + + If you want the \gui{Documentation} window to use as much space as possible, + you can easily group, move or hide the tool windows. To group the windows, + drag one on top of the other and release the mouse. If one or all tool + windows are not shown, press \key{Alt+C}, \key{Alt+I} or \key{Alt+O} to show + the required window. + + The tool windows can be docked into the main window, so you can drag them + to the top, left, right or bottom of \e{Qt Assistant's} window, or you can + drag them outside \QA to float them as independent windows. + + \section1 Documentation Window + + \img assistant-docwindow.png + + The \gui{Documentation} window lets you create a tab for each + documentation page that you view. Click the \gui{Add Tab} button and a new + tab will appear with the page name as the tab's caption. This makes it + convenient to switch between pages when you are working with different + documentation. You can delete a tab by clicking the \gui{Close Tab} button + located on the right side of the \gui{Documentation} window. + + \section1 Toolbars + + \img assistant-toolbar.png + + The main toolbar provides fast access to the most common actions. + + \table + \header \o Action \o Description \o Menu Item \o Shortcut + \row \o \gui{Previous} \o Takes you to the previous page in the history. + \o \menu{Go|Previous} \o \key{Alt+Left Arrow} + \row \o \gui{Next} \o Takes you to the next page in the history. + \o \menu{Go|Next} \o \key{Alt+Right Arrow} + \row \o \gui{Home} + \o Takes you to the home page as specified in the Preferences Dialog. + \o \menu{Go|Home} \o \key{Ctrl+Home}. + \row \o \gui{Sync with Table of Contents} + \o Synchronizes the \gui{Contents} tool window with the page currently + shown in the \gui{Documentation} window. + \o \menu{Go|Sync with Table of Contents} \o + \row \o \gui{Copy} \o Copies any selected text to the clipboard. + \o \menu{Edit|Copy} \o \key{Ctrl+C} + \row \o \gui{Print} \o Opens the \gui{Print} dialog. + \o \menu{File|Print} \o \key{Ctrl+P} + \row \o \gui{Find in Text} \o Opens the \gui{Find Text} dialog. + \o \menu{Edit|Find in Text} \o \key{Ctrl+F} + \row \o \gui{Zoom in} + \o Increases the font size used to display text in the current tab. + \o \menu{View|Zoom in} \o \key{Ctrl++} + \row \o \gui{Zoom out} + \o Decreases the font size used to display text in the current tab. + \o \menu{View|Zoom out} \o \key{Ctrl+-} + \row \o \gui{Normal Size} + \o Resets the font size to its normal size in the current tab. + \o \menu{View|Normal Size} \o \key{Ctrl+0} + \endtable + + \img assistant-address-toolbar.png + + The address toolbar provides a fast way to enter a specific URL for a + documentation file. By default, the address toolbar is not shown, so it + has to be activated via \menu{View|Toolbars|Address Toolbar}. + + \img assistant-filter-toolbar.png + + The filter toolbar allows you to apply a filter to the currently installed + documentation. As with the address toolbar, the filter toolbar is not visible + by default and has to be activated via \menu{View|Toolbars|Filter Toolbar}. + + \section1 Menus + + \section2 File Menu + + \list + \o \menu{File|Page Setup...} invokes a dialog allowing you to define + page layout properties, such as margin sizes, page orientation and paper size. + \o \menu{File|Print Preview...} provides a preview of the printed pages. + \o \menu{File|Print...} opens the \l{#Print Dialog}{\gui{Print} dialog}. + \o \menu{File|New Tab} opens a new empty tab in the \gui{Documentation} + window. + \o \menu{File|Close Tab} closes the current tab of the + \gui{Documentation} window. + \o \menu{File|Exit} closes the \QA application. + \endlist + + \section2 Edit Menu + + \list + \o \menu{Edit|Copy} copies any selected text to the clipboard. + \o \menu{Edit|Find in Text} invokes the \l{#Find Text Control}{\gui{Find Text} + control} at the lower end of the \gui{Documentation} window. + \o \menu{Edit|Find Next} looks for the next occurance of the specified + text in the \gui{Find Text} control. + \o \menu{Edit|Find Previous} looks for the previous occurance of + the specified text in the \l{#Find Text Control}{\gui{Find Text} control}. + \o \menu{Edit|Preferences} invokes the \l{#Preferences Dialog}{\gui{Preferences} dialog}. + \endlist + + \section2 View Menu + + \list + \o \menu{View|Zoom in} increases the font size in the current tab. + \o \menu{View|Zoom out} decreases the font size in the current tab. + \o \menu{View|Normal Size} resets the font size in the current tab. + \o \menu{View|Contents} toggles the display of the \gui{Contents} tool window. + \o \menu{View|Index} toggles the display of the \gui{Index} tool window. + \o \menu{View|Bookmarks} toggles the display of the \gui{Bookmarks} tool window. + \o \menu{View|Search} toggles the display of the Search in the \gui{Documentation} window. + \endlist + + \section2 Go Menu + + \list + \o \menu{Go|Home} goes to the home page. + \o \menu{Go|Back} displays the previous page in the history. + \o \menu{Go|Forward} displays the next page in the history. + \o \menu{Go|Sync with Table of Contents} syncs the \gui{Contents} tool window to the currently shown page. + \o \menu{Go|Next Page} selects the next tab in the \gui{Documentation} window. + \o \menu{Go|Previous Page} selects the previous tab in the \gui{Documentation} window. + \endlist + + \section2 Bookmarks Menu + + \list + \o \menu{Bookmarks|Add} adds the current page to the list of bookmarks. + \endlist + + \section1 Dialogs + + \section2 Print Dialog + + This dialog is platform-specific. It gives access to various printer + options and can be used to print the document shown in the current tab. + + \section2 Preferences Dialog + + \img assistant-preferences-fonts.png + + The \menu{Fonts} page allows you to change the font family and font sizes of the + browser window displaying the documentation or the application itself. + + \img assistant-preferences-filters.png + + The \menu{Filters} page lets you create and remove documentation + filters. To add a new filter, click the \gui{Add} button, specify a + filter name in the pop-up dialog and click \gui{OK}, then select + the filter attributes in the list box on the right hand side. + You can delete a filter by selecting it and clicking the \gui{Remove} + button. + + \img assistant-preferences-documentation.png + + The \menu{Documentation} page lets you install and remove compressed help + files. Click the \gui{Install} button and choose the path of the compressed + help file (*.qch) you would like to install. + To delete a help file, select a documentation set in the list and click + \gui{Remove}. + + \img assistant-preferences-options.png + + The \menu{Options} page lets you specify the homepage \QA will display when + you click the \gui{Home} button in \QA's main user interface. You can specify + the hompage by typing it here or clicking on one of the buttons below the + textbox. \gui{Current Page} sets the currently displayed page as your home + page while \gui{Restore to default} will reset your home page to the default + home page. + + \section1 Find Text Control + + This control is used to find text in the current page. Enter the text you want + to find in the line edit. The search is incremental, meaning that the most + relevant result is shown as you enter characters into the line edit. + + If you check the \gui{Whole words only} checkbox, the search will only consider + whole words; for example, if you search for "spin" with this checkbox checked it will + not match "spinbox", but will match "spin". If you check the \gui{Case sensitive} + checkbox then, for example, "spin" will match "spin" but not "Spin". You can + search forwards or backwards from your current position in the page by clicking + the \gui{Previous} or \gui{Next} buttons. To hide the find control, either click the + \gui{Close} button or hit the \key{Esc} key. + + \section1 Filtering Help Contents + + \QA allows you to install any kind of documentation as long as it is organized + in Qt compressed help files (*.qch). For example, it is possible to install the + Qt reference documentation for Qt 4.4.0 and Qt 4.4.1 at the same time. In many + respects, this is very convenient since only one version of \QA is needed. + However, at the same time it becomes more complicated when performing tasks like + searching the index because nearly every keyword is defined in Qt 4.4.0 as well + as in Qt 4.4.1. This means that \QA will always ask the user to choose which one + should be displayed. + + We use documentation filters to solve this issue. A filter is identified by its + name, and contains a list of filter attributes. An attribute is just a string and + can be freely chosen. Attributes are defined by the documentation itself, this + means that every documentation set usually has one or more attributes. + + For example, the Qt 4.4.0 \QA documentation defines the attributes \c {assistant}, + \c{tools} and \c{4.4.0}, \QD defines \c{designer}, \c{tools} and \c{4.4.0}. + The filter to display all tools would then define only the attribute + \c{tools} since this attribute is part of both documentation sets. + Adding the attribute \c{assistant} to the filter would then only show \QA + documentation since the \QD documentation does not contain this + attribute. Having an empty list of attributes in a filter will match all + documentation; i.e., it is equivalent to requesting unfiltered documentation. + + \section1 Full Text Searching + + \img assistant-search.png + + \QA provides a powerful full text search engine. To search + for certain words or text, click the \gui{Search} tab in the \gui{Documentation} + window. Then enter the text you want to look for and press \key{Enter} + or click the \gui{Search} button. The search is not case sensitive, so, + for example, Foo, fOo and FOO are all treated as the same. The following are + examples of common search patterns: + + \list + \o \c deep -- lists all the documents that contain the word 'deep' + \o \c{deep*} -- lists all the documents that contain a word beginning + with 'deep' + \o \c{deep copy} -- lists all documents that contain both 'deep' \e + and 'copy' + \o \c{"deep copy"} -- list all documents that contain the phrase 'deep copy' + \endlist + + It is also possible to use the \gui{Advanced search} to get more flexibility. + You can specify some words so that hits containing these are excluded from the + result, or you can search for an exact phrase. Searching for similar words will + give results like these: + + \list + \o \c{QStin} -- lists all the documents with titles that are similar, such as \c{QString} + \o \c{QSting} -- lists all the documents with titles that are similar, such as \c{QString} + \o \c{QStrin} -- lists all the documents with titles that are similar, such as \c{QString} + \endlist + + Options can be combined to improve the search results. + + The list of documents found is ordered according to the number of + occurrences of the search text which they contain, with those containing + the highest number of occurrences appearing first. Simply click any + document in the list to display it in the \gui{Documentation} window. + + If the documentation has changed \mdash for example, if documents have been added + or removed \mdash \QA will index them again. + +*/ + +/*! + \page assistant-custom-help-viewer.html + \title Using Qt Assistant as a Custom Help Viewer + + \contentspage {Qt Assistant Manual}{Contents} + \previouspage Qt Assistant in More Detail + + Using \QA as custom help viewer requires more than just being able to + display custom documentation. It is equally important that the + appearance of \QA can be customized so that it is seen as a + application-specific help viewer rather than \QA. This is achieved by + changing the window title or icon, as well as some application-specific + menu texts and actions. The complete list of possible customizations + can be found in the \l{Creating a Custom Help Collection File} section. + + Another requirement of a custom help viewer is the ability to receive + actions or commands from the application it provides help for. This is + especially important when the application offers context sensitive help. + When used in this way, the help viewer may need to change its contents + depending on the state the application is currently in. This means that + the application has to communicate the current state to the help viewer. + The section about \l{Using Qt Assistant Remotely} explains how this can + be done. + + \tableofcontents + + The \l{Simple Text Viewer Example}{Simple Text Viewer} example uses the + techniques described in this document to show how to use \QA as a custom + help viewer for an application. + + \warning In order to ship Qt Assistant in your application, it is crucial + that you include the sqlite plugin. For more information on how to include + plugins in your application, refer to the \l{Deploying Qt Applications} + {deployment documentation}. + + \section1 Qt Help Collection Files + + The first important point to know about \QA is that it stores all + settings related to its appearance \e and a list of installed + documentation in a help collection file. This means, when starting \QA + with different collection files, \QA may look totally different. This + complete separation of settings makes it possible to deploy \QA as a + custom help viewer for more than one application on one machine + without risk of interference between different instances of \QA. + + To apply a certain help collection to \QA, specify the respective + collection file on the command line when starting it. For example: + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8 + + However, storing all settings in one collection file raises some problems. + The collection file is usually installed in the same directory as the + application itself, or one of its subdirectories. Depending on the + directory and the operating system, the user may not have any permissions + to modify this file which would happen when the user settings are stored. + Also, it may not even be possible to give the user write permissions; + e.g., when the file is located on a read-only medium like a CD-ROM. + + Even if it is possible to give everybody the right to store their settings + in a globally available collection file, the settings from one user would + be overwritten by another user when exiting \QA. + + To solve this dilemma, \QA creates user specific collection files which + are more or less copied from the original collection file. The user-specific + collection file will be saved in a subdirectory of the path returned by + QDesktopServices::DataLocation. The subdirectory, or \e{cache directory} + within this user-specific location, can be defined in the help collection + project file. For example: + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 7 + + So, when calling + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8 + + \QA actually uses the collection file: + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 9 + + There is no need ever to start \QA with the user specific collection + file. Instead, the collection file shipped with the application should + always be used. Also, when adding or removing documentation from the + collection file (see next section) always use the normal collection file. + \QA will take care of synchronizing the user collection files when the + list of installed documentation has changed. + + \section1 Displaying Custom Documentation + + Before \QA is able to show documentation, it has to know where it can + find the actual documentation files, meaning that it has to know the + location of the Qt compressed help file (*.qch). As already mentioned, + \QA stores references to the compressed help files in the currently used + collection file. So, when creating a new collection file you can list + all compressed help files \QA should display. + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 5 + + Sometimes, depending on the application for which \QA acts as a + help viewer, more documentation needs to be added over time; for + example, when installing more application components or plugins. + This can be done manually by starting \QA, opening the \gui{Edit|Preferences} + dialog and navigating to the \gui{Documentation} tab page. Then click + the \gui{Add...} button, select a Qt compressed help file (*.qch) + and press \gui{Open}. However, this approach has the disadvantage + that every user has to do it manually to get access to the new + documentation. + + The prefered way of adding documentation to an already existing collection + file is to use the \c{-register} command line flag of \QA. When starting + \QA with this flag, the documentation will be added and \QA will + exit right away displaying a message if the registration was successful + or not. + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 6 + + The \c{-quiet} flag can be passed on to \QA to prevent it from writing + out the status message. + + \bold{Note:} \QA will show the documentation in the contents view in the same + order as it was registered. + + + \section1 Changing the Appearance of Qt Assistant + + The appearance of \QA can be changed by passing different command line options + on startup. However, these command line options only allow to show or hide + specific widgets, like the contents or index view. Other customizations, such + as changing the application title or icon, or disabling the filter functionality, + can be done by creating a custom help collection file. + + \section2 Creating a Custom Help Collection File + + The help collection file (*.qhc) used by \QA is created when running the + \c qcollectiongenerator tool on a help collection project file (*.qhcp). + The project file format is XML and supports the following tags: + + \table + \header + \o Tag + \o Brief Description + \row + \o \c{<title>} + \o This property is used to specify a window title for \QA. + \row + \o \c{<homePage>} + \o This tag specifies which page should be display when + pressing the home button in \QA's main user interface. + \row + \o \c{<startPage>} + \o This tag specifies which page \QA should initially + display when the help collection is used. + \row + \o \c{<currentFilter>} + \o This tag specifies the \l{Qt Assistant in More Detail#Preferences Dialog}{filter} + that is initially used. + If this filter is not specified, the documentation will not be filtered. This has + no impact if only one documentation set is installed. + \row + \o \c{<applicationIcon>} + \o This tag describes an icon that will be used instead of the normal \QA + application icon. This is specified as a relative path from the directory + containing the collection file. + \row + \o \c{<enableFilterFunctionality>} + \o This tag is used to enable or disable user accessible filter functionality, + making it possible to prevent the user from changing any filter when running \QA. + It does not mean that the internal filter functionality is completely disabled. + Set the value to \c{false} if you want to disable the filtering. If the filter + toolbar should be shown by default, set the attribute \c{visible} to \c{true}. + \row + \o \c{<enableDocumentationManager>} + \o This tag is used to specify whether the documentation manager should be shown + in the preferences dialog. Disabling the Documentation Manager allows you to limit + \QA to display a specific documentation set or make it impossible for the end user + to accidentally remove or install documentation. To hide the documentation manager, + set the tag value to \c{false}. + \row + \o \c{<enableAddressBar>} + \o This tag describes if the address bar can be shown. By default it is + enabled; if you want to disable it set the tag value to \c{false}. If the + address bar functionality is enabled, the address bar can be shown by setting the + tag attribute \c{visible} to \c{true}. + \row + \o \c{<aboutMenuText>, <text>} + \o The \c{aboutMenuText} tag lists texts for different languages which will + later appear in the \menu{Help} menu; e.g., "About Application". A text is + specified within the \c{text} tags; the \c{language} attribute takes the two + letter language name. The text is used as the default text if no language + attribute is specified. + \row + \o \c{<aboutDialog>, <file>, <icon>} + \o The \c{aboutDialog} tag can be used to specify the text for the \gui{About} + dialog that can be opened from the \menu{Help} menu. The text is taken from the + file in the \c{file} tags. It is possible to specify a different file or any + language. The icon defined by the \c{icon} tags is applied to any language. + \row + \o \c{<cacheDirectory>} + \o Specified as a path relative to the directory given by + QDesktopServices::DataLocation, the cache path is used to store index files + needed for the full text search and a copy of the collection file. + The copy is needed because \QA stores all its settings in the collection file; + i.e., it must be writable for the user. + \endtable + + In addition to those \QA specific tags, the tags for generating and registering + documentation can be used. See \l{The Qt Help Framework#Creating a Qt Help Collection} + {Qt Help Collection} documentation for more information. + + An example of a help collection file that uses all the available tags is shown below: + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 1 + + To create the binary collection file, run the \c qcollectiongenerator tool: + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 10 + + To test the generated collection file, start \QA in the following way: + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8 + + \section1 Using Qt Assistant Remotely + + Even though the help viewer is a standalone application, it will mostly + be launched by the application it provides help for. This approach + gives the application the possibility to ask for specific help contents + to be displayed as soon as the help viewer is started. Another advantage + with this approach is that the application can communicate with the + help viewer process and can therefore request other help contents to be + shown depending on the current state of the application. + + So, to use \QA as the custom help viewer of your application, simply + create a QProcess and specify the path to the Assistant executable. In order + to make Assistant listen to your application, turn on its remote control + functionality by passing the \c{-enableRemoteControl} command line option. + + \warning The trailing '\0' must be appended separately to the QByteArray, + e.g., \c{QByteArray("command" + '\0')}. + + The following example shows how this can be done: + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 2 + + Once \QA is running, you can send commands by using the stdin channel of + the process. The code snippet below shows how to tell \QA to show a certain + page in the documentation. + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 3 + + The following commands can be used to control \QA: + + \table + \header + \o Command + \o Brief Description + \row + \o \c{show <Widget>} + \o Shows the dock widget specified by <Widget>. If the widget + is already shown and this command is sent again, the widget will be + activated, meaning that it will be raised and given the input focus. + Possible values for <Widget> are "contents", "index", "bookmarks" or "search". + \row + \o \c{hide <Widget>} + \o Hides the dock widget specified by <Widget>. Possible values for + <Widget> are "contents", "index", "bookmarks" and "search". + \row + \o \c{setSource <Url>} + \o Displays the given <Url>. The URL can be absolute or relative + to the currently displayed page. If the URL is absolute, it has to + be a valid Qt help system URL; i.e., starting with "qthelp://". + \row + \o \c{activateKeyword <Keyword>} + \o Inserts the specified <Keyword> into the line edit of the + index dock widget and activates the corresponding item in the + index list. If such an item has more than one link associated + with it, a topic chooser will be shown. + \row + \o \c{activateIdentifier <Id>} + \o Displays the help contents for the given <Id>. An ID is unique + in each namespace and has only one link associated to it, so the + topic chooser will never pop up. + \row + \o \c{syncContents} + \o Selects the item in the contents widget which corresponds to + the currently displayed page. + \row + \o \c{setCurrentFilter} + \o Selects the specified filter and updates the visual representation + accordingly. + \row + \o \c{expandToc <Depth>} + \o Expands the table of contents tree to the given depth. If depth + is less than 1, the tree will be collapsed completely. + \endtable + + If you want to send several commands within a short period of time, it is + recommended that you write only a single line to the stdin of the process + instead of one line for every command. The commands have to be separated by + a semicolon, as shown in the following example: + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 4 + + \section1 Compatibility with Old Formats + + In older versions of Qt, the help system was based on Document Content File + (DCF) and Qt Assistant Documentation Profile (ADP) formats. In contrast, + Qt Assistant and the help system used in Qt 4.4 use the formats described + earlier in this manual. + + Unfortunately, the old file formats are not compatible with the new ones. + In general, the differences are not that big \mdash in most cases is the old + format is just a subset of the new one. One example is the \c namespace tag in + the Qt Help Project format, which was not part of the old format, but plays a vital + role in the new one. To help you to move to the new file format, we have created + a conversion wizard. + + The wizard is started by executing \c qhelpconverter. It guides you through the + conversion of different parts of the file and generates a new \c qch or \c qhcp + file. + + Once the wizard is finished and the files created, run the \c qhelpgenerator + or the \c qcollectiongenerator tool to generate the binary help files used by \QA. +*/ + +/* +\section2 Modifying \QA with Command Line Options + + Different help collections can be shown by simply passing the help collection + path to \QA. For example: + + \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 0 + + Other available options the can be passed on the command line. + + \table + \header + \o Command Line Option + \o Brief Description + \row + \o -collectionFile <file.qhc> + \o Uses the specified collection file instead of the default one. + \row + \o -showUrl URL + \o Shows the document referenced by URL. + \row + \o -enableRemoteControl + \o Enables \QA to be remotly controlled. + \row + \o -show <widget> + \o Shows the specified dockwidget which can be "contents", "index", + "bookmarks" or "search". + \row + \o -hide <widget> + \o Hides the specified dockwidget which can be "contents", "index", + "bookmarks" or "search. + \row + \o -activate <widget> + \o Activates the specified dockwidget which can be "contents", + "index", "bookmarks" or "search. + \row + \o -register <doc.qch> + \o Registers the specified compressed help file in the given help + collection. + \row + \o -unregister <doc.qch> + \o Unregisters the specified compressed help file from the given + collection file. + \row + \o -quiet + \o Doesn't show any error, warning or success messages. + \endtable + */ diff --git a/doc/src/development/debug.qdoc b/doc/src/development/debug.qdoc new file mode 100644 index 0000000..f0fe128 --- /dev/null +++ b/doc/src/development/debug.qdoc @@ -0,0 +1,243 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page debug.html + \title Debugging Techniques + + Here we present some useful hints to help you with debugging your + Qt-based software. + + \tableofcontents + + \section1 Configuring Qt for Debugging + + When \l{Installation}{configuring Qt for installation}, it is possible + to ensure that it is built to include debug symbols that can make it + easier to track bugs in applications and libraries. However, on some + platforms, building Qt in debug mode will cause applications to be larger + than desirable. + + \section2 Debugging in Mac OS X and Xcode + + \section3 Debugging With/Without Frameworks + + The basic stuff you need to know about debug libraries and + frameworks is found at developer.apple.com in: + \l{http://developer.apple.com/technotes/tn2004/tn2124.html#SECDEBUGLIB} + {Apple Technicle Note TN2124} Qt follows that. + + When you build Qt, frameworks are built by default, and inside the + framework you will find both a release and a debug version (e.g., + QtCore and QtCore_debug). If you pass the \c{-no-framework} flag + when you build Qt, two dylibs are built for each Qt library (e.g., + libQtCore.4.dylib and libQtCore_debug.4.dylib). + + What happens when you link depends on whether you use frameworks + or not. We don't see a compelling reason to recommend one over the + other. + + \section4 With Frameworks: + + Since the release and debug libraries are inside the framework, + the app is simply linked against the framework. Then when you run + in the debugger, you will get either the release version or the + debug version, depending on whether you set \c{DYLD_IMAGE_SUFFIX}. + If you don't set it, you get the release version by default (i.e., + non _debug). If you set \c{DYLD_IMAGE_SUFFIX=_debug}, you get the + debug version. + + \section4 Without Frameworks: + + When you tell \e{qmake} to generate a Makefile with the debug + config, it will link against the _debug version of the libraries + and generate debug symbols for the app. Running this program in + GDB will then work like running GDB on other platforms, and you + will be able to trace inside Qt. + + \section3 Debug Symbols and Size + + The amount of space taken up by debug symbols generated by GCC can + be excessively large. However, with the release of Xcode 2.3 it is + now possible to use Dwarf symbols which take up a significantly + smaller amount of space. To enable this feature when configuring + Qt, pass the \c{-dwarf-2} option to the configure script. + + This is not enabled by default because previous versions of Xcode + will not work with the compiler flag used to implement this + feature. Mac OS X 10.5 will use dwarf-2 symbols by default. + + dwarf-2 symbols contain references to source code, so the size of + the final debug application should compare favorably to a release + build. + + \omit + Although it is not necessary to build Qt with debug symbols to use the + other techniques described in this document, certain features are only + available when Qt is configured for debugging. + \endomit + + \section1 Command Line Options Recognized by Qt + + When you run a Qt application, you can specify several + command-line options that can help with debugging. These are + recognized by QApplication. + + \table + \header \o Option \o Description + \row \o \c -nograb + \o The application should never grab \link QWidget::grabMouse() + the mouse\endlink or \link QWidget::grabKeyboard() the + keyboard \endlink. This option is set by default when the + program is running in the \c gdb debugger under Linux. + \row \o \c -dograb + \o Ignore any implicit or explicit \c{-nograb}. \c -dograb wins over + \c -nograb even when \c -nograb is last on the command line. + \row \o \c -sync + \o Runs the application in X synchronous mode. Synchronous mode + forces the X server to perform each X client request + immediately and not use buffer optimization. It makes the + program easier to debug and often much slower. The \c -sync + option is only valid for the X11 version of Qt. + \endtable + + \section1 Warning and Debugging Messages + + Qt includes four global functions for writing out warning and debug + text. You can use them for the following purposes: + + \list + \o qDebug() is used for writing custom debug output. + \o qWarning() is used to report warnings and recoverable errors in + your application. + \o qCritical() is used for writing critical error mesages and + reporting system errors. + \o qFatal() is used for writing fatal error messages shortly before exiting. + \endlist + + If you include the <QtDebug> header file, the \c qDebug() function + can also be used as an output stream. For example: + + \snippet doc/src/snippets/code/doc_src_debug.qdoc 0 + + The Qt implementation of these functions prints the text to the + \c stderr output under Unix/X11 and Mac OS X. With Windows, if it + is a console application, the text is sent to console; otherwise, it + is sent to the debugger. You can take over these functions by + installing a message handler using qInstallMsgHandler(). + + If the \c QT_FATAL_WARNINGS environment variable is set, + qWarning() exits after printing the warning message. This makes + it easy to obtain a backtrace in the debugger. + + Both qDebug() and qWarning() are debugging tools. They can be + compiled away by defining \c QT_NO_DEBUG_OUTPUT and \c + QT_NO_WARNING_OUTPUT during compilation. + + The debugging functions QObject::dumpObjectTree() and + QObject::dumpObjectInfo() are often useful when an application + looks or acts strangely. More useful if you use \l{QObject::setObjectName()}{object names} + than not, but often useful even without names. + + \section1 Providing Support for the qDebug() Stream Operator + + You can implement the stream operator used by qDebug() to provide + debugging support for your classes. The class that implements the + stream is \c QDebug. The functions you need to know about in \c + QDebug are \c space() and \c nospace(). They both return a debug + stream; the difference between them is whether a space is inserted + between each item. Here is an example for a class that represents + a 2D coordinate. + + \snippet doc/src/snippets/qdebug/qdebugsnippet.cpp 0 + + Integration of custom types with Qt's meta-object system is covered + in more depth in the \l{Creating Custom Qt Types} document. + + \section1 Debugging Macros + + The header file \c <QtGlobal> contains some debugging macros and + \c{#define}s. + + Three important macros are: + \list + \o \l{Q_ASSERT()}{Q_ASSERT}(cond), where \c cond is a boolean + expression, writes the warning "ASSERT: '\e{cond}' in file xyz.cpp, line + 234" and exits if \c cond is false. + \o \l{Q_ASSERT_X()}{Q_ASSERT_X}(cond, where, what), where \c cond is a + boolean expression, \c where a location, and \c what a message, + writes the warning: "ASSERT failure in \c{where}: '\c{what}', file xyz.cpp, line 234" + and exits if \c cond is false. + \o \l{Q_CHECK_PTR()}{Q_CHECK_PTR}(ptr), where \c ptr is a pointer. + Writes the warning "In file xyz.cpp, line 234: Out of memory" and + exits if \c ptr is 0. + \endlist + + These macros are useful for detecting program errors, e.g. like this: + + \snippet doc/src/snippets/code/doc_src_debug.qdoc 1 + + Q_ASSERT(), Q_ASSERT_X(), and Q_CHECK_PTR() expand to nothing if + \c QT_NO_DEBUG is defined during compilation. For this reason, + the arguments to these macro should not have any side-effects. + Here is an incorrect usage of Q_CHECK_PTR(): + + \snippet doc/src/snippets/code/doc_src_debug.qdoc 2 + + If this code is compiled with \c QT_NO_DEBUG defined, the code in + the Q_CHECK_PTR() expression is not executed and \e alloc returns + an unitialized pointer. + + The Qt library contains hundreds of internal checks that will + print warning messages when a programming error is detected. We + therefore recommend that you use a debug version of Qt when + developing Qt-based software. + + \section1 Common Bugs + + There is one bug that is so common that it deserves mention here: + If you include the Q_OBJECT macro in a class declaration and + run \link moc.html the meta-object compiler\endlink (\c{moc}), + but forget to link the \c{moc}-generated object code into your + executable, you will get very confusing error messages. Any link + error complaining about a lack of \c{vtbl}, \c{_vtbl}, \c{__vtbl} + or similar is likely to be a result of this problem. +*/ diff --git a/doc/src/development/designer-manual.qdoc b/doc/src/development/designer-manual.qdoc new file mode 100644 index 0000000..5d8587a --- /dev/null +++ b/doc/src/development/designer-manual.qdoc @@ -0,0 +1,2836 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page designer-manual.html + + \title Qt Designer Manual + \ingroup qttools + \keyword Qt Designer + + \QD is Qt's tool for designing and building graphical user + interfaces (GUIs) from Qt components. You can compose and customize your + widgets or dialogs in a what-you-see-is-what-you-get (WYSIWYG) manner, and + test them using different styles and resolutions. + + Widgets and forms created with \QD integrated seamlessly with programmed + code, using Qt's signals and slots mechanism, that lets you easily assign + behavior to graphical elements. All properties set in \QD can be changed + dynamically within the code. Furthermore, features like widget promotion + and custom plugins allow you to use your own components with \QD. + + If you are new to \QD, you can take a look at the + \l{Getting To Know Qt Designer} document. For a quick tutorial on how to + use \QD, refer to \l{A Quick Start to Qt Designer}. + + Qt Designer 4.5 boasts a long list of improvements. For a detailed list of + what is new, refer \l{What's New in Qt Designer 4.5}. + + \image designer-multiple-screenshot.png + + For more information on using \QD, you can take a look at the following + links: + + \list + \o \l{Qt Designer's Editing Modes} + \list + \o \l{Qt Designer's Widget Editing Mode}{Widget Editing Mode} + \o \l{Qt Designer's Signals and Slots Editing Mode} + {Signals and Slots Editing Mode} + \o \l{Qt Designer's Buddy Editing Mode} + {Buddy Editing Mode} + \o \l{Qt Designer's Tab Order Editing Mode} + {Tab Order Editing Mode} + \endlist + \o \l{Using Layouts in Qt Designer} + \o \l{Saving, Previewing and Printing Forms in Qt Designer} + \o \l{Using Containers in Qt Designer} + \o \l{Creating Main Windows in Qt Designer} + \o \l{Editing Resources with Qt Designer} + \o \l{Using Stylesheets with Qt Designer} + \o \l{Using a Designer UI File in Your Application} + \endlist + + For advanced usage of \QD, you can refer to these links: + + \list + \o \l{Customizing Qt Designer Forms} + \o \l{Using Custom Widgets with Qt Designer} + \o \l{Creating Custom Widgets for Qt Designer} + \o \l{Creating Custom Widget Extensions} + \o \l{Qt Designer's UI File Format} + \endlist + + + \section1 Legal Notices + + Some source code in \QD is licensed under specific highly permissive + licenses from the original authors. The Qt team gratefully acknowledges + these contributions to \QD and all uses of \QD should also acknowledge + these contributions and quote the following license statements in an + appendix to the documentation. + + \list + \i \l{Implementation of the Recursive Shadow Casting Algorithm in Qt Designer} + \endlist +*/ + + + +/*! + \page designer-whats-new.html + \contentspage {Qt Designer Manual}{Contents} + + + \title What's New in Qt Designer 4.5 + + \section1 General Changes + + + \table + \header + \i Widget Filter Box + \i Widget Morphing + \i Disambiguation Field + \row + \i \inlineimage designer-widget-filter.png + \i \inlineimage designer-widget-morph.png + \i \inlineimage designer-disambiguation.png + \endtable + + \list 1 + \i Displaying only icons in the \gui{Widget Box}: It is now possible + for the \gui{Widget Box} to display icons only. Simply select + \gui{Icon View} from the context menu. + \i Filter for \gui{Widget Box}: A filter is now provided to quickly + locate the widget you need. If you use a particular widget + frequently, you can always add it to the + \l{Getting to Know Qt Designer#WidgetBox}{scratch pad}. + \i Support for QButtonGroup: It is available via the context + menu of a selection of QAbstractButton objects. + \i Improved support for item widgets: The item widgets' (e.g., + QListWidget, QTableWidget, and QTreeWidget) contents dialogs have + been improved. You can now add translation comments and also modify + the header properties. + \i Widget morphing: A widget can now be morphed from one type to + another with its layout and properties preserved. To begin, click + on your widget and select \gui{Morph into} from the context menu. + \i Disambiguation field: The property editor now shows this extra + field under the \gui{accessibleDescription} property. This field + has been introduced to aid translators in the case of two source + texts being the same but used for different purposes. For example, + a dialog could have two \gui{Add} buttons for two different + reasons. \note To maintain compatibility, comments in UI files + created prior to Qt 4.5 will be listed in the \gui{Disambiguation} + field. + \endlist + + + + \section1 Improved Shortcuts for the Editing Mode + + \list + \i The \key{Shift+Click} key combination now selects the ancestor for + nested layouts. This iterates from one ancestor to the other. + + \i The \key{Ctrl} key is now used to toggle and copy drag. Previously + this was done with the \key{Shift} key but is now changed to + conform to standards. + + \i The left mouse button does rubber band selection for form windows; + the middle mouse button does rubber band selection everywhere. + \endlist + + + \section1 Layouts + \list + \i It is now possible to switch a widget's layout without breaking it + first. Simply select the existing layout and change it to another + type using the context menu or the layout buttons on the toolbar. + + \i To quickly populate a \gui{Form Layout}, you can now use the + \gui{Add form layout row...} item available in the context menu or + double-click on the red layout. + \endlist + + + \section1 Support for Embedded Design + + \table + \header + \i Comboboxes to Select a Device Profile + \row + \i \inlineimage designer-embedded-preview.png + \endtable + + It is now possible to specify embedded device profiles, e.g., Style, Font, + Screen DPI, resolution, default font, etc., in \gui{Preferences}. These + settings will affect the \gui{Form Editor}. The profiles will also be + visible with \gui{Preview}. + + + \section1 Related Classes + + \list + \i QUiLoader \mdash forms loaded with this class will now react to + QEvent::LanguageChange if QUiLoader::setLanguageChangeEnabled() or + QUiLoader::isLanguageChangeEnabled() is set to true. + + \i QDesignerCustomWidgetInterface \mdash the + \l{QDesignerCustomWidgetInterface::}{domXml()} function now has new + attributes for its \c{<ui>} element. These attributes are + \c{language} and \c{displayname}. The \c{language} element can be + one of the following "", "c++", "jambi". If this element is + specified, it must match the language in which Designer is running. + Otherwise, this element will not be available. The \c{displayname} + element represents the name that will be displayed in the + \gui{Widget Box}. Previously this was hardcoded to be the class + name. + + \i QWizard \mdash QWizard's page now has a string \c{id} attribute that + can be used to fill in enumeration values to be used by the + \c{uic}. However, this attribute has no effect on QUiLoader. + \endlist +*/ + + +/*! + \page designer-to-know.html + \contentspage {Qt Designer Manual}{Contents} + + + \title Getting to Know Qt Designer + + \tableofcontents + + \image designer-screenshot.png + + \section1 Launching Designer + + The way that you launch \QD depends on your platform: + + \list + \i On Windows, click the Start button, under the \gui Programs submenu, + open the \gui{Qt 4} submenu and click \gui Designer. + \i On Unix or Linux, you might find a \QD icon on the desktop + background or in the desktop start menu under the \gui Programming + or \gui Development submenus. You can launch \QD from this icon. + Alternatively, you can type \c{designer} in a terminal window. + \i On Mac OS X, double click on \QD in \gui Finder. + \endlist + + \section1 The User Interface + + When used as a standalone application, \QD's user interface can be + configured to provide either a multi-window user interface (the default + mode), or it can be used in docked window mode. When used from within an + integrated development environment (IDE) only the multi-window user + interface is available. You can switch modes in the \gui Preferences dialog + from the \gui Edit menu. + + In multi-window mode, you can arrange each of the tool windows to suit your + working style. The main window consists of a menu bar, a tool bar, and a + widget box that contains the widgets you can use to create your user + interface. + + \target MainWindow + \table + \row + \i \inlineimage designer-main-window.png + \i \bold{Qt Designer's Main Window} + + The menu bar provides all the standard actions for managing forms, + using the clipboard, and accessing application-specific help. + The current editing mode, the tool windows, and the forms in use can + also be accessed via the menu bar. + + The tool bar displays common actions that are used when editing a form. + These are also available via the main menu. + + The widget box provides common widgets and layouts that are used to + design components. These are grouped into categories that reflect their + uses or features. + \endtable + + Most features of \QD are accessible via the menu bar, the tool bar, or the + widget box. Some features are also available through context menus that can + be opened over the form windows. On most platforms, the right mouse is used + to open context menus. + + \target WidgetBox + \table + \row + \i \inlineimage designer-widget-box.png + \i \bold{Qt Designer's Widget Box} + + The widget box provides a selection of standard Qt widgets, layouts, + and other objects that can be used to create user interfaces on forms. + Each of the categories in the widget box contain widgets with similar + uses or related features. + + \note Since Qt 4.4, new widgets have been included, e.g., + QPlainTextEdit, QCommandLinkButton, QScrollArea, QMdiArea, and + QWebView. + + You can display all of the available objects in a category by clicking + on the handle next to the category label. When in + \l{Qt Designer's Widget Editing Mode}{Widget Editing + Mode}, you can add objects to a form by dragging the appropriate items + from the widget box onto the form, and dropping them in the required + locations. + + \QD provides a scratch pad feature that allows you to collect + frequently used objects in a separate category. The scratch pad + category can be filled with any widget currently displayed in a form + by dragging them from the form and dropping them onto the widget box. + These widgets can be used in the same way as any other widgets, but + they can also contain child widgets. Open a context menu over a widget + to change its name or remove it from the scratch pad. + \endtable + + + \section1 The Concept of Layouts in Qt + + A layout is used to arrange and manage the elements that make up a user + interface. Qt provides a number of classes to automatically handle layouts + -- QHBoxLayout, QVBoxLayout, QGridLayout, and QFormLayout. These classes + solve the challenge of laying out widgets automatically, providing a user + interface that behaves predictably. Fortunately knowledge of the layout + classes is not required to arrange widgets with \QD. Instead, select one of + the \gui{Lay Out Horizontally}, \gui{Lay Out in a Grid}, etc., options from + the context menu. + + Each Qt widget has a recommended size, known as \l{QWidget::}{sizeHint()}. + The layout manager will attempt to resize a widget to meet its size hint. + In some cases, there is no need to have a different size. For example, the + height of a QLineEdit is always a fixed value, depending on font size and + style. In other cases, you may require the size to change, e.g., the width + of a QLineEdit or the width and height of item view widgets. This is where + the widget size constraints -- \l{QWidget::minimumSize()}{minimumSize} and + \l{QWidget::maximumSize()}{maximumSize} constraints come into play. These + are properties you can set in the property editor. For example, to override + the default \l{QWidget::}{sizeHint()}, simply set + \l{QWidget::minimumSize()}{minimumSize} and \l{QWidget::maximumSize()} + {maximumSize} to the same value. Alternatively, to use the current size as + a size constraint value, choose one of the \gui{Size Constraint} options + from the widget's context menu. The layout will then ensure that those + constraints are met. To control the size of your widgets via code, you can + reimplement \l{QWidget::}{sizeHint()} in your code. + + The screenshot below shows the breakdown of a basic user interface designed + using a grid. The coordinates on the screenshot show the position of each + widget within the grid. + + \image addressbook-tutorial-part3-labeled-layout.png + + \note Inside the grid, the QPushButton objects are actually nested. The + buttons on the right are first placed in a QVBoxLayout; the buttons at the + bottom are first placed in a QHBoxLayout. Finally, they are put into + coordinates (1,2) and (3,1) of the QGridLayout. + + To visualize, imagine the layout as a box that shrinks as much as possible, + attempting to \e squeeze your widgets in a neat arrangement, and, at the + same time, maximize the use of available space. + + Qt's layouts help when you: + + \list 1 + \i Resize the user face to fit different window sizes. + \i Resize elements within the user interface to suit different + localizations. + \i Arrange elements to adhere to layout guidelines for different + platforms. + \endlist + + So, you no longer have to worry about rearranging widgets for different + platforms, settings, and languages. + + The example below shows how different localizations can affect the user + interface. When a localization requires more space for longer text strings + the Qt layout automatically scales to accommodate this, while ensuring that + the user interface looks presentable and still matches the platform + guidelines. + + \table + \header + \i A Dialog in English + \i A Dialog in French + \row + \i \image designer-english-dialog.png + \i \image designer-french-dialog.png + \endtable + + The process of laying out widgets consists of creating the layout hierarchy + while setting as few widget size constraints as possible. + + For a more technical perspective on Qt's layout classes, refer to the + \l{Layout Management} documentation. +*/ + + +/*! + \page designer-quick-start.html + \contentspage {Qt Designer Manual}{Contents} + + + \title A Quick Start to Qt Designer + + Using \QD involves \bold four basic steps: + + \list 1 + \o Choose your form and objects + \o Lay the objects out on the form + \o Connect the signals to the slots + \o Preview the form + \endlist + + \image rgbController-screenshot.png + + Suppose you would like to design a small widget (see screenshot above) that + contains the controls needed to manipulate Red, Green and Blue (RGB) values + -- a type of widget that can be seen everywhere in image manipulation + programs. + + \table + \row + \i \inlineimage designer-choosing-form.png + \i \bold{Choosing a Form} + + You start by choosing \gui Widget from the \gui{New Form} dialog. + \endtable + + + \table + \row + \i \inlineimage rgbController-arrangement.png + \i \bold{Placing Widgets on a Form} + + Drag three labels, three spin boxes and three vertical sliders on to your + form. To change the label's default text, simply double-click on it. You + can arrange them according to how you would like them to be laid out. + \endtable + + To ensure that they are laid out exactly like this in your program, you + need to place these widgets into a layout. We will do this in groups of + three. Select the "RED" label. Then, hold down \key Ctrl while you select + its corresponding spin box and slider. In the \gui{Form} menu, select + \gui{Lay Out in a Grid}. + + \table + \row + \i \inlineimage rgbController-form-gridLayout.png + \i \inlineimage rgbController-selectForLayout.png + \endtable + + + Repeat the step for the other two labels along with their corresponding + spin boxes and sliders as well. + + The next step is to combine all three layouts into one \bold{main layout}. + The main layout is the top level widget's (in this case, the QWidget) + layout. It is important that your top level widget has a layout; otherwise, + the widgets on your window will not resize when your window is resized. To + set the layout, \gui{Right click} anywhere on your form, outside of the + three separate layouts, and select \gui{Lay Out Horizontally}. + Alternatively, you could also select \gui{Lay Out in a Grid} -- you will + still see the same arrangement (shown below). + + \image rgbController-final-layout.png + + \note Main layouts cannot be seen on the form. To check if you have a main + layout installed, try resizing your form; your widgets should resize + accordingly. Alternatively, you can take a look at \QD's + \gui{Object Inspector}. If your top level widget does not have a layout, + you will see the broken layout icon next to it, + \inlineimage rgbController-no-toplevel-layout.png + . + + When you click on the slider and drag it to a certain value, you want the + spin box to display the slider's position. To accomplish this behavior, you + need to connect the slider's \l{QAbstractSlider::}{valueChanged()} signal + to the spin box's \l{QSpinBox::}{setValue()} slot. You also need to make + the reverse connections, e.g., connect the spin box's \l{QSpinBox::} + {valueChanged()} signal to the slider's \l{QAbstractSlider::value()} + {setValue()} slot. + + To do this, you have to switch to \gui{Edit Signals/Slots} mode, either by + pressing \key{F4} or something \gui{Edit Signals/Slots} from the \gui{Edit} + menu. + + \table + \row + \i \inlineimage rgbController-signalsAndSlots.png + \i \bold{Connecting Signals to Slots} + + Click on the slider and drag the cursor towards the spin box. The + \gui{Configure Connection} dialog, shown below, will pop up. Select the + correct signal and slot and click \gui OK. + \endtable + + \image rgbController-configure-connection1.png + + Repeat the step (in reverse order), clicking on the spin box and dragging + the cursor towards the slider, to connect the spin box's + \l{QSpinBox::}{valueChanged()} signal to the slider's + \l{QAbstractSlider::value()}{setValue()} slot. + + You can use the screenshot below as a guide to selecting the correct signal + and slot. + + \image rgbController-configure-connection2.png + + Now that you have successfully connected the objects for the "RED" + component of the RGB Controller, do the same for the "GREEN" and "BLUE" + components as well. + + Since RGB values range between 0 and 255, we need to limit the spin box + and slider to that particular range. + + \table + \row + \i \inlineimage rgbController-property-editing.png + \i \bold{Setting Widget Properties} + + Click on the first spin box. Within the \gui{Property Editor}, you will + see \l{QSpinBox}'s properties. Enter "255" for the + \l{QSpinBox::}{maximum} property. Then, click on the first vertical + slider, you will see \l{QAbstractSlider}'s properties. Enter "255" for + the \l{QAbstractSlider::}{maximum} property as well. Repeat this + process for the remaining spin boxes and sliders. + \endtable + + Now, we preview your form to see how it would look in your application - + press \key{Ctrl + R} or select \gui Preview from the \gui Form menu. Try + dragging the slider - the spin box will mirror its value too (and vice + versa). Also, you can resize it to see how the layouts that are used to + manage the child widgets, respond to different window sizes. +*/ + + +/*! + \page designer-editing-mode.html + \previouspage Getting to Know Qt Designer + \contentspage {Qt Designer Manual}{Contents} + \nextpage Using Layouts in Qt Designer + + \title Qt Designer's Editing Modes + + \QD provides four editing modes: \l{Qt Designer's Widget Editing Mode} + {Widget Editing Mode}, \l{Qt Designer's Signals and Slots Editing Mode} + {Signals and Slots Editing Mode}, \l{Qt Designer's Buddy Editing Mode} + {Buddy Editing Mode} and \l{Qt Designer's Tab Order Editing Mode} + {Tab Order Editing Mode}. When working with \QD, you will always be in one + of these four modes. To switch between modes, simply select it from the + \gui{Edit} menu or the toolbar. The table below describes these modes in + further detail. + + \table + \header \i \i \bold{Editing Modes} + \row + \i \inlineimage designer-widget-tool.png + \i In \l{Qt Designer's Widget Editing Mode}{Edit} mode, we can + change the appearance of the form, add layouts, and edit the + properties of each widget. To switch to this mode, press + \key{F3}. This is \QD's default mode. + + \row + \i \inlineimage designer-connection-tool.png + \i In \l{Qt Designer's Signals and Slots Editing Mode} + {Signals and Slots} mode, we can connect widgets together using + Qt's signals and slots mechanism. To switch to this mode, press + \key{F4}. + + \row + \i \inlineimage designer-buddy-tool.png + \i In \l{Qt Designer's Buddy Editing Mode}{Buddy Editing Mode}, + buddy widgets can be assigned to label widgets to help them + handle keyboard focus correctly. + + \row + \i \inlineimage designer-tab-order-tool.png + \i In \l{Qt Designer's Tab Order Editing Mode} + {Tab Order Editing Mode}, we can set the order in which widgets + receive the keyboard focus. + \endtable + +*/ + + +/*! + \page designer-widget-mode.html + \previouspage Qt Designer's Editing Modes + \contentspage {Qt Designer Manual}{Contents} + \nextpage Qt Designer's Signals and Slots Editing Mode + + \title Qt Designer's Widget Editing Mode + + \image designer-editing-mode.png + + In the Widget Editing Mode, objects can be dragged from the main window's + widget box to a form, edited, resized, dragged around on the form, and even + dragged between forms. Object properties can be modified interactively, so + that changes can be seen immediately. The editing interface is intuitive + for simple operations, yet it still supports Qt's powerful layout + facilities. + + + \tableofcontents + + To create and edit new forms, open the \gui File menu and select + \gui{New Form...} or press \key{Ctrl+N}. Existing forms can also be edited + by selecting \gui{Open Form...} from the \gui File menu or pressing + \key{Ctrl+O}. + + At any point, you can save your form by selecting the \gui{Save From As...} + option from the \gui File menu. The UI files saved by \QD contain + information about the objects used, and any details of signal and slot + connections between them. + + + \section1 Editing A Form + + By default, new forms are opened in widget editing mode. To switch to Edit + mode from another mode, select \gui{Edit Widgets} from the \gui Edit menu + or press the \key F3 key. + + Objects are added to the form by dragging them from the main widget box + and dropping them in the desired location on the form. Once there, they + can be moved around simply by dragging them, or using the cursor keys. + Pressing the \key Ctrl key at the same time moves the selected widget + pixel by pixel, while using the cursor keys alone make the selected widget + snap to the grid when it is moved. Objects can be selected by clicking on + them with the left mouse button. You can also use the \key Tab key to + change the selection. + + ### Screenshot of widget box, again + + The widget box contains objects in a number of different categories, all of + which can be placed on the form as required. The only objects that require + a little more preparation are the \gui Container widgets. These are + described in further detail in the \l{Using Containers in Qt Designer} + chapter. + + + \target SelectingObjects + \table + \row + \i \inlineimage designer-selecting-widget.png + \i \bold{Selecting Objects} + + Objects on the form are selected by clicking on them with the left + mouse button. When an object is selected, resize handles are shown at + each corner and the midpoint of each side, indicating that it can be + resized. + + To select additional objects, hold down the \key Shift key and click on + them. If more than one object is selected, the current object will be + displayed with resize handles of a different color. + + To move a widget within a layout, hold down \key Shift and \key Control + while dragging the widget. This extends the selection to the widget's + parent layout. + + Alternatively, objects can be selected in the + \l{The Object Inspector}{Object Inspector}. + \endtable + + When a widget is selected, normal clipboard operations such as cut, copy, + and paste can be performed on it. All of these operations can be done and + undone, as necessary. + + The following shortcuts can be used: + + \target ShortcutsForEditing + \table + \header \i Action \i Shortcut \i Description + \row + \i Cut + \i \key{Ctrl+X} + \i Cuts the selected objects to the clipboard. + \row + \i Copy + \i \key{Ctrl+C} + \i Copies the selected objects to the clipboard. + \row + \i Paste + \i \key{Ctrl+V} + \i Pastes the objects in the clipboard onto the form. + \row + \i Delete + \i \key Delete + \i Deletes the selected objects. + \row + \i Clone object + \i \key{Ctrl+drag} (leftmouse button) + \i Makes a copy of the selected object or group of objects. + \row + \i Preview + \i \key{Ctrl+R} + \i Shows a preview of the form. + \endtable + + All of the above actions (apart from cloning) can be accessed via both the + \gui Edit menu and the form's context menu. These menus also provide + funcitons for laying out objects as well as a \gui{Select All} function to + select all the objects on the form. + + Widgets are not unique objects; you can make as many copies of them as you + need. To quickly duplicate a widget, you can clone it by holding down the + \key Ctrl key and dragging it. This allows widgets to be copied and placed + on the form more quickly than with clipboard operations. + + + \target DragAndDrop + \table + \row + \i \inlineimage designer-dragging-onto-form.png + \i \bold{Drag and Drop} + + \QD makes extensive use of the drag and drop facilities provided by Qt. + Widgets can be dragged from the widget box and dropped onto the form. + + Widgets can also be "cloned" on the form: Holding down \key Ctrl and + dragging the widget creates a copy of the widget that can be dragged to + a new position. + + It is also possible to drop Widgets onto the \l {The Object Inspector} + {Object Inspector} to handle nested layouts easily. + \endtable + + \QD allows selections of objects to be copied, pasted, and dragged between + forms. You can use this feature to create more than one copy of the same + form, and experiment with different layouts in each of them. + + + \section2 The Property Editor + + The Property Editor always displays properties of the currently selected + object on the form. The available properties depend on the object being + edited, but all of the widgets provided have common properties such as + \l{QObject::}{objectName}, the object's internal name, and + \l{QWidget::}{enabled}, the property that determines whether an + object can be interacted with or not. + + + \target EditingProperties + \table + \row + \i \inlineimage designer-property-editor.png + \i \bold{Editing Properties} + + The property editor uses standard Qt input widgets to manage the + properties of jbects on the form. Textual properties are shown in line + edits, integer properties are displayed in spinboxes, boolean + properties are displayed in check boxes, and compound properties such + as colors and sizes are presented in drop-down lists of input widgets. + + Modified properties are indicated with bold labels. To reset them, click + the arrow button on the right. + + Changes in properties are applied to all selected objects that have the + same property. + \endtable + + Certain properties are treated specially by the property editor: + + \list + \o Compound properties -- properties that are made up of more than one + value -- are represented as nodes that can be expanded, allowing + their values to be edited. + \o Properties that contain a choice or selection of flags are edited + via combo boxes with checkable items. + \o Properties that allow access to rich data types, such as QPalette, + are modified using dialogs that open when the properties are edited. + QLabel and the widgets in the \gui Buttons section of the widget box + have a \c text property that can also be edited by double-clicking + on the widget or by pressing \gui F2. \QD interprets the backslash + (\\) character specially, enabling newline (\\n) characters to be + inserted into the text; the \\\\ character sequence is used to + insert a single backslash into the text. A context menu can also be + opened while editing, providing another way to insert special + characters and newlines into the text. + \endlist + + + \section2 Dynamic Properties + + The property editor can also be used to add new + \l{QObject#Dynamic Properties}{dynamic properties} to both standard Qt + widgets and to forms themselves. Since Qt 4.4, dynamic properties are added + and removed via the property editor's toolbar, shown below. + + \image designer-property-editor-toolbar.png + + To add a dynamic property, clcik on the \gui Add button + \inlineimage designer-property-editor-add-dynamic.png + . To remove it, click on the \gui Remove button + \inlineimage designer-property-editor-remove-dynamic.png + instead. You can also sort the properties alphabetically and change the + color groups by clickinig on the \gui Configure button + \inlineimage designer-property-editor-configure.png + . + + \section2 The Object Inspector + \table + \row + \i \inlineimage designer-object-inspector.png + \i \bold{The Object Inspector} + + The \gui{Object Inspector} displays a hierarchical list of all the + objects on the form that is currently being edited. To show the child + objects of a container widget or a layout, click the handle next to the + object label. + + Each object on a form can be selected by clicking on the corresponding + item in the \gui{Object Inspector}. Right-clicking opens the form's + context menu. These features can be useful if you have many overlapping + objects. To locate an object in the \gui{Object Inspector}, use + \key{Ctrl+F}. + + Since Qt 4.4, double-clicking on the object's name allows you to change + the object's name with the in-place editor. + + Since Qt 4.5, the \gui{Object Inspector} displays the layout state of + the containers. The broken layout icon ###ICON is displayed if there is + something wrong with the layouts. + + \endtable +*/ + + +/*! + \page designer-layouts.html + \previouspage Qt Designer's Widget Editing Mode + \contentspage + \nextpage Qt Designer's Signals and Slots Editing Mode + + \title Using Layouts in Qt Designer + + Before a form can be used, the objects on the form need to be placed into + layouts. This ensures that the objects will be displayed properly when the + form is previewed or used in an application. Placing objects in a layout + also ensures that they will be resized correctly when the form is resized. + + + \tableofcontents + + \section1 Applying and Breaking Layouts + + The simplest way to manage objects is to apply a layout to a group of + existing objects. This is achieved by selecting the objects that you need + to manage and applying one of the standard layouts using the main toolbar, + the \gui Form menu, or the form's context menu. + + Once widgets have been inserted into a layout, it is not possible to move + and resize them individually because the layout itself controls the + geometry of each widget within it, taking account of the hints provided by + spacers. Instead, you must either break the layout and adjust each object's + geometry manually, or you can influence the widget's geometry by resizing + the layout. + + To break the layout, press \key{Ctrl+0} or choose \gui{Break Layout} from + the form's context menu, the \gui Form menu or the main toolbar. You can + also add and remove spacers from the layout to influence the geometries of + the widgets. + + + \target InsertingObjectsIntoALayout + \table + \row + \i \inlineimage designer-layout-inserting.png + \i \bold{Inserting Objects into a Layout} + + Objects can be inserted into an existing layout by dragging them from + their current positions and dropping them at the required location. A + blue cursor is displayed in the layout as an object is dragged over + it to indicate where the object will be added. + \endtable + + + \section2 Setting A Top Level Layout + + The form's top level layout can be set by clearing the slection (click the + left mouse button on the form itself) and applying a layout. A top level + layout is necessary to ensure that your widgets will resize correctly when + its window is resized. To check if you have set a top level layout, preview + your widget and attempt to resize the window by dragging the size grip. + + \table + \row + \i \inlineimage designer-set-layout.png + \i \bold{Applying a Layout} + + To apply a layout, you can select your choice of layout from the + toolbar shown on the left, or from the context menu shown below. + \endtable + + \image designer-set-layout2.png + + + \section2 Horizontal and Vertical Layouts + + The simplest way to arrange objects on a form is to place them in a + horizontal or vertical layout. Horizontal layouts ensure that the widgets + within are aligned horizontally; vertical layouts ensure that they are + aligned vertically. + + Horizontal and vertical layouts can be combined and nested to any depth. + However, if you need more control over the placement of objects, consider + using the grid layout. + + + \section3 The Grid Layout + + Complex form layouts can be created by placing objects in a grid layout. + This kind of layout gives the form designer much more freedom to arrange + widgets on the form, but can result in a much less flexible layout. + However, for some kinds of form layout, a grid arrangement is much more + suitable than a nested arrangement of horizontal and vertical layouts. + + + \section3 Splitter Layouts + + Another common way to manage the layout of objects on a form is to place + them in a splitter. These splitters arrange the objects horizontally or + vertically in the same way as normal layouts, but also allow the user to + adjust the amount of space allocated to each object. + + \image designer-splitter-layout.png + + Although QSplitter is a container widget, \QD treats splitter objects as + layouts that are applied to existing widgets. To place a group of widgets + into a splitter, select them + \l{Qt Designer's Widget Editing Mode#SelectingObjects}{as described here} + then apply the splitter layout by using the appropriate toolbar button, + keyboard shortcut, or \gui{Lay out} context menu entry. + + + \section3 The Form Layout + + Since Qt 4.4, another layout class has been included -- QFormLayout. This + class manages widgets in a two-column form; the left column holds labels + and the right column holds field widgets such as line edits, spin boxes, + etc. The QFormLayout class adheres to various platform look and feel + guidelines and supports wrapping for long rows. + + \image designer-form-layout.png + + The UI file above results in the previews shown below. + + \table + \header + \i Windows XP + \i Mac OS X + \i Cleanlooks + \row + \i \inlineimage designer-form-layout-windowsXP.png + \i \inlineimage designer-form-layout-macintosh.png + \i \inlineimage designer-form-layout-cleanlooks.png + \endtable + + + \section2 Shortcut Keys + + In addition to the standard toolbar and context menu entries, there is also + a set of keyboard shortcuts to apply layouts on widgets. + + \target LayoutShortcuts + \table + \header + \i Layout + \i Shortcut + \i Description + \row + \i Horizontal + \i \key{Ctrl+1} + \i Places the selected objects in a horizontal layout. + \row + \i Vertical + \i \key{Ctrl+2} + \i Places the selected objects in a vertical layout. + \row + \i Grid + \i \key{Ctrl+5} + \i Places the selected objects in a grid layout. + \row + \i Form + \i \key{Ctrl+6} + \i Places the selected objects in a form layout. + \row + \i Horizontal splitter + \i \key{Ctrl+3} + \i Creates a horizontal splitter and places the selected objects + inside it. + \row + \i Vertical splitter + \i \key{Ctrl+4} + \i Creates a vertical splitter and places the selected objects + inside it. + \row + \i Adjust size + \i \key{Ctrl+J} + \i Adjusts the size of the layout to ensure that each child object + has sufficient space to display its contents. See + QWidget::adjustSize() for more information. + \endtable + + \note \key{Ctrl+0} is used to break a layout. + +*/ + + +/*! + \page designer-preview.html + \contentspage {Qt Designer Manual}{Contents} + \previouspage Using Layouts in Qt Designer + \nextpage Qt Designer's Buddy Editing Mode + \title Saving, Previewing and Printing Forms in Qt Designer + + Although \QD's forms are accurate representations of the components being + edited, it is useful to preview the final appearance while editing. This + feature can be activated by opening the \gui Form menu and selecting + \gui Preview, or by pressing \key{Ctrl+R} when in the form. + + \image designer-dialog-preview.png + + The preview shows exactly what the final component will look like when used + in an application. + + Since Qt 4.4, it is possible to preview forms with various skins - default + skins, skins created with Qt Style Sheets or device skins. This feature + simulates the effect of calling \c{QApplication::setStyleSheet()} in the + application. + + To preview your form with skins, open the \gui Edit menu and select + \gui{Preferences...} + + You will see the dialog shown below: + + \image designer-preview-style.png + + The \gui{Print/Preview Configuration} checkbox must be checked to activate + previews of skins. You can select the styles provided from the \gui{Style} + drop-down box. + + \image designer-preview-style-selection.png + + Alternatively, you can preview custom style sheet created with Qt Style + Sheets. The figure below shows an example of Qt Style Sheet syntax and the + corresponding output. + + \image designer-preview-stylesheet.png + + Another option would be to preview your form with device skins. A list of + generic device skins are available in \QD, however, you may also use + other QVFB skins with the \gui{Browse...} option. + + \image designer-preview-deviceskin-selection.png + + + \section1 Viewing the Form's Code + + Since Qt 4.4, it is possible to view code generated by the User Interface + Compiler (uic) for the \QD form. + + \image designer-form-viewcode.png + + Select \gui{View Code...} from the \gui{Form} menu and a dialog with the + generated code will be displayed. The screenshot below is an example of + code generated by the \c{uic}. + + \image designer-code-viewer.png + + \section1 Saving and Printing the Form + + Forms created in \QD can be saved to an image or printed. + + \table + \row + \i \inlineimage designer-file-menu.png + \i \bold{Saving Forms} + + To save a form as an image, choose the \gui{Save Image...} option. The file + will be saved in \c{.png} format. + + \bold{Printing Forms} + + To print a form, select the \gui{Print...} option. + + \endtable +*/ + + +/*! + \page designer-connection-mode.html + \contentspage {Qt Designer Manual}{Contents} + \previouspage Using Layouts in Qt Designer + \nextpage Qt Designer's Buddy Editing Mode + + + \title Qt Designer's Signals and Slots Editing Mode + + \image designer-connection-mode.png + + In \QD's signals and slots editing mode, you can connect objects in a form + together using Qt's signals and slots mechanism. Both widgets and layouts + can be connected via an intuitive connection interface, using the menu of + compatible signals and slots provided by \QD. When a form is saved, all + connections are preserved so that they will be ready for use when your + project is built. + + + \tableofcontents + + For more information on Qt's signals and sltos mechanism, refer to the + \l{Signals and Slots} document. + + + \section1 Connecting Objects + + To begin connecting objects, enter the signals and slots editing mode by + opening the \gui Edit menu and selecting \gui{Edit Signals/Slots}, or by + pressing the \key F4 key. + + All widgets and layouts on the form can be connected together. However, + spacers just provide spacing hints to layouts, so they cannot be connected + to other objects. + + + \target HighlightedObjects + \table + \row + \i \inlineimage designer-connection-highlight.png + \i \bold{Highlighted Objects} + + When the cursor is over an object that can be used in a connection, the + object will be highlighted. + \endtable + + To make a connectionn, press the left mouse button and drag the cursor + towards the object you want to connect it to. As you do this, a line will + extend from the source object to the cursor. If the cursor is over another + object on the form, the line will end with an arrow head that points to the + destination object. This indicates that a connection will be made between + the two objects when you release the mouse button. + + You can abandon the connection at any point while you are dragging the + connection path by pressing \key{Esc}. + + \target MakingAConnection + \table + \row + \i \inlineimage designer-connection-making.png + \i \bold{Making a Connection} + + The connection path will change its shape as the cursor moves around + the form. As it passes over objects, they are highlighted, indicating + that they can be used in a signal and slot connection. Release the + mouse button to make the connection. + \endtable + + The \gui{Configure Connection} dialog (below) is displayed, showing signals + from the source object and slots from the destination object that you can + use. + + \image designer-connection-dialog.png + + To complete the connection, select a signal from the source object and a + slot from the destination object, then click \key OK. Click \key Cancel if + you wish to abandon the connection. + + \note If the \gui{Show all signals and slots} checkbox is selected, all + available signals from the source object will be shown. Otherwise, the + signals and slots inherited from QWidget will be hidden. + + You can make as many connections as you like between objects on the form; + it is possible to connect signals from objects to slots in the form itself. + As a result, the signal and slot connections in many dialogs can be + completely configured from within \QD. + + \target ConnectingToTheForm + \table + \row + \i \inlineimage designer-connection-to-form.png + \i \bold{Connecting to a Form} + + To connect an object to the form itself, simply position the cursor + over the form and release the mouse button. The end point of the + connection changes to the electrical "ground" symbol. + \endtable + + + \section1 Editing and Deleting Connections + + By default, connection paths are created with two labels that show the + signal and slot involved in the connection. These labels are usually + oriented along the line of the connection. You can move them around inside + their host widgets by dragging the red square at each end of the connection + path. + + \target ConnectionEditor + \table + \row + \i \inlineimage designer-connection-editor.png + \i \bold{The Signal/Slot Editor} + + The signal and slot used in a connection can be changed after it has + been set up. When a connection is configured, it becomes visible in + \QD's signal and slot editor where it can be further edited. You can + also edit signal/slot connections by double-clicking on the connection + path or one of its labels to display the Connection Dialog. + \endtable + + \target DeletingConnections + \table + \row + \i \inlineimage designer-connection-editing.png + \i \bold{Deleting Connections} + + The whole connection can be selected by clicking on any of its path + segments. Once selected, a connection can be deleted with the + \key Delete key, ensuring that it will not be set up in the UI + file. + \endtable +*/ + + +/*! + \page designer-buddy-mode.html + \contentspage{Qt Designer Manual}{Contents} + \previouspage Qt Designer's Signals and Slots Editing Mode + \nextpage Qt Designer's Tab Order Editing Mode + + \title Qt Designer's Buddy Editing Mode + + \image designer-buddy-mode.png + + One of the most useful basic features of Qt is the support for buddy + widgets. A buddy widget accepts the input focus on behalf of a QLabel when + the user types the label's shortcut key combination. The buddy concept is + also used in Qt's \l{Model/View Programming}{model/view} framework. + + + \section1 Linking Labels to Buddy Widgets + + To enter buddy editing mode, open the \gui Edit menu and select + \gui{Edit Buddies}. This mode presents the widgets on the form in a similar + way to \l{Qt Designer's Signals and Slots Editing Mode}{signals and slots + editing mode} but in this mode, connections must start at label widgets. + Ideally, you should connect each label widget that provides a shortcut with + a suitable input widget, such as a QLineEdit. + + + \target MakingBuddies + \table + \row + \i \inlineimage designer-buddy-making.png + \i \bold{Making Buddies} + + To define a buddy widget for a label, click on the label, drag the + connection to another widget on the form, and release the mouse button. + The connection shown indicates how input focus is passed to the buddy + widget. You can use the form preview to test the connections between + each label and its buddy. + \endtable + + + \section1 Removing Buddy Connections + + Only one buddy widget can be defined for each label. To change the buddy + used, it is necessary to delete any existing buddy connection before you + create a new one. + + Connections between labels and their buddy widgets can be deleted in the + same way as signal-slot connections in signals and slots editing mode: + Select the buddy connection by clicking on it and press the \key Delete + key. This operation does not modify either the label or its buddy in any + way. +*/ + + +/*! + \page designer-tab-order.html + \contentspage {Qt Designer Manual}{Contents} + \previouspage Qt Designer's Buddy Editing Mode + \nextpage Using Containers in Qt Designer + + \title Qt Designer's Tab Order Editing Mode + + \image designer-tab-order-mode.png + + Many users expect to be able to navigate between widgets and controls + using only the keyboard. Qt lets the user navigate between input widgets + with the \key Tab and \key{Shift+Tab} keyboard shortcuts. The default + \e{tab order} is based on the order in which widgets are constructed. + Although this order may be sufficient for many users, it is often better + to explicitly specify the tab order to make your application easier to + use. + + + \section1 Setting the Tab Order + + To enter tab order editing mode, open the \gui Edit menu and select + \gui{Edit Tab Order}. In this mode, each input widget in the form is shown + with a number indicating its position in the tab order. So, if the user + gives the first input widget the input focus and then presses the tab key, + the focus will move to the second input widget, and so on. + + The tab order is defined by clicking on each of the numbers in the correct + order. The first number you click will change to red, indicating the + currently edited position in the tab order chain. The widget associated + with the number will become the first one in the tab order chain. Clicking + on another widget will make it the second in the tab order, and so on. + + Repeat this process until you are satisfied with the tab order in the form + -- you do not need to click every input widget if you see that the + remaining widgets are already in the correct order. Numbers, for which you + already set the order, change to green, while those which are not clicked + yet, remain blue. + + If you make a mistake, simply double click outside of any number or choose + \gui{Restart} from the form's context menu to start again. If you have many + widgets on your form and would like to change the tab order in the middle or + at the end of the tab order chain, you can edit it at any position. Press + \key{Ctrl} and click the number from which you want to start. + Alternatively, choose \gui{Start from Here} in the context menu. + +*/ + + +/*! + \page designer-using-containers.html + \contentspage {Qt Designer Manual}{Contents} + \previouspage Qt Designer's Tab Order Editing Mode + \nextpage Creating Main Windows in Qt Designer + + + \title Using Containers in Qt Designer + + Container widgets provide high level control over groups of objects on a + form. They can be used to perform a variety of functions, such as managing + input widgets, providing paged and tabbed layouts, or just acting as + decorative containers for other objects. + + \image designer-widget-morph.png + + \QD provides visual feedback to help you place objects inside your + containers. When you drag an object from the widget box (or elsewhere) on + the form, each container will be highlighted when the cursor is positioned + over it. This indicates that you can drop the object inside, making it a + child object of the container. This feedback is important because it is + easy to place objects close to containers without actually placing them + inside. Both widgets and spacers can be used inside containers. + + Stacked widgets, tab widgets, and toolboxes are handled specially in \QD. + Normally, when adding pages (tabs, pages, compartments) to these containers + in your own code, you need to supply existing widgets, either as + placeholders or containing child widgets. In \QD, these are automatically + created for you, so you can add child objects to each page straight away. + + Each container typically allows its child objects to be arranged in one or + more layouts. The type of layout management provided depends on each + container, although setting the layout is usually just a matter of + selecting the container by clicking it, and applying a layout. The table + below shows a list of available containers. + + \table + \row + \i \inlineimage designer-containers-frame.png + \i \bold Frames + + Frames are used to enclose and group widgets, as well as to provide + decoration. They are used as the foundation for more complex + containers, but they can also be used as placeholders in forms. + + The most important properties of frames are \c frameShape, + \c frameShadow, \c lineWidth, and \c midLineWidth. These are described + in more detail in the QFrame class description. + + \row + \i \inlineimage designer-containers-groupbox.png + \i \bold{Group Boxes} + + Group boxes are usually used to group together collections of + checkboxes and radio buttons with similar purposes. + + Among the significant properties of group boxes are \c title, \c flat, + \c checkable, and \c checked. These are demonstrated in the + \l{widgets/groupbox}{Group Box} example, and described in the QGroupBox + class documentation. Each group box can contain its own layout, and + this is necessary if it contains other widgets. To add a layout to the + group box, click inside it and apply the layout as usual. + + \row + \i \inlineimage designer-containers-stackedwidget.png + \i \bold{Stacked Widgets} + + Stacked widgets are collections of widgets in which only the topmost + layer is visible. Control over the visible layer is usually managed by + another widget, such as combobox, using signals and slots. + + \QD shows arrows in the top-right corner of the stack to allow you to + see all the widgets in the stack when designing it. These arrows do not + appear in the preview or in the final component. To navigate between + pages in the stack, select the stacked widget and use the + \gui{Next Page} and \gui{Previous Page} entries from the context menu. + The \gui{Insert Page} and \gui{Delete Page} context menu options allow + you to add and remove pages. + + \row + \i \inlineimage designer-containers-tabwidget.png + \i \bold{Tab Widgets} + + Tab widgets allow the developer to split up the contents of a widget + into different labelled sections, only one of which is displayed at any + given time. By default, the tab widget contains two tabs, and these can + be deleted or renamed as required. You can also add additional tabs. + + To delete a tab: + \list + \o Click on its label to make it the current tab. + \o Select the tab widget and open its context menu. + \o Select \gui{Delete Page}. + \endlist + + To add a new tab: + \list + \o Select the tab widget and open its context menu. + \o Select \gui{Insert Page}. + \o You can add a page before or after the \e current page. \QD + will create a new widget for that particular tab and insert it + into the tab widget. + \o You can set the title of the current tab by changing the + \c currentTabText property in the \gui{Property Editor}. + \endlist + + \row + \i \inlineimage designer-containers-toolbox.png + \i \bold{ToolBox Widgets} + + Toolbox widgets provide a series of pages or compartments in a toolbox. + They are handled in a way similar to stacked widgets. + + To rename a page in a toolbox, make the toolbox your current pange and + change its \c currentItemText property from the \gui{Property Editor}. + + To add a new page, select \gui{Insert Page} from the toolbox widget's + context menu. You can add the page before or after the current page. + + To delete a page, select \gui{Delete Page} from the toolbox widget's + context menu. + + \row + \i \inlineimage designer-containers-dockwidget.png + \i \bold{Dock Widgets} + + Dock widgets are floating panels, often containing input widgets and + more complex controls, that are either attached to the edges of the + main window in "dock areas", or floated as independent tool windows. + + Although dock widgets can be added to any type of form, they are + typically used with forms created from the + \l{Creating Main Windows in Qt Designer}{main window template}. + + \endtable +*/ + + +/*! + \page designer-creating-mainwindows.html + \contentspage {Qt Designer Manual}{Contents} + \previouspage Using Containers in Qt Designer + \nextpage Editing Resources with Qt Designer + + \title Creating Main Windows in Qt Designer + + \QD can be used to create user interfaces for different purposes, and + it provides different kinds of form templates for each user interface. The + main window template is used to create application windows with menu bars, + toolbars, and dock widgets. + + \omit + \image designer-mainwindow-example.png + \endomit + + Create a new main window by opening the \gui File menu and selecting the + \gui{New Form...} option, or by pressing \key{Ctrl+N}. Then, select the + \gui{Main Window} template. This template provides a main application + window containing a menu bar and a toolbar by default -- these can be + removed if they are not required. + + If you remove the menu bar, a new one can be created by selecting the + \gui{Create Menu Bar} option from the context menu, obtained by + right-clicking within the main window form. + + An application can have only \bold one menu bar, but \bold several + toolbars. + + + \section1 Menus + + Menus are added to the menu bar by modifying the \gui{Type Here} + placeholders. One of these is always present for editing purposes, and + will not be displayed in the preview or in the finished window. + + Once created, the properties of a menu can be accessed using the + \l{Qt Designer's Widget Editing Mode#The Property Editor}{Property Editor}, + and each menu can be accessed for this purpose via the + \l{Qt Designer's Widget Editing Mode#The Object Inspector}{The Object Inspector}. + + Existing menus can be removed by opening a context menu over the label in + the menu bar, and selecting \gui{Remove Menu 'menu_name'}. + + + \target CreatingAMenu + \table + \row + \i \inlineimage designer-creating-menu1.png + \i \inlineimage designer-creating-menu2.png + \i \bold{Creating a Menu} + + Double-click the placeholder item to begin editing. The menu text, + displayed using a line edit, can be modified. + + \row + \i \inlineimage designer-creating-menu3.png + \i \inlineimage designer-creating-menu4.png + \i Insert the required text for the new menu. Inserting an + ampersand character (&) causes the letter following it to be + used as a mnemonic for the menu. + + Press \key Return or \key Enter to accept the new text, or press + \key Escape to reject it. You can undo the editing operation later if + required. + \endtable + + Menus can also be rearranged in the menu bar simply by dragging and + dropping them in the preferred location. A vertical red line indicates the + position where the menu will be inserted. + + Menus can contain any number of entries and separators, and can be nested + to the required depth. Adding new entries to menus can be achieved by + navigating the menu structure in the usual way. + + \target CreatingAMenuEntry + \table + \row + \i \inlineimage designer-creating-menu-entry1.png + \i \inlineimage designer-creating-menu-entry2.png + \i \bold{Creating a Menu Entry} + + Double-click the \gui{new action} placeholder to begin editing, or + double-click \gui{new separator} to insert a new separator line after + the last entry in the menu. + + The menu entry's text is displayed using a line edit, and can be + modified. + + \row + \i \inlineimage designer-creating-menu-entry3.png + \i \inlineimage designer-creating-menu-entry4.png + \i Insert the required text for the new entry, optionally using + the ampersand character (&) to mark the letter to use as a + mnemonic for the entry. + + Press \key Return or \key Enter to accept the new text, or press + \key Escape to reject it. The action created for this menu entry will + be accessible via the \l{#TheActionEditor}{Action Editor}, and any + associated keyboard shortcut can be set there. + \endtable + + Just like with menus, entries can be moved around simply by dragging and + dropping them in the preferred location. When an entry is dragged over a + closed menu, the menu will open to allow it to be inserted there. Since + menu entries are based on actions, they can also be dropped onto toolbars, + where they will be displayed as toolbar buttons. + + + \section1 Toolbars + + + ### SCREENSHOT + + Toolbars ared added to a main window in a similar way to the menu bar: + Select the \gui{Add Tool Bar} option from the form's context menu. + Alternatively, if there is an existing toolbar in the main window, you can + click the arrow on its right end to create a new toolbar. + + Toolbar buttons are created using the action system to populate each + toolbar, rather than by using specific button widgets from the widget box. + Since actions can be represented by menu entries and toolbar buttons, they + can be moved between menus and toolbars. To share an action between a menu + and a toolbar, drag its icon from the \l{#TheActionEditor}{Action Editor} + to the toolbar rather than from the menu where its entry is located. + + New actions for menus and toolbars can be created in the + \l{#TheActionEditor}{Action Editor}. + + + \section1 Actions + + With the menu bar and the toolbars in place, it's time to populate them + with action: \QD provides an action editor to simplify the creation and + management of actions. + + + \target TheActionEditor + \table + \row + \i \inlineimage designer-action-editor.png + \i \bold{The Action Editor} + + Enable the action editor by opening the \gui Tools menu, and switching + on the \gui{Action Editor} option. + + The action editor allows you to create \gui New actions and \gui Delete + actions. It also provides a search function, \gui Filter, using the + action's text. + + \QD's action editor can be viewed in the classic \gui{Icon View} and + \gui{Detailed View}. The screenshot below shows the action editor in + \gui{Detailed View}. You can also copy and paste actions between menus, + toolbars and forms. + \endtable + + To create an action, use the action editor's \gui New button, which will + then pop up an input dialog. Provide the new action with a \gui Text -- + this is the text that will appear in a menu entry and as the action's + tooltip. The text is also automatically added to an "action" prefix, + creating the action's \gui{Object Name}. + + In addition, the dialog provides the option of selecting an \gui Icon for + the action, as well as removing the current icon. + + Once the action is created, it can be used wherever actions are applicable. + + + \target AddingAnAction + \table + \row + \i \inlineimage designer-adding-menu-action.png + \i \inlineimage designer-adding-toolbar-action.png + \i \bold{Adding an Action} + + To add an action to a menu or a toolbar, simply press the left mouse + button over the action in the action editor, and drag it to the + preferred location. + + \QD provides highlighted guide lines that tell you where the action + will be added. Release the mouse button to add the action when you have + found the right spot. + \endtable + + + \section1 Dock Widgets + + Since dock widgets are \l{Using Containers in Qt Designer} + {container widgets}, they can be added to a form in the usuasl way. Once + added to a form, dock widgets are not placed in any particular dock area by + default; you need to set the \gui{docked} property to true for each widget + and choose an appropriate value for its \gui{dockWidgetArea} property. + + \target AddingADockWidget + \table + \row + \i \inlineimage designer-adding-dockwidget.png + \i \bold{Adding a Dock Widget} + + To add a dock widget, simply drag one from the \gui Containers section + of the widget box, and drop it onto the main form area. Just like other + widgets, its properties can be modified with the \gui{Property Editor}. + + Dock widgets can be optionally floated as indpendent tool windows. + Hence, it is useful to give them window titles by setting their + \gui{windowTitle} property. This also helps to identify them on the + form. + + \endtable +*/ + + +/*! + \page designer-resources.html + \contentspage {Qt Designer Manual}{Contents} + \previouspage Creating Main Windows in Qt Designer + \nextpage Using Stylesheets with Qt Designer + + \title Editing Resources with Qt Designer + + \image designer-resources-editing.png + + \QD fully supports the \l{The Qt Resource System}{Qt Resource System}, + enabling resources to be specified together with forms as they are + designed. To aid designers and developers manage resources for their + applications, \QD's resource editor allows resources to be defined on a + per-form basis. In other words, each form can have a separate resource + file. + + \section1 Defining a Resource File + + To specify a resource file you must enable the resource editor by opening + the \gui Tools menu, and switching on the \gui{Resource Browser} option. + + \target ResourceFiles + \table + \row + \i \inlineimage designer-resource-browser.png + \i \bold{Resource Files} + + Within the resource browser, you can open existing resource files or + create new ones. Click the \gui{Edit Resources} button + \inlineimage designer-edit-resources-button.png + to edit your resources. To reload resources, click on the \gui Reload + button + \inlineimage designer-reload-resources-button.png + . + \endtable + + + Once a resource file is loaded, you can create or remove entries in it + using the given \gui{Add Files} + \inlineimage designer-add-resource-entry-button.png + and \gui{Remove Files} + \inlineimage designer-remove-resource-entry-button.png + buttons, and specify resources (e.g., images) using the \gui{Add Files} + button + \inlineimage designer-add-files-button.png + . Note that these resources must reside within the current resource file's + directory or one of its subdirectories. + + + \target EditResource + \table + \row + \i \inlineimage designer-edit-resource.png + \i \bold{Editing Resource Files} + + Press the + \inlineimage designer-add-resource-entry-button.png + button to add a new resource entry to the file. Then use the + \gui{Add Files} button + \inlineimage designer-add-files-button.png + to specify the resource. + + You can remove resources by selecting the corresponding entry in the + resource editor, and pressing the + \inlineimage designer-remove-resource-entry-button.png + button. + \endtable + + + \section1 Using the Resources + + Once the resources are defined you can use them actively when composing + your form. For example, you might want to create a tool button using an + icon specified in the resource file. + + \target UsingResources + \table + \row + \i \inlineimage designer-resources-using.png + \i \bold{Using Resources} + + When changing properties with values that may be defined within a + resource file, \QD's property editor allows you to specify a resource + in addition to the option of selecting a source file in the ordinary + way. + + \row + \i \inlineimage designer-resource-selector.png + \i \bold{Selecting a Resource} + + You can open the resource selector by clicking \gui{Choose Resource...} + to add resources any time during the design process. + +\omit +... check with Friedemann +To quickly assign icon pixmaps to actions or pixmap properties, you may +drag the pixmap from the resource editor to the action editor, or to the +pixmap property in the property editor. +\endomit + + \endtable +*/ + + +/*! + \page designer-stylesheet.html + \contentspage {Qt Designer Manual}{Contents} + \previouspage Editing Resources with Qt Designer + \nextpage Using a Designer UI File in Your Application + + \title Using Stylesheets with Qt Designer + + Since Qt 4.2, it is possible to edit stylesheets in \QD with the stylesheet + editor. + + \target UsingStylesheets + \table + \row + \i \inlineimage designer-stylesheet-options.png + \bold{Setting a Stylesheet} + + The stylesheet editor can be accessed by right-clicking a widget + and selecting \gui{Change styleSheet...} + + \row + \i \inlineimage designer-stylesheet-usage.png + \endtable + +*/ + + +/*! + \page designer-using-a-ui-file.html + \previouspage Using Stylesheets with Qt Designer + \contentspage {Qt Designer Manual}{Contents} + \nextpage Using Custom Widgets with Qt Designer + + \title Using a Designer UI File in Your Application + + With Qt's integrated build tools, \l{qmake Manual}{qmake} and \l uic, the + code for user interface components created with \QD is automatically + generated when the rest of your application is built. Forms can be included + and used directly from your application. Alternatively, you can use them to + extend subclasses of standard widgets. These forms can be processed at + compile time or at run time, depending on the approach used. + + + \tableofcontents + \section1 Compile Time Form Processing + + A compile time processed form can be used in your application with one of + the following approaches: + + \list + \o The Direct Approach: you construct a widget to use as a placeholder + for the component, and set up the user interface inside it. + \o The Single Inheritance Approach: you subclass the form's base class + (QWidget or QDialog, for example), and include a private instance + of the form's user interface object. + \o The MultipleInheritance Approach: you subclass both the form's base + class and the form's user interface object. This allows the widgets + defined in the form to be used directly from within the scope of + the subclass. + \endlist + + + \section2 The Direct Approach + + To demonstrate how to use user interface (UI) files straight from + \QD, we create a simple Calculator Form application. This is based on the + original \l{Calculator Form Example}{Calculator Form} example. + + The application consists of one source file, \c main.cpp and a UI + file. + + The \c{calculatorform.ui} file designed with \QD is shown below: + + \image directapproach-calculatorform.png + + We will use \c qmake to build the executable, so we need to write a + \c{.pro} file: + + \snippet doc/src/snippets/uitools/calculatorform/calculatorform.pro 0 + + The special feature of this file is the \c FORMS declaration that tells + \c qmake which files to process with \c uic. In this case, the + \c calculatorform.ui file is used to create a \c ui_calculatorform.h file + that can be used by any file listed in the \c SOURCES declaration. To + ensure that \c qmake generates the \c ui_calculatorform.h file, we need to + include it in a file listed in \c SOURCES. Since we only have \c main.cpp, + we include it there: + + \snippet doc/src/snippets/uitools/calculatorform/main.cpp 0 + + This include is an additional check to ensure that we do not generate code + for UI files that are not used. + + The \c main function creates the calculator widget by constructing a + standard QWidget that we use to host the user interface described by the + \c calculatorform.ui file. + + \snippet doc/src/snippets/uitools/calculatorform/main.cpp 1 + + In this case, the \c{Ui::CalculatorForm} is an interface description object + from the \c ui_calculatorform.h file that sets up all the dialog's widgets + and the connections between its signals and slots. + + This approach provides a quick and easy way to use simple, self-contained + components in your applications, but many componens created with \QD will + require close integration with the rest of the application code. For + instance, the \c CalculatorForm code provided above will compile and run, + but the QSpinBox objects will not interact with the QLabel as we need a + custom slot to carry out the add operation and display the result in the + QLabel. To achieve this, we need to subclass a standard Qt widget (known as + the single inheritance approach). + + + \section2 The Single Inheritance Approach + + In this approach, we subclass a Qt widget and set up the user interface + from within the constructor. Components used in this way expose the widgets + and layouts used in the form to the Qt widget subclass, and provide a + standard system for making signal and slot connections between the user + interface and other objects in your application. + + This approach is used in the \l{Calculator Form Example}{Calculator Form} + example. + + To ensure that we can use the user interface, we need to include the header + file that \c uic generates before referring to \c{Ui::CalculatorForm}: + + \snippet examples/designer/calculatorform/calculatorform.h 0 + + This means that the \c{.pro} file must be updated to include + \c{calculatorform.h}: + + \snippet examples/designer/calculatorform/calculatorform.pro 0 + + The subclass is defined in the following way: + + \snippet examples/designer/calculatorform/calculatorform.h 1 + + The important feature of the class is the private \c ui object which + provides the code for setting up and managing the user interface. + + The constructor for the subclass constructs and configures all the widgets + and layouts for the dialog just by calling the \c ui object's \c setupUi() + function. Once this has been done, it is possible to modify the user + interface as needed. + + \snippet examples/designer/calculatorform/calculatorform.cpp 0 + + We can connect signals and slots in user interface widgets in the usual + way, taking care to prefix the \c ui object to each widget used. + + The advantages of this approach are its simple use of inheritance to + provide a QWidget-based interface, and its encapsulation of the user + interface widget variables within the \c ui data member. We can use this + method to define a number of user interfaces within the same widget, each + of which is contained within its own namespace, and overlay (or compose) + them. This approach can be used to create individual tabs from existing + forms, for example. + + + \section2 The Multiple Inheritance Approach + + Forms created with \QD can be subclassed together with a standard + QWidget-based class. This approach makes all the user interface components + defined in the form directly accessible within the scope of the subclass, + and enables signal and slot connections to be made in the usual way with + the \l{QObject::connect()}{connect()} function. + + This approach is used in the \l{Multiple Inheritance Example} + {Multiple Inheritance} example. + + We need to include the header file that \c uic generates from the + \c calculatorform.ui file: + + \snippet examples/uitools/multipleinheritance/calculatorform.h 0 + + The class is defined in a similar way to the one used in the + \l{The Single Inheritance Approach}{single inheritance approach}, except that + this time we inherit from \e{both} QWidget and \c{Ui::CalculatorForm}: + + \snippet examples/uitools/multipleinheritance/calculatorform.h 1 + + We inherit \c{Ui::CalculatorForm} privately to ensure that the user + interface objects are private in our subclass. We can also inherit it with + the \c public or \c protected keywords in the same way that we could have + made \c ui public or protected in the previous case. + + The constructor for the subclass performs many of the same tasks as the + constructor used in the \l{The Single Inheritance Approach} + {single inheritance} example: + + \snippet examples/uitools/multipleinheritance/calculatorform.cpp 0 + + In this case, the widgets used in the user interface can be accessed in the + same say as a widget created in code by hand. We no longer require the + \c{ui} prefix to access them. + + Subclassing using multiple inheritance gives us more direct access to the + contents of the form, is slightly cleaner than the single inheritance + approach, but does not conveniently support composition of multiple user + interfaces. + + + \section1 Run Time Form Processing + + Alternatively, forms can be processed at run time, producing dynamically- + generated user interfaces. This can be done using the QtUiTools module + that provides the QUiLoader class to handle forms created with \QD. + + + \section2 The UiTools Approach + + A resource file containing a UI file is required to process forms at + run time. Also, the application needs to be configured to use the QtUiTools + module. This is done by including the following declaration in a \c qmake + project file, ensuring that the application is compiled and linked + appropriately. + + \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 0 + + The QUiLoader class provides a form loader object to construct the user + interface. This user interface can be retrieved from any QIODevice, e.g., + a QFile object, to obtain a form stored in a project's resource file. The + QUiLoader::load() function constructs the form widget using the user + interface description contained in the file. + + The QtUiTools module classes can be included using the following directive: + + \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 1 + + The QUiLoader::load() function is invoked as shown in this code from the + \l{Text Finder Example}{Text Finder} example: + + \snippet examples/uitools/textfinder/textfinder.cpp 4 + + In a class that uses QtUiTools to build its user interface at run time, we + can locate objects in the form using qFindChild(). For example, in the + follownig code, we locate some components based on their object names and + widget types: + + \snippet examples/uitools/textfinder/textfinder.cpp 1 + + Processing forms at run-time gives the developer the freedom to change a + program's user interface, just by changing the UI file. This is useful + when customizing programs to suit various user needs, such as extra large + icons or a different colour scheme for accessibility support. + + + \section1 Automatic Connections + + The signals and slots connections defined for compile time or run time + forms can either be set up manually or automatically, using QMetaObject's + ability to make connections between signals and suitably-named slots. + + Generally, in a QDialog, if we want to process the information entered by + the user before accepting it, we need to connect the clicked() signal from + the \gui OK button to a custom slot in our dialog. We will first show an + example of the dialog in which the slot is connected by hand then compare + it with a dialog that uses automatic connection. + + + \section2 A Dialog Without Auto-Connect + + We define the dialog in the same way as before, but now include a slot in + addition to the constructor: + + \snippet doc/src/snippets/designer/noautoconnection/imagedialog.h 0 + + The \c checkValues() slot will be used to validate the values provided by + the user. + + In the dialog's constructor we set up the widgets as before, and connect + the \gui Cancel button's \l{QPushButton::clicked()}{clicked()} signal to + the dialog's reject() slot. We also disable the + \l{QPushButton::autoDefault}{autoDefault} property in both buttons to + ensure that the dialog does not interfere with the way that the line edit + handles return key events: + + \snippet doc/src/snippets/designer/noautoconnection/imagedialog.cpp 0 + \dots + \snippet doc/src/snippets/designer/noautoconnection/imagedialog.cpp 1 + + We connect the \gui OK button's \l{QPushButton::clicked()}{clicked()} + signal to the dialog's checkValues() slot which we implement as follows: + + \snippet doc/src/snippets/designer/noautoconnection/imagedialog.cpp 2 + + This custom slot does the minimum necessary to ensure that the data + entered by the user is valid - it only accepts the input if a name was + given for the image. + + \section2 Widgets and Dialogs with Auto-Connect + + Although it is easy to implement a custom slot in the dialog and connect + it in the constructor, we could instead use QMetaObject's auto-connection + facilities to connect the \gui OK button's clicked() signal to a slot in + our subclass. \c{uic} automatically generates code in the dialog's + \c setupUi() function to do this, so we only need to declare and + implement a slot with a name that follows a standard convention: + + \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 2 + + Using this convention, we can define and implement a slot that responds to + mouse clicks on the \gui OK button: + + \snippet doc/src/snippets/designer/autoconnection/imagedialog.h 0 + + Another example of automatic signal and slot connection would be the + \l{Text Finder Example}{Text Finder} with its \c{on_findButton_clicked()} + slot. + + We use QMetaObject's system to enable signal and slot connections: + + \snippet examples/uitools/textfinder/textfinder.cpp 2 + + This enables us to implement the slot, as shown below: + + \snippet examples/uitools/textfinder/textfinder.cpp 6 + \dots + \snippet examples/uitools/textfinder/textfinder.cpp 8 + + Automatic connection of signals and slots provides both a standard naming + convention and an explicit interface for widget designers to work to. By + providing source code that implements a given interface, user interface + designers can check that their designs actually work without having to + write code themselves. +*/ + + +/*! + \page designer-customizing-forms.html + \contentspage {Qt Designer Manual}{Contents} + \previouspage Using Stylesheets with Qt Designer + \nextpage Using Custom Widgets with Qt Designer + + \title Customizing Qt Designer Forms + + \image designer-form-settings.png + + When saving a form in \QD, it is stored as a UI file. Several form + settings, for example the grid settings or the margin and spacing for the + default layout, are stored along with the form's components. These settings + are used when the \l uic generates the form's C++ code. For more + information on how to use forms in your application, see the + \l{Using a Designer UI File in Your Application} section. + + + \section1 Modifying the Form Settings + + To modify the form settings, open the \gui Form menu and select \gui{Form + Settings...} + + In the forms settings dialog you can specify the \gui Author of the form. + + You can also alter the margin and spacing properties for the form's default + layout (\gui {Layout Default}). These default layout properties will be + replaced by the corresponding \gui {Layout Function}, if the function is + specified, when \c uic generates code for the form. The form settings + dialog lets you specify functions for both the margin and the spacing. + + \target LayoutFunction + \table + \row + \i \inlineimage designer-form-layoutfunction.png + \i \bold{Layout Function} + + The default layout properties will be replaced by the corresponding + \gui{Layout Function}, when \c uic generates code for the form. This is + useful when different environments requires different layouts for the same + form. + + To specify layout functions for the form's margin and spacing, check the + \gui{Layout Function} group box to enable the line edits. + \endtable + + You can also specify the form's \gui{Include Hints}; i.e., provide a list + of the header files which will then be included in the form window's + associated UI file. Header files may be local, i.e., relative to the + project's directory, \c "mywidget.h", or global, i.e. part of Qt or the + compilers standard libraries: \c <QtGui/QWidget>. + + Finally, you can specify the function used to load pixmaps into the form + window (the \gui {Pixmap Function}). +*/ + + +/*! + \page designer-using-custom-widgets.html + \contentspage {Qt Designer Manual}{Contents} + \previouspage Customizing Qt Designer Forms + \nextpage Creating Custom Widgets for Qt Designer + + \title Using Custom Widgets with Qt Designer + + \QD can display custom widgets through its extensible plugin mechanism, + allowing the range of designable widgets to be extended by the user and + third parties. This feature also allows \QD to optionally support + \l{Qt3Support}{Qt 3 compatibility widgets}. Alternatively, it is possible + to use existing widgets as placeholders for widget classes that provide + similar APIs. + + Widgets from the Qt3Support library are made available via in \QD's support + for custom widgets. + + + \section1 Handling Custom Widgets + + Although \QD supports all of the standard Qt widgets, and can be configured + to handle widgets supplied in the Qt3Support library, some specialized + widgets may not be available as standard for a number of reasons: + + \list + \i Custom widgets may not be available at the time the user interface + is being designed. + \i Custom widgets may be platform-specific, and designers may be + developing the user interface on a different platform to end users. + \i The source code for a custom widget is not available, or the user + interface designers are unable to use the widget for non-technical + reasons. + \endlist + + In the above situations, it is still possible to design forms with the aim + of using custom widgets in the application. To achieve this, we can use + the widget promotion feature of \QD. + + In all other cases, where the source code to the custom widgets is + available, we can adapt the custom widget for use with \QD. + + + \section2 Promoting Widgets + + \image designer-promoting-widgets.png + + If some forms must be designed, but certain custom widgets are unavailble + to the designer, we can substitute similar widgets to represent the missing + widgets. For example, we might represent instances of a custom push button + class, \c MyPushButton, with instances of QPushButton and promote these to + \c MyPushButton so that \l{uic.html}{uic} generates suitable code for this + missing class. + + When choosing a widget to use as a placeholder, it is useful to compare the + API of the missing widget with those of standard Qt widgets. For + specialized widgets that subclass standard classes, the obvious choice of + placeholder is the base class of the custom widget; for example, QSlider + might be used for specialized QSlider subclasses. + + For specialized widgets that do not share a common API with standard Qt + widgets, it is worth considering adapting a custom widget for use in \QD. + If this is not possible then QWidget is the obvious choice for a + placeholder widget since it is the lowest common denominator for all + widgets. + + To add a placeholder, select an object of a suitable base class and choose + \gui{Promote to ...} from the form's context menu. After entering the class + name and header file in the lower part of the dialog, choose \gui{Add}. The + placeholder class will now appear along with the base class in the upper + list. Click the \gui{Promote} button to accept this choice. + + Now, when the form's context menu is opened over objects of the base class, + the placeholder class will appear in the \gui{Promote to} submenu, allowing + for convenient promotion of objects to that class. + + A promoted widget can be reverted to its base class by choosing + \gui{Demote to} from the form's context menu. + + + \section2 User Defined Custom Widgets + + \image worldtimeclockplugin-example.png + + Custom widgets can be adapted for use with \QD, giving designers the + opportunity to configure the user interface using the actual widgets that + will be used in an application rather than placeholder widgets. The process + of creating a custom widget plugin is described in the + \l{Creating Custom Widgets for Qt Designer} chapter of this manual. + + To use a plugin created in this way, it is necessary to ensure that the + plugin is located on a path that \QD searches for plugins. Generally, + plugins stored in \c{$QTDIR/plugins/designer} will be loaded when \QD + starts. Further information on building and installing plugins can be found + \l{Creating Custom Widgets for Qt Designer#BuildingandInstallingthePlugin} + {here}. You can also refer to the \l{How to Create Qt Plugins} + {Plugins HOWTO} document for information about creating plugins. +*/ + + +/*! + \page designer-creating-custom-widgets.html + \previouspage Using Custom Widgets with Qt Designer + \contentspage {Qt Designer Manual}{Contents} + \nextpage Creating Custom Widget Extensions + + \title Creating Custom Widgets for Qt Designer + + \QD's plugin-based architecture allows user-defined and third party custom + widgets to be edited just like you do with standard Qt widgets. All of the + custom widget's features are made available to \QD, including widget + properties, signals, and slots. Since \QD uses real widgets during the form + design process, custom widgets will appear the same as they do when + previewed. + + \image worldtimeclockplugin-example.png + + The \l QtDesigner module provides you with the ability to create custom + widgets in \QD. + + + \section1 Getting Started + + To integrate a custom widget with \QD, you require a suitable description + for the widget and an appropriate \c{.pro} file. + + + \section2 Providing an Interface Description + + To inform \QD about the type of widget you want to provide, create a + subclass of QDesignerCustomWidgetInterface that describes the various + properties your widget exposes. Most of these are supplied by functions + that are pure virtual in the base class, because only the author of the + plugin can provide this information. + + \table + \header + \o Function + \o Description of the return value + \row + \o \c name() + \o The name of the class that provides the widget. + \row + \o \c group() + \o The group in \QD's widget box that the widget belongs to. + \row + \o \c toolTip() + \o A short description to help users identify the widget in \QD. + \row + \o \c whatsThis() + \o A longer description of the widget for users of \QD. + \row + \o \c includeFile() + \o The header file that must be included in applications that use + this widget. This information is stored in UI files and will + be used by \c uic to create a suitable \c{#includes} statement + in the code it generates for the form containing the custom + widget. + \row + \o \c icon() + \o An icon that can be used to represent the widget in \QD's + widget box. + \row + \o \c isContainer() + \o True if the widget will be used to hold child widgets; + false otherwise. + \row + \o \c createWidget() + \o A QWidget pointer to an instance of the custom widget, + constructed with the parent supplied. + \note createWidget() is a factory function responsible for + creating the widget only. The custom widget's properties will + not be available until load() returns. + \row + \o \c domXml() + \o A description of the widget's properties, such as its object + name, size hint, and other standard QWidget properties. + \row + \o \c codeTemplate() + \o This function is reserved for future use by \QD. + \endtable + + Two other virtual functions can also be reimplemented: + + \table + \row + \o \c initialize() + \o Sets up extensions and other features for custom widgets. Custom + container extensions (see QDesignerContainerExtension) and task + menu extensions (see QDesignerTaskMenuExtension) should be set + up in this function. + \row + \o \c isInitialized() + \o Returns true if the widget has been initialized; returns false + otherwise. Reimplementations usually check whether the + \c initialize() function has been called and return the result + of this test. + \endtable + + + \section2 Notes on the \c{domXml()} Function + + The \c{domXml()} function returns a UI file snippet that is used by + \QD's widget factory to create a custom widget and its applicable + properties. + + Since Qt 4.4, \QD's widget box allows for a complete UI file to + describe \bold one custom widget. The UI file can be loaded using the + \c{<ui>} tag. Specifying the <ui> tag allows for adding the <customwidget> + element that contains additional information for custom widgets. The + \c{<widget>} tag is sufficient if no additional information is required + + If the custom widget does not provide a reasonable size hint, it is + necessary to specify a default geometry in the string returned by the + \c domXml() function in your subclass. For example, the + \c AnalogClockPlugin provided by the \l{designer/customwidgetplugin} + {Custom Widget Plugin} example, defines a default widgetgeometry in the + following way: + + \dots + \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 11 + \dots + + An additional feature of the \c domXml() function is that, if it returns + an empty string, the widget will not be installed in \QD's widget box. + However, it can still be used by other widgets in the form. This feature + is used to hide widgets that should not be explicitly created by the user, + but are required by other widgets. + + + A complete custom widget specification looks like: + + \code +<ui language="c++"> displayname="MyWidget"> + <widget class="widgets::MyWidget" name="mywidget"/> + <customwidgets> + <customwidget> + <class>widgets::MyWidget</class> + <addpagemethod>addPage</addpagemethod> + <propertyspecifications> + <stringpropertyspecification name="fileName" notr="true" type="singleline" + <stringpropertyspecification name="text" type="richtext" + </propertyspecifications> + </customwidget> + </customwidgets> +</ui> + \endcode + + Attributes of the \c{<ui>} tag: + \table + \header + \o Attribute + \o Presence + \o Values + \o Comment + \row + \o \c{language} + \o optional + \o "c++", "jambi" + \o This attribute specifies the language the custom widget is intended for. + It is mainly there to prevent C++-plugins from appearing in Qt Jambi. + \row + \o \c{displayname} + \o optional + \o Class name + \o The value of the attribute appears in the Widget box and can be used to + strip away namespaces. + \endtable + + The \c{<addpagemethod>} tag tells \QD and \l uic which method should be used to + add pages to a container widget. This applies to container widgets that require + calling a particular method to add a child rather than adding the child by passing + the parent. In particular, this is relevant for containers that are not a + a subclass of the containers provided in \QD, but are based on the notion + of \e{Current Page}. In addition, you need to provide a container extension + for them. + + The \c{<propertyspecifications>} element can contain a list of property meta information. + Currently, properties of type string are supported. For these properties, the + \c{<stringpropertyspecification>} tag can be used. This tag has the following attributes: + + + \table + \header + \o Attribute + \o Presence + \o Values + \o Comment + \row + \o \c{name} + \o required + \o Name of the property + \row + \o \c{type} + \o required + \o See below table + \o The value of the attribute determines how the property editor will handle them. + \row + \o \c{notr} + \o optional + \o "true", "false" + \o If the attribute is "true", the value is not meant to be translated. + \endtable + + Values of the \c{type} attribute of the string property: + + \table + \header + \o Value + \o Type + \row + \o \c{"richtext"} + \o Rich text. + \row + \o \c{"multiline"} + \o Multi-line plain text. + \row + \o \c{"singleline"} + \o Single-line plain text. + \row + \o \c{"stylesheet"} + \o A CSS-style sheet. + \row + \o \c{"objectname"} + \o An object name (restricted set of valid characters). + \row + \o \c{"url"} + \o URL, file name. + \endtable + + \section1 Plugin Requirements + + In order for plugins to work correctly on all platforms, you need to ensure + that they export the symbols needed by \QD. + + First of all, the plugin class must be exported in order for the plugin to + be loaded by \QD. Use the Q_EXPORT_PLUGIN2() macro to do this. Also, the + QDESIGNER_WIDGET_EXPORT macro must be used to define each custom widget class + within a plugin, that \QD will instantiate. + + + \section1 Creating Well Behaved Widgets + + Some custom widgets have special user interface features that may make them + behave differently to many of the standard widgets found in \QD. + Specifically, if a custom widget grabs the keyboard as a result of a call + to QWidget::grabKeyboard(), the operation of \QD will be affected. + + To give custom widgets special behavior in \QD, provide an implementation + of the initialize() function to configure the widget construction process + for \QD specific behavior. This function will be called for the first time + before any calls to createWidget() and could perhaps set an internal flag + that can be tested later when \QD calls the plugin's createWidget() + function. + + + \target BuildingandInstallingthePlugin + \section1 Building and Installing the Plugin + + \section2 A Simple Plugin + + The \l{Custom Widget Plugin Example} demonstrates a simple \QD plugin. + + The \c{.pro} file for a plugin must specify the headers and sources for + both the custom widget and the plugin interface. Typically, this file only + has to specify that the plugin's project is to be built as a library, but + with specific plugin support for \QD. This is done with the following + declarations: + + \snippet examples/designer/customwidgetplugin/customwidgetplugin.pro 1 + + If Qt is configured to build in both debug and release modes, \QD will be + built in release mode. When this occurs, it is necessary to ensure that + plugins are also built in release mode. To do this, include the following + declaration in the plugin's \c{.pro} file: + + \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 3 + + If plugins are built in a mode that is incompatible with \QD, they will + not be loaded and installed. For more information about plugins, see the + \l{plugins-howto.html}{Plugins HOWTO} document. + + It is also necessary to ensure that the plugin is installed together with + other \QD widget plugins: + + \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 4 + + The \c $[QT_INSTALL_PLUGINS] variable is a placeholder to the location of + the installed Qt plugins. You can configure \QD to look for plugins in + other locations by setting the \c QT_PLUGIN_PATH environment variable + before running the application. + + \note \QD will look for a \c designer subdirectory in each path supplied. + + See QCoreApplication::libraryPaths() for more information about customizing + paths for libraries and plugins with Qt applications. + + \section2 Splitting up the Plugin + + In a real world scenario, you do not want to have dependencies of the + application making use of the custom widgets to the \QD headers and + libraries as introduced by the simple approach explained above. + + There are two ways to resolve this: + + \list + \i Create a \c{.pri} file that contains the headers sources and sources + of the custom widget: + + \code + INCLUDEPATH += $$PWD + HEADERS += $$PWD/analogclock.h + SOURCES += $$PWD/analogclock.cpp + \endcode + + This file would then be included by the \c{.pro} file of the plugin and + the application: + + \code + include(customwidget.pri) + \endcode + + Running \c{qmake -Wall} on the \c{.pro} files causes a warning to be + printed if an included \c{.pri} file cannot be found. + + \i Create a standalone shared library containing the custom widgets only + as described in + \l{sharedlibrary.html}{Creating Shared Libraries}. + + This library would then be used by the application as well as by the + \QD plugin. Care must be taken to ensure that the plugin can locate + the library at run-time. + \endlist + + \section1 Related Examples + + For more information on using custom widgets in \QD, refer to the + \l{designer/customwidgetplugin}{Custom Widget Plugin} and + \l{designer/worldtimeclockplugin}{World Time Clock Plugin} examples for more + information about using custom widgets in \QD. Also, you can use the + QDesignerCustomWidgetCollectionInterface class to combine several custom + widgets into a single library. +*/ + + +/*! + \page designer-creating-custom-widgets-extensions.html + \previouspage Creating Custom Widgets for Qt Designer + \nextpage Qt Designer's UI File Format + \contentspage {Qt Designer Manual}{Contents} + + \title Creating Custom Widget Extensions + + Once you have a custom widget plugin for \QD, you can provide it with the + expected behavior and functionality within \QD's workspace, using custom + widget extensions. + + + \section1 Extension Types + + There are several available types of extensions in \QD. You can use all of + these extensions in the same pattern, only replacing the respective + extension base class. + + QDesignerContainerExtension is necessary when implementing a custom + multi-page container. + + \table + \row + \i \inlineimage designer-manual-taskmenuextension.png + \i \bold{QDesignerTaskMenuExtension} + + QDesignerTaskMenuExtension is useful for custom widgets. It provides an + extension that allows you to add custom menu entries to \QD's task + menu. + + The \l{designer/taskmenuextension}{Task Menu Extension} example + illustrates how to use this class. + + \row + \i \inlineimage designer-manual-containerextension.png + \i \bold{QDesignerContainerExtension} + + QDesignerContainerExtension is necessary when implementing a custom + multi-page container. It provides an extension that allows you to add + and delete pages for a multi-page container plugin in \QD. + + The \l{designer/containerextension}{Container Extension} example + further explains how to use this class. + + \note It is not possible to add custom per-page properties for some + widgets (e.g., QTabWidget) due to the way they are implemented. + \endtable + + \table + \row + \i \inlineimage designer-manual-membersheetextension.png + \i \bold{QDesignerMemberSheetExtension} + + The QDesignerMemberSheetExtension class allows you to manipulate a + widget's member functions displayed when connecting signals and slots. + + \row + \i \inlineimage designer-manual-propertysheetextension.png + \i \bold{QDesignerPropertySheetExtension, + QDesignerDynamicPropertySheetExtension} + + These extension classes allow you to control how a widget's properties + are displayed in \QD's property editor. + \endtable + +\omit + \row + \o + \o \bold {QDesignerScriptExtension} + + The QDesignerScriptExtension class allows you to define script + snippets that are executed when a form is loaded. The extension + is primarily intended to be used to set up the internal states + of custom widgets. + \endtable +\endomit + + + \QD uses the QDesignerPropertySheetExtension and the + QDesignerMemberSheetExtension classes to feed its property and signal and + slot editors. Whenever a widget is selected in its workspace, \QD will + query for the widget's property sheet extension; likewise, whenever a + connection between two widgets is requested, \QD will query for the + widgets' member sheet extensions. + + \warning All widgets have default property and member sheets. If you + implement custom property sheet or member sheet extensions, your custom + extensions will override the default sheets. + + + \section1 Creating an Extension + + To create an extension you must inherit both QObject and the appropriate + base class, and reimplement its functions. Since we are implementing an + interface, we must ensure that it is made known to the meta object system + using the Q_INTERFACES() macro in the extension class's definition. For + example: + + \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 7 + + This enables \QD to use the qobject_cast() function to query for supported + interfaces using a QObject pointer only. + + + \section1 Exposing an Extension to Qt Designer + + In \QD the extensions are not created until they are required. For this + reason, when implementing extensions, you must subclass QExtensionFactory + to create a class that is able to make instances of your extensions. Also, + you must register your factory with \QD's extension manager; the extension + manager handles the construction of extensions. + + When an extension is requested, \QD's extension manager will run through + its registered factories calling QExtensionFactory::createExtension() for + each of them until it finds one that is able to create the requested + extension for the selected widget. This factory will then make an instance + of the extension. + + \image qtdesignerextensions.png + + + \section2 Creating an Extension Factory + + The QExtensionFactory class provides a standard extension factory, but it + can also be used as an interface for custom extension factories. + + The purpose is to reimplement the QExtensionFactory::createExtension() + function, making it able to create your extension, such as a + \l{designer/containerextension}{MultiPageWidget} container extension. + + You can either create a new QExtensionFactory and reimplement the + QExtensionFactory::createExtension() function: + + \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 8 + + or you can use an existing factory, expanding the + QExtensionFactory::createExtension() function to enable the factory to + create your custom extension as well: + + \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 9 + + + \section2 Accessing Qt Designer's Extension Manager + + When implementing a custom widget plugin, you must subclass the + QDesignerCustomWidgetInterface to expose your plugin to \QD. This is + covered in more detail in the + \l{Creating Custom Widgets for Qt Designer} section. The registration of + an extension factory is typically made in the + QDesignerCustomWidgetInterface::initialize() function: + + \snippet doc/src/snippets/code/doc_src_designer-manual.qdoc 10 + + The \c formEditor parameter in the + QDesignerCustomWidgetInterface::initialize() function is a pointer to \QD's + current QDesignerFormEditorInterface object. You must use the + QDesignerFormEditorInterface::extensionManager() function to retrieve an + interface to \QD's extension manager. Then you use the + QExtensionManager::registerExtensions() function to register your custom + extension factory. + + + \section1 Related Examples + + For more information on creating custom widget extensions in \QD, refer to + the \l{designer/taskmenuextension}{Task Menu Extension} and + \l{designer/containerextension}{Container Extension} examples. +*/ + + +/*! + \page designer-ui-file-format.html + \previouspage Creating Custom Widget Extensions + \contentspage {Qt Designer Manual}{Contents} + + \title Qt Designer's UI File Format + + The \c UI file format used by \QD is described by the + \l{http://www.w3.org/XML/Schema}{XML schema} presented below, + which we include for your convenience. Be aware that the format + may change in future Qt releases. + + \quotefile tools/designer/data/ui4.xsd +*/ + + +/*! + \page designer-recursive-shadow-casting.html + \title Implementation of the Recursive Shadow Casting Algorithm in Qt Designer + \contentspage {Qt Designer Manual}{Contents} + + \ingroup licensing + \brief License information for contributions to specific parts of the Qt + Designer source code. + + \legalese + Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). \BR + Copyright (C) 2005 Bjoern Bergstroem + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, modify, market, reproduce, + grant sublicenses and distribute subject to the following conditions: + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. These + files are provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE + WARRANTY OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR + PURPOSE. + \endlegalese +*/ diff --git a/doc/src/development/developing-on-mac.qdoc b/doc/src/development/developing-on-mac.qdoc new file mode 100644 index 0000000..dee6d4d --- /dev/null +++ b/doc/src/development/developing-on-mac.qdoc @@ -0,0 +1,269 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page developing-on-mac.html + \title Developing Qt Applications on Mac OS X + \brief A overview of items to be aware of when developing Qt applications + on Mac OS X + \ingroup platform-specific + + \tableofcontents + + Mac OS X is a UNIX platform and behaves similar to other Unix-like + platforms. The main difference is X11 is not used as the primary windowing + system. Instead, Mac OS X uses its own native windowing system that is + accessible through the Carbon and Cocoa APIs. Application development on + Mac OS X is done using Xcode Tools, an optional install included on every + Mac with updates available from \l {http://developer.apple.com}{Apple's + developer website}. Xcode Tools includes Apple-modified versions of the GCC + compiler. + + + \section1 What Versions of Mac OS X are Supported? + + As of Qt 4.6, Qt supports Mac OS X versions 10.4 and up. It is usually in + the best interest of the developer and user to be running the latest + updates to any version. We test internally against Mac OS X 10.4.11 as well + as the updated release of Mac OS X 10.5 and Mac OS X 10.6. + + \section2 Carbon or Cocoa? + + Historically, Qt has used the Carbon toolkit, which supports 32-bit + applications on Mac OS X 10.4 and up. Qt 4.5 and up has support for the Cocoa + toolkit, which requires 10.5 and provides 64-bit support. + + This detail is typically not important to Qt application developers. Qt is + cross-platform across Carbon and Cocoa, and Qt applications behave + the same way when configured for either one. Eventually, the Carbon + version will be discontinued. This is something to keep in mind when you + consider writing code directly against native APIs. + + The current binary for Qt is built in two flavors, 32-bit Carbon and full + universal Cocoa (32-bit and 64-bit). If you want a different setup for + Qt will use, you must build from scratch. Carbon or Cocoa is chosen when + configuring the package for building. The configure process selects Carbon + by default, to specify Cocoa use the \c{-cocoa} flag. configure for a + 64-bit architecture using one of the \c{-arch} flags (see \l{universal + binaries}{Universal Binaries}). + + Currently, Apple's default GCC compiler is used by default (GCC 4.0.1 on + 10.4 and 10.5, GCC 4.2 on 10.6). You can specify alternate compilers + though. For example, on Mac OS X 10.5, Apple's GCC 4.2 is also available + and selectable with the configure flag: \c{-platform macx-g++42}. LLVM-GCC + support is available by passing in the \c{-platform macx-llvm} flag. GCC + 3.x will \e not work. Though they may work, We do not support custom-built + GCC's. + + The following table summarizes the different versions of Mac OS X and what + capabilities are used by Qt. + + \table + \header + \o Mac OS X Version + \o Cat Name + \o Native API Used by Qt + \o Bits available to address memory + \o CPU Architecture Supported + \o Development Platform + \row + \o 10.4 + \o Tiger + \o Carbon + \o 32 + \o PPC/Intel + \o Yes + \row + \o 10.5 + \o Leopard + \o Carbon + \o 32 + \o PPC/Intel + \o Yes + \row + \o 10.5 + \o Leopard + \o Cocoa + \o 32/64 + \o PPC/Intel + \o Yes + \row + \o 10.6 + \o Snow Leopard + \o Carbon + \o 32 + \o PPC/Intel + \o Yes + \row + \o 10.6 + \o Snow Leopard + \o Cocoa + \o 32/64 + \o PPC/Intel + \o Yes + \endtable + + \section2 Which One Should I Use? + + Carbon and Cocoa both have their advantages and disadvantages. Probably the + easiest way to determine is to look at the version of Mac OS X you are + targetting. If you are starting a new application and can target 10.5 and + up, then please consider Cocoa only. If you have an existing application or + need to target earlier versions of the operating system and do not need + access to 64-bit or newer Apple technologies, then Carbon is a good fit. If + your needs fall in between, you can go with a 64-bit Cocoa and 32-bit + Carbon universal application with the appropriate checks in your code to + choose the right path based on where you are running the application. + + For Mac OS X 10.6, Apple has started recommending developers to build their + applications 64-bit. The main reason is that there is a small speed + increase due to the extra registers on Intel CPU's, all their machine + offerings have been 64-bit since 2007, and there is a cost for reading all + the 32-bit libraries into memory if everything else is 64-bit. If you want + to follow this advice, there is only one choice, 64-bit Cocoa. + + \target universal binaries + \section1 Universal Binaries + + In 2006, Apple begin transitioning from PowerPC (PPC) to Intel (x86) + systems. Both architectures are supported by Qt. The release of Mac OS X + 10.5 in October 2007 added the possibility of writing and deploying 64-bit + GUI applications. Qt 4.5 and up supports both the 32-bit (PPC and x86) and + 64-bit (PPC64 and x86-64) versions of PowerPC and Intel-based systems. + + Universal binaries are used to bundle binaries for more than one + architecture into a single package, simplifying deployment and + distribution. When running an application the operating system will select + the most appropriate architecture. Universal binaries support the following + architectures; they can be added to the build at configure time using the + \c{-arch} arguments: + + \table + \header + \o Architecture + \o Flag + \row + \o Intel, 32-bit + \o \c{-arch x86} + \row + \o Intel, 64-bit + \o \c{-arch x86_64} + \row + \o PPC, 32-bit + \o \c{-arch ppc} + \row + \o PPC, 64-bit + \o \c{-arch ppc64} + \endtable + + If there are no \c{-arch} flags specified, configure builds for the 32-bit + architecture, if you are currently on one. Universal binaries were initially + used to simplify the PPC to Intel migration. You can use \c{-universal} to + build for both the 32-bit Intel and PPC architectures. + + \note The \c{-arch} flags at configure time only affect how Qt is built. + Applications are by default built for the 32-bit architecture you are + currently on. To build a universal binary, add the architectures to the + CONFIG variable in the .pro file: + + \code + CONFIG += x86 ppc x86_64 ppc64 + \endcode + + + \section1 Day-to-Day Application Development on OS X + + On the command-line, applications can be built using \c qmake and \c make. + Optionally, \c qmake can generate project files for Xcode with + \c{-spec macx-xcode}. If you are using the binary package, \c qmake + generates Xcode projects by default; use \c{-spec macx-gcc} to generate + makefiles. + + The result of the build process is an application bundle, which is a + directory structure that contains the actual application executable. The + application can be launched by double-clicking it in Finder, or by + referring directly to its executable from the command line, i. e. + \c{myApp.app/Contents/MacOS/myApp}. + + If you wish to have a command-line tool that does not use the GUI (e.g., + \c moc, \c uic or \c ls), you can tell \c qmake not to execute the bundle + creating steps by removing it from the \c{CONFIG} in your \c{.pro} file: + + \code + CONFIG -= app_bundle + \endcode + + + \section1 Deployment - "Compile once, deploy everywhere" + + In general, Qt supports building on one Mac OS X version and deploying on + all others, both forward and backwards. You can build on 10.4 Tiger and run + the same binary on 10.5 and up. + + Some restrictions apply: + + \list + \o Some functions and optimization paths that exist in later versions + of Mac OS X will not be available if you build on an earlier + version of Mac OS X. + \o The CPU architecture should match. + \o Cocoa support is only available for Mac OS X 10.5 and up. + \endlist + + Universal binaries can be used to provide a smorgasbord of configurations + catering to all possible architectures. + + Mac applications are typically deployed as self-contained application + bundles. The application bundle contains the application executable as well + as dependencies such as the Qt libraries, plugins, translations and other + resources you may need. Third party libraries like Qt are normally not + installed system-wide; each application provides its own copy. + + The most common way to distribute applications is to provide a compressed + disk image (.dmg file) that the user can mount in Finder. The Mac + deployment tool (macdeployqt) can be used to create the self-contained bundles, and + optionally also create a .dmg archive. See the + \l{Deploying an Application on Mac OS X}{Mac deployment guide} for more + information about deployment. It is also possible to use an installer + wizard. More information on this option can be found in + \l{http://developer.apple.com/mac/}{Apple's documentation}. +*/ + diff --git a/doc/src/development/developing-with-qt.qdoc b/doc/src/development/developing-with-qt.qdoc new file mode 100644 index 0000000..9fa2242 --- /dev/null +++ b/doc/src/development/developing-with-qt.qdoc @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page developing-with-qt.html + \title Cross Platform Development with Qt + + Qt is provided with a set of build tools to help developers automate + the process of building and installing Qt applications. + + \table 100% + \header \o Development \o Cross-Platform Issues \o Specific Tools + \row + \o + \list + \o \l {Debugging Techniques} + \o \l {Qt's Tools} + \o \l {The Qt Resource System} + \o \l {Using Precompiled Headers} + \endlist + \o + \list + \o \l {Cross Compiling Qt for Embedded Linux Applications} + \o \l {Deploying Qt Applications} + \o \l {Installation}{Installing Qt} + \o \l {Window System Specific Notes} + \endlist + \o + \list + \o \l lupdate and \l lrelease + \o \l {moc}{Meta-Object Compiler (moc)} + \o \l {User Interface Compiler (uic)} + \o \l {Resource Compiler (rcc)} + \endlist + \endtable +*/ diff --git a/doc/src/development/moc.qdoc b/doc/src/development/moc.qdoc new file mode 100644 index 0000000..747c68d --- /dev/null +++ b/doc/src/development/moc.qdoc @@ -0,0 +1,335 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page moc.html + \title Using the Meta-Object Compiler (moc) + \ingroup qttools + \keyword moc + + The Meta-Object Compiler, \c moc, is the program that handles + \l{Meta-Object System}{Qt's C++ extensions}. + + The \c moc tool reads a C++ header file. If it finds one or more + class declarations that contain the Q_OBJECT macro, it + produces a C++ source file containing the meta-object code for + those classes. Among other things, meta-object code is required + for the signals and slots mechanism, the run-time type information, + and the dynamic property system. + + The C++ source file generated by \c moc must be compiled and + linked with the implementation of the class. + + If you use \l qmake to create your makefiles, build rules will be + included that call the moc when required, so you will not need to + use the moc directly. For more background information on \c moc, + see \l{Why Doesn't Qt Use Templates for Signals and Slots?} + + \section1 Usage + + \c moc is typically used with an input file containing class + declarations like this: + + \snippet doc/src/snippets/moc/myclass1.h 0 + + In addition to the signals and slots shown above, \c moc also + implements object properties as in the next example. The + Q_PROPERTY() macro declares an object property, while + Q_ENUMS() declares a list of enumeration types within the class + to be usable inside the \l{Qt's Property System}{property + system}. + + In the following example, we declare a property of the + enumeration type \c Priority that is also called \c priority and + has a get function \c priority() and a set function \c + setPriority(). + + \snippet doc/src/snippets/moc/myclass2.h 0 + + The Q_FLAGS() macro declares enums that are to be used + as flags, i.e. OR'd together. Another macro, Q_CLASSINFO(), + allows you to attach additional name/value pairs to the class's + meta-object: + + \snippet doc/src/snippets/moc/myclass3.h 0 + + The output produced by \c moc must be compiled and linked, just + like the other C++ code in your program; otherwise, the build + will fail in the final link phase. If you use \c qmake, this is + done automatically. Whenever \c qmake is run, it parses the + project's header files and generates make rules to invoke \c moc + for those files that contain a Q_OBJECT macro. + + If the class declaration is found in the file \c myclass.h, the + moc output should be put in a file called \c moc_myclass.cpp. + This file should then be compiled as usual, resulting in an + object file, e.g., \c moc_myclass.obj on Windows. This object + should then be included in the list of object files that are + linked together in the final building phase of the program. + + \section1 Writing Make Rules for Invoking \c moc + + For anything but the simplest test programs, it is recommended + that you automate running the \c{moc}. By adding some rules to + your program's makefile, \c make can take care of running moc + when necessary and handling the moc output. + + We recommend using the \l qmake makefile generation tool for + building your makefiles. This tool generates a makefile that does + all the necessary \c moc handling. + + If you want to create your makefiles yourself, here are some tips + on how to include moc handling. + + For Q_OBJECT class declarations in header files, here is a + useful makefile rule if you only use GNU make: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 0 + + If you want to write portably, you can use individual rules of + the following form: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 1 + + You must also remember to add \c moc_foo.cpp to your \c SOURCES + (substitute your favorite name) variable and \c moc_foo.o or \c + moc_foo.obj to your \c OBJECTS variable. + + Both examples assume that \c $(DEFINES) and \c $(INCPATH) expand + to the define and include path options that are passed to the C++ + compiler. These are required by \c moc to preprocess the source + files. + + While we prefer to name our C++ source files \c .cpp, you can use + any other extension, such as \c .C, \c .cc, \c .CC, \c .cxx, and + \c .c++, if you prefer. + + For Q_OBJECT class declarations in implementation (\c .cpp) + files, we suggest a makefile rule like this: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 2 + + This guarantees that make will run the moc before it compiles + \c foo.cpp. You can then put + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 3 + + at the end of \c foo.cpp, where all the classes declared in that + file are fully known. + + \section1 Command-Line Options + + Here are the command-line options supported by the moc: + + \table + \header \o Option \o Description + + \row + \o \c{-o<file>} + \o Write output to \c <file> rather than to standard output. + + \row + \o \c{-f[<file>]} + \o Force the generation of an \c #include statement in the + output. This is the default for header files whose extension + starts with \c H or \c h. This option is useful if you have + header files that do not follow the standard naming conventions. + The \c <file> part is optional. + + \row + \o \c -i + \o Do not generate an \c #include statement in the output. + This may be used to run the moc on on a C++ file containing one or + more class declarations. You should then \c #include the meta-object + code in the \c .cpp file. + + \row + \o \c -nw + \o Do not generate any warnings. (Not recommended.) + + \row + \o \c {-p<path>} + \o Makes the moc prepend \c {<path>/} to the file name in the + generated \c #include statement. + + \row + \o \c {-I<dir>} + \o Add dir to the include path for header files. + + \row + \o \c{-E} + \o Preprocess only; do not generate meta-object code. + + \row + \o \c {-D<macro>[=<def>]} + \o Define macro, with optional definition. + + \row + \o \c{-U<macro>} + \o Undefine macro. + + \row + \o \c{@<file>} + \o Read additional command-line options from \c{<file>}. + Each line of the file is treated as a single option. Empty lines + are ignored. Note that this option is not supported within the + options file itself (i.e. an options file can't "include" another + file). + + \row + \o \c{-h} + \o Display the usage and the list of options. + + \row + \o \c {-v} + \o Display \c{moc}'s version number. + + \row + \o \c{-Fdir} + + \o Mac OS X. Add the framework directory \c{dir} to the head of + the list of directories to be searched for header files. These + directories are interleaved with those specified by -I options + and are scanned in a left-to-right order (see the manpage for + gcc). Normally, use -F /Library/Frameworks/ + + \endtable + + You can explicitly tell the moc not to parse parts of a header + file. \c moc defines the preprocessor symbol \c Q_MOC_RUN. Any + code surrounded by + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 4 + + is skipped by the \c moc. + + \section1 Diagnostics + + \c moc will warn you about a number of dangerous or illegal + constructs in the Q_OBJECT class declarations. + + If you get linkage errors in the final building phase of your + program, saying that \c YourClass::className() is undefined or + that \c YourClass lacks a vtable, something has been done wrong. + Most often, you have forgotten to compile or \c #include the + moc-generated C++ code, or (in the former case) include that + object file in the link command. If you use \c qmake, try + rerunning it to update your makefile. This should do the trick. + + \section1 Limitations + + \c moc does not handle all of C++. The main problem is that class + templates cannot have signals or slots. Here is an example: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 5 + + Another limitation is that moc does not expand macros, so you + for example cannot use a macro to declare a signal/slot + or use one to define a base class for a QObject. + + Less importantly, the following constructs are illegal. All of + them have alternatives which we think are usually better, so + removing these limitations is not a high priority for us. + + \section2 Multiple Inheritance Requires QObject to Be First + + If you are using multiple inheritance, \c moc assumes that the + first inherited class is a subclass of QObject. Also, be sure + that only the first inherited class is a QObject. + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 6 + + Virtual inheritance with QObject is \e not supported. + + \section2 Function Pointers Cannot Be Signal or Slot Parameters + + In most cases where you would consider using function pointers as + signal or slot parameters, we think inheritance is a better + alternative. Here is an example of illegal syntax: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 7 + + You can work around this restriction like this: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 8 + + It may sometimes be even better to replace the function pointer + with inheritance and virtual functions. + + \section2 Enums and Typedefs Must Be Fully Qualified for Signal and Slot Parameters + + When checking the signatures of its arguments, QObject::connect() + compares the data types literally. Thus, + \l{Qt::Alignment}{Alignment} and \l{Qt::Alignment} are treated as + two distinct types. To work around this limitation, make sure to + fully qualify the data types when declaring signals and slots, + and when establishing connections. For example: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 9 + + \section2 Type Macros Cannot Be Used for Signal and Slot Parameters + + Since \c moc doesn't expand \c{#define}s, type macros that take + an argument will not work in signals and slots. Here is an + illegal example: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 10 + + A macro without parameters will work. + + \section2 Nested Classes Cannot Have Signals or Slots + + Here's an example of the offending construct: + + \snippet doc/src/snippets/code/doc_src_moc.qdoc 11 + + \section2 Signal/Slot return types cannot be references + + Signals and slots can have return types, but signals or slots returning references + will be treated as returning void. + + \section2 Only Signals and Slots May Appear in the \c signals and \c slots Sections of a Class + + \c moc will complain if you try to put other constructs in the \c + signals or \c slots sections of a class than signals and slots. + + \sa {Meta-Object System}, {Signals and Slots}, {Qt's Property System} +*/ diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc new file mode 100644 index 0000000..181ba6a --- /dev/null +++ b/doc/src/development/qmake-manual.qdoc @@ -0,0 +1,4320 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qmake-manual.html + \title qmake Manual + \startpage {index.html}{Qt Reference Documentation} + \nextpage qmake Tutorial + + \ingroup qttools + \keyword qmake + + \c qmake is a tool that helps simplify the build + process for development project across different platforms. \c qmake + automates the generation of Makefiles so that only a few lines of + information are needed to create each Makefile. \c qmake can be used for + any software project, whether it is written in Qt or not. + + \c qmake generates a Makefile based on the information in a project + file. Project files are created by the developer, and are usually + simple, but more sophisticated project files can be created for + complex projects. + \c qmake contains additional features to support development with Qt, + automatically including build rules for \l{moc.html}{moc} + and \l{uic.html}{uic}. + \c qmake can also generate projects for Microsoft Visual studio + without requiring the developer to change the project file. + + \section1 Getting Started + + The \l{qmake Tutorial} and guide to \l{qmake Common Projects} provide overviews + that aim to help new users get started with \c qmake. + + \list + \o \l{qmake Tutorial} + \tableofcontents{1 qmake Tutorial} + \endlist + + \list + \o \l{qmake Common Projects} + \tableofcontents{1 qmake Common Projects} + \endlist + + \section1 Table of Contents + + \list + \o \l{Using qmake} + \tableofcontents{1 Using qmake} + \o \l{qmake Project Files} + \tableofcontents{1 qmake Project Files} + \o \l{Running qmake} + \tableofcontents{1 Running qmake} + \o \l{qmake Platform Notes} + \tableofcontents{1 qmake Platform Notes} + \o \l{qmake Advanced Usage} + \tableofcontents{1 qmake Advanced Usage} + \o \l{Using Precompiled Headers} + \tableofcontents{1 Using Precompiled Headers} + \o \l{qmake Reference} + \tableofcontents{1 qmake Reference} + \o \l{qmake Variable Reference} + \tableofcontents{1 qmake Variable Reference} + \o \l{qmake Function Reference} + \tableofcontents{1 qmake Function Reference} + \o \l{Configuring qmake's Environment} + \tableofcontents{1 Configuring qmake's Environment} + \endlist +*/ + +/*! + \page qmake-using.html + \title Using qmake + \contentspage {qmake Manual}{Contents} + \previouspage qmake Manual + \nextpage qmake Project Files + + \c qmake provides a project-oriented system for managing the build + process for applications, libraries, and other components. This + approach gives developers control over the source files used, and + allows each of the steps in the process to be described concisely, + typically within a single file. \c qmake expands the information in + each project file to a Makefile that executes the necessary commands + for compiling and linking. + + In this document, we provide a basic introduction to project files, + describe some of the main features of \c qmake, and show how to use + \c qmake on the command line. + + \section1 Describing a Project + + Projects are described by the contents of project (\c .pro) files. + The information within these is used by \c qmake to generate a Makefile + containing all the commands that are needed to build each project. + Project files typically contain a list of source and header files, + general configuration information, and any application-specific details, + such as a list of extra libraries to link against, or a list of extra + include paths to use. + + Project files can contain a number of different elements, including + comments, variable declarations, built-in functions, and some simple + control structures. In most simple projects, it is only necessary + to declare the source and header files that are used to build the + project with some basic configuration options. + + Complete examples of project files can be found in the + \l{qmake Tutorial}. + An introduction to project files can be found in the + \l{qmake Project Files} chapter, and a more detailed description is + available in the \l{qmake Reference}. + + \section1 Building a Project + + For simple projects, you only need to run \c qmake in the top + level directory of your project. By default, \c qmake generates a + Makefile that you then use to build the project, and you can then + run your platform's \c make tool to build the project. + + \c qmake can also be used to generate project files. A full + description of \c{qmake}'s command line options can be found in the + \l{Running qmake} chapter of this manual. + + \section1 Using Precompiled Headers + + In large projects, it is possible to take advantage of precompiled + header files to speed up the build process. This feature is described + in detail in the \l{Using Precompiled Headers} chapter. +*/ + +/*! + \page qmake-project-files.html + \title qmake Project Files + \contentspage {qmake Manual}{Contents} + \previouspage Using qmake + \nextpage Running qmake + + Project files contain all the information required by \c qmake to build + your application, library, or plugin. The resources used by your project + are generally specified using a series of declarations, but support for + simple programming constructs allow you to describe different build + processes for different platforms and environments. + + \tableofcontents + + \section1 Project File Elements + + The project file format used by \c qmake can be used to support both + simple and fairly complex build systems. Simple project files will + use a straightforward declarative style, defining standard variables + to indicate the source and header files that are used in the project. + Complex projects may use the control flow structures to fine-tune the + build process. + + The following sections describe the different types of elements used + in project files. + + \section2 Variables + + In a project file, variables are used to hold lists of strings. + In the simplest projects, these variables inform \c qmake about the + configuration options to use, or supply filenames and paths to use + in the build process. + + \c qmake looks for certain variables in each project file, and it + uses the contents of these to determine what it should write to a + Makefile. For example, the list of values in the \c HEADERS and + \c SOURCES variables are used to tell \c qmake about header and + source files in the same directory as the project file. + + Variables can also be used internally to store temporary lists of values, + and existing lists of values can be overwritten or extended with new + values. + + The following lines show how lists of values are assigned to variables: + + \snippet doc/src/snippets/qmake/variables.pro 0 + + Note that the first assignment only includes values that are specified on + the same line as the \c SOURCES variable. The second assignment splits + the items across lines by using the \c \\ character. + + The list of values in a variable is extended in the following way: + + \snippet doc/src/snippets/qmake/variables.pro 1 + + The \c CONFIG variable is another special variable that \c qmake + uses when generating a Makefile. It is discussed in the section on + \l{#GeneralConfiguration}{general configuration} later in this chapter. + In the above line, \c qt is added to the list of existing values + contained in \c CONFIG. + + The following table lists the variables that \c qmake recognizes, and + describes what they should contain. + + \table + \header \o Variable \o Contents + \row \o CONFIG \o General project configuration options. + \row \o DESTDIR \o The directory in which the executable or binary file will + be placed. + \row \o FORMS \o A list of UI files to be processed by \c uic. + \row \o HEADERS \o A list of filenames of header (.h) files used when + building the project. + \row \o QT \o Qt-specific configuration options. + \row \o RESOURCES \o A list of resource (.rc) files to be included in the + final project. See the \l{The Qt Resource System} for + more information about these files. + \row \o SOURCES \o A list of source code files to be used when building + the project. + \row \o TEMPLATE \o The template to use for the project. This determines + whether the output of the build process will be an + application, a library, or a plugin. + \endtable + + The contents of a variable can be read by prepending the variable name with + \c $$. This can be used to assign the contents of one variable to another: + + \snippet doc/src/snippets/qmake/dereferencing.pro 0 + + The \c $$ operator is used extensively with built-in functions that operate + on strings and lists of values. These are described in the chapter on + \l{qmake Advanced Usage}. + + \section3 Whitespace + + Normally, variables are used to contain whitespace-separated lists + of values. However, it is sometimes necessary to specify values containing + spaces. These must be quoted by using the + \l{qmake Function Reference#quote-string}{quote()} function in the following way: + + \snippet doc/src/snippets/qmake/quoting.pro 0 + + The quoted text is treated as a single item in the list of values held by + the variable. A similar approach is used to deal with paths that contain + spaces, particularly when defining the + \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} and + \l{qmake Variable Reference#LIBS}{LIBS} variables for the Windows platform. + In cases like these, the \l{qmake Function Reference#quote(string)}{quote()} + function can be used in the following way: + + \snippet doc/src/snippets/qmake/spaces.pro quoting include paths with spaces + + \section2 Comments + + You can add comments to project files. Comments begin with the \c + # character and continue to the end of the same line. For example: + + \snippet doc/src/snippets/qmake/comments.pro 0 + + To include the \c # character in variable assignments, it is necessary + to use the contents of the built-in \c LITERAL_HASH variable. See the + \l{qmake Variable Reference#LITERAL_HASH}{variable reference} for more + information. + + \section2 Built-in Functions and Control Flow + + \c qmake provides a number of built-in functions to allow the contents + of variables to be processed. The most commonly used function in simple + project files is the \c include function which takes a filename as an + argument. The contents of the given file are included in the project + file at the place where the \c include function is used. + The \c include function is most commonly used to include other project + files: + + \snippet doc/src/snippets/qmake/include.pro 0 + + Support for conditional structures is made available via + \l{qmake Advanced Usage#scopes}{scopes} that behave like \c if + statements in programming languages: + + \snippet doc/src/snippets/qmake/scopes.pro 0 + + The assignments inside the braces are only made if the condition is + true. In this case, the special \c win32 variable must be set; this + happens automatically on Windows, but this can also be specified on + other platforms by running \c qmake with the \c{-win32} command line + option (see \l{Running qmake} for more information). The opening + brace must stand on the same line as the condition. + + Simple loops are constructed by iterating over lists of values using + the built-in \c for function. The following code adds directories + to the \l{qmake Variable Reference#SUBDIRS}{SUBDIRS} variable, but + only if they exist: + + \snippet doc/src/snippets/qmake/functions.pro 0 + + More complex operations on variables that would usually require loops + are provided by built-in functions such as \c find, \c unique, and + \c count. These functions, and many others are provided to manipulate + strings and paths, support user input, and call external tools. A list + of the functions available can be found in the + \l{qmake Advanced Usage} chapter of this manual. + + \section1 Project Templates + + The \c TEMPLATE variable is used to define the type of project that will + be built. If this is not declared in the project file, \c qmake assumes + that an application should be built, and will generate an appropriate + Makefile (or equivalent file) for the purpose. + + The types of project available are listed in the following table with + information about the files that \c qmake will generate for each of them: + + \table + \header \o Template \o Description of \c qmake output + \row \o app (default) \o Creates a Makefile to build an application. + \row \o lib \o Creates a Makefile to build a library. + \row \o subdirs \o Creates a Makefile containing rules for the + subdirectories specified using the \l{qmake Variable Reference#SUBDIRS}{SUBDIRS} + variable. Each subdirectory must contain its own project file. + \row \o vcapp \o Creates a Visual Studio Project file to build + an application. + \row \o vclib \o Creates a Visual Studio Project file to build a library. + \endtable + + See the \l{qmake Tutorial} for advice on writing project files for + projects that use the \c app and \c lib templates. + + When the \c subdirs template is used, \c qmake generates a Makefile + to examine each specified subdirectory, process any project file it finds + there, and run the platform's \c make tool on the newly-created Makefile. + The \l{qmake Variable Reference#SUBDIRS}{SUBDIRS} variable is used to + contain a list of all the subdirectories to be processed. + + \target GeneralConfiguration + \section1 General Configuration + + The \l{qmake Variable Reference#CONFIG}{CONFIG variable} specifies the + options and features that the compiler should use and the libraries that + should be linked against. Anything can be added to the \c CONFIG variable, + but the options covered below are recognized by \c qmake internally. + + The following options control the compiler flags that are used to build the + project: + + \table + \header \o Option \o Description + \row \o release \o The project is to be built in release mode. + This is ignored if \c debug is also specified. + \row \o debug \o The project is to be built in debug mode. + \row \o debug_and_release \o The project is built in \e both debug and + release modes. + \row \o debug_and_release_target \o The project is built in \e both debug + and release modes. TARGET is built into \e both the debug and release directories. + \row \o build_all \o If \c debug_and_release is specified, the project is + built in both debug and release modes by default. + \row \o autogen_precompile_source \o Automatically generates a \c .cpp file that includes + the precompiled header file specified in the .pro file. + \row \o ordered \o When using the \c subdirs template, this option + specifies that the directories listed should be processed in the + order in which they are given. + \row \o warn_on \o The compiler should output as many warnings as possible. + This is ignored if \c warn_off is specified. + \row \o warn_off \o The compiler should output as few warnings as possible. + \row \o copy_dir_files \o Enables the install rule to also copy directories, not just files. + \endtable + + The \c debug_and_release option is special in that it enables \e both debug and + release versions of a project to be built. In such a case, the Makefile that + \c qmake generates includes a rule that builds both versions, and this can be + invoked in the following way: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 0 + + Adding the \c build_all option to the \c CONFIG variable makes this rule + the default when building the project, and installation targets will be + created for both debug and release builds. + + Note that each of the options specified in the \c CONFIG variable can also be + used as a scope condition. + You can test for the presence of certain configuration options by using the + built-in \l{qmake Function Reference#CONFIG(config)}{CONFIG()} function. + For example, the following lines show the function as the condition in a scope + to test whether only the \c opengl option is in use: + + \snippet doc/src/snippets/qmake/configscopes.pro 4 + \snippet doc/src/snippets/qmake/configscopes.pro 5 + + This enables different configurations to be defined for \c release and + \c debug builds, and is described in more detail in the + \l{qmake Advanced Usage#Scopes}{Scopes} section of the + \l{qmake Advanced Usage}{Advanced Usage} chapter of this manual. + + The following options define the type of project to be built. Note that some + of these options only take effect when used on the relevant platform. On other + platforms, they have no effect. + + \table + \header \o Option \o Description + \row \o qt \o The project is a Qt application and should link against the Qt + library. You can use the \c QT variable to control any additional + Qt modules that are required by your application. + \row \o thread \o The project is a multi-threaded application. + \row \o x11 \o The project is an X11 application or library. + \endtable + + When using \l{qmake Variable Reference#TEMPLATE}{application or library project + templates}, more specialized configuration options can be used to fine tune the + build process. These are explained in details in the + \l{qmake-common-projects.html}{Common Projects} chapter of this manual. + + For example, if your application uses the Qt library and you want to + build it as a multi-threaded application in \c debug mode, your project + file will contain the following line: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 1 + + Note, that you must use "+=", not "=", or \c qmake will not be able to + use Qt's configuration to determine the settings needed for your project. + + \section1 Declaring Qt Libraries + + If the \c CONFIG variable contains the \c qt value, qmake's support for Qt + applications is enabled. This makes it possible to fine-tune which of the + Qt modules are used by your application. This is achieved with the \c QT + variable which can be used to declare the required extension modules. + For example, we can enable the XML and network modules in the following way: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 2 + + Note that \c QT includes the \c core and \c gui modules by default, so the + above declaration \e adds the network and XML modules to this default list. + The following assignment \e omits the default modules, and will lead to + errors when the application's source code is being compiled: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 3 + + If you want to build a project \e without the \c gui module, you need to + exclude it with the "-=" operator. By default, \c QT contains both + \c core and \c gui, so the following line will result in a minimal + Qt project being built: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 4 + + The table below shows the options that can be used with the \c QT variable + and the features that are associated with each of them: + + \table + \header \o Option \o Features + \row \o core (included by default) \o QtCore module + \row \o gui (included by default) \o QtGui module + \row \o network \o QtNetwork module + \row \o opengl \o QtOpenGL module + \row \o sql \o QtSql module + \row \o svg \o QtSvg module + \row \o xml \o QtXml module + \row \o xmlpatterns \o QtXmlPatterns module + \row \o qt3support \o Qt3Support module + \endtable + + Note that adding the \c opengl option to the \c QT variable automatically + causes the equivalent option to be added to the \c CONFIG variable. + Therefore, for Qt applications, it is not necessary to add the \c opengl + option to both \c CONFIG and \c{QT}. + + \section1 Configuration Features + + \c qmake can be set up with extra configuration features that are specified + in feature (.prf) files. These extra features often provide support for + custom tools that are used during the build process. To add a feature to + the build process, append the feature name (the stem of the feature filename) + to the \c CONFIG variable. + + For example, \c qmake can configure the build process to take advantage + of external libraries that are supported by + \l{http://www.freedesktop.org/wiki/Software_2fpkgconfig}{pkg-config}, + such as the D-Bus and ogg libraries, with the following lines: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 5 + + More information about features can be found in the + \l{qmake Advanced Usage#Adding New Configuration Features} + {Adding New Configuration Features} section of the \l{qmake Advanced Usage} + chapter. + + \section1 Declaring Other Libraries + + If you are using other libraries in your project in addition to those + supplied with Qt, you need to specify them in your project file. + + The paths that \c qmake searches for libraries and the specific libraries + to link against can be added to the list of values in the + \l{qmake Variable Reference#LIBS}{LIBS} variable. The paths to the libraries + themselves can be given, or the familiar Unix-style notation for specifying + libraries and paths can be used if preferred. + + For example, the following lines show how a library can be specified: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 6 + + The paths containing header files can also be specified in a similar way + using the \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} variable. + + For example, it is possible to add several paths to be searched for header + files: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 7 +*/ + +/*! + \page qmake-running.html + \title Running qmake + \contentspage {qmake Manual}{Contents} + \previouspage qmake Project Files + \nextpage qmake Platform Notes + + The behavior of \c qmake can be customized when it is run by + specifying various options on the command line. These allow the + build process to be fine-tuned, provide useful diagnostic + information, and can be used to specify the target platform for + your project. + + \tableofcontents + + \target Commands + \section1 Command-Line Options + + \section2 Syntax + + The syntax used to run \c qmake takes the following simple form: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 8 + + \c qmake supports two different modes of operation: In the default mode, + \c qmake will use the description in a project file to generate a Makefile, + but it is also possible to use \c qmake to generate project files. + If you want to explicitly set the mode, you must specify it before all + other options. The \c mode can be either of the following two values: + + \list + \o \c -makefile \BR + \c qmake output will be a Makefile. + \o \c -project \BR + \c qmake output will be a project file. \BR +\bold{Note:} It is likely that the created file will need to be edited for example adding the \c QT variable to suit what modules are required for the project. + \endlist + + The following \c options are used to specify both general and mode-specific + settings. Options that only apply to the Makefile mode are described in the + \l{#MakefileMode}{Makefile Mode Options} section; options that influence the + creation of project files are described in the + \l{#ProjectMode}{Project File Options} section. + + The \c files argument represents a list of one or more project files, separated + by spaces. + + \section2 Options + + A wide range of options can be specified on the command line to \c qmake in + order to customize the build process, and to override default settings for + your platform. The following basic options provide usage information, specify + where \c qmake writes the output file, and control the level of debugging + information that will be written to the console: + + \list + \o \c -help \BR + \c qmake will go over these features and give some useful help. + \o \c -o file \BR + \c qmake output will be directed to \e file. If this option + is not specified, \c qmake will try to use a suitable file name for its + output, depending on the mode it is running in.\BR + If '-' is specified, output is directed to stdout. + \o \c -d \BR + \c qmake will output debugging information. + \endlist + + For projects that need to be built differently on each target platform, with + many subdirectories, you can run \c qmake with each of the following + options to set the corresponding platform-specific variable in each + project file: + + \list + \o \c -unix \BR + \c qmake will run in unix mode. In this mode, Unix file + naming and path conventions will be used, additionally testing for \c unix + (as a scope) will succeed. This is the default mode on all Unices. + \o \c -macx \BR + \c qmake will run in Mac OS X mode. In this mode, Unix file + naming and path conventions will be used, additionally testing for \c macx + (as a scope) will succeed. This is the default mode on Mac OS X. + \o \c -win32 \BR + \c qmake will run in win32 mode. In this mode, Windows file naming and path + conventions will be used, additionally testing for \c win32 (as a scope) + will succeed. This is the default mode on Windows. + \endlist + + The template used for the project is usually specified by the \c TEMPLATE + variable in the project file. We can override or modify this by using the + following options: + + \list + \o \c -t tmpl \BR + \c qmake will override any set \c TEMPLATE variables with tmpl, but only + \e after the .pro file has been processed. + \o \c -tp prefix \BR + \c qmake will add the prefix to the \c TEMPLATE variable. + \endlist + + The level of warning information can be fine-tuned to help you find problems in + your project file: + + \list + \o \c -Wall \BR + \c qmake will report all known warnings. + \o \c -Wnone \BR + No warning information will be generated by \c qmake. + \o \c -Wparser \BR + \c qmake will only generate parser warnings. This will alert + you to common pitfalls and potential problems in the parsing of your + project files. + \o \c -Wlogic \BR + \c qmake will warn of common pitfalls and potential problems in your + project file. For example, \c qmake will report whether a file is placed + into a list of files multiple times, or if a file cannot be found. + \endlist + + \target MakefileMode + \section2 Makefile Mode Options + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 9 + + In Makefile mode, \c qmake will generate a Makefile that is used to build the + project. Additionally, the following options may be used in this mode to + influence the way the project file is generated: + + \list + \o \c -after \BR + \c qmake will process assignments given on the command line after + the specified files. + \o \c -nocache \BR + \c qmake will ignore the .qmake.cache file. + \o \c -nodepend \BR + \c qmake will not generate any dependency information. + \o \c -cache file \BR + \c qmake will use \e file as the cache file, ignoring any other + .qmake.cache files found. + \o \c -spec spec \BR + \c qmake will use \e spec as a path to platform and compiler information, + and the value of \c QMAKESPEC will be ignored. + \endlist + + You may also pass \c qmake assignments on the command line; + they will be processed before all of the files specified. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 10 + + This will generate a Makefile, from test.pro with Unix pathnames. However + many of the specified options aren't necessary as they are the default. + Therefore, the line can be simplified on Unix to: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 11 + + If you are certain you want your variables processed after the + files specified, then you may pass the \c -after option. When this + is specified, all assignments on the command line after the \c -after + option will be postponed until after the specified files are parsed. + + \target ProjectMode + \section2 Project Mode Options + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 12 + + In project mode, \c qmake will generate a project file. Additionally, you + may supply the following options in this mode: + + \list + \o \c -r \BR + \c qmake will look through supplied directories recursively + \o \c -nopwd \BR + \c qmake will not look in your current working directory for + source code and only use the specified \c files + \endlist + + In this mode, the \c files argument can be a list of files or directories. + If a directory is specified, it will be included in the \c DEPENDPATH + variable, and relevant code from there will be included in the generated + project file. If a file is given, it will be appended to the correct + variable, depending on its extension; for example, UI files are added + to \c FORMS, and C++ files are added to \c SOURCES. + + You may also pass assignments on the command line in this mode. When doing + so, these assignments will be placed last in the generated project file. +*/ + +/*! + \page qmake-platform-notes.html + \title qmake Platform Notes + \contentspage {qmake Manual}{Contents} + \previouspage Running qmake + \nextpage qmake Advanced Usage + + Many cross-platform projects can be handled by the \c{qmake}'s basic + configuration features. On some platforms, it is sometimes useful, or even + necessary, to take advantage of platform-specific features. \c qmake knows + about many of these features, and these can be accessed via specific + variables that only have an effect on the platforms where they are relevant. + + \tableofcontents + + \section1 Mac OS X + + Features specific to this platform include support for creating universal + binaries, frameworks and bundles. + + \section2 Source and Binary Packages + + The version of \c qmake supplied in source packages is configured slightly + differently to that supplied in binary packages in that it uses a different + feature specification. Where the source package typically uses the + \c macx-g++ specification, the binary package is typically configured to + use the \c macx-xcode specification. + + Users of each package can override this configuration by invoking \c qmake + with the \c -spec option (see \l{Running qmake} for more information). This + makes it possible, for example, to use \c qmake from a binary package to + create a Makefile in a project directory with the following command line + invocation: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 13 + + \section2 Using Frameworks + + \c qmake is able to automatically generate build rules for linking against + frameworks in the standard framework directory on Mac OS X, located at + \c{/Library/Frameworks/}. + + Directories other than the standard framework directory need to be specified + to the build system, and this is achieved by appending linker options to the + \l{qmake Variable Reference#QMAKE_LFLAGS}{QMAKE_LFLAGS} variable, as shown + in the following example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 14 + + The framework itself is linked in by appending the \c{-framework} options and + the name of the framework to the \l{qmake Variable Reference#LIBS}{LIBS} + variable: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 15 + + \section2 Creating Frameworks + + Any given library project can be configured so that the resulting library + file is placed in a + \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WhatAreFrameworks.html} + {framework}, ready for deployment. To do this, set up the project to use the + \l{qmake Variable Reference#TEMPLATE}{\c lib template} and add the + \c lib_bundle option to the + \l{qmake Variable Reference#CONFIG}{CONFIG} variable: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 16 + + The data associated with the library is specified using the + \l{qmake Variable Reference#QMAKE_BUNDLE_DATA}{QMAKE_BUNDLE_DATA} + variable. This holds items that will be installed with a library + bundle, and is often used to specify a collection of header files, + as in the following example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 17 + + Here, the \c FRAMEWORK_HEADERS variable is a user-defined variable that + is used to define the headers required to use a particular framework. + Appending it to the \c QMAKE_BUNDLE_DATA variable ensures that the + information about these headers are added to the collection of + resources that will be installed with the library bundle. Also, the + framework's name and version are specified by + \l{qmake Variable Reference#QMAKE_FRAMEWORK_BUNDLE_NAME} + {QMAKE_FRAMEWORK_BUNDLE_NAME} + and \l{qmake Variable Reference#QMAKE_FRAMEWORK_VERSION} + {QMAKE_FRAMEWORK_VERSION} variables. By default, the values used for + these are obtained from the \l{qmake Variable Reference#TARGET}{TARGET} + and \l{qmake Variable Reference#VERSION}{VERSION} variables. + + See \l{Deploying an Application on Mac OS X} for more information about + deploying applications and libraries. + + \section2 Creating Universal Binaries + + To create a universal binary for your application, you need to be using + a version of Qt that has been configured with the \c{-universal} option. + + The architectures to be supported in the binary are specified with the + \l{qmake Variable Reference#CONFIG}{CONFIG} variable. For example, the + following assignment causes \c qmake to generate build rules to create + a universal binary for both PowerPC and x86 architectures: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 18 + + Additionally, developers using a PowerPC-based platform need to set the + \l{qmake Variable Reference#QMAKE_MAC_SDK}{QMAKE_MAC_SDK} variable. + This process is discussed in more detail in the + \l{Deploying an Application on Mac OS X#Architecture Dependencies}{deployment guide for Mac OS X}. + + \section2 Creating and Moving Xcode Projects + + Developers on Mac OS X can take advantage of \c{qmake}'s support for Xcode + project files, as described in + \l{Qt is Mac OS X Native#Development Tools}{Qt is Mac OS X Native}, + by running \c qmake to generate an Xcode project from an existing \c qmake + project files. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 19 + + Note that, if a project is later moved on the disk, \c qmake must be run + again to process the project file and create a new Xcode project file. + + \section2 On supporting two build targets simultaneously + + Implementing this is currently not feasible, because the XCode + concept of Active Build Configurations is conceptually different + from the qmake idea of build targets. + + The XCode Active Build Configurations settings are for modifying + xcode configurations, compiler flags and similar build + options. Unlike Visual Studio, XCode does not allow for the + selection of specific library files based on whether debug or + release build configurations are selected. The qmake debug and + release settings control which library files are linked to the + executable. + + It is currently not possible to set files in XCode configuration + settings from the qmake generated xcode project file. The way the + libraries are linked in the "Frameworks & Libraries" phase in the + XCode build system. + + Furthermore, The selected "Active Build Configuration" is stored + in a .pbxuser file, which is generated by xcode on first load, not + created by qmake. + + \section1 Windows + + Features specific to this platform include support for creating Visual + Studio project files and handling manifest files when deploying Qt + applications developed using Visual Studio 2005. + + \section2 Creating Visual Studio Project Files + + Developers using Visual Studio to write Qt applications can use the + Visual Studio integration facilities provided with the + \l{Qt Commercial Editions} and do not need to worry about how + project dependencies are managed. + + However, some developers may need to import an existing \c qmake project + into Visual Studio. \c qmake is able to take a project file and create a + Visual Studio project that contains all the necessary information required + by the development environment. This is achieved by setting the \c qmake + \l{qmake Variable Reference#TEMPLATE}{project template} to either \c vcapp + (for application projects) or \c vclib (for library projects). + + This can also be set using a command line option, for example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 20 + + It is possible to recursively generate \c{.vcproj} files in subdirectories + and a \c{.sln} file in the main directory, by typing: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 21 + + Each time you update the project file, you need to run \c qmake to generate + an updated Visual Studio project. + + \note If you are using the Visual Studio Add-in, you can import \c .pro + files via the \gui{Qt->Import from .pro file} menu item. + + \section2 Visual Studio 2005 Manifest Files + + When deploying Qt applications built using Visual Studio 2005, it is + necessary to ensure that the manifest file, created when the application + was linked, is handled correctly. This is handled automatically for + projects that generate DLLs. + + Removing manifest embedding for application executables can be done with + the following assignment to the \l{qmake Variable Reference#CONFIG} + {CONFIG} variable: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 22 + + Also, the manifest embedding for DLLs can be removed with the following + assignment to the \l{qmake Variable Reference#CONFIG}{CONFIG} variable: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 23 + + This is discussed in more detail in the + \l{Deploying an Application on Windows#Visual Studio 2005 Onwards} + {deployment guide for Windows}. +*/ + +/*! + \page qmake-reference.html + \title qmake Reference + \contentspage {qmake Manual}{Contents} + \previouspage Using Precompiled Headers + \nextpage qmake Variable Reference + + This reference is a detailed index of all the variables and function + that are available for use in \c qmake project files. + + \section1 Variable Reference + + The \l{qmake Variable Reference} describes the variables that are + recognized by \c qmake when configuring the build process for + projects. + + \section1 Function Reference + + The \l{qmake Function Reference} describes the function that can be + used to process the contents of variables defined in project files. + + \target FrequentlyUsedVariables + \section1 Frequently Used Variables + + The following variables are frequently used in project files to describe + common aspects of the build process. These are fully described in the + \l{qmake-variable-reference.html}{Variable Reference}. + + \list + \o \l{qmake Variable Reference#CONFIG}{CONFIG} + \o \l{qmake Variable Reference#DEF_FILE}{DEF_FILE} + \o \l{qmake Variable Reference#DEFINES}{DEFINES} + \o \l{qmake Variable Reference#DESTDIR}{DESTDIR} + \o \l{qmake Variable Reference#DISTFILES}{DISTFILES} + \o \l{qmake Variable Reference#DLLDESTDIR}{DLLDESTDIR} + \o \l{qmake Variable Reference#FORMS}{FORMS} + \o \l{qmake Variable Reference#FORMS3}{FORMS3} + \o \l{qmake Variable Reference#GUID}{GUID} + \o \l{qmake Variable Reference#HEADERS}{HEADERS} + \o \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} + \o \l{qmake Variable Reference#LEXSOURCES}{LEXSOURCES} + \o \l{qmake Variable Reference#LIBS}{LIBS} + \o \l{qmake Variable Reference#MOC_DIR}{MOC_DIR} + \o \l{qmake Variable Reference#OBJECTS_DIR}{OBJECTS_DIR} + \o \l{qmake Variable Reference#QT}{QT} + \o \l{qmake Variable Reference#RCC_DIR}{RCC_DIR} + \o \l{qmake Variable Reference#REQUIRES}{REQUIRES} + \o \l{qmake Variable Reference#RESOURCES}{RESOURCES} + \o \l{qmake Variable Reference#SOURCES}{SOURCES} + \o \l{qmake Variable Reference#SUBDIRS}{SUBDIRS} + \o \l{qmake Variable Reference#TARGET}{TARGET} + \o \l{qmake Variable Reference#TEMPLATE}{TEMPLATE} + \o \l{qmake Variable Reference#TRANSLATIONS}{TRANSLATIONS} + \o \l{qmake Variable Reference#UI_DIR}{UI_DIR} + \o \l{qmake Variable Reference#UI_HEADERS_DIR}{UI_HEADERS_DIR} + \o \l{qmake Variable Reference#UI_SOURCES_DIR}{UI_SOURCES_DIR} + \o \l{qmake Variable Reference#VERSION}{VERSION} + \o \l{qmake Variable Reference#YACCSOURCES}{YACCSOURCES} + \endlist + + \section1 Environment Variables and Configuration + + The \l{Configuring qmake's Environment} chapter of this manual + describes the environment variables that \c qmake uses when + configuring the build process. +*/ + +/*! + \page qmake-variable-reference.html + \title qmake Variable Reference + \contentspage {qmake Manual}{Contents} + \previouspage qmake Reference + \nextpage qmake Function Reference + + \c{qmake}'s fundamental behavior is influenced by variable declarations that + define the build process of each project. Some of these declare resources, + such as headers and source files, that are common to each platform; others + are used to customize the behavior of compilers and linkers on specific + platforms. + + Platform-specific variables follow the naming pattern of the + variables which they extend or modify, but include the name of the relevant + platform in their name. For example, \c QMAKE_LIBS can be used to specify a list + of libraries that a project needs to link against, and \c QMAKE_LIBS_X11 can be + used to extend or override this list. + + \tableofcontents{3} + + \target CONFIG + \section1 CONFIG + + The \c CONFIG variable specifies project configuration and + compiler options. The values will be recognized internally by + \c qmake and have special meaning. They are as follows. + + These \c CONFIG values control compilation flags: + + \table 95% + \header \o Option \o Description + \row \o release \o The project is to be built in release mode. + This is ignored if \c debug is also specified. + \row \o debug \o The project is to be built in debug mode. + \row \o debug_and_release \o The project is built in \e both debug and + release modes. This can have some unexpected side effects (see + below for more information). + \row \o build_all \o If \c debug_and_release is specified, the project is + built in both debug and release modes by default. + \row \o ordered \o When using the \c subdirs template, this option + specifies that the directories listed should be processed in the + order in which they are given. + \row \o precompile_header \o Enables support for the use of + \l{Using Precompiled Headers}{precompiled headers} in projects. + \row \o warn_on \o The compiler should output as many warnings as possible. + This is ignored if \c warn_off is specified. + \row \o warn_off \o The compiler should output as few warnings as possible. + \omit + \row \o qt_debug \o Specifies that the project should be built against + debug versions of the Qt libraries specified using the + \l{#QT}{QT} variable. + \row \o qt_release \o Specifies that the project should be built against + release versions of the Qt libraries specified using the + \l{#QT}{QT} variable. + \endomit + \endtable + + Since the \c debug option overrides the \c release option when both are + defined in the \c CONFIG variable, it is necessary to use the + \c debug_and_release option if you want to allow both debug and release + versions of a project to be built. In such a case, the Makefile that + \c qmake generates includes a rule that builds both versions, and this can + be invoked in the following way: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 24 + + When linking a library, \c qmake relies on the underlying platform to know + what other libraries this library links against. However, if linking + statically, \c qmake will not get this information unless we use the following + \c CONFIG options: + + \table 95% + \header \o Option \o Description + \row \o create_prl \o This option enables \c qmake to track these + dependencies. When this option is enabled, \c qmake will create a file + ending in \c .prl which will save meta-information about the library + (see \l{LibDepend}{Library Dependencies} for more info). + \row \o link_prl \o When this is enabled, \c qmake will process all + libraries linked to by the application and find their meta-information + (see \l{LibDepend}{Library Dependencies} for more info). + \endtable + + Please note that \c create_prl is required when \e {building} a + static library, while \c link_prl is required when \e {using} a + static library. + + On Windows (or if Qt is configured with \c{-debug_and_release}, adding the + \c build_all option to the \c CONFIG variable makes this rule the default + when building the project, and installation targets will be created for + both debug and release builds. + + Additionally, adding \c debug_and_release to the \c CONFIG variable will + cause both \c debug and \c release to be defined in the contents of + \c CONFIG. When the project file is processed, the + \l{qmake Advanced Usage#Scopes}{scopes} that test for each value will be + processed for \e both debug and release modes. The \c{build_pass} variable + will be set for each of these mode, and you can test for this to perform + build-specific tasks. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 25 + + As a result, it may be useful to define mode-specific variables, such as + \l{#QMAKE_LFLAGS_RELEASE}{QMAKE_LFLAGS_RELEASE}, instead of general + variables, such as \l{#QMAKE_LFLAGS}{QMAKE_LFLAGS}, where possible. + + The following options define the application/library type: + + \table 95% + \header \o Option \o Description + \row \o qt \o The target is a Qt application/library and requires the Qt + library and header files. The proper include and library paths for the + Qt library will automatically be added to the project. This is defined + by default, and can be fine-tuned with the \c{\l{#qt}{QT}} variable. + \row \o thread \o The target is a multi-threaded application or library. The + proper defines and compiler flags will automatically be added to + the project. + \row \o x11 \o The target is a X11 application or library. The proper + include paths and libraries will automatically be added to the + project. + \row \o windows \o The target is a Win32 window application (app only). The + proper include paths, compiler flags and libraries will + automatically be added to the project. + \row \o console \o The target is a Win32 console application (app only). The + proper include paths, compiler flags and libraries will + automatically be added to the + project. + \row \o shared \o{1,3} The target is a shared object/DLL. The proper + include paths, compiler flags and libraries will automatically be + added to the project. + \row \o dll \o + \row \o dylib \o + \row \o static \o{1,2} The target is a static library (lib only). The proper + compiler flags will automatically be added to the project. + \row \o staticlib \o + \row \o plugin \o The target is a plugin (lib only). This enables dll as well. + \row \o designer \o The target is a plugin for \QD. + \row \o uic3 \o Configures qmake to run uic3 on the content of \c FORMS3 if + defined; otherwise the contents of \c FORMS will be processed instead. + \row \o no_lflags_merge \o Ensures that the list of libraries stored in the + \c LIBS variable is not reduced to a list of unique values before it is used. + \row \o resources \o Configures qmake to run rcc on the content of \c RESOURCES + if defined. + \endtable + + These options are used to set the compiler flags: + + \table 95% + \header \o Option \o Description + \row \o 3dnow \o AMD 3DNow! instruction support is enabled. + \row \o exceptions \o Exception support is enabled. + \row \o mmx \o Intel MMX instruction support is enabled. + \row \o rtti \o RTTI support is enabled. + \row \o stl \o STL support is enabled. + \row \o sse \o SSE support is enabled. + \row \o sse2 \o SSE2 support is enabled. + \endtable + + These options define specific features on Windows only: + + \table 95% + \header \o Option \o Description + \row \o flat \o When using the vcapp template this will put all the source + files into the source group and the header files into the header group + regardless of what directory they reside in. Turning this + option off will group the files within the source/header group depending + on the directory they reside. This is turned on by default. + \row \o embed_manifest_dll \o Embeds a manifest file in the DLL created + as part of a library project. + \row \o embed_manifest_exe \o Embeds a manifest file in the DLL created + as part of an application project. + \row \o incremental \o Used to enable or disable incremental linking in Visual + C++, depending on whether this feature is enabled or disabled by default. + \endtable + + See \l{qmake Platform Notes#Visual Studio 2005 Manifest Files}{qmake Platform Notes} + for more information on the options for embedding manifest files. + + These options only have an effect on Mac OS X: + + \table 95% + \header \o Option \o Description + \row \o ppc \o Builds a PowerPC binary. + \row \o x86 \o Builds an i386 compatible binary. + \row \o app_bundle \o Puts the executable into a bundle (this is the default). + \row \o lib_bundle \o Puts the library into a library bundle. + \endtable + + The build process for bundles is also influenced by + the contents of the \l{#QMAKE_BUNDLE_DATA}{QMAKE_BUNDLE_DATA} variable. + + These options have an effect on Linux/Unix platforms: + + \table 95% + \header \o Option \o Description + \row \o largefile \o Includes support for large files. + \row \o separate_debug_info \o Puts debugging information for libraries in + separate files. + \endtable + + The \c CONFIG variable will also be checked when resolving scopes. You may + assign anything to this variable. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 26 + + \target DEFINES + \section1 DEFINES + + \c qmake adds the values of this variable as compiler C + preprocessor macros (-D option). + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 27 + + \target DEF_FILE + \section1 DEF_FILE + + \e {This is only used on Windows when using the \c app template}. + + Specifies a \c .def file to be included in the project. + + \target DEPENDPATH + \section1 DEPENDPATH + + This variable contains the list of all directories to look in to + resolve dependencies. This will be used when crawling through + \c included files. + + \target DEPLOYMENT + \section1 DEPLOYMENT + + \e {This is only used on Windows CE.} + + Specifies which additional files will be deployed. Deployment means the + transfer of files from the development system to the target device or + emulator. + + Files can be deployed by either creating a Visual Studio project or using + the \l {Using QTestLib remotely on Windows CE}{cetest} executable. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 28 + + This will upload all PNG images in \c path to the same directory your + build target will be deployed to. + + The default deployment target path for Windows CE is + \c{%CSIDL_PROGRAM_FILES%\target}, which usually gets expanded to + \c{\Program Files\target}. + + It is also possible to specify multiple \c sources to be deployed on + target \c paths. In addition, different variables can be used for + deployment to different directories. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 29 + + \note All linked Qt libraries will be deployed to the path specified + by \c{myFiles.path}. + + \target DEPLOYMENT_PLUGIN + \section1 DEPLOYMENT_PLUGIN + + \e {This is only used on Windows CE.} + + This variable specifies the Qt plugins that will be deployed. All plugins + available in Qt can be explicitly deployed to the device. See + \l{Static Plugins}{Static Plugins} for a complete list. + + \note No plugins will be deployed automatically. If the application + depends on plugins, these plugins have to be specified manually. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 128 + + This will upload the jpeg imageformat plugin to the plugins directory + on the Windows CE device. + + \target DESTDIR + \section1 DESTDIR + + Specifies where to put the \l{#TARGET}{target} file. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 30 + + \target DESTDIR_TARGET + \section1 DESTDIR_TARGET + + This variable is set internally by \c qmake, which is basically the + \c DESTDIR variable with the \c TARGET variable appened at the end. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target DLLDESTDIR + \section1 DLLDESTDIR + + Specifies where to copy the \l{#TARGET}{target} dll. + + \target DISTFILES + \section1 DISTFILES + + This variable contains a list of files to be included in the dist + target. This feature is supported by UnixMake specs only. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 31 + + \target DSP_TEMPLATE + \section1 DSP_TEMPLATE + + This variable is set internally by \c qmake, which specifies where the + dsp template file for basing generated dsp files is stored. The value + of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target FORMS + \section1 FORMS + + This variable specifies the UI files (see \link + designer-manual.html Qt Designer \endlink) to be processed through \c uic + before compiling. All dependencies, headers and source files required + to build these UI files will automatically be added to the project. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 32 + + If FORMS3 is defined in your project, then this variable must contain + forms for uic, and not uic3. If CONFIG contains uic3, and FORMS3 is not + defined, the this variable must contain only uic3 type forms. + + \target FORMS3 + \section1 FORMS3 + + This variable specifies the old style UI files to be processed + through \c uic3 before compiling, when \c CONFIG contains uic3. + All dependencies, headers and source files required to build these + UI files will automatically be added to the project. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 33 + + \target GUID + \section1 GUID + + Specifies the GUID that is set inside a \c{.vcproj} file. The GUID is + usually randomly determined. However, should you require a fixed GUID, + it can be set using this variable. + + This variable is specific to \c{.vcproj} files only; it is ignored + otherwise. + + \target HEADERS + \section1 HEADERS + + Defines the header files for the project. + + \c qmake will generate dependency information (unless \c -nodepend + is specified on the \l{Running qmake#Commands}{command line}) + for the specified headers. \c qmake will also automatically detect if + \c moc is required by the classes in these headers, and add the + appropriate dependencies and files to the project for generating and + linking the moc files. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 34 + + See also \l{#SOURCES}{SOURCES}. + + \target INCLUDEPATH + \section1 INCLUDEPATH + + This variable specifies the #include directories which should be + searched when compiling the project. Use ';' or a space as the + directory separator. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 35 + + To specify a path containing spaces, quote the path using the technique + mentioned in the \l{qmake Project Files#Whitespace}{qmake Project Files} + document. For example, paths with spaces can be specified on Windows + and Unix platforms by using the \l{qmake Function Reference#quote-string}{quote()} + function in the following way: + + \snippet doc/src/snippets/qmake/spaces.pro quoting include paths with spaces + + \target INSTALLS + \section1 INSTALLS + + This variable contains a list of resources that will be installed when + \c{make install} or a similar installation procedure is executed. Each + item in the list is typically defined with attributes that provide + information about where it will be installed. + + For example, the following \c{target.path} definition describes where the + build target will be installed, and the \c INSTALLS assignment adds the + build target to the list of existing resources to be installed: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 36 + + \target LEXIMPLS + \section1 LEXIMPLS + + This variable contains a list of lex implementation files. The value + of this variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. + + \target LEXOBJECTS + \section1 LEXOBJECTS + + This variable contains the names of intermediate lex object + files.The value of this variable is typically handled by + \c qmake and rarely needs to be modified. + + \target LEXSOURCES + \section1 LEXSOURCES + + This variable contains a list of lex source files. All + dependencies, headers and source files will automatically be added to + the project for building these lex files. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 37 + + \target LIBS + \section1 LIBS + + This variable contains a list of libraries to be linked into the project. + You can use the Unix \c -l (library) and -L (library path) flags and qmake + will do the correct thing with these libraries on Windows (namely this + means passing the full path of the library to the linker). The only + limitation to this is the library must exist, for qmake to find which + directory a \c -l lib lives in. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 38 + + To specify a path containing spaces, quote the path using the technique + mentioned in the \l{qmake Project Files#Whitespace}{qmake Project Files} + document. For example, paths with spaces can be specified on Windows + and Unix platforms by using the \l{qmake Function Reference#quote-string}{quote()} + function in the following way: + + \snippet doc/src/snippets/qmake/spaces.pro quoting library paths with spaces + + \bold{Note:} On Windows, specifying libraries with the \c{-l} option, + as in the above example, will cause the library with the highest version + number to be used; for example, \c{libmath2.lib} could potentially be used + instead of \c{libmathlib}. To avoid this ambiguity, we recommend that you + explicitly specify the library to be used by including the \c{.lib} + file name suffix. + + By default, the list of libraries stored in \c LIBS is reduced to a list of + unique names before it is used. To change this behavior, add the + \c no_lflags_merge option to the \c CONFIG variable: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 39 + + \target LITERAL_HASH + \section1 LITERAL_HASH + + This variable is used whenever a literal hash character (\c{#}) is needed in + a variable declaration, perhaps as part of a file name or in a string passed + to some external application. + + For example: + + \snippet doc/src/snippets/qmake/comments.pro 1 + + By using \c LITERAL_HASH in this way, the \c # character can be used + to construct a URL for the \c message() function to print to the console. + + \target MAKEFILE + \section1 MAKEFILE + + This variable specifies the name of the Makefile which + \c qmake should use when outputting the dependency information + for building a project. The value of this variable is typically + handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target MAKEFILE_GENERATOR + \section1 MAKEFILE_GENERATOR + + This variable contains the name of the Makefile generator to use + when generating a Makefile. The value of this variable is typically + handled internally by \c qmake and rarely needs to be modified. + + \target MOC_DIR + \section1 MOC_DIR + + This variable specifies the directory where all intermediate moc + files should be placed. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 40 + + \target OBJECTS + \section1 OBJECTS + + This variable is generated from the \link #SOURCES SOURCES + \endlink variable. The extension of each source file will have been + replaced by .o (Unix) or .obj (Win32). The value of this variable is + typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and + rarely needs to be modified. + + \target OBJECTS_DIR + \section1 OBJECTS_DIR + + This variable specifies the directory where all intermediate + objects should be placed. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 41 + + \target OBJMOC + \section1 OBJMOC + + This variable is set by \c qmake if files can be found that + contain the Q_OBJECT macro. \c OBJMOC contains the + name of all intermediate moc object files. The value of this variable + is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be + modified. + + \target POST_TARGETDEPS + \section1 POST_TARGETDEPS + + All libraries that the \l{#TARGET}{target} depends on can be + listed in this variable. Some backends do not support this, these include + MSVC Dsp, and ProjectBuilder .pbproj files. Generally this is supported + internally by these build tools, this is useful for explicitly listing + dependant static libraries. + + This list will go after all builtin (and \link #PRE_TARGETDEPS + $$PRE_TARGETDEPS \endlink) dependencies. + + \target PRE_TARGETDEPS + \section1 PRE_TARGETDEPS + + All libraries that the \l{#TARGET}{target} depends on can be + listed in this variable. Some backends do not support this, these include + MSVC Dsp, and ProjectBuilder .pbproj files. Generally this is supported + internally by these build tools, this is useful for explicitly listing + dependant static libraries. + + This list will go before all builtin dependencies. + + \target PRECOMPILED_HEADER + \section1 PRECOMPILED_HEADER + + This variable indicates the header file for creating a precompiled + header file, to increase the compilation speed of a project. + Precompiled headers are currently only supported on some platforms + (Windows - all MSVC project types, Mac OS X - Xcode, Makefile, + Unix - gcc 3.3 and up). + + On other platforms, this variable has different meaning, as noted + below. + + This variable contains a list of header files that require some + sort of pre-compilation step (such as with moc). The value of this + variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be + modified. + + \target PWD + \section1 PWD + + This variable contains the full path leading to the directory where + the \c qmake project file (project.pro) is located. + + \target OUT_PWD + \section1 OUT_PWD + + This variable contains the full path leading to the directory where + \c qmake places the generated Makefile. + + \target QMAKE_systemvariable + \section1 QMAKE + + This variable contains the name of the \c qmake program + itself and is placed in generated Makefiles. The value of this + variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be + modified. + + \target QMAKESPEC_systemvariable + \section1 QMAKESPEC + + This variable contains the name of the \c qmake + configuration to use when generating Makefiles. The value of this + variable is typically handled by \c qmake and rarely needs to be modified. + + Use the \c{QMAKESPEC} environment variable to override the \c qmake configuration. + Note that, due to the way \c qmake reads project files, setting the \c{QMAKESPEC} + environment variable from within a project file will have no effect. + + \target QMAKE_APP_FLAG + \section1 QMAKE_APP_FLAG + + This variable is empty unless the \c app + \l{#TEMPLATE}{TEMPLATE} is specified. The value of this + variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be + modified. Use the following instead: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 42 + + \target QMAKE_APP_OR_DLL + \section1 QMAKE_APP_OR_DLL + + This variable is empty unless the \c app or \c dll + \l{#TEMPLATE}{TEMPLATE} is specified. The value of this + variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be + modified. + + \target QMAKE_AR_CMD + \section1 QMAKE_AR_CMD + + \e {This is used on Unix platforms only.} + + This variable contains the command for invoking the program which + creates, modifies and extracts archives. The value of this variable is + typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} + and rarely needs to be modified. + + \target QMAKE_BUNDLE_DATA + \section1 QMAKE_BUNDLE_DATA + + This variable is used to hold the data that will be installed with a library + bundle, and is often used to specify a collection of header files. + + For example, the following lines add \c path/to/header_one.h + and \c path/to/header_two.h to a group containing information about the + headers supplied with the framework: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 43 + + The last line adds the information about the headers to the collection of + resources that will be installed with the library bundle. + + Library bundles are created when the \c lib_bundle option is added to the + \l{#CONFIG}{CONFIG} variable. + + See \l{qmake Platform Notes#Creating Frameworks}{qmake Platform Notes} for + more information about creating library bundles. + + \e{This is used on Mac OS X only.} + + \section1 QMAKE_BUNDLE_EXTENSION + + This variable defines the extension to be used for library bundles. + This allows frameworks to be created with custom extensions instead of the + standard \c{.framework} directory name extension. + + For example, the following definition will result in a framework with the + \c{.myframework} extension: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 44 + + \e{This is used on Mac OS X only.} + + \section1 QMAKE_CC + + This variable specifies the C compiler that will be used when building + projects containing C source code. Only the file name of the compiler + executable needs to be specified as long as it is on a path contained + in the \c PATH variable when the Makefile is processed. + + \target QMAKE_CFLAGS_DEBUG + \section1 QMAKE_CFLAGS_DEBUG + + This variable contains the flags for the C compiler in debug mode.The value of this variable is + typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} + and rarely needs to be modified. + + \target QMAKE_CFLAGS_MT + \section1 QMAKE_CFLAGS_MT + + This variable contains the compiler flags for creating a + multi-threaded application or when the version of Qt that you link + against is a multi-threaded statically linked library. The value of + this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target QMAKE_CFLAGS_MT_DBG + \section1 QMAKE_CFLAGS_MT_DBG + + This variable contains the compiler flags for creating a debuggable + multi-threaded application or when the version of Qt that you link + against is a debuggable multi-threaded statically linked library. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target QMAKE_CFLAGS_MT_DLL + \section1 QMAKE_CFLAGS_MT_DLL + + \e {This is used on Windows only.} + + This variable contains the compiler flags for creating a + multi-threaded dll or when the version of Qt that you link + against is a multi-threaded dll. The value of this variable is typically + handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and + rarely needs to be modified. + + \target QMAKE_CFLAGS_MT_DLLDBG + \section1 QMAKE_CFLAGS_MT_DLLDBG + + \e {This is used on Windows only.} + + This variable contains the compiler flags for creating a debuggable + multi-threaded dll or when the version of Qt that you link + against is a debuggable multi-threaded statically linked library. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target QMAKE_CFLAGS_RELEASE + \section1 QMAKE_CFLAGS_RELEASE + + This variable contains the compiler flags for creating a non-debuggable + application. The value of this variable is typically + handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and + rarely needs to be modified. + + \target QMAKE_CFLAGS_SHLIB + \section1 QMAKE_CFLAGS_SHLIB + + \e {This is used on Unix platforms only.} + + This variable contains the compiler flags for creating a shared + library. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs + to be modified. + + \target QMAKE_CFLAGS_THREAD + \section1 QMAKE_CFLAGS_THREAD + + This variable contains the compiler flags for creating a multi-threaded + application. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs + to be modified. + + \target QMAKE_CFLAGS_WARN_OFF + \section1 QMAKE_CFLAGS_WARN_OFF + + This variable is not empty if the warn_off + \l{#TEMPLATE}{TEMPLATE} option is specified. The value of this + variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} + and rarely needs to be modified. + + \target QMAKE_CFLAGS_WARN_ON + \section1 QMAKE_CFLAGS_WARN_ON + + This variable is not empty if the warn_on + \l{#TEMPLATE}{TEMPLATE} option is specified. + The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs + to be modified. + + \target QMAKE_CLEAN + \section1 QMAKE_CLEAN + + This variable contains any files which are not generated files (such as moc and uic + generated files) and object files that should be removed when using "make clean". + + \section1 QMAKE_CXX + + This variable specifies the C++ compiler that will be used when building + projects containing C++ source code. Only the file name of the compiler + executable needs to be specified as long as it is on a path contained + in the \c PATH variable when the Makefile is processed. + + \section1 QMAKE_CXXFLAGS + + This variable contains the C++ compiler flags that are used when building + a project. The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. The flags + specific to debug and release modes can be adjusted by modifying + the \c QMAKE_CXXFLAGS_DEBUG and \c QMAKE_CXXFLAGS_RELEASE variables, + respectively. + + \target QMAKE_CXXFLAGS_DEBUG + \section1 QMAKE_CXXFLAGS_DEBUG + + This variable contains the C++ compiler flags for creating a debuggable + application. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs + to be modified. + + \target QMAKE_CXXFLAGS_MT + \section1 QMAKE_CXXFLAGS_MT + + This variable contains the C++ compiler flags for creating a multi-threaded + application. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs + to be modified. + + \target QMAKE_CXXFLAGS_MT_DBG + \section1 QMAKE_CXXFLAGS_MT_DBG + + This variable contains the C++ compiler flags for creating a debuggable multi-threaded + application. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs + to be modified. + + \target QMAKE_CXXFLAGS_MT_DLL + \section1 QMAKE_CXXFLAGS_MT_DLL + + \c {This is used on Windows only.} + + This variable contains the C++ compiler flags for creating a multi-threaded + dll. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs + to be modified. + + \target QMAKE_CXXFLAGS_MT_DLLDBG + \section1 QMAKE_CXXFLAGS_MT_DLLDBG + + \c {This is used on Windows only.} + + This variable contains the C++ compiler flags for creating a multi-threaded debuggable + dll. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs + to be modified. + + \target QMAKE_CXXFLAGS_RELEASE + \section1 QMAKE_CXXFLAGS_RELEASE + + This variable contains the C++ compiler flags for creating an + application. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs + to be modified. + + \target QMAKE_CXXFLAGS_SHLIB + \section1 QMAKE_CXXFLAGS_SHLIB + + This variable contains the C++ compiler flags for creating a + shared library. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs + to be modified. + + \target QMAKE_CXXFLAGS_THREAD + \section1 QMAKE_CXXFLAGS_THREAD + + This variable contains the C++ compiler flags for creating a + multi-threaded application. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs + to be modified. + + \target QMAKE_CXXFLAGS_WARN_OFF + \section1 QMAKE_CXXFLAGS_WARN_OFF + + This variable contains the C++ compiler flags for suppressing compiler warnings. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target QMAKE_CXXFLAGS_WARN_ON + \section1 QMAKE_CXXFLAGS_WARN_ON + + This variable contains C++ compiler flags for generating compiler warnings. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target QMAKE_DISTCLEAN + \section1 QMAKE_DISTCLEAN + + This variable removes extra files upon the invocation of \c{make distclean}. + + \target QMAKE_EXTENSION_SHLIB + \section1 QMAKE_EXTENSION_SHLIB + + This variable contains the extention for shared libraries. The value of this + variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} + and rarely needs to be modified. + + Note that platform-specific variables that change the extension will override + the contents of this variable. + + \section1 QMAKE_EXT_MOC + + This variable changes the extention used on included moc files. + + See also \l{Configuring qmake's Environment#Extensions}{File Extensions}. + + \section1 QMAKE_EXT_UI + + This variable changes the extention used on /e Designer UI files. + + See also \l{Configuring qmake's Environment#Extensions}{File Extensions}. + + \section1 QMAKE_EXT_PRL + + This variable changes the extention used on created PRL files. + + See also \l{Configuring qmake's Environment#Extensions}{File Extensions}, + \l{Configuring qmake's Environment#libdepend}{Library Dependencies}. + + \section1 QMAKE_EXT_LEX + + This variable changes the extention used on files given to lex. + + See also \l{Configuring qmake's Environment#Extensions}{File Extensions}, + \l{#LEXSOURCES}{LEXSOURCES}. + + \section1 QMAKE_EXT_YACC + This variable changes the extention used on files given to yacc. + + See also \l{Configuring qmake's Environment#Extensions}{File Extensions}, + \l{#YACCSOURCES}{YACCSOURCES}. + + \section1 QMAKE_EXT_OBJ + + This variable changes the extention used on generated object files. + + See also \l{Configuring qmake's Environment#Extensions}{File Extensions}. + + \section1 QMAKE_EXT_CPP + + This variable changes the interpretation of all suffixes in this + list of values as files of type C++ source code. + + See also \l{Configuring qmake's Environment#Extensions}{File Extensions}. + + \section1 QMAKE_EXT_H + + This variable changes the interpretation of all suffixes in this + list of values as files of type C header files. + + See also \l{Configuring qmake's Environment#Extensions}{File Extensions}. + + \section1 QMAKE_EXTRA_COMPILERS + + This variable contains the extra compilers/preprocessors that have been added + + See also \l{Configuring qmake's Environment#Customizing}{Customizing Makefile Output} + + \section1 QMAKE_EXTRA_TARGETS + + This variable contains the extra targets that have been added + + See also \l{Configuring qmake's Environment#Customizing}{Customizing Makefile Output} + + \target QMAKE_FAILED_REQUIREMENTS + \section1 QMAKE_FAILED_REQUIREMENTS + + This variable contains the list of requirements that were failed to be met when + \c qmake was used. For example, the sql module is needed and wasn't compiled into Qt. The + value of this variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} + and rarely needs to be modified. + + \target QMAKE_FILETAGS + \section1 QMAKE_FILETAGS + + This variable contains the file tags needed to be entered into the Makefile, such as SOURCES + and HEADERS. The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_FRAMEWORK_BUNDLE_NAME + + In a framework project, this variable contains the name to be used for the + framework that is built. + + By default, this variable contains the same value as the \l{#TARGET}{TARGET} + variable. + + See \l{qmake Platform Notes#Creating Frameworks}{qmake Platform Notes} for + more information about creating frameworks and library bundles. + + \e{This is used on Mac OS X only.} + + \target QMAKE_FRAMEWORK_VERSION + \section1 QMAKE_FRAMEWORK_VERSION + + For projects where the build target is a Mac OS X framework, this variable + is used to specify the version number that will be applied to the framework + that is built. + + By default, this variable contains the same value as the \l{#VERSION}{VERSION} + variable. + + See \l{qmake Platform Notes#Creating Frameworks}{qmake Platform Notes} for + more information about creating frameworks. + + \e{This is used on Mac OS X only.} + + \target QMAKE_INCDIR + \section1 QMAKE_INCDIR + + This variable contains the location of all known header files to be added to + INCLUDEPATH when building an application. The value of this variable is + typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. + + \target QMAKE_INCDIR_EGL + \section1 QMAKE_INCDIR_EGL + + This variable contains the location of EGL header files to be added + to INCLUDEPATH when building an application with OpenGL/ES or + OpenVG support. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target QMAKE_INCDIR_OPENGL + \section1 QMAKE_INCDIR_OPENGL + + This variable contains the location of OpenGL header files to be added + to INCLUDEPATH when building an application with OpenGL support. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + If the OpenGL implementation uses EGL (most OpenGL/ES systems), + then QMAKE_INCDIR_EGL may also need to be set. + + \target QMAKE_INCDIR_OPENVG + \section1 QMAKE_INCDIR_OPENVG + + This variable contains the location of OpenVG header files to be added + to INCLUDEPATH when building an application with OpenVG support. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + If the OpenVG implementation uses EGL then QMAKE_INCDIR_EGL may also + need to be set. + + \target QMAKE_INCDIR_QT + \section1 QMAKE_INCDIR_QT + + This variable contains the location of all known header file + paths to be added to INCLUDEPATH when building a Qt application. The value + of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target QMAKE_INCDIR_THREAD + \section1 QMAKE_INCDIR_THREAD + + This variable contains the location of all known header file + paths to be added to INCLUDEPATH when building a multi-threaded application. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target QMAKE_INCDIR_X11 + \section1 QMAKE_INCDIR_X11 + + \e {This is used on Unix platforms only.} + + This variable contains the location of X11 header file paths to be + added to INCLUDEPATH when building a X11 application. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target QMAKE_INFO_PLIST + \section1 QMAKE_INFO_PLIST + + \e {This is used on Mac OS X platforms only.} + + This variable contains the name of the property list file, \c{.plist}, you + would like to include in your Mac OS X application bundle. + + In the \c{.plist} file, you can define some variables, e.g., @EXECUTABLE@, + which qmake will replace with the actual executable name. Other variables + include @ICON@, @TYPEINFO@, @LIBRARY@, and @SHORT_VERSION@. + + \note Most of the time, the default \c{Info.plist} is good enough. + + \section1 QMAKE_LFLAGS + + This variable contains a general set of flags that are passed to + the linker. If you need to change the flags used for a particular + platform or type of project, use one of the specialized variables + for that purpose instead of this variable. + + \target QMAKE_LFLAGS_CONSOLE + \section1 QMAKE_LFLAGS_CONSOLE + + \e {This is used on Windows only.} + + This variable contains link flags when building console + programs. The value of this variable is typically handled by + \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LFLAGS_CONSOLE_DLL + + \e {This is used on Windows only.} + + This variable contains link flags when building console + dlls. The value of this variable is typically handled by + \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LFLAGS_DEBUG + + This variable contains link flags when building debuggable applications. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LFLAGS_PLUGIN + + This variable contains link flags when building plugins. The value + of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LFLAGS_QT_DLL + + This variable contains link flags when building programs that + use the Qt library built as a dll. The value of this variable is + typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LFLAGS_RELEASE + + This variable contains link flags when building applications for + release. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LFLAGS_SHAPP + + This variable contains link flags when building applications which are using + the \c app template. The value of this variable is typically handled by + \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LFLAGS_SHLIB + + This variable contains link flags when building shared libraries + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LFLAGS_SONAME + + This variable specifies the link flags to set the name of shared objects, + such as .so or .dll. The value of this variable is typically handled by \c + qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LFLAGS_THREAD + + This variable contains link flags when building multi-threaded projects. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LFLAGS_WINDOWS + + \e {This is used on Windows only.} + + This variable contains link flags when building Windows GUI projects + (i.e. non-console applications). + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LFLAGS_WINDOWS_DLL + + \e {This is used on Windows only.} + + This variable contains link flags when building Windows DLL projects. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBDIR + + This variable contains the location of all known library + directories.The value of this variable is typically handled by + \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBDIR_FLAGS + + \e {This is used on Unix platforms only.} + + This variable contains the location of all library + directory with -L prefixed. The value of this variable is typically handled by + \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBDIR_EGL + + This variable contains the location of the EGL library + directory, when EGL is used with OpenGL/ES or OpenVG. The value + of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBDIR_OPENGL + + This variable contains the location of the OpenGL library + directory.The value of this variable is typically handled by + \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + If the OpenGL implementation uses EGL (most OpenGL/ES systems), + then QMAKE_LIBDIR_EGL may also need to be set. + + \section1 QMAKE_LIBDIR_OPENVG + + This variable contains the location of the OpenVG library + directory. The value of this variable is typically handled by + \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + If the OpenVG implementation uses EGL, then QMAKE_LIBDIR_EGL + may also need to be set. + + \section1 QMAKE_LIBDIR_QT + + This variable contains the location of the Qt library + directory.The value of this variable is typically handled by + \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBDIR_X11 + + \e {This is used on Unix platforms only.} + + This variable contains the location of the X11 library + directory.The value of this variable is typically handled by + \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBS + + This variable contains all project libraries. The value of this + variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBS_CONSOLE + + \e {This Windows-specific variable is no longer used.} + + Prior to Qt 4.2, this variable was used to list the libraries + that should be linked against when building a console application + project on Windows. \l{#QMAKE_LIBS_WINDOW}{QMAKE_LIBS_WINDOW} + should now be used instead. + + \section1 QMAKE_LIBS_EGL + + This variable contains all EGL libraries when building Qt with + OpenGL/ES or OpenVG. The value of this variable is typically + handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely + needs to be modified. The usual value is \c{-lEGL}. + + \section1 QMAKE_LIBS_OPENGL + + This variable contains all OpenGL libraries. The value of this + variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + If the OpenGL implementation uses EGL (most OpenGL/ES systems), + then QMAKE_LIBS_EGL may also need to be set. + + \section1 QMAKE_LIBS_OPENGL_QT + + This variable contains all OpenGL Qt libraries.The value of this + variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBS_OPENVG + + This variable contains all OpenVG libraries. The value of this + variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} + and rarely needs to be modified. The usual value is \c{-lOpenVG}. + + Some OpenVG engines are implemented on top of OpenGL. This will + be detected at configure time and QMAKE_LIBS_OPENGL will be implicitly + added to QMAKE_LIBS_OPENVG wherever the OpenVG libraries are linked. + + If the OpenVG implementation uses EGL, then QMAKE_LIBS_EGL may also + need to be set. + + \section1 QMAKE_LIBS_QT + + This variable contains all Qt libraries.The value of this + variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBS_QT_DLL + + \e {This is used on Windows only.} + + This variable contains all Qt libraries when Qt is built as a dll. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBS_QT_OPENGL + + This variable contains all the libraries needed to link against if + OpenGL support is turned on. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBS_QT_THREAD + + This variable contains all the libraries needed to link against if + thread support is turned on. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBS_RT + + \e {This is used with Borland compilers only.} + + This variable contains the runtime library needed to link against when + building an application. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBS_RTMT + + \e {This is used with Borland compilers only.} + + This variable contains the runtime library needed to link against when + building a multi-threaded application. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBS_THREAD + + \e {This is used on Unix platforms only.} + + This variable contains all libraries that need to be linked against + when building a multi-threaded application. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBS_WINDOWS + + \e {This is used on Windows only.} + + This variable contains all windows libraries.The value of this + variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBS_X11 + + \e {This is used on Unix platforms only.} + + This variable contains all X11 libraries.The value of this + variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIBS_X11SM + + \e {This is used on Unix platforms only.} + + This variable contains all X11 session management libraries. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LIB_FLAG + + This variable is not empty if the \c lib template is specified. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_LINK_SHLIB_CMD + + This variable contains the command to execute when creating a + shared library. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_POST_LINK + + This variable contains the command to execute after linking the TARGET + together. This variable is normally empty and therefore nothing is + executed, additionally some backends will not support this - mostly only + Makefile backends. + + \section1 QMAKE_PRE_LINK + + This variable contains the command to execute before linking the TARGET + together. This variable is normally empty and therefore nothing is + executed, additionally some backends will not support this - mostly only + Makefile backends. + + \section1 QMAKE_LN_SHLIB + + This variable contains the command to execute when creating a link + to a shared library. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_MAC_SDK + + This variable is used on Mac OS X when building universal binaries. + This process is described in more detail in the + \l{Deploying an Application on Mac OS X#Architecture Dependencies}{Deploying + an Application on Mac OS X} document. + + \section1 QMAKE_MACOSX_DEPLOYMENT_TARGET + This variable only has an effect when building on Mac OS X. On that + platform, the variable will be forwarded to the MACOSX_DEPLOYMENT_TARGET + environment variable, which is interpreted by the compiler or linker. + For more information, see the + \l{Deploying an Application on Mac OS X#Mac OS X Version Dependencies}{Deploying + an Application on Mac OS X} document. + + \section1 QMAKE_MAKEFILE + + This variable contains the name of the Makefile to create. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_MOC_SRC + + This variable contains the names of all moc source files to + generate and include in the project. The value of this variable is + typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_QMAKE + + This variable contains the location of qmake if it is not in the path. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_QT_DLL + + This variable is not empty if Qt was built as a dll. The + value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_RESOURCE_FLAGS + + This variable is used to customize the list of options passed to the + \l{rcc}{Resource Compiler} in each of the build rules where it is used. + For example, the following line ensures that the \c{-threshold} and + \c{-compress} options are used with particular values each time that + \c rcc is invoked: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 45 + + \section1 QMAKE_RUN_CC + + This variable specifies the individual rule needed to build an object. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_RUN_CC_IMP + + This variable specifies the individual rule needed to build an object. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_RUN_CXX + + This variable specifies the individual rule needed to build an object. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_RUN_CXX_IMP + + This variable specifies the individual rule needed to build an object. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_TARGET + + This variable contains the name of the project target. The value of + this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 QMAKE_UIC + + This variable contains the location of uic if it is not in the path. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + It can be used to specify arguments to uic as well, such as additional plugin + paths. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 46 + + \section1 QT + + The values stored in the \c QT variable control which of the Qt modules are + used by your project. + + The table below shows the options that can be used with the \c QT variable + and the features that are associated with each of them: + + \table + \header \o Option \o Features + \row \o core (included by default) \o QtCore module + \row \o gui (included by default) \o QtGui module + \row \o network \o QtNetwork module + \row \o opengl \o QtOpenGL module + \row \o phonon \o Phonon Multimedia Framework + \row \o sql \o QtSql module + \row \o svg \o QtSvg module + \row \o xml \o QtXml module + \row \o webkit \o WebKit integration + \row \o qt3support \o Qt3Support module + \endtable + + By default, \c QT contains both \c core and \c gui, ensuring that standard + GUI applications can be built without further configuration. + + If you want to build a project \e without the QtGui module, you need to + exclude the \c gui value with the "-=" operator; the following line will + result in a minimal Qt project being built: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 47 + + Note that adding the \c opengl option to the \c QT variable automatically + causes the equivalent option to be added to the \c CONFIG variable. + Therefore, for Qt applications, it is not necessary to add the \c opengl + option to both \c CONFIG and \c{QT}. + + \section1 QTPLUGIN + + This variable contains a list of names of static plugins that are to be + compiled with an application so that they are available as built-in + resources. + + \target QT_VERSION + \section1 QT_VERSION + + This variable contains the current version of Qt. + + \target QT_MAJOR_VERSION + \section1 QT_MAJOR_VERSION + + This variable contains the current major version of Qt. + + \target QT_MINOR_VERSION + \section1 QT_MINOR_VERSION + + This variable contains the current minor version of Qt. + + \target QT_PATCH_VERSION + \section1 QT_PATCH_VERSION + + This variable contains the current patch version of Qt. + + \section1 RC_FILE + + This variable contains the name of the resource file for the application. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target RCC_DIR + \section1 RCC_DIR + + This variable specifies the directory where all intermediate + resource files should be placed. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 48 + + \target REQUIRES + \section1 REQUIRES + + This is a special variable processed by \c qmake. If the + contents of this variable do not appear in CONFIG by the time this + variable is assigned, then a minimal Makefile will be generated that + states what dependencies (the values assigned to REQUIRES) are + missing. + + This is mainly used in Qt's build system for building the examples. + + \section1 RESOURCES + + This variable contains the name of the resource collection file (qrc) + for the application. Further information about the resource collection + file can be found at \l{The Qt Resource System}. + + \section1 RES_FILE + + This variable contains the name of the resource file for the application. + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target SIGNATURE_FILE + \section1 SIGNATURE_FILE + + \e {This is only used on Windows CE.} + + Specifies which signature file should be used to sign the project target. + + \note This variable will overwrite the setting you have specified in configure, + with the \c -signature option. + + \target SOURCES + \section1 SOURCES + + This variable contains the name of all source files in the project. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 49 + + See also \l{#HEADERS}{HEADERS} + + \section1 SRCMOC + + This variable is set by \c qmake if files can be found that + contain the Q_OBJECT macro. \c SRCMOC contains the + name of all the generated moc files. The value of this variable + is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be + modified. + + \target SUBDIRS + \section1 SUBDIRS + + This variable, when used with the \l{#TEMPLATE}{\c subdirs template} + contains the names of all subdirectories that contain parts of the project + that need be built. Each subdirectory must contain its own project file. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 50 + + It is essential that the project file in each subdirectory has the same + name as the subdirectory itself, so that \c qmake can find it. + For example, if the subdirectory is called \c myapp then the project file + in that directory should be called \c myapp.pro. + + If you need to ensure that the subdirectories are built in the order in + which they are specified, update the \l{#CONFIG}{CONFIG} variable to + include the \c ordered option: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 51 + + \target TARGET + \section1 TARGET + + This specifies the name of the target file. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 52 + + The project file above would produce an executable named \c myapp on + unix and 'myapp.exe' on windows. + + \section1 TARGET_EXT + + This variable specifies the target's extension. The value of this variable + is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be + modified. + + \section1 TARGET_x + + This variable specifies the target's extension with a major version number. The value of this variable + is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be + modified. + + \section1 TARGET_x.y.z + + This variable specifies the target's extension with version number. The value of this variable + is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be + modified. + + \target TEMPLATE + \section1 TEMPLATE + + This variable contains the name of the template to use when + generating the project. The allowed values are: + + \table + \header \o Option \o Description + \row \o app \o Creates a Makefile for building applications (the default). (See + \l{qmake Common Projects#Application}{qmake Common Projects} for more information.) + \row \o lib \o Creates a Makefile for building libraries. (See + \l{qmake Common Projects#Library}{qmake Common Projects} for more information.) + \row \o subdirs \o Creates a Makefile for building targets in subdirectories. + The subdirectories are specified using the \l{#SUBDIRS}{SUBDIRS} + variable. + \row \o vcapp \o \e {Windows only} Creates an application project for Visual Studio. + (See \l{qmake Platform Notes#Creating Visual Studio Project Files}{qmake Platform Notes} + for more information.) + \row \o vclib \o \e {Windows only} Creates a library project for Visual Studio. + (See \l{qmake Platform Notes#Creating Visual Studio Project Files}{qmake Platform Notes} + for more information.) + \endtable + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 53 + + The template can be overridden by specifying a new template type with the + \c -t command line option. This overrides the template type \e after the .pro + file has been processed. With .pro files that use the template type to + determine how the project is built, it is necessary to declare TEMPLATE on + the command line rather than use the \c -t option. + + \section1 TRANSLATIONS + + This variable contains a list of translation (.ts) files that contain + translations of the user interface text into non-native languages. + + See the \l{Qt Linguist Manual} for more information about + internationalization (i18n) and localization (l10n) with Qt. + + \section1 UICIMPLS + + This variable contains a list of the generated implementation files by UIC. + The value of this variable + is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be + modified. + + \section1 UICOBJECTS + + This variable is generated from the UICIMPLS variable. The extension of each + file will have been replaced by .o (Unix) or .obj (Win32). The value of this variable is + typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and + rarely needs to be modified. + + \target UI_DIR + \section1 UI_DIR + + This variable specifies the directory where all intermediate files from uic + should be placed. This variable overrides both UI_SOURCES_DIR and + UI_HEADERS_DIR. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 54 + + \target UI_HEADERS_DIR + \section1 UI_HEADERS_DIR + + This variable specifies the directory where all declaration files (as + generated by uic) should be placed. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 55 + + \target UI_SOURCES_DIR + \section1 UI_SOURCES_DIR + + This variable specifies the directory where all implementation files (as generated + by uic) should be placed. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 56 + + \target VERSION + \section1 VERSION + + This variable contains the version number of the application or library if + either the \c app \l{#TEMPLATE}{TEMPLATE} or the \c lib \l{#TEMPLATE}{TEMPLATE} + is specified. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 57 + + \section1 VER_MAJ + + This variable contains the major version number of the library, if the + \c lib \l{#TEMPLATE}{template} is specified. + + \section1 VER_MIN + + This variable contains the minor version number of the library, if the + \c lib \l{#TEMPLATE}{template} is specified. + + \section1 VER_PAT + + This variable contains the patch version number of the library, if the + \c lib \l{#TEMPLATE}{template} is specified. + + \section1 VPATH + + This variable tells \c qmake where to search for files it cannot + open. With this you may tell \c qmake where it may look for things + like SOURCES, and if it finds an entry in SOURCES that cannot be + opened it will look through the entire VPATH list to see if it can + find the file on its own. + + See also \l{#DEPENDPATH}{DEPENDPATH}. + + \section1 YACCIMPLS + + This variable contains a list of yacc source files. The value of + this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \section1 YACCOBJECTS + + This variable contains a list of yacc object files. The value of + this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + \target YACCSOURCES + \section1 YACCSOURCES + + This variable contains a list of yacc source files to be included + in the project. All dependencies, headers and source files will + automatically be included in the project. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 58 + + \section1 _PRO_FILE_ + + This variable contains the path to the project file in use. + + For example, the following line causes the location of the project + file to be written to the console: + + \snippet doc/src/snippets/qmake/project_location.pro project file + + \section1 _PRO_FILE_PWD_ + + This variable contains the path to the directory containing the project + file in use. + + For example, the following line causes the location of the directory + containing the project file to be written to the console: + + \snippet doc/src/snippets/qmake/project_location.pro project file directory +*/ + +/*! + \page qmake-function-reference.html + \title qmake Function Reference + \contentspage {qmake Manual}{Contents} + \previouspage qmake Variable Reference + \nextpage Configuring qmake's Environment + + \c qmake provides built-in functions to allow the contents of + variables to be processed, and to enable tests to be performed + during the configuration process. Functions that process the + contents of variables typically return values that can be assigned + to other variables, and these values are obtained by prefixing + function with the \c $$ operator. Functions that perform tests + are usually used as the conditional parts of scopes; these are + indicated in the function descriptions below. + + \tableofcontents{2} + + \section1 basename(variablename) + + Returns the basename of the file specified. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 59 + + \section1 CONFIG(config) + [Conditional] + + This function can be used to test for variables placed into the + \c CONFIG variable. This is the same as regular old style (tmake) scopes, + but has the added advantage a second parameter can be passed to test for + the active config. As the order of values is important in \c CONFIG + variables (i.e. the last one set will be considered the active config for + mutually exclusive values) a second parameter can be used to specify a set + of values to consider. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 60 + + Because release is considered the active setting (for feature parsing) + it will be the CONFIG used to generate the build file. In the common + case a second parameter is not needed, but for specific mutual + exclusive tests it is invaluable. + + \section1 contains(variablename, value) + [Conditional] + + Succeeds if the variable \e variablename contains the value \e value; + otherwise fails. You can check the return value of this function using + a scope. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 61 + + The contents of the scope are only processed if the \c drivers + variable contains the value, \c network. If this is the case, the + appropriate files are added to the \c SOURCES and \c HEADERS + variables. + + \section1 count(variablename, number) + [Conditional] + + Succeeds if the variable \e variablename contains a list with the + specified \e number of value; otherwise fails. + + This function is used to ensure that declarations inside a scope are + only processed if the variable contains the correct number of values; + for example: + + \snippet doc/src/snippets/qmake/functions.pro 2 + + \section1 dirname(file) + + Returns the directory name part of the specified file. For example: + + \snippet doc/src/snippets/qmake/dirname.pro 0 + + \section1 error(string) + + This function never returns a value. \c qmake displays the given + \e string to the user, and exits. This function should only be used + for unrecoverable errors. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 62 + + \section1 eval(string) + [Conditional] + + Evaluates the contents of the string using \c qmake's syntax rules + and returns true. + Definitions and assignments can be used in the string to modify the + values of existing variables or create new definitions. + + For example: + \snippet doc/src/snippets/qmake/functions.pro 4 + + Note that quotation marks can be used to delimit the string, and that + the return value can be discarded if it is not needed. + + \section1 exists(filename) + [Conditional] + + Tests whether a file with the given \e filename exists. + If the file exists, the function succeeds; otherwise it fails. + If a regular expression is specified for the filename, this function + succeeds if any file matches the regular expression specified. + + For example: + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 63 + + Note that "/" can be used as a directory separator, regardless of the + platform in use. + + \section1 find(variablename, substr) + + Places all the values in \e variablename that match \e substr. \e + substr may be a regular expression, and will be matched accordingly. + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 64 + + MY_VAR2 will contain '-Lone -Ltwo -Lthree -Lfour -Lfive', and MY_VAR3 will + contains 'three two three'. + + \section1 for(iterate, list) + + This special test function will cause a loop to be started that + iterates over all values in \e list, setting \e iterate to each + value in turn. As a convenience, if \e list is 1..10 then iterate will + iterate over the values 1 through 10. + + The use of an else scope afer a condition line with a for() loop is + disallowed. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 65 + + \section1 include(filename) + [Conditional] + + Includes the contents of the file specified by \e filename into the + current project at the point where it is included. This function + succeeds if \e filename is included; otherwise it fails. The included + file is processed immediately. + + You can check whether the file was included by using this function as + the condition for a scope; for example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 66 + + \section1 infile(filename, var, val) + [Conditional] + + Succeeds if the file \e filename (when parsed by \c qmake itself) + contains the variable \e var with a value of \e val; otherwise fails. + If you do not specify a third argument (\e val), the function will + only test whether \e var has been declared in the file. + + \section1 isEmpty(variablename) + [Conditional] + + Succeeds if the variable \e variablename is empty; otherwise fails. + This is the equivalent of \c{count( variablename, 0 )}. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 67 + + \section1 join(variablename, glue, before, after) + + Joins the value of \e variablename with \c glue. If this value is + non-empty it prefixes the value with \e before and suffix it with \e + after. \e variablename is the only required field, the others default + to empty strings. If you need to encode spaces in \e glue, \e before, or \e + after you must quote them. + + \section1 member(variablename, position) + + Returns the value at the given \e position in the list of items in + \e variablename. + If an item cannot be found at the position specified, an empty string is + returned. \e variablename is the only required field. If not specified, + \c position defaults to 0, causing the first value in the list to be + returned. + + \section1 message(string) + + This function simply writes a message to the console. Unlike the + \c error() function, this function allows processing to continue. + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 68 + + The above line causes "This is a message" to be written to the console. + The use of quotation marks is optional. + + \note By default, messages are written out for each Makefile generated by + qmake for a given project. If you want to ensure that messages only appear + once for each project, test the \c build_pass variable + \l{qmake Advanced Usage}{in conjunction with a scope} to filter out + messages during builds; for example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 69 + + \section1 prompt(question) + + Displays the specified \e question, and returns a value read from stdin. + + \section1 quote(string) + + Converts a whole \e string into a single entity and returns the result. + Newlines, carriage returns, and tabs can be specified in the string + with \\n \\r and \\t. The return value does not contain either single + or double quotation marks unless you explicitly include them yourself, + but will be placed into a single entry (for literal expansion). + + \section1 replace(string, old_string, new_string) + + Replaces each instance of \c old_string with \c new_string in the + contents of the variable supplied as \c string. For example, the + code + + \snippet doc/src/snippets/qmake/replace.pro 0 + + prints the message: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 70 + + \section1 sprintf(string, arguments...) + + Replaces %1-%9 with the arguments passed in the comma-separated list + of function \e arguments and returns the processed string. + + \section1 system(command) + [Conditional] + + Executes the given \c command in a secondary shell, and succeeds + if the command returns with a zero exit status; otherwise fails. + You can check the return value of this function using a scope: + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 71 + + Alternatively, you can use this function to obtain stdout and stderr + from the command, and assign it to a variable. For example, you can + use this to interrogate information about the platform: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 72 + + \target unique + \section1 unique(variablename) + + This will return a list of values in variable that are unique (that is + with repetitive entries removed). For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 73 + + \section1 warning(string) + + This function will always succeed, and will display the given + \e string to the user. message() is a synonym for warning(). +*/ + +/*! + \page qmake-environment-reference.html + \contentspage {qmake Manual}{Contents} + \previouspage qmake Function Reference + + \title Configuring qmake's Environment + + \tableofcontents + + \target Properties + \section1 Properties + + \c qmake has a system of persistant information, this allows you to + \c set a variable in qmake once, and each time qmake is invoked this + value can be queried. Use the following to set a property in qmake: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 74 + + The appropriate variable and value should be substituted for + \c VARIABLE and \c VALUE. + + To retrieve this information back from qmake you can do: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 75 + + \note \c{qmake -query} will only list variables that you have + previously set with \c{qmake -set VARIABLE VALUE}. + + This information will be saved into a QSettings object (meaning it + will be stored in different places for different platforms). As + \c VARIABLE is versioned as well, you can set one value in an older + version of \c qmake, and newer versions will retrieve this value. However, + if you set \c VARIABLE for a newer version of \c qmake, the older version + will not use this value. You can however query a specific version of a + variable if you prefix that version of \c qmake to \c VARIABLE, as in + the following example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 76 + + \c qmake also has the notion of \c builtin properties, for example you can + query the installation of Qt for this version of \c qmake with the + \c QT_INSTALL_PREFIX property: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 77 + + These built-in properties cannot have a version prefixed to them as + they are not versioned, and each version of \c qmake will have its own + built-in set of these values. The list below outlines the built-in + properties: + + \list + \o \c QT_INSTALL_PREFIX - Where the version of Qt this qmake is built for resides + \o \c QT_INSTALL_DATA - Where data for this version of Qt resides + \o \c QMAKE_VERSION - The current version of qmake + \endlist + + Finally, these values can be queried in a project file with a special + notation such as: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 78 + + \target QMAKESPEC + \section1 QMAKESPEC + + \c qmake requires a platform and compiler description file which + contains many default values used to generate appropriate Makefiles. + The standard Qt distribution comes with many of these files, located + in the \c mkspecs subdirectory of the Qt installation. + + The \c QMAKESPEC environment variable can contain any of the following: + + \list + \o A complete path to a directory containing a \c{qmake.conf} file. + In this case \c qmake will open the \c{qmake.conf} file from within that + directory. If the file does not exist, \c qmake will exit with an + error. + \o The name of a platform-compiler combination. In this case, \c qmake + will search in the directory specified by the \c mkspecs subdirectory + of the data path specified when Qt was compiled (see + QLibraryInfo::DataPath). + \endlist + + \bold{Note:} The \c QMAKESPEC path will automatically be added to the + \l{qmake Variable Reference#INCLUDEPATH}{INCLUDEPATH} system variable. + + \target INSTALLS + \section1 INSTALLS + + It is common on Unix to also use the build tool to install applications + and libraries; for example, by invoking \c{make install}. For this reason, + \c qmake has the concept of an install set, an object which contains + instructions about the way part of a project is to be installed. + For example, a collection of documentation files can be described in the + following way: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 79 + + The \c path member informs \c qmake that the files should be installed in + \c /usr/local/program/doc (the path member), and the \c files member + specifies the files that should be copied to the installation directory. + In this case, everything in the \c docs directory will be coped to + \c /usr/local/program/doc. + + Once an install set has been fully described, you can append it to the + install list with a line like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 80 + + \c qmake will ensure that the specified files are copied to the installation + directory. If you require greater control over this process, you can also + provide a definition for the \c extra member of the object. For example, + the following line tells \c qmake to execute a series of commands for this + install set: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 81 + + The \c unix scope + (see \l{qmake Advanced Usage#Scopes and Conditions}{Scopes and Conditions}) + ensures that these particular commands are only executed on Unix platforms. + Appropriate commands for other platforms can be defined using other scope + rules. + + Commands specified in the \c extra member are executed before the instructions + in the other members of the object are performed. + + If you append a built-in install set to the \c INSTALLS variable and do + not specify \c files or \c extra members, \c qmake will decide what needs to + be copied for you. Currently, the only supported built-in install set is + \c target: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 82 + + In the above lines, \c qmake knows what needs to be copied, and will handle + the installation process automatically. + + \target cache + \section1 Cache File + + The cache file is a special file \c qmake reads to find settings not specified + in the \c qmake.conf file, project files, or at the command line. If + \c -nocache is not specified when \c qmake is run, it will try to find a file + called \c{.qmake.cache} in parent directories of the current directory. If + it fails to find this file, it will silently ignore this step of processing. + + If it finds a \c{.qmake.cache} file then it will process this file first before + it processes the project file. + + \target LibDepend + \section1 Library Dependencies + + Often when linking against a library, \c qmake relies on the underlying + platform to know what other libraries this library links against, and + lets the platform pull them in. In many cases, however, this is not + sufficent. For example, when statically linking a library, no other + libraries are linked to, and therefore no dependencies to those + libraries are created. However, an application that later links + against this library will need to know where to find the symbols that + the static library will require. To help with this situation, \c qmake + attempts to follow a library's dependencies where appropriate, but + this behavior must be explicitly enabled by following two steps. + + The first step is to enable dependency tracking in the library itself. + To do this you must tell \c qmake to save information about the library: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 83 + + This is only relevant to the \c lib template, and will be ignored for + all others. When this option is enabled, \c qmake will create a file + ending in .prl which will save some meta-information about the + library. This metafile is just like an ordinary project file, but only + contains internal variable declarations. You are free to view this file + and, if it is deleted, \c qmake will know to recreate it when necessary, + either when the project file is later read, or if a dependent library + (described below) has changed. When installing this library, by + specifying it as a target in an \c INSTALLS declaration, \c qmake will + automatically copy the .prl file to the installation path. + + The second step in this process is to enable reading of this meta + information in the applications that use the static library: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 84 + + When this is enabled, \c qmake will process all libraries linked to + by the application and find their meta-information. \c qmake will use + this to determine the relevant linking information, specifically adding + values to the application project file's list of \c DEFINES as well as + \c LIBS. Once \c qmake has processed this file, it will then look through + the newly introduced libraries in the \c LIBS variable, and find their + dependent .prl files, continuing until all libraries have been resolved. + At this point, the Makefile is created as usual, and the libraries are + linked explicitlyy against the application. + + The internals of the .prl file are left closed so they can easily + change later. They are not designed to be changed by hand, should only + be created by \c qmake, and should not be transferred between operating + systems as they may contain platform-dependent information. + + \target Extensions + \section1 File Extensions + + Under normal circumstances \c qmake will try to use appropriate file extensions + for your platform. However, it is sometimes necessary to override the default + choices for each platform and explicitly define file extensions for \c qmake to use. + This is achieved by redefining certain built-in variables; for example the extension + used for \l moc files can be redefined with the following assignment in a project + file: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 85 + + The following variables can be used to redefine common file extensions recognized + by \c qmake: + + \list + \o QMAKE_EXT_MOC - This modifies the extension placed on included moc files. + \o QMAKE_EXT_UI - This modifies the extension used for designer UI files (usually + in \c FORMS). + \o QMAKE_EXT_PRL - This modifies the extension placed on + \l{#LibDepend}{library dependency files}. + \o QMAKE_EXT_LEX - This changes the suffix used in files (usually in \c LEXSOURCES). + \o QMAKE_EXT_YACC - This changes the suffix used in files (usually in \c YACCSOURCES). + \o QMAKE_EXT_OBJ - This changes the suffix used on generated object files. + \endlist + + All of the above accept just the first value, so you must assign to it just one + value that will be used throughout your project file. There are two variables that + accept a list of values: + + \list + \o QMAKE_EXT_CPP - Causes \c qmake to interpret all files with these suffixes as + C++ source files. + \o QMAKE_EXT_H - Causes \c qmake to interpret all files with these suffixes as + C and C++ header files. + \endlist + + \target Customizing + \section1 Customizing Makefile Output + + \c qmake tries to do everything expected of a cross-platform build tool. + This is often less than ideal when you really need to run special + platform-dependent commands. This can be achieved with specific instructions + to the different \c qmake backends. + + Customization of the Makefile output is performed through an object-style + API as found in other places in \c qmake. Objects are defined automatically + by specifying their members; for example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 86 + + The definitions above define a \c qmake target called \c mytarget, containing + a Makefile target called \c{.buildfile} which in turn is generated with + the \c touch command. Finally, the \c{.depends} member specifies that + \c mytarget depends on \c mytarget2, another target that is defined afterwards. + \c mytarget2 is a dummy target; it is only defined to echo some text to + the console. + + The final step is to instruct \c qmake that this object is a target to be built: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 87 + + This is all you need to do to actually build custom targets. Of course, you may + want to tie one of these targets to the + \l{qmake Variable Reference#TARGET}{qmake build target}. To do this, you simply need to + include your Makefile target in the list of + \l{qmake Variable Reference#PRE_TARGETDEPS}{PRE_TARGETDEPS}. + + The following tables are an overview of the options available to you with the QMAKE_EXTRA_TARGETS + variable. + + \table + \header + \o Member + \o Description + \row + \o commands + \o The commands for generating the custom build target. + \row + \o CONFIG + \o Specific configuration options for the custom build target. See the CONFIG table for details. + \row + \o depends + \o The existing build targets that the custom build target depends on. + \row + \o recurse + \o Specifies which sub-targets should used when creating the rules in the Makefile to call in + the sub-target specific Makefile. This is only used when \c recursive is set in the CONFIG. + \row + \o recurse_target + \o Specifies the target that should be built via the sub-target Makefile for the rule in the Makefile. + This adds something like $(MAKE) -f Makefile.[subtarget] [recurse_target]. This is only used when + \c recursive is set in the CONFIG. + \row + \o target + \o The file being created by the custom build target. + \endtable + + List of members specific to the CONFIG option: + + \table + \header + \o Member + \o Description + \row + \o recursive + \o Indicates that rules should be created in the Makefile and thus call + the relevant target inside the sub-target specific Makefile. This defaults to creating + an entry for each of the sub-targets. + \endtable + + For convenience, there is also a method of customizing projects + for new compilers or preprocessors: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 88 + + With the above definitions, you can use a drop-in replacement for moc if one + is available. The commands is executed on all arguments given to the + \c NEW_HEADERS variable (from the \c input member), and the result is written + to the file defined by the \c output member; this file is added to the + other source files in the project. + Additionally, \c qmake will execute \c depend_command to generate dependency + information, and place this information in the project as well. + + These commands can easily be placed into a cache file, allowing subsequent + project files to add arguments to \c NEW_HEADERS. + + The following tables are an overview of the options available to you with the QMAKE_EXTRA_COMPILERS + variable. + + \table + \header + \o Member + \o Description + \row + \o commands + \o The commands used for for generating the output from the input. + \row + \o CONFIG + \o Specific configuration options for the custom compiler. See the CONFIG table for details. + \row + \o depend_command + \o Specifies a command used to generate the list of dependencies for the output. + \row + \o dependency_type + \o Specifies the type of file the output is, if it is a known type (such as TYPE_C, + TYPE_UI, TYPE_QRC) then it is handled as one of those type of files. + \row + \o depends + \o Specifies the dependencies of the output file. + \row + \o input + \o The variable that contains the files that should be processed with the custom compiler. + \row + \o name + \o A description of what the custom compiler is doing. This is only used in some backends. + \row + \o output + \o The filename that is created from the custom compiler. + \row + \o output_function + \o Specifies a custom qmake function that is used to specify the filename to be created. + \row + \o variable_out + \o The variable that the files created from the output should be added to. + \endtable + + List of members specific to the CONFIG option: + + \table + \header + \o Member + \o Description + \row + \o combine + \o Indicates that all of the input files are combined into a single output file. + \row + \o target_predeps + \o Indicates that the output should be added to the list of PRE_TARGETDEPS. + \row + \o explicit_dependencies + \o The dependencies for the output only get generated from the depends member and from + nowhere else. + \row + \o no_link + \o Indicates that the output should not be added to the list of objects to be linked in + \endtable +*/ + +/*! + \page qmake-advanced-usage.html + \title qmake Advanced Usage + \contentspage {qmake Manual}{Contents} + \previouspage qmake Platform Notes + \nextpage Using Precompiled Headers + + Many \c qmake project files simply describe the sources and header files used + by the project, using a list of \c{name = value} and \c{name += value} + definitions. \c qmake also provides other operators, functions, and scopes + that can be used to process the information supplied in variable declarations. + These advanced features allow Makefiles to be generated for multiple platforms + from a single project file. + + \tableofcontents + + \section1 Operators + + In many project files, the assignment (\c{=}) and append (\c{+=}) operators can + be used to include all the information about a project. The typical pattern of + use is to assign a list of values to a variable, and append more values + depending on the result of various tests. Since \c qmake defines certain + variables using default values, it is sometimes necessary to use the removal + (\c{-=}) operator to filter out values that are not required. The following + operators can be used to manipulate the contents of variables. + + The \c = operator assigns a value to a variable: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 89 + + The above line sets the \c TARGET variable to \c myapp. This will overwrite any + values previously set for \c TARGET with \c myapp. + + The \c += operator appends a new value to the list of values in a variable: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 90 + + The above line appends \c QT_DLL to the list of pre-processor defines to be put + in the generated Makefile. + + The \c -= operator removes a value from the list of values in a variable: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 91 + + The above line removes \c QT_DLL from the list of pre-processor defines to be + put in the generated Makefile. + + The \c *= operator adds a value to the list of values in a variable, but only + if it is not already present. This prevents values from being included many + times in a variable. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 92 + + In the above line, \c QT_DLL will only be added to the list of pre-processor + defines if it is not already defined. Note that the + \l{qmake Function Reference#unique}{unique()} + function can also be used to ensure that a variables only contains one + instance of each value. + + The \c ~= operator replaces any values that match a regular expression with + the specified value: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 93 + + In the above line, any values in the list that start with \c QT_D or \c QT_T are + replaced with \c QT. + + The \c $$ operator is used to extract the contents of a variable, and can be + used to pass values between variables or supply them to functions: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 94 + + \target Scopes + \section1 Scopes + + Scopes are similar to \c if statements in procedural programming languages. + If a certain condition is true, the declarations inside the scope are processed. + + \section2 Syntax + + Scopes consist of a condition followed by an opening brace on the same line, + a sequence of commands and definitions, and a closing brace on a new line: + + \snippet doc/src/snippets/qmake/scopes.pro syntax + + The opening brace \e{must be written on the same line as the condition}. + Scopes may be concatenated to include more than one condition; see below + for examples. + + \section2 Scopes and Conditions + + A scope is written as a condition followed by a series of declarations + contained within a pair of braces; for example: + + \snippet doc/src/snippets/qmake/scopes.pro 0 + + The above code will add the \c paintwidget_win.cpp file to the sources listed + in the generated Makefile if \c qmake is used on a Windows platform. + If \c qmake is used on a platform other than Windows, the define will be + ignored. + + The conditions used in a given scope can also be negated to provide an + alternative set of declarations that will be processed only if the + original condition is false. For example, suppose we want to process + something on all platforms \e except for Windows. We can achieve this by + negating the scope like this: + + \snippet doc/src/snippets/qmake/scopes.pro 1 + + Scopes can be nested to combine more than one condition. For instance, if + you want to include a particular file for a certain platform only if + debugging is enabled then you write the following: + + \snippet doc/src/snippets/qmake/scopes.pro 2 + + To save writing many nested scopes, you can nest scopes using the \c : + operator. The nested scopes in the above example can be rewritten in + the following way: + + \snippet doc/src/snippets/qmake/scopes.pro 3 + + You may also use the \c : operator to perform single line conditional + assignments; for example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 95 + + The above line adds \c QT_DLL to the \c DEFINES variable only on the + Windows platform. + Generally, the \c : operator behaves like a logical AND operator, joining + together a number of conditions, and requiring all of them to be true. + + There is also the \c | operator to act like a logical OR operator, joining + together a number of conditions, and requiring only one of them to be true. + + \snippet doc/src/snippets/qmake/scopes.pro 4 + + You can also provide alternative declarations to those within a scope by + using an \c else scope. Each \c else scope is processed if the conditions + for the preceding scopes are false. + This allows you to write complex tests when combined with other scopes + (separated by the \c : operator as above). For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 96 + + \section2 Configuration and Scopes + + The values stored in the + \l{qmake-project-files.html#GeneralConfiguration}{\c CONFIG variable} + are treated specially by \c qmake. Each of the possible values can be + used as the condition for a scope. For example, the list of values + held by \c CONFIG can be extended with the \c opengl value: + + \snippet doc/src/snippets/qmake/configscopes.pro 0 + + As a result of this operation, any scopes that test for \c opengl will + be processed. We can use this feature to give the final executable an + appropriate name: + + \snippet doc/src/snippets/qmake/configscopes.pro 1 + \snippet doc/src/snippets/qmake/configscopes.pro 2 + \snippet doc/src/snippets/qmake/configscopes.pro 3 + + This feature makes it easy to change the configuration for a project + without losing all the custom settings that might be needed for a specific + configuration. In the above code, the declarations in the first scope are + processed, and the final executable will be called \c application-gl. + However, if \c opengl is not specified, the declarations in the second + scope are processed instead, and the final executable will be called + \c application. + + Since it is possible to put your own values on the \c CONFIG + line, this provides you with a convenient way to customize project files + and fine-tune the generated Makefiles. + + \section2 Platform Scope Values + + In addition to the \c win32, \c macx, and \c unix values used in many + scope conditions, various other built-in platform and compiler-specific + values can be tested with scopes. These are based on platform + specifications provided in Qt's \c mkspecs directory. For example, the + following lines from a project file show the current specification in + use and test for the \c linux-g++ specification: + + \snippet doc/src/snippets/qmake/specifications.pro 0 + + You can test for any other platform-compiler combination as long as a + specification exists for it in the \c mkspecs directory. + + \section1 Variables + + Many of the variables used in project files are special variables that + \c qmake uses when generating Makefiles, such as \c DEFINES, \c SOURCES, + and \c HEADERS. It is possible for you to create variables for your own + use; \c qmake creates new variables with a given name when it encounters + an assignment to that name. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 97 + + There are no restricitions on what you do to your own variables, as \c + qmake will ignore them unless it needs to evaluate them when processing + a scope. + + You can also assign the value of a current variable to another + variable by prefixing $$ to the variable name. For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 98 + + Now the MY_DEFINES variable contains what is in the DEFINES variable at + this point in the project file. This is also equivalent to: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 99 + + The second notation allows you to append the contents of the variable to + another value without separating the two with a space. For example, the + following will ensure that the final executable will be given a name + that includes the project template being used: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 100 + + Variables can be used to store the contents of environment variables. + These can be evaluated at the time that \c qmake is run, or included + in the generated Makefile for evaluation when the project is built. + + To obtain the contents of an environment value when \c qmake is run, + use the \c $$(...) operator: + + \snippet doc/src/snippets/qmake/environment.pro 0 + + In the above assignment, the value of the \c PWD environment variable + is read when the project file is processed. + + To obtain the contents of an environment value at the time when the + generated Makefile is processed, use the \c $(...) operator: + + \snippet doc/src/snippets/qmake/environment.pro 1 + + In the above assignment, the value of \c PWD is read immediately + when the project file is processed, but \c $(PWD) is assigned to + \c DESTDIR in the generated Makefile. This makes the build process + more flexible as long as the environment variable is set correctly + when the Makefile is processed. + + The special \c $$[...] operator can be used to access various + configuration options that were set when Qt was built: + + \snippet doc/src/snippets/qmake/qtconfiguration.pro 0 + + The variables accessible with this operator are typically used to + enable third party plugins and components to be integrated with Qt. + For example, a \QD plugin can be installed alongside \QD's built-in + plugins if the following declaration is made in its project file: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 101 + + \target VariableProcessingFunctions + \section1 Variable Processing Functions + + \c qmake provides a selection of built-in functions to allow the + contents of variables to be processed. These functions process the + arguments supplied to them and return a value, or list of values, as + a result. In order to assign a result to a variable, it is necessary + to use the \c $$ operator with this type of function in the same way + used to assign contents of one variable to another: + + \snippet doc/src/snippets/qmake/functions.pro 1 + + This type of function should be used on the right-hand side of + assignments (i.e, as an operand). + + It is possible to define your own functions for processing the + contents of variables. These functions can be defined in the following + way: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 102 + + The following example function takes a variable name as its only + argument, extracts a list of values from the variable with the + \l{qmake-function-reference.html}{eval()} built-in function, + and compiles a list of files: + + \snippet doc/src/snippets/qmake/replacefunction.pro 0 + + \target ConditionalFunctions + \section1 Conditional Functions + + \c qmake provides built-in functions that can be used as conditions + when writing scopes. These functions do not return a value, but + instead indicate "success" or "failure": + + \snippet doc/src/snippets/qmake/functions.pro 3 + + This type of function should be used in conditional expressions + only. + + It is possible to define your own functions to provide conditions + for scopes. The following example tests whether each file in a list + exists and returns true if they all exist, or false if not: + + \snippet doc/src/snippets/qmake/testfunction.pro 0 + + \section1 Adding New Configuration Features + + \c qmake lets you create your own \e features that can be included in + project files by adding their names to the list of values specified by + the \c CONFIG variable. Features are collections of custom functions and + definitions in \c{.prf} files that can reside in one of many standard + directories. The locations of these directories are defined in a number + of places, and \c qmake checks each of them in the following order when + it looks for \c{.prf} files: + + \list 1 + \o In a directory listed in the \c QMAKEFEATURES environment variable; + this contains a colon-separated list of directories. + \o In a directory listed in the \c QMAKEFEATURES property variable; this + contains a colon-spearated list of directories. + \omit + \o In a features directory beneath the project's root directory (where + the \c{.qmake.cache} file is generated). + \endomit + \o In a features directory residing within a \c mkspecs directory. + \c mkspecs directories can be located beneath any of the directories + listed in the \c QMAKEPATH environment variable (a colon-separated list + of directories). (\c{$QMAKEPATH/mkspecs/<features>}) + \o In a features directory residing beneath the directory provided by the + \c QMAKESPEC environment variable. (\c{$QMAKESPEC/<features>}) + \o In a features directory residing in the \c data_install/mkspecs directory. + (\c{data_install/mkspecs/<features>}) + \o In a features directory that exists as a sibling of the directory + specified by the \c QMAKESPEC environment variable. + (\c{$QMAKESPEC/../<features>}) + \endlist + + The following features directories are searched for features files: + + \list 1 + \o \c{features/unix}, \c{features/win32}, or \c{features/macx}, depending on + the platform in use + \o \c features/ + \endlist + + For example, consider the following assignment in a project file: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 103 + + With this addition to the \c CONFIG variable, \c qmake will search the + locations listed above for the \c myfeatures.prf file after it has + finished parsing your project file. On Unix systems, it will look for + the following file: + + \list 1 + \o \c $QMAKEFEATURES/myfeatures.prf (for each directory listed in the + \c QMAKEFEATURES environment variable) + \o \c $$QMAKEFEATURES/myfeatures.prf (for each directory listed in the + \c QMAKEFEATURES property variable) + \o \c myfeatures.prf (in the project's root directory) + \o \c $QMAKEPATH/mkspecs/features/unix/myfeatures.prf and + \c $QMAKEPATH/mkspecs/features/myfeatures.prf (for each directory + listed in the \c QMAKEPATH environment variable) + \o \c $QMAKESPEC/features/unix/myfeatures.prf and + \c $QMAKESPEC/features/myfeatures.prf + \o \c data_install/mkspecs/features/unix/myfeatures.prf and + \c data_install/mkspecs/features/myfeatures.prf + \o \c $QMAKESPEC/../features/unix/myfeatures.prf and + \c $QMAKESPEC/../features/myfeatures.prf + \endlist + + \note The \c{.prf} files must have names in lower case. + + +*/ + +/*! + \page qmake-precompiledheaders.html + \title Using Precompiled Headers + \contentspage {qmake Manual}{Contents} + \previouspage qmake Advanced Usage + \nextpage qmake Reference + + \target Introduction + + Precompiled headers are a performance feature supported by some + compilers to compile a stable body of code, and store the compiled + state of the code in a binary file. During subsequent compilations, + the compiler will load the stored state, and continue compiling the + specified file. Each subsequent compilation is faster because the + stable code does not need to be recompiled. + + \c qmake supports the use of precompiled headers (PCH) on some + platforms and build environments, including: + \list + \o Windows + \list + \o nmake + \o Dsp projects (VC 6.0) + \o Vcproj projects (VC 7.0 \& 7.1) + \endlist + \o Mac OS X + \list + \o Makefile + \o Xcode + \endlist + \o Unix + \list + \o GCC 3.4 and above + \endlist + \endlist + + \target ADD_PCH + \section1 Adding Precompiled Headers to Your Project + + \target PCH_CONTENTS + \section2 Contents of the Precompiled Header File + + The precompiled header must contain code which is \e stable + and \e static throughout your project. A typical PCH might look + like this: + + \section3 Example: \c stable.h + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 104 + + Note that a precompiled header file needs to separate C includes from + C++ includes, since the precompiled header file for C files may not + contain C++ code. + + \target PROJECT_OPTIONS + \section2 Project Options + + To make your project use PCH, you only need to define the + \c PRECOMPILED_HEADER variable in your project file: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 105 + + \c qmake will handle the rest, to ensure the creation and use of the + precompiled header file. You do not need to include the precompiled + header file in \c HEADERS, as \c qmake will do this if the configuration + supports PCH. + + All platforms that support precompiled headers have the configuration + option \c precompile_header set. Using this option, you may trigger + conditional blocks in your project file to add settings when using PCH. + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 106 + + \section1 Notes on Possible Issues + + On some platforms, the file name suffix for precompiled header files is + the same as that for other object files. For example, the following + declarations may cause two different object files with the same name to + be generated: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 107 + + To avoid potential conflicts like these, it is good practice to ensure + that header files that will be precompiled are given distinctive names. + + \target EXAMPLE_PROJECT + \section1 Example Project + + You can find the following source code in the + \c{examples/qmake/precompile} directory in the Qt distribution: + + \section2 \c mydialog.ui + + \quotefromfile examples/qmake/precompile/mydialog.ui + \printuntil + + \section2 \c stable.h + + \snippet examples/qmake/precompile/stable.h 0 + + \section2 \c myobject.h + + \snippet examples/qmake/precompile/myobject.h 0 + + \section2 \c myobject.cpp + + \snippet examples/qmake/precompile/myobject.cpp 0 + + \section2 \c util.cpp + + \snippet examples/qmake/precompile/util.cpp 0 + + \section2 \c main.cpp + + \snippet examples/qmake/precompile/main.cpp 0 + + \section2 \c precompile.pro + + \snippet examples/qmake/precompile/precompile.pro 0 +*/ + +/*! + \page qmake-tutorial.html + \title qmake Tutorial + \contentspage {qmake Manual}{Contents} + \previouspage qmake Manual + \nextpage qmake Common Projects + + This tutorial teaches you how to use \c qmake. We recommend that + you read the \c qmake user guide after completing this tutorial. + + \section1 Starting off Simple + + Let's assume that you have just finished a basic implementation of + your application, and you have created the following files: + + \list + \o hello.cpp + \o hello.h + \o main.cpp + \endlist + + You will find these files in the \c{examples/qmake/tutorial} directory + of the Qt distribution. The only other thing you know about the setup of + the application is that it's written in Qt. First, using your favorite + plain text editor, create a file called \c hello.pro in + \c{examples/qmake/tutorial}. The first thing you need to do is add the + lines that tell \c qmake about the source and header files that are part + of your development project. + + We'll add the source files to the project file first. To do this you + need to use the \l{qmake Variable Reference#SOURCES}{SOURCES} variable. + Just start a new line with \c {SOURCES +=} and put hello.cpp after it. + You should have something like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 108 + + We repeat this for each source file in the project, until we end up + with the following: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 109 + + If you prefer to use a Make-like syntax, with all the files listed in + one go you can use the newline escaping like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 110 + + Now that the source files are listed in the project file, the header + files must be added. These are added in exactly the same way as source + files, except that the variable name we use is + \l{qmake Variable Reference#HEADERS}{HEADERS}. + + Once you have done this, your project file should look something like + this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 111 + + The target name is set automatically; it is the same as the project + file, but with the suffix appropriate to the platform. For example, if + the project file is called \c hello.pro, the target will be \c hello.exe + on Windows and \c hello on Unix. If you want to use a different name + you can set it in the project file: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 112 + + The final step is to set the \l{qmake Variable Reference#CONFIG}{CONFIG} + variable. Since this is a Qt application, we need to put \c qt on the + \c CONFIG line so that \c qmake will add the relevant libraries to be + linked against and ensure that build lines for \c moc and \c uic are + included in the generated Makefile. + + The finished project file should look like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 113 + + You can now use \c qmake to generate a Makefile for your application. + On the command line, in your project's directory, type the following: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 114 + + Then type \c make or \c nmake depending on the compiler you use. + + For Visual Studio users, \c qmake can also generate \c .dsp or + \c .vcproj files, for example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 115 + + \section1 Making an Application Debuggable + + The release version of an application doesn't contain any debugging + symbols or other debugging information. During development it is useful + to produce a debugging version of the application that has the + relevant information. This is easily achieved by adding \c debug to the + \c CONFIG variable in the project file. + + For example: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 116 + + Use \c qmake as before to generate a Makefile and you will be able to + obtain useful information about your application when running it in + a debugging environment. + + \section1 Adding Platform-Specific Source Files + + After a few hours of coding, you might have made a start on the + platform-specific part of your application, and decided to keep the + platform-dependent code separate. So you now have two new files to + include into your project file: \c hellowin.cpp and \c + hellounix.cpp. We can't just add these to the \c SOURCES + variable since this will put both files in the Makefile. So, what we + need to do here is to use a scope which will be processed depending on + which platform \c qmake is run on. + + A simple scope that will add in the platform-dependent file for + Windows looks like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 117 + + So if \c qmake is run on Windows, it will add \c hellowin.cpp to the + list of source files. If \c qmake is run on any other platform, it + will simply ignore it. Now all that is left to be done is to create a + scope for the Unix-specific file. + + When you have done that, your project file should now look + something like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 118 + + Use \c qmake as before to generate a Makefile. + + \section1 Stopping qmake If a File Doesn't Exist + + You may not want to create a Makefile if a certain file doesn't exist. + We can check if a file exists by using the exists() function. We can + stop \c qmake from processing by using the error() function. This + works in the same way as scopes do. Simply replace the scope condition + with the function. A check for a \c main.cpp file looks like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 119 + + The \c{!} symbol is used to negate the test; i.e. \c{exists( main.cpp )} + is true if the file exists, and \c{!exists( main.cpp )} is true if the + file doesn't exist. + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 120 + + Use \c qmake as before to generate a makefile. If you rename \c + main.cpp temporarily, you will see the message and \c qmake will stop + processing. + + \section1 Checking for More than One Condition + + Suppose you use Windows and you want to be able to see statement + output with qDebug() when you run your application on the command line. + Unless you build your application with the appropriate console setting, + you won't see the output. We can easily put \c console on the \c CONFIG + line so that on Windows the makefile will have this setting. However, + let's say that we only want to add the \c CONFIG line if we are running + on Windows \e and when \c debug is already on the \c CONFIG line. + This requires using two nested scopes; just create one scope, then create + the other inside it. Put the settings to be processed inside the last + scope, like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 121 + + Nested scopes can be joined together using colons, so the final + project file looks like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 122 + + That's it! You have now completed the tutorial for \c qmake, and are + ready to write project files for your development projects. +*/ + +/*! + \page qmake-common-projects.html + \title qmake Common Projects + \contentspage {qmake Manual}{Contents} + \previouspage qmake Tutorial + \nextpage Using qmake + + This chapter describes how to set up \c qmake project files for three + common project types that are based on Qt. Although all kinds of + projects use many of the same variables, each of them use project-specific + variables to customize output files. + + Platform-specific variables are not described here; we refer the reader to + the \l{Deploying Qt Applications} document for information on issues such as + \l{Deploying an Application on Mac OS X#Architecture Dependencies}{building + universal binaries for Mac OS X} and + \l{Deploying an Application on Windows#Visual Studio 2005 Onwards} + {handling Visual Studio manifest files}. + + \tableofcontents + + \target Application + \section1 Building an Application + + \section2 The app Template + + The \c app template tells \c qmake to generate a Makefile that will build + an application. With this template, the type of application can be specified + by adding one of the following options to the \c CONFIG variable definition: + + \table + \header \o Option \o Description + \row \o windows \o The application is a Windows GUI application. + \row \o console \o \c app template only: the application is a Windows console + application. + \endtable + + When using this template the following \c qmake system variables are recognized. + You should use these in your .pro file to specify information about your + application. + + \list + \o HEADERS - A list of all the header files for the application. + \o SOURCES - A list of all the source files for the application. + \o FORMS - A list of all the UI files (created using \c{Qt Designer}) + for the application. + \o LEXSOURCES - A list of all the lex source files for the application. + \o YACCSOURCES - A list of all the yacc source files for the application. + \o TARGET - Name of the executable for the application. This defaults + to the name of the project file. (The extension, if any, is added + automatically). + \o DESTDIR - The directory in which the target executable is placed. + \o DEFINES - A list of any additional pre-processor defines needed for the application. + \o INCLUDEPATH - A list of any additional include paths needed for the application. + \o DEPENDPATH - The dependency search path for the application. + \o VPATH - The search path to find supplied files. + \o DEF_FILE - Windows only: A .def file to be linked against for the application. + \o RC_FILE - Windows only: A resource file for the application. + \o RES_FILE - Windows only: A resource file to be linked against for the application. + \endlist + + You only need to use the system variables that you have values for, + for instance, if you do not have any extra INCLUDEPATHs then you do not + need to specify any, \c qmake will add in the default ones needed. + For instance, an example project file might look like this: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 123 + + For items that are single valued, e.g. the template or the destination + directory, we use "="; but for multi-valued items we use "+=" to \e + add to the existing items of that type. Using "=" replaces the item's + value with the new value, for example if we wrote \c{DEFINES=QT_DLL}, + all other definitions would be deleted. + + \target Library + \section1 Building a Library + + \section2 The lib Template + + The \c lib template tells \c qmake to generate a Makefile that will + build a library. When using this template, in addition to the system variables + mentioned above for the \c app template the \c VERSION variable is + supported. You should use these in your .pro file to specify + information about the library. + + When using the \c lib template, the following options can be added to the + \c CONFIG variable to determine the type of library that is built: + + \table + \header \o Option \o Description + \row \o dll \o The library is a shared library (dll). + \row \o staticlib \o The library is a static library. + \row \o plugin \o The library is a plugin; this also enables the dll option. + \endtable + + The following option can also be defined to provide additional information about + the library. + + \list + \o VERSION - The version number of the target library, for example, 2.3.1. + \endlist + + The target file name for the library is platform-dependent. For example, on + X11 and Mac OS X, the library name will be prefixed by \c lib; on Windows, + no prefix is added to the file name. + + \target Plugin + \section1 Building a Plugin + + Plugins are built using the \c lib template, as described in the previous + section. This tells \c qmake to generate a Makefile for the project that will + build a plugin in a suitable form for each platform, usually in the form of a + library. As with ordinary libraries, the \c VERSION variable is used to specify + information about the plugin. + + \list + \o VERSION - The version number of the target library, for example, 2.3.1. + \endlist + + \section2 Building a Qt Designer Plugin + + \QD plugins are built using a specific set of configuration settings that + depend on the way Qt was configured for your system. For convenience, these + settings can be enabled by adding \c designer to the project's \c CONFIG + variable. For example: + + \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 0 + + See the \l{Qt Designer Examples} for more examples of plugin-based projects. + + \section1 Building and Installing in Debug and Release Modes + + Sometimes, it is necessary to build a project in both debug and release + modes. Although the \c CONFIG variable can hold both \c debug and \c release + options, the \c debug option overrides the \c release option. + + \section2 Building in Both Modes + + To enable a project to be built in both modes, you must add the + \c debug_and_release option to your project's \c CONFIG definition: + + \snippet doc/src/snippets/qmake/debug_and_release.pro 0 + \snippet doc/src/snippets/qmake/debug_and_release.pro 1 + + The scope in the above snippet modifies the build target in each mode to + ensure that the resulting targets have different names. Providing different + names for targets ensures that one will not overwrite the other. + + When \c qmake processes the project file, it will generate a Makefile rule + to allow the project to be built in both modes. This can be invoked in the + following way: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 124 + + The \c build_all option can be added to the \c CONFIG variable in the + project file to ensure that the project is built in both modes by default: + + \snippet doc/src/snippets/qmake/debug_and_release.pro 2 + + This allows the Makefile to be processed using the default rule: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 125 + + \section2 Installing in Both Modes + + The \c build_all option also ensures that both versions of the target + will be installed when the installation rule is invoked: + + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 126 + + It is possible to customize the names of the build targets depending on + the target platform. For example, a library or plugin may be named using a + different convention on Windows to the one used on Unix platforms: + + \omit + Note: This was originally used in the customwidgetplugin.pro file, but is + no longer needed there. + \endomit + \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 127 + + The default behavior in the above snippet is to modify the name used for + the build target when building in debug mode. An \c else clause could be + added to the scope to do the same for release mode; left as it is, the + target name remains unmodified. +*/ + diff --git a/doc/src/development/qmsdev.qdoc b/doc/src/development/qmsdev.qdoc new file mode 100644 index 0000000..ceed4c1 --- /dev/null +++ b/doc/src/development/qmsdev.qdoc @@ -0,0 +1,166 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/* NOT DOCUMENTED ! + \page qmsdev.html + + \title The QMsDev Plugin + + The Visual Studio Integration Plugin is currently available only to users of + Visual Studio 6. It offers simple ways of doing common tasks when writing a + Qt application. + + \tableofcontents + + \section1 How to install the Visual Studio Integration Plugin + + When you install Qt, the integration plugin should be installed for you, + however, sometimes this does not happen, so to install the integration + plugin manually just carry out the following steps. + + \list + \i Start up Visual Studio. + \i Select Tools|Customize|Add-ins and Macro Files. + \i Ensure that there is a tick next to QMsDev Developer Studio Add-In. + \i Click Close. + \endlist + + Now the integration plugin should be installed. If this doesn't + work, then contact Qt technical support giving details of + what went wrong. + + \section1 How to uninstall the Visual Studio Integration Plugin + + When you want to uninstall the integration plugin, just carry out the + following steps. + + \list + \i Close down any instances of Visual Studio. + \i Delete the file '%MSDevDir%\\addins\\qmsdev.dll' + \endlist + + \section1 What can the Visual Studio Integration Plugin do? + + The integration plugin adds the following options to Visual Studio: + + \list + \i New Qt Project + \i New Qt Dialog + \i Qt Designer + \i Open Qt Project + \i Write Qt Project + \i Use Qt In Current Project + \i Add MOC + \endlist + + \section2 Using the 'New Qt Project' button + + The 'New Qt Project' button allows you to create a simple Qt project + ready for development. Simply fill in the form and if you select + 'Dialog' or 'Main Window' without MDI support then it will + automatically start up \e{Qt Designer}. When you have finished with + the form in \e{Qt Designer} just save it and it will appear in a + ready made Qt project. + + If you select 'Main Window' with 'MDI Support' then it will simply + give you a code skeleton in a project ready for you to populate with + your own code. + + \section2 Using the 'New Qt Dialog' button + + The 'New Qt Dialog' button works in two ways: You can use it to create a new + dialog for your project; or you can use it to insert an existing + dialog into your project. + + If you want to create a new dialog then all you need to do is specify where + the dialog file should be saved and give it a name. This will start up + \e{Qt Designer} to allow you to design your new dialog, and will add it to + the existing project. + + If you want to add an existing dialog to your project, then just select the + relevant UI file. This will then add it to your existing project and add + the relevant steps to create the generated code. + + \section2 Using the 'Qt Designer' button + + The 'Qt Designer' button simply starts up \e{Qt Designer}, it has no ties to + your existing project so whatever you do with it will not affect your + existing projects. It can also be started up by using the Ctrl+Shift+D key + combination in Visual Studio. + + \section2 Using the 'Open Qt Project' button + + The 'Open Qt Project' button allows you to convert an existing \c + qmake project file into a \c .dsp file which you can insert into + your existing workspace. When you click the 'Open Qt Project' + button, just select an existing \c qmake project file (a \c .pro + file) and then click OK. You will get a message box at the end + which asks you to insert the newly created \c .dsp file into your + existing workspace. + + \section2 Using the 'Write Qt Project' button + + The 'Write Qt Project' button creates a \c qmake project (\c .pro) + file for your current project so that you can easily copy the files + onto another platform and be able to use \c qmake to create a Makefile + on that other platform. All you need to do is make the project you + want to create a \c .pro file for, and click on the button. Just + name your \c qmake project file and click Save. + + \section2 Using the 'Use Qt In Current Project' button + + The 'Use Qt In Current Project' button simply adds in the necessary + information for the current project so that it links against Qt and + sets any other settings needed to use Qt in that project. + + \section2 Using the 'Add MOC' button + + The 'Add MOC' button will add in the custom build step for the selected file + so that it creates any needed MOC files and it will add these generated + files to the project. All you need to do to use it is click on a file that + has Q_OBJECT and click the button. + + You only need to use this button if you added a file that has + Q_OBJECT in it by hand, you don't need to use this if you used any + of the previously mentioned buttons. It can also be invoked by using + the \key{Ctrl+Shift+M} key combination in Visual Studio. + +*/ diff --git a/doc/src/development/qtestlib.qdoc b/doc/src/development/qtestlib.qdoc new file mode 100644 index 0000000..13a5b7c --- /dev/null +++ b/doc/src/development/qtestlib.qdoc @@ -0,0 +1,778 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtestlib-manual.html + \title QTestLib Manual + \brief An overview of Qt's unit testing framework. + + \ingroup frameworks-technologies + \keyword qtestlib + + The QTestLib framework, provided by Nokia, is a tool for unit + testing Qt based applications and libraries. QTestLib provides + all the functionality commonly found in unit testing frameworks as + well as extensions for testing graphical user interfaces. + + Table of contents: + + \tableofcontents + + \section1 QTestLib Features + + QTestLib is designed to ease the writing of unit tests for Qt + based applications and libraries: + + \table + \header \o Feature \o Details + \row + \o \bold Lightweight + \o QTestLib consists of about 6000 lines of code and 60 + exported symbols. + \row + \o \bold Self-contained + \o QTestLib requires only a few symbols from the Qt Core library + for non-gui testing. + \row + \o \bold {Rapid testing} + \o QTestLib needs no special test-runners; no special + registration for tests. + \row + \o \bold {Data-driven testing} + \o A test can be executed multiple times with different test data. + \row + \o \bold {Basic GUI testing} + \o QTestLib offers functionality for mouse and keyboard simulation. + \row + \o \bold {Benchmarking} + \o QTestLib supports benchmarking and provides several measurement back-ends. + \row + \o \bold {IDE friendly} + \o QTestLib outputs messages that can be interpreted by Visual + Studio and KDevelop. + \row + \o \bold Thread-safety + \o The error reporting is thread safe and atomic. + \row + \o \bold Type-safety + \o Extensive use of templates prevent errors introduced by + implicit type casting. + \row + \o \bold {Easily extendable} + \o Custom types can easily be added to the test data and test output. + \endtable + + Note: For higher-level GUI and application testing needs, please + see the \l{Third-Party Tools}{Qt testing products provided by + Nokia partners}. + + + \section1 QTestLib API + + All public methods are in the \l QTest namespace. In addition, the + \l QSignalSpy class provides easy introspection for Qt's signals and slots. + + + \section1 Using QTestLib + + \section2 Creating a Test + + To create a test, subclass QObject and add one or more private slots to it. Each + private slot is a testfunction in your test. QTest::qExec() can be used to execute + all testfunctions in the test object. + + In addition, there are four private slots that are \e not treated as testfunctions. + They will be executed by the testing framework and can be used to initialize and + clean up either the entire test or the current test function. + + \list + \o \c{initTestCase()} will be called before the first testfunction is executed. + \o \c{cleanupTestCase()} will be called after the last testfunction was executed. + \o \c{init()} will be called before each testfunction is executed. + \o \c{cleanup()} will be called after every testfunction. + \endlist + + If \c{initTestCase()} fails, no testfunction will be executed. If \c{init()} fails, + the following testfunction will not be executed, the test will proceed to the next + testfunction. + + Example: + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 0 + + For more examples, refer to the \l{QTestLib Tutorial}. + + \section2 Building a Test + + If you are using \c qmake as your build tool, just add the + following to your project file: + + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 1 + + If you are using other buildtools, make sure that you add the location + of the QTestLib header files to your include path (usually \c{include/QtTest} + under your Qt installation directory). If you are using a release build + of Qt, link your test to the \c QtTest library. For debug builds, use + \c{QtTest_debug}. + + See \l {Chapter 1: Writing a Unit Test}{Writing a Unit Test} for a step by + step explanation. + + \section2 QTestLib Command Line Arguments + + \section3 Syntax + + The syntax to execute an autotest takes the following simple form: + + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 2 + + Substitute \c testname with the name of your executable. \c + testfunctions can contain names of test functions to be + executed. If no \c testfunctions are passed, all tests are run. If you + append the name of an entry in \c testdata, the test function will be + run only with that test data. + + For example: + + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 3 + + Runs the test function called \c toUpper with all available test data. + + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 4 + + Runs the \c toUpper test function with all available test data, + and the \c toInt test function with the testdata called \c + zero (if the specified test data doesn't exist, the associated test + will fail). + + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 5 + + Runs the testMyWidget function test, outputs every signal + emission and waits 500 milliseconds after each simulated + mouse/keyboard event. + + \section3 Options + + The following command line arguments are understood: + + \list + \o \c -help \BR + outputs the possible command line arguments and give some useful help. + \o \c -functions \BR + outputs all test functions available in the test. + \o \c -o \e filename \BR + write output to the specified file, rather than to standard output + \o \c -silent \BR + silent output, only shows warnings, failures and minimal status messages + \o \c -v1 \BR + verbose output; outputs information on entering and exiting test functions. + \o \c -v2 \BR + extended verbose output; also outputs each \l QCOMPARE() and \l QVERIFY() + \o \c -vs \BR + outputs every signal that gets emitted + \o \c -xml \BR + outputs XML formatted results instead of plain text + \o \c -lightxml \BR + outputs results as a stream of XML tags + \o \c -eventdelay \e ms \BR + if no delay is specified for keyboard or mouse simulation + (\l QTest::keyClick(), + \l QTest::mouseClick() etc.), the value from this parameter + (in milliseconds) is substituted. + \o \c -keydelay \e ms \BR + like -eventdelay, but only influences keyboard simulation and not mouse + simulation. + \o \c -mousedelay \e ms \BR + like -eventdelay, but only influences mouse simulation and not keyboard + simulation. + \o \c -keyevent-verbose \BR + output more verbose output for keyboard simulation + \o \c -maxwarnings \e number\BR + sets the maximum number of warnings to output. 0 for unlimited, defaults to 2000. + \endlist + + \section2 Creating a Benchmark + + To create a benchmark, follow the instructions for crating a test and then add a + QBENCHMARK macro to the test function that you want to benchmark. + + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 12 + + The code insde the QBENCHMARK macro will be measured, and possibly also repeated + several times in order to get an accurate measurement. This depends on the selected + measurement back-end. Several back-ends are available an can be selected on the + command line: + + \target testlib-benchmarking-measurement + + \table + \header \o Name + \o Commmand-line Arguemnt + \o Availability + \row \o Walltime + \o (default) + \o All platforms + \row \o CPU tick counter + \o -tickcounter + \o Windows, Mac OS X, Linux, many UNIX-like systems. + \row \o Valgrind/Callgrind + \o -callgrind + \o Linux (if installed) + \row \o Event Counter + \o -eventcounter + \o All platforms + \endtable + + In short, walltime is always available but requires many repetitions to + get a useful result. + Tick counters are usually available and can provide + results with fewer repetitions, but can be susceptible to CPU frequency + scaling issues. + Valgrind provides exact results, but does not take + I/O waits into account, and is only available on a limited number of + platforms. + Event counting is available on all platforms and it provides the number of events + that were received by the event loop before they are sent to their corresponding + targets (this might include non-Qt events). + + \note Depending on the device configuration, Tick counters on the + Windows CE platform may not be as fine-grained, compared to other platforms. + Devices that do not support high-resolution timers default to + one-millisecond granularity. + + See the chapter 5 in the \l{QTestLib Tutorial} for more benchmarking examples. + + \section1 Using QTestLib remotely on Windows CE + \c cetest is a convenience application which helps the user to launch an + application remotely on a Windows CE device or emulator. + + It needs to be executed after the unit test has been successfully compiled. + + Prior to launching, the following files are copied to the device: + + \list + \o all Qt libraries the project links to + \o \l {QtRemote}{QtRemote.dll} + \o the c runtime library specified during installation + \o all files specified in the \c .pro file following the \l DEPLOYMENT rules. + \endlist + + \section2 Using \c cetest + \section3 Syntax + The syntax to execute an autotest takes the following simple form: + + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 6 + + \section3 Options + \c cetest provides the same options as those for unit-testing on non cross-compiled + platforms. See \l {QTestLib Command Line Arguments} {Command Line Arguments} for + more information. + + The following commands are also included: + + \list + \o \c -debug \BR + Test version compiled in debug mode. + \o \c -release \BR + Test version compiled in release mode. + \o \c -libpath \e path \BR + Target path to copy Qt libraries to. + \o \c -qt-delete \BR + Delete Qt libraries after execution. + \o \c -project-delete \BR + Delete project files after execution. + \o \c -delete \BR + Delete project and Qt libraries after execution. + \o \c -conf \BR + Specifies a qt.conf file to be deployed to remote directory. + \endlist + + \note \c{debug} is the default build option. + + \section2 QtRemote + \c QtRemote is a small library which is build after QTestLib. It allows the host + system to create a process on a remote device and waits until its execution has + been finished. + + \section2 Requirements + \c cetest uses Microsoft ActiveSync to establish a remote connection between the + host computer and the device. Thus header files and libraries are needed to compile + cetest and QtRemote successfully. + + Prior to \l{Installing Qt on Windows CE}{installation} of Qt, you need to set your + \c INCLUDE and \c LIB environment variables properly. + + A default installation of Windows Mobile 5 for Pocket PC can be obtained by: + + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 7 + + Note that Qt will remember the path, so you do not need to set it again + after switching the environments for cross-compilation. + + \section1 3rd Party Code + + The CPU tick counters used for benchmarking is licensed under the following + license: (from src/testlib/3rdparty/cycle.h) + + \legalese + Copyright (c) 2003, 2006 Matteo Frigo\br + Copyright (c) 2003, 2006 Massachusetts Institute of Technology + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + \endlegalese +*/ + +/*! + \page qtestlib-tutorial.html + \brief A short introduction to testing with QTestLib. + \contentspage QTestLib Manual + \nextpage {Chapter 1: Writing a Unit Test}{Chapter 1} + + \title QTestLib Tutorial + + This tutorial gives a short introduction to how to use some of the + features of the QTestLib framework. It is divided into four + chapters: + + \list 1 + \o \l {Chapter 1: Writing a Unit Test}{Writing a Unit Test} + \o \l {Chapter 2: Data Driven Testing}{Data Driven Testing} + \o \l {Chapter 3: Simulating GUI Events}{Simulating GUI Events} + \o \l {Chapter 4: Replaying GUI Events}{Replaying GUI Events} + \o \l {Chapter 5: Writing a Benchmark}{Writing a Benchmark} + \endlist + +*/ + + +/*! + \example qtestlib/tutorial1 + + \contentspage {QTestLib Tutorial}{Contents} + \nextpage {Chapter 2: Data Driven Testing}{Chapter 2} + + \title Chapter 1: Writing a Unit Test + + In this first chapter we will see how to write a simple unit test + for a class, and how to execute it. + + \section1 Writing a Test + + Let's assume you want to test the behavior of our QString class. + First, you need a class that contains your test functions. This class + has to inherit from QObject: + + \snippet examples/qtestlib/tutorial1/testqstring.cpp 0 + + Note that you need to include the QTest header, and that the + test functions have to be declared as private slots so the + test framework finds and executes it. + + Then you need to implement the test function itself. The + implementation could look like this: + + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 8 + + The \l QVERIFY() macro evaluates the expression passed as its + argument. If the expression evaluates to true, the execution of + the test function continues. Otherwise, a message describing the + failure is appended to the test log, and the test function stops + executing. + + But if you want a more verbose output to the test log, you should + use the \l QCOMPARE() macro instead: + + \snippet examples/qtestlib/tutorial1/testqstring.cpp 1 + + If the strings are not equal, the contents of both strings is + appended to the test log, making it immediately visible why the + comparison failed. + + Finally, to make our test case a stand-alone executable, the + following two lines are needed: + + \snippet examples/qtestlib/tutorial1/testqstring.cpp 2 + + The \l QTEST_MAIN() macro expands to a simple \c main() + method that runs all the test functions. Note that if both the + declaration and the implementation of our test class are in a \c + .cpp file, we also need to include the generated moc file to make + Qt's introspection work. + + \section1 Executing a Test + + Now that we finished writing our test, we want to execute + it. Assuming that our test was saved as \c testqstring.cpp in an + empty directory: we build the test using qmake to create a project + and generate a makefile. + + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 9 + + \bold {Note:}If you're using windows, replace \c make with \c + nmake or whatever build tool you use. + + Running the resulting executable should give you the following + output: + + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 10 + + Congratulations! You just wrote and executed your first unit test + using the QTestLib framework. +*/ + +/*! + \example qtestlib/tutorial2 + + \previouspage {Chapter 1: Writing a Unit Test}{Chapter 1} + \contentspage {QTestLib Tutorial}{Contents} + \nextpage {Chapter 3: Simulating Gui Events}{Chapter 3} + + \title Chapter 2: Data Driven Testing + + In this chapter we will demonstrate how to execute a test + multiple times with different test data. + + So far, we have hard coded the data we wanted to test into our + test function. If we add more test data, the function might look like + this: + + \snippet doc/src/snippets/code/doc_src_qtestlib.qdoc 11 + + To prevent that the function ends up being cluttered by repetitive + code, QTestLib supports adding test data to a test function. All + we need is to add another private slot to our test class: + + \snippet examples/qtestlib/tutorial2/testqstring.cpp 0 + + \section1 Writing the Data Function + + A test function's associated data function carries the same name, + appended by \c{_data}. Our data function looks like this: + + \snippet examples/qtestlib/tutorial2/testqstring.cpp 1 + + First, we define the two elements of our test table using the \l + QTest::addColumn() function: A test string, and the + expected result of applying the QString::toUpper() function to + that string. + + Then we add some data to the table using the \l + QTest::newRow() function. Each set of data will become a + separate row in the test table. + + \l QTest::newRow() takes one argument: A name that will be + associated with the data set. If the test fails, the name will be + used in the test log, referencing the failed data. Then we + stream the data set into the new table row: First an arbitrary + string, and then the expected result of applying the + QString::toUpper() function to that string. + + You can think of the test data as a two-dimensional table. In + our case, it has two columns called \c string and \c result and + three rows. In addition a name as well as an index is associated + with each row: + + \table + \header + \o index + \o name + \o string + \o result + \row + \o 0 + \o all lower + \o "hello" + \o HELLO + \row + \o 1 + \o mixed + \o "Hello" + \o HELLO + \row + \o 2 + \o all upper + \o "HELLO" + \o HELLO + \endtable + + \section1 Rewriting the Test Function + + Our test function can now be rewritten: + + \snippet examples/qtestlib/tutorial2/testqstring.cpp 2 + + The TestQString::toUpper() function will be executed three times, + once for each entry in the test table that we created in the + associated TestQString::toUpper_data() function. + + First, we fetch the two elements of the data set using the \l + QFETCH() macro. \l QFETCH() takes two arguments: The data type of + the element and the element name. Then we perform the test using + the \l QCOMPARE() macro. + + This approach makes it very easy to add new data to the test + without modifying the test itself. + + And again, to make our test case a stand-alone executable, + the following two lines are needed: + + \snippet examples/qtestlib/tutorial2/testqstring.cpp 3 + + As before, the QTEST_MAIN() macro expands to a simple main() + method that runs all the test functions, and since both the + declaration and the implementation of our test class are in a .cpp + file, we also need to include the generated moc file to make Qt's + introspection work. +*/ + +/*! + \example qtestlib/tutorial3 + + \previouspage {Chapter 2 Data Driven Testing}{Chapter 2} + \contentspage {QTestLib Tutorial}{Contents} + \nextpage {Chapter 4: Replaying GUI Events}{Chapter 4} + + \title Chapter 3: Simulating GUI Events + + QTestLib features some mechanisms to test graphical user + interfaces. Instead of simulating native window system events, + QTestLib sends internal Qt events. That means there are no + side-effects on the machine the tests are running on. + + In this chapter we will se how to write a simple GUI test. + + \section1 Writing a GUI test + + This time, let's assume you want to test the behavior of our + QLineEdit class. As before, you will need a class that contains + your test function: + + \snippet examples/qtestlib/tutorial3/testgui.cpp 0 + + The only difference is that you need to include the QtGui class + definitions in addition to the QTest namespace. + + \snippet examples/qtestlib/tutorial3/testgui.cpp 1 + + In the implementation of the test function we first create a + QLineEdit. Then we simulate writing "hello world" in the line edit + using the \l QTest::keyClicks() function. + + \note The widget must also be shown in order to correctly test keyboard + shortcuts. + + QTest::keyClicks() simulates clicking a sequence of keys on a + widget. Optionally, a keyboard modifier can be specified as well + as a delay (in milliseconds) of the test after each key click. In + a similar way, you can use the QTest::keyClick(), + QTest::keyPress(), QTest::keyRelease(), QTest::mouseClick(), + QTest::mouseDClick(), QTest::mouseMove(), QTest::mousePress() + and QTest::mouseRelease() functions to simulate the associated + GUI events. + + Finally, we use the \l QCOMPARE() macro to check if the line edit's + text is as expected. + + As before, to make our test case a stand-alone executable, the + following two lines are needed: + + \snippet examples/qtestlib/tutorial3/testgui.cpp 2 + + The QTEST_MAIN() macro expands to a simple main() method that + runs all the test functions, and since both the declaration and + the implementation of our test class are in a .cpp file, we also + need to include the generated moc file to make Qt's introspection + work. +*/ + +/*! + \example qtestlib/tutorial4 + + \previouspage {Chapter 3: Simulating GUI Event}{Chapter 3} + \contentspage {QTestLib Tutorial}{Contents} + \nextpage {Chapter 5: Writing a Benchmark}{Chapter 5} + + \title Chapter 4: Replaying GUI Events + + In this chapter, we will show how to simulate a GUI event, + and how to store a series of GUI events as well as replay them on + a widget. + + The approach to storing a series of events and replay them, is + quite similar to the approach explained in \l {Chapter 2: + Data Driven Testing}{chapter 2}; all you need is to add a data + function to your test class: + + \snippet examples/qtestlib/tutorial4/testgui.cpp 0 + + \section1 Writing the Data Function + + As before, a test function's associated data function carries the + same name, appended by \c{_data}. + + \snippet examples/qtestlib/tutorial4/testgui.cpp 1 + + First, we define the elements of the table using the + QTest::addColumn() function: A list of GUI events, and the + expected result of applying the list of events on a QWidget. Note + that the type of the first element is \l QTestEventList. + + A QTestEventList can be populated with GUI events that can be + stored as test data for later usage, or be replayed on any + QWidget. + + In our current data function, we create two \l + {QTestEventList}s. The first list consists of a single click to + the 'a' key. We add the event to the list using the + QTestEventList::addKeyClick() function. Then we use the + QTest::newRow() function to give the data set a name, and + stream the event list and the expected result into the table. + + The second list consists of two key clicks: an 'a' with a + following 'backspace'. Again we use the + QTestEventList::addKeyClick() to add the events to the list, and + QTest::newRow() to put the event list and the expected + result into the table with an associated name. + + \section1 Rewriting the Test Function + + Our test can now be rewritten: + + \snippet examples/qtestlib/tutorial4/testgui.cpp 2 + + The TestGui::testGui() function will be executed two times, + once for each entry in the test data that we created in the + associated TestGui::testGui_data() function. + + First, we fetch the two elements of the data set using the \l + QFETCH() macro. \l QFETCH() takes two arguments: The data type of + the element and the element name. Then we create a QLineEdit, and + apply the list of events on that widget using the + QTestEventList::simulate() function. + + Finally, we use the QCOMPARE() macro to check if the line edit's + text is as expected. + + As before, to make our test case a stand-alone executable, + the following two lines are needed: + + \snippet examples/qtestlib/tutorial4/testgui.cpp 3 + + The QTEST_MAIN() macro expands to a simple main() method that + runs all the test functions, and since both the declaration and + the implementation of our test class are in a .cpp file, we also + need to include the generated moc file to make Qt's introspection + work. +*/ + +/*! + \example qtestlib/tutorial5 + + \previouspage {Chapter 4: Replaying GUI Events}{Chapter 4} + \contentspage {QTestLib Tutorial}{Contents} + + \title Chapter 5: Writing a Benchmark + + In this final chapter we will demonstrate how to write benchmarks + using QTestLib. + + \section1 Writing a Benchmark + To create a benchmark we extend a test function with a QBENCHMARK macro. + A benchmark test function will then typically consist of setup code and + a QBENCHMARK macro that contains the code to be measured. This test + function benchmarks QString::localeAwareCompare(). + + \snippet examples/qtestlib/tutorial5/benchmarking.cpp 0 + + Setup can be done at the beginning of the function, the clock is not + running at this point. The code inside the QBENCHMARK macro will be + measured, and possibly repeated several times in order to get an + accurate measurement. + + Several \l {testlib-benchmarking-measurement}{back-ends} are available + and can be selected on the command line. + + \section1 Data Functions + + Data functions are useful for creating benchmarks that compare + multiple data inputs, for example locale aware compare against standard + compare. + + \snippet examples/qtestlib/tutorial5/benchmarking.cpp 1 + + The test function then uses the data to determine what to benchmark. + + \snippet examples/qtestlib/tutorial5/benchmarking.cpp 2 + + The "if(useLocaleCompare)" switch is placed outside the QBENCHMARK + macro to avoid measuring its overhead. Each benchmark test function + can have one active QBENCHMARK macro. + + \section1 External Tools + + Tools for handling and visualizing test data are available as part of + the \l{qtestlib-tools} project on the Qt Labs Web site. These include + a tool for comparing performance data obtained from test runs and a + utility to generate Web-based graphs of performance data. + + See the \l{qtestlib-tools Announcement} for more information on these + tools and a simple graphing example. + +*/ + + + diff --git a/doc/src/development/rcc.qdoc b/doc/src/development/rcc.qdoc new file mode 100644 index 0000000..1da641c --- /dev/null +++ b/doc/src/development/rcc.qdoc @@ -0,0 +1,95 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page rcc.html + \title Resource Compiler (rcc) + \ingroup qttools + \keyword rcc + + The \c rcc tool is used to embed resources into a Qt application during + the build process. It works by generating a C++ source file containing + data specified in a Qt resource (.qrc) file. + + Usage: + \snippet doc/src/snippets/code/doc_src_rcc.qdoc 0 + + RCC accepts the following command line options: + + \table + \header \o Option \o Argument \o Description + + \row \o \c{-o} \o \o Writes output to file rather than + stdout. + + \row \o \c{-name} \o \c name \o Creates an external initialization + function with name. + + \row \o \c{-threshold} \o \c level \o Specifies a threshold (in bytes) + to use when compressing files. If + the file is smaller than the + threshold, it will not be + compressed, independent of what + the compression level is. + + \row \o \c{-compress} \o \c level \o Compresses input files with the + given level. Level is an integer + from 1 to 9 - 1 being the fastest, + producing the least compression; + 9 being the slowest, producing + the most compression. + + \row \o \c{-root} \o \c path \o Prefixes the resource access path + with root path. + + \row \o \c{-no-compress} \o \o Disables all compression. + + \row \o \c{-binary} \o \o Outputs a binary file for use as + a dynamic resource. + + \row \o \c{-version} \o \o Displays version information. + + \row \o \c{-help} \o \o Displays usage information. + \endtable + + See also \l{The Qt Resource System} for more information about embedding + resources in Qt applications. +*/ diff --git a/doc/src/development/tools-list.qdoc b/doc/src/development/tools-list.qdoc new file mode 100644 index 0000000..01f71d3 --- /dev/null +++ b/doc/src/development/tools-list.qdoc @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group qttools + \title Qt's Tools + + Qt is supplied with several command line and graphical tools to + ease and speed the development process. Each tool is listed here + with a link to its documentation. + + \table + \header \o Tool \o Description + \row \o \l{Qt Designer Manual}{Qt Designer} + \o Create forms visually. + \row \o \l{Qt Assistant Manual}{Qt Assistant} + \o Quickly find the help you need. + \row \o \l{Qt Linguist Manual}{Qt Linguist, lupdate, lrelease, lconvert} + \o Translate applications to reach international markets. + \row \o \l{qmake Manual}{qmake} + \o Create makefiles from simple platform-independent project files (\c .pro files). + \row \o \l{The Virtual Framebuffer}{qvfb} + \o Run and test embedded applications on the desktop. + \row \o \l{makeqpf} + \o Create pre-rendered fonts for embedded devices. + \row \o \l{moc}{Meta-Object Compiler (moc)} + \o Generate meta-object information for QObject subclasses. + \row \o \l{User Interface Compiler (uic)} + \o Generate C++ code from user interface files. + \row \o \l{Resource Compiler (rcc)} + \o Embed resources into Qt applications during the build process. + \row \o \l{Configuring Qt}{Configuring Qt (qtconfig)} + \o X11-based Qt configuration tool with online help. + \row \o \l{Fine-Tuning Features in Qt}{Configuring Qt Embedded (qconfig)} + \o Qt Embedded (Linux and Windows CE) configuration tool. + \row \o \l{Examples and Demos Launcher} + \o A launcher for Qt's Examples and Demonstration programs. + \row \o \l{qt3to4 - The Qt 3 to 4 Porting Tool} + \o A tool to assist in porting applications from Qt 3 to Qt 4. + \row \o \l{QtDBus XML compiler (qdbusxml2cpp)} + \o A tool to convert D-Bus interface descriptions to C++ source code. + \row \o \l{D-Bus Viewer} + \o A tool to introspect D-Bus objects and messages. + \endtable + +*/ diff --git a/doc/src/development/uic.qdoc b/doc/src/development/uic.qdoc new file mode 100644 index 0000000..b05643c --- /dev/null +++ b/doc/src/development/uic.qdoc @@ -0,0 +1,88 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page uic.html + \title User Interface Compiler (uic) + \ingroup qttools + \keyword uic + + \omit KEEP THIS FILE SYNCHRONIZED WITH uic.1 \endomit + + This page documents the \e{User Interface Compiler} for the Qt GUI + toolkit. The \c uic reads an XML format user interface definition + (\c .ui) file as generated by \l{designer-manual.html}{Qt + Designer} and creates a corresponding C++ header file. + + Usage: + \snippet doc/src/snippets/code/doc_src_uic.qdoc 0 + + \section1 Options + + The following table lists the command-line options recognized by + \c uic. + + \table + \header \o Option \o Description + \row \o \c{-o <file>} \o Write output to \c <file> instead of to standard output. + \row \o \c{-tr <func>} \o Use \c <func> for translating strings instead of \c tr(). + \row \o \c{-p} \o Don't generate guards against multiple inclusion (\c #ifndef FOO_H ...). + \row \o \c{-h} \o Display the usage and the list of options. + \row \o \c{-v} \o Display \c{uic}'s version number. + \endtable + + \section1 Examples + + If you use \c qmake, \c uic will be invoked automatically for + header files. + + Here are useful makefile rules if you only use GNU make: + + \snippet doc/src/snippets/code/doc_src_uic.qdoc 1 + + If you want to write portably, you can use individual rules of the + following form: + + \snippet doc/src/snippets/code/doc_src_uic.qdoc 2 + + You must also remember to add \c{ui_foo.h} to your \c HEADERS + (substitute your favorite name). +*/ diff --git a/doc/src/distributingqt.qdoc b/doc/src/distributingqt.qdoc deleted file mode 100644 index 0739976..0000000 --- a/doc/src/distributingqt.qdoc +++ /dev/null @@ -1,154 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/**************************************************************************** -** -** Documentation on deploying Qt. -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - -/* -\page distributingqt.html - -\title Deploying Qt Applications - -This document lists the platform-specific files needed to distribute -Qt applications. We do not include any compiler-specific files that -may also be required. (See also, \link winsystem.html Window -System-specific Notes\endlink.) - -\tableofcontents - -Also see the "deployment" articles in -\e{\link http://qt.nokia.com/doc/qq/ Qt Quarterly\endlink}: -\list -\i \link http://qt.nokia.com/doc/qq/qq09-mac-deployment.html -Deploying Applications on Mac OS X\endlink -\i \link http://qt.nokia.com/doc/qq/qq10-windows-deployment.html -Deploying Applications on Windows\endlink -\i \link http://qt.nokia.com/doc/qq/qq11-unix-deployment.html -Deploying Applications on X11\endlink -\endlist - -\section1 Static Qt Applications - -To distribute static Qt applications, you need the following file for -all platforms: - -\list -\i your application's executable -\endlist - -\section1 Dynamic Qt Applications - -To distribute dynamic Qt applications, you will need the following -files for all platforms: - -\list -\i application executable -\i the Qt library -\endlist - -The Qt library must either be in the same directory as the application -executable or in a directory which is included in the system library -path. - -The library is provided by the following platform specific files: - -\table -\header \i Platform \i File -\row \i Windows \i \c qt[version].dll -\row \i Unix/Linux \i \c libqt[version].so -\row \i Mac \i \c libqt[version].dylib -\endtable - -\e version includes the three version numbers. - -\section2 Distributing Plugins - -You must include any plugin files required by the application. - -Plugins must be put into a subdirectory under a directory known to -Qt as a plugin directory. The subdirectory must have the name of the -plugin category (e.g. \c styles, \c sqldrivers, \c designer, etc.). - -Qt searches in the following directories for plugin categories: - -\list -\i Application specific plugin paths -\i Build-directory of Qt -\i The application directory -\endlist - -Application specific plugin paths can be added using -QCoreApplication::addLibraryPath(). The build-directory of Qt is hardcoded -in the Qt library and can be changed as a part of the installation -process. - -\section1 Dynamic Dialogs - -For dynamic dialogs if you use QWidgetFactory, you need the following -files for all platforms: - -\list -\i The same files as used for dynamic Qt applications -\i The QUI Library -\endlist - -The QUI library is provided by the following platform specific files: -\table -\header \i Platform \i File -\row \i Windows \i\c qui.lib -\row \i Unix/Linux \i\c libqui.so -\row \i Mac \i \c libqui.dylib -\endtable - -The QUI library must either be in the same directory as the -application executable or in a directory which is included in the -system library path. - -*/ diff --git a/doc/src/dnd.qdoc b/doc/src/dnd.qdoc deleted file mode 100644 index 661c621..0000000 --- a/doc/src/dnd.qdoc +++ /dev/null @@ -1,546 +0,0 @@ -/**************************************************************************** -** -** 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 dnd.html - \title Drag and Drop - \ingroup architecture - \brief An overview of the drag and drop system provided by Qt. - - Drag and drop provides a simple visual mechanism which users can use - to transfer information between and within applications. (In the - literature this is referred to as a "direct manipulation model".) Drag - and drop is similar in function to the clipboard's cut and paste - mechanism. - - \tableofcontents - - This document describes the basic drag and drop mechanism and - outlines the approach used to enable it in custom widgets. Drag - and drop operations are also supported by Qt's item views and by - the graphics view framework; more information is available in the - \l{Using Drag and Drop with Item Views} and \l{The Graphics View - Framework} documents. - - \section1 Configuration - - The QApplication object provides some properties that are related - to drag and drop operations: - - \list - \i \l{QApplication::startDragTime} describes the amount of time in - milliseconds that the user must hold down a mouse button over an - object before a drag will begin. - \i \l{QApplication::startDragDistance} indicates how far the user has to - move the mouse while holding down a mouse button before the movement - will be interpreted as dragging. Use of high values for this quantity - prevents accidental dragging when the user only meant to click on an - object. - \endlist - - These quantities provide sensible default values for you to use if you - provide drag and drop support in your widgets. - - \section1 Dragging - - To start a drag, create a QDrag object, and call its - exec() function. In most applications, it is a good idea to begin a drag - and drop operation only after a mouse button has been pressed and the - cursor has been moved a certain distance. However, the simplest way to - enable dragging from a widget is to reimplement the widget's - \l{QWidget::mousePressEvent()}{mousePressEvent()} and start a drag - and drop operation: - - \snippet doc/src/snippets/dragging/mainwindow.cpp 0 - \dots 8 - \snippet doc/src/snippets/dragging/mainwindow.cpp 2 - - Although the user may take some time to complete the dragging operation, - as far as the application is concerned the exec() function is a blocking - function that returns with \l{Qt::DropActions}{one of several values}. - These indicate how the operation ended, and are described in more detail - below. - - Note that the exec() function does not block the main event loop. - - For widgets that need to distinguish between mouse clicks and drags, it - is useful to reimplement the widget's - \l{QWidget::mousePressEvent()}{mousePressEvent()} function to record to - start position of the drag: - - \snippet doc/src/snippets/draganddrop/dragwidget.cpp 6 - - Later, in \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()}, we can determine - whether a drag should begin, and construct a drag object to handle the - operation: - - \snippet doc/src/snippets/draganddrop/dragwidget.cpp 7 - \dots - \snippet doc/src/snippets/draganddrop/dragwidget.cpp 8 - - This particular approach uses the \l QPoint::manhattanLength() function - to get a rough estimate of the distance between where the mouse click - occurred and the current cursor position. This function trades accuracy - for speed, and is usually suitable for this purpose. - - \section1 Dropping - - To be able to receive media dropped on a widget, call - \l{QWidget::setAcceptDrops()}{setAcceptDrops(true)} for the widget, - and reimplement the \l{QWidget::dragEnterEvent()}{dragEnterEvent()} and - \l{QWidget::dropEvent()}{dropEvent()} event handler functions. - - For example, the following code enables drop events in the constructor of - a QWidget subclass, making it possible to usefully implement drop event - handlers: - - \snippet doc/src/snippets/dropevents/window.cpp 0 - \dots - \snippet doc/src/snippets/dropevents/window.cpp 1 - \snippet doc/src/snippets/dropevents/window.cpp 2 - - The dragEnterEvent() function is typically used to inform Qt about the - types of data that the widget accepts. - You must reimplement this function if you want to receive either - QDragMoveEvent or QDropEvent in your reimplementations of - \l{QWidget::dragMoveEvent()}{dragMoveEvent()} and - \l{QWidget::dropEvent()}{dropEvent()}. - - The following code shows how \l{QWidget::dragEnterEvent()}{dragEnterEvent()} - can be reimplemented to - tell the drag and drop system that we can only handle plain text: - - \snippet doc/src/snippets/dropevents/window.cpp 3 - - The \l{QWidget::dropEvent()}{dropEvent()} is used to unpack dropped data - and handle it in way that is suitable for your application. - - In the following code, the text supplied in the event is passed to a - QTextBrowser and a QComboBox is filled with the list of MIME types that - are used to describe the data: - - \snippet doc/src/snippets/dropevents/window.cpp 4 - - In this case, we accept the proposed action without checking what it is. - In a real world application, it may be necessary to return from the - \l{QWidget::dropEvent()}{dropEvent()} function without accepting the - proposed action or handling - the data if the action is not relevant. For example, we may choose to - ignore Qt::LinkAction actions if we do not support - links to external sources in our application. - - \section2 Overriding Proposed Actions - - We may also ignore the proposed action, and perform some other action on - the data. To do this, we would call the event object's - \l{QDropEvent::setDropAction()}{setDropAction()} with the preferred - action from Qt::DropAction before calling \l{QEvent::}{accept()}. - This ensures that the replacement drop action is used instead of the - proposed action. - - For more sophisticated applications, reimplementing - \l{QWidget::dragMoveEvent()}{dragMoveEvent()} and - \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()} will let you make - certain parts of your widgets sensitive to drop events, and give you more - control over drag and drop in your application. - - \section2 Subclassing Complex Widgets - - Certain standard Qt widgets provide their own support for drag and drop. - When subclassing these widgets, it may be necessary to reimplement - \l{QWidget::dragMoveEvent()}{dragMoveEvent()} in addition to - \l{QWidget::dragEnterEvent()}{dragEnterEvent()} and - \l{QWidget::dropEvent()}{dropEvent()} to prevent the base class from - providing default drag and drop handling, and to handle any special - cases you are interested in. - - \section1 Drag and Drop Actions - - In the simplest case, the target of a drag and drop action receives a - copy of the data being dragged, and the source decides whether to - delete the original. This is described by the \c CopyAction action. - The target may also choose to handle other actions, specifically the - \c MoveAction and \c LinkAction actions. If the source calls - QDrag::exec(), and it returns \c MoveAction, the source is responsible - for deleting any original data if it chooses to do so. The QMimeData - and QDrag objects created by the source widget \e{should not be deleted} - - they will be destroyed by Qt. The target is responsible for taking - ownership of the data sent in the drag and drop operation; this is - usually done by keeping references to the data. - - If the target understands the \c LinkAction action, it should - store its own reference to the original information; the source - does not need to perform any further processing on the data. The - most common use of drag and drop actions is when performing a - Move within the same widget; see the section on \l{Drop Actions} - for more information about this feature. - - The other major use of drag actions is when using a reference type - such as text/uri-list, where the dragged data are actually references - to files or objects. - - \section1 Adding New Drag and Drop Types - - Drag and drop is not limited to text and images. Any type of information - can be transferred in a drag and drop operation. To drag information - between applications, the applications must be able to indicate to each - other which data formats they can accept and which they can produce. - This is achieved using - \l{http://www.rfc-editor.org/rfc/rfc1341.txt}{MIME types}. The QDrag - object constructed by the source contains a list of MIME types that it - uses to represent the data (ordered from most appropriate to least - appropriate), and the drop target uses one of these to access the data. - For common data types, the convenience functions handle the MIME types - used transparently but, for custom data types, it is necessary to - state them explicitly. - - To implement drag and drop actions for a type of information that is - not covered by the QDrag convenience functions, the first and most - important step is to look for existing formats that are appropriate: - The Internet Assigned Numbers Authority (\l{http://www.iana.org}{IANA}) - provides a - \l{http://www.iana.org/assignments/media-types/}{hierarchical - list of MIME media types} at the Information Sciences Institute - (\l{http://www.isi.edu}{ISI}). - Using standard MIME types maximizes the interoperability of - your application with other software now and in the future. - - To support an additional media type, simply set the data in the QMimeData - object with the \l{QMimeData::setData()}{setData()} function, supplying - the full MIME type and a QByteArray containing the data in the appropriate - format. The following code takes a pixmap from a label and stores it - as a Portable Network Graphics (PNG) file in a QMimeData object: - - \snippet doc/src/snippets/separations/finalwidget.cpp 0 - - Of course, for this case we could have simply used - \l{QMimeData::setImageData()}{setImageData()} instead to supply image data - in a variety of formats: - - \snippet doc/src/snippets/separations/finalwidget.cpp 1 - - The QByteArray approach is still useful in this case because it provides - greater control over the amount of data stored in the QMimeData object. - - Note that custom datatypes used in item views must be declared as - \l{QMetaObject}{meta objects} and that stream operators for them - must be implemented. - - \section1 Drop Actions - - In the clipboard model, the user can \e cut or \e copy the source - information, then later paste it. Similarly in the drag and drop - model, the user can drag a \e copy of the information or they can drag - the information itself to a new place (\e moving it). The - drag and drop model has an additional complication for the programmer: - The program doesn't know whether the user wants to cut or copy the - information until the operation is complete. This often makes no - difference when dragging information between applications, but within - an application it is important to check which drop action was used. - - We can reimplement the mouseMoveEvent() for a widget, and start a drag - and drop operation with a combination of possible drop actions. For - example, we may want to ensure that dragging always moves objects in - the widget: - - \snippet doc/src/snippets/draganddrop/dragwidget.cpp 7 - \dots - \snippet doc/src/snippets/draganddrop/dragwidget.cpp 8 - - The action returned by the exec() function may default to a - \c CopyAction if the information is dropped into another application - but, if it is dropped in another widget in the same application, we - may obtain a different drop action. - - The proposed drop actions can be filtered in a widget's dragMoveEvent() - function. However, it is possible to accept all proposed actions in - the dragEnterEvent() and let the user decide which they want to accept - later: - - \snippet doc/src/snippets/draganddrop/dragwidget.cpp 0 - - When a drop occurs in the widget, the dropEvent() handler function is - called, and we can deal with each possible action in turn. First, we - deal with drag and drop operations within the same widget: - - \snippet doc/src/snippets/draganddrop/dragwidget.cpp 1 - - In this case, we refuse to deal with move operations. Each type of drop - action that we accept is checked and dealt with accordingly: - - \snippet doc/src/snippets/draganddrop/dragwidget.cpp 2 - \snippet doc/src/snippets/draganddrop/dragwidget.cpp 3 - \snippet doc/src/snippets/draganddrop/dragwidget.cpp 4 - \dots - \snippet doc/src/snippets/draganddrop/dragwidget.cpp 5 - - Note that we checked for individual drop actions in the above code. - As mentioned above in the section on - \l{#Overriding Proposed Actions}{Overriding Proposed Actions}, it is - sometimes necessary to override the proposed drop action and choose a - different one from the selection of possible drop actions. - To do this, you need to check for the presence of each action in the value - supplied by the event's \l{QDropEvent::}{possibleActions()}, set the drop - action with \l{QDropEvent::}{setDropAction()}, and call - \l{QEvent::}{accept()}. - - \section1 Drop Rectangles - - The widget's dragMoveEvent() can be used to restrict drops to certain parts - of the widget by only accepting the proposed drop actions when the cursor - is within those areas. For example, the following code accepts any proposed - drop actions when the cursor is over a child widget (\c dropFrame): - - \snippet doc/src/snippets/droprectangle/window.cpp 0 - - The dragMoveEvent() can also be used if you need to give visual - feedback during a drag and drop operation, to scroll the window, or - whatever is appropriate. - - \section1 The Clipboard - - Applications can also communicate with each other by putting data on - the clipboard. To access this, you need to obtain a QClipboard object - from the QApplication object: - - \snippet examples/widgets/charactermap/mainwindow.cpp 3 - - The QMimeData class is used to represent data that is transferred to and - from the clipboard. To put data on the clipboard, you can use the - setText(), setImage(), and setPixmap() convenience functions for common - data types. These functions are similar to those found in the QMimeData - class, except that they also take an additional argument that controls - where the data is stored: If \l{QClipboard::Mode}{Clipboard} is - specified, the data is placed on the clipboard; if - \l{QClipboard::Mode}{Selection} is specified, the data is placed in the - mouse selection (on X11 only). By default, data is put on the clipboard. - - For example, we can copy the contents of a QLineEdit to the clipboard - with the following code: - - \snippet examples/widgets/charactermap/mainwindow.cpp 11 - - Data with different MIME types can also be put on the clipboard. - Construct a QMimeData object and set data with setData() function in - the way described in the previous section; this object can then be - put on the clipboard with the - \l{QClipboard::setMimeData()}{setMimeData()} function. - - The QClipboard class can notify the application about changes to the - data it contains via its \l{QClipboard::dataChanged()}{dataChanged()} - signal. For example, we can monitor the clipboard by connecting this - signal to a slot in a widget: - - \snippet doc/src/snippets/clipboard/clipwindow.cpp 0 - - The slot connected to this signal can read the data on the clipboard - using one of the MIME types that can be used to represent it: - - \snippet doc/src/snippets/clipboard/clipwindow.cpp 1 - \dots - \snippet doc/src/snippets/clipboard/clipwindow.cpp 2 - - The \l{QClipboard::selectionChanged()}{selectionChanged()} signal can - be used on X11 to monitor the mouse selection. - - \section1 Examples - - \list - \o \l{draganddrop/draggableicons}{Draggable Icons} - \o \l{draganddrop/draggabletext}{Draggable Text} - \o \l{draganddrop/dropsite}{Drop Site} - \o \l{draganddrop/fridgemagnets}{Fridge Magnets} - \o \l{draganddrop/puzzle}{Drag and Drop Puzzle} - \endlist - - \section1 Interoperating with Other Applications - - On X11, the public \l{http://www.newplanetsoftware.com/xdnd/}{XDND - protocol} is used, while on Windows Qt uses the OLE standard, and - Qt for Mac OS X uses the Carbon Drag Manager. On X11, XDND uses MIME, - so no translation is necessary. The Qt API is the same regardless of - the platform. On Windows, MIME-aware applications can communicate by - using clipboard format names that are MIME types. Already some - Windows applications use MIME naming conventions for their - clipboard formats. Internally, Qt uses QWindowsMime and - QMacPasteboardMime for translating proprietary clipboard formats - to and from MIME types. - - On X11, Qt also supports drops via the Motif Drag & Drop Protocol. The - implementation incorporates some code that was originally written by - Daniel Dardailler, and adapted for Qt by Matt Koss <koss@napri.sk> - and Nokia. Here is the original copyright notice: - - \legalese - Copyright 1996 Daniel Dardailler. - - Permission to use, copy, modify, distribute, and sell this software - for any purpose is hereby granted without fee, provided that the above - copyright notice appear in all copies and that both that copyright - notice and this permission notice appear in supporting documentation, - and that the name of Daniel Dardailler not be used in advertising or - publicity pertaining to distribution of the software without specific, - written prior permission. Daniel Dardailler makes no representations - about the suitability of this software for any purpose. It is - provided "as is" without express or implied warranty. - - Modifications Copyright 1999 Matt Koss, under the same license as - above. - \endlegalese - \omit NOTE: The copyright notice is from qmotifdnd_x11.cpp. \endomit - - Note: The Motif Drag \& Drop Protocol only allows receivers to - request data in response to a QDropEvent. If you attempt to - request data in response to e.g. a QDragMoveEvent, an empty - QByteArray is returned. -*/ - -/*! - \page porting4-dnd.html - \title Porting to Qt 4 - Drag and Drop - \contentspage {Porting Guides}{Contents} - \previouspage Porting to Qt 4 - Virtual Functions - \nextpage Porting UI Files to Qt 4 - \ingroup porting - \brief An overview of the porting process for applications that use drag and drop. - - Qt 4 introduces a new set of classes to handle drag and drop operations - that aim to be easier to use than their counterparts in Qt 3. As a result, - the way that drag and drop is performed is quite different to the way - developers of Qt 3 applications have come to expect. In this guide, we - show the differences between the old and new APIs and indicate where - applications need to be changed when they are ported to Qt 4. - - \tableofcontents - - \section1 Dragging - - In Qt 3, drag operations are encapsulated by \c QDragObject (see Q3DragObject) - and its subclasses. These objects are typically constructed on the heap in - response to mouse click or mouse move events, and ownership of them is - transferred to Qt so that they can be deleted when the corresponding drag and - drop operations have been completed. The drag source has no control over how - the drag and drop operation is performed once the object's - \l{Q3DragObject::}{drag()} function is called, and it receives no information - about how the operation ended. - - \snippet doc/src/snippets/code/doc_src_dnd.qdoc 0 - - Similarly, in Qt 4, drag operations are also initiated when a QDrag object - is constructed and its \l{QDrag::}{exec()} function is called. In contrast, - these objects are typically constructed on the stack rather than the heap - since each drag and drop operation is performed synchronously as far as the - drag source is concerned. One key benefit of this is that the drag source - can receive information about how the operation ended from the value returned - by \l{QDrag::}{exec()}. - - \snippet doc/src/snippets/porting4-dropevents/window.cpp 2 - \snippet doc/src/snippets/porting4-dropevents/window.cpp 3 - \dots 8 - \snippet doc/src/snippets/porting4-dropevents/window.cpp 4 - \snippet doc/src/snippets/porting4-dropevents/window.cpp 5 - - A key difference in the above code is the use of the QMimeData class to hold - information about the data that is transferred. Qt 3 relies on subclasses - of \c QDragObject to provide support for specific MIME types; in Qt 4, the - use of QMimeData as a generic container for data makes the relationship - between MIME type and data more tranparent. QMimeData is described in more - detail later in this document. - - \section1 Dropping - - In both Qt 3 and Qt 4, it is possible to prepare a custom widget to accept - dropped data by enabling the \l{QWidget::}{acceptDrops} property of a widget, - usually in the widget's constructor. As a result, the widget will receive - drag enter events that can be handled by its \l{QWidget::}{dragEnterEvent()} - function. - As in Qt 3, custom widgets in Qt 4 handle these events by determining - whether the data supplied by the drag and drop operation can be dropped onto - the widget. Since the classes used to encapsulate MIME data are different in - Qt 3 and Qt 4, the exact implementations differ. - - In Qt 3, the drag enter event is handled by checking whether each of the - standard \c QDragObject subclasses can decode the data supplied, and - indicating success or failure of these checks via the event's - \l{QDragEnterEvent::}{accept()} function, as shown in this simple example: - - \snippet doc/src/snippets/code/doc_src_dnd.qdoc 1 - - In Qt 4, you can examine the MIME type describing the data to determine - whether the widget should accept the event or, for common data types, you - can use convenience functions: - - \snippet doc/src/snippets/porting4-dropevents/window.cpp 0 - - The widget has some control over the type of drag and drop operation to be - performed. In the above code, the action proposed by the drag source is - accepted, but - \l{Drag and Drop#Overriding Proposed Actions}{this can be overridden} if - required. - - In both Qt 3 and Qt 4, it is necessary to accept a given drag event in order - to receive the corresponding drop event. A custom widget in Qt 3 that can - accept dropped data in the form of text or images might provide an - implementation of \l{QWidget::}{dropEvent()} that looks like the following: - - \snippet doc/src/snippets/code/doc_src_dnd.qdoc 2 - - In Qt 4, the event is handled in a similar way: - - \snippet doc/src/snippets/porting4-dropevents/window.cpp 1 - - It is also possible to extract data stored for a particular MIME type if it - was specified by the drag source. - - \section1 MIME Types and Data - - In Qt 3, data to be transferred in drag and drop operations is encapsulated - in instances of \c QDragObject and its subclasses, representing specific - data formats related to common MIME type and subtypes. - - In Qt 4, only the QMimeData class is used to represent data, providing a - container for data stored in multiple formats, each associated with - a relevant MIME type. Since arbitrary MIME types can be specified, there is - no need for an extensive class hierarchy to represent different kinds of - information. Additionally, QMimeData it provides some convenience functions - to allow the most common data formats to be stored and retrieved with less - effort than for arbitrary MIME types. -*/ diff --git a/doc/src/ecmascript.qdoc b/doc/src/ecmascript.qdoc deleted file mode 100644 index a13f55d..0000000 --- a/doc/src/ecmascript.qdoc +++ /dev/null @@ -1,313 +0,0 @@ -/**************************************************************************** -** -** 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 ecmascript.html - \title ECMAScript Reference - \ingroup scripting - \brief A list of objects, functions and properties supported by QtScript. - - This reference contains a list of objects, functions and - properties supported by QtScript. - - \tableofcontents - - \section1 The Global Object - - \section2 Value Properties - - \list - \o NaN - \o Infinity - \o undefined - \o Math - \endlist - - \section2 Function Properties - - \list - \o eval(x) - \o parseInt(string, radix) - \o parseFloat(string) - \o isNaN(number) - \o isFinite(number) - \o decodeURI(encodedURI) - \o decodeURIComponent(encodedURIComponent) - \o encodeURI(uri) - \o encodeURIComponent(uriComponent) - \endlist - - \section2 Constructor Properties - - \list - \o Object - \o Function - \o Array - \o String - \o Boolean - \o Number - \o Date - \o RegExp - \o Error - \o EvalError - \o RangeError - \o ReferenceError - \o SyntaxError - \o TypeError - \o URIError - \endlist - - \section1 Object Objects - - \section2 Object Prototype Object - - \list - \o toString() - \o toLocaleString() - \o valueOf() - \o hasOwnProperty(V) - \o isPrototypeOf(V) - \o propertyIsEnumerable(V) - \endlist - - \section1 Function Objects - - \section2 Function Prototype Object - - \section3 Function Properties - - \list - \o toString() - \o apply(thisArg, argArray) - \o call(thisArg [, arg1 [, arg2, ...]]) - \endlist - - \section1 Array Objects - - \section2 Array Prototype Object - - \section3 Function Properties - - \list - \o toString() - \o toLocaleString() - \o concat([item1 [, item2 [, ...]]]) - \o join(separator) - \o pop() - \o push([item1 [, item2 [, ...]]]) - \o reverse() - \o shift() - \o slice(start, end) - \o sort(comparefn) - \o splice(start, deleteCount[, item1 [, item2 [, ...]]]) - \o unshift([item1 [, item2 [, ...]]]) - \endlist - - \section1 String Objects - - \section2 String Prototype Object - - \section3 Function Properties - - \list - \o toString() - \o valueOf() - \o charAt(pos) - \o charCodeAt(pos) - \o concat([string1 [, string2 [, ...]]]) - \o indexOf(searchString ,position) - \o lastIndexOf(searchString, position) - \o localeCompare(that) - \o match(regexp) - \o replace(searchValue, replaceValue) - \o search(regexp) - \o slice(start, end) - \o split(separator, limit) - \o substring(start, end) - \o toLowerCase() - \o toLocaleLowerCase() - \o toUpperCase() - \o toLocaleUpperCase() - \endlist - - \section1 Boolean Objects - - \section2 Boolean Prototype Object - - \section3 Function Properties - - \list - \o toString() - \o valueOf() - \endlist - - \section1 Number Objects - - \section2 Number Prototype Object - - \section3 Function Properties - - \list - \o toString(radix) - \o toLocaleString() - \o toFixed(fractionDigits) - \o toExponential(fractionDigits) - \o toPrecision(precision) - \endlist - - \section1 The Math Object - - \section2 Value Properties - - \list - \o E - \o LN10 - \o LN2 - \o LOG2E - \o LOG10E - \o PI - \o SQRT1_2 - \o SQRT2 - \endlist - - \section2 Function Properties - - \list - \o abs(x) - \o acos(x) - \o asin(x) - \o atan(x) - \o atan2(y, x) - \o ceil(x) - \o cos(x) - \o exp(x) - \o floor(x) - \o log(x) - \o max([value1 [, value2 [, ...]]]) - \o min([value1 [, value2 [, ...]]]) - \o pow(x, y) - \o random() - \o round(x) - \o sin(x) - \o sqrt(x) - \o tan(x) - \endlist - - \section1 Date Objects - - \section2 Date Prototype Object - - \section3 Function Properties - - \list - \o toString() - \o toDateString() - \o toTimeString() - \o toLocaleString() - \o toLocaleDateString() - \o toLocaleTimeString() - \o valueOf() - \o getTime() - \o getFullYear() - \o getUTCFullYear() - \o getMonth() - \o getUTCMonth() - \o getDate() - \o getUTCDate() - \o getDay() - \o getUTCDay() - \o getHours() - \o getUTCHours() - \o getMinutes() - \o getUTCMinutes() - \o getSeconds() - \o getUTCSeconds() - \o getMilliseconds() - \o getUTCMilliseconds() - \o getTimeZoneOffset() - \o setTime(time) - \o setMilliseconds(ms) - \o setUTCMilliseconds(ms) - \o setSeconds(sec [, ms]) - \o setUTCSeconds(sec [, ms]) - \o setMinutes(min [, sec [, ms]]) - \o setUTCMinutes(min [, sec [, ms]]) - \o setHours(hour [, min [, sec [, ms]]]) - \o setUTCHours(hour [, min [, sec [, ms]]]) - \o setDate(date) - \o setUTCDate(date) - \o setMonth(month [, date]) - \o setUTCMonth(month [, date]) - \o setFullYear(year [, month [, date]]) - \o setUTCFullYear(year [, month [, date]]) - \o toUTCString() - \endlist - - \section1 RegExp Objects - - \section2 RegExp Prototype Object - - \section3 Function Properties - - \list - \o exec(string) - \o test(string) - \o toString() - \endlist - - \section1 Error Objects - - \section2 Error Prototype Object - - \section3 Value Properties - - \list - \o name - \o message - \endlist - - \section3 Function Properties - - \list - \o toString() - \endlist - -*/ diff --git a/doc/src/emb-accel.qdoc b/doc/src/emb-accel.qdoc deleted file mode 100644 index 818538a..0000000 --- a/doc/src/emb-accel.qdoc +++ /dev/null @@ -1,143 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-accel.html - - \target add your graphics driver to Qt for Embedded Linux - - \title Adding an Accelerated Graphics Driver to Qt for Embedded Linux - \ingroup qt-embedded-linux - - In \l{Qt for Embedded Linux}, painting is a pure software implementation - normally performed in two steps. First, each window is rendered - onto a QWSWindowSurface using QPaintEngine. Second, the server - composes the surface images and copies the composition to the - screen (see \l{Qt for Embedded Linux Architecture} for details). - \l{Qt for Embedded Linux} uses QRasterPaintEngine (a raster-based implementation of - QPaintEngine) to implement painting operations, and uses QScreen - to implement window composition. - - It is possible to add an accelerated graphics driver to take - advantage of available hardware resources. This is described in - detail in the \l {Accelerated Graphics Driver Example} which uses - the following approach: - - \tableofcontents - - \warning This feature is under development and is subject to - change. - - \section1 Step 1: Create a Custom Screen - - Create a custom screen by deriving from the QScreen class. - - The \l {QScreen::}{connect()}, \l {QScreen::}{disconnect()}, \l - {QScreen::}{initDevice()} and \l {QScreen::}{shutdownDevice()} - functions are declared as pure virtual functions in QScreen and - must be implemented. These functions are used to configure the - hardware, or query its configuration. The \l - {QScreen::}{connect()} and \l {QScreen::}{disconnect()} are called - by both the server and client processes, while the \l - {QScreen::}{initDevice()} and \l {QScreen::}{shutdownDevice()} - functions are only called by the server process. - - You might want to accelerate the final copying to the screen by - reimplementing the \l {QScreen::}{blit()} and \l - {QScreen::}{solidFill()} functions. - - \section1 Step 2: Implement a Custom Raster Paint Engine - - Implement the painting operations by subclassing the - QRasterPaintEngine class. - - To accelerate a graphics primitive, simply reimplement the - corresponding function in your custom paint engine. If there is - functionality you do not want to reimplement (such as certain - pens, brushes, modes, etc.), you can just call the corresponding - base class implementation. - - \section1 Step 3: Make the Paint Device Aware of Your Paint Engine - - To activate your paint engine you must create a subclass of the - QCustomRasterPaintDevice class and reimplement its \l - {QCustomRasterPaintDevice::}{paintEngine()} function. Let this - function return a pointer to your paint engine. In addition, the - QCustomRasterPaintDevice::memory() function must be reimplemented - to return a pointer to the buffer where the painting should be - done. - - \table - \header \o Acceleration Without a Memory Buffer - \row - \o - - By default the QRasterPaintEngine draws into a memory buffer (this can - be local memory, shared memory or graphics memory mapped into - application memory). - In some cases you might want to avoid using a memory buffer directly, - e.g if you want to use an accelerated graphic controller to handle all - the buffer manipulation. This can be implemented by reimplementing - the QCustomRasterPaintDevice::memory() function to return 0 (meaning - no buffer available). Then, whenever a color or image buffer normally - would be written into paint engine buffer, the paint engine will call the - QRasterPaintEngine::drawColorSpans() and - QRasterPaintEngine::drawBufferSpan() functions instead. - - Note that the default implementations of these functions only - calls qFatal() with an error message; reimplement the functions - and let them do the appropriate communication with the accelerated - graphics controller. - - \endtable - - \section1 Step 4: Make the Window Surface Aware of Your Paint Device - - Derive from the QWSWindowSurface class and reimplement its \l - {QWSWindowSurface::}{paintDevice()} function. Make this function - return a pointer to your custom raster paint device. - - \section1 Step 5: Enable Creation of an Instance of Your Window Surface - - Finally, reimplement QScreen's \l {QScreen::}{createSurface()} - function and make this function able to create an instance of your - QWSWindowSurface subclass. -*/ diff --git a/doc/src/emb-charinput.qdoc b/doc/src/emb-charinput.qdoc deleted file mode 100644 index 5ceb6a4..0000000 --- a/doc/src/emb-charinput.qdoc +++ /dev/null @@ -1,164 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-charinput.html - - \title Qt for Embedded Linux Character Input - \ingroup qt-embedded-linux - - When running a \l {Qt for Embedded Linux} application, it either runs as a - server or connects to an existing server. The keyboard driver is - loaded by the server application when it starts running, using - Qt's \l {How to Create Qt Plugins}{plugin system}. - - Internally in the client/server protocol, all system generated - events, including key events, are passed to the server application - which then propagates the event to the appropriate client. Note - that key events do not always come from a keyboard device, they - can can also be generated by the server process using input - widgets. - - \table - \header \o Input Widgets - \row - \o - - The server process may call the static QWSServer::sendKeyEvent() - function at any time. Typically, this is done by popping up a - widget that enables the user specify characters with the pointer - device. - - Note that the key input widget should not take focus since the - server would then just send the key events back to the input - widget. One way to make sure that the input widget never takes - focus is to set the Qt::Tool widget flag in the QWidget - constructor. - - The \l{Qt Extended} environment contains various input widgets such as - Handwriting Recognition and Virtual Keyboard. - - \endtable - - \tableofcontents - - \section1 Available Keyboard Drivers - - \l {Qt for Embedded Linux} provides ready-made drivers for the console - (TTY) and the standard Linux Input Subsystem (USB, PS/2, ...). Run the - \c configure script to list the available drivers: - - \snippet doc/src/snippets/code/doc_src_emb-charinput.qdoc 0 - - Note that only the console (TTY) keyboard driver handles console - switching (\bold{Ctrl+Alt+F1}, ..., \bold{Ctrl+Alt+F10}) and - termination (\bold{Ctrl+Alt+Backspace}). - - In the default Qt configuration, only the "TTY" driver is - enabled. The various drivers can be enabled and disabled using the - \c configure script. For example: - - \snippet doc/src/snippets/code/doc_src_emb-charinput.qdoc 1 - - Custom keyboard drivers can be implemented by subclassing the - QWSKeyboardHandler class and creating a keyboard driver plugin - (derived from the QKbdDriverPlugin class). The default - implementation of the QKbdDriverFactory class will automatically - detect the plugin, loading the driver into the server application - at run-time. - - \section1 Keymaps - - Starting with 4.6, \l {Qt for Embedded Linux} has gained support for - user defined keymaps. Keymap handling is supported by the built-in - keyboard drivers \c TTY and \c LinuxInput. Custom keyboard drivers can - use the existing keymap handling code via - QWSKeyboardHandler::processKeycode(). - - By default Qt will use an internal, compiled-in US keymap. - See the options below for how to load a different keymap. - - \section1 Specifying a Keyboard Driver - - To specify which driver to use, set the QWS_KEYBOARD environment - variable. For example (if the current shell is bash, ksh, zsh or - sh): - - \snippet doc/src/snippets/code/doc_src_emb-charinput.qdoc 2 - - The \c <driver> arguments are \c TTY, \c LinuxInput and \l - {QKbdDriverPlugin::keys()}{keys} identifying custom drivers, and the - driver specific options are typically a device, e.g., \c /dev/tty0. - - Multiple keyboard drivers can be specified in one go: - - \snippet doc/src/snippets/code/doc_src_emb-charinput.qdoc 3 - - Input will be read from all specified drivers. - - Currently the following options are supported by both the \c TTY and \c - LinuxInput driver: - - \table - \header \o Option \o Description - \row \o \c /dev/xxx \o - Open the specified device, instead of the driver's default device. - \row \o \c repeat-delay=<d> \o - Time (in milliseconds) until auto-repeat kicks in. - \row \o \c repeat-rate=<r> \o - Time (in milliseconds) specifying the interval between auto-repeats. - \row \o \c keymap=xx.qmap \o - File name of a keymap file in Qt's \c qmap format. See \l {kmap2qmap} - for instructions on how to create thoes files.\br Note that the file - name can of course also be the name of a QResource. - \row \o \c disable-zap \o - Disable the QWS server "Zap" shortcut \bold{Ctrl+Alt+Backspace} - \row \o \c enable-compose \o - Activate Latin-1 composing features in the built-in US keymap. You can - use the right \c AltGr or right \c Alt is used as a dead key modifier, - while \c AltGr+. is the compose key. For example: - \list - \o \c AltGr + \c " + \c u = \uuml (u with diaeresis / umlaut u) - \o \c AltGr + \c . + \c / + \c o = \oslash (slashed o) - \endlist - \endtable - -*/ diff --git a/doc/src/emb-crosscompiling.qdoc b/doc/src/emb-crosscompiling.qdoc deleted file mode 100644 index 2e0ba4b..0000000 --- a/doc/src/emb-crosscompiling.qdoc +++ /dev/null @@ -1,191 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-crosscompiling.html - - \title Cross-Compiling Qt for Embedded Linux Applications - \ingroup qt-embedded-linux - - Cross-compiling is the process of compiling an application on one - machine, producing executable code for a different machine or - device. To cross-compile a \l{Qt for Embedded Linux} application, - use the following approach: - - \tableofcontents - - \note The cross-compiling procedure has the configuration - process in common with the installation procedure; i.e., you might - not necessarily have to perform all the mentioned actions - depending on your current configuration. - - \section1 Step 1: Set the Cross-Compiler's Path - - Specify which cross-compiler to use by setting the \c PATH - environment variable. For example, if the current shell is bash, - ksh, zsh or sh: - - \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 0 - - \section1 Step 2: Create a Target Specific qmake Specification - - The qmake tool requires a platform and compiler specific \c - qmake.conf file describing the various default values, to generate - the appropriate Makefiles. The standard \l{Qt for Embedded Linux} - distribution provides such files for several combinations of - platforms and compilers. These files are located in the - distribution's \c mkspecs/qws subdirectory. - - Each platform has a default specification. \l{Qt for Embedded Linux} will - use the default specification for the current platform unless told - otherwise. To override this behavior, you can use the \c configure - script's \c -platform option to change the specification for the host - platform (where compilation will take place). - - The \c configure script's \c -xplatform option is used to provide a - specification for the target architecture (where the library will be - deployed). - - For example, to cross-compile an application to run on a device with - an ARM architecture, using the GCC toolchain, run the configure - script at the command line in the following way: - - \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 1 - - If neither of the provided specifications fits your target device, - you can create your own. To create a custom \c qmake.conf file, - just copy and customize an already existing file. For example: - - \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 2 - - \note When defining a mkspec for a Linux target, the directory must - be prefixed with "linux-". We recommend that you copy the entire - directory. - - Note also that when providing you own qmake specifcation, you must - use the \c configure script's \c -xplatform option to make - \l{Qt for Embedded Linux} aware of the custom \c qmake.conf file. - - \section1 Step 3: Provide Architecture Specific Files - - Starting with Qt 4, all of Qt's implicitly shared classes can - safely be copied across threads like any other value classes, - i.e., they are fully reentrant. This is accomplished by - implementing reference counting operations using atomic hardware - instructions on all the different platforms supported by Qt. - - To support a new architecture, it is important to ensure that - these platform-specific atomic operations are implemented in a - corresponding header file (\c qatomic_ARCH.h), and that this file - is located in Qt's \c src/corelib/arch directory. For example, the - Intel 80386 implementation is located in \c - src/corelib/arch/qatomic_i386.h. - - See the \l {Implementing Atomic Operations} documentation for - details. - - \section1 Step 4: Provide Hardware Drivers - - Without the proper mouse and keyboard drivers, you will not be - able to give any input to your application when it is installed on - the target device. You must also ensure that the appropriate - screen driver is present to make the server process able to put - the application's widgets on screen. - - \l{Qt for Embedded Linux} provides several ready-made mouse, keyboard and - screen drivers, see the \l{Qt for Embedded Linux Pointer Handling}{pointer - handling}, \l{Qt for Embedded Linux Character Input}{character input} and - \l{Qt for Embedded Linux Display Management}{display management} - documentation for details. - - In addition, custom drivers can be added by deriving from the - QWSMouseHandler, QWSKeyboardHandler and QScreen classes - respectively, and by creating corresponding plugins to make use of - Qt's plugin mechanism (dynamically loading the drivers into the - server application at runtime). Note that the plugins must be - located in a location where Qt will look for plugins, e.g., the - standard \c plugin directory. - - See the \l {How to Create Qt Plugins} documentation and the \l - {tools/plugandpaint}{Plug & Paint} example for details. - - \section1 Step 5: Build the Target Specific Executable - - Before building the executable, you must specify the target - architecture as well as the target specific hardware drivers by - running the \c configure script: - - \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 3 - - It is also important to make sure that all the third party - libraries that the application and the Qt libraries require, are - present in the tool chain. In particular, if the zlib and jpeg - libraries are not available, they must be included by running the - \c configure script with the \c -L and \c -I options. For example: - - \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 4 - - The JPEG source can be downloaded from \l http://www.ijg.org/. The - \l{Qt for Embedded Linux} distribution includes a version of the zlib source - that can be compiled into the Qt for Embedded Linux library. If integrators - wish to use a later version of the zlib library, it can be - downloaded from the \l http://www.gzip.org/zlib/ website. - - Then build the executable: - - \snippet doc/src/snippets/code/doc_src_emb-crosscompiling.qdoc 5 - - That's all. Your target specific executable is ready for deployment. - - \table 100% - \row - \o \bold {See also:} - - \l{Qt for Embedded Linux Architecture} and \l{Deploying Qt for Embedded Linux - Applications}. - - \row - \o \bold{Third party resources:} - - \l{http://silmor.de/29}{Cross compiling Qt/Win Apps on Linux} covers the - process of cross-compiling Windows applications on Linux. - \endtable -*/ diff --git a/doc/src/emb-deployment.qdoc b/doc/src/emb-deployment.qdoc deleted file mode 100644 index 9a83dcf..0000000 --- a/doc/src/emb-deployment.qdoc +++ /dev/null @@ -1,111 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-deployment.html - - \title Deploying Qt for Embedded Linux Applications - \ingroup qt-embedded-linux - - The procedure of deploying an Qt application on \l{Qt for Embedded Linux} - is essentially the same as the deployment procedure on X11 platforms - which is described in detail in the \l {Deploying an Application - on X11 Platforms} documentation. See also the \l {Deploying Qt - applications}{general remarks} about deploying Qt applications. - - In addition, there is a couple of Qt for Embedded Linux specific issues to - keep in mind: - - \tableofcontents - - \section1 Fonts - - When Qt for Embedded Linux applications run, they look for a file called - \c fontdir in Qt's \c /lib/fonts/ directory defining the - fonts that are available to the application (i.e. the fonts - located in the mentioned directory). - - For that reason, the preferred fonts must be copied to the \c - /lib/fonts/ directory, and the \c fontdir file must be customized - accordingly. See the \l {Qt for Embedded Linux Fonts}{fonts} documentation - for more details about the supported font formats. - - Note that the application will look for the \c /lib/fonts/ - directory relative to the path set using the \c -prefix parameter - when running the \c configure script; ensure that this is a - sensible path in the target device environment. See the \l - {Installing Qt for Embedded Linux#Step 3: Building the - Library}{installation} documentation for more details. - - \section1 Environment Variables - - In general, any variable value that differs from the provided - default values must be set explicitly in the target device - environment. Typically, these include the QWS_MOUSE_PROTO, - QWS_KEYBOARD and QWS_DISPLAY variables specifying the drivers for - pointer handling, character input and display management, - respectively. - - For example, without the proper mouse and keyboard drivers, there - is no way to give any input to the application when it is - installed on the target device. By running the \c configure script - using the \c -qt-kbd-<keyboarddriver> and \c - -qt-mouse-<mousedriver> options, the drivers are enabled, but in - addition the drivers and the preferred devices must be specified - as the ones to use in the target environment, by setting the - environment variables. - - See the \l{Qt for Embedded Linux Pointer Handling}{pointer handling}, - \l{Qt for Embedded Linux Character Input}{character input} and - \l{Qt for Embedded Linux Display Management}{display management} - documentation for more information. - - \section1 Framebuffer Support - - No particular actions are required to enable the framebuffer on - target devices: The Linux framebuffer is enabled by default on all - modern Linux distributions. For information on older versions, see - \l http://en.tldp.org/HOWTO/Framebuffer-HOWTO.html. - - To test that the Linux framebuffer is set up correctly, and that - the device permissions are correct, use the program provided by - the \l {Testing the Linux Framebuffer} document. -*/ diff --git a/doc/src/emb-differences.qdoc b/doc/src/emb-differences.qdoc deleted file mode 100644 index cf3ab75..0000000 --- a/doc/src/emb-differences.qdoc +++ /dev/null @@ -1,72 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-differences.html - - \title Porting Qt Applications to Qt for Embedded Linux - \ingroup porting - \ingroup qt-embedded-linux - - Existing Qt applications should require no porting provided there is no - platform dependent code. - - \table 100% - \header \o Platform Dependent Code - - \row - \o - Platform dependent code includes system calls, calls to the - underlying window system (Windows or X11), and Qt platform - specific methods such as QApplication::x11EventFilter(). - - For cases where it is necessary to use platform dependent code - there are macros defined that can be used to enable and disable - code for each platform using \c #ifdef directives: - - \list - \o Qt for Embedded Linux: Q_WS_QWS - \o Qt for Mac OS X: Q_WS_MAC - \o Qt for Windows: Q_WS_WIN - \o Qt for X11: Q_WS_X11 - \endlist - \endtable -*/ diff --git a/doc/src/emb-envvars.qdoc b/doc/src/emb-envvars.qdoc deleted file mode 100644 index c423fef..0000000 --- a/doc/src/emb-envvars.qdoc +++ /dev/null @@ -1,168 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-envvars.html - - \title Qt for Embedded Linux Environment Variables - \ingroup qt-embedded-linux - - These environment variables are relevant to \l{Qt for Embedded Linux} - users. - - \table - \header \o Variable \o Description - - \row - \o \bold POINTERCAL_FILE \target POINTERCAL_FILE - - \o Specifies the file containing the data used to calibrate the - pointer device. - - See also QWSCalibratedMouseHandler and \l{Qt for Embedded Linux Pointer - Handling}. - - \row - \o \bold QT_ONSCREEN_PAINT \target QT_ONSCREEN_PAINT - - \o If defined, the application will render its widgets directly on - screen. The affected regions of the screen will not be modified by - the screen driver unless another window with a higher focus - requests (parts of) the same region. - - Setting this environment variable is equivalent to setting the - Qt::WA_PaintOnScreen attribute for all the widgets in the - application. - - See also the Qt for Embedded Linux \l{Qt for Embedded Linux Architecture#Graphics - Rendering}{graphics rendering} documentation. - - \row - \o \bold QWS_SW_CURSOR \target QWS_SW_CURSOR - \o If defined, the software mouse cursor is always used (even when using an - accelerated driver that supports a hardware cursor). - - \row - \o \bold QWS_DISPLAY \target QWS_DISPLAY - \o - - Specifies the display type and framebuffer. For example, if the - current shell is bash, ksh, zsh or sh: - - \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 0 - - The valid values for the \c <driver> argument are \c LinuxFb, \c - QVFb, \c VNC, \c Transformed, \c Multi and \l - {QScreenDriverPlugin::keys()}{keys} identifying custom drivers, - and the \c {<display num>} argument is used to separate screens - that are using the same screen driver and to enable multiple - displays (see the \l {Running Qt for Embedded Linux Applications} - documentation for more details). - - The driver specific options are described in the \l{Qt for Embedded Linux - Display Management}{display management} documentation. - - \row - \o \bold QWS_SIZE \target QWS_SIZE - \o - - Specifies the size of the \l{Qt for Embedded Linux} window which is centered - within the screen. For example, if the current shell is bash, ksh, - zsh or sh: - - \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 1 - - \row - \o \bold QWS_MOUSE_PROTO \target QWS_MOUSE_PROTO - \o - - Specifies the driver for pointer handling. For example, if the - current shell is bash, ksh, zsh or sh: - - \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 2 - - The valid values for the \c <driver> argument are \c MouseMan, \c - IntelliMouse, \c Microsoft, \c VR41xx, \c LinuxTP, \c Yopy. \c - Tslib and \l {QMouseDriverPlugin::keys()}{keys} identifying - custom drivers, and the driver specific options are typically a - device, e.g., \c /dev/mouse for mouse devices and \c /dev/ts for - touch panels. - - Multiple keyboard drivers can be specified in one go: - - \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 3 - - Input will be read from all specified drivers. - Note that the \c Vr41xx driver also accepts two optional - arguments: \c press=<value> defining a mouseclick (the default - value is 750) and \c filter=<value> specifying the length of the - filter used to eliminate noise (the default length is 3). For - example: - - \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 4 - - See also \l {Qt for Embedded Linux Pointer Handling}. - - \row - \o \bold QWS_KEYBOARD \target QWS_KEYBOARD - \o - - Specifies the driver and device for character input. For example, if the - current shell is bash, ksh, zsh or sh: - - \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 5 - - The valid values for the \c <driver> argument are \c SL5000, \c - Yopy, \c VR41xx, \c TTY, \c USB and \l - {QKbdDriverPlugin::keys()}{keys} identifying custom drivers, - and the driver specific options are typically a device, e.g., \c - /dev/tty0. - - Multiple keyboard drivers can be specified in one go: - - \snippet doc/src/snippets/code/doc_src_emb-envvars.qdoc 6 - - Input will be read from all specified drivers. - - See also \l {Qt for Embedded Linux Character Input}. - - \endtable -*/ diff --git a/doc/src/emb-features.qdoc b/doc/src/emb-features.qdoc deleted file mode 100644 index fdd2e46..0000000 --- a/doc/src/emb-features.qdoc +++ /dev/null @@ -1,147 +0,0 @@ -/**************************************************************************** -** -** 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 fine-tuning-features.html - \title Fine-Tuning Features in Qt - \ingroup qtce - \ingroup qt-embedded-linux - \brief Describes how to reduce the size of Qt libraries by selecting only - the features that are needed. - - In many cases, only a fixed set of applications are deployed on an - embedded device, making it possible to save resources by minimizing - the size of the associated libraries. The Qt installation can easily - be optimized by avoiding to compile in the features that are not - required. - - \tableofcontents - - A wide range of features are defined, covering classes and technologies - provided by several of Qt's modules. - You can look up the different feature definitions in the - \c{src/corelib/global/qfeatures.txt} file within the Qt source - distribution. - - \section1 Simple Customization - - \section2 Embedded Linux - - To disable a particular feature, just run the \c configure script - for Qt for Embedded Linux with the \c -no-feature-<feature> option. - For example: - - \snippet doc/src/snippets/code/doc_src_emb-features.qdoc 1 - - The feature can easily be enabled again by running \c configure - with the \c -feature-<feature> option. - - See also \l{Qt Performance Tuning}. - - \section2 Windows CE - - To disable a particular feature, just run the \c configure script - with the set of required \c -D<feature> options. For example, - you can use the \c -D option to define \c{QT_NO_THREAD}: - - \snippet doc/src/snippets/code/doc_src_emb-features.qdoc 0 - - The \c -D option only creates a Qt internal define. If you get linker - errors you have to define \c QT_NO_THREAD also for your project. - You can do this by adding \c DEFINES += \c QT_NO_THREAD to your - \c .pro file. - - See also \l{Qt Performance Tuning}. - - \section1 Managing Large Numbers of Features - - If you want to disable a lot of features, it is more comfortable - to use the \c qconfig tool. - You can disable a \e set of features by creating a custom - configuration file that defines the preferred subset of Qt's - functionality. Such a file uses macros to disable the unwanted - features, and can be created manually or by using the \c qconfig - tool located in the \c{tools/qconfig} directory of the Qt source - distribution. - - \note The \c qconfig tool is intended to be built against Qt on - desktop platforms. - - \bold{Windows CE:} The Qt for Windows CE package contains a \c qconfig - executable that you can run on a Windows desktop to configure the build. - - \image qt-embedded-qconfigtool.png - - The \c qconfig tool's interface displays all of Qt's - functionality, and allows the user to both disable and enable - features. The user can open and edit any custom configuration file - located in the \c{src/corelib/global} directory. When creating a - custom configuration file manually, a description of the currently - available Qt features can be found in the - \c{src/corelib/global/qfeatures.txt} file. - - Note that some features depend on others; disabling any feature - will automatically disable all features depending on it. The - feature dependencies can be explored using the \c qconfig tool, - but they are also described in the \c{src/corelib/global/qfeatures.h} - file. - - To be able to apply the custom configuration, it must be saved in - a file called \c qconfig-myfile.h in the \c{src/corelib/global} - directory. Then use the \c configure tool's \c -qconfig option - and pass the configuration's file name without the \c qconfig- - prefix and \c .h extension, as argument. - The following examples show how this is invoked on each of the - embedded platforms for a file called \c{qconfig-myfile.h}: - - \bold{Embedded Linux:} - - \snippet doc/src/snippets/code/doc_src_emb-features.qdoc 3 - - \bold{Windows CE:} - - \snippet doc/src/snippets/code/doc_src_emb-features.qdoc 2 - - Qt provides several ready-made custom configuration files, - defining minimal, small, medium and large installations, - respectively. These files are located in the - \c{/src/corelib/global} directory in the Qt source distribution. -*/ diff --git a/doc/src/emb-fonts.qdoc b/doc/src/emb-fonts.qdoc deleted file mode 100644 index 70fddbf..0000000 --- a/doc/src/emb-fonts.qdoc +++ /dev/null @@ -1,201 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-fonts.html - - \title Qt for Embedded Linux Fonts - \ingroup qt-embedded-linux - - \l {Qt for Embedded Linux} uses the - \l{http://freetype.sourceforge.net/freetype2/index.html}{FreeType 2} - font engine to produce font output. The formats supported depends on - the locally installed version of the FreeType library. In addition, - \l{Qt for Embedded Linux} supports the Qt Prerendered Font formats (\l QPF and \l QPF2): - light-weight non-scalable font formats specific to \l {Qt for Embedded Linux}. - QPF2 is the native format of \l{Qt for Embedded Linux}. QPF is the legacy - format used by Qt/Embedded 2.x and 3.x. Several of the formats may be rendered - using anti-aliasing for improved readability. - - When \l{Qt for Embedded Linux} applications run, they look for fonts in - Qt's \c lib/fonts/ directory. \l {Qt for Embedded Linux} will automatically detect - prerendered fonts and TrueType fonts. For compatibility, it will also read the - legacy \c lib/fonts/fontdir file. - - Support for other font formats can be added, contact - \l{mailto:qt-info@nokia.com}{qt-info@nokia.com} for more - information. - - \tableofcontents - - \table 100% - \row - \o - \bold {Optimization} - - The \l FreeType, \l QPF2 and \l QPF formats are features that can be - disabled using the - \l{Fine-Tuning Features in Qt}{feature definition system}, - reducing the size of Qt and saving resources. - - Note that at least one font format must be defined. - - See the \l {Fine-Tuning Features in Qt} documentation for - details. - - \o - \inlineimage qt-embedded-fontfeatures.png - \endtable - - All supported fonts use the Unicode character encoding. Most fonts - available today do, but they usually don't contain \e all the - Unicode characters. A complete 16-point Unicode font uses over 1 - MB of memory. - - \target FreeType - \section1 FreeType Formats - - The \l {http://freetype.sourceforge.net/freetype2/index.html}{FreeType 2} - library (and therefore \l{Qt for Embedded Linux}) can support the following font formats: - - \list - \o TrueType (TTF) - \o PostScript Type1 (PFA/PFB) - \o Bitmap Distribution Format (BDF) - \o CID-keyed Type1 - \o Compact Font Format (CFF) - \o OpenType fonts - \o SFNT-based bitmap fonts - \o Portable Compiled Format (PCF) - \o Microsoft Windows Font File Format (Windows FNT) - \o Portable Font Resource (PFR) - \o Type 42 (limited support) - \endlist - - It is possible to add modules to the \l - {http://freetype.sourceforge.net/freetype2/index.html}{FreeType 2} - font engine to support other types of font files. For more - information, see the font engine's own website: \l - http://freetype.sourceforge.net/freetype2/index.html. - - Glyphs rendered using FreeType are shared efficiently between applications, - reducing memory requirements and speeding up text rendering. - - \omit - \l {Qt for Embedded Linux} will by default use the system FreeType library if it exists. - Otherwise it will use a copy of the FreeType library in Qt, which by default only - supports TrueType fonts to reduce footprint. - \endomit - - \target QPF2 - \section1 Qt Prerendered Font (QPF2) - - The Qt Prerendered Font (QPF2) is an architecture-independent, - light-weight and non-scalable font format specific to \l{Qt for Embedded Linux}. - - Nokia provides the cross-platform \l makeqpf tool, included in the - \c tools directory of both \l {Qt} and \l{Qt for Embedded Linux}, which allows - generation of QPF2 files from system fonts. - - QPF2 supports anti-aliasing and complex writing systems, using information - from the corresponding TrueType font, if present on the system. The format - is designed to be mapped directly to memory. The same format is used to - share glyphs from non-prerendered fonts between applications. - - \target QPF - \section1 Legacy Qt Prerendered Font (QPF) - - Nokia provides support for the legacy QPF format for compatibility - reasons. QPF is based on the internal font engine data structure of Qt/Embedded - versions 2 and 3. - - Note that the file name describes the font, for example \c helvetica_120_50.qpf - is 12 point Helvetica while \c helvetica_120_50i.qpf is 12 point Helvetica \e italic. - - \omit - \section1 Memory Requirements - - Taking advantage of the way the QPF format is structured, Qt for - Embedded Linux memory-maps the data rather than reading and parsing it. - This reduces RAM consumption even further. - - Scalable fonts use a larger amount of memory per font, but - these fonts provide a memory saving if many different sizes of each - font are needed. - \endomit - - \section1 The Legacy \c fontdir File - - For compatibility reasons \l{Qt for Embedded Linux} supports the \c fontdir - file, if present. The file defines additional fonts available to the - application, and has the following format: - - \snippet doc/src/snippets/code/doc_src_emb-fonts.qdoc 0 - - \table 100% - \header \o Field \o Description - \row \o \bold name - \o The name of the font format, e.g.,\c Helvetica, \c Times, etc. - \row \o \bold file - \o The name of the file containing the font, e.g., \c - helvR0810.bdf, \c verdana.ttf, etc. - \row \o \bold renderer - \o Specifies the font engine that should be used to render the - font, currently only the FreeType font engine (\c FT) is - supported. - \row \o \bold italic - \o Specifies whether the font is italic or not; the accepted - values are \c y or \c n. - \row \o \bold weight - \o Specifies the font's weight: \c 50 is normal, \c 75 is bold, - etc. - \row \o \bold size - \o Specifies the font size, i.e., point size * 10. For example, a - value of 120 means 12pt. A value of 0 means that the font is - scalable. - \row \o \bold flags - \o The following flag is supported: - \list - \o \c s: smooth (anti-aliased) - \endlist - All other flags are ignored. - \endtable -*/ diff --git a/doc/src/emb-framebuffer-howto.qdoc b/doc/src/emb-framebuffer-howto.qdoc deleted file mode 100644 index 14400c2..0000000 --- a/doc/src/emb-framebuffer-howto.qdoc +++ /dev/null @@ -1,53 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-testingframebuffer.html - - \title Testing the Linux Framebuffer - \subtitle for Qt for Embedded Linux - \ingroup qt-embedded-linux - - To test that the Linux framebuffer is set up correctly, and that - the device permissions are correct, use the program found in - \c examples/qws/framebuffer which opens the frame buffer and draws - three squares of different colors. -*/ diff --git a/doc/src/emb-install.qdoc b/doc/src/emb-install.qdoc deleted file mode 100644 index e23cc1b..0000000 --- a/doc/src/emb-install.qdoc +++ /dev/null @@ -1,197 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-install.html - - \title Installing Qt for Embedded Linux - \ingroup qt-embedded-linux - \ingroup installation - \brief How to install Qt for Embedded Linux. - - This document describes how to install \l{Qt for Embedded Linux} in your - development environment: - - \tableofcontents - - Please see the \l{Cross-Compiling Qt for Embedded Linux Applications}{cross - compiling} and \l{Deploying Qt for Embedded Linux Applications}{deployment} - documentation for details on how to install \l{Qt for Embedded Linux} on - your target device. - - Note also that this installation procedure is written for Linux, - and that it may need to be modified for other platforms. - - \section1 Step 1: Installing the License File (commercial editions only) - - If you have the commercial edition of \l{Qt for Embedded Linux}, the first step - is to install your license file as \c $HOME/.qt-license. - - For the open source version you do not need a license file. - - \section1 Step 2: Unpacking the Archive - - First uncompress the archive in the preferred location, then - unpack it: - - \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 0 - - This document assumes that the archive is unpacked in the - following directory: - - \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 1 - - \section1 Step 3: Building the Library - - Before building the \l{Qt for Embedded Linux} library, run the \c - ./configure script to configure the library for your development - architecture. You can list all of the configuration system's - options by typing \c {./configure -help}. - - Note that by default, \l{Qt for Embedded Linux} is configured for - installation in the \c{/usr/local/Trolltech/QtEmbedded-%VERSION%} - directory, but this can be changed by using the \c{-prefix} - option. Alternatively, the \c{-prefix-install} option can be used - to specify a "local" installation within the source directory. - - The configuration system is also designed to allow you to specify - your platform architecture: - - \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 2 - - In general, all Linux systems which have framebuffer support can - use the \c generic architecture. Other typical architectures are - \c x86, \c arm and \c mips. - - \note If you want to build Qt for Embedded Linux for use with a virtual - framebuffer, pass the \c{-qvfb} option to the \c configure - script. - - To create the library and compile all the demos, examples, tools, - and tutorials, type: - - \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 3 - - On some systems the \c make utility is named differently, e.g. \c - gmake. The \c configure script tells you which \c make utility to - use. - - If you did not configure \l{Qt for Embedded Linux} using the \c{-prefix-install} - option, you need to install the library, demos, examples, tools, - and tutorials in the appropriate place. To do this, type: - - \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 4 - - and enter the root password. - - \note You can use the \c INSTALL_ROOT environment variable to specify - the location of the installed files when invoking \c{make install}. - - \section1 Step 4: Adjusting the Environment Variables - - In order to use \l{Qt for Embedded Linux}, the \c PATH variable must be extended - to locate \c qmake, \c moc and other \l{Qt for Embedded Linux} tools, and the \c - LD_LIBRARY_PATH must be extended for compilers that do not support - \c rpath. - - To set the \c PATH variable, add the following lines to your \c - .profile file if your shell is bash, ksh, zsh or sh: - - \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 5 - - In case your shell is csh or tcsh, add the following line to the - \c .login file instead: - - \snippet doc/src/snippets/code/doc_src_emb-install.qdoc 6 - - If you use a different shell, please modify your environment - variables accordingly. - - For compilers that do not support \c rpath you must also extend - the \c LD_LIBRARY_PATH environment variable to include - \c /usr/local/Trolltech/QtEmbedded-%VERSION%/lib. Note that on Linux - with GCC, this step is not needed. - - \section1 Step 5: Building the Virtual Framebuffer - - For development and debugging, \l{Qt for Embedded Linux} provides a virtual - framebuffer as well as the option of running \l{Qt for Embedded Linux} as a VNC - server. For a description of how to install the virtual - framebuffer and how to use the VNC protocol, please consult the - documentation at: - - \list - \o \l {The Virtual Framebuffer} - \o \l {The VNC Protocol and Qt for Embedded Linux} - \endlist - - Note that the virtual framebuffer requires a Qt for X11 - installation. See \l {Installing Qt on X11 Platforms} for details. - - The Linux framebuffer, on the other hand, is enabled by default on - all modern Linux distributions. For information on older versions, - see \l http://en.tldp.org/HOWTO/Framebuffer-HOWTO.html. To test - that the Linux framebuffer is set up correctly, use the program - provided by the \l {Testing the Linux Framebuffer} document. - - That's all. \l{Qt for Embedded Linux} is now installed. - - \table 100% - \row - \o - \bold {Customizing the Qt for Embedded Linux Library} - - When building embedded applications on low-powered devices, - reducing the memory and CPU requirements is important. - - A number of options tuning the library's performance are - available. But the most direct way of saving resources is to - fine-tune the set of Qt features that is compiled. It is also - possible to make use of accelerated graphics hardware. - - \list - \o \l {Fine-Tuning Features in Qt} - \o \l {Qt Performance Tuning} - \o \l {Adding an Accelerated Graphics Driver to Qt for Embedded Linux} - \endlist - - \endtable -*/ diff --git a/doc/src/emb-kmap2qmap.qdoc b/doc/src/emb-kmap2qmap.qdoc deleted file mode 100644 index 291a553..0000000 --- a/doc/src/emb-kmap2qmap.qdoc +++ /dev/null @@ -1,84 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-kmap2qmap.html - \title kmap2qmap - \ingroup qt-embedded-linux - - \c kmap2qmap is a tool to generate keymaps for use on Embedded Linux. - The source files have to be in standard Linux \c kmap format that is - e.g. understood by the kernel's \c loadkeys command. This means you - can use the following sources to generate \c qmap files: - - \list - \o The \l {http://lct.sourceforge.net/}{Linux Console Tools (LCT)} project. - \o \l {http://www.x.org/}{Xorg} X11 keymaps can be converted to the \c - kmap format with the \c ckbcomp utility. - \o Since \c kmap files are plain text files, they can also be hand crafted. - \endlist - - The generated \c qmap files are size optimized binary files. - - \c kmap2qmap is a command line program, that needs at least 2 files as - parameters. The last one will be the generated \c .qmap file, while all - the others will be parsed as input \c .kmap files. For example: - - \code - kmap2qmap i386/qwertz/de-latin1-nodeadkeys.kmap include/compose.latin1.inc de-latin1-nodeadkeys.qmap - \endcode - - \c kmap2qmap does not support all the (pseudo) symbols that the Linux - kernel supports. If you are converting a standard keymap you will get a - lot of warnings for things like \c Show_Registers, \c Hex_A, etc.: you - can safely ignore those. - - It also doesn't support numeric symbols (e.g. \c{keycode 1 = 4242}, - instead of \c{keycode 1 = colon}), since these are deprecated and can - change from one kernel version to the other. - - On the other hand, \c kmap2qmap supports one additional, Qt specific, - symbol: \c QtZap. The built-in US keymap has that symbol mapped tp - \c{Ctrl+Alt+Backspace} and it serves as a shortcut to kill your QWS - server (similiar to the X11 server). - - See also \l {Qt for Embedded Linux Character Input} -*/ diff --git a/doc/src/emb-makeqpf.qdoc b/doc/src/emb-makeqpf.qdoc deleted file mode 100644 index dc1196a..0000000 --- a/doc/src/emb-makeqpf.qdoc +++ /dev/null @@ -1,53 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-makeqpf.html - \title makeqpf - \ingroup qt-embedded-linux - - \c makeqpf is a tool to generate pre-rendered fonts in QPF2 format for use on Embedded Linux. - - Qt 4 can read files in QPF2 format in addition to QPF files generated by older versions of - \c makeqpf from Qt 2 or 3. - - \sa {Qt for Embedded Linux Fonts} -*/ diff --git a/doc/src/emb-performance.qdoc b/doc/src/emb-performance.qdoc deleted file mode 100644 index 9bc373b..0000000 --- a/doc/src/emb-performance.qdoc +++ /dev/null @@ -1,152 +0,0 @@ -/**************************************************************************** -** -** 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 qt-performance.html - \title Qt Performance Tuning - \ingroup qtce - \ingroup qt-embedded-linux - \brief Ways to improve performance on embedded platforms. - - When building embedded applications on low-powered devices, - \l{Qt for Windows CE} and \l{Qt for Embedded Linux} provide - a number of options that reduce the memory and/or CPU requirements - by making various trade-offs. These options range from variations - in programming style, to linking and memory allocation. - - Note that the most direct way of saving resources, is to avoid compiling - in features that are not required. See the \l{Fine-Tuning Features in Qt} - {fine tuning features} documentation for details. - - \tableofcontents - - \section1 Programming Style - - Rather than creating dialogs and widgets every time they are - needed, and delete them when they are no longer required, create - them once and use the QWidget::hide() and QWidget::show() - functions whenever appropriate. To avoid a slow startup of the - application, delay the creation of dialogs and widgets until they - are requested. All this will improve the CPU performance, it - requires a little more memory, but will be much faster. - - \section1 Static vs. Dynamic Linking - - A lot of CPU and memory is used by the ELF (Executable and Linking - Format) linking process. Significant savings can be achieved by - using a static build of the application suite; rather than having - a collection of executables which link dynamically to Qt's - libraries, all the applications is built into into a single - executable which is statically linked to Qt's libraries. - - This improves the start-up time and reduces memory usage at the - expense of flexibility (to add a new application, you must - recompile the single executable) and robustness (if one - application has a bug, it might harm other applications). - - \table 100% - \row - \o \bold {Creating a Static Build} - - To compile Qt as a static library, use the \c -static option when - running configure: - - \snippet doc/src/snippets/code/doc_src_emb-performance.qdoc 0 - - To build the application suite as an all-in-one application, - design each application as a stand-alone widget (or set of - widgets) with only minimal code in the \c main() function. Then, - write an application that provides a means of switching between - the applications. The \l Qt Extended platform is an example using this - approach: It can be built either as a set of dynamically linked - executables, or as a single static application. - - Note that the application still should link dynamically against - the standard C library and any other libraries which might be used - by other applications on the target device. - - \endtable - - When installing end-user applications, this approach may not be an - option, but when building a single application suite for a device - with limited CPU power and memory, this option could be very - beneficial. - - \section1 Alternative Memory Allocation - - The libraries shipped with some C++ compilers on some platforms - have poor performance in the built-in "new" and "delete" - operators. Improved memory allocation and performance may be - gained by re-implementing these functions: - - \snippet doc/src/snippets/code/doc_src_emb-performance.qdoc 1 - - The example above shows the necessary code to switch to the plain - C memory allocators. - - \section1 Bypassing the Backing Store - - When rendering, Qt uses the concept of a backing store; i.e., a - paint buffer, to reduce flicker and to support graphics operations - such as blending. - - The default behavior is for each client to render - its widgets into memory while the server is responsible for - putting the contents of the memory onto the screen. But when the - hardware is known and well defined, as is often the case with - software for embedded devices, it might be useful to bypass the - backing store, allowing the clients to manipulate the underlying - hardware directly. - \if defined(qtce) - This is achieved by setting the Qt::WA_PaintOnScreen window attribute - for each widget. - \else - - There are two approaches to direct painting: The first approach is - to set the Qt::WA_PaintOnScreen window attribute for each widget, - the other is to use the QDirectPainter class to reserve a region - of the framebuffer. - For more information, see the - \l{Qt for Embedded Linux Architecture#Direct Painting}{direct painting} - section of the \l{Qt for Embedded Linux Architecture}{architecture} - documentation. - \endif -*/ diff --git a/doc/src/emb-pointer.qdoc b/doc/src/emb-pointer.qdoc deleted file mode 100644 index 39a8482..0000000 --- a/doc/src/emb-pointer.qdoc +++ /dev/null @@ -1,209 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-pointer.html - - \title Qt for Embedded Linux Pointer Handling - \ingroup qt-embedded-linux - - When running a \l{Qt for Embedded Linux} application, it either runs as a - server or connects to an existing server. The mouse driver is - loaded by the server application when it starts running, using - Qt's \l {How to Create Qt Plugins}{plugin system}. - - Internally in the client/server protocol, all system generated - events, including pointer events, are passed to the server - application which then propagates the event to the appropriate - client. Note that pointer handling in \l{Qt for Embedded Linux} works for - both mouse and mouse-like devices such as touch panels and - trackballs. - - Contents: - - \tableofcontents - - \section1 Available Drivers - - \l{Qt for Embedded Linux} provides ready-made drivers for the MouseMan, - IntelliMouse, Microsoft and Linux Touch Panel protocols, for the - standard Linux Input Subsystem as well as the universal touch screen - library, tslib. Run the \c configure script to list the available - drivers: - - \if defined(QTOPIA_PHONE) - - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 0 - - \bold{Note:} By default only the PC mouse driver is enabled. - - The various drivers can be enabled and disabled using the \c - configure script. For example: - - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 1 - - \else - - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 2 - - In the default Qt configuration, only the "pc" mouse driver is - enabled. The various drivers can be enabled and disabled using - the \c configure script. For example: - - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 3 - \endif - - Custom mouse drivers can be implemented by subclassing the - QWSMouseHandler class and creating a mouse driver plugin (derived - from the QMouseDriverPlugin class). The default implementation of the - QMouseDriverFactory class will automatically detect the plugin, - loading the driver into the server application at run-time. - - If you are creating a driver for a device that needs calibration - or noise reduction, such as a touchscreen, derive from the - QWSCalibratedMouseHandler subclass instead to take advantage of - its calibration functionality. - - \if defined(QTOPIA_PHONE) - For a tutorial on how to add a new keyboard driver plug-in - see: \l {Tutorial: Implementing a Device Plug-in}. - \endif - - \section1 Specifying a Driver - - Provided that the "pc" mouse driver is enabled, \l{Qt for Embedded Linux} will - try to auto-detect the mouse device if it is one of the supported - types on \c /dev/psaux or one of the \c /dev/ttyS? serial - lines. If multiple mice are detected, all may be used - simultaneously. - - Note that \l{Qt for Embedded Linux} does not support auto-detection of \e - {touch panels} in which case the driver must be specified - explicitly to determine which device to use. - - To manually specify which driver to use, set the QWS_MOUSE_PROTO - environment variable. For example (if the current shell is bash, - ksh, zsh or sh): - - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 4 - - The valid values for the \c <driver> argument are \c MouseMan, \c - IntelliMouse, \c Microsoft, \c LinuxTP, \c LinuxInput, \c - Tslib and \l {QMouseDriverPlugin::keys()}{keys} identifying custom - drivers, and the driver specific options are typically a device, - e.g., \c /dev/mouse for mouse devices and \c /dev/ts for touch - panels. - - Multiple mouse drivers can be specified in one go: - - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 5 - - Input will be read from all specified drivers. - - \table - \header \o The Tslib Mouse Driver - \row - \o - - The tslib mouse driver inherits the QWSCalibratedMouseHandler - class, providing calibration and noise reduction functionality in - addition to generating mouse events for devices using the - Universal Touch Screen Library. - - To be able to compile this mouse handler, \l{Qt for Embedded Linux} must be - configured with the \c -qt-mouse-tslib option as described - above. In addition, the tslib headers and library must be present - in the build environment. - - The tslib sources can be downloaded from \l - http://tslib.berlios.de. Use the \c configure script's -L and - -I options to explicitly specify the location of the library and - its headers: - - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 7 - - In order to use this mouse driver, tslib must also be correctly - installed on the target machine. This includes providing a \c - ts.conf configuration file and setting the neccessary environment - variables (see the README file provided with tslib for details). - - The \c ts.conf file will usually contain the following two lines: - - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 8 - - To make \l{Qt for Embedded Linux} explicitly choose the tslib mouse - handler, set the QWS_MOUSE_PROTO environment variable as explained - above. - - \endtable - - \section1 Troubleshooting - - \section2 Device Files - - Make sure you are using the correct device file. - - As a first step, you can test whether the device file actually gives any - output. For instance, if you have specified the mouse driver with - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 9 - then try examining - the output from the device by entering the following command in a console: - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 10 - - If you see output from the device printed on the console when you move - the mouse, you are probably using the correct device file; otherwise, you - will need to experiment to find the correct device file. - - \section2 File Permissions - - Make sure you have sufficient permissions to access the device file. - - The Qt for Embedded Linux server process needs at least read permission for the - device file. Some drivers also require write access to the device file. - For instance, if you have specified the mouse driver with - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 11 - then examine the permissions of the device file by entering the following - command in a console: - \snippet doc/src/snippets/code/doc_src_emb-pointer.qdoc 12 - - If the device file is actually a symbolic link to another file, you must - change the permissions of the actual file instead. -*/ diff --git a/doc/src/emb-porting.qdoc b/doc/src/emb-porting.qdoc deleted file mode 100644 index 1afd1be..0000000 --- a/doc/src/emb-porting.qdoc +++ /dev/null @@ -1,193 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-porting-operatingsystem.html - - \title Porting Qt for Embedded Linux to Another Operating System - \ingroup qt-embedded-linux - - \l{Qt for Embedded Linux} is reasonably platform-independent, making use of - the standard C library and some POSIX functions, but only a Linux - implementation is publically available. If you are looking for a - non-Linux commercial implementation, it is worth contacting \l - {mailto:qt-info@nokia.com}{qt-info@nokia.com} to see if we can - help. - - There are several issues to be aware of if you plan to do your own - port to another operating system. In particular you must resolve - \l{Qt for Embedded Linux}'s shared memory and semaphores (used to share - window regions), and you must provide something similar to - Unix-domain sockets for inter-application communication. You must - also provide a screen driver, and if you want to implement sound - you must provide your own sound server. Finally you must modify - the event dispatcher used by \l{Qt for Embedded Linux}. - - Contents: - - \tableofcontents - - \section1 Shared Memory and Semaphores - - \l{Qt for Embedded Linux} uses System V IPC (shared memory and semaphores) - to share window regions between client and server. When porting, - something similar must be provided; otherwise it will not be - possible to run multiple applications. - - System V semaphores are also used for synchronizing access to the - framebuffer. - - \list - \o Modify \c qsharedmemory_p.cpp - \o Modify \c qlock_qws.cpp - \o Modify \c qwslock.cpp - \endlist - - \section1 Inter-Application Communication - - To communicate between applications, \l{Qt for Embedded Linux} uses the - Unix-domain sockets. When porting, something similar must be - provided; otherwise it will not be possible to run multiple - applications. - - It should be possible to use message queues or similar mechanisms - to achieve this. With the exception of QCOP messages, individual - messages should be no more than a few bytes in length (QCOP - messages are generated by the client applications and not Qt for - Embedded Linux). - - \list - \o Modify \c qwssocket_qws.cpp - \endlist - - \section1 Screen Management - - When rendering, the default behavior in \l{Qt for Embedded Linux} is - for each client to render its widgets into memory while the server is - responsible for putting the contents of the memory onto the screen - using the screen driver. - - When porting, a new screen driver must be implemented, providing a - byte pointer to a memory-mapped framebuffer and information about - width, height and bit depth (the latter information can most - likely be hard-coded). - - \list - \o Reimplement \c qscreen_qws.cpp - \endlist - - \section1 Sound Management - - To implement sound, \l{Qt for Embedded Linux} uses a Linux style device (\c - /dev/dsp). If you want to use the \l{Qt for Embedded Linux} sound server on - another platform you must reimplement it. - - \list - \o Reimplement \c qsoundqss_qws.cpp - \endlist - - \section1 Event Dispatching - - \l{Qt for Embedded Linux} uses an event dispatcher to pass events to and - from the \l{Qt for Embedded Linux} server application. Reimplement the \c - select() function to enable \l{Qt for Embedded Linux} to dispatch events on - your platform. - - \list - \o Modify \c qeventdispatcher_qws.cpp - \endlist -*/ - -/*! - \page qt-embedded-porting-device.html - - \title Porting Qt for Embedded Linux to a New Architecture - \ingroup qt-embedded-linux - - When porting \l{Qt for Embedded Linux} to a new architecture there are - several issues to be aware of: You must provide suitable hardware - drivers, and you must ensure to implement platform dependent - atomic operations to enable multithreading on the new - architecture. - - \section1 Hardware Drivers - - When running a \l{Qt for Embedded Linux} application, it either runs as a - server or connects to an existing server. All system generated - events, including keyboard and mouse events, are passed to the - server application which then propagates the event to the - appropriate client. When rendering, the default behavior is for - each client to render its widgets into memory while the server is - responsible for putting the contents of the memory onto the - screen. - - The various hardware drivers are loaded by the server - application when it starts running, using Qt's \l {How to Create - Qt Plugins}{plugin system}. - - Derive from the QWSMouseHandler, QWSKeyboardHandler and QScreen - classes to create a custom mouse, keyboard and screen driver - respectively. To load the drivers into the server application at - runtime, you must also create corresponding plugins. See the - following documentation for more details: - - \list - \o \l{Qt for Embedded Linux Pointer Handling}{Pointer Handling} - \o \l{Qt for Embedded Linux Character Input}{Character Input} - \o \l{Qt for Embedded Linux Display Management}{Display Management} - \endlist - - \section1 Atomic Operations - - Qt uses an optimization called \l {Implicitly Shared Classes}{implicit sharing} - for many of its value classes; implicitly shared classes can safely be - copied across threads. This technology is implemented using atomic - operations; i.e., \l{Qt for Embedded Linux} requires that platform-specific - atomic operations are implemented to support Linux. - - When porting \l{Qt for Embedded Linux} to a new architecture, it is - important to ensure that the platform-specific atomic operations - are implemented in a corresponding header file, and that this file - is located in Qt's \c src/corelib/arch directory. - - See the \l {Implementing Atomic Operations}{atomic operations} - documentation for more details. -*/ diff --git a/doc/src/emb-qvfb.qdoc b/doc/src/emb-qvfb.qdoc deleted file mode 100644 index 48e0d35..0000000 --- a/doc/src/emb-qvfb.qdoc +++ /dev/null @@ -1,296 +0,0 @@ -/**************************************************************************** -** -** 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 qvfb.html - - \title The Virtual Framebuffer - \ingroup qt-embedded-linux - - \l{Qt for Embedded Linux} applications write directly to the - framebuffer, eliminating the need for the X Window System and - saving memory. For development and debugging purposes, a virtual - framebuffer can be used, allowing \l{Qt for Embedded Linux} - programs to be developed on a desktop machine, without switching - between consoles and X11. - - QVFb is an X11 application supplied with Qt for X11 that provides - a virtual framebuffer for Qt for Embedded Linux to use. To use it, - you need to \l{Installing Qt on X11 Platforms}{configure and - install Qt on X11 platforms} appropriately. Further requirements - can be found in the \l{Qt for Embedded Linux Requirements} - document. - - \image qt-embedded-virtualframebuffer.png - - The virtual framebuffer emulates a framebuffer using a shared - memory region and the \c qvfb tool to display the framebuffer in a - window. The \c qvfb tool also supports a feature known as a skin - which can be used to change the look and feel of the display. The - tool is located in Qt's \c tools/qvfb directory, and provides - several additional features accessible through its \gui File and - \gui View menus. - - Please note that the virtual framebuffer is a development tool - only. No security issues have been considered in the virtual - framebuffer design. It should be avoided in a production - environment; i.e. do not configure production libraries with the - \c -qvfb option. - - \tableofcontents - - \section1 Displaying the Virtual Framebuffer - - To run the \c qvfb tool displaying the virtual framebuffer, the - \l{Qt for Embedded Linux} library must be configured and compiled - with the \c -qvfb option: - - \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 0 - - Ensure that you have all the - \l{Qt for Embedded Linux Requirements#Additional X11 Libraries for QVFb} - {necessary libraries} needed to build the tool, then compile and run the - \c qvfb tool as a normal Qt for X11 application (i.e., do \e not compile - it as a \l{Qt for Embedded Linux} application): - - \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 1 - - The \c qvfb application supports the following command line - options: - - \table - \header \o Option \o Description - \row - \o \c {-width <value>} - \o The width of the virtual framebuffer (default: 240). - \row - \o \c {-height <value>} - \o The height of the virtual framebuffer (default: 320). - \row - \o \c {-depth <value>} - \o The depth of the virtual framebuffer (1, 8 or 32; default: 8). - \row - \o \c -nocursor - \o Do not display the X11 cursor in the framebuffer window. - \row - \o \c {-qwsdisplay <:id>} - \o The \l{Qt for Embedded Linux} display ID (default: 0). - \row - \o \c {-skin <name>.skin} - \o The preferred skin. Note that the skin must be located in Qt's - \c /tools/qvfb/ directory. - \row - \o \c {-zoom <factor>} - \o Scales the application view with the given factor. - - \endtable - - \section2 Skins - - A skin is a set of XML and pixmap files that tells the vitual - framebuffer what it should look like and how it should behave; a - skin can change the unrealistic default display into a display - that is similar to the target device. To access the \c qvfb tool's - menus when a skin is activated, right-click over the display. - - Note that a skin can have buttons which (when clicked) send - signals to the Qt Extended application running inside the virtual - framebuffer, just as would happen on a real device. - - \table 100% - \row - \o - \bold {Target Device Environment} - - The \c qvfb tool provides various skins by default, allowing - the user to view their application in an environment similar - to their target device. The provided skins are: - - \list - \o ClamshellPhone - \o pda - \o PDAPhone - \o Qt ExtendedPDA - \o Qt ExtendedPhone-Advanced - \o Qt ExtendedPhone-Simple - \o SmartPhone - \o SmartPhone2 - \o SmartPhoneWithButtons - \o TouchscreenPhone - \o Trolltech-Keypad - \o Trolltech-Touchscreen - \endlist - - In addition, it is possible to create custom skins. - - \o \image qt-embedded-phone.png - \o \image qt-embedded-pda.png - \endtable - - \bold {Creating Custom Skins} - - The XML and pixmap files specifying a custom skin must be located - in subdirectory of the Qt's \c /tools/qvfb directory, called \c - /customskin.skin. See the ClamshellPhone skin for an example of the - file structure: - - \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 2 - - The \c /ClamshellPhone.skin directory contains the following files: - - \list - \o \c ClamshellPhone.skin - \o \c ClamshellPhone1-5.png - \o \c ClamshellPhone1-5-pressed.png - \o \c ClamshellPhone1-5-closed.png - \o \c defaultbuttons.conf (only necessary for \l Qt Extended) - \endlist - - Note that the \c defaultbuttons.conf file is only necessary if the - skin is supposed to be used with \l Qt Extended (The file customizes - the launch screen applications, orders the soft keys and provides - input method hints). See the \l Qt Extended documentation for more - information. - - \table 100% - \header - \o {3,1} The ClamshellPhone Skin - \row - \o {3,1} - - \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 3 - - The \c ClamShellPhone.skin file quoted above, specifies three - pixmaps: One for the normal skin (\c Up), one for the activated - skin (\c Down) and one for the closed skin (\c Closed). In - addition, it is possible to specify a pixmap for the cursor (using - a \c Cursor variable). - - The file also specifies the screen size (\c Screen) and the number - of available buttons (\c Areas). Then it describes the buttons - themselves; each button is specified by its name, keycode and - coordinates. - - The coordinates are a list of at least 2 points in clockwise order - that define a shape for the button; a click inside this shape will - be treated as a click on that button. While pressed, the pixels - for the button are redrawn from the activated skin. - - \row - \row - \o - \image qt-embedded-clamshellphone-closed.png The ClamshellPhone Skin (closed) - \o - \image qt-embedded-clamshellphone.png The ClamshellPhone Skin - \o - \image qt-embedded-clamshellphone-pressed.png The ClamshellPhone Skin (pressed) - \row - \o \c ClamshellPhone1-5-closed.png - \o \c ClamshellPhone1-5.png - \o \c ClamshellPhone1-5-pressed.png - \endtable - - \section2 The File Menu - - \image qt-embedded-qvfbfilemenu.png - - The \gui File menu allows the user to configure the virtual - framebuffer display (\gui File|Configure...), save a snapshot of - the framebuffer contents (\gui {File|Save Image...}) and record - the movements in the framebuffer (\gui File|Animation...). - - When choosing the \gui File|Configure menu item, the \c qvfb tool - provides a configuration dialog allowing the user to customize the - display of the virtual framebuffer. The user can modify the size - and depth as well as the Gamma values, and also select the - preferred skin (i.e. making the virtual framebuffer simulate the - target device environment). In addition, it is possible to emulate - a touch screen and a LCD screen. - - Note that when configuring (except when changing the Gamma values - only), any applications using the virtual framebuffer will be - terminated. - - \section2 The View Menu - - \image qt-embedded-qvfbviewmenu.png - - The \gui View menu allows the user to modify the target's refresh - rate (\gui {View|Refresh Rate...}), making \c qvfb check for - updated regions more or less frequently. - - The regions of the display that have changed are updated - periodically, i.e. the virtual framebuffer is displaying discrete - snapshots of the framebuffer rather than each individual drawing - operation. For this reason drawing problems such as flickering may - not be apparent until the program is run using a real framebuffer. - If little drawing is being done, the framebuffer will not show any - updates between drawing events. If an application is displaying an - animation, the updates will be frequent, and the application and - \c qvfb will compete for processor time. - - The \gui View menu also allows the user to zoom the view of the - application (\gui {View|Zoom *}). - - \section1 Running Applications Using the Virtual Framebuffer - - Once the virtual framebuffer (the \c qvfb application) is running, - it is ready for use: Start a server application (i.e. construct a - QApplication object with the QApplication::GuiServer flag or use - the \c -qws command line parameter. See the - \l {Running Qt for Embedded Linux Applications}{running applications} - documentation for details). For example: - - \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 4 - - Note that as long as the virtual framebuffer is running and the - current \l{Qt for Embedded Linux} configuration supports \c qvfb, - \l{Qt for Embedded Linux} will automatically detect it and use it by - default. Alternatively, the \c -display option can be used to - specify the virtual framebuffer driver. For example: - - \snippet doc/src/snippets/code/doc_src_emb-qvfb.qdoc 5 - - \warning If \c qvfb is not running (or the current - \l{Qt for Embedded Linux} configuration doesn't support it) and the - driver is not explicitly specified, \l{Qt for Embedded Linux} will - write to the real framebuffer and the X11 display will be corrupted. -*/ diff --git a/doc/src/emb-running.qdoc b/doc/src/emb-running.qdoc deleted file mode 100644 index cb7a7ae..0000000 --- a/doc/src/emb-running.qdoc +++ /dev/null @@ -1,210 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-running.html - - \title Running Qt for Embedded Linux Applications - \ingroup qt-embedded-linux - - A \l{Qt for Embedded Linux} application requires a server application to be - running, or to be the server application itself. Any \l{Qt for Embedded Linux} - application can be the server application by constructing the QApplication - object with the QApplication::GuiServer type, or by running the application - with the \c -qws command line option. - - Applications can run using both single and multiple displays, and - various command line options are available. - - Note that this document assumes that you either are using the - \l{The Virtual Framebuffer} or that you are running \l{Qt for Embedded Linux} - using the \l {The VNC Protocol and Qt for Embedded Linux}{VNC} protocol, - \e or that you have the Linux framebuffer configured - correctly and that no server process is running. (To test that the - Linux framebuffer is set up correctly, use the program provided by - the \l {Testing the Linux Framebuffer} document.) - - \tableofcontents - - \section1 Using a Single Display - - To run the application using a single display, change to a Linux - console and select an application to run, e.g. \l {Text - Edit}{demos/textedit}. Run the application with the \c -qws - option: - - \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 0 - - \table 100% - \row - \o - Provided that the environment variables are adjusted properly - during the \l {Installing Qt for Embedded Linux}{installation process}, you - should see the \l {Text Edit} demo appear. - - It might be that the hardware drivers must be specified explicitly - to make everything work properly. For more information, please - consult the following documentation: - - \list - \o \l{Qt for Embedded Linux Pointer Handling}{Pointer Handling} - \o \l{Qt for Embedded Linux Character Input}{Character Input} - \o \l{Qt for Embedded Linux Display Management}{Display Management} - \endlist - - \o - \inlineimage qt-embedded-runningapplication.png - \endtable - - Additional applications can be run as clients, i.e., by running - these applications \e without the \c -qws option they will connect - to the existing server as clients. You can exit the server - application at any time using \gui{Ctrl+Alt+Backspace}. - - \section1 Using Multiple Displays - - Qt for Embedded Linux also allows multiple displays to be used - simultaneously. There are two ways of achieving this: Either run - multiple Qt for Embedded Linux server processes, or use the - ready-made \c Multi screen driver. - - When running multiple server processes, the screen driver (and - display number) must be specified for each process using the \c - -display command line option or by setting the QWS_DISPLAY - environment variable. For example: - - \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 1 - - See the \l {Qt for Embedded Linux Display Management}{display management} - documentation for more details on how to specify a screen - driver. Note that you must also specify the display (i.e., server - process) when starting client applications: - - \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 2 - - There is no way of moving a client from one display to another - when running multiple server processes. Using the \c Multi screen - driver, on the other hand, applications can easiliy be moved - between the various screens. - - The \c Multi screen driver can be specified just like any other - screen driver by using the \c -display command line option or by - setting the QWS_DISPLAY environment variable. For example: - - \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 3 - - See the \l {Qt for Embedded Linux Display Management}{display management} - documentation for details regarding arguments. - - \section1 Command Line Options - - \table 100% - \header - \o Option \o Description - \row - \o \bold -fn <font> - \o - Defines the application font. For example: - \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 4 - The font should be specified using an X logical font description. - \row - \o \bold -bg <color> - \o - Sets the default application background color. For example: - \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 5 - The color-name must be one of the names recognized by the QColor constructor. - \row - \o \bold -btn <color> \o - Sets the default button color. For example: - \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 6 - The color-name must be one of the names recognized by the QColor constructor. - \row - \o \bold -fg <color> \o - Sets the default application foreground color. For example: - \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 7 - The color-name must be one of the names recognized by the QColor constructor. - \row - \o \bold -name <objectname> \o - Sets the application name, i.e. the application object's object name. For example: - \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 8 - \row - \o \bold -title <title> \o - Sets the application's title. For example: - \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 9 - \row - \o \bold -geometry <width>x<height>+<Xoffset>+<Yoffset> \o - Sets the client geometry of the first window that is shown. For example: - \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 10 - \row - \o \bold -keyboard \o - Enables the keyboard. - - See also: \l {Qt for Embedded Linux Character Input}. - \row - \o \bold -nokeyboard \o - Disables the keyboard. - \row - \o \bold -mouse \o - Enables the mouse cursor. - - See also: \l {Qt for Embedded Linux Pointer Handling}. - \row - \o \bold -nomouse \o - Disables the mouse cursor. - \row - \o \bold -qws \o - Runs the application as a server application, i.e. constructs a - QApplication object of the QApplication::GuiServer type. - \row - \o \bold -display \o - Specifies the screen driver. - - See also: \l {Qt for Embedded Linux Display Management}. - \row - \o \bold -decoration <style>\o - Sets the application decoration. For example: - \snippet doc/src/snippets/code/doc_src_emb-running.qdoc 11 - The supported styles are \c windows, \c default and \c styled. - - See also QDecoration. - - \endtable -*/ diff --git a/doc/src/emb-vnc.qdoc b/doc/src/emb-vnc.qdoc deleted file mode 100644 index c8289f8..0000000 --- a/doc/src/emb-vnc.qdoc +++ /dev/null @@ -1,141 +0,0 @@ -/**************************************************************************** -** -** 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 qt-embedded-vnc.html - \brief A guide to using Qt for Embedded Linux applications as VNC servers - and clients. - - \title The VNC Protocol and Qt for Embedded Linux - \ingroup qt-embedded-linux - - VNC (Virtual Network Computing) software makes it possible to view - and interact with one computer (the "server") from any other - computer or mobile device (the "viewer") anywhere on a network. - - \image qt-embedded-vnc-screen.png - - VNC clients are available for a vast array of display systems, including - X11, Mac OS X and Windows. - - \section1 Configuring Qt with VNC Capabilities - - To run a \l{Qt for Embedded Linux} application using the VNC protocol, the - \l{Qt for Embedded Linux} library must be configured and compiled with the - \c -qt-gfx-vnc option: - - \snippet doc/src/snippets/code/doc_src_emb-vnc.qdoc 0 - - \section1 Running a Server Application - - Start a server application by specifying the \c -qws command - line option when running the application. (This can also be - specified in the application's source code.) - Use the \c -display command line option to specify the VNC server's - driver and the virtual screen to use. For example: - - \snippet doc/src/snippets/code/doc_src_emb-vnc.qdoc 1 - - The application will act as a VNC server which can be accessed using - an ordinary VNC client, either on the development machine or from a - different machine on a network. - - For example, using the X11 VNC client to view the application from the - same machine: - - \snippet doc/src/snippets/code/doc_src_emb-vnc.qdoc 2 - - To interact with the application from another machine on the network, - run a VNC client pointing to the machine that is running the server - application. - - \l{Qt for Embedded Linux} will create a 640 by 480 pixel display by - default. Alternatively, the \c QWS_SIZE environment variable can be - used to set another size; e.g., \c{QWS_SIZE=240x320}. - - \section1 Running Client Applications - - If you want to run more than one application on the same display, you - only need to start the first one as a server application, using the - \c -qws command line option to indicate that it will manage other - windows. - - \snippet doc/src/snippets/code/doc_src_emb-vnc.qdoc Starting server - - Subsequent client applications can be started \e without the \c -qws - option, but will each require the same \c -display option and argument - as those used for the server. - - \snippet doc/src/snippets/code/doc_src_emb-vnc.qdoc Starting clients - - However, for the clients, this option will not cause a new VNC server - to be started, but only indicates that their windows will appear on the - virtual screen managed by the server application. - - \section1 Related Resources - - It is not always necessary to specify the \c -qws command line option - when running a server application as long as the QApplication object - used by the application has been constructed with the - QApplication::GuiServer flag. - - See the \l{Running Qt for Embedded Linux Applications}{running applications} - documentation for more details about server and client applications. - - \table - \row - \o \bold {The Virtual Framebuffer} - - The \l{The Virtual Framebuffer}{virtual framebuffer} is - an alternative technique recommended for development and debugging - purposes. - - The virtual framebuffer emulates a framebuffer using a shared - memory region and the \c qvfb tool to display the framebuffer in a - window. - - Its use of shared memory makes the virtual framebuffer much faster - and smoother than using the VNC protocol, but it does not operate - over a network. - - \o \inlineimage qt-embedded-virtualframebuffer.png - \endtable -*/ diff --git a/doc/src/eventsandfilters.qdoc b/doc/src/eventsandfilters.qdoc deleted file mode 100644 index a67e523..0000000 --- a/doc/src/eventsandfilters.qdoc +++ /dev/null @@ -1,221 +0,0 @@ -/**************************************************************************** -** -** 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 eventsandfilters.html - \title Events and Event Filters - \ingroup architecture - \brief A guide to event handling in Qt. - - In Qt, events are objects, derived from the abstract QEvent class, - that represent things that have happened either within an application - or as a result of outside activity that the application needs to know - about. Events can be received and handled by any instance of a - QObject subclass, but they are especially relevant to widgets. This - document describes how events are delivered and handled in a typical - application. - - \tableofcontents - - \section1 How Events are Delivered - - When an event occurs, Qt creates an event object to represent it by - constructing an instance of the appropriate QEvent subclass, and - delivers it to a particular instance of QObject (or one of its - subclasses) by calling its \l{QObject::}{event()} function. - - This function does not handle the event itself; based on the type - of event delivered, it calls an event handler for that specific - type of event, and sends a response based on whether the event - was accepted or ignored. - - \omit - Event delivery means that an - event has occurred, the QEvent indicates precisely what, and the - QObject needs to respond. Most events are specific to QWidget and its - subclasses, but there are important events that aren't related to - graphics (e.g., \l{QTimer}{timer events}). - \endomit - - Some events, such as QMouseEvent and QKeyEvent, come from the - window system; some, such as QTimerEvent, come from other sources; - some come from the application itself. - - \section1 Event Types - - Most events types have special classes, notably QResizeEvent, - QPaintEvent, QMouseEvent, QKeyEvent, and QCloseEvent. Each class - subclasses QEvent and adds event-specific functions. For example, - QResizeEvent adds \l{QResizeEvent::}{size()} and - \l{QResizeEvent::}{oldSize()} to enable widgets to discover how - their dimensions have been changed. - - Some classes support more than one actual event type. QMouseEvent - supports mouse button presses, double-clicks, moves, and other - related operations. - - Each event has an associated type, defined in QEvent::Type, and this - can be used as a convenient source of run-time type information to - quickly determine which subclass a given event object was constructed - from. - - Since programs need to react in varied and complex ways, Qt's - event delivery mechanisms are flexible. The documentation for - QCoreApplication::notify() concisely tells the whole story; the - \e{Qt Quarterly} article - \l{http://qt.nokia.com/doc/qq/qq11-events.html}{Another Look at Events} - rehashes it less concisely. Here we will explain enough for 95% - of applications. - - \section1 Event Handlers - - The normal way for an event to be delivered is by calling a virtual - function. For example, QPaintEvent is delivered by calling - QWidget::paintEvent(). This virtual function is responsible for - reacting appropriately, normally by repainting the widget. If you - do not perform all the necessary work in your implementation of the - virtual function, you may need to call the base class's implementation. - - For example, the following code handles left mouse button clicks on - a custom checkbox widget while passing all other button clicks to the - base QCheckBox class: - - \snippet doc/src/snippets/events/events.cpp 0 - - If you want to replace the base class's function, you must - implement everything yourself. However, if you only want to extend - the base class's functionality, then you implement what you want and - call the base class to obtain the default behavior for any cases you - do not want to handle. - - Occasionally, there isn't such an event-specific function, or the - event-specific function isn't sufficient. The most common example - involves \key Tab key presses. Normally, QWidget intercepts these to - move the keyboard focus, but a few widgets need the \key{Tab} key for - themselves. - - These objects can reimplement QObject::event(), the general event - handler, and either do their event handling before or after the usual - handling, or they can replace the function completely. A very unusual - widget that both interprets \key Tab and has an application-specific - custom event might contain the following \l{QObject::event()}{event()} - function: - - \snippet doc/src/snippets/events/events.cpp 1 - - Note that QWidget::event() is still called for all of the cases not - handled, and that the return value indicates whether an event was - dealt with; a \c true value prevents the event from being sent on - to other objects. - - \section1 Event Filters - - Sometimes an object needs to look at, and possibly intercept, the - events that are delivered to another object. For example, dialogs - commonly want to filter key presses for some widgets; for example, - to modify \key{Return}-key handling. - - The QObject::installEventFilter() function enables this by setting - up an \e{event filter}, causing a nominated filter object to receive - the events for a target object in its QObject::eventFilter() - function. An event filter gets to process events before the target - object does, allowing it to inspect and discard the events as - required. An existing event filter can be removed using the - QObject::removeEventFilter() function. - - When the filter object's \l{QObject::}{eventFilter()} implementation - is called, it can accept or reject the event, and allow or deny - further processing of the event. If all the event filters allow - further processing of an event (by each returning \c false), the event - is sent to the target object itself. If one of them stops processing - (by returning \c true), the target and any later event filters do not - get to see the event at all. - - \snippet doc/src/snippets/eventfilters/filterobject.cpp 0 - - The above code shows another way to intercept \key{Tab} key press - events sent to a particular target widget. In this case, the filter - handles the relevant events and returns \c true to stop them from - being processed any further. All other events are ignored, and the - filter returns \c false to allow them to be sent on to the target - widget, via any other event filters that are installed on it. - - It is also possible to filter \e all events for the entire application, - by installing an event filter on the QApplication or QCoreApplication - object. Such global event filters are called before the object-specific - filters. This is very powerful, but it also slows down event delivery - of every single event in the entire application; the other techniques - discussed should generally be used instead. - - \section1 Sending Events - - Many applications want to create and send their own events. You can - send events in exactly the same ways as Qt's own event loop by - constructing suitable event objects and sending them with - QCoreApplication::sendEvent() and QCoreApplication::postEvent(). - - \l{QCoreApplication::}{sendEvent()} processes the event immediately. - When it returns, the event filters and/or the object itself have - already processed the event. For many event classes there is a function - called isAccepted() that tells you whether the event was accepted - or rejected by the last handler that was called. - - \l{QCoreApplication::}{postEvent()} posts the event on a queue for - later dispatch. The next time Qt's main event loop runs, it dispatches - all posted events, with some optimization. For example, if there are - several resize events, they are are compressed into one. The same - applies to paint events: QWidget::update() calls - \l{QCoreApplication::}{postEvent()}, which eliminates flickering and - increases speed by avoiding multiple repaints. - - \l{QCoreApplication::}{postEvent()} is also used during object - initialization, since the posted event will typically be dispatched - very soon after the initialization of the object is complete. - When implementing a widget, it is important to realise that events - can be delivered very early in its lifetime so, in its constructor, - be sure to initialize member variables early on, before there's any - chance that it might receive an event. - - To create events of a custom type, you need to define an event - number, which must be greater than QEvent::User, and you may need to - subclass QEvent in order to pass specific information about your - custom event. See the QEvent documentation for further details. -*/ diff --git a/doc/src/examples-overview.qdoc b/doc/src/examples-overview.qdoc deleted file mode 100644 index 50c19fa..0000000 --- a/doc/src/examples-overview.qdoc +++ /dev/null @@ -1,367 +0,0 @@ -/**************************************************************************** -** -** 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 examples-overview.html - \title An Overview of Qt's Examples - \brief A short guide to the different categories of examples included with Qt. - \ingroup howto - - Qt is supplied with a variety of examples that cover almost every aspect - of development. These examples are ordered by functional area, but many - examples often use features from many parts of Qt to highlight one area - in particular. - - This document provides a brief overview of each example category and - provides links to the more formal \l{Qt Examples}{list of examples}. - - \section1 \l{Qt Examples#Widgets}{Widgets} - - \l{Qt Examples#Widgets}{\inlineimage widget-examples.png - } - - Qt comes with a large range of standard widgets that users of modern - applications have come to expect. - - You can also develop your own custom widgets and controls, and use them - alongside standard widgets. - - It is even possible to provide custom styles and themes for widgets that can - be used to change the appearance of standard widgets and appropriately - written custom widgets. - - \section1 \l{Qt Examples#Dialogs}{Dialogs} - - \l{Qt Examples#Dialogs}{\inlineimage dialog-examples.png - } - - Qt includes standard dialogs for many common operations, such as file - selection, printing, and color selection. - - Custom dialogs can also be created for specialized modal or modeless - interactions with users. - - \section1 \l{Qt Examples#Main Windows}{Main Windows} - - \l{Qt Examples#Main Windows}{\inlineimage mainwindow-examples.png - } - - All the standard features of application main windows are provided by Qt. - - Main windows can have pull down menus, tool bars, and dock windows. These - separate forms of user input are unified in an integrated action system that - also supports keyboard shortcuts and accelerator keys in menu items. - - \section1 \l{Qt Examples#Layouts}{Layouts} - - \l{Qt Examples#Layouts}{\inlineimage layout-examples.png - } - - Qt uses a layout-based approach to widget management. Widgets are arranged in - the optimal positions in windows based on simple layout rules, leading to a - consistent look and feel. - - Custom layouts can be used to provide more control over the positions and - sizes of child widgets. - - \section1 \l{Qt Examples#Painting}{Painting} - - \l{Qt Examples#Painting}{\inlineimage painting-examples.png - } - - Qt's painting system is able to render vector graphics, images, and outline - font-based text with sub-pixel accuracy accuracy using anti-aliasing to - improve rendering quality. - - These examples show the most common techniques that are used when painting - with Qt, from basic concepts such as drawing simple primitives to the use of - transformations. - - \section1 \l{Qt Examples#Item Views}{Item Views} - - \l{Qt Examples#Item Views}{\inlineimage itemview-examples.png - } - - Item views are widgets that typically display data sets. Qt 4's model/view - framework lets you handle large data sets by separating the underlying data - from the way it is represented to the user, and provides support for - customized rendering through the use of delegates. - - \section1 \l{Qt Examples#Graphics View}{Graphics View} - - \l{Qt Examples#Graphics View}{\inlineimage graphicsview-examples.png - } - - Qt is provided with a comprehensive canvas through the GraphicsView - classes. - - These examples demonstrate the fundamental aspects of canvas programming - with Qt. - - \section1 \l{Qt Examples#Rich Text}{Rich Text} - - \l{Qt Examples#Rich Text}{\inlineimage richtext-examples.png - } - - Qt provides powerful document-oriented rich text engine that supports Unicode - and right-to-left scripts. Documents can be manipulated using a cursor-based - API, and their contents can be imported and exported as both HTML and in a - custom XML format. - - \section1 \l{Qt Examples#Tools}{Tools} - - \l{Qt Examples#Tools}{\inlineimage tool-examples.png - } - - Qt is equipped with a range of capable tool classes, from containers and - iterators to classes for string handling and manipulation. - - Other classes provide application infrastructure support, handling plugin - loading and managing configuration files. - - \section1 \l{Qt Examples#Desktop}{Desktop} - - \l{Qt Examples#Desktop}{\inlineimage desktop-examples.png - } - - Qt provides features to enable applications to integrate with the user's - preferred desktop environment. - - Features such as system tray icons, access to the desktop widget, and - support for desktop services can be used to improve the appearance of - applications and take advantage of underlying desktop facilities. - - \section1 \l{Qt Examples#Drag and Drop}{Drag and Drop} - - \l{Qt Examples#Drag and Drop}{\inlineimage draganddrop-examples.png - } - - Qt supports native drag and drop on all platforms via an extensible - MIME-based system that enables applications to send data to each other in the - most appropriate formats. - - Drag and drop can also be implemented for internal use by applications. - - \section1 \l{Qt Examples#Threads}{Threads} - - \l{Qt Examples#Threads}{\inlineimage thread-examples.png - } - - Qt 4 makes it easier than ever to write multithreaded applications. More - classes have been made usable from non-GUI threads, and the signals and slots - mechanism can now be used to communicate between threads. - - Additionally, it is now possible to move objects between threads. - - \section1 \l{Qt Examples#Concurrent Programming}{Concurrent Programming} - - The QtConcurrent namespace includes a collection of classes and functions - for straightforward concurrent programming. - - These examples show how to apply the basic techniques of concurrent - programming to simple problems. - - \section1 \l{Qt Examples#Network}{Network} - - \l{Qt Examples#Network}{\inlineimage network-examples.png - } - - Qt is provided with an extensive set of network classes to support both - client-based and server side network programming. - - These examples demonstrate the fundamental aspects of network programming - with Qt. - - \section1 \l{Qt Examples#XML}{XML} - - \l{Qt Examples#XML}{\inlineimage xml-examples.png - } - - XML parsing and handling is supported through SAX and DOM compliant APIs. - - Qt's SAX compliant classes allow you to parse XML incrementally; the DOM - classes enable more complex document-level operations to be performed on - XML files. - - \section1 \l{Qt Examples#XQuery, XPath}{XQuery, XPath} - - Qt provides an XQuery/XPath engine, QtXmlPatterns, for querying XML - files and custom data models, similar to the model/view framework. - - \section1 \l{Qt Examples#OpenGL}{OpenGL} - - \l{Qt Examples#OpenGL}{\inlineimage opengl-examples.png - } - - Qt provides support for integration with OpenGL implementations on all - platforms, giving developers the opportunity to display hardware accelerated - 3D graphics alongside a more conventional user interface. - - These examples demonstrate the basic techniques used to take advantage of - OpenGL in Qt applications. - - \section1 \l{Qt Examples#Multimedia}{Multimedia} - - \l{Qt Examples#Multimedia} - - Qt provides low-level audio support on linux,windows and mac platforms by default and - an audio plugin API to allow developers to implement there own audio support for - custom devices and platforms. - - These examples demonstrate the basic techniques used to take advantage of - Audio API in Qt applications. - - \section1 \l{Qt Examples#SQL}{SQL} - - \l{Qt Examples#SQL}{\inlineimage sql-examples.png - } - - Qt provides extensive database interoperability, with support for products - from both open source and proprietary vendors. - - SQL support is integrated with Qt's model/view architecture, making it easier - to provide GUI integration for your database applications. - - \section1 \l{Qt Examples#Help System}{Help System} - - \l{Qt Examples#Help System}{\inlineimage assistant-examples.png - } - - Support for interactive help is provided by the Qt Assistant application. - Developers can take advantages of the facilities it offers to display - specially-prepared documentation to users of their applications. - - \section1 \l{Qt Examples#Qt Designer}{Qt Designer} - - \l{Qt Examples#Qt Designer}{\inlineimage designer-examples.png - } - - Qt Designer is a capable graphical user interface designer that lets you - create and configure forms without writing code. GUIs created with - Qt Designer can be compiled into an application or created at run-time. - - \section1 \l{Qt Examples#UiTools}{UiTools} - - \l{Qt Examples#UiTools}{\inlineimage uitools-examples.png - } - - Qt is equipped with a range of capable tool classes, from containers and - iterators to classes for string handling and manipulation. - - Other classes provide application infrastructure support, handling plugin - loading and managing configuration files. - - \section1 \l{Qt Examples#Qt Linguist}{Qt Linguist} - - \l{Qt Examples#Qt Linguist}{\inlineimage linguist-examples.png - } - - Internationalization is a core feature of Qt. These examples show how to - access translation and localization facilities at run-time. - - \section1 \l{Qt Examples#Qt Script}{Qt Script} - - \l{Qt Examples#Qt Script}{\inlineimage qtscript-examples.png - } - - Qt is provided with a powerful embedded scripting environment through the QtScript - classes. - - These examples demonstrate the fundamental aspects of scripting applications - with Qt. - - \section1 \l{Qt Examples#Phonon Multimedia Framework}{Phonon Multimedia Framework} - - \l{Qt Examples#Phonon Multimedia Framework}{\inlineimage phonon-examples.png - } - - The Phonon Multimedia Framework brings multimedia support to Qt applications. - - The examples and demonstrations provided show how to play music and movies - using the Phonon API. - - \section1 \l{Qt Examples#WebKit}{WebKit} - - \l{Qt Examples#WebKit}{\inlineimage webkit-examples.png - } - - Qt provides an integrated Web browser component based on WebKit, the popular - open source browser engine. - - These examples and demonstrations show a range of different uses for WebKit, - from displaying Web pages within a Qt user interface to an implementation of - a basic function Web browser. - - \section1 \l{Qt Examples#State Machine}{State Machine} - - Qt provides a powerful hierchical finite state machine through the Qt State - Machine classes. - - These examples demonstrate the fundamental aspects of implementing - Statecharts with Qt. - - \section1 \l{Qt Examples#Qt for Embedded Linux}{Qt for Embedded Linux} - - \l{Qt Examples#Qt for Embedded Linux}{\inlineimage qt-embedded-examples.png - } - - These examples show how to take advantage of features specifically designed - for use on systems with limited resources, specialized hardware, and small - screens. - - \section1 \l{Qt Examples#ActiveQt}{ActiveQt} - - Qt is supplied with a number of example applications and demonstrations that - have been written to provide developers with examples of the Qt API in use, - highlight good programming practice, and showcase features found in each of - Qt's core technologies. - - The example and demo launcher can be used to explore the different categories - available. It provides an overview of each example, lets you view the - documentation in Qt Assistant, and is able to launch examples and demos. - - \section1 \l{http://qt.nokia.com/doc/qq}{Another Source of Examples} - - One more valuable source for examples and explanations of Qt - features is the archive of the \l {http://qt.nokia.com/doc/qq} - {Qt Quarterly}. - -*/ diff --git a/doc/src/examples.qdoc b/doc/src/examples.qdoc deleted file mode 100644 index 0181e09..0000000 --- a/doc/src/examples.qdoc +++ /dev/null @@ -1,437 +0,0 @@ -/**************************************************************************** -** -** 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 examples.html - \title Qt Examples - \brief Information about the example programs provided with Qt. - \ingroup howto - - This is the list of examples in Qt's \c examples directory. The - examples demonstrate Qt features in small, self-contained - programs. They are not all designed to be impressive when you run - them, but their source code is carefully written to show good Qt - programming practices. You can launch any of these programs from the - \l{Examples and Demos Launcher} application. - - If you are new to Qt, you should probably start by going through - the \l{Tutorials} before you have a look at the - \l{mainwindows/application}{Application} example. - - In addition to the examples and the tutorial, Qt includes a - \l{Qt Demonstrations}{selection of demos} that deliberately show off - Qt's features. You might want to look at these as well. - - One more valuable source for examples and explanations of Qt - features is the archive of the \l {Qt Quarterly}. - - In the list below, examples marked with an asterisk (*) are fully - documented. Eventually, all the examples will be fully documented, - but sometimes we include an example before we have time to write - about it, because someone might need it right now. - - Categories: - - \tableofcontents - - \section1 ActiveQt - - \list - \o \l{activeqt/comapp}{COM App}\raisedaster - \o \l{Dot Net Example (ActiveQt)}{Dot Net}\raisedaster - \o \l{activeqt/hierarchy}{Hierarchy}\raisedaster - \o \l{activeqt/menus}{Menus}\raisedaster - \o \l{activeqt/multiple}{Multiple}\raisedaster - \o \l{activeqt/opengl}{OpenGL}\raisedaster - \o \l{activeqt/qutlook}{Qutlook}\raisedaster - \o \l{activeqt/simple}{Simple}\raisedaster - \o \l{activeqt/webbrowser}{Web Browser}\raisedaster - \o \l{activeqt/wrapper}{Wrapper}\raisedaster - \endlist - - \section1 Animation - - \list - \o \l{animation/moveblocks}{Move Blocks}\raisedaster - \o \l{animation/stickman}{Stick man}\raisedaster - \endlist - - \section1 Concurrent Programming - - \list - \o \l{qtconcurrent/imagescaling}{QtConcurrent Asynchronous Image Scaling} - \o \l{qtconcurrent/map}{QtConcurrent Map} - \o \l{qtconcurrent/progressdialog}{QtConcurrent Progress Dialog} - \o \l{qtconcurrent/runfunction}{QtConcurrent Run Function} - \o \l{qtconcurrent/wordcount}{QtConcurrent Word Count} - \endlist - - \section1 D-Bus - \list - \o \l{dbus/dbus-chat}{Chat} - \o \l{dbus/complexpingpong}{Complex Ping Pong} - \o \l{dbus/listnames}{List Names} - \o \l{dbus/pingpong}{Ping Pong} - \o \l{dbus/remotecontrolledcar}{Remote Controlled Car} - \endlist - - \section1 Desktop - - \list - \o \l{desktop/screenshot}{Screenshot}\raisedaster - \o \l{desktop/systray}{System Tray}\raisedaster - \endlist - - \section1 Dialogs - - \list - \o \l{dialogs/classwizard}{Class Wizard}\raisedaster - \o \l{dialogs/configdialog}{Config Dialog} - \o \l{dialogs/extension}{Extension}\raisedaster - \o \l{dialogs/findfiles}{Find Files}\raisedaster - \o \l{dialogs/licensewizard}{License Wizard}\raisedaster - \o \l{dialogs/standarddialogs}{Standard Dialogs} - \o \l{dialogs/tabdialog}{Tab Dialog}\raisedaster - \o \l{dialogs/trivialwizard}{Trivial Wizard} - \endlist - - \section1 Drag and Drop - - \list - \o \l{draganddrop/delayedencoding}{Delayed Encoding}\raisedaster - \o \l{draganddrop/draggableicons}{Draggable Icons} - \o \l{draganddrop/draggabletext}{Draggable Text} - \o \l{draganddrop/dropsite}{Drop Site} - \o \l{draganddrop/fridgemagnets}{Fridge Magnets}\raisedaster - \o \l{draganddrop/puzzle}{Drag and Drop Puzzle} - \endlist - - \section1 Graphics View - - \list - \o \l{graphicsview/collidingmice}{Colliding Mice}\raisedaster - \o \l{graphicsview/diagramscene}{Diagram Scene}\raisedaster - \o \l{graphicsview/dragdroprobot}{Drag and Drop Robot} - \o \l{graphicsview/elasticnodes}{Elastic Nodes} - \o \l{graphicsview/portedasteroids}{Ported Asteroids} - \o \l{graphicsview/portedcanvas}{Ported Canvas} - \endlist - - \section1 Help System - - \list - \o \l{help/simpletextviewer}{Simple Text Viewer}\raisedaster - \endlist - - \section1 Item Views - - \list - \o \l{itemviews/addressbook}{Address Book}\raisedaster - \o \l{itemviews/basicsortfiltermodel}{Basic Sort/Filter Model} - \o \l{itemviews/chart}{Chart} - \o \l{itemviews/coloreditorfactory}{Color Editor Factory}\raisedaster - \o \l{itemviews/combowidgetmapper}{Combo Widget Mapper}\raisedaster - \o \l{itemviews/customsortfiltermodel}{Custom Sort/Filter Model}\raisedaster - \o \l{itemviews/dirview}{Dir View} - \o \l{itemviews/editabletreemodel}{Editable Tree Model}\raisedaster - \o \l{itemviews/fetchmore}{Fetch More}\raisedaster - \o \l{itemviews/frozencolumn}{Frozen Column}\raisedaster - \o \l{itemviews/pixelator}{Pixelator}\raisedaster - \o \l{itemviews/puzzle}{Puzzle} - \o \l{itemviews/simpledommodel}{Simple DOM Model}\raisedaster - \o \l{itemviews/simpletreemodel}{Simple Tree Model}\raisedaster - \o \l{itemviews/simplewidgetmapper}{Simple Widget Mapper}\raisedaster - \o \l{itemviews/spinboxdelegate}{Spin Box Delegate}\raisedaster - \o \l{itemviews/stardelegate}{Star Delegate}\raisedaster - \endlist - - \section1 Layouts - - \list - \o \l{layouts/basiclayouts}{Basic Layouts}\raisedaster - \o \l{layouts/borderlayout}{Border Layout} - \o \l{layouts/dynamiclayouts}{Dynamic Layouts} - \o \l{layouts/flowlayout}{Flow Layout} - \endlist - - \section1 Main Windows - - \list - \o \l{mainwindows/application}{Application}\raisedaster - \o \l{mainwindows/dockwidgets}{Dock Widgets}\raisedaster - \o \l{mainwindows/mdi}{MDI} - \o \l{mainwindows/menus}{Menus}\raisedaster - \o \l{mainwindows/recentfiles}{Recent Files} - \o \l{mainwindows/sdi}{SDI} - \endlist - - \section1 Network - - \list - \o \l{network/blockingfortuneclient}{Blocking Fortune Client}\raisedaster - \o \l{network/broadcastreceiver}{Broadcast Receiver} - \o \l{network/broadcastsender}{Broadcast Sender} - \o \l{network/network-chat}{Network Chat} - \o \l{network/fortuneclient}{Fortune Client}\raisedaster - \o \l{network/fortuneserver}{Fortune Server}\raisedaster - \o \l{network/ftp}{FTP}\raisedaster - \o \l{network/http}{HTTP} - \o \l{network/loopback}{Loopback} - \o \l{network/threadedfortuneserver}{Threaded Fortune Server}\raisedaster - \o \l{network/torrent}{Torrent} - \o \l{network/googlesuggest}{Google Suggest} - \endlist - - \section1 OpenGL - - \list - \o \l{opengl/2dpainting}{2D Painting}\raisedaster - \o \l{opengl/framebufferobject}{Framebuffer Object} - \o \l{opengl/framebufferobject2}{Framebuffer Object 2} - \o \l{opengl/grabber}{Grabber} - \o \l{opengl/hellogl}{Hello GL}\raisedaster - \o \l{opengl/overpainting}{Overpainting}\raisedaster - \o \l{opengl/pbuffers}{Pixel Buffers} - \o \l{opengl/pbuffers2}{Pixel Buffers 2} - \o \l{opengl/samplebuffers}{Sample Buffers} - \o \l{opengl/textures}{Textures} - \endlist - - \section1 Painting - - \list - \o \l{painting/basicdrawing}{Basic Drawing}\raisedaster - \o \l{painting/concentriccircles}{Concentric Circles}\raisedaster - \o \l{painting/fontsampler}{Font Sampler} - \o \l{painting/imagecomposition}{Image Composition}\raisedaster - \o \l{painting/painterpaths}{Painter Paths}\raisedaster - \o \l{painting/svggenerator}{SVG Generator}\raisedaster - \o \l{painting/svgviewer}{SVG Viewer} - \o \l{painting/transformations}{Transformations}\raisedaster - \endlist - - \section1 Phonon Multimedia Framework - - \list - \o \l{phonon/capabilities}{Capabilities}\raisedaster - \o \l{phonon/musicplayer}{Music Player}\raisedaster - \endlist - - \section1 Multimedia - - \list - \o \l{multimedia/audio/audiodevices}{Audio Devices}\raisedaster - \o \l{multimedia/audio/audiooutput}{Audio Output}\raisedaster - \o \l{multimedia/audio/audioinput}{Audio Input}\raisedaster - \endlist - - \section1 Qt Designer - - \list - \o \l{designer/calculatorbuilder}{Calculator Builder}\raisedaster - \o \l{designer/calculatorform}{Calculator Form}\raisedaster - \o \l{designer/customwidgetplugin}{Custom Widget Plugin}\raisedaster - \o \l{designer/taskmenuextension}{Task Menu Extension}\raisedaster - \o \l{designer/containerextension}{Container Extension}\raisedaster - \o \l{designer/worldtimeclockbuilder}{World Time Clock Builder}\raisedaster - \o \l{designer/worldtimeclockplugin}{World Time Clock Plugin}\raisedaster - \endlist - - \section1 Qt Linguist - - \list - \o \l{linguist/hellotr}{Hello tr()}\raisedaster - \o \l{linguist/arrowpad}{Arrow Pad}\raisedaster - \o \l{linguist/trollprint}{Troll Print}\raisedaster - \endlist - - \section1 Qt for Embedded Linux - - \list - \o \l{qws/svgalib}{Accelerated Graphics Driver}\raisedaster - \o \l{qws/dbscreen}{Double Buffered Graphics Driver}\raisedaster - \o \l{qws/mousecalibration}{Mouse Calibration}\raisedaster - \o \l{qws/ahigl}{OpenGL for Embedded Systems}\raisedaster - \o \l{qws/simpledecoration}{Simple Decoration}\raisedaster - \endlist - - \section1 Qt Script - - \list - \o \l{script/calculator}{Calculator}\raisedaster - \o \l{script/context2d}{Context2D}\raisedaster - \o \l{script/defaultprototypes}{Default Prototypes}\raisedaster - \o \l{script/helloscript}{Hello Script}\raisedaster - \o \l{script/qstetrix}{Qt Script Tetrix}\raisedaster - \o \l{script/customclass}{Custom Script Class}\raisedaster - \endlist - - \section1 Rich Text - - \list - \o \l{richtext/calendar}{Calendar}\raisedaster - \o \l{richtext/orderform}{Order Form}\raisedaster - \o \l{richtext/syntaxhighlighter}{Syntax Highlighter}\raisedaster - \o \l{richtext/textobject}{Text Object}\raisedaster - \endlist - - \section1 SQL - - \list - \o \l{sql/cachedtable}{Cached Table}\raisedaster - \o \l{sql/drilldown}{Drill Down}\raisedaster - \o \l{sql/querymodel}{Query Model} - \o \l{sql/relationaltablemodel}{Relational Table Model} - \o \l{sql/tablemodel}{Table Model} - \o \l{sql/sqlwidgetmapper}{SQL Widget Mapper}\raisedaster - \endlist - - \section1 State Machine - - \list - \o \l{statemachine/eventtransitions}{Event Transitions}\raisedaster - \o \l{statemachine/factorial}{Factorial States}\raisedaster - \o \l{statemachine/pingpong}{Ping Pong States}\raisedaster - \o \l{statemachine/rogue}{Rogue}\raisedaster - \o \l{statemachine/trafficlight}{Traffic Light}\raisedaster - \o \l{statemachine/twowaybutton}{Two-way Button}\raisedaster - \endlist - - \section1 Threads - - \list - \o \l{threads/queuedcustomtype}{Queued Custom Type}\raisedaster - \o \l{threads/mandelbrot}{Mandelbrot}\raisedaster - \o \l{threads/semaphores}{Semaphores}\raisedaster - \o \l{threads/waitconditions}{Wait Conditions}\raisedaster - \endlist - - \section1 Tools - - \list - \o \l{tools/codecs}{Codecs} - \o \l{tools/completer}{Completer}\raisedaster - \o \l{tools/customcompleter}{Custom Completer}\raisedaster - \o \l{tools/customtype}{Custom Type}\raisedaster - \o \l{tools/customtypesending}{Custom Type Sending}\raisedaster - \o \l{tools/echoplugin}{Echo Plugin}\raisedaster - \o \l{tools/i18n}{I18N} - \o \l{tools/plugandpaint}{Plug & Paint}\raisedaster - \o Plug & Paint Plugins: \l{tools/plugandpaintplugins/basictools}{Basic Tools}\raisedaster - and \l{tools/plugandpaintplugins/extrafilters}{Extra Filters}\raisedaster - \o \l{tools/regexp}{RegExp} - \o \l{tools/settingseditor}{Settings Editor} - \o \l{tools/styleplugin}{Style Plugin}\raisedaster - \o \l{tools/treemodelcompleter}{Tree Model Completer}\raisedaster - \o \l{tools/undoframework}{Undo Framework}\raisedaster - \endlist - - \section1 UiTools - - \list - \o \l{uitools/multipleinheritance}{Multiple Inheritance}\raisedaster - \o \l{uitools/textfinder}{Text Finder}\raisedaster - \endlist - - \section1 WebKit - - \list - \o \l{webkit/previewer}{Previewer}\raisedaster - \o \l{webkit/formextractor}{Form Extractor} - \o \l{webkit/googlechat}{Google Chat} - \o \l{webkit/fancybrowser}{Fancy Browser} - \endlist - - \section1 Widgets - - \list - \o \l{widgets/analogclock}{Analog Clock}\raisedaster - \o \l{widgets/calculator}{Calculator}\raisedaster - \o \l{widgets/calendarwidget}{Calendar Widget}\raisedaster - \o \l{widgets/charactermap}{Character Map}\raisedaster - \o \l{widgets/codeeditor}{Code Editor}\raisedaster - \o \l{widgets/digitalclock}{Digital Clock}\raisedaster - \o \l{widgets/groupbox}{Group Box}\raisedaster - \o \l{widgets/icons}{Icons}\raisedaster - \o \l{widgets/imageviewer}{Image Viewer}\raisedaster - \o \l{widgets/lineedits}{Line Edits}\raisedaster - \o \l{widgets/movie}{Movie} - \o \l{widgets/scribble}{Scribble}\raisedaster - \o \l{widgets/shapedclock}{Shaped Clock}\raisedaster - \o \l{widgets/sliders}{Sliders}\raisedaster - \o \l{widgets/spinboxes}{Spin Boxes}\raisedaster - \o \l{widgets/styles}{Styles}\raisedaster - \o \l{widgets/stylesheet}{Style Sheet}\raisedaster - \o \l{widgets/tablet}{Tablet}\raisedaster - \o \l{widgets/tetrix}{Tetrix}\raisedaster - \o \l{widgets/tooltips}{Tooltips}\raisedaster - \o \l{widgets/wiggly}{Wiggly}\raisedaster - \o \l{widgets/windowflags}{Window Flags}\raisedaster - \endlist - - \section1 XML - - \list - \o \l{xml/dombookmarks}{DOM Bookmarks} - \o \l{xml/saxbookmarks}{SAX Bookmarks} - \o \l{xml/streambookmarks}{QXmlStream Bookmarks}\raisedaster - \o \l{xml/rsslisting}{RSS-Listing} - \o \l{xml/xmlstreamlint}{XML Stream Lint Example}\raisedaster - \endlist - - \section1 XQuery, XPath - - \list - \o \l{xmlpatterns/recipes}{Recipes} - \o \l{xmlpatterns/filetree}{File System Example} - \o \l{xmlpatterns/qobjectxmlmodel}{QObject XML Model Example} - \o \l{xmlpatterns/xquery/globalVariables}{C++ Source Code Analyzer Example} - \o \l{xmlpatterns/trafficinfo}{Traffic Info}\raisedaster - \o \l{xmlpatterns/schema}{XML Schema Validation}\raisedaster - \endlist - - \section1 Inter-Process Communication - \list - \o \l{ipc/localfortuneclient}{Local Fortune Client}\raisedaster - \o \l{ipc/localfortuneserver}{Local Fortune Server}\raisedaster - \o \l{ipc/sharedmemory}{Shared Memory}\raisedaster - \endlist -*/ diff --git a/doc/src/examples/application.qdoc b/doc/src/examples/application.qdoc index 7b7b881..dcab9e7 100644 --- a/doc/src/examples/application.qdoc +++ b/doc/src/examples/application.qdoc @@ -289,7 +289,7 @@ When restoring the position and size of a window, it's important to call QWidget::resize() before QWidget::move(). The reason why - is given in the \l{geometry.html}{Window Geometry} overview. + is given in the \l{Window Geometry} overview. \snippet examples/mainwindows/application/mainwindow.cpp 37 \snippet examples/mainwindows/application/mainwindow.cpp 39 diff --git a/doc/src/examples/drilldown.qdoc b/doc/src/examples/drilldown.qdoc index fff3b60..b62ecc5 100644 --- a/doc/src/examples/drilldown.qdoc +++ b/doc/src/examples/drilldown.qdoc @@ -389,9 +389,7 @@ the item's hover events, animating the item when the mouse cursor is hovering over the image (by default, no items accept hover events). Please see the \l{The Graphics View Framework} - documentation and the - \l{Qt Examples#Graphics View}{Graphics View examples} for more - details. + documentation and the \l{Graphics View Examples} for more details. \snippet examples/sql/drilldown/view.cpp 5 diff --git a/doc/src/examples/qtscriptcalculator.qdoc b/doc/src/examples/qtscriptcalculator.qdoc index e9156b3..0e6e153 100644 --- a/doc/src/examples/qtscriptcalculator.qdoc +++ b/doc/src/examples/qtscriptcalculator.qdoc @@ -42,7 +42,6 @@ /*! \example script/calculator \title QtScript Calculator Example - \ingroup scripting In this simple QtScript example, we show how to implement the functionality of a calculator widget. diff --git a/doc/src/examples/trafficinfo.qdoc b/doc/src/examples/trafficinfo.qdoc index 76d0810..500cf31 100644 --- a/doc/src/examples/trafficinfo.qdoc +++ b/doc/src/examples/trafficinfo.qdoc @@ -159,5 +159,5 @@ The rest of the code in this example is just for representing the time and station information to the user, and uses techniques described in the - \l{Qt Examples#Widgets}{Widgets examples}. + \l{Widgets Examples}. */ diff --git a/doc/src/exportedfunctions.qdoc b/doc/src/exportedfunctions.qdoc deleted file mode 100644 index c51ace4..0000000 --- a/doc/src/exportedfunctions.qdoc +++ /dev/null @@ -1,139 +0,0 @@ -/**************************************************************************** -** -** 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 exportedfunctions.html - \title Special-Purpose Global Functions Exported by Qt - \ingroup classlists - - Qt provides a few low-level global functions for fine-tuning - applications. Most of these perform very specific tasks and are - platform-specific. In general, we recommend that you try using - Qt's public API before resorting to using any functions mentioned - here. - - These functions are exported by \l QtCore and \l QtGui, but most - of them aren't declared in Qt's header files. To use them in your - application, you must declare them before calling them. For - example: - - \snippet doc/src/snippets/code/doc_src_exportedfunctions.qdoc 0 - - These functions will remain as part of Qt for the lifetime of Qt - 4. - - Functions: - - \tableofcontents - - \section1 void qt_set_library_config_file(const QString &\e{fileName}) - - Specifies the location of the Qt configuration file. You must - call this function before constructing a QApplication or - QCoreApplication object. If no location is specified, Qt - automatically finds an appropriate location. - - \section1 void qt_set_sequence_auto_mnemonic(bool \e{enable}) - - Specifies whether mnemonics for menu items, labels, etc., should - be honored or not. On Windows and X11, this feature is - on by default; on Mac OS X, it is off. When this feature is off, - the QKeySequence::mnemonic() function always returns an empty - string. This feature is also enabled on embedded Linux. - - \section1 void qt_x11_wait_for_window_manager(QWidget *\e{widget}) - - Blocks until the X11 window manager has shown the widget after a - call to QWidget::show(). - - \section1 void qt_mac_secure_keyboard(bool \e{enable}) - - Turns the Mac OS X secure keyboard feature on or off. QLineEdit - uses this when the echo mode is QLineEdit::Password or - QLineEdit::NoEcho to guard the editor against keyboard sniffing. - If you implement your own password editor, you might want to turn - on this feature in your editor's - \l{QWidget::focusInEvent()}{focusInEvent()} and turn it off in - \l{QWidget::focusOutEvent()}{focusOutEvent()}. - - \section1 void qt_mac_set_dock_menu(QMenu *\e{menu}) - - Sets the menu to display in the Mac OS X Dock for the - application. This menu is shown when the user attempts a - press-and-hold operation on the application's dock icon or - \key{Ctrl}-clicks on it while the application is running. - - The menu will be turned into a Mac menu and the items added to the default - Dock menu. There is no merging of the Qt menu items with the items that are - in the Dock menu (i.e., it is not recommended to include actions that - duplicate functionality of items already in the Dock menu). - - \section1 void qt_mac_set_menubar_icons(bool \e{enable}) - - Specifies whether icons associated to menu items for the - application's menu bar should be shown on Mac OS X. By default, - icons are shown on Mac OS X just like on the other platforms. - - In Qt 4.4, this is equivalent to - \c { QApplication::instance()->setAttribute(Qt::AA_DontShowIconsInMenus); }. - - \section1 void qt_mac_set_menubar_merge(bool \e{enable}) - - Specifies whether Qt should attempt to relocate standard menu - items (such as \gui Quit, \gui Preferences, and \gui About) to - the application menu on Mac OS X. This feature is on by default. - See \l{Qt for Mac OS X - Specific Issues} for the list of menu items for - which this applies. - - \section1 void qt_mac_set_native_menubar(bool \e{enable}) - - Specifies whether the application should use the native menu bar - on Mac OS X or be part of the main window. This feature is on by - default. - - In Qt 4.6, this is equivalent to - \c { QApplication::instance()->setAttribute(Qt::AA_DontUseNativeMenuBar); }. - - \section1 void qt_mac_set_press_and_hold_context(bool \e{enable}) - - Turns emulation of the right mouse button by clicking and holding - the left mouse button on or off. This feature is off by default. -*/ diff --git a/doc/src/files-and-resources/datastreamformat.qdoc b/doc/src/files-and-resources/datastreamformat.qdoc new file mode 100644 index 0000000..4226d0b --- /dev/null +++ b/doc/src/files-and-resources/datastreamformat.qdoc @@ -0,0 +1,363 @@ +/**************************************************************************** +** +** 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 datastreamformat.html + \title Format of the QDataStream Operators + \brief Representations of data types that can be serialized by QDataStream. + + The \l QDataStream allows you to serialize some of the Qt data types. + The table below lists the data types that QDataStream can serialize + and how they are represented. The format described below is + \l{QDataStream::setVersion()}{version 8}. + + It is always best to cast integers to a Qt integer type, such as + qint16 or quint32, when reading and writing. This ensures that + you always know exactly what size integers you are reading and + writing, no matter what the underlying platform and architecture + the application happens to be running on. + + \table + \row \o bool + \o \list + \o boolean + \endlist + \row \o qint8 + \o \list + \o signed byte + \endlist + \row \o qint16 + \o \list + \o signed 16-bit integer + \endlist + \row \o qint32 + \o \list + \o signed 32-bit integer + \endlist + \row \o qint64 + \o \list + \o signed 64-bit integer + \endlist + \row \o quint8 + \o \list + \o unsigned byte + \endlist + \row \o quint16 + \o \list + \o unsigned 16-bit integer + \endlist + \row \o quint32 + \o \list + \o unsigned 32-bit integer + \endlist + \row \o quint64 + \o \list + \o unsigned 64-bit integer + \endlist + \row \o \c float + \o \list + \o 32-bit floating point number using the standard IEEE 754 format + \endlist + \row \o \c double + \o \list + \o 64-bit floating point number using the standard IEEE 754 format + \endlist + \row \o \c {const char *} + \o \list + \o The string length (quint32) + \o The string bytes, excluding the terminating 0 + \endlist + \row \o QBitArray + \o \list + \o The array size (quint32) + \o The array bits, i.e. (size + 7)/8 bytes + \endlist + \row \o QBrush + \o \list + \o The brush style (quint8) + \o The brush color (QColor) + \o If style is CustomPattern, the brush pixmap (QPixmap) + \endlist + \row \o QByteArray + \o \list + \o If the byte array is null: 0xFFFFFFFF (quint32) + \o Otherwise: the array size (quint32) followed by the array bytes, i.e. size bytes + \endlist + \row \o \l QColor + \o \list + \o Color spec (qint8) + \o Alpha value (quint16) + \o Red value (quint16) + \o Green value (quint16) + \o Blue value (quint16) + \o Pad value (quint16) + \endlist + \row \o QCursor + \o \list + \o Shape ID (qint16) + \o If shape is BitmapCursor: The bitmap (QPixmap), mask (QPixmap), and hot spot (QPoint) + \endlist + \row \o QDate + \o \list + \o Julian day (quint32) + \endlist + \row \o QDateTime + \o \list + \o Date (QDate) + \o Time (QTime) + \o 0 for Qt::LocalTime, 1 for Qt::UTC (quint8) + \endlist + \row \o QFont + \o \list + \o The family (QString) + \o The point size (qint16) + \o The style hint (quint8) + \o The char set (quint8) + \o The weight (quint8) + \o The font bits (quint8) + \endlist + \row \o QHash<Key, T> + \o \list + \o The number of items (quint32) + \o For all items, the key (Key) and value (T) + \endlist + \row \o QIcon + \o \list + \o The number of pixmap entries (quint32) + \o For all pixmap entries: + \list + \o The pixmap (QPixmap) + \o The file name (QString) + \o The pixmap size (QSize) + \o The \l{QIcon::Mode}{mode} (quint32) + \o The \l{QIcon::State}{state} (quint32) + \endlist + \endlist + \row \o QImage + \o \list + \o If the image is null a "null image" marker is saved; + otherwise the image is saved in PNG or BMP format (depending + on the stream version). If you want control of the format, + stream the image into a QBuffer (using QImageIO) and stream + that. + \endlist + \row \o QKeySequence + \o \list + \o A QList<int>, where each integer is a key in the key sequence + \endlist + \row \o QLinkedList<T> + \o \list + \o The number of items (quint32) + \o The items (T) + \endlist + \row \o QList<T> + \o \list + \o The number of items (quint32) + \o The items (T) + \endlist + \row \o QMap<Key, T> + \o \list + \o The number of items (quint32) + \o For all items, the key (Key) and value (T) + \endlist + \row \o QMatrix + \o \list + \o m11 (double) + \o m12 (double) + \o m21 (double) + \o m22 (double) + \o dx (double) + \o dy (double) + \endlist + \row \o QMatrix4x4 + \o \list + \o m11 (double) + \o m12 (double) + \o m13 (double) + \o m14 (double) + \o m21 (double) + \o m22 (double) + \o m23 (double) + \o m24 (double) + \o m31 (double) + \o m32 (double) + \o m33 (double) + \o m34 (double) + \o m41 (double) + \o m42 (double) + \o m43 (double) + \o m44 (double) + \endlist + \row \o QPair<T1, T2> + \o \list + \o first (T1) + \o second (T2) + \endlist + \row \o QPalette + \o The disabled, active, and inactive color groups, each of which consists + of the following: + \list + \o foreground (QBrush) + \o button (QBrush) + \o light (QBrush) + \o midlight (QBrush) + \o dark (QBrush) + \o mid (QBrush) + \o text (QBrush) + \o brightText (QBrush) + \o buttonText (QBrush) + \o base (QBrush) + \o background (QBrush) + \o shadow (QBrush) + \o highlight (QBrush) + \o highlightedText (QBrush) + \o link (QBrush) + \o linkVisited (QBrush) + \endlist + \row \o QPen + \o \list + \o The pen styles (quint8) + \o The pen width (quint16) + \o The pen color (QColor) + \endlist + \row \o QPicture + \o \list + \o The size of the picture data (quint32) + \o The raw bytes of picture data (char) + \endlist + \row \o QPixmap + \o \list + \o Save it as a PNG image. + \endlist + \row \o QPoint + \o \list + \o The x coordinate (qint32) + \o The y coordinate (qint32) + \endlist + \row \o QQuaternion + \o \list + \o The scalar component (double) + \o The x coordinate (double) + \o The y coordinate (double) + \o The z coordinate (double) + \endlist + \row \o QRect + \o \list + \o left (qint32) + \o top (qint32) + \o right (qint32) + \o bottom (qint32) + \endlist + \row \o QRegExp + \o \list + \o The regexp pattern (QString) + \o Case sensitivity (quint8) + \o Regular expression syntax (quint8) + \o Minimal matching (quint8) + \endlist + \row \o QRegion + \o \list + \o The size of the data, i.e. 8 + 16 * (number of rectangles) (quint32) + \o 10 (qint32) + \o The number of rectangles (quint32) + \o The rectangles in sequential order (QRect) + \endlist + \row \o QSize + \o \list + \o width (qint32) + \o height (qint32) + \endlist + \row \o QString + \o \list + \o If the string is null: 0xFFFFFFFF (quint32) + \o Otherwise: The string length in bytes (quint32) followed by the data in UTF-16 + \endlist + \row \o QTime + \o \list + \o Milliseconds since midnight (quint32) + \endlist + \row \o QTransform + \o \list + \o m11 (double) + \o m12 (double) + \o m13 (double) + \o m21 (double) + \o m22 (double) + \o m23 (double) + \o m31 (double) + \o m32 (double) + \o m33 (double) + \endlist + \row \o QUrl + \o \list + \o Holds an URL (QString) + \endlist + \row \o QVariant + \o \list + \o The type of the data (quint32) + \o The null flag (qint8) + \o The data of the specified type + \endlist + \row \o QVector2D + \o \list + \o the x coordinate (double) + \o the y coordinate (double) + \endlist + \row \o QVector3D + \o \list + \o the x coordinate (double) + \o the y coordinate (double) + \o the z coordinate (double) + \endlist + \row \o QVector4D + \o \list + \o the x coordinate (double) + \o the y coordinate (double) + \o the z coordinate (double) + \o the w coordinate (double) + \endlist + \row \o QVector<T> + \o \list + \o The number of items (quint32) + \o The items (T) + \endlist + \endtable +*/ diff --git a/doc/src/files-and-resources/resources.qdoc b/doc/src/files-and-resources/resources.qdoc new file mode 100644 index 0000000..a799646 --- /dev/null +++ b/doc/src/files-and-resources/resources.qdoc @@ -0,0 +1,203 @@ +/**************************************************************************** +** +** 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 io + \title Input/Output and Networking + \ingroup groups + + \brief Classes providing file input and output along with directory and + network handling. + + These classes are used to handle input and output to and from external + devices, processes, files etc. as well as manipulating files and directories. +*/ + +/*! + \page resources.html + \title The Qt Resource System + + \keyword resource system + + The Qt resource system is a platform-independent mechanism for + storing binary files in the application's executable. This is + useful if your application always needs a certain set of files + (icons, translation files, etc.) and you don't want to run the + risk of losing the files. + + The resource system is based on tight cooperation between \l qmake, + \l rcc (Qt's resource compiler), and QFile. It obsoletes Qt 3's + \c qembed tool and the + \l{http://qt.nokia.com/doc/qq/qq05-iconography.html#imagestorage}{image + collection} mechanism. + + \section1 Resource Collection Files (\c{.qrc}) + + The resources associated with an application are specified in a + \c .qrc file, an XML-based file format that lists files on the + disk and optionally assigns them a resource name that the + application must use to access the resource. + + Here's an example \c .qrc file: + + \quotefile mainwindows/application/application.qrc + + The resource files listed in the \c .qrc file are files that are + part of the application's source tree. The specified paths are + relative to the directory containing the \c .qrc file. Note that + the listed resource files must be located in the same directory as + the \c .qrc file, or one of its subdirectories. + + Resource data can either be compiled into the binary and thus accessed + immediately in application code, or a binary resource can be created + and at a later point in application code registered with the resource + system. + + By default, resources are accessible in the application under the + same name as they have in the source tree, with a \c :/ prefix. + For example, the path \c :/images/cut.png would give access to the + \c cut.png file, whose location in the application's source tree + is \c images/cut.png. This can be changed using the \c file tag's + \c alias attribute: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 0 + + The file is then accessible as \c :/cut-img.png from the + application. It is also possible to specify a path prefix for all + files in the \c .qrc file using the \c qresource tag's \c prefix + attribute: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 1 + + In this case, the file is accessible as \c + :/myresources/cut-img.png. + + Some resources, such as translation files and icons, many need to + change based on the user's locale. This is done by adding a \c lang + attribute to the \c qresource tag, specifying a suitable locale + string. For example: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 2 + + If the user's locale is French (i.e., QLocale::system().name() returns + "fr_FR"), \c :/cut.jpg becomes a reference to the \c cut_fr.jpg + image. For other locales, \c cut.jpg is used. + + See the QLocale documentation for a description of the format to use + for locale strings. + + + \section2 External Binary Resources + + For an external binary resource to be created you must create the resource + data (commonly given the \c .rcc extension) by passing the -binary switch to + \l rcc. Once the binary resource is created you can register the resource + with the QResource API. + + For example, a set of resource data specified in a \c .qrc file can be + compiled in the following way: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 3 + + In the application, this resource would be registered with code like this: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 4 + + \section2 Compiled-In Resources + + For a resource to be compiled into the binary the \c .qrc file must be + mentioned in the application's \c .pro file so that \c qmake knows + about it. For example: + + \snippet examples/mainwindows/application/application.pro 0 + + \c qmake will produce make rules to generate a file called \c + qrc_application.cpp that is linked into the application. This + file contains all the data for the images and other resources as + static C++ arrays of compressed binary data. The \c + qrc_application.cpp file is automatically regenerated whenever + the \c .qrc file changes or one of the files that it refers to + changes. If you don't use \c .pro files, you can either invoke + \c rcc manually or add build rules to your build system. + + \image resources.png Building resources into an application + + Currently, Qt always stores the data directly in the executable, + even on Windows and Mac OS X, where the operating system provides + native support for resources. This might change in a future Qt + release. + + \section1 Using Resources in the Application + + In the application, resource paths can be used in most places + instead of ordinary file system paths. In particular, you can + pass a resource path instead of a file name to the QIcon, QImage, + or QPixmap constructor: + + \snippet examples/mainwindows/application/mainwindow.cpp 21 + + See the \l{mainwindows/application}{Application} example for an + actual application that uses Qt's resource system to store its + icons. + + In memory, resources are represented by a tree of resource + objects. The tree is automatically built at startup and used by + QFile for resolving paths to resources. You can use a QDir initialized + with ":/" to navigate through the resource tree from the root. + + Qt's resources support the concept of a search path list. If you then + refer to a resource with \c : instead of \c :/ as the prefix, the + resource will be looked up using the search path list. The search + path list is empty at startup; call QDir::addSearchPath() to + add paths to it. + + If you have resources in a static library, you might need to + force initialization of your resources by calling \l + Q_INIT_RESOURCE() with the base name of the \c .qrc file. For + example: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 5 + + Similarly, if you must unload a set of resources explicitly + (because a plugin is being unloaded or the resources are not valid + any longer), you can force removal of your resources by calling + Q_CLEANUP_RESOURCE() with the same base name as above. +*/ diff --git a/doc/src/focus.qdoc b/doc/src/focus.qdoc deleted file mode 100644 index 459a9d8..0000000 --- a/doc/src/focus.qdoc +++ /dev/null @@ -1,213 +0,0 @@ -/**************************************************************************** -** -** 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$ -** -****************************************************************************/ - -/**************************************************************************** -** -** Documentation of focus handling in Qt. -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the Qt GUI Toolkit. -** EDITIONS: FREE, PROFESSIONAL, ENTERPRISE -** -****************************************************************************/ - -/*! - \page focus.html - \title Keyboard Focus - \ingroup architecture - \ingroup gui-programming - \brief An overview of the keyboard focus management and handling. - - \keyword keyboard focus - - Qt's widgets handle keyboard focus in the ways that have become - customary in GUIs. - - The basic issue is that the user's key strokes can be directed at any - of several windows on the screen, and any of several widgets inside - the intended window. When the user presses a key, they expect it to go - to the right place, and the software must try to meet this - expectation. The system must determine which application the key stroke - is directed at, which window within that application, and which widget - within that window. - - \section1 Focus Motion - - The customs which have evolved for directing keyboard focus to a - particular widget are these: - - \list 1 - - \o The user presses \key Tab (or \key Shift+Tab). - \o The user clicks a widget. - \o The user presses a keyboard shortcut. - \o The user uses the mouse wheel. - \o The user moves the focus to a window, and the application must - determine which widget within the window should get the focus. - \endlist - - Each of these motion mechanisms is different, and different types of - widgets receive focus in only some of them. We'll cover each of them - in turn. - - \section2 Tab or Shift+Tab - - Pressing \key Tab is by far the most common way to move focus - using the keyboard. (Sometimes in data-entry applications Enter - does the same as \key{Tab}; this can easily be achieved in Qt by - implementing an \l{Events and Event Filters}{event filter}.) - - Pressing \key Tab, in all window systems in common use today, - moves the keyboard focus to the next widget in a circular - per-window list. \key Tab moves focus along the circular list in - one direction, \key Shift+Tab in the other. The order in which - \key Tab presses move from widget to widget is called the tab order. - - You can customize the tab order using QWidget::setTabOrder(). (If - you don't, \key Tab generally moves focus in the order of widget - construction.) \l{Qt Designer} provides a means of visually - changing the tab order. - - Since pressing \key Tab is so common, most widgets that can have focus - should support tab focus. The major exception is widgets that are - rarely used, and where there is some keyboard accelerator or error - handler that moves the focus. - - For example, in a data entry dialog, there might be a field that - is only necessary in one per cent of all cases. In such a dialog, - \key Tab could skip this field, and the dialog could use one of - these mechanisms: - - \list 1 - - \o If the program can determine whether the field is needed, it can - move focus there when the user finishes entry and presses \gui OK, or when - the user presses Enter after finishing the other fields. Alternately, - include the field in the tab order but disable it. Enable it if it - becomes appropriate in view of what the user has set in the other - fields. - - \o The label for the field can include a keyboard shortcut that moves - focus to this field. - - \endlist - - Another exception to \key Tab support is text-entry widgets that - must support the insertion of tabs; almost all text editors fall - into this c