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/internationalization | |
| 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/internationalization')
| -rw-r--r-- | doc/src/internationalization/i18n.qdoc | 515 | ||||
| -rw-r--r-- | doc/src/internationalization/linguist-manual.qdoc | 1512 |
2 files changed, 2027 insertions, 0 deletions
diff --git a/doc/src/internationalization/i18n.qdoc b/doc/src/internationalization/i18n.qdoc new file mode 100644 index 0000000..25c35c7 --- /dev/null +++ b/doc/src/internationalization/i18n.qdoc @@ -0,0 +1,515 @@ +/**************************************************************************** +** +** 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 i18n + \title Qt Classes for Internationalization +*/ + +/*! + \page internationalization.html + \title Internationalization with Qt + \brief Information about Qt's support for internationalization and multiple languages. + + \keyword internationalization + \keyword i18n + + The internationalization of an application is the process of making + the application usable by people in countries other than one's own. + + \tableofcontents + + \section1 Relevant Qt Classes and APIs + + These classes support internationalizing of Qt applications. + + \annotatedlist i18n + + \section1 Languages and Writing Systems + + In some cases internationalization is simple, for example, making a US + application accessible to Australian or British users may require + little more than a few spelling corrections. But to make a US + application usable by Japanese users, or a Korean application usable + by German users, will require that the software operate not only in + different languages, but use different input techniques, character + encodings and presentation conventions. + + Qt tries to make internationalization as painless as possible for + developers. All input widgets and text drawing methods in Qt offer + built-in support for all supported languages. The built-in font engine + is capable of correctly and attractively rendering text that contains + characters from a variety of different writing systems at the same + time. + + Qt supports most languages in use today, in particular: + \list + \o All East Asian languages (Chinese, Japanese and Korean) + \o All Western languages (using Latin script) + \o Arabic + \o Cyrillic languages (Russian, Ukrainian, etc.) + \o Greek + \o Hebrew + \o Thai and Lao + \o All scripts in Unicode 4.0 that do not require special processing + \endlist + + On Windows, Unix/X11 with FontConfig (client side font support) + and Qt for Embedded Linux the following languages are also supported: + \list + \o Bengali + \o Devanagari + \o Dhivehi (Thaana) + \o Gujarati + \o Gurmukhi + \o Kannada + \o Khmer + \o Malayalam + \o Myanmar + \o Syriac + \o Tamil + \o Telugu + \o Tibetan + \endlist + + Many of these writing systems exhibit special features: + + \list + + \o \bold{Special line breaking behavior.} Some of the Asian languages are + written without spaces between words. Line breaking can occur either + after every character (with exceptions) as in Chinese, Japanese and + Korean, or after logical word boundaries as in Thai. + + \o \bold{Bidirectional writing.} Arabic and Hebrew are written from right to + left, except for numbers and embedded English text which is written + left to right. The exact behavior is defined in the + \l{http://www.unicode.org/unicode/reports/tr9/}{Unicode Technical Annex #9}. + + \o \bold{Non-spacing or diacritical marks (accents or umlauts in European + languages).} Some languages such as Vietnamese make extensive use of + these marks and some characters can have more than one mark at the + same time to clarify pronunciation. + + \o \bold{Ligatures.} In special contexts, some pairs of characters get + replaced by a combined glyph forming a ligature. Common examples are + the fl and fi ligatures used in typesetting US and European books. + + \endlist + + Qt tries to take care of all the special features listed above. You + usually don't have to worry about these features so long as you use + Qt's input widgets (e.g. QLineEdit, QTextEdit, and derived classes) + and Qt's display widgets (e.g. QLabel). + + Support for these writing systems is transparent to the + programmer and completely encapsulated in \l{rich text + processing}{Qt's text engine}. This means that you don't need to + have any knowledge about the writing system used in a particular + language, except for the following small points: + + \list + + \o QPainter::drawText(int x, int y, const QString &str) will always + draw the string with its left edge at the position specified with + the x, y parameters. This will usually give you left aligned strings. + Arabic and Hebrew application strings are usually right + aligned, so for these languages use the version of drawText() that + takes a QRect since this will align in accordance with the language. + + \o When you write your own text input controls, use QTextLayout. + In some languages (e.g. Arabic or languages from the Indian + subcontinent), the width and shape of a glyph changes depending on the + surrounding characters, which QTextLayout takes into account. + Writing input controls usually requires a certain knowledge of the + scripts it is going to be used in. Usually the easiest way is to + subclass QLineEdit or QTextEdit. + + \endlist + + The following sections give some information on the status of the + internationalization (i18n) support in Qt. See also the \l{Qt + Linguist manual}. + + \section1 Step by Step + + Writing cross-platform international software with Qt is a gentle, + incremental process. Your software can become internationalized in + the following stages: + + \section2 Use QString for All User-Visible Text + + Since QString uses the Unicode 4.0 encoding internally, every + language in the world can be processed transparently using + familiar text processing operations. Also, since all Qt functions + that present text to the user take a QString as a parameter, + there is no \c{char *} to QString conversion overhead. + + Strings that are in "programmer space" (such as QObject names + and file format texts) need not use QString; the traditional + \c{char *} or the QByteArray class will suffice. + + You're unlikely to notice that you are using Unicode; + QString, and QChar are just like easier versions of the crude + \c{const char *} and char from traditional C. + + \section2 Use tr() for All Literal Text + + Wherever your program uses "quoted text" for text that will + be presented to the user, ensure that it is processed by the \l + QCoreApplication::translate() function. Essentially all that is necessary + to achieve this is to use QObject::tr(). For example, assuming the + \c LoginWidget is a subclass of QWidget: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 0 + + This accounts for 99% of the user-visible strings you're likely to + write. + + If the quoted text is not in a member function of a + QObject subclass, use either the tr() function of an + appropriate class, or the QCoreApplication::translate() function + directly: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 1 + + If you need to have translatable text completely + outside a function, there are two macros to help: QT_TR_NOOP() + and QT_TRANSLATE_NOOP(). They merely mark the text for + extraction by the \c lupdate utility described below. + The macros expand to just the text (without the context). + + Example of QT_TR_NOOP(): + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 2 + + Example of QT_TRANSLATE_NOOP(): + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 3 + + If you disable the \c{const char *} to QString automatic + conversion by compiling your software with the macro \c + QT_NO_CAST_FROM_ASCII defined, you'll be very likely to catch any + strings you are missing. See QString::fromLatin1() for more + information. Disabling the conversion can make programming a bit + cumbersome. + + If your source language uses characters outside Latin1, you + might find QObject::trUtf8() more convenient than + QObject::tr(), as tr() depends on the + QTextCodec::codecForTr(), which makes it more fragile than + QObject::trUtf8(). + + \section2 Use QKeySequence() for Accelerator Values + + Accelerator values such as Ctrl+Q or Alt+F need to be translated + too. If you hardcode Qt::CTRL + Qt::Key_Q for "quit" in your + application, translators won't be able to override it. The + correct idiom is + + \snippet examples/mainwindows/application/mainwindow.cpp 20 + + \section2 Use QString::arg() for Dynamic Text + + The QString::arg() functions offer a simple means for substituting + arguments: + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 4 + + In some languages the order of arguments may need to change, and this + can easily be achieved by changing the order of the % arguments. For + example: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 5 + + produces the correct output in English and Norwegian: + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 6 + + \section2 Produce Translations + + Once you are using tr() throughout an application, you can start + producing translations of the user-visible text in your program. + + The \l{Qt Linguist manual} provides further information about + Qt's translation tools, \e{Qt Linguist}, \c lupdate and \c + lrelease. + + Translation of a Qt application is a three-step process: + + \list 1 + + \o Run \c lupdate to extract translatable text from the C++ + source code of the Qt application, resulting in a message file + for translators (a TS file). The utility recognizes the tr() + construct and the \c{QT_TR*_NOOP()} macros described above and + produces TS files (usually one per language). + + \o Provide translations for the source texts in the TS file, using + \e{Qt Linguist}. Since TS files are in XML format, you can also + edit them by hand. + + \o Run \c lrelease to obtain a light-weight message file (a QM + file) from the TS file, suitable only for end use. Think of the TS + files as "source files", and QM files as "object files". The + translator edits the TS files, but the users of your application + only need the QM files. Both kinds of files are platform and + locale independent. + + \endlist + + Typically, you will repeat these steps for every release of your + application. The \c lupdate utility does its best to reuse the + translations from previous releases. + + Before you run \c lupdate, you should prepare a project file. Here's + an example project file (\c .pro file): + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 7 + + When you run \c lupdate or \c lrelease, you must give the name of the + project file as a command-line argument. + + In this example, four exotic languages are supported: Danish, + Finnish, Norwegian and Swedish. If you use \l{qmake}, you usually + don't need an extra project file for \c lupdate; your \c qmake + project file will work fine once you add the \c TRANSLATIONS + entry. + + In your application, you must \l QTranslator::load() the translation + files appropriate for the user's language, and install them using \l + QCoreApplication::installTranslator(). + + \c linguist, \c lupdate and \c lrelease are installed in the \c bin + subdirectory of the base directory Qt is installed into. Click Help|Manual + in \e{Qt Linguist} to access the user's manual; it contains a tutorial + to get you started. + + \target qt-itself + Qt itself contains over 400 strings that will also need to be + translated into the languages that you are targeting. You will find + translation files for French, German and Simplified Chinese in + \c{$QTDIR/translations}, as well as a template for translating to + other languages. (This directory also contains some additional + unsupported translations which may be useful.) + + Typically, your application's \c main() function will look like + this: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 8 + + Note the use of QLibraryInfo::location() to locate the Qt translations. + Developers should request the path to the translations at run-time by + passing QLibraryInfo::TranslationsPath to this function instead of + using the \c QTDIR environment variable in their applications. + + \section2 Support for Encodings + + The QTextCodec class and the facilities in QTextStream make it easy to + support many input and output encodings for your users' data. When an + application starts, the locale of the machine will determine the 8-bit + encoding used when dealing with 8-bit data: such as for font + selection, text display, 8-bit text I/O, and character input. + + The application may occasionally require encodings other than the + default local 8-bit encoding. For example, an application in a + Cyrillic KOI8-R locale (the de-facto standard locale in Russia) might + need to output Cyrillic in the ISO 8859-5 encoding. Code for this + would be: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 9 + + For converting Unicode to local 8-bit encodings, a shortcut is + available: the QString::toLocal8Bit() function returns such 8-bit + data. Another useful shortcut is QString::toUtf8(), which returns + text in the 8-bit UTF-8 encoding: this perfectly preserves + Unicode information while looking like plain ASCII if the text is + wholly ASCII. + + For converting the other way, there are the QString::fromUtf8() and + QString::fromLocal8Bit() convenience functions, or the general code, + demonstrated by this conversion from ISO 8859-5 Cyrillic to Unicode + conversion: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 10 + + Ideally Unicode I/O should be used as this maximizes the portability + of documents between users around the world, but in reality it is + useful to support all the appropriate encodings that your users will + need to process existing documents. In general, Unicode (UTF-16 or + UTF-8) is best for information transferred between arbitrary people, + while within a language or national group, a local standard is often + more appropriate. The most important encoding to support is the one + returned by QTextCodec::codecForLocale(), as this is the one the user + is most likely to need for communicating with other people and + applications (this is the codec used by local8Bit()). + + Qt supports most of the more frequently used encodings natively. For a + complete list of supported encodings see the \l QTextCodec + documentation. + + In some cases and for less frequently used encodings it may be + necessary to write your own QTextCodec subclass. Depending on the + urgency, it may be useful to contact Qt's technical support team or + ask on the \c qt-interest mailing list to see if someone else is + already working on supporting the encoding. + + \keyword localization + + \section2 Localize + + Localization is the process of adapting to local conventions, for + example presenting dates and times using the locally preferred + formats. Such localizations can be accomplished using appropriate tr() + strings. + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 11 + + In the example, for the US we would leave the translation of + "AMPM" as it is and thereby use the 12-hour clock branch; but in + Europe we would translate it as something else and this will make + the code use the 24-hour clock branch. + + For localized numbers use the QLocale class. + + Localizing images is not recommended. Choose clear icons that are + appropriate for all localities, rather than relying on local puns or + stretched metaphors. The exception is for images of left and right + pointing arrows which may need to be reversed for Arabic and Hebrew + locales. + + \section1 Dynamic Translation + + Some applications, such as Qt Linguist, must be able to support changes + to the user's language settings while they are still running. To make + widgets aware of changes to the installed QTranslators, reimplement the + widget's \l{QWidget::changeEvent()}{changeEvent()} function to check whether + the event is a \l{QEvent::LanguageChange}{LanguageChange} event, and update + the text displayed by widgets using the \l{QObject::tr()}{tr()} function + in the usual way. For example: + + \snippet doc/src/snippets/code/doc_src_i18n.qdoc 12 + + All other change events should be passed on by calling the default + implementation of the function. + + The list of installed translators might change in reaction to a + \l{QEvent::LocaleChange}{LocaleChange} event, or the application might + provide a user interface that allows the user to change the current + application language. + + The default event handler for QWidget subclasses responds to the + QEvent::LanguageChange event, and will call this function when necessary; + other application components can also force widgets to update themselves + by posting the \l{QEvent::LanguageChange}{LanguageChange} event to them. + + \section1 Translating Non-Qt Classes + + It is sometimes necessary to provide internationalization support for + strings used in classes that do not inherit QObject or use the Q_OBJECT + macro to enable translation features. Since Qt translates strings at + run-time based on the class they are associated with and \c lupdate + looks for translatable strings in the source code, non-Qt classes must + use mechanisms that also provide this information. + + One way to do this is to add translation support to a non-Qt class + using the Q_DECLARE_TR_FUNCTIONS() macro; for example: + + \snippet doc/src/snippets/i18n-non-qt-class/myclass.h 0 + \dots + \snippet doc/src/snippets/i18n-non-qt-class/myclass.h 1 + + This provides the class with \l{QObject::}{tr()} functions that can + be used to translate strings associated with the class, and makes it + possible for \c lupdate to find translatable strings in the source + code. + + Alternatively, the QCoreApplication::translate() function can be called + with a specific context, and this will be recognized by \c lupdate and + Qt Linguist. + + \section1 System Support + + Some of the operating systems and windowing systems that Qt runs on + only have limited support for Unicode. The level of support available + in the underlying system has some influence on the support that Qt can + provide on those platforms, although in general Qt applications need + not be too concerned with platform-specific limitations. + + \section2 Unix/X11 + + \list + \o Locale-oriented fonts and input methods. Qt hides these and + provides Unicode input and output. + \o Filesystem conventions such as + \l{http://www.ietf.org/rfc/rfc2279.txt}{UTF-8} + are under development in some Unix variants. All Qt file + functions allow Unicode, but convert filenames to the local + 8-bit encoding, as this is the Unix convention (see + QFile::setEncodingFunction() to explore alternative + encodings). + \o File I/O defaults to the local 8-bit encoding, + with Unicode options in QTextStream. + \o Many Unix distributions contain only partial support for some locales. + For example, if you have a \c /usr/share/locale/ja_JP.EUC directory, + this does not necessarily mean you can display Japanese text; you also + need JIS encoded fonts (or Unicode fonts), and the + \c /usr/share/locale/ja_JP.EUC directory needs to be complete. For + best results, use complete locales from your system vendor. + \endlist + + \section2 Windows + + \list + \o Qt provides full Unicode support, including input methods, fonts, + clipboard, drag-and-drop and file names. + \o File I/O defaults to Latin1, with Unicode options in QTextStream. + Note that some Windows programs do not understand big-endian + Unicode text files even though that is the order prescribed by + the Unicode Standard in the absence of higher-level protocols. + \o Unlike programs written with MFC or plain winlib, Qt programs + are portable between Windows 98 and Windows NT. + \e {You do not need different binaries to support Unicode.} + \endlist + + \section2 Mac OS X + + For details on Mac-specific translation, refer to the Qt/Mac Specific Issues + document \l{Qt for Mac OS X - Specific Issues#Translating the Application Menu and Native Dialogs}{here}. +*/ diff --git a/doc/src/internationalization/linguist-manual.qdoc b/doc/src/internationalization/linguist-manual.qdoc new file mode 100644 index 0000000..a67d65a --- /dev/null +++ b/doc/src/internationalization/linguist-manual.qdoc @@ -0,0 +1,1512 @@ +/**************************************************************************** +** +** 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 linguist-manual.html + \title Qt Linguist Manual + \ingroup qttools + + \startpage {index.html}{Qt Reference Documentation} + \nextpage Qt Linguist Manual: Release Manager + + \keyword Qt Linguist + + Qt provides excellent support for translating applications into local + languages. This Guide explains how to use Qt's translation tools for + each of the roles involved in translating an application. The Guide + begins with a brief overview of the issues that must be considered, + followed by chapters devoted to each role and the supporting tools + provided. + + The \l{linguist-manager.html}{Release Manager} chapter is aimed + at the person with overall responsibility for the release of the + application. They will typically coordinate the work of the + software engineers and the translator. The chapter describes the + use of two tools. The \l{lupdate} tool is used to synchronize + source code and translations. The \l{lrelease} tool is used to + create runtime translation files for use by the released + application. + + The \l{linguist-translators.html}{Translators} chapter is for + translators. It describes the use of the \QL tool. + No computer knowledge beyond the ability to start a program and + use a text editor or word processor is required. + + The \l{linguist-programmers.html}{Programmers} chapter is for Qt + programmers. It explains how to create Qt applications that are + able to use translated text. It also provides guidance on how to + help the translator identify the context in which phrases appear. + This chapter's three short tutorials cover everything the + programmer needs to do. + + \section1 Overview of the Translation Process + + Most of the text that must be translated in an application program + consists of either single words or short phrases. These typically + appear as window titles, menu items, pop-up help text (balloon help), + and labels to buttons, check boxes and radio buttons. + + The phrases are entered into the source code by the programmer in + their native language using a simple but special syntax to identify + that the phrases require translation. The Qt tools provide context + information for each of the phrases to help the translator, and the + programmer is able to add additional context information to phrases + when necessary. The release manager generates a set of translation + files that are produced from the source files and passes these to the + translator. The translator opens the translation files using \QL, + enters their translations and saves the results back into + the translation files, which they pass back to the release manager. + The release manager then generates fast compact versions of these + translation files ready for use by the application. The tools are + designed to be used in repeated cycles as applications change and + evolve, preserving existing translations and making it easy to + identify which new translations are required. \QL also + provides a phrase book facility to help ensure consistent + translations across multiple applications and projects. + + Translators and programmers must address a number of issues because + of the subtleties and complexities of human language: + + \list + + \o A single phrase may need to be translated into several + different forms depending on context, e.g. \e open in English + might become \e{\ouml\c{}ffnen}, "open file", or \e aufbauen, + "open internet connection", in German. + + \o Keyboard accelerators may need to be changed but without + introducing conflicts, e.g. "\&Quit" in English becomes "Avslutt" + in Norwegian which doesn't contain a "Q". We cannot use a letter + that is already in use - unless we change several accelerators. + + \o Phrases that contain variables, for example, "The 25 files + selected will take 63 seconds to process", where the two numbers + are inserted programmatically at runtime may need to be reworded + because in a different language the word order and therefore the + placement of the variables may have to change. + + \endlist + + The Qt translation tools provide clear and simple solutions to these + issues. + + Chapters: + + \list + \o \l{Qt Linguist Manual: Release Manager}{Release Manager} + \o \l{Qt Linguist Manual: Translators}{Translators} + \o \l{Qt Linguist Manual: Programmers}{Programmers} + \o \l{Qt Linguist Manual: TS File Format}{TS File Format} + \endlist + + \QL and \c lupdate are able to import and export XML Localization + Interchange File Format (XLIFF) files, making it possible to take + advantage of tools and translation services that work with this + format. See the \l{Qt Linguist Manual: Translators} {Translators} + section for more information on working with these files. + + \table + + \row \o{1,2} \inlineimage wVista-Cert-border-small.png + \o \e{Qt Linguist 4.3 is Certified for Windows Vista} + + \row \o Windows Vista and the Windows Vista Start button are + trademarks or registered trademarks of Microsoft Corporation in + the United States and/or other countries. + + \endtable +*/ + +/*! + \page linguist-manager.html + \title Qt Linguist Manual: Release Manager + + \contentspage {Qt Linguist Manual}{Contents} + \previouspage Qt Linguist Manual + \nextpage Qt Linguist Manual: Translators + + \keyword lupdate + \keyword lrelease + + Two tools are provided for the release manager, \l lupdate and \l + lrelease. These tools can process \l qmake project files, or operate + directly on the file system. + + \section1 Qt Project Files + + The easiest method to use \l{#lupdate} {lupdate} and \l{#lrelease} + {lrelease} is by specifing a \c .pro Qt project file. There must + be an entry in the \c TRANSLATIONS section of the project file for + each language that is additional to the native language. A typical + entry looks like this: + + \snippet examples/linguist/arrowpad/arrowpad.pro 1 + + Using a locale within the translation file name is useful for + determining which language to load at runtime. This is explained + in the \l{linguist-programmers.html} {Programmers} chapter. + + An example of a complete \c .pro file with four translation source + files: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 0 + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1 + + QTextCodec::setCodecForTr() makes it possible to choose a 8-bit + encoding for literal strings that appear within \c tr() calls. + This is useful for applications whose source language is, for + example, Chinese or Japanese. If no encoding is set, \c tr() uses + Latin1. + + If you do use the QTextCodec::codecForTr() mechanism in your + application, \QL needs you to set the \c CODECFORTR + entry in the \c .pro file as well. For example: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 1 + + Also, if your compiler uses a different encoding for its runtime + system as for its source code and you want to use non-ASCII + characters in string literals, you will need to set the \c + CODECFORSRC. For example: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 2 + + Microsoft Visual Studio 2005 .NET appears to be the only compiler + for which this is necessary. However, if you want to write + portable code, we recommend that you avoid non-ASCII characters + in your source files. You can still specify non-ASCII characters + portably using escape sequences, for example: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 3 + + \target lupdate manual + \section1 lupdate + + Usage: \c {lupdate myproject.pro} + + \l lupdate is a command line tool that finds the translatable + strings in the specified source, header and \e {Qt Designer} + interface files, and produces or updates \c .ts translation + files. The files to process and the files to update can be set at + the command line, or provided in a \c .pro file specified as an + command line argument. The produced translation files are given to + the translator who uses \QL to read the files and insert the + translations. + + Companies that have their own translators in-house may find it + useful to run \l lupdate regularly, perhaps monthly, as the + application develops. This will lead to a fairly low volume of + translation work spread evenly over the life of the project and + will allow the translators to support a number of projects + simultaneously. + + Companies that hire in translators as required may prefer to run + \l lupdate only a few times in the application's life cycle, the + first time might be just before the first test phase. This will + provide the translator with a substantial single block of work and + any bugs that the translator detects may easily be included with + those found during the initial test phase. The second and any + subsequent \l lupdate runs would probably take place during the + final beta phase. + + The TS file format is a simple human-readable XML format that + can be used with version control systems if required. \c lupdate + can also process Localization Interchange File Format (XLIFF) + format files; files in this format typically have file names that + end with the \c .xlf suffix. + + Pass the \c -help option to \c lupdate to obtain the list of + supported options: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 4 + + \QL is also able to import and export XLIFF files. See the + \l{Qt Linguist Manual: Translators}{Translators} section for more + information. + + \section1 lrelease + + Usage: \c {lrelease myproject.pro} + + \l lrelease is a command line tool that produces QM files out + of TS files. The QM file format is a compact binary format + that is used by the localized application. It provides extremely + fast lookups for translations. The TS files \l lrelease + processes can be specified at the command line, or given + indirectly by a Qt \c .pro project file. + + This tool is run whenever a release of the application is to be + made, from initial test version through to final release + version. If the QM files are not created, e.g. because an + alpha release is required before any translation has been + undertaken, the application will run perfectly well using the text + the programmers placed in the source files. Once the QM files + are available the application will detect them and use them + automatically. + + Note that lrelease will only incorporate translations that are + marked as "finished". Otherwise the original text will be used + instead. + + Pass the \c -help option to \c lrelease to obtain the list of + supported options: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 5 + + \section1 Missing Translations + + Both \l lupdate and \l lrelease may be used with TS + translation source files which are incomplete. Missing + translations will be replaced with the native language phrases at + runtime. +*/ + +/*! + \page linguist-translators.html + \title Qt Linguist Manual: Translators + + \contentspage {Qt Linguist Manual}{Contents} + \previouspage Qt Linguist Manual: Release Manager + \nextpage Qt Linguist Manual: Programmers + + Contents + + \tableofcontents + + \section1 The One Minute Guide to Using Qt Linguist + + \QL is a tool for adding translations to Qt applications. Run \QL + from the taskbar menu, or by double clicking the desktop icon, or + by entering the command \c {linguist} at the command line. Once + \QL has started, choose \menu{File|Open} from the \l{menubar} + {menu bar} and select a translation source (TS file) to + load. If you do not have a TS file, see the \l {Qt Linguist + Manual: Release Manager} {release manager manual} to learn how to + generate one. + + The \QL main window is divided into several, dockable subwindows + arranged around a central \l{The Translation Area} {translation + area}. The \l{Context Window} {context list} is normally shown + on the left, and the \l{Sources and Forms Window} {source code}, + \l{Strings Window} {string list}, and either the \l{Phrases and + Guesses Window} {prhrases and guesses}, or the \l{Warnings Window} + {warnings} are shown above and below the \l{The Translation Area} + {translations area}. + + With a translation file loaded, select a context from the + \l{Context Window} {context list} on the left. Selecting a context + loads the translatable strings found in that context into the + \l{Strings Window} {string list}. Selecting one of the strings + copies that string as the \key{Source text} in the \l{The + Translation Area} {translation area}. Click in the text entry + widget below the copied string and type your translation for that + string. To accept the translation, either press the green + \key{tick mark} button on the toolbar, or click the icon to the + left of the selected source string in the string list. Repeat this + process until all strings in the string list are marked with + \inlineimage linguist-check-on.png + or + \inlineimage linguist-check-warning.png + . Then select the next context and continue. + + Translation options are shown in the \l{Phrases and Guesses + Window} {phrases and guesses window}. If the phrases and guesses + window is not visible, click the \key{Phrases and guesses} tab at + the bottom of the main window. The phrases and guesses window + shows possible translations for the current string. These + translation "guesses" have been read from phrase books + (\menu{Phrases|Open Phrase Book...}). The current string's + current translation is also shown here. To select a guess, double + click it in the prases and guesses window or use the keyboard + shortcut shown to the right of the guess. + + \QL can automatically check whether your translation strings pass + a list of \l{Validation Tests} {validation tests}. Validation test + failures are shown in the \l{Warnings Window} {warnings window}. + If the warnings window is not visible, click the \key{Warnings} + tab at the bottom of the main window. + + Finally, if the source code for the contexts is accessible, the + \l{Sources and Forms Window} {source code window} shows the + context where the current string is used. If the source code + window is not visible, click the \key{Sources and Forms} tab at + the bottom of the main window. + + At the end of the session choose \menu{File|Save} from the menu + bar and then \menu{File|Exit} to quit. + + \section1 The Qt Linguist Window + + \image linguist-linguist.png "Linguist UI Snapshot" + + This \QL main window is divided into dockable subwindows arranged + around a central \l{The Translation Area} {translation area}. The + subwindows are: \l{Context Window} {Context}, \l{Sources and Forms + Window} {Sources and Forms}, \l{Strings Window} {Strings}, + \l{Phrases and Guesses Window} {Phrases and guesses}, and + \l{Warnings Window} {Warnings} (hidden in the UI snapsot). The + translation area is always visible, but the dockable subwindows + can be activated or deactivated in the \menu{View|Views} menu, and + dragged around by their title bars and dropped in the translation + area or even outside the main window. + + \section2 Context Window + + The context window normally appears on the left side of the main + window. It lists the contexts in which strings to be translated + appear. The column labeled \e{Context} lists the context names in + alphabetical order. Each context is the name of a subclass of + QObject. There can also be a context for QObject itself, which + contains strings passed to the static function QObject::tr(). + There can also be an \e{<unnamed context>}, which contains strings + that aren't in a subclass of QObject. + + To the left of the \e{Context} column is a column labeled + \inlineimage linguist-check-obsolete.png + . This column uses the following list of icons to summarize the + current translation state for each context: + + \list + + \o \inlineimage linguist-check-on.png + All strings in the context have been translated, and all the + translations passed the \l{Validation Tests} {validation tests}. + + \o \inlineimage linguist-check-warning.png + All strings in the context have been translated or marked as + translated, but at least one translation failed the \l{Validation + Tests} {validation tests}. + + \o \inlineimage linguist-check-off.png + At least one string in the context has not been translated or is + not marked as translated. + + \o \inlineimage linguist-check-obsolete.png + None of the translated strings still appears in the context. This + usually means the context itself no longer exists in the + application. + + \endlist + + To the right of the \e{Context} column is the \e{Items} column. + Each entry in the \e{Items} column is a pair of numbers separated + by a slash ("/"). The number to the right of the slash is the + number of translatable strings in the context. The number to the + left of the slash is the number of those strings that currently + have translations. i.e., if the numbers are equal, all the + translatable strings in the context have translations. + + In the UI snapshot above, the \bold{MessageEditor} context is + selected. Its \e{Items} entry shows \bold{18/18}, which means it + has 18 translatable strings and all 18 strings currently have + translations. However, the context has been marked with the + \inlineimage linguist-check-warning.png + icon, which means that at least one of the current translations + failed a \l{Validation Tests} {validation test}. In the + \l{Strings Window} {strings window} to the right, we see that one + of the strings is indeed marked with the + \inlineimage linguist-check-warning.png + icon. + + The context window is a dockable window. It can be dragged to + another position in the main window, or dragged out of the main + window to be a separate window. If you move the context window, + \QL remembers the new position and puts the context window there + whenever you start the program. If the context window has been + closed, it can be restored by pressing \key{F6}. + + \section2 Strings Window + + The strings window normally appears on the right in the main + window, above the \l{The Translation Area} {translation area}. Its + \e{Source text} column lists all the translatable strings found in + the current context. Selecting a string makes that string the + current string in the \l{The Translation Area} {translation area}. + + To the left of the \e{Source text} column is a column labeled + \inlineimage linguist-check-obsolete.png + . This column is similar to the one in the \l{Context Window} + {context window}, but here you can click on the icon to change the + translation acceptance state for each string in the list. A tick + mark, green or yellow, means the string has been translated and + the user has accepted the translation. A question mark means + either that the user has not accepted the string's translation or + that the string doesn't have a translation. The table below + explains the acceptance states and their icons: + + \target String Translation States + + \table + \header + \o State + \o Icon + \o Description + + \row + \o Accepted/Correct + \o \inlineimage linguist-check-on.png + \o The source string has a translation (possibly empty); the user + has accepted the translation, and the translation passes all the + \l{Validation Tests} {validation tests}. If the translation is + empty, the user has chosen to leave it empty. Click the icon to + revoke acceptance of the translation and decrement the number of + accepted translations in the \e{Items} column of the \l{Context + Window} {context list} by 1. The state is reset to + \inlineimage linguist-check-off.png + if the string has a translation, or to + \inlineimage linguist-check-empty.png + if the string's translation is empty. If \c{lupdate} changes the + contents of a string, its acceptance state is automatically reset + to \inlineimage linguist-check-off.png + . + + \row + \o Accepted/Warnings + \o \inlineimage linguist-check-warning.png + \o The user has accepted the translation, but the translation does + not pass all the \l{Validation Tests} {validation tests}. The + validation test failures are shown in the \l{Warnings Window} + {warnings window}. Click the icon to revoke acceptance of the + translation. The state is reset to \inlineimage linguist-danger.png + , and the number of accepted translations in the \e{Items} column + of the \l{Context Window} {context list} is decremented by 1. + + \row + \o Not Accepted + \o \inlineimage linguist-check-off.png + \o The string has a non-empty translation that passes all the + \l{Validation Tests} {validation tests}, but the user has not yet + accepted the translation. Click the icon or press \key{Ctrl+Enter} + to accept the translation. The state is reset to + \inlineimage linguist-check-on.png + , and the number of accepted translations in the \e{Items} column + of the \l{Context Window} {context list} is incremented by 1. + + \row + \o No Translation + \o \inlineimage linguist-check-empty.png + \o The string does not have a translation. Click the icon to + accpet the empty translation anyway. The state is reset to + \inlineimage linguist-check-on.png + , and the number of accepted translations in the \e{Items} column + of the \l{Context Window} {context list} is incremented by 1. + + \row + \o Validation Failures + \o \inlineimage linguist-danger.png + \o The string has a translation, but the translation does not + pass all the \l{Validation Tests} {validation tests}. Validation + test failures are shown in the \l{Warnings Window} {warnings} + window. Click on the icon or press \key{Ctrl+Return} to accept + the translation even with validation failures. The state is + reset to \inlineimage linguist-check-warning.png + . We recommended editing the translation to fix the causes of + the validation failures. The state will reset automatically to + \inlineimage linguist-check-off.png + , when all the failures have been fixed. + + \row + \o Obsolete + \o \inlineimage linguist-check-obsolete.png + \o The string is obsolete. It is no longer used in the context. + See the \l{Qt Linguist Manual: Release Manager} {Release Manager} + for instructions on how to remove obsolete messages from the file. + + \endtable + + The string list is a dockable subwindow. If it has been closed, + restored it by pressing \key{F7}. + + \section2 The Translation Area + + The translation area is in the middle of the main window, to the + right of the \l{Context Window} {context list}. It doesn't have a + title bar, so you can't drag it around. Instead, you drag and drop + the other subwindows to arrange them around the translation area. + The string currently selected in the \l{Strings Window} {string + list} appears at the top of the translation area, under the label + \menu{Source text}. Note that all blanks in the source text have + been replaced by "." so the translator can see the spacing + required within the text. + + If the developer provides a \l{QObject::tr()} {disambiguating + comment}, it will appear below the source text area, under the + label \menu{Developer comments}. + + Below the source text and optional developer comments are two text + entry widgets for the translator, one for entering the translation + of the current string, and one for the translator to enter an + optional comment to be read by other translators. + + When \l{Translating Multiple Languages Simultaneously} {multiple + languages} are being translated, this sequence of fields is + repeated for each language. See aso \l {Changing the Target + Locale}. + + \section2 Phrases and Guesses Window + + If the current string in the \l{Strings Window} {string list} + appears in one or more of the \l{Phrase Books} {phrase books} + that have been loaded, the current string and its phrase book + translation(s) will be listed in this window. If the current + string is the same as, or similar to, another string that has + already been translated, that other string and its translation + will also be listed in this window. + + To use a translation from the Phrases and Guesses Window, you can + double click the translation, and it will be copied into the + translation area, or you can use the translation's \e{Guess} + hotkey on the right. You can also press \key{F10} to move the + focus to the Phrases and Guesses Window, then use the up and down + arrow keys to find the desired translation, and and then press + \key{Enter} to copy it to the translation area. If you decide + that you don't want to copy a phrase after all, press \key{Esc} to + return the focus to the translation area. + + The Phrases and Guesses Window is a dockable window. If it has + been closed, it can be made visible by pressing the \e{Phrases and + guesses} tab at the bottom of the window, or by pressing + \key{F10}. + + \section2 Sources and Forms Window + + If the source files containing the translatable strings are + available to \QL, this window shows the source context of the + current string in the \l{Strings Window} {string list}. The source + code line containing the current string should be shown and + highlighted. If the file containing the source string is not + found, the expected absolute file path is shown. + + If the source context shows the wrong source line, it probably + means the translation file is out of sync with the source files. + To re-sync the translation file with the source files, see the + \l{lupdate manual} {lupdate manual}. + + The Sources and Forms window is a dockable window. If it has been + closed, it can be made visible again by pressing the \e{Sources + and Forms} tab at the bottom of the window, or by pressing + \key{F9}. + + \section2 Warnings Window + + If the translation you enter for the current string fails any of + the active \l{Validation Tests} {validation tests}, the failures + are listed in the warnings window. The first of these failure + messages is also shown in the status bar at the bottom of the main + window. Note that only \e{active} validation tests are + reported. To see which validation tests are currently active, or + to activate or deactivate tests, use the \menu{Validation} menu + from the \l{menubar}{menu bar}. + + The Warnings window is a dockable window. If it has been closed, + it can be made visible by pressing the \e{Warnings} tab at the + bottom of the window, or by pressing \key{F8}. + + \target multiple languages + \section2 Translating Multiple Languages Simultaneously + + Qt Linguist can now load and edit multiple translation files + simultaneously. One use for this is the case where you know two + languages better than you know English (Polish and Japanese, say), + and you are given an application's Polish translation file and + asked to update the application's Japanese translation file. You + are more comfortable translating Polish to Japanese than you are + translating English to Japanese. + + Below is the UI snapshot shown earlier, but this time with both + \e{Polish} and \e{Japanese} translation files loaded. + + \image linguist-linguist_2.png + + The first thing to notice is that the \l{The Translation Area} + {translation area} has text editing areas for both Polish and + Japanese, and these are color-coded for easier separation. + Second, the \l{Context Window} and the \l{Strings Window} both + have two clomuns labeled \inlineimage linguist-check-obsolete.png + instead of one, and although it may be hard to tell, these columns + are also color-coded with the same colors. The left-most column in + either case applies to the top-most language area (Polish above) + in the \l{The Translation Area} {translation area}, and the + right-most column applies to the bottom language area. + + The \e{Items} column in the \l{Context Window} combines the values + for both languages. The best way to see this is to look at the + value for the \bold{MessageEditor} context, which is the one + selected in the snapshot shown above. Recall that in the first UI + snapshot (Polish only), the numbers for this context were + \e{18/18}, meaning 18 translatable strings had been found in the + context, and all 18 strings had accepted translations. In the UI + snapshot above, the numbers for the \bold{MessageEditor} context + are now \e{1/18}, meaning that both languages have 18 translatable + strings for that context, but for Japanese, only 1 of the 18 + strings has an accepted translation. The + \inlineimage linguist-check-off.png + icon in the Japanese column means that at least one string in the + context doesn't have an accepted Japanese translation yet. In fact, + 17 of the 18 strings don't have accepted Japanese translations yet. + We will see \e{18/18} in the \e{Items} column when all 18 strings + have accepted translations for all the loaded translation files, + e.g., both Polish and Japanese in the snapshot. + + \section1 Common Tasks + + \section2 Leaving a Translation for Later + + If you wish to leave a translation press \key{Ctrl+L} (Next + Unfinished) to move to the next unfinished translation. To move to + the next translation (whether finished or unfinished) press + \key{Shift+Ctrl+L}. You can also navigate using the Translation + menu. If you want to go to a different context entirely, click the + context you want to work on in the Context list, then click the + source text in the \l{Strings Window} {string list}. + + \section2 Phrases That Require Multiple Translations Depending on Context + + The same phrase may occur in two or more contexts without conflict. Once + a phrase has been translated in one context, \QL notes + that the translation has been made and when the translator reaches a + later occurrence of the same phrase \QL will provide + the previous translation as a possible translation candidate in the + \l{Phrases and Guesses Window}. + + If a phrase occurs more than once in a particular context it will + only be shown once in \QL's \l{Context Window} {context list} and + the translation will be applied to every occurrence within the + context. If the same phrase needs to be translated differently + within the same context the programmer must provide a + distinguishing comment for each of the phrases concerned. If such + comments are used the duplicate phrases will appear in the + \l{Context Window} {context list}. The programmers comments will + appear in the \l{The Translation Area} {translation area} on a + light blue background. + + \section2 Changing Keyboard Accelerators + + A keyboard accelerator is a key combination that, when pressed, + causes an application to perform an action. There are two kinds of + keyboard accelerators: Alt key and Ctrl key accelerators. + + \section3 Alt Key Accellerators + + Alt key accelerators are used in menu selection and on buttons. + The underlined character in a menu item or button label signifies + that pressing the Alt key with the underlined character will + perform the same action as clicking the menu item or pressing the + button. For example, most applications have a \e{File} menu with + the "F" in the word "File" underlined. In these applications the + \e{File} menu can be invoked either by clicking the word "File" on + the menu bar or by pressing \e{Alt+F}. To identify an accelerator + key in the translation text ("File") precede it with an ampersand, + e.g. \e{\&File}. If a string to be translated has an ampersand in + it, then the translation for that string should also have an + ampersand in it, preferably in front of the same character. + + The meaning of an Alt key accelerator can be determined from the + phrase in which the ampersand is embedded. The translator can + change the character part of the Alt key accelerator, if the + translated phrase does not contain the same character or if that + character has already been used in the translation of some other + Alt key accelerator. Conflicts with other Alt key accelerators + must be avoided within a context. Note that some Alt key + accelerators, usually those on the menu bar, may apply in other + contexts. + + \section3 Ctrl Key Accelerators + + Ctrl key accelerators can exist independently of any visual + control. They are often used to invoke actions in menus that would + otherwise require multiple keystrokes or mouse clicks. They may + also be used to perform actions that do not appear in any menu or + on any button. For example, most applications that have a \e{File} + menu have a \e{New} submenu item in the \e{File} menu. The \e{New} + item might appear as "\underline{N}ew Ctrl+N" in the \e{File} + menu, meaning the \e{New} menu can be invoked by simply pressing + \key{Ctrl+N}, instead of either clicking \e{File} with the mouse + and then clicking \e{New} with the mouse, or by entering \e{Alt+F} + and \e{N}. + + Each Ctrl key accelerator is shown in the \l{Strings Window} + {string list} as a separte string, e.g. \key{Ctrl+Enter}. Since + the string doesn't have a context to give it meaning, e.g. like + the context of the phrase in which an Alt key accelerator appears, + the translator must rely on the UI developer to include a + \l{QObject::tr()} {disambiguation comment} to explain the action + the Ctrl key accelerator is meant to perform. This disambiguating + comment (if provided by the developer) will appear under + \e{Developer comments} in the \l{The Translation Area} + {translation area} under the \e{Source text} area. + + Ideally Ctrl key accelerators are translated simply by copying + them directly using \e {Copy from source text} in the + \menu{Translation} menu. However, in some cases the character will + not make sense in the target language, and it must be + changed. Whichever character (alpha or digit) is chosen, the + translation must be in the form "Ctrl+" followed by the upper case + character. \e{Qt} will automatically display the correct name at + runtime. As with Alt key accelerators, if the translator changes + the character, the new character must not conflict with any other + Ctrl key accelerator. + + \warning Do not translate the "Alt", "Ctrl" or "Shift" parts of + the accelerators. \e{Qt} relies on these strings being there. For + supported languages, \e {Qt} automatically translates these + strings. + + \section2 Handling Numbered Arguments + + Some phrases contain numbered arguments. A numbered argument is a + placeholder that will be replaced with text at runtime. A numbered + argument appears in a source string as a percent sign followed by + a digit. Consider an example: \c{After processing file %1, file %2 + is next in line}. In this string to be translated, \c{%1} and + \c{%2} are numbered arguments. At runtime, \c{%1} and \c{%2} will + be replaced with the first and next file names respectively. The + same numbered arguments must appear in the translation, but not + necessarily in the same order. A German translation of the string + might reverse the phrases, e.g. \c{Datei %2 wird bearbeitet, wenn + Datei %1 fertig ist}. Both numbered arguments appear in the + translation, but in the reverse order. \c{%i} will always be + replaced by the same text in the translation stringss, regardless + of where argument \e{i} appears in the argument sequence in the + source string. + + \section2 Reusing Translations + + If the translated text is similar to the source text, choose the + \e {Copy from source text} entry in the \menu Translation menu (press + \key{Ctrl+B}) which will copy the source text into the + \l{The Translation Area} {translation area}. + + \QL automatically lists possible translations from any open + \l{Phrase Books} {phrase books} in the \l{Phrases and Guesses + Window}, as well as similar or identical phrases that have already + been translated. + + \section2 Changing the Target Locale + + \QL displays the target language in the \l{The Translation Area} + {translation area}, and adapts the number of input fields for + plural forms accordingly. If not explicitly set, \QL guesses the + target language and country by evaluating the translation source + file name: E.g. \c app_de.ts sets the target language to German, + and \c app_de_ch.ts sets the target language to German and the + target country to Switzerland (this also helps loading + translations for the current locale automatically; see + \l{linguist-programmers.html}{Programmers Manual} for details). + If your files do not follow this convention, you can also set the + locale information explicitly using \e {Translation File Settings} + in the \menu Edit menu. + + \image linguist-translationfilesettings.png + + \section1 Phrase Books + + A \QL phrase book is a set of source phrases, target + (translated) phrases, and optional definitions. Typically one phrase book + will be created per language and family of applications. Phrase books + are used to provide a common set of translations to help ensure consistency. + They can also be used to avoid duplication of effort since the translations + for a family of applications can be produced once in the phrase book. + If the translator reaches an untranslated phrase that is the same as a + source phrase in a phrase book, \QL will show the + phrase book entry in the \l {Phrases and Guesses Window}. + + \section2 Creating and Editing Phrase Books + + \image linguist-phrasebookdialog.png + + Before a phrase book can be edited it must be created or, if it already + exists, opened. Create a new phrase book by selecting + \menu{Phrase|New Phrase Book} from the menu bar. You must enter a + filename and may change the location of the file if you wish. A newly + created phrase book is automatically opened. Open an existing phrase + book by choosing \menu{Phrase|Open Phrase Book} from the menu bar. + + The phrase book contents can be displayed and changed by selecting + \menu{Phrase|Edit Phrase Book}, and then activating the phrase book you + want to work on. This will pop up the Phrase Book Dialog as shown + in the image above. To add a new phrase click the \gui{New Phrase} + button (or press Alt+N) and type in a new source phrase. Press Tab and + type in the translation. Optionally press Tab and enter a definition -- + this is useful to distinguish different translations of the same source + phrase. This process may be repeated as often as necessary. You can delete + a phrase by selecting it in the phrases list and clicking + Remove Phrase. Click the \gui Close button (press Esc) once you've finished + adding (and removing) phrases. + + \section2 Shortcuts for Editing Phrase Books + + You can also create a new phrase book entry directly out of the translation you + are working on: Clicking \menu{Phrases|Add to Phrase Book} or pressing + \key{Ctrl+T} will add the source text and the content of the first translation + field to the current phrase book. If multiple phrase books are loaded, + you have to specify the phrase book to add the entry to in a dialogue. + If you detect an error in a phrase book entry that is shown in the + \l{Phrases and Guesses Window}, you can also edit it in place by right + clicking on the entry, and selecting \menu{Edit}. After fixing the error + press \key{Return} to leave the editing mode. + + \section2 Batch Translation + + \image linguist-batchtranslation.png + + Use the batch translation feature of \QL to automatically + translate source texts that are also in a phrase book. Selecting + \menu{Tools|Batch Translation} will show you the batch translation dialog, + which let you configure which phrase books to use in what order during the + batch translation process. Furthermore you can set whether only entries + with no present translation should be considered, and whether batch translated + entries should be set to finished (see also \l {String Translation States}). + + \section1 Validation Tests + + \QL provides four kinds of validation tests for translations. + + \list 1 + \o \e {Accelerator validation} detects translated phrases + that do not have an ampersand when the source phrase does and vice + versa. + \o \e {Punctuation validation} detects differences in the + terminating punctuation between source and translated phrases when this + may be significant, e.g. warns if the source phrase ends with an + ellipsis, exclamation mark or question mark, and the translated phrase + doesn't and vice versa. + \o \e {Phrases validation} detects source phrases that are + also in the phrase book but whose translation differs from that given in + the phrase book. + \o \e {Place marker validation} detects whether the same variables + (like \c %1, \c %2) are used both in the source text and in the translation. + \endlist + + Validation may be switched on or off from the menu bar's + Validation item or using the toolbar buttons. Unfinished phrases + that fail validation are marked with an exclamation mark in the + source text pane. Finished phrases will get a yellow tick + instead. If you switch validation off and then switch it on later, + \QL will recheck all phrases and mark any that fail + validation. See also \l{String Translation States}. + + \section1 Form Preview + + \image linguist-previewtool.png + + Forms created by \e{Qt Designer} are stored in special UI files. + \QL can make use of these UI files to show the translations + done so far on the form itself. This of course requires access to the UI + files during the translation process. Activate + \menu{Tools|Open/Refresh Form Preview} to open the window shown above. + The list of UI files \QL has detected are displayed in the Forms + List on the left hand. If the path to the files has changed, you can load + the files manually via \menu{File|Open Form...}. Double-click on an entry + in the Forms List to display the Form File. Select \e{<No Translation>} from + the toolbar to display the untranslated form. + + \section1 Qt Linguist Reference + + + \section2 File Types + + \QL makes use of four kinds of files: + + \list + \o TS \e {translation source files} \BR are human-readable XML + files containing source phrases and their translations. These files are + usually created and updated by \l lupdate and are specific to an + application. + \o \c .xlf \e {XLIFF files} \BR are human-readable XML files that adhere + to the international XML Localization Interchange File Format. \QL + can be used to edit XLIFF files generated by other programs. For standard + Qt projects, however, only the TS file format is used. + \o QM \e {Qt message files} \BR are binary files that contain + translations used by an application at runtime. These files are + generated by \l lrelease, but can also be generated by \QL. + \o \c .qph \e {Qt phrase book files} \BR are human-readable XML + files containing standard phrases and their translations. These files + are created and updated by \QL and may be used by any + number of projects and applications. + \endlist + + \target menubar + \section2 The Menu Bar + + \image linguist-menubar.png + + \list + \o \gui {File} + \list + \o \gui {Open... Ctrl+O} \BR pops up an open file dialog from which a + translation source \c .ts or \c .xlf file can be chosen. + \o \gui {Recently opened files} \BR shows the TS files that + have been opened recently, click one to open it. + \o \gui {Save Ctrl+S} \BR saves the current translation source file. + \o \gui {Save As...} \BR pops up a save as file dialog so that the + current translation source file may be saved with a different + name, format and/or put in a different location. + \o \gui {Release} \BR create a Qt message QM file with the same base + name as the current translation source file. The release manager's + command line tool \l lrelease performs the same function on + \e all of an application's translation source files. + \o \gui {Release As...} \BR pops up a save as file dialog. The + filename entered will be a Qt message QM file of the translation + based on the current translation source file. The release manager's + command line tool \l lrelease performs the same function on + \e all of an application's translation source files. + \o \gui {Print... Ctrl+P} \BR pops up a print dialog. If you click + OK the translation source and the translations will be printed. + \o \gui {Exit Ctrl+Q} \BR closes \QL. + \endlist + + \o \gui {Edit} + \list + \o \gui {Undo Ctrl+Z} \BR undoes the last editing action in the + translation pane. + \o \gui {Redo Ctrl+Y} \BR redoes the last editing action in the + translation pane. + \o \gui {Cut Ctrl+X} \BR deletes any highlighted text in the + translation pane and saves a copy to the clipboard. + \o \gui {Copy Ctrl+C} \BR copies the highlighted text in the + translation pane to the clipboard. + \o \gui {Paste Ctrl+V} \BR pastes the clipboard text into the + translation pane. + \omit + \o \gui {Delete} \BR deletes the highlighted text in the + translation pane. + \endomit + \o \gui {Select All Ctrl+A} \BR selects all the text in the + translation pane ready for copying or deleting. + \o \gui {Find... Ctrl+F} \BR pops up the + Find dialog. When the dialog pops up + enter the text to be found and click the \gui {Find Next} button. + Source phrases, translations and comments may be searched. + \o \gui {Find Next F3} \BR finds the next occurrence of the text that + was last entered in the Find dialog. + \o \gui {Search and Translate...} \BR pops up the Search and + Replace Dialog. Use this dialog to translate the same text in multiple items. + \o \gui {Translation File Settings...} \BR let you configure the target + language and the country/region of a translation source file. + \endlist + + \o \gui {Translation} + \list + \o \gui {Prev Unfinished Ctrl+K} \BR moves to the nearest previous + unfinished source phrase (unfinished means untranslated or + translated but failed validation). + \o \gui {Next Unfinished Ctrl+L} \BR moves to the next unfinished source + phrase. + \o \gui {Prev Shift+Ctrl+K} \BR moves to the previous source phrase. + \o \gui {Next Shift+Ctrl+L} \BR moves to the next source phrase. + \o \gui {Done \& Next Ctrl+Enter} \BR mark this phrase as 'done' + (translated) and move to the next unfinished source phrase. + \o \gui {Copy from source text Ctrl+B} \BR copies the source text into + the translation. + \endlist + + \o \gui {Validation} (See \l{Validation Tests}) + \list + \o \gui {Accelerators} \BR toggles validation on or off for Alt + accelerators. + \o \gui {Ending Punctuation} \BR switches validation on or off + for phrase ending punctuation, e.g. ellipsis, exclamation mark, + question mark, etc. + \o \gui {Phrase Matches} \BR sets validation on or off for + matching against translations that are in the current phrase book. + \o \gui {Place Marker Matches} \BR sets validation on or off for + the use of the same place markers in the source and translation. + \endlist + + \o \gui {Phrases} (See the section \l {Phrase Books} for details.) + \list + + \o \gui {New Phrase Book... Ctrl+N} \BR pops up a save as file + dialog. You must enter a filename to be used for the phrase + book and save the file. Once saved you should open the phrase + book to begin using it. + + \o \gui {Open Phrase Book... Ctrl+H} \BR pops up an open file + dialog. Find and choose a phrase book to open. + + \o \gui {Close Phrase Book} \BR displays the list of phrase + books currently opened. Clicking on one of the items will + close the phrase book. If the phrase book has been modified, a + dialog box asks whether \QL should save the changes. + + \o \gui {Edit Phrase Book...} \BR displays the list of phrase + books currently opened. Clicking on one of the items will open + the \l{Creating and Editing Phrase Books}{Phrase Book Dialog} + where you can add, edit or delete phrases. + + \o \gui {Print Phrase Book...} \BR displays the list of phrase + books currently opened. Clicking on one of the items pops up a + print dialog. If you click OK the phrase book will be + printed. + + \o \gui {Add to Phrase Book Ctrl+T} \BR Adds the source text + and translation currently shown in the \l{The Translation + Area} {translation area} to a phrase book. If multiple phrase + books are loaded, a dialog box let you specify select one. + + \endlist + + \o \gui {Tools} + \list + + \o \gui {Batch Translation...} \BR Opens a \l{Batch + Translation}{dialog} which let you automatically insert + translations for source texts which are in a phrase book. + + \o \gui {Open/Refresh Form Preview F3} \BR Opens the \l{Form + Preview}. This window let you instantly see translations for + forms created with \QD. \endlist + + \o \gui {View} + \list + + \o \gui {Revert Sorting} \BR puts the items in the \l{Context + Window} {context list} and in the \l{Strings Window} {string + list} into their original order. + + \o \gui {Display Guesses} \BR turns the display of phrases and + guesses on or off. + + \o \gui {Statistics} \BR toggles the visibility of the + Statistics dialog. + + \o \gui {Views} \BR toggles the visibility of the \l{Context + Window}, \l{Strings Window}, \l{Phrases and Guesses Window}, + \l{Warnings Window}, or \l{Sources and Forms Window}. + + \o \gui {Toolbars} \BR toggles the visibility of the different + toolbars. + + \endlist + + \o \gui {Help} + \list + \o \gui {Manual F1} \BR opens this manual. + \o \gui {About Qt Linguist} \BR Shows information about \QL. + \o \gui {About Qt} \BR Shows information about \e{Qt}. + \o \gui {What's This? Shift+F1} \BR Click on one item in the main window + to get additional information about it. + \endlist + + \endlist + + \section2 The Toolbar + + \image linguist-toolbar.png + + \list + \o \inlineimage linguist-fileopen.png + \BR + Pops up the open file dialog to open a new translation source TS file. + + \o \inlineimage linguist-filesave.png + \BR + Saves the current translation source TS file. + + \o \inlineimage linguist-fileprint.png + \BR + Prints the current translation source TS file. + + \o \inlineimage linguist-phrasebookopen.png + \BR + Pops up the file open dialog to open a new phrase book \c .qph file. + + \o \inlineimage linguist-editundo.png + \BR + Undoes the last editing action in the translation pane. + + \o \inlineimage linguist-editredo.png + \BR + Redoes the last editing action in the translation pane. + + \o \inlineimage linguist-editcut.png + \BR + Deletes any highlighted text in the translation pane and save a copy to + the clipboard. + + \o \inlineimage linguist-editcopy.png + \BR + Copies the highlighted text in the translation pane to the clipboard. + + \o \inlineimage linguist-editpaste.png + \BR + Pastes the clipboard text into the translation pane. + + \o \inlineimage linguist-editfind.png + \BR + Pops up the Find dialog . + + \o \inlineimage linguist-prev.png + \BR + Moves to the previous source phrase. + + \o \inlineimage linguist-next.png + \BR + Moves to the next source phrase. + + \o \inlineimage linguist-prevunfinished.png + \BR + Moves to the previous unfinished source phrase. + + \o \inlineimage linguist-nextunfinished.png + \BR + Moves to the next unfinished source phrase. + + \o \inlineimage linguist-doneandnext.png + \BR + Marks the phrase as 'done' (translated) and move to the next + unfinished source phrase. + + \o \inlineimage linguist-validateaccelerators.png + \BR + Toggles accelerator validation on and off. + + \o \inlineimage linguist-validatepunctuation.png + \BR + Toggles phrase ending punctuation validation on and off. + + \o \inlineimage linguist-validatephrases.png + \BR + Toggles phrase book validation on or off. + + \o \inlineimage linguist-validateplacemarkers.png + \BR + Toggles place marker validation on or off. + + \endlist + +*/ + +/*! + \page linguist-programmers.html + \title Qt Linguist Manual: Programmers + + \contentspage {Qt Linguist Manual}{Contents} + \previouspage Qt Linguist Manual: Translators + \nextpage Qt Linguist Manual: TS File Format + + Support for multiple languages is extremely simple in Qt + applications, and adds little overhead to the programmer's workload. + + Qt minimizes the performance cost of using translations by + translating the phrases for each window as they are created. In most + applications the main window is created just once. Dialogs are often + created once and then shown and hidden as required. Once the initial + translation has taken place there is no further runtime overhead for + the translated windows. Only those windows that are created, + destroyed and subsequently created will have a translation + performance cost. + + Creating applications that can switch language at runtime is possible + with Qt, but requires a certain amount of programmer intervention and + will of course incur some runtime performance cost. + + \section1 Making the Application Translation-Aware + + Programmers should make their application look for and load the + appropriate translation file and mark user-visible text and Ctrl + keyboard accelerators as targets for translation. + + Each piece of text that requires translating requires context to help + the translator identify where in the program the text occurs. In the + case of multiple identical texts that require different translations, + the translator also requires some information to disambiguate the + source texts. Marking text for translation will automatically cause + the class name to be used as basic context information. In some cases + the programmer may be required to add additional information to help + the translator. + + \section2 Creating Translation Files + + Translation files consist of all the user-visible text and Ctrl key + accelerators in an application and translations of that text. + Translation files are created as follows: + + \list 1 + \o Run \l lupdate initially to generate the first set of TS + translation source files with all the user-visible text but no + translations. + \o The TS files are given to the translator who adds translations + using \QL. \QL takes care of any changed + or deleted source text. + \o Run \l lupdate to incorporate any new text added to the + application. \l lupdate synchronizes the user-visible text from the + application with the translations; it does not destroy any data. + \o Steps 2 and 3 are repeated as often as necessary. + \o When a release of the application is needed \l lrelease is run to + read the TS files and produce the QM files used by the + application at runtime. + \endlist + + For \l lupdate to work successfully, it must know which translation + files to produce. The files are simply listed in the application's \c + .pro Qt project file, for example: + + \snippet examples/linguist/arrowpad/arrowpad.pro 1 + + If your sources contain genuine non-Latin1 strings, \l lupdate needs + to be told about it in the \c .pro file by using, for example, + the following line: + + \code + CODECFORTR = UTF-8 + \endcode + + See the \l lupdate and \l lrelease sections. + + \section2 Loading Translations + + \snippet examples/linguist/hellotr/main.cpp 1 + \snippet examples/linguist/hellotr/main.cpp 3 + + This is how a simple \c main() function of a Qt application begins. + + \snippet examples/linguist/hellotr/main.cpp 1 + \snippet examples/linguist/hellotr/main.cpp 4 + + For a translation-aware application a translator object is created, a + translation is loaded and the translator object installed into the + application. + + \snippet examples/linguist/arrowpad/main.cpp 0 + \snippet examples/linguist/arrowpad/main.cpp 1 + + For non-Latin1 strings in the sources you will also need for example: + + \code + QTextCodec::setCodecForTr(QTextCodec::codecForName("utf8")); + \endcode + + In production applications a more flexible approach, for example, + loading translations according to locale, might be more appropriate. If + the TS files are all named according to a convention such as + \e appname_locale, e.g. \c tt2_fr, \c tt2_de etc, then the + code above will load the current locale's translation at runtime. + + If there is no translation file for the current locale the application + will fall back to using the original source text. + + Note that if you need to programmatically add translations at + runtime, you can reimplement QTranslator::translate(). + + \section2 Making the Application Translate User-Visible Strings + + User-visible strings are marked as translation targets by wrapping them + in a \c tr() call, for example: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 6 + + would become + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 7 + + All QObject subclasses that use the \c Q_OBJECT macro implement + the \c tr() function. + + Although the \c tr() call is normally made directly since it is + usually called as a member function of a QObject subclass, in + other cases an explicit class name can be supplied, for example: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 8 + + or + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 9 + + \section2 Distinguishing Identical Strings That Require Different Translations + + The \l lupdate program automatically provides a \e context for every + source text. This context is the class name of the class that contains + the \c tr() call. This is sufficient in the vast majority of cases. + Sometimes however, the translator will need further information to + uniquely identify a source text; for example, a dialog that contained + two separate frames, each of which contained an "Enabled" option would + need each identified because in some languages the translation would + differ between the two. This is easily achieved using the + two argument form of the \c tr() call, e.g. + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 10 + + and + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 11 + + Ctrl key accelerators are also translatable: + + \snippet examples/linguist/trollprint/mainwindow.cpp 2 + + It is strongly recommended that the two argument form of \c tr() is used + for Ctrl key accelerators. The second argument is the only clue the + translator has as to the function performed by the accelerator. + + \section2 Helping the Translator with Navigation Information + + In large complex applications it may be difficult for the translator to + see where a particular source text comes from. This problem can be + solved by adding a comment using the keyword \e TRANSLATOR which + describes the navigation steps to reach the text in question; e.g. + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 12 + + These comments are particularly useful for widget classes. + + \section2 Handling Plural Forms + + Qt includes a \c tr() overload that will make it very easy to + write "plural-aware" internationalized applications. This overload + has the following signature: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 17 + + Depending on the value of \c n, the \c tr() function will return a different + translation, with the correct grammatical number for the target language. + Also, any occurrence of \c %n is replaced with \c{n}'s value. For example: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 18 + + If a French translation is loaded, this will expand to "0 item + remplac\unicode{233}", "1 item remplac\unicode{233}", "2 items + remplac\unicode{233}s", etc., depending on \c{n}'s value. + And if no translation is loaded, the orignal string is used, with \c %n + replaced with count's value (e.g., "6 item(s) replaced"). + + To handle plural forms in the native language, you need to load a + translation file for this language, too. \l lupdate has the + \c -pluralonly command line option, which allows the creation of + TS files containing only entries with plural forms. + + See the \l{http://qt.nokia.com/doc/qq/}{Qt Quarterly} Article + \l{http://qt.nokia.com/doc/qq/qq19-plurals.html}{Plural Forms in Translations} + for further details on this issue. + + \section2 Coping With C++ Namespaces + + C++ namespaces and the \c {using namespace} statement can confuse + \l lupdate. It will interpret \c MyClass::tr() as meaning just + that, not as \c MyNamespace::MyClass::tr(), even if \c MyClass is + defined in the \c MyNamespace namespace. Runtime translation of + these strings will fail because of that. + + You can work around this limitation by putting a \e TRANSLATOR + comment at the beginning of the source files that use \c + MyClass::tr(): + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 13 + + After the comment, all references to \c MyClass::tr() will be + understood as meaning \c MyNamespace::MyClass::tr(). + + \section2 Translating Text That is Outside of a QObject Subclass + + \section3 Using QCoreApplication::translate() + + If the quoted text is not in a member function of a QObject subclass, + use either the tr() function of an appropriate class, or the + QCoreApplication::translate() function directly: + + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 14 + + \section3 Using QT_TR_NOOP() and QT_TRANSLATE_NOOP() + + If you need to have translatable text completely outside a function, + there are two macros to help: QT_TR_NOOP() and QT_TRANSLATE_NOOP(). + These macros merely mark the text for extraction by \l{lupdate}. + The macros expand to just the text (without the context). + + Example of QT_TR_NOOP(): + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 15 + + Example of QT_TRANSLATE_NOOP(): + \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 16 + + \section1 Tutorials + + Three tutorials are presented: + + \list 1 + \o \l{linguist/hellotr}{Hello tr()} demonstrates the creation of + a \l QTranslator object. It also shows the simplest use of + the \c tr() function to mark user-visible source text for + translation. + + \o \l{linguist/arrowpad}{Arrow Pad} explains how to make the application load the + translation file applicable to the current locale. It also shows the + use of the two-argument form of \c tr() which provides additional + information to the translator. + + \o \l{linguist/trollprint}{Troll Print} explains how + identical source texts can be distinguished even when they occur in + the same context. This tutorial also discusses how the translation + tools help minimize the translator's work when an application is + upgraded. + \endlist + + These tutorials cover all that you need to know to prepare your Qt + applications for translation. + + At the beginning of a project add the translation source files to be + used to the project file and add calls to \l lupdate and \l lrelease to + the makefile. + + During the project all the programmer must do is wrap any user-visible + text in \c tr() calls. They should also use the two argument form for + Ctrl key accelerators, or when asked by the translator for the cases + where the same text translates into two different forms in the same + context. The programmer should also include \c TRANSLATION comments to + help the translator navigate the application. +*/ + +/*! + \page linguist-ts-file-format.html + \title Qt Linguist Manual: TS File Format + + \contentspage {Qt Linguist Manual}{Contents} + \previouspage Qt Linguist Manual: Programmers + + The TS file format used by \QL is described by the + \l{http://www.w3.org/TR/1998/REC-xml-19980210}{DTD} presented below, + which we include for your convenience. Be aware that the format + may change in future Qt releases. + + \quotefile tools/linguist/shared/ts.dtd + +*/ |