diff options
| author | Volker Hilsheimer <volker.hilsheimer@nokia.com> | 2009-08-17 16:37:42 (GMT) |
|---|---|---|
| committer | Volker Hilsheimer <volker.hilsheimer@nokia.com> | 2009-08-17 16:37:42 (GMT) |
| commit | 911557fcf7dedc002e689a0d66efd2b77e044bd1 (patch) | |
| tree | a66138f008c27f39e5306dc6f2df01c129e11988 /doc/src/platforms | |
| parent | 285d4b12cb937a5672d6eb15781f03d249f8cfc1 (diff) | |
| download | Qt-911557fcf7dedc002e689a0d66efd2b77e044bd1.zip Qt-911557fcf7dedc002e689a0d66efd2b77e044bd1.tar.gz Qt-911557fcf7dedc002e689a0d66efd2b77e044bd1.tar.bz2 | |
Restructure the documentation, both on a file and on a content level.
- directory structure in doc/src
- moving of class-specific documentation together with classes
- new, less cluttered index page
- significantely reduced number of "groups of classes"
- categorized all (?) documentation into "Frameworks" or "Howtos"
- reformatting of examples pages
- splitting of very long documentation pages into walkthroughs
- some writing where it was missing
Squashed commit of the following:
commit b44ea6c917a7470a678509f4c6c9b8836d277346
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 17 18:32:09 2009 +0200
Some cleaning up in the categories.
commit b592c6eba72332fd23911251d836cf0af4514bae
Merge: 1e10d9e 285d4b1
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 17 18:20:57 2009 +0200
Merge branch 'master' into doccleanup
commit 1e10d9e732f4171e61b3d1ecf0b64f7509e71607
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 17 18:19:03 2009 +0200
Split the "io" group into "io" and "network".
And list the network classes in the respective overview documentation.
commit fae86d24becb69c532a9c3b4fbf744c44a54f49d
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 17 18:00:32 2009 +0200
Move the string-processing classes together with the Unicode in Qt docu.
commit d2a6dd3307b0306bd7a8e283e11a99e833206963
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 17 18:00:14 2009 +0200
Not a toplevel topic, it's within the "paint system" set of pages.
commit 44cba00cdf7fb086dd3bb62b15c0f9a7915e20c2
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 17 17:57:37 2009 +0200
"Canvas UI" is not a stand-alone concept in Qt - yet!
commit 5f6e69b38fbca661709bc20b502ab0bc1b251b96
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 17 17:43:01 2009 +0200
Can just as well delete the old index.
commit aa5ec5327dceb1d3df62b990a32c970cce03ba9c
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 17 17:39:52 2009 +0200
Some rephrasing and easier access to the "Keyboard Focus" docu.
commit 6248de281565cafce12221c902e9944867b338b3
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 17 17:37:02 2009 +0200
Replace the old index with the new index.
commit 110acab8af0c99db9905b0f4cc6e93c325b1e3c6
Merge: d88d526 53807e5
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 17 16:04:59 2009 +0200
Merge branch 'master' into doccleanup
commit d88d52681d758e9e730de0e69290472728bf8c40
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Sun Aug 16 17:34:14 2009 +0200
Give the "Widgets and Layouts" topic a bit more content.
commit 01e108a5f2d1d0948c2093987a77f222d6cc4d09
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Sun Aug 16 14:21:41 2009 +0200
Move OpenVG "best practices" documentation into howtos directory.
commit 86f4ca38f965909a29cee0478c537558a4ea8f5a
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Sun Aug 16 14:18:32 2009 +0200
Add module documentation for OpenVG and Multimedia.
commit 9fef923acbbb75cdc3fc4e984aec177ddcd24c53
Merge: e7e5cd9 72c1cb2
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Sun Aug 16 13:20:23 2009 +0200
Merge branch 'master' into doccleanup
commit e7e5cd9444ac0e7be55ecfbeb8c9ace23784205b
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Sun Aug 16 13:20:08 2009 +0200
Add Google custom search box.
Not sure why that change was never merged in by git.
commit 348372947a3d7da2b28325731ac02bbc67cdec41
Merge: 3ff51b9 aa09d4f
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Sat Aug 15 02:14:31 2009 +0200
Merge branch 'master' into doccleanup
commit 3ff51b9b52af39c00a938db380809e36b6c701c9
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Sat Aug 15 02:09:38 2009 +0200
Minor word-smithing.
commit da612b4130061e094a16d47a450f3f3fe6f547c7
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Sat Aug 15 01:55:16 2009 +0200
Separating the "multimedia" group into reasonable sets of classes.
commit 838955a1a780e41ea77676e1bef8e471c7a2a2f5
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Aug 14 23:12:33 2009 +0200
Just one file, doesn't need a separate directory.
commit b99f56262faa4410880d08787f2c8d9a509d303d
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Aug 14 23:05:59 2009 +0200
Move documentation for Asian codecs into src/corelib/codecs.
Not ideal, the source of most of those codecs live in src/plugins/codecs,
but since this is no real API documentation it's probably appropriate.
commit ba2258c0b6587d959cdfe6ff99c4d36319077aac
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Aug 14 22:24:33 2009 +0200
Renaming of files that used old product/company names.
commit 30ee7deb935bb3de4257cd71be5ba9610376047c
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Aug 14 22:14:30 2009 +0200
Those will only used by "Qt 4 for Qt 3" users, so leave the original text.
commit d0c110d047bbbd2dde70fc51ad702db59fa3883b
Merge: c5eccd5 8198d35
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Aug 14 22:12:15 2009 +0200
Merge branch 'master' into doccleanup
commit c5eccd51ad85cfaf07ea8522a977b7bef70f70fd
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Aug 14 22:09:43 2009 +0200
Moving some last files from doc/src into subdirectories.
commit d2dc303d92c1f66bf721b65fca1c6d55ab7ec01d
Merge: 0bdf16e a835ec7
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Aug 14 15:39:59 2009 +0200
Merge branch 'master' into doccleanup
commit 0bdf16e1bb04e532d4cc72c5646cb28470d5e627
Merge: 04bb351 c73fd72
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Aug 14 13:08:37 2009 +0200
Merge branch 'master' into doccleanup
Conflicts:
src/3rdparty/webkit/WebKit/qt/Api/qwebelement.cpp
commit 04bb3513f107a895cfbbf98f8c4f9a67e392c72a
Merge: 8a52ce8 07d2ce1
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Wed Aug 12 19:58:04 2009 +0200
Merge branch 'master' into doccleanup
Conflicts:
tools/qdoc3/test/qt-html-templates.qdocconf
commit 8a52ce8055d5d8b1bf799bf1fdde18aaf8b940c7
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Wed Aug 12 13:30:50 2009 +0200
Fix some links to the qt.nokia.com page, and at least some linking to IO.
commit f7823801bf750b0b76ce0871c3f9e8e59c7901fe
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Wed Aug 12 12:27:19 2009 +0200
Make links in header point to the pages with links to everything else.
commit 335012b7e96698d6ec7994fdfd52813140f12413
Merge: 21b1263 96b6a3c
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Wed Aug 12 12:17:57 2009 +0200
Merge branch 'master' into doccleanup
Conflicts:
doc/src/classes/qtdesigner-api.qdoc
doc/src/desktop-integration.qdoc
doc/src/distributingqt.qdoc
doc/src/examples-overview.qdoc
doc/src/examples.qdoc
doc/src/frameworks-technologies/dbus-adaptors.qdoc
doc/src/geometry.qdoc
doc/src/groups.qdoc
doc/src/objecttrees.qdoc
doc/src/plugins-howto.qdoc
doc/src/qt4-accessibility.qdoc
doc/src/qt4-scribe.qdoc
doc/src/qt4-sql.qdoc
doc/src/qt4-styles.qdoc
doc/src/qtdbus.qdoc
doc/src/qtgui.qdoc
doc/src/qtmain.qdoc
doc/src/qtopengl.qdoc
doc/src/qtscripttools.qdoc
doc/src/qtsvg.qdoc
doc/src/qtuiloader.qdoc
doc/src/qundo.qdoc
doc/src/richtext.qdoc
doc/src/topics.qdoc
doc/src/xml-processing/xml-processing.qdoc
commit 21b126346989a86a828ee8a66bb12108d2bb2b71
Merge: 88e7d76 204c771
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 11 18:15:17 2009 +0200
Merge branch 'master' into doccleanup
commit 88e7d76ceec664404a913469025ed9a7ca6f4fb0
Merge: 97c4128 1c62dc4
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 11 18:00:56 2009 +0200
Merge branch 'master' into doccleanup
commit 97c412815162859d853c5a4ede1eb9bd4be4af9b
Merge: cf5d8ae 4096911
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 10 19:27:08 2009 +0200
Merge branch 'master' into doccleanup
commit cf5d8ae4b09a92fed5b4e4cabbcfd49116e9e13f
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 10 19:09:57 2009 +0200
This should link to the platform specific documentation.
commit 38610f0ff210286f92528495d48f434d2c0db8e8
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 10 18:59:35 2009 +0200
These groups are embedded in the respective framework overview already.
commit 1e58a90c561d33aada9427b17db8e0f7bbe02fa7
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Mon Aug 10 18:07:23 2009 +0200
This guide should only be in the porting group.
commit ef731bcc53a9b34ba3b42e5ad7caf4234941c4a9
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Mon Aug 10 17:55:20 2009 +0200
Make the QtScript overview documentation part of frameworks.
commit 3413696bd745ee5862aa517dcfc9c8446fee9b82
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Mon Aug 10 17:44:57 2009 +0200
Porting guides are part of the Howto's
commit cfcc742f938cf7c278f1f8b11b24a61f62fb4c62
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Mon Aug 10 16:48:09 2009 +0200
Merge branch 'master' into doccleanup
commit c5642857b2f2364134f58776661cc08a9da13b2c
Merge: 9cdeba7 24aa363
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 10 15:53:47 2009 +0200
Merge branch 'master' into doccleanup
commit 9cdeba712c51eb0bf71eab35080734a2b93efcc5
Merge: 09dac33 d13418e
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Sat Aug 8 11:46:42 2009 +0200
Merge branch 'master' into doccleanup
commit 09dac333d427792a8d33fa311a63c620678e7920
Merge: f7b211e dfa2842
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Aug 7 15:40:33 2009 +0200
Merge branch 'master' into doccleanup
Conflicts:
doc/src/examples.qdoc
commit f7b211e5588fee20913a8d02c55cca0e05ea2859
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Thu Aug 6 14:58:49 2009 +0200
Rename file to follow naming scheme and resulting html.
commit ed6432fea376e60e4dd7c8987ed61a063af11ac7
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Thu Aug 6 14:15:00 2009 +0200
Add a table of contents.
commit 1569c35cb90c10ead72dcea2c4b99a0a6cbfcc13
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Thu Aug 6 14:04:52 2009 +0200
Splitting the long SQL documentation into walkthrough steps.
commit 6a05688bce3cca34dd1b8b323b8feb49d3133d7e
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Thu Aug 6 08:15:52 2009 +0200
Merge branch 'master' into doccleanup
commit 2a286b03167ce028821b4007bf08537d2c5637c2
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Wed Aug 5 18:09:58 2009 +0200
Merge branch 'master' into doccleanup
commit 86f956c89b9b8fb3d684665797d4a5b5e538fb2c
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Wed Aug 5 17:06:15 2009 +0200
Start work on windows and dialogs docu.
commit 4253dea2661dc3526a9dec53f336301992b543cb
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Wed Aug 5 16:01:25 2009 +0200
Make QtWebKit classes show up in the module overview.
commit d38d185ec8b7d32037e86b4ecbbc725343aabea7
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Wed Aug 5 14:35:07 2009 +0200
Merge branch 'master' into doccleanup
commit deb4c2bb4d7120579fda541b03c0a77d989089d5
Merge: 37e5373 f78bd88
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Wed Aug 5 12:59:22 2009 +0200
Merge branch 'master' into doccleanup
commit 37e5373dcc5455b1e029ee389ce7985a98f579d9
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Wed Aug 5 00:04:36 2009 +0200
Line-feed fixes.
commit 2fa80a411dd96369c0e09defc54af44118930ae5
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Wed Aug 5 00:00:45 2009 +0200
The Accessibility group is just a group of classes.
commit b17db7dc54c1945cd2651fdebde471c71ef4001d
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 17:35:46 2009 +0200
This should be together with all the other licensing documentation.
commit be91b2fe15c67cb90eaa59121d7ff51eb21b4dba
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 17:26:02 2009 +0200
These are best practices.
commit 8e0b104db1266a736ac246c9466656c058df18f2
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 17:25:35 2009 +0200
Another technology.
commit 19c16384d712c652716776c94c749030b0742752
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 17:24:55 2009 +0200
Remove duplicate and out-of-date license headers.
commit 689aa91de0f840fc0f98f0adfbb2f18d72c6b985
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 15:54:46 2009 +0200
Use the new \annotatedlist command, and make it a framework.
commit ba3a0376acb44ae5cafc8bd3802bd425dcb663a5
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 15:38:24 2009 +0200
Make \annotatedlist <group> work.
commit c80fb8d6a143c81700c2aefe7af1e83dd487dde4
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 15:37:51 2009 +0200
These are API documentation, not architecture.
commit 713744520bd35d510864ad48464575f1c8a35668
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 15:10:25 2009 +0200
Frameworks and technologies used in Qt are really one thing.
commit a86d4248c1e3c13f245c49f3f2d018ec4babc822
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 12:50:58 2009 +0200
Architecture -> Frameworks and Technologies
commit 4a3ba3f19d78c4df5343af951c761df47e22759a
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 12:50:41 2009 +0200
Some consolidation of the Tulip documentation.
commit d3dab98b96d83ce408523f8ccb9363a09eed1f34
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 12:01:10 2009 +0200
Start with "Frameworks and Technologies" vs "howtos and best practices".
commit 37a8e364442e6234c6a83667eb64af1c79b38e9b
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 12:00:34 2009 +0200
Beautify.
commit c86d844a79406d4b9fee67578efd67e27ce96b83
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 00:04:40 2009 +0200
Fix some headers.
commit 20b775d781d3b1d91164320807c21c8a6efcf011
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Mon Aug 3 23:45:28 2009 +0200
Move "Getting Started" documentation into getting-started directory.
commit 561cc3eafa20903243f3946ac4b7b724554c341c
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 3 19:06:16 2009 +0200
Group "getting started" documents into a walkthrough structure.
commit 6d703807348923a068dea7360fb4456cbde071b6
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 3 17:35:15 2009 +0200
Add screenshots for example-overview page.
commit f7a47536305e157c16e8a863f145a2617606a2cc
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Sat Aug 1 22:39:27 2009 +0200
Cleanup the script-related groups a bit.
commit ca469165a9f55ca6bd31e53d85d74883fe892ed4
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Sat Aug 1 20:50:06 2009 +0200
One group of thread-related classes should be enough.
commit b8935bc0ec3d33b6a3fe7b3b220b5781ad79d68d
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 18:37:53 2009 +0200
Consolidate style documentation.
commit 1d8d30eee1e2fe9f8e77ce1462803921b2132ade
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 17:13:44 2009 +0200
Split plugin-documentation into two: writing plugins and deploying plugins.
commit a329665353a78749b0d4fdd6e75403252d34f679
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 14:19:47 2009 +0200
Some final module cleaning up.
commit e3de6579d43cc9796b69188cfb9d3d415a91a770
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 13:51:54 2009 +0200
Move remaining overview groups into one file.
commit 7d783342f520f8376e561246268371d0b74a4e44
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 13:28:21 2009 +0200
Kill the group "misc".
commit e414a8945cb938ccc6bd1bd8cd52adbfade096c2
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 13:08:37 2009 +0200
More moving of files and content.
commit 1ef3134bade2df33ff68c7c906cf20343abd86a5
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 02:03:07 2009 +0200
Workaround qdoc being difficult.
commit 49064b0570088fe749fc08c02c5ab6d23855089f
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 01:49:52 2009 +0200
Some more moving of files into meaningful directories.
commit df4ced831cf9f49c638c231fa9f2754699a8a59d
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Thu Jul 30 20:57:39 2009 +0200
Fix a few links.
commit ecb79681417e8bc3d8e46065dc12146f4d4dfc5f
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Thu Jul 30 20:20:55 2009 +0200
Consolidate the two example documents into one page.
commit d30d980055e7c531c9e73cdf9a1b220ce9691eef
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Thu Jul 30 18:23:55 2009 +0200
The new index page and respective style changes.
commit 5245d784eb46287f8e1ae41addb2765eb19b0663
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Thu Jul 30 17:05:46 2009 +0200
Deployment group is gone.
commit 567d737a8d08f227133674ebfe2d161888862b8c
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <thierry.bastian@nokia.com>
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 <richard.gustavsen@nokia.com>
Date: Tue Aug 4 10:00:01 2009 +0200
Mac: Remove debug work output
commit 62687960508b2855b48d64825b445e5738c44142
Author: Richard Moe Gustavsen <richard.gustavsen@nokia.com>
Date: Tue Aug 4 09:45:47 2009 +0200
Modify imagewidget example so it works with new API
commit 9c7aed68270b336ae9a309d9eb0107d49729c1f3
Author: Richard Moe Gustavsen <richard.gustavsen@nokia.com>
Date: Tue Aug 4 09:43:14 2009 +0200
Add support for pan gesture on mac (carbon and cocoa)
commit be5783878a977148b34dc64c464e951be312964e
Author: Morten Sorvig <msorvig@trolltech.com>
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 <msorvig@trolltech.com>
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 <msorvig@trolltech.com>
Date: Tue Aug 4 08:15:21 2009 +0200
Make Cocoa builds 64-bit by default on snow leopard.
commit 4672e771c164503d998ccb6ca05cf7e7906fb031
Author: Jason McDonald <jason.mcdonald@nokia.com>
Date: Tue Aug 4 15:40:15 2009 +1000
Fix incorrect license headers.
Reviewed-by: Trust Me
commit a3bd65e8eb0fd39e14539919cc9ced645c969883
Author: Bill King <bill.king@nokia.com>
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 <jason.mcdonald@nokia.com>
Date: Tue Aug 4 14:49:14 2009 +1000
Fix obsolete license headers
Reviewed-by: Trust Me
commit c3bcc8b094341e0dc768ef5820ba359e2c23436a
Author: Aaron Kennedy <aaron.kennedy@nokia.com>
Date: Tue Aug 4 10:59:02 2009 +1000
Doc fixes
Reviewed-by: TrustMe
commit 1d60528ced1f6818a60889d672089bfe4d2290bb
Author: Morten Sorvig <msorvig@trolltech.com>
Date: Mon Aug 3 15:57:44 2009 +0200
Fix spelling error.
commit e99794c1200515f18ffdd0bec9c143db46e009a1
Merge: 199db81 d65f893
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 09:24:14 2009 +0200
Merge branch 'master' into doccleanup
commit 199db8104a680f91451cf2c93d2d41077b5605bb
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Tue Aug 4 00:04:40 2009 +0200
Fix some headers.
commit e8f8193b951a9f9e4b6d309c44151c47b715e901
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Mon Aug 3 19:10:51 2009 +0200
Merge branch 'master' into doccleanup
commit a1e50f6619ff1a302dd1fefbcb6b0cd62a653e7d
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 3 19:06:16 2009 +0200
Group "getting started" documents into a walkthrough structure.
commit e393b4f458263cb2f011cc5e5e67cdcc48610ea9
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 3 17:35:15 2009 +0200
Add screenshots for example-overview page.
commit 8c84f307f73ab7b77a91e61ed18fdc685afebcc5
Merge: a16033a 34e272a
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Mon Aug 3 11:03:41 2009 +0200
Merge branch 'master' into doccleanup
commit a16033a287afe2f494401e24f02f046ec98d944c
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Sat Aug 1 22:39:27 2009 +0200
Cleanup the script-related groups a bit.
commit a66227d0bed87c633a22a4d155f6a7f0061fc34e
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Sat Aug 1 20:50:06 2009 +0200
One group of thread-related classes should be enough.
commit a2511650577126026f98cb7416c159498f6f2db5
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Sat Aug 1 12:04:55 2009 +0200
Merge branch 'master' into doccleanup
commit bad9ba5468333be2f08da7f28950c980bc63c787
Merge: 49f38b7 c57ed13
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 19:31:04 2009 +0200
Merge branch 'master' into doccleanup
commit 49f38b7afe3205eedccf655c0ad749d685cb3d52
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 18:37:53 2009 +0200
Consolidate style documentation.
commit 01c78ff78888d3ccb50189206b9bcacaf13f5c80
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 16:04:51 2009 +0200
Merge branch 'master' into doccleanup
commit da93c4ccc25dd189dfb9b71bda28bd1e3a7230c1
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 14:19:47 2009 +0200
Some final module cleaning up.
commit 9eb0815bbd01b7e30877110b53aa6f82b8e9221d
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 13:51:54 2009 +0200
Move remaining overview groups into one file.
commit 65d4c4145386a409aeb1372ae5adc6f3e71e444b
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 13:28:21 2009 +0200
Kill the group "misc".
commit 7b7484b37b074d52af5c4ff9b138087a75965508
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 13:08:37 2009 +0200
More moving of files and content.
commit 96a707d25342c273cdd7629fc1e24b0ead4118de
Merge: 4ffe572 18fbfdf
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 11:08:11 2009 +0200
Merge branch 'master' into doccleanup
commit 4ffe572a954e99d604c1360fc55db25e8586436c
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 02:03:07 2009 +0200
Workaround qdoc being difficult.
commit 7f0e965c7cf613782e8189069444a4b549f0c11a
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Fri Jul 31 01:49:52 2009 +0200
Some more moving of files into meaningful directories.
commit b0d67674469e57b29e60110888352ae955adcdd8
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Thu Jul 30 20:57:39 2009 +0200
Fix a few links.
commit 74027c3568c1bdbb9960d203266f4ccc5e89c05c
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Thu Jul 30 20:20:55 2009 +0200
Consolidate the two example documents into one page.
commit cfc0fd3df050cf6c0e3229d22adfbff35aed46af
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Thu Jul 30 18:23:55 2009 +0200
The new index page and respective style changes.
commit a3e4eb6712e24a4d6156c340ee98671887a2b2fa
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
Date: Thu Jul 30 17:05:46 2009 +0200
Deployment group is gone.
commit f03ee6192450db977bc2e4b07ffc613314b63a80
Author: Volker Hilsheimer <volker.hilsheimer@nokia.com>
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 <volker.hilsheimer@nokia.com>
Date: Thu Jul 30 16:47:20 2009 +0200
Cleaning up files documenting deployment. Text need to be reviewed and merged.
Diffstat (limited to 'doc/src/platforms')
35 files changed, 6139 insertions, 0 deletions
diff --git a/doc/src/platforms/atomic-operations.qdoc b/doc/src/platforms/atomic-operations.qdoc new file mode 100644 index 0000000..19fbea6 --- /dev/null +++ b/doc/src/platforms/atomic-operations.qdoc @@ -0,0 +1,90 @@ +/**************************************************************************** +** +** 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 + \brief A guide to implementing atomic operations on new architectures. + + \ingroup best-practices + \ingroup qt-embedded-linux + + 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 {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/platforms/compiler-notes.qdoc b/doc/src/platforms/compiler-notes.qdoc new file mode 100644 index 0000000..f4e9805 --- /dev/null +++ b/doc/src/platforms/compiler-notes.qdoc @@ -0,0 +1,278 @@ +/**************************************************************************** +** +** 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-specific + \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/platforms/emb-accel.qdoc b/doc/src/platforms/emb-accel.qdoc new file mode 100644 index 0000000..818538a --- /dev/null +++ b/doc/src/platforms/emb-accel.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 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/platforms/emb-architecture.qdoc b/doc/src/platforms/emb-architecture.qdoc new file mode 100644 index 0000000..06ffac6 --- /dev/null +++ b/doc/src/platforms/emb-architecture.qdoc @@ -0,0 +1,338 @@ +/**************************************************************************** +** +** 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-architecture.html + + \title Qt for Embedded Linux Architecture + \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 act as the server. + When more than one application is running, the subsequent + applications connect to the existing server application as clients. + + The server and client processes have different responsibilities: + The server process manages pointer handling, character input, and + screen output. In addition, the server controls the appearance of + the screen cursor and the screen saver. The client process + performs all application specific operations. + + The server application is represented by an instance of the + QWSServer class, while the client applications are represented by + instances of the QWSClient class. On each side, there are several + classes performing the various operations. + + \image qt-embedded-architecture2.png + + 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. But when the + hardware is known and well defined, as is often the case with + software for embedded devices, it may be useful for the clients to + manipulate and control the underlying hardware directly. + \l{Qt for Embedded Linux} provides two different approaches to + achieve this behavior, see the graphics rendering section below for + details. + + \tableofcontents + + \section1 Client/Server Communication + + The running applications continuously alter the appearance of the + screen by adding and removing widgets. The server maintains + information about each top-level window in a corresponding + QWSWindow object. + + Whenever the server receives an event, it queries its stack of + top-level windows to find the window containing the event's + position. Each window can identify the client application that + created it, and returns its ID to the server upon + request. Finally, the server forwards the event, encapsulated by + an instance of the QWSEvent class, to the appropriate client. + + \image qt-embedded-clientservercommunication.png + + If an input method is installed, it is used as a filter between + the server and the client application. Derive from the + QWSInputMethod class to implement custom input methods, and use + the server's \l {QWSServer::}{setCurrentInputMethod()} function to + install it. In addition, it is possible to implement global, + low-level filters on key events using the + QWSServer::KeyboardFilter class; this can be used to implement + things like advanced power management suspended from a button + without having to filter for it in all applications. + + \table 100% + \header \o UNIX Domain Socket + \row + \o + + \image qt-embedded-client.png + + The server communicates with the client applications over the UNIX + domain socket. You can retrieve direct access to all the events a + client receives from the server, by reimplementing QApplication's + \l {QApplication::}{qwsEventFilter()} function. + + \endtable + + The clients (and the server) communicate with each other using the + QCopChannel class. QCOP is a many-to-many communication protocol + for transferring messages on various channels. A channel is + identified by a name, and anyone who wants to can listen to + it. The QCOP protocol allows clients to communicate both within + the same address space and between different processes. + + \section1 Pointer Handling Layer + + \list + \o QWSMouseHandler + \o QMouseDriverPlugin + \o QMouseDriverFactory + \endlist + + The mouse driver (represented by an instance of the + QWSMouseHandler class) is loaded by the server application when it + starts running, using Qt's \l {How to Create Qt Plugins}{plugin + system}. + + \image qt-embedded-pointerhandlinglayer.png + + A mouse driver receives mouse events from the device and + encapsulates each event with an instance of the QWSEvent class + which it then passes to the server. + + \l{Qt for Embedded Linux} provides ready-made drivers for several mouse + protocols, see the \l{Qt for Embedded Linux Pointer Handling}{pointer + handling} documentation for details. Custom mouse drivers can be + implemented by subclassing the QWSMouseHandler class and creating + a mouse driver plugin. The default implementation of the + QMouseDriverFactory class will automatically detect the plugin, + loading the driver into the server application at runtime. + + In addition to the generic mouse handler, \l{Qt for Embedded Linux} + provides a calibrated mouse handler. Use the + QWSCalibratedMouseHandler class as the base class when the system + device does not have a fixed mapping between device and screen + coordinates and/or produces noisy events, e.g. a touchscreen. + + See also: \l{Qt for Embedded Linux Pointer Handling} and + \l{How to Create Qt Plugins}. + + \section1 Character Input Layer + + \list + \o QWSKeyboardHandler + \o QKbdDriverPlugin + \o QKbdDriverFactory + \endlist + + The keyboard driver (represented by an instance of the + QWSKeyboardHandler class) is loaded by the server application when + it starts running, using Qt's \l {How to Create Qt Plugins}{plugin + system}. + + \image qt-embedded-characterinputlayer.png + + A keyboard driver receives keyboard events from the device and + encapsulates each event with an instance of the QWSEvent class + which it then passes to the server. + + \l{Qt for Embedded Linux} provides ready-made drivers for several keyboard + protocols, see the \l {Qt for Embedded Linux Character Input}{character + input} documentation for details. Custom keyboard drivers can be + implemented by subclassing the QWSKeyboardHandler class and + creating a keyboard driver plugin. The default implementation of the + QKbdDriverFactory class will automatically detect the plugin, loading the + driver into the server application at run-time. + + See also: \l{Qt for Embedded Linux Character Input} and \l {How to Create + Qt Plugins}. + + \section1 Graphics Rendering + + \list + \o QApplication + \o QDecoration + \o QDecorationPlugin + \o QDecorationFactory + \endlist + + The default behavior is for each client to render its widgets as well + as its decorations into memory, while the server copies the memory content + to the device's framebuffer. + + Whenever a client receives an event that alters any of its + widgets, the application updates the relevant parts of its memory + buffer: + + \image qt-embedded-clientrendering.png + + The decoration is loaded by the client application when it starts + running (using Qt's \l {How to Create Qt Plugins}{plugin system}), + and can be customized by deriving from the QDecoration class and + creating a decoration plugin. The default implementation of + the QDecorationFactory class will automatically detect the plugin, + loading the decoration into the application at runtime. Call the + QApplication::qwsSetDecoration() function to actually apply the + given decoration to an application. + + \table 100% + \header \o Direct Painting \target Direct Painting + \row + \o + + It is possible for the clients to manipulate and control the + underlying hardware directly. There are two ways of achieving + this: 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. + + \image qt-embedded-setwindowattribute.png + + By setting the Qt::WA_PaintOnScreen attribute, the application + renders the widget directly onto the screen and the affected + region will not be modified by the screen driver \e unless another + window with a higher focus requests (parts of) the same + region. Note that if you want to render all of an application's + widgets directly on screen, it might be easier to set the + QT_ONSCREEN_PAINT environment variable. + + \image qt-embedded-reserveregion.png + + Using QDirectPainter, on the other hand, provides a complete + control over the reserved region, i.e., the screen driver will + never modify the given region. + + To draw on a region reserved by a QDirectPainter instance, the + application must get hold of a pointer to the framebuffer. In + general, a pointer to the framebuffer can be retrieved using the + QDirectPainter::frameBuffer() function. But note that if the + current screen has subscreens, you must query the screen driver + instead to identify the correct subscreen. A pointer to the + current screen driver can always be retrieved using the static + QScreen::instance() function. Then use QScreen's \l + {QScreen::}{subScreenIndexAt()} and \l {QScreen::}{subScreens()} + functions to access the correct subscreen, and the subscreen's \l + {QScreen::}{base()} function to retrieve a pointer to the + framebuffer. + + Note that \l{Qt for Embedded Linux} also provides the QWSEmbedWidget class, + making it possible to embed the reserved region (i.e., the + QDirectPainter object) in a regular widget. + + \endtable + + \section1 Drawing on Screen + + \list + \o QScreen + \o QScreenDriverPlugin + \o QScreenDriverFactory + \endlist + + When a screen update is required, the server runs through all the + top-level windows that intersect with the region that is about to + be updated, and ensures that the associated clients have updated + their memory buffer. Then the server uses the screen driver + (represented by an instance of the QScreen class) to copy the + content of the memory to the screen. + + The screen driver is loaded by the server application when it + starts running, using Qt's plugin system. \l{Qt for Embedded Linux} + provides ready-made drivers for several screen protocols, see the + \l{Qt for Embedded Linux Display Management}{display management} + documentation for details. Custom screen drivers can be + implemented by subclassing the QScreen class and creating a screen + driver plugin. The default implementation of the QScreenDriverFactory + class will automatically detect the plugin, loading the driver into + the server application at run-time. + + \image qt-embedded-drawingonscreen.png + + To locate the relevant parts of memory, the driver is provided + with the list of top-level windows that intersect with the given + region. Associated with each of the top-level windows there is an + instance of the QWSWindowSurface class representing the drawing + area of the window. The driver uses these objects to retrieve + pointers to the various memory blocks. Finally, the screen driver + composes the surface images before copying the updated region to + the framebuffer. + + \table 100% + \header \o Accelerated Graphics + \row + \o + + In \l{Qt for Embedded Linux}, painting is a pure software implementation, + but (starting with Qt 4.2) it is possible to add an accelerated + graphics driver to take advantage of available hardware resources. + + \image qt-embedded-accelerateddriver.png + + The clients render each window onto a corresponding window surface + object using Qt's paint system, and then store the surface in + memory. The screen driver accesses the memory and composes the + surface images before it copies them to the screen as explained + above. + + To add an accelerated graphics driver you must create a custom + screen and implement a custom raster paint engine + (\l{Qt for Embedded Linux} uses a raster-based paint engine to + implement the painting operations). Then you must create a custom + paint device that is aware of your paint engine, a custom window + surface that knows about your paint device, and make your screen + able to recognize your window surface. + + See the \l{Adding an Accelerated Graphics Driver to Qt for Embedded Linux} + {accelerated graphics driver} documentation for details. + + \endtable + + See also: \l{Qt for Embedded Linux Display Management} and + \l{How to Create Qt Plugins}. +*/ diff --git a/doc/src/platforms/emb-charinput.qdoc b/doc/src/platforms/emb-charinput.qdoc new file mode 100644 index 0000000..5ceb6a4 --- /dev/null +++ b/doc/src/platforms/emb-charinput.qdoc @@ -0,0 +1,164 @@ +/**************************************************************************** +** +** 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/platforms/emb-crosscompiling.qdoc b/doc/src/platforms/emb-crosscompiling.qdoc new file mode 100644 index 0000000..2e0ba4b --- /dev/null +++ b/doc/src/platforms/emb-crosscompiling.qdoc @@ -0,0 +1,191 @@ +/**************************************************************************** +** +** 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/platforms/emb-deployment.qdoc b/doc/src/platforms/emb-deployment.qdoc new file mode 100644 index 0000000..9a83dcf --- /dev/null +++ b/doc/src/platforms/emb-deployment.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** 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/platforms/emb-differences.qdoc b/doc/src/platforms/emb-differences.qdoc new file mode 100644 index 0000000..cf3ab75 --- /dev/null +++ b/doc/src/platforms/emb-differences.qdoc @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** 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/platforms/emb-displaymanagement.qdoc b/doc/src/platforms/emb-displaymanagement.qdoc new file mode 100644 index 0000000..8a743b1 --- /dev/null +++ b/doc/src/platforms/emb-displaymanagement.qdoc @@ -0,0 +1,205 @@ +/**************************************************************************** +** +** 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-displaymanagement.html + + \title Qt for Embedded Linux Display Management + \ingroup qt-embedded-linux + + When rendering, the default behavior for each Qt for Embedded Linux + client is to render its widgets into memory, while the server is + responsible for putting the contents of the memory onto the + screen. The server uses the screen driver to copy the content of + the memory to the display. + + The screen driver is loaded by the server application when it + starts running, using Qt's \l {How to Create Qt Plugins}{plugin + system}. + + Contents: + + \tableofcontents + + \section1 Available Drivers + + \l{Qt for Embedded Linux} provides drivers for the Linux framebuffer, the + virtual framebuffer, transformed screens, VNC servers and multi + screens. Run the \c configure script to list the available + drivers: + + \if defined(QTOPIA_DOCS) + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 0 + \else + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 1 + \endif + + \if defined(QTOPIA_DOCS) + In the default Qt Extended configuration, only an unaccelerated Linux + framebuffer driver (\c /dev/fb0) is enabled. The various drivers + can be enabled and disabled using the \c configure script. For + example: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 2 + \else + In the default Qt configuration, only an unaccelerated Linux + framebuffer driver (\c /dev/fb0) is enabled. The various drivers + can be enabled and disabled using the \c configure script. For + example: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 3 + \endif + + Custom screen drivers can be implemented by subclassing the + QScreen class and creating a screen driver plugin (derived from + the QScreenDriverPlugin class). The default implementation + of the QScreenDriverFactory class will automatically detect the + plugin, loading the driver into the server application at run-time. + + \section1 Specifying a Driver + + To specify which driver to use, set the QWS_DISPLAY environment + variable. For example (if the current shell is bash, ksh, zsh or + sh): + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 4 + + 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 table below. + + \table + \header + \o Driver Specific Option \o Available For \o Description + \row + \o \c tty=<device> + \o LinuxFb + \o Passes the device file to the console the application is + running on. + \row + \o \c nographicsmodeswitch + \o LinuxFb + \o Ensures that the application is not in graphics mode. + \row + \o \c littleendian + \o LinuxFb + \o Tells the driver it must handle a little-endian frame + buffer in a big-endian system. + \row + \o \c mmWidth=<value> \target mmWidth + \o LinuxFb, QVFb + \o The screen's physical width (used to calculate DPI). + \row + \o \c mmHeight=<value> \target mmHeight + \o LinuxFb, QVFb + \o The screen's physical height (used to calculate DPI). + \row + \o \c <device> + \o LinuxFb + \o + \row + \o \c <subdriver> + \o VNC, Transformed, Multi + \o Specifies a subdriver. + \row + \o \c <RotX> + \o Transformed + \o Specifies the rotation of the screen. The valid values of + \c X are 90, 180 and 270. + \row + \o \c offset=<x,y> + \o Multi + \o Specifies the coordinates of a subscreens top-left corner + (by default 0,0). + + \endtable + + The QWS_DISPLAY environment variable can also be set using the \c + -display option when running an application. For example: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 5 + + \section1 Subdrivers and Multiple Drivers + + The VNC, Transformed and Multi screen drivers depend on + subdrivers. The general syntax for specifying a driver is as + follows: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 6 + + In the case of subdrivers, it is important to add a space between + each subdriver and before the display number to separate the + various drivers and displays. Note that \c Multi screen drivers + can have several subdrivers. For example: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 7 + + Note also that the VNC screen driver defaults to a virtual screen + driver if no subdriver is specified. In this case the VNC driver accepts a + few additional (optional) arguments specifying the size and depth + of the default virtual screen: + + \list + \o \c {size=<width x height>} + \o \c {depth=<value>} + \o \c {mmHeight=<physical height in millimeters>} + \o \c {mmWidth=<physical width in millimeters>} + \endlist + + Example running the VNC screen driver with a virtual screen of size + 720x480 with 32 bits per pixel: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 8 + + Example running the VNC screen driver on top of the Linux framebuffer + driver: + + \snippet doc/src/snippets/code/doc_src_qt-embedded-displaymanagement.qdoc 9 + + In this last example, Qt is using two screen drivers simultaneously, + displaying output on both the device's screen and across a network on + VNC client displays. +*/ diff --git a/doc/src/platforms/emb-envvars.qdoc b/doc/src/platforms/emb-envvars.qdoc new file mode 100644 index 0000000..c423fef --- /dev/null +++ b/doc/src/platforms/emb-envvars.qdoc @@ -0,0 +1,168 @@ +/**************************************************************************** +** +** 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/platforms/emb-features.qdoc b/doc/src/platforms/emb-features.qdoc new file mode 100644 index 0000000..fdd2e46 --- /dev/null +++ b/doc/src/platforms/emb-features.qdoc @@ -0,0 +1,147 @@ +/**************************************************************************** +** +** 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/platforms/emb-fonts.qdoc b/doc/src/platforms/emb-fonts.qdoc new file mode 100644 index 0000000..70fddbf --- /dev/null +++ b/doc/src/platforms/emb-fonts.qdoc @@ -0,0 +1,201 @@ +/**************************************************************************** +** +** 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/platforms/emb-framebuffer-howto.qdoc b/doc/src/platforms/emb-framebuffer-howto.qdoc new file mode 100644 index 0000000..14400c2 --- /dev/null +++ b/doc/src/platforms/emb-framebuffer-howto.qdoc @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** 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/platforms/emb-install.qdoc b/doc/src/platforms/emb-install.qdoc new file mode 100644 index 0000000..e23cc1b --- /dev/null +++ b/doc/src/platforms/emb-install.qdoc @@ -0,0 +1,197 @@ +/**************************************************************************** +** +** 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/platforms/emb-kmap2qmap.qdoc b/doc/src/platforms/emb-kmap2qmap.qdoc new file mode 100644 index 0000000..291a553 --- /dev/null +++ b/doc/src/platforms/emb-kmap2qmap.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$ +** +****************************************************************************/ + +/*! + \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/platforms/emb-makeqpf.qdoc b/doc/src/platforms/emb-makeqpf.qdoc new file mode 100644 index 0000000..dc1196a --- /dev/null +++ b/doc/src/platforms/emb-makeqpf.qdoc @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** 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/platforms/emb-opengl.qdoc b/doc/src/platforms/emb-opengl.qdoc new file mode 100644 index 0000000..e61ccde --- /dev/null +++ b/doc/src/platforms/emb-opengl.qdoc @@ -0,0 +1,227 @@ +/**************************************************************************** +** +** 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-opengl.html + +\title Qt for Embedded Linux and OpenGL +\ingroup qt-embedded-linux + +\section1 Introduction + +\l {http://www.opengl.org}{OpenGL} is an industry standard API for +2D/3D graphics. It provides a powerful, low-level interface between +software and acceleration hardware, and it is operating system and +window system independent. + +\l {http://www.khronos.org/opengles}{OpenGL ES} is a subset +of the \l {http://www.opengl.org}{OpenGL} standard. +Because it is meant for use in embedded systems, it has a smaller, +more constrained API. + +For reference, Nokia provides a plugin which integrates \l +{http://www.khronos.org/opengles}{OpenGL ES} with Qt for Embedded Linux, +but Qt for Embedded Linux can be adapted to a wide range of OpenGL +versions. + +There are three ways to use OpenGL with Qt for Embedded Linux: +\list + \o Perform OpenGL 3D graphics operations in applications; + \o Accelerate normal 2D painting operations; + \o Implement window compositing and special effects. +\endlist + +Qt for Embedded Linux is shipped with a reference integration example +that demonstrates all three uses. + +\section2 Using OpenGL 3D Graphics in Applications + +The \l {QtOpenGL module} offers classes that make it easy to draw 3D +graphics in GUI applications. The module API is cross-platform, so it +is also available on Windows, X11, and Mac OS X. + +To use OpenGL-enabled widgets in a Qt for Embedded Linux application, +all that is required is to subclass the QGLWidget and draw into instances of +the subclass with standard OpenGL functions. + +\section2 Using OpenGL to Accelerate Normal 2D Painting + +Qt provides QOpenGLPaintEngine, a subclass of QPaintEngine that +translates QPainter operations into OpenGL calls. This specialized +paint engine can be used to improve 2D rendering performance on +appropriate hardware. It can also overlay controls and decorations +onto 3D scenes drawn using OpenGL. + +\section2 Using OpenGL to Implement Window Compositing and Effects + +Qt for Embedded Linux includes a complete windowing system, which implements +real transparency. The windowing system can be accelerated using +OpenGL to implement top level window compositing. This makes it easy +to add 3D effects to applications, for instance when windows are +minimized or maximized. + +\section1 Acceleration Architecture + +The diagram below shows the Qt for Embedded Linux painting architecture. + +\image qt-embedded-opengl3.png + +A client process widget uses a paint engine to draw into a window +surface. The server then combines the window surfaces and displays the +composition on the screen. This architecture lets you +control the steps of the painting process by subclassing. + +Subclassing QPaintEngine allows you to implement the QPainter API +using accelerated hardware. Subclassing QWindowSurface lets you +decide the properties of the space your widgets will draw themselves +into, as well as which paint engine they should use to draw themselves +into that space. Subclassing QScreen lets you control the creation of +window surfaces and lets you decide how to implement window +compositing. Using subclassing, your implementation work is minimized +since you can reuse base class functionality you don't need to change. + +The elements of an accelerated Qt for Embedded Linux system are shown in the +diagram below. + +\image qt-embedded-opengl1.png + +The applications, using the Qt API, do not depend on the presence of +the acceleration plugin. The plugin uses the graphics hardware to +accelerate painting primitives. Any operations not accelerated by the +plugin are done in software by the software paint engine. + +To integrate an OpenGL implementation into Qt for Embedded Linux for a +particular platform, you use the same mechanisms you would use for +writing any other accelerated driver. Base classes, e.g., QGLScreen +and QWSGLWindowSurface, are provided to minimize the need for +reimplementing common functionality. + +\section1 The Reference Integration + +The \l{OpenGL for Embedded Systems Example} is the reference implementation +for integrating OpenGL ES and \l{http://www.khronos.org/egl/}{EGL} with +the graphics acceleration architecture of Qt for Embedded Linux. +(\l{http://www.khronos.org/egl/}{EGL} is a library that binds OpenGL ES to +native windowing systems.) + +The diagram below shows how OpenGL ES is used within the acceleration architecture: + +\image qt-embedded-opengl2.png + +The example implements a screen driver plugin that demonstrates all +three uses of OpenGL in Qt for Embedded Linux: 2D graphics acceleration, 3D +graphics operations using the \l {QtOpenGL module}, and top-level +window compositing and special effects. The applications still do +not talk directly to the accelerated plugin. + +For 2D graphics, applications use the normal Qt painting API. The example accelerates 2D +painting by using the QOpenGLPaintEngine, which is included in the \l {QtOpenGL module}. + +For 3D graphics applications use the OpenGL API directly, together with the functionality +in the Qt OpenGL support classes. The example supports this by creating a +QWSGLWindowSurface whenever a QGLWidget is instantiated. + +All access to the display is done through OpenGL. The example subclasses +QWSGLWindowSurface implementation and uses the \l +{http://oss.sgi.com/projects/ogl-sample/registry/EXT/framebuffer_object.txt} +{OpenGL Framebuffer Object extension} to draw windows into an offscreen buffer. This +lets the example use OpenGL to implement top level window compositing of opaque and +semi-transparent windows, and to provide a 3D animated transition effect as each new +window is shown. + +The specific OpenGL library being used by the example restricts all +OpenGL operations to occur in a single process. Hence the example +creates instances of QWSGLWindowSurface only in the server process. +Other processes then perform 2D graphics by creating instances +of the standard QWindowSurface classes for client processes. The +standard window surface performs software-based rendering into a +shared memory segment. The server then transfers the contents of this +shared memory into an OpenGL texture before they are drawn onto the +screen during window compositing. + +\omit + +\section1 Future Directions + +\section2 API Improvements + +Nokia is now working on enhancing the API for integrating OpenGL +with Qt for Embedded Linux. The current design plan includes the following +features: + +\list + + \o Provide convenience classes, e.g., QEGLScreen and + QWSEGLWindowSurface, which implement common uses of the EGL + API. These classes will simplify implementing an OpenGL ES + integration. + + \o Extend the screen driver API to provide more control over window + properties and animations, and provide a software-based integration + to enable testing on the desktop. + + \o Improve performance as opportunities arise. + +\endlist + +\section2 OpenVG Support + +\l {http://www.khronos.org/openvg} {OpenVG} is a dedicated API for 2D +graphics on mobile devices. It is therefore more likely to be a better +alternative for 2D acceleration than OpenGL. Until recently, no +OpenVG-capable hardware has been available, so Nokia has not yet +included an OpenVG solution in Qt for Embedded Linux. + +However, Nokia has done a feasibility study, implementing an +OpenVG paint engine on top of a software OpenVG implementation. +Assuming availability of the appropriate hardware, this OpenVG paint +engine can easily be completed and integrated using the existing +acceleration architecture. Since OpenVG shares the same EGL layer as +OpenGL ES, the work already done on the OpenGL integration can be +reused. + +Related technologies included in the \l +{http://www.khronos.org/openkode} {OpenKODE} API set will also be +considered. + +\endomit + +*/ diff --git a/doc/src/platforms/emb-performance.qdoc b/doc/src/platforms/emb-performance.qdoc new file mode 100644 index 0000000..9bc373b --- /dev/null +++ b/doc/src/platforms/emb-performance.qdoc @@ -0,0 +1,152 @@ +/**************************************************************************** +** +** 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/platforms/emb-pointer.qdoc b/doc/src/platforms/emb-pointer.qdoc new file mode 100644 index 0000000..39a8482 --- /dev/null +++ b/doc/src/platforms/emb-pointer.qdoc @@ -0,0 +1,209 @@ +/**************************************************************************** +** +** 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/platforms/emb-porting.qdoc b/doc/src/platforms/emb-porting.qdoc new file mode 100644 index 0000000..1afd1be --- /dev/null +++ b/doc/src/platforms/emb-porting.qdoc @@ -0,0 +1,193 @@ +/**************************************************************************** +** +** 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/platforms/emb-qvfb.qdoc b/doc/src/platforms/emb-qvfb.qdoc new file mode 100644 index 0000000..48e0d35 --- /dev/null +++ b/doc/src/platforms/emb-qvfb.qdoc @@ -0,0 +1,296 @@ +/**************************************************************************** +** +** 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/platforms/emb-running.qdoc b/doc/src/platforms/emb-running.qdoc new file mode 100644 index 0000000..cb7a7ae --- /dev/null +++ b/doc/src/platforms/emb-running.qdoc @@ -0,0 +1,210 @@ +/**************************************************************************** +** +** 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/platforms/emb-vnc.qdoc b/doc/src/platforms/emb-vnc.qdoc new file mode 100644 index 0000000..c8289f8 --- /dev/null +++ b/doc/src/platforms/emb-vnc.qdoc @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** 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/platforms/mac-differences.qdoc b/doc/src/platforms/mac-differences.qdoc new file mode 100644 index 0000000..b911510 --- /dev/null +++ b/doc/src/platforms/mac-differences.qdoc @@ -0,0 +1,339 @@ +/**************************************************************************** +** +** 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 mac-differences.html + \title Qt for Mac OS X - Specific Issues + \brief A description of issues with Qt that are specific to Mac OS X. + \ingroup platform-specific + + This file outlines known issues and possible workarounds when + using Qt on Mac OS X. Contact Qt's technical support team if you find + additional issues which are not covered here. (See also the + document \l{qtmac-as-native.html} {Qt is Mac OS X Native}.) + + \tableofcontents + + \section1 GUI Applications + + Mac OS X handles most applications as "bundles". A bundle is a + directory structure that groups related files together (e.g., + widgets.app/). GUI applications in particular must be run from a + bundle or by using the open(1), because Mac OS X needs the bundle + to dispatch events correctly, as well as for accessing the menu + bar. + + If you are using older versions of GDB you must run with the full + path to the executable. Later versions allow you to pass the + bundle name on the command line. + + \section1 Painting + + Mac OS X always double buffers the screen so the + Qt::WA_PaintOnScreen attribute has no effect. Also it is + impossible to paint outside of a paint event so + Qt::WA_PaintOutsidePaintEvent has no effect either. + + \section1 Library Support + + \section2 Qt libraries as frameworks + + By default, Qt is built as a set of frameworks. Frameworks is the + Mac OS X "preferred" way of distributing libraries. There are + definite advantages to using them. See + \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html} + {Apple's Framework Programming Guide} for more information. + + In general, this shouldn't be an issue because qmake takes care of + the specifics for you. The + \l{http://developer.apple.com/documentation/MacOSX/Conceptual/BPFrameworks/index.html} + {Framework Programming Guide} discusses issues to keep in mind + when choosing frameworks over the more typical, dynamic libraries. + However, one point to remember is: \bold {Frameworks always link + with "release" versions of libraries}. + + If you actually want to use a \e{debug} version of a Qt framework, + you must ensure that your application actually loads that debug + version. This is often done by using the DYLD_IMAGE_SUFFIX + environment variables, but that way often doesn't work so well. + Instead, you can temporarily swap your debug and release versions, + which is documented in + \l{http://developer.apple.com/technotes/tn2004/tn2124.html#SECJUSTONELIB} + {Apple's "Debugging Magic" technical note}. + + If you don't want to use frameworks, simply configure Qt with + \c{-no-framework}. + + \section2 Bundle-Based Libraries + + If you want to use some dynamic libraries in your Mac OS X + application bundle (the application directory), create a + subdirectory named "Frameworks" in the application bundle + directory and place your dynamic libraries there. The application + will find a dynamic library if it has the install name + \e{@executable_path/../Frameworks/libname.dylib}. + + If you use \c qmake and Makefiles, use the \c QMAKE_LFLAGS_SONAME setting: + + \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 0 + + Alternatively, you can modify the install name using the + install_name_tool(1) on the command line. See its manpage for more + information. + + Note that the \c DYLD_LIBRARY_PATH environment variable will + override these settings, and any other default paths, such as a + lookup of dynamic libraries inside \c /usr/lib and similar default + locations. + + \section2 Combining Libraries + + If you want to build a new dynamic library combining the Qt 4 + dynamic libraries, you need to introduce the \c{ld -r} flag. Then + relocation information is stored in the output file, so that + this file could be the subject of another \c ld run. This is done + by setting the \c -r flag in the \c .pro file, and the \c LFLAGS + settings. + + \section2 Initialization Order + + dyld(1) calls global static initializers in the order they are + linked into your application. If a library links against Qt and + references globals in Qt (from global initializers in your own + library), be sure to link your application against Qt before + linking it against the library. Otherwise the result will be + undefined because Qt's global initializers have not been called + yet. + + \section1 Compile-Time Flags + + The follewing flags are helpful when you want to define Mac OS X specific + code: + + \list + + \o Q_OS_DARWIN is defined when Qt detects you are on a + Darwin-based system (including the Open Source version) + + \o Q_WS_MAC is defined when the Mac OS X GUI is present. + + \o QT_MAC_USE_COCOA is defined when Qt is built to use the Cocoa framework. + If it is not present, then Qt is using Carbon. + + \endlist + + A additional flag, Q_OS_MAC, is defined as a convenience whenever + Q_OS_DARWIN is defined. + + If you want to define code for specific versions of Mac OS X, use + the availability macros defined in /usr/include/AvailabilityMacros.h. + + See QSysInfo for information on runtime version checking. + + \section1 Mac OS X Native API Access + + \section2 Accessing the Bundle Path + + The Mac OS X application is actually a directory (ending with \c + .app). This directory contains sub-directories and files. It may + be useful to place items (e.g. plugins, online-documentation, + etc.) inside this bundle. You might then want to find out where + the bundle resides on the disk. The following code returns the + path of the application bundle: + + \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 1 + + Note: When OS X is set to use Japanese, a bug causes this sequence + to fail and return an empty string. Therefore, always test the + returned string. + + For more information about using the CFBundle API, see + \l{http://developer.apple.com/documentation/CoreFoundation/Reference/CFBundleRef/index.html} + {Apple's Developer Website}. + + \section2 Translating the Application Menu and Native Dialogs + + The items in the Application Menu will be merged correctly for + your localized application, but they will not show up translated + until you + \l{http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFBundles/Concepts/BundleAnatomy.html#//apple_ref/doc/uid/20001119-105003-BAJFDAAG} + {add a localized resource folder} to the application bundle. + The main thing you need to do is create a file called + locversion.plist. Here is an example for Norwegian: + + \snippet doc/src/snippets/code/doc_src_mac-differences.qdoc 2 + + Now when you run the application with your preferred language set + to Norwegian, you should see menu items like "Avslutt" instead of + "Quit". + + \section1 User Interface + + \section2 Right-Mouse Clicks + + If you want to provide right-mouse click support for Mac OS X, use + the QContextMenuEvent class. This will map to a context menu + event, i.e., a menu that will display a pop-up selection. This is + the most common use of right-mouse clicks, and maps to a + control-click with the Mac OS X one-button mouse support. + + \section2 Menu Bar + + Qt will automatically detect your menu bars for you and turn + them into Mac native menu bars. Fitting this into your existing Qt + application will normally be automatic. However, if you have + special needs, the Qt implementation currently selects a menu + bar by starting at the active window + (i.e. QApplication::activeWindow()) and applying the following + tests: + + \list 1 + + \i If the window has a QMenuBar, then it is used. + + \i If the window is modal, then its menu bar is used. If no menu + bar is specified, then a default menu bar is used (as + documented below). + + \i If the window has no parent, then the default menu bar is used + (as documented below). + + \endlist + + These tests are followed all the way up the parent window chain + until one of the above rules is satisifed. If all else fails, a + default menu bar will be created. Note the default menu bar on + Qt is an empty menu bar. However, you can create a different + default menu bar by creating a parentless QMenuBar. The first one + created will be designated the default menu bar and will be used + whenever a default menu bar is needed. + + Note that using native menu bars introduces certain limitations on + Qt classes. See the \l{#Limitations}{list of limitations} below + for more information about these. + + \section2 Special Keys + + To provide the expected behavior for Qt applications on Mac OS X, + the Qt::Meta, Qt::MetaModifier, and Qt::META enum values + correspond to the Control keys on the standard Macintosh keyboard, + and the Qt::Control, Qt::ControlModifier, and Qt::CTRL enum values + correspond to the Command keys. + + \section1 Limitations + + \section2 Menu Actions + + \list + + \o Actions in a QMenu with accelerators that have more than one + keystroke (QKeySequence) will not display correctly, when the + QMenu is translated into a Mac native menu bar. The first key + will be displayed. However, the shortcut will still be + activated as on all other platforms. + + \o QMenu objects used in the native menu bar are not able to + handle Qt events via the normal event handlers. + For Carbon, you will have to install a Carbon event handler on + the menu bar in order to receive Carbon events that are similar + to \l{QMenu::}{showEvent()}, \l{QMenu::}{hideEvent()}, and + \l{QMenu::}{mouseMoveEvent()}. For Cocoa, you will have to + install a delegate on the menu itself to be notified of these + changes. Alternatively, consider using the QMenu::aboutToShow() + and QMenu::aboutToHide() signals to keep track of menu visibility; + these provide a solution that should work on all platforms + supported by Qt. + + \endlist + + \section2 Native Widgets + + Qt has support for sheets and drawers, represented in the + window flags by Qt::Sheet and Qt::Drawer respectiviely. Brushed + metal windows can also be created by using the + Qt::WA_MacMetalStyle window attribute. + +*/ + +/*! + \page qt-mac-cocoa-licensing.html + + \title Contributions to the Following QtGui Files: qapplication_cocoa_p.h, qapplication_mac.mm, qdesktopwidget_mac.mm qeventdispatcher_mac.mm qeventdispatcher_mac_p.h qmacincludes_mac.h qt_cocoa_helpers.mm qt_cocoa_helpers_p.h qwidget_mac.mm qsystemtrayicon_mac.mm + + \contentspage {Other Licenses Used in Qt}{Contents} + + \ingroup licensing + \brief License information for contributions by Apple, Inc. to specific parts of the Qt/Mac Cocoa port. + + \legalese + + Copyright (C) 2007-2008, Apple, 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 + \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. + \o Neither the name of Apple, Inc. nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + \endlist + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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/platforms/platform-notes-rtos.qdoc b/doc/src/platforms/platform-notes-rtos.qdoc new file mode 100644 index 0000000..8a52d84 --- /dev/null +++ b/doc/src/platforms/platform-notes-rtos.qdoc @@ -0,0 +1,220 @@ +/*! + \page platform-notes-vxworks.html + \title Platform Notes - VxWorks + \contentspage Platform Notes + \target VxWorks + + \note VxWorks is a community supported platform. See the + \l{Supported Platforms} page for more information. + + This page contains information about the Qt for VxWorks port. More + information about the combinations of platforms and compilers supported + by Qt can be found on the \l{Supported Platforms} page. + + \tableofcontents + + \section1 Supported Versions + + Qt has been tested on WindRiver VxWorks 6.7 in kernel mode using the + vendor supplied GCC compiler, targetting both the x86 simulator + (simpentium) and Power-PC devices (ppc). + VxWorks' RTP mode is currently not supported. + + \section1 Limitations + + The VxWorks kernel has an optional POSIX compatibility layer, but this + layer does not implement all POSIX functionality needed for a complete + Qt port. + + \table + \header \o Function \o Notes + \row \o QProcess + \o Not available - VxWorks has no concept of processes. + \row \o QSharedMemory + \o Not available - VxWorks has only a global, flat address space. + \row \o QSystemSemaphore + \o Not available - VxWorks has no concept of processes. + \row \o QLibrary + \o QLibrary is only a small stub to make it possible to build + static plugins. + \row \o QCoreApplication + \o Can only be instantiated once. Qt's Q(CoreE)Application is + tightly coupled to one address space and process, while VxWorks + only supports one global address space and has no concept of + processes. + \row \o Phonon + \o There is no standard audio backend, which could be integrated into Phonon. + \row \o Qt3Support + \o The Qt3Support library is not available on QNX. + + \endtable + + \section1 Build Instructions + + Qt for VxWorks needs to be \l{Cross-Compiling Qt for Embedded Linux + Applications}{cross-compiled} on a Linux host. \c configure and \c make + the build like you would with a standard \l{Cross-Compiling Qt for + Embedded Linux Applications}{embedded Linux cross build}. Building the + VxWorks simulator would be done like this: + + \code + <path/to/qt/sources>/configure -xplatform unsupported/vxworks-simpentium-g++ -embedded vxworks -exceptions -no-gfx-linuxfb -no-mouse-linuxtp -no-mouse-pc -no-kbd-tty + make + \endcode + + \list + \o \c{-xplatform unsupported/qws/vxworks-simpentium-g++} - selects the x86 simulator mkspec for VxWorks + \o \c{-embedded vxworks} - builds the embedded version of Qt and sets the architecture to VxWorks + \o \c{-exceptions} - see General Notes below + \o \c{-no-gfx-linuxfb}, \c{-no-mouse-linuxtp}, \c{-no-mouse-pc} and \c{-no-kbd-tty} are Linux specific and won't work on VxWorks + \endlist + + \section1 General Notes + + \list + + \o Configuring with \c{-exceptions} is necessary, because the VxWorks + 6.7 g++ headers require exceptions to be enabled when compiling C++ + code. + + \o Configure's \c{-xplatform} can be any of + \c{unsupported/vxworks-(simpentium|ppc)-(g++|dcc)}, but \c{dcc} + (WindRiver DIAB compiler) has not yet tested been tested with Qt 4.6 and + VxWorks 6.7. + + \o Building shared libraries with \c{-shared} (the default) doesn't + really build shared libraries, like e.g. on Linux, since these are not + supported by VxWorks. Instead, qmake will created partially linked + objects, that can be loaded at runtime with \c{ld}. + + \o Creating static builds with \c{-static} is fully supported. + + \o "Munching" (generating constructors/destructors for static C++ + objects) is done automatically by a special qmake extension (for both + shared libraries and executables) + + \o VxWorks does not have a file system layer, but the low level storage + drivers have to supply a file system like interface to the applications. + Since each driver implements a different subset of the functionality + supported by this interface, Qt's file system auto-tests show wildly + differing results running on different "file systems". The best results + can be achieved when running on a (writable) NFS mount, since that + provides the most Unix-ish interface. The worst results come from the + FTP file system driver, which may crash when accessed by a + \c{QFileInfo}. + + \o Keep in mind that VxWorks doesn't call your \c{main()} function with + the standard \c{argc}/\c{argv} parameters. So either add a special + \c{vxmain()} function or use a tool like \c{callmain} to translate + VxWorks' commandline arguments to an \c{argc}/\c{argv} array. + + \o Some example will fail to build, due to some missing dependencies + (e.g. shared memory) - this will be fixed in a later release. + + \endlist +*/ + +/*! + \page platform-notes-qnx.html + \title Platform Notes - QNX + \contentspage Platform Notes + \target QNX + + \note QNX is a community supported platform. See the + \l{Supported Platforms} page for more information. + + This page contains information about the Qt for QNX port. More + information about the combinations of platforms and compilers supported + by Qt can be found on the \l{Supported Platforms} page. + + Note that Qt for QNX is currently based on \l{Qt for Embedded Linux}, which + contains its own windowing system. Mixing QNX's Photon environment with + Qt for QNX is currently not possible. Building Qt for QNX with Photon's + X11 embedded server is not recommended due to missing support for X11 extensions, + resulting in poor rendering quality. + + Qt for QNX contains experimental screen and input drivers based on QNX's + \c devi-hid and \c io-display. For more information, check the class documentation + for QQnxScreen, QWSQnxKeyboardHandler and QQnxMouseHandler. See the + \l{Porting Qt for Embedded Linux to a New Architecture} document for information + on how to add custom screen or input drivers. + + \tableofcontents + + \section1 Supported Versions + + Qt has been tested on QNX 6.4 on i386 and PowerPC targets with QNX's default + gcc compiler. + + \section1 Limitations + + Some of Qt's functionality is currently not available on QNX: + + \table + \header \o Function \o Notes + \row \o QProcess + \o Not available - QNX doesn't support mixing threads and processes. + \row \o QSharedMemory + \o Not available - QNX doesn't support SYSV style shared memory. + \row \o QSystemSemaphore + \o Not available - QNX doesn't support SYSV style system semaphores. + \row \o QWS Multi Process + \o QT_NO_QWS_MULTIPROCESS is always on due to missing shared memory support. + \row \o Phonon + \o There is no standard audio backend, which could be integrated into Phonon. + \row \o Qt3Support + \o The Qt3Support library is not available on QNX. + \endtable + + \section1 Build Instructions + + Qt for QNX needs to be built either on a QNX system, or \l{Cross-Compiling Qt + for Embedded Linux Applications}{cross-compiled} on a Linux host. In either + case, The QNX Software Development Platform must be installed. + + Example configure line for cross-compiling Qt for QNX on a Linux host for an + i386 QNX target: + + \code + configure -xplatform unsupported/qws/qnx-i386-g++ -embedded i386 -no-gfx-linuxfb -no-mouse-linuxtp -no-kbd-tty -no-qt3support -qt-gfx-qnx -qt-mouse-qnx -qt-kbd-qnx -no-exceptions + \endcode + + \list + \o \c{-xplatform unsupported/qws/qnx-i386-g++} - selects the i386-g++ mkspec for QNX + \o \c{-embedded i386} - builds the embedded version of Qt and sets the architecture to i386 + \o \c{-no-gfx-linuxfb}, \c{-no-mouse-linuxtp} and \c{-no-kbd-tty} are Linux specific and won't work on QNX + \o \c{-no-qt3support} - required since the Qt3 support classes are not supported on QNX + \o \c{-no-exceptions} - reduces the size of the library by disabling exception support + \o \c{-qt-gfx-qnx} - enables the experimental \c{io-graphics} based display driver + \o \c{-qt-mouse-qnx} - enables the experimental \c{devi-hig} based mouse driver + \o \c{-qt-kbd-qnx} - enables the experimental \c{devi-hig} based keyboard driver + \endlist + + \section1 General Notes + + \list + \o To enable the experimental QNX display and input drivers, \c{io-display} needs to be + up and running. The \c devi-hid based Qt input drivers require \c devi-hid to run + in resource mode without Photon support. To enable a standard mouse and keyboard + combination, run \c devi-hid as follows: \c{/usr/photon/bin/devi-hid -Pr kbd mouse}. + Note that your current shell will not accept keyboard and mouse input anymore after + running that command, so run it either from a script that launches a Qt application + afterwards, or make sure to have remote login available to launch a Qt application. + In addition, the \c QWS_DISPLAY, \c QWS_MOUSE_PROTO and \c QWS_KEYBOARD environment + variables should all be set to \c{qnx} before running a Qt application. + + \o The 3rd party TIFF library currently doesn't build due to the missing \c inflateSync + symbol from QNX's \c{libz.so.2}. Workarounds would be to manually replace QNX's libz + with a newer version, or disable the TIFF plugin entierly by appending + \c{QT_CONFIG += no-tiff} to \c{.qmake.cache} after configuring Qt. + + \o Some of the tools, examples and demos do not compile due to dependencies on QProcess + or other classes that are not available on QNX. + \endlist + + \section1 Platform Regressions + + Qt for QNX's behavior is mostly identical with \l{Qt for Embedded Linux}. However, + some regressions were spotted in QDateTime computation around year 0 and year 1970, + which have been tracked back to faulty time zone data on some QNX versions. +*/ diff --git a/doc/src/platforms/platform-notes.qdoc b/doc/src/platforms/platform-notes.qdoc new file mode 100644 index 0000000..20f0933 --- /dev/null +++ b/doc/src/platforms/platform-notes.qdoc @@ -0,0 +1,412 @@ +/**************************************************************************** +** +** 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 platform-specific + \title Platform-Specific Documentation + \brief Documents describing platform-specific features of Qt. + + These documents describe platform-specific features provided by Qt, and + discuss issues related to particular platforms and environments. + + \generatelist{related} +*/ + +/*! + \page platform-notes.html + \ingroup platform-specific + \title Platform Notes + \brief Information about the platforms on which Qt can be used. + + This page contains information about the platforms Qt is currently known + to run on, with links to platform-specific notes, including any known bugs + or incompatibilities. + + \list + \o \l{Platform Notes - X11} + \tableofcontents{1 Platform Notes - X11} + \o \l{Platform Notes - Windows} + \tableofcontents{1 Platform Notes - Windows} + \o \l{Platform Notes - Mac OS X} + \tableofcontents{1 Platform Notes - Mac OS X} + \o \l{Platform Notes - Embedded Linux} + \tableofcontents{1 Platform Notes - Embedded Linux} + \o \l{Platform Notes - Windows CE} + \tableofcontents{1 Platform Notes - Windows CE} + \o \l{Platform Notes - QNX} + \tableofcontents{1 Platform Notes - QNX} + \o \l{Platform Notes - VxWorks} + \tableofcontents{1 Platform Notes - VxWorks} + \endlist + + See also the \l{Compiler Notes} for information about compiler-specific + build issues. Information about the combinations of platforms and compilers + supported by Qt can be found on the \l{Supported Platforms} page. + + 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}. +*/ + +/*! + \page platform-notes-x11.html + \title Platform Notes - X11 + \contentspage Platform Notes + + This page contains information about the X11 platforms Qt is currently + known to run on, with links to platform-specific notes. More information + about the combinations of platforms and compilers supported by Qt can be + found on the \l{Supported Platforms} page. + + \tableofcontents + + \target AIX + \section1 AIX - 5.2 + + Qt has been tested on AIX 5.2, using the + \l{Compiler Notes#IBM xlC (AIX)}{xlC} compiler. + + \table + \header \o Compiler \o Notes + \row \o xlC + \o If Qt is built correctly but all symbols are reported to be missing + when you link an application, your makeC++SharedLib script might be out + of date. Make sure you have the latest version from the + \l{http://www-306.ibm.com/software/awdtools/vacpp/support/}{IBM website}. + \row \o GCC + \o We have tested earlier versions of Qt 4 successfully with GCC version + 3.3 and above. Some versions of GCC may fail to link Qt with a "TOC overflow" + message. + Fix this by upgrading to the latest maintenance release of the dynamic + linker. On AIX this is bos.rte.bind_cmds.4.1.5.3 or later. + Some versions of GCC may fail to build Qt with STL and large-file support + enabled, due to + \l{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=9551}{a bug in GCC}. + Fix this by upgrading to the latest maintenance release of the compiler. + It is also possible to work around this problem by running configure with + either \c{-no-stl} or \c{-no-largefile}. + \endtable + + \target FreeBSD + \section1 FreeBSD - 6.0-RELEASE + + \note FreeBSD is a community supported platform. See the + \l{Supported Platforms} page for more information. + + The system compiler on FreeBSD 4.x is gcc 2.95.4, which is not + officially supported by Qt 4. We develop using and recommend + ports/lang/gcc34. You will need to run configure with the + \c{-platform freebsd-g++34} arguments. Optionally, you may use + ports/lang/icc. + + The system compiler on FreeBSD 5.x and 6.x is GCC 3.4.4, which should be + sufficient to build Qt. You do not need to add any special arguments when + running configure. Optionally, you may use ports/lang/icc. + + Note that we do not actively test FreeBSD 4.x and 5.x. Our developers + migrated to 6.x after the Qt 4 launch. FreeBSD-CURRENT is not supported. + + \target HP-UX + \section1 HP-UX + + Qt supports HP-UX on both PA-RISC and the Itanium (IA64) architectures. + + \section2 PA-RISC - B.11.11 or later + + You can configure Qt for aCC in 32 and 64 bit mode (hpux-acc-64 or + hpux-acc-32), or gcc in 32 bit mode (hpux-g++). The default platform is + hpux-acc-32. The minimum required version for aCC (HP ANSI C++) on PA-RISC + is A.03.57. The supported gcc compiler is gcc 3.4.3. + + \section2 Itanium - B.11.23 or later + + You can configure Qt for aCC in 32 and 64 bit mode (hpuxi-acc-64 or + hpuxi-acc-32). gcc is currently unsupported. The default platform is + hpuxi-acc-64. The minimum required version for aCC (HP ANSI C++) on + Itanium is A.06.12. + + \section2 OpenGL Support + + Qt's \l{QtOpenGL}{OpenGL} module requires GLX 1.3 or later to be installed. + This is available for HP-UX 11i - see the + \l{http://docs.hp.com/en/5992-2331/ch04s02.html}{Graphics and Technical Computing Software} + section of the release notes for more information. + + \target IRIX + \section1 IRIX - 6.5.x + + \bold{IRIX is an unsupported platform - please see Qt's online + \l{Platform Support Policy} for details.} + + Unpackaging and IRIX tar: + Because of long filenames some files will be cut off incorrectly with IRIX + tar. Please use GNU tar to unpack Qt packages. + + \section1 Linux + + There are no known problems with using Qt on production versions of + Linux/x86, Linux/ppc, Linux/amd64 and Linux/ia64 (including Altix(R)). + + For the gcc/g++ compiler, please also see the relevant + \l{Compiler Notes#GCC}{compiler page}. + + \section2 Installation problems + + See also the \l{Installation FAQ}. + + If you experience problems when installing new open source versions of Qt + versions, try to use the open source Qt archives (e.g., RPM) + provided by your Linux distribution. If you need to install the source (.tgz) + archive, be aware that you will probably end up with two different + versions of the Qt library installed on your system, which will probably + lead to link errors, like this: + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 0 + Fix this by removing the old version of the library. + + If you have problems installing open source versions of Qt + provided by your Linux distribution (e.g., RPM), please consult the + maintainers of the distribution, not us. + + Some RPM versions have problems installing some of the Qt RPM archives + where installation stops with an error message warning about a + "Failed Dependency". Use the \c{--nodeps} option to \c rpm to workaround + this problem. + + \target Solaris + \section1 Solaris - 9 or later + + \section2 Unpackaging and Solaris tar + + On some Solaris systems, both Solaris tar and GNU tar have been reported + to truncate long filenames. We recommend using star instead + (http://star.berlios.de). + + \section2 CC on Solaris + + Be sure to check our \l{Compiler Notes#Sun Studio}{Forte Developer / Sun Studio} + notes. + + \section2 GCC on Solaris + + Be sure to check the installation notes for \l{GCC on Solaris}. + Do not use GCC with Sun's assembler/linker, this will result in link-time + errors in shared libraries. Use GNU binutils instead. + + GCC 3.2.* is known to miscompile Qt due to an optimizer bug that will + cause the resulting binaries to hang. Please use GCC 3.4.2 or later. +*/ + +/*! + \page platform-notes-windows.html + \title Platform Notes - Windows + \contentspage Platform Notes + + This page contains information about the Windows platforms Qt is currently + known to run on, with links to platform-specific notes. More information + about the combinations of platforms and compilers supported by Qt can be + found on the \l{Supported Platforms} page. + + \tableofcontents + + \section1 Windows Vista + + At the time Qt %VERSION% was released, there were no known Vista-specific issues. + + \target Windows NT + \section1 Windows XP, Windows 2000 and Windows NT + + \section2 Installation location + + Installing Qt into a directory with spaces, e.g. C:\\Program Files, may + cause linker errors like the following: + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 2 + + Install Qt into a subdirectory without spaces to avoid this problem. + + \section2 AccelGALAXY graphic card + + When you use a NT 4.0 machine with the driver number + 4,00,1381,1000,021,4.0.0 there is a problem with drag an drop and icons. + The computer freezes, and you have to reset. The problem disappears with + the newest version of the driver, available at + \l{http://www.es.com/}{www.es.com}. + + \section2 Possible GL conflict + + There is a known issue with running Microsoft NetMeeting, Lotus SameTime + and other applications that require screen grabbing while direct + rendering is enabled. Other GL-applications may not work as expected, + unless direct rendering is disabled. +*/ + +/*! + \page platform-notes-mac.html + \title Platform Notes - Mac OS X + \contentspage Platform Notes + + This page contains information about the Mac OS X versions Qt is currently + known to run on, with links to platform-specific notes. More information + about the combinations of platforms and compilers supported by Qt can be + found on the \l{Supported Platforms} page. + + \tableofcontents + + \section1 General Information + + Qt 4.4 and Qt 4.5 development is only supported on Mac OS X 10.4 and up. + Applications built against these version of Qt can be deployed on Mac OS X + 10.3, but cannot be developed on that version of the operating system due + to compiler issues. + + Qt 4.3 has been tested to run on Mac OS X 10.3.9 and up. See notes on + the binary package for more information. + + Qt 4.1 has been tested to run on Mac OS X 10.2.8 and up. Qt 4.1.4 is the + last release to work with Mac OS X 10.2. + + \section2 Required GCC version + + Apple's gcc 4 that is shipped with the Xcode Tools for both Mac OS X 10.4 + and 10.5 will compile Qt. There is preliminary support for gcc 4.2 which + is included with Xcode Tools 3.1+ (configurable with + \c{-platform macx-g++42}). + + \section2 Binary Package + + The binary package requires that you have your .qt-license file in your + home directory. Installer.app cannot complete without a valid .qt-license + file. Evaluation users of Qt will have information about how to create + this file in the email they receive. + + The binary package was built on Mac OS X 10.4 with Xcode Tools 2.1 + (gcc 4.0.0) for Qt 4.1.0, Xcode Tools 2.2 (gcc 4.0.1) for Qt 4.1.1-4.1.4 + and Xcode Tools 2.3 for 4.2.0. It will only link executables built + against 10.4 (or a 10.4 SDK). You should be able to run applications + linked against these frameworks on Mac OS X 10.3.9 and Mac OS X 10.4+. + If you require a different configuration, you will have to use the + source package and build with GCC 3.3. + + \section2 Mac OS X on Intel hardware + + Qt 4 fully supports both the Intel and PowerPC architectures on the Mac. + As of Qt 4.1 it is possible to support the Intel architecture by + creating Universal Binaries with qmake. As of Qt 4.1 it is possible to + build Qt as a set of universal binaries and frameworks from configure by + adding these extra flags: + + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 3 + + If you are building on Intel hardware you can omit the sdk parameter, but + PowerPC hardware requires it. + + You can also generate universal binaries using qmake. Simply add these + lines to your .pro file: + + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 4 + + \section2 Build Issues + + If Qt does not build upon executing make, and fails with an error message + such as + + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 5 + + this could be an indication you have upgraded your version of Mac OS X + (e.g. 10.3 to 10.4), without upgrading your Developer Tools (Xcode Tools). + These must match in order to successfully compile files. + + Please be sure to upgrade both simultaneously. If problems still occur, + contact support. + + \section2 Fink + + If you have installed the Qt for X11 package from \l{Fink}, + it will set the QMAKESPEC environment variable to darwin-g++. This will + cause problems when you build the Qt for Mac OS X package. To fix this, simply + unset your QMAKESPEC or set it to macx-g++ before you run configure. + You need to have a fresh Qt distribution (make confclean). + + \section2 MySQL and Mac OS X + + There seems to be a issue when both -prebind and -multi_module are + defined when linking static C libraries into dynamic library. If you + get the following error message when linking Qt: + + \snippet doc/src/snippets/code/doc_src_platform-notes.qdoc 6 + + re-link Qt using -single_module. This is only a problem when building the + MySQL driver into Qt. It does not affect plugins or static builds. + + \section2 Qt and Precompiled Headers (PCH) + + Starting with Qt 3.3.0 it is possible to use precompiled headers. They + are not enabled by default as it appears that some versions of Apple's + GCC and make have problems with this feature. If you want to use + precompiled headers when building the Qt source package, specify the + -pch option to configure. If, while using precompiled headers, you + encounter an internal compile error, try removing the -include header + statement from the compile line and trying again. If this solves the + problem, it probably is a good idea to turn off precompiled headers. + Also, consider filing a bug report with Apple so that they can + improve support for this feature. +*/ + +/*! + \page platform-notes-windows-ce.html + \title Platform Notes - Windows CE + \contentspage Platform Notes + + This page contains information about the Windows CE and Windows Mobile + platforms Qt is currently known to run on, with links to platform-specific + notes. More information about the combinations of platforms and compilers + supported by Qt can be found on the \l{Supported Platforms} page. +*/ + +/*! + \page platform-notes-embedded-linux.html + \title Platform Notes - Embedded Linux + \contentspage Platform Notes + + This page contains information about the Embedded Linux platforms Qt is + currently known to run on, with links to platform-specific notes. More + information about the combinations of platforms and compilers supported + by Qt can be found on the \l{Supported Platforms} page. +*/ diff --git a/doc/src/platforms/qt-embedded-linux.qdoc b/doc/src/platforms/qt-embedded-linux.qdoc new file mode 100644 index 0000000..5329218 --- /dev/null +++ b/doc/src/platforms/qt-embedded-linux.qdoc @@ -0,0 +1,126 @@ +/**************************************************************************** +** +** 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 qws + \title Qt for Embedded Linux Classes + \ingroup groups + \ingroup qt-embedded-linux + \ingroup platform-specific + + \brief Classes that are specific to Qt for Embedded Linux. + + These classes are relevant to \l{Qt for Embedded Linux} users. +*/ + + +/*! + \group qt-embedded-linux + \ingroup qt-embedded + \title Qt for Embedded Linux + \brief Documents specifically about Qt for Embedded Linux. + + Qt for Embedded Linux is a C++ framework for GUI and application development + for embedded devices. It runs on a variety of processors, usually + with Embedded Linux. Qt for Embedded Linux provides the standard Qt API for + embedded devices with a lightweight window system. + + \image qt-embedded-architecture.png + + Qt for Embedded Linux applications write directly to the framebuffer, + eliminating the need for the X Window System and saving memory. + The Linux framebuffer is enabled by default on all modern Linux + distributions. For information on older versions, please refer to + the \l{Framebuffer HOWTO} document. For development + and debugging purposes, Qt for Embedded Linux provides a \l {The + Virtual Framebuffer}{virtual framebuffer}. It is also possible to + run an application using the + \l{The VNC Protocol and Qt for Embedded Linux}{VNC protocol}. + + \table 100% + \header \o Getting Started \o Reference \o Features + \row + \o + \list + \o \l {Qt for Embedded Linux Architecture}{Architecture Overview} + \o \l {Installing Qt for Embedded Linux}{Installation} + \o \l {Running Qt for Embedded Linux Applications}{Running Applications} + \o \l {Qt for Embedded Linux Examples}{Examples} + \endlist + \o + \list + \o \l {Qt for Embedded Linux Classes}{Classes} + \o \l {Qt for Embedded Linux Environment Variables}{Environment Variables} + \o \l {Licenses for Fonts Used in Qt for Embedded Linux}{Font Licenses} + \endlist + \o + \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} + \o \l {Qt for Embedded Linux and OpenGL}{OpenGL} + \o \l {Qt for Embedded Linux Fonts}{Fonts} + \endlist + + \header \o Development \o Porting \o Optimization + \row + \o + \list + \o \l {The Virtual Framebuffer}{Virtual Framebuffer} + \o \l {The VNC Protocol and Qt for Embedded Linux}{VNC Protocol} + \o \l {Testing the Linux Framebuffer} + \o \l {Cross Compiling Qt for Embedded Linux Applications}{Cross Compiling Applications} + \o \l {Deploying Qt for Embedded Linux Applications}{Deploying Applications} + \endlist + \o + \list + \o \l {Porting Qt Applications to Qt for Embedded Linux} + \o \l {Porting Qt for Embedded Linux to a New Architecture} + \o \l {Porting Qt for Embedded Linux to Another Operating System} + \endlist + \o + \list + \o \l {Qt Performance Tuning} + \o \l {Fine-Tuning Features in Qt} + \o \l {Adding an Accelerated Graphics Driver to Qt for Embedded Linux}{Adding an Accelerated Graphics Driver} + \endlist + \endtable +*/ diff --git a/doc/src/platforms/qt-embedded.qdoc b/doc/src/platforms/qt-embedded.qdoc new file mode 100644 index 0000000..22cba80 --- /dev/null +++ b/doc/src/platforms/qt-embedded.qdoc @@ -0,0 +1,76 @@ +/**************************************************************************** +** +** 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 qt-embedded + \title Qt for Embedded Platforms + \brief Documents related to Qt for Embedded Platforms. + \ingroup platform-specific + + Qt is available for embedded platforms and devices as well as for a number + of desktop platforms. The features provided for each platform depend on the + capabilities and architecture of the operating system. + + Currently, two embedded platforms are supported by Qt: + + \table 90% + \header + \raw HTML + <td style="width: 40%">Embedded Linux</td> + <td style="background: white; width: 5%"></td> + <td style="width: 40%">Windows CE</td> + \endraw + \row \o \l{Qt for Embedded Linux} is designed to be used on Linux devices + without X11 or existing graphical environments. This flavor of + Qt includes a framework for creating both applications and an + environment for them. As a result, it includes features for + window management, inter-process communication and facilities + for handling input and display devices. + \raw HTML + <td style="background: white; width: 5%"></td> + \endraw + \o \l{Qt for Windows CE} is used to create applications running in + existing Windows CE and Windows Mobile environments. + Applications use the appropriate style for the embedded + environment and use native features, such as menus, to conform + to the native style guidelines. + \endtable +*/ diff --git a/doc/src/platforms/qtmac-as-native.qdoc b/doc/src/platforms/qtmac-as-native.qdoc new file mode 100644 index 0000000..265d222 --- /dev/null +++ b/doc/src/platforms/qtmac-as-native.qdoc @@ -0,0 +1,202 @@ +/**************************************************************************** +** +** 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 for Mac OS X 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 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 qtmac-as-native.html + \title Qt is Mac OS X Native + \brief An explanation of Qt's native features on Mac OS X. + \ingroup platform-specific + + This document explains what makes an application native on Mac OS X. + It shows the areas where Qt is compliant, and the grey areas where + compliance is more questionable. (See also the document + \l{mac-differences.html}{Qt for Mac OS X - Specific Issues}.) + + Normally when referring to a native Mac application, one really means an + application that talks directly to the underlying window system, rather + than one that uses some intermediary (for example Apple's X11 server, or a + web browser). Qt applications run as first class citizens, just like + Cocoa, and Carbon applications. In fact, we use Carbon and HIView + internally to communicate with OS X. + + When an application is running as a first class citizen, it means that + it can interact with specific components of the Mac OS X experience: + + \tableofcontents + + \section1 The Global Menu Bar + + Qt does this via the QMenuBar abstraction. Mac users expect to + have a menu bar at the top of the screen and Qt honors this. + + Additionally, users expect certain conventions to be respected, for + example the application menu should contain About, Preferences, + Quit, etc. Qt handles this automatically, although it does not + provide a means of interacting directly with the application menu. + (By doing this automatically, Qt makes it easier to port Qt + applications to other platforms.) + + \section1 Aqua + + This is a critical piece of Mac OS X (documentation can be found at + \l{http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/index.html}). + It is a huge topic, but the most important guidelines for GUI + design are probably these: + + \list + \i \e{Aqua look} + + As with Cocoa/Carbon, Qt provides widgets that look like those + described in the Human Interface Descriptions. Qt's widgets use + Appearance Manager on Mac OS X 10.2 and the new HIThemes on Mac OS X 10.3 + and higher to implement the look, in other words we use Apple's own API's + for doing the rendering. + + \i \e{Aqua feel} + + This is a bit more subjective, but certainly Qt strives to + provide the same feel as any Mac OS X application (and we + consider situations where it doesn't achieve this to be bugs). + Of course Qt has other concerns to bear in mind, especially + remaining cross-platform. Some "baggage" that Qt carries is in + an effort to provide a widget on a platform for which an + equivelant doesn't exist, or so that a single API can be used to + do something, even if the API doesn't make entire sense for a + specific widget. + + \i \e{Aqua guides} + + This is the most subjective, but there are many suggestions and + guidelines in the Aqua style guidelines. This is the area where Qt is + of least assistance. The decisions that must be made to conform (widget + sizes, widget layouts with respect to other widgets, window margins, + placement of OK and Cancel, etc) must be made based on the user + experience demanded by your application. If your user base is small or + mostly comes from the Windows or Unix worlds, these are minor issues much + less important than trying to make a mass market product. Qt for Mac OS X + is fully API compatible with Qt for Windows and X11, but Mac OS X is a + significantly different platform to Windows and some special + considerations must be made based on your audience. + + \endlist + + \section1 Dock + + Interaction with the dock is possible. The icon can be set by calling + QWidget::setWindowIcon() on the main window in your application. The + setWindowIcon() call can be made as often as necessary, providing an + icon that can be easily updated. + \omit + It is also possible to set a QMenu as the dock menu through the use of the + qt_mac_set_dock_menu() function. + \endomit + + \section1 Accessiblity + + Although many users never use this, some users will only interact with your + applications via assistive devices. With Qt the aim is to make this + automatic in your application so that it conforms to accepted practice on + its platform. Qt uses Apple's accessibility framework to provide access + to users with diabilities. + + \section1 Development Tools + + Mac OS X developers expect a certain level of interopability + between their development toolkit and the platform's developer + tools (for example Visual Studio, gmake, etc). Qt supports both Unix + style Makefiles, and ProjectBuilder/Xcode project files by using + the \l qmake tool. For example: + + \snippet doc/src/snippets/code/doc_src_qtmac-as-native.qdoc 0 + + will generate an Xcode project file from project.pro. With \l qmake + you do not have to worry about rules for Qt's preprocessors (\l moc + and \l uic) since \l qmake automatically handles them and ensures that + everything necessary is linked into your application. + + Qt does not entirely interact with the development environment (for + example plugins to set a file to "mocable" from within the Xcode + user interface). Nokia is actively working on improving Qt's + interoperability with various IDEs. +*/ diff --git a/doc/src/platforms/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc new file mode 100644 index 0000000..8aec1e2 --- /dev/null +++ b/doc/src/platforms/supported-platforms.qdoc @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** 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 supported-platforms.html + \title Supported Platforms + \brief The platforms supported by Nokia for Qt. + \ingroup platform-specific + + The Qt team strives to provide support for the platforms most + frequently used by Qt users. We have designed our internal testing procedure to + divide platforms into three test categories (Tier 1, Tier 2 and Tier 3) in order + to prioritize internal testing and development resources so that the most + frequently used platforms are subjected to our most rigorous testing processes. + + Qt is supported on a variety of 32-bit and 64-bit platforms, and can + usually be built on each platform with GCC, a vendor-supplied compiler, or + a third party compiler. Although Qt may be built on a range of platform-compiler + combinations, only a subset of these are actively supported by Nokia. + + \tableofcontents + + Information about the specific platforms Qt runs on can be found on the + \l{Platform Notes} page. Information about the compilers used on each platform + can be found on the \l{Compiler Notes} page. + + \section1 Tier 1 Platforms + + All Tier 1 platforms are subjected to our unit test suite and other internal + testing tools on a frequent basis (prior to new version releases, source tree + branching, and at other significant period points in the development process). + Errors or bugs discovered in these platforms are prioritized for correction + by the development team. Significant errors discovered in Tier 1 platforms can + impact release dates and Qt Development Frameworks strives to resolve all known + high priority errors in Tier 1 platforms prior to new version releases. + + \table + \header \o Platform + \o Compilers + \row \o Linux (32 and 64-bit) + \o gcc 4.2 + \row \o Microsoft Windows XP + \o gcc 3.4.2 (MinGW) (32-bit), MSVC 2003, 2005 (32 and 64-bit) + \row \o Microsoft Windows Vista + \o MSVC 2005, 2008 + \row \o Microsoft Windows Vista 64bit + \o MSVC 2008 + \row \o Apple Mac OS X 10.5 "Leopard" x86_64 (Carbon, Cocoa 32 and 64bit) + \o As provided by Apple + \row \o Embedded Linux QWS (ARM) + \o gcc (\l{http:\\www.codesourcery.com}{Codesourcery version)} + \row \o Windows CE 5.0 (ARMv4i, x86, MIPS) + \o MSVC 2005 WinCE 5.0 Standard (x86, pocket, smart, mipsii) + \endtable + + \section1 Tier 2 Platforms + + Tier 2 platforms are subjected to our unit test suite and other internal testing + tools prior to release of new product versions. Qt users should note, however, + that errors may be present in released product versions for Tier 2 platforms and, + subject to resource availability, known errors in Tier 2 platforms may or may not + be corrected prior to new version releases. + + \table + \header \o Platform + \o Compilers + \row \o Apple Mac OS X 10.4 "Tiger" + \o As provided by Apple + \row \o HPUXi 11.11 + \o aCC 3.57, gcc 3.4 + \row \o HPUXi 11.23 + \o aCC 6.10 + \row \o Solaris 10 UltraSparc + \o Sun Studio 12 + \row \o AIX 6 + \o Power5 xlC 7 + \row \o Microsoft Windows XP + \o Intel Compiler + \row \o Linux + \o Intel Compiler + \row \o Embedded Linux QWS (Mips, PowerPC) + \o gcc (\l{http:\\www.codesourcery.com}{Codesourcery version)} + \row \o Windows CE 6.0 (ARMv4i, x86, MIPS) + \o MSVC 2008 WinCE 6.0 Professional + \endtable + + \section1 Tier 3 Platforms (Not supported by Nokia) + + All platforms not specifically listed above are not supported by Nokia. Nokia does + not run its unit test suite or perform any other internal tests on platforms not + listed above. Qt users should note, however, that there may be various open source + projects, community users and/or Qt partners who are able to provide assistance with + platforms not supported by Nokia. + + \section1 General Legal Disclaimer + + Please note that Qt is offered on an "as is" basis without warranty + of any kind and that our products are not error or bug free. To the maximum extent + permitted by applicable law, Nokia on behalf of itself and its suppliers, disclaims all + warranties and conditions, either express or implied, including, but not limited to, + implied warranties of merchantability, fitness for a particular purpose, title and + non-infringement with regard to the Licensed Software. +*/ diff --git a/doc/src/platforms/wince-customization.qdoc b/doc/src/platforms/wince-customization.qdoc new file mode 100644 index 0000000..06de1c8 --- /dev/null +++ b/doc/src/platforms/wince-customization.qdoc @@ -0,0 +1,264 @@ +/**************************************************************************** +** +** 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 windowsce-customization.html + \ingroup qtce + \title Windows CE - Working with Custom SDKs + \brief How to set up Qt for use with custom Windows CE SDKs. + + When working with a custom SDK for Windows CE, Qt provides an easy way + to add support for it to your development environment. The following is + a tutorial that covers how to create a specification for Qt on Windows + CE platforms. + + \tableofcontents + + \section1 Creating a Custom Build Specification + + Create a subdirectory in the \c mkspecs folder of the Qt directory. + New specifications for Qt for Windows CE following this naming convention: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 0 + + Using this convention makes it possible for \l{qmake} to identify that + you are building Qt for Windows CE, and will customize the compilation + process accordingly. + + Create the files \c qmake.conf and \c qplatformdefs.h inside the new + specification directory. Take a look at the implementation of the other + Windows CE specifications included in the \c mkspecs directory to see + what is required to build Qt for Windows CE successfully. + + + \section1 Fine-Tuning Options + + Compared to the desktop versions, Qt for Windows CE needs two additional + options: + + \list + \o \bold{CE_SDK} specifies the name of the SDK. + \o \bold{CE_ARCH} specifies information about the target architecture. + \endlist + + Following is an example configuration for the Windows Mobile 5 for + Pocket PC SDK: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 1 + + \note \l{qmake} uses this information to build a valid Visual Studio + project file. You need to ensure that they are identical to the + configuration of the custom SDK, otherwise you might not be able to compile + or debug your project with Visual Studio. + + Additionally, most Windows CE SDKs use extra compiler options. These + can be specified by expanding the \c DEFINES value. + + For example, with Windows Mobile 5 for Pocket PC, the \c DEFINES variable + is expanded in the following way: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 2 + + The mkspec may require additional configuration to be used inside of Visual + Studio, depending on the Windows CE SDK. The above example defines + \c _M_ARM. This definition is available internally in Visual Studio. Hence, + the compiler will warn you about redefinition during the build step. These + warnings can be disabled by adding a \c default_post.prf file containing + the following lines, within the subdirectory. + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 8 + + + \section1 Cross-compilation Environment for a Custom SDK + + Qt for Windows CE supports a convenience script, \c{setcepaths.bat}, that + prepares the environment in a command prompt for cross-compilation. + However, on custom SDKs, the \c checksdk tool is provided to identify the + environment, so Qt compiles successfully. + + \c checksdk is generated during the \c configure step and allows for the + following options: + + \list + \o \c list: Returns a list of available Windows CE SDKs. (This list + may contain one or more SDKs not supported on Qt for Windows CE, + e.g., Pocket PC 2003.) + \o \c sdk: The parameter to specify an SDK. Returns a setup of + environment variables that must be set to cross-compile Qt. + \o \c script: Stores your setup in a \c{.bat} file. This simplifies + the process of switching environments when you load a command + prompt in future. + \endlist + + + \section1 Compiling Qt for a Custom SDK + + Windows CE is highly customizable, hence it is possible that some SDKs have + feature-stripped setups. Depending on the SDK's configuration, Qt may not + compile in its standard configuration, as Qt for Windows CE is designed to + be compatible with the Standard SDK setup. + + However, it is possible to exclude features of Qt and create a version that + compiles for the desired SDK. + + Further information on stripping features can be found in the + \l{Fine-Tuning Features in Qt}{QFeatures} documentation. + + + \section1 Making Qt Applications Start on a Custom Device + + Sometimes, a Windows CE device has been created with a configuration + different from the corresponding SDK's configuration. In this case, symbols + that were available at linking stage will be missing from the run-time + libraries. + + Unfortunately, the operating system will not provide an error message that + mentions which symbols are absent. Instead, a message box with the following + message will appear: + + \c{app.exe is not a valid CE application!} + + To identify the missing symbols, you need to create a temporary + application that attempts to dynamically load the Qt for Windows CE + libraries using \c LoadLibrary. The following code can be used for this: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 9 + + Once you have compiled and deployed the application as well as the Qt + libraries, start a remote debugger. The debugger will then print the + ordinal number of the unresolved symbol. + + Search for parts of Qt that rely on these functions and disable them using + the \l{Fine-Tuning Features in Qt}{QFeatures} functionality. + + In our experience, when Qt applications do not start on Windows CE, it is + usually the result of missing symbols for the following classes or + features: + \list + \o \l{Drag and Drop} + \o \l{QClipboard} + \o \l{QCursor} + \endlist + + Please refer to the Microsoft documentation + \l{http://msdn.microsoft.com/en-us/library/e7tsx612.aspx}{here} for + information on what ordinals are and how you can create them. Information + on accessing the corresponding symbol name to a given ordinal value can + also be found in the Microsoft documentation. + +*/ + +/*! + \page shadow builds-wince.html + \ingroup qtce + \title Windows CE - Using shadow builds + \brief How to create a shadow build for Qt for Windows CE. + + \tableofcontents + + While developing for Windows CE you might want to compile a + version of Qt for several different platforms and SDKs. In order + to create those different builds of Qt you do not have to copy the + whole Qt package or the Qt source. You are able to create multiple + Qt builds from a single source tree. Such builds are called shadow + builds. + + Basically a shadow build is created by calling configure.exe from a + different directory. + + To make sure that the shadow build compiles correctly it is important + that you following these guidelines: + + \list + \o The original Qt source package must be left untouched - configure must + never have been run in the source tree directory. + + \o The shadow build directory must be on the same level as the Qt source + package.\br + If the Qt package is in \c{C:\Qt\%VERSION%} the shadow build directory + could be \c{C:\Qt\shadowbuild}. A shadow build from a directory like + \c{C:\shadowbuild} will not compile. + \o Avoid using "release" and "debug" in the path to the shadow build + directory. (This is an internal limitation of the build system.) + \o The \c{\bin} directory of the shadow build directory must be added to the + \c PATH environment variable. + \o Perl has been installed on your system. (\l{ActivePerl} is a popular + distribution of Perl on Windows.) + \endlist + + So lets assume you have installed Qt in \c{C:\Qt\%VERSION%} and you want + to create a shadow build in \c{C:\Qt\mobile5-shadow}: + + \list + \o First add \c{C:\Qt\mobile5-shadow\bin} to the \c PATH variable. + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 3 + + \o Make sure the enviroment variables for your compiler are set. + + Visual Studio includes \c{vcvars32.bat} for that purpose - or simply use + the "Visual Studio Command Prompt" from the Start menu. + + \o Now navigate to your shadow build directory and run configure: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 4 + + \o To build Qt, you have to update your \c{PATH, INCLUDE} and \c LIB paths + to point to your target platforms. + + For a default installation of the Windows Mobile 5.0 Pocket PC SDK, you + can do the following: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 5 + + We have provided a convenience script for this called \c{setcepaths}. Simply + type: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 6 + + \o Finally, to build the shadow build type: + + \snippet doc/src/snippets/code/doc_src_wince-customization.qdoc 7 + + \o That's all. You have successfully created a shadow build of Qt in + \c{C:\Qt\mobile5-shadow}. + \endlist +*/ diff --git a/doc/src/platforms/wince-introduction.qdoc b/doc/src/platforms/wince-introduction.qdoc new file mode 100644 index 0000000..29f880e --- /dev/null +++ b/doc/src/platforms/wince-introduction.qdoc @@ -0,0 +1,142 @@ +/**************************************************************************** +** +** 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 qtce + \title Qt for Windows CE + \ingroup qt-embedded + \brief Documents related to Qt on Windows CE + + Qt for Windows CE is a C++ framework for GUI and application development + for embedded devices running Windows CE. It runs on a variety of processors, + including ARM, Intel x86, MIPS and SH-4. + + \table 100% + \header \o Getting Started \o Reference \o Performance and Optimization + \row + \o + \list + \o \l {Qt for Windows CE Requirements} + \o \l {Installing Qt on Windows CE} + \o \l {Windows CE - Introduction to using Qt}{Introduction to using Qt} + \endlist + \o + \list + \o \l {Windows CE - Using shadow builds}{Using shadow builds} + \o \l {Windows CE - Working with Custom SDKs}{Working with Custom SDKs} + \endlist + \o + \list + \o \l {Windows CE OpenGL ES}{OpenGL ES} + \o \l {Qt Performance Tuning} + \o \l {Fine-Tuning Features in Qt} + \endlist + \endtable +*/ + +/*! + \page wince-with-qt-introduction.html + + \title Windows CE - Introduction to using Qt + \brief An introduction to Qt for Windows CE developers. + \ingroup qtce + + \tableofcontents + + \section1 Required tools + + In order to use Qt for Windows CE you need to have Visual Studio + 2005 and at least one of the supported Windows CE/Mobile SDKs + installed. + + We recommend the \e{Windows Mobile 5.0 SDK for Pocket PC} SDK available + \l{http://www.microsoft.com/downloads/details.aspx?FamilyID=83a52af2-f524-4ec5-9155-717cbe5d25ed&DisplayLang=en}{here}. + + \section1 Installing Qt + + Follow the instructions found in \l{Installing Qt on Windows CE}. + + \section1 Building your own applications + + If you are new to Qt development, have a look at \l{How to Learn Qt} + and \l{Tutorials}. In general there is little or no difference in + developing Qt applications for Windows CE compared to any of the + other platforms supported by Qt. + + Once you have a \c .pro file, there are two ways of building your + application. You can either do it on the command line or inside of + VS2005. To do it on the command line, simply write: + + \snippet doc/src/snippets/code/doc_src_wince-introduction.qdoc 0 + + To build the project inside of VS2005, on the command line write: + + \snippet doc/src/snippets/code/doc_src_wince-introduction.qdoc 1 + + then start VS2005 with the generated \c .vcproj or \c .sln file and + select \e{Build project}. + + For more information on how to use qmake have a look at the \l + {qmake Tutorial}. + + \section1 Running the application + + In order to run the application, it needs to be deployed on the + Windows CE/Mobile device you want to test it for. This can either + be done manually or automated using VS2005. + + To do it manually, simply copy the executable, the Qt \c{.dll} + files needed for the application to run, and the C-runtime library + into a folder on the device, and then click on the executable to + start the program. You can either use the \e Explorer found in + ActiveSync or the \e{Remote File Viewer} found in VS2005 to do + this. + + VS2005 can do this step automatically for you as well. If you have + built the project inside VS2005, simply select \e Deploy and then + \e Debug to deploy and then run the application. You can change the + device type by changing the \e{Target Device} specified in the + VS2005 toolbar. + + Further information on deploying Qt applications for Windows can + be found in the \l{Deploying an Application on Windows} + {deployment document}. +*/ diff --git a/doc/src/platforms/wince-opengl.qdoc b/doc/src/platforms/wince-opengl.qdoc new file mode 100644 index 0000000..3c7e22f --- /dev/null +++ b/doc/src/platforms/wince-opengl.qdoc @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** 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 windowsce-opengl.html + \title Windows CE OpenGL ES + \ingroup qtce + \brief Information about support for OpenGL ES with Qt for Windows CE. + + \section1 Introduction + + \l {http://www.opengl.org}{OpenGL} is an industry standard API for 2D/3D + graphics. It provides a powerful, low-level interface between software + and acceleration hardware, and it is operating system and window system + independent. + + \l {http://www.khronos.org/opengles}{OpenGL ES} is a subset of the + \l {http://www.opengl.org}{OpenGL} standard. It is meant for use in + embedded systems. Hence, it has a smaller, more constrained API. + + Qt for Windows CE uses EGL 1.1 to embed OpenGL ES windows within the + Windows CE window manager. + + To use OpenGL ES enabled widgets in a Qt for Windows CE application, you + only need to subclass QGLWidget and draw on instances of the subclass with + OpenGL ES functions. + + OpenGL ES includes profiles for floating-point and fixed-point arithmetic. + The floating point profile is called OpenGL ES CM (Common) and the + fixed-point profile is called OpenGL ES CL (Common Lite). + + You can run \c{configure} with the \c{-opengl-es-cm} option for the Common + profile or \c{-opengl-es-cl} for the Common Lite profile. In both cases, + ensure that the \c{lib} and \c{includes} paths include the OpenGL ES + headers and libararies from your SDK. The OpenGL ES lib should be called + either \c{libGLES_CM.lib} for the Common profile or \c{libGLES_CL.lib} + for the Common Lite profile. + + To configure Qt for Windows Mobile 5.0 and OpenGL ES Common Lite support + you can run \c{configure} like this: + + \snippet doc/src/snippets/code/doc_src_wince-opengl.qdoc 0 + + The distinction between the Common and Common Lite profiles is important, + because the Common Lite profile has less functionality and only supports a + fixed-point vertex format. + + To start programming with Qt and OpenGL ES on Windows CE, you can start + with the \l{Hello GL ES Example}. This example shows how to use QGLWidget + and QGLPainter with OpenGL ES. It also provides some hints on how to port + OpenGL code to OpenGL ES. + + \section2 Using OpenGL to Accelerate Normal 2D Painting + + Qt provides QOpenGLPaintEngine, a subclass of QPaintEngine that translates + QPainter operations into OpenGL calls. This is especially convenient for + drawing text or QImage objects in an OpenGL ES context. For further + details, refer to the \l{Hello GL ES Example}. + +*/ diff --git a/doc/src/platforms/winsystem.qdoc b/doc/src/platforms/winsystem.qdoc new file mode 100644 index 0000000..5afa1f7 --- /dev/null +++ b/doc/src/platforms/winsystem.qdoc @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** 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 winsystem.html + \title Window System Specific Notes + \ingroup platform-specific + + Qt is a cross-platform GUI toolkit, so almost the entire API is the + same on all platforms and window systems. If you wish to use + platform-specific features, and still maintain a platform-independent + source tree, you should protect the platform-specific code using the + appropriate \c{#ifdef} directives (see below). + + Qt provides a few low-level global functions for fine-tuning + applications on specific platforms. See \l{Special-Purpose Global + Functions Exported by Qt} for details. + + \tableofcontents + + For information about which platforms are supported by Qt, see the + \l{Platform Notes}. For information on distributing Qt applications, see + \l{Deploying Qt Applications}. + + \target x11 + \section1 Qt for X11 + + When compiling for this platform, the macro \c{Q_WS_X11} is defined. + + \e{Not documented here. Please contact Qt's technical support team + if you have queries.} + + See the \l{Qt for X11 Requirements} page for more information about the + libraries required to build Qt with as many features as possible. + + \target win + \section1 Qt for Windows + + When compiling for this platform, the macro \c{Q_WS_WIN} is defined. + + \e{Not documented here. Please contact Qt's technical support team + if you have queries.} + + \target macosx + \section1 Qt for Mac OS X + + When compiling for this platform, the macro \c{Q_WS_MAC} is defined. + + \list + \i \l{Qt for Mac OS X - Specific Issues} + \i \l{Qt is Mac OS X Native} + \endlist + + \target qws + \section1 Qt for Embedded Linux + + When compiling for this platform, the macro \c{Q_WS_QWS} is + defined (the window system is literally the Qt Window System). See + the \l{Qt for Embedded Linux} documentation for more information. +*/ diff --git a/doc/src/platforms/x11overlays.qdoc b/doc/src/platforms/x11overlays.qdoc new file mode 100644 index 0000000..7d7a776 --- /dev/null +++ b/doc/src/platforms/x11overlays.qdoc @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** 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 x11overlays.html + \title How to Use X11 Overlays with Qt + + X11 overlays are a powerful mechanism for drawing + annotations etc., on top of an image without destroying it, thus saving + a great deal of image rendering time. For more information, see the highly + recommended book \e{OpenGL Programming for the X Window System} (Mark + Kilgard, Addison Wesley Developers Press 1996). + + \warning The Qt OpenGL Extension includes direct support for the + use of OpenGL overlays. For many uses of overlays, this makes the + technique described below redundant. The following is a discussion + on how to use non-QGL widgets in overlay planes. + + In the typical case, X11 overlays can easily be used together with the + current version of Qt and the Qt OpenGL Extension. The following + requirements apply: + + \list 1 + \i Your X server and graphics card/hardware must support overlays. + For many X servers, overlay support can be turned on with + a configuration option; consult your X server installation + documentation. + + \i Your X server must (be configured to) use an overlay visual as the + default visual. Most modern X servers do this, since this has the + added advantage that pop-up menus, overlapping windows etc., will + \e not affect underlying images in the main plane, thereby + avoiding expensive redraws. + + \i The best (deepest) visual for OpenGL rendering is in the main + plane. This is the normal case. Typically, X servers that support + overlays provide a 24-bit \c TrueColor visual in the main plane, + and an 8-bit \c PseudoColor (default) visual in the overlay plane. + \endlist + + Assuming that the requirements mentioned above are met, a + QGLWidget will default to using the main plane visual, while all + other widgets will use the overlay visual. Thus, we can place a + normal widget on top of the QGLWidget, and do drawing on it, + without affecting the image in the OpenGL window. In other words, + we can use all the drawing capabilities of QPainter to draw + annotations, rubberbands, etc. For the typical use of overlays, + this is much easier than using OpenGL for rendering annotations. + + An overlay plane has a specific color called the transparent + color. Pixels drawn in this color will not be visible; instead + the underlying OpenGL image will show through. + + To use this technique, you must not use the + QApplication::ManyColor or QApplication::TrueColor color + specification for QApplication, because this will force the + normal Qt widgets to use a \c TrueColor visual, which will + typically be in the main plane, not in the overlay plane as + desired. +*/ |