diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/src/development/qmake-manual.qdoc | 29 | ||||
-rw-r--r-- | doc/src/examples/ftp.qdoc | 2 | ||||
-rw-r--r-- | doc/src/examples/stickman.qdoc | 9 | ||||
-rw-r--r-- | doc/src/frameworks-technologies/statemachine.qdoc | 115 | ||||
-rw-r--r-- | doc/src/getting-started/examples.qdoc | 2 | ||||
-rw-r--r-- | doc/src/internationalization/i18n.qdoc | 277 | ||||
-rw-r--r-- | doc/src/internationalization/linguist-manual.qdoc | 368 | ||||
-rw-r--r-- | doc/src/modules.qdoc | 5 | ||||
-rw-r--r-- | doc/src/network-programming/qtnetwork.qdoc | 2 | ||||
-rw-r--r-- | doc/src/snippets/code/doc_src_i18n.qdoc | 2 | ||||
-rw-r--r-- | doc/src/snippets/code/src_corelib_kernel_qobject.cpp | 3 | ||||
-rw-r--r-- | doc/src/snippets/statemachine/main2.cpp | 11 | ||||
-rw-r--r-- | doc/src/snippets/statemachine/main5.cpp | 44 | ||||
-rw-r--r-- | doc/src/sql-programming/sql-programming.qdoc | 4 |
14 files changed, 436 insertions, 437 deletions
diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc index 6c53242..9548848 100644 --- a/doc/src/development/qmake-manual.qdoc +++ b/doc/src/development/qmake-manual.qdoc @@ -2252,6 +2252,18 @@ For example: If the OpenGL implementation uses EGL (most OpenGL/ES systems), then QMAKE_INCDIR_EGL may also need to be set. + \section1 QMAKE_INCDIR_OPENGL_ES1, QMAKE_INCDIR_OPENGL_ES1CL, QMAKE_INCDIR_OPENGL_ES2 + + These variables contain the location of OpenGL headers files to be added + to INCLUDEPATH when building an application with OpenGL ES 1, OpenGL ES 1 Common + Lite or OpenGL ES 2 support respectively. + + The value of this variable is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + If the OpenGL implementation uses EGL (most OpenGL/ES systems), + then QMAKE_INCDIR_EGL may also need to be set. + \target QMAKE_INCDIR_OPENVG \section1 QMAKE_INCDIR_OPENVG @@ -2342,6 +2354,8 @@ For example: \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. \section1 QMAKE_LFLAGS_RPATH + + \e {This is used on Unix platforms only.} Library paths in this definition are added to the executable at link time so that the added paths will be preferentially searched at runtime. @@ -2496,6 +2510,17 @@ For example: variable is typically handled by \c qmake or \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + \section1 QMAKE_LIBS_OPENGL_ES1, QMAKE_LIBS_OPENGL_ES1CL, QMAKE_LIBS_OPENGL_ES2 + + These variables contain all the OpenGL libraries for OpenGL ES 1, + OpenGL ES 1 Common Lite profile and OpenGL ES 2. + + The value of these variables is typically handled by \c qmake or + \l{#QMAKESPEC}{qmake.conf} and rarely needs to be modified. + + If the OpenGL implementation uses EGL (most OpenGL/ES systems), + then QMAKE_LIBS_EGL may also need to be set. + \section1 QMAKE_LIBS_OPENVG This variable contains all OpenVG libraries. The value of this @@ -2673,11 +2698,15 @@ For example: \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 45 \section1 QMAKE_RPATH + + \e {This is used on Unix platforms only.} Is equivalent to \l QMAKE_LFLAGS_RPATH. \section1 QMAKE_RPATHDIR + \e {This is used on Unix platforms only.} + A list of library directory paths, these paths are added to the executable at link time so that the paths will be preferentially searched at runtime. diff --git a/doc/src/examples/ftp.qdoc b/doc/src/examples/ftp.qdoc index 8fded88..782613c 100644 --- a/doc/src/examples/ftp.qdoc +++ b/doc/src/examples/ftp.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! - \example network/ftp + \example network/qftp \title FTP Example The FTP example demonstrates a simple FTP client that can be used diff --git a/doc/src/examples/stickman.qdoc b/doc/src/examples/stickman.qdoc index e70c39b..c9e98d0 100644 --- a/doc/src/examples/stickman.qdoc +++ b/doc/src/examples/stickman.qdoc @@ -55,9 +55,9 @@ Animations are implemented as composite states. Each child state of the animation state represents a frame in the animation by setting the position of each joint in the stickman's skeleton to the positions defined for the particular frame. The frames are then bound together - with animated transitions that trigger on the source state's polished() signal. Thus, the - machine will enter the state representing the next frame in the animation immediately after it - has finished animating into the previous frame. + with animated transitions that trigger on the source state's propertiesAssigned() signal. Thus, + the machine will enter the state representing the next frame in the animation immediately after + it has finished animating into the previous frame. \image stickman-example1.png @@ -67,7 +67,8 @@ \snippet examples/animation/stickman/lifecycle.cpp 1 - The states are then bound together with signal transitions that listen to the polished() signal. + The states are then bound together with signal transitions that listen to the + propertiesAssigned() signal. \snippet examples/animation/stickman/lifecycle.cpp 2 diff --git a/doc/src/frameworks-technologies/statemachine.qdoc b/doc/src/frameworks-technologies/statemachine.qdoc index ed8bc85..b0b13a7 100644 --- a/doc/src/frameworks-technologies/statemachine.qdoc +++ b/doc/src/frameworks-technologies/statemachine.qdoc @@ -75,6 +75,11 @@ states can be configured to set properties and invoke methods on QObjects. Qt's event system is used to drive the state machines. + The state graph in the State Machine framework is hierarchical. States can be nested inside of + other states, and the current configuration of the state machine consists of the set of states + which are currently active. All the states in a valid configuration of the state machine will + have a common ancestor. + \section1 Classes in the State Machine Framework These classes are provided by qt for creating event-driven state machines. @@ -269,9 +274,17 @@ When a parallel state group is entered, all its child states will be simultaneously entered. Transitions within the individual child states - operate normally. However, any of the child states may take a transition - outside the parent state. When this happens, the parent state and all of its - child states are exited. + operate normally. However, any of the child states may take a transition which exits the parent + state. When this happens, the parent state and all of its child states are exited. + + The parallelism in the State Machine framework follows an interleaved semantics. All parallel + operations will be executed in a single, atomic step of the event processing, so no event can + interrupt the parallel operations. However, events will still be processed sequentially, since + the machine itself is single threaded. As an example: Consider the situation where there are two + transitions that exit the same parallel state group, and their conditions become true + simultaneously. In this case, the event that is processed last of the two will not have any + effect, since the first event will already have caused the machine to exit from the parallel + state. \section1 Detecting that a Composite State has Finished @@ -413,18 +426,8 @@ value of the property before any property assignments in states were executed.) Take the following code: - \code - QStateMachine machine; - machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties); - - QState *s1 = new QState(); - s1->assignProperty(object, "fooBar", 1.0); - machine.addState(s1); - machine.setInitialState(s1); - QState *s2 = new QState(); - machine.addState(s2); - \endcode + \snippet doc/src/snippets/statemachine/main5.cpp 0 Lets say the property \c fooBar is 0.0 when the machine starts. When the machine is in state \c s1, the property will be 1.0, since the state explicitly assigns this value to it. When the @@ -433,21 +436,8 @@ If we are using nested states, the parent defines a value for the property which is inherited by all descendants that do not explicitly assign a value to the property. - \code - QStateMachine machine; - machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties); - QState *s1 = new QState(); - s1->assignProperty(object, "fooBar", 1.0); - machine.addState(s1); - machine.setInitialState(s1); - - QState *s2 = new QState(s1); - s2->assignProperty(object, "fooBar", 2.0); - s1->setInitialState(s2); - - QState *s3 = new QState(s1); - \endcode + \snippet doc/src/snippets/statemachine/main5.cpp 2 Here \c s1 has two children: \c s2 and \c s3. When \c s2 is entered, the property \c fooBar will have the value 2.0, since this is explicitly defined for the state. When the machine is in @@ -460,15 +450,8 @@ properties as they are assigned in states. Say we have the following code: - \code - QState *s1 = new QState(); - QState *s2 = new QState(); - s1->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); - s2->assignProperty(button, "geometry", QRectF(0, 0, 100, 100)); - - s1->addTransition(button, SIGNAL(clicked()), s2); - \endcode + \snippet doc/src/snippets/statemachine/main5.cpp 3 Here we define two states of a user interface. In \c s1 the \c button is small, and in \c s2 it is bigger. If we click the button to transition from \c s1 to \c s2, the geometry of the button @@ -476,16 +459,7 @@ smooth, however, all we need to do is make a QPropertyAnimation and add this to the transition object. - \code - QState *s1 = new QState(); - QState *s2 = new QState(); - - s1->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); - s2->assignProperty(button, "geometry", QRectF(0, 0, 100, 100)); - - QSignalTransition *transition = s1->addTransition(button, SIGNAL(clicked()), s2); - transition->addAnimation(new QPropertyAnimation(button, "geometry")); - \endcode + \snippet doc/src/snippets/statemachine/main5.cpp 4 Adding an animation for the property in question means that the property assignment will no longer take immediate effect when the state has been entered. Instead, the animation will start @@ -504,33 +478,48 @@ property can potentially have any value, depending on the animation. In some cases, it can be useful to be able to detect when the property has actually been assigned - the value defined by a state. For this, we can use the state's polished() signal. - \code - QState *s1 = new QState(); - s1->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); + the value defined by a state. - QState *s2 = new QState(); + Say we have the following code: - s1->addTransition(s1, SIGNAL(polished()), s2); - \endcode + \snippet doc/src/snippets/statemachine/main5.cpp 5 + + When \c button is clicked, the machine will transition into state \c s2, which will set the + geometry of the button, and then pop up a message box to alert the user that the geometry has + been changed. + + In the normal case, where animations are not used, this will operate as expected. However, if + an animation for the \c geometry of \c button is set on the transition between \c s1 and \c s2, + the animation will be started when \c s2 is entered, but the \c geometry property will not + actually reach its defined value before the animation is finished running. In this case, the + message box will pop up before the geometry of the button has actually been set. + + To ensure that the message box does not pop up until the geometry actually reaches its final + value, we can use the state's propertiesAssigned() signal. The propertiesAssigned() signal will be + emitted when the property is assigned its final value, whether this is done immediately or + after the animation has finished playing. + + \snippet doc/src/snippets/statemachine/main5.cpp 6 - The machine will be in state \c s1 until the \c geometry property has been set. Then it will - immediately transition into \c s2. If the transition into \c s1 has an animation for the \c - geometry property, then the machine will stay in \c s1 until the animation has finished. If there - is no animation, it will simply set the property and immediately enter state \c s2. + In this example, when \c button is clicked, the machine will enter \c s2. It will remain in state + \c s2 until the \c geometry property has been set to \c QRect(0, 0, 50, 50). Then it will + transition into \c s3. When \c s3 is entered, the message box will pop up. If the transition into + \c s2 has an animation for the \c geometry property, then the machine will stay in \c s2 until the + animation has finished playing. If there is no such animation, it will simply set the property and + immediately enter state \c s3. - Either way, when the machine is in state \c s2, the property \c geometry has been assigned the - defined value. + Either way, when the machine is in state \c s3, you are guaranteed that the property \c geometry + has been assigned the defined value. If the global restore policy is set to QStateMachine::RestoreProperties, the state will not emit - the polished() signal until these have been executed as well. + the propertiesAssigned() signal until these have been executed as well. - \section1 What happens if a state is exited before the animation has finished + \section1 What Happens If A State Is Exited Before The Animation Has Finished If a state has property assignments, and the transition into the state has animations for the properties, the state can potentially be exited before the properties have been assigned to the values defines by the state. This is true in particular when there are transitions out from the - state that do not depend on the state being polished, as described in the previous section. + state that do not depend on the propertiesAssigned signal, as described in the previous section. The State Machine API guarantees that a property assigned by the state machine either: \list @@ -545,7 +534,7 @@ If the target state does not assign any value to the property, there are two options: By default, the property will be assigned the value defined by the state it is leaving - (the value it would have been assigned if the animation had been permitted to finish playing.) If + (the value it would have been assigned if the animation had been permitted to finish playing). If a global restore policy is set, however, this will take precedence, and the property will be restored as usual. diff --git a/doc/src/getting-started/examples.qdoc b/doc/src/getting-started/examples.qdoc index 05940e4..79cbe89 100644 --- a/doc/src/getting-started/examples.qdoc +++ b/doc/src/getting-started/examples.qdoc @@ -729,7 +729,7 @@ \o \l{network/network-chat}{Network Chat} \o \l{network/fortuneclient}{Fortune Client}\raisedaster \o \l{network/fortuneserver}{Fortune Server}\raisedaster - \o \l{network/ftp}{FTP}\raisedaster + \o \l{network/qftp}{FTP}\raisedaster \o \l{network/http}{HTTP} \o \l{network/loopback}{Loopback} \o \l{network/threadedfortuneserver}{Threaded Fortune Server}\raisedaster diff --git a/doc/src/internationalization/i18n.qdoc b/doc/src/internationalization/i18n.qdoc index e873f4e..2d1b8cc 100644 --- a/doc/src/internationalization/i18n.qdoc +++ b/doc/src/internationalization/i18n.qdoc @@ -51,6 +51,7 @@ \page internationalization.html \title Internationalization with Qt \brief Information about Qt's support for internationalization and multiple languages. + \nextpage Writing Source Code for Translation \keyword internationalization \keyword i18n @@ -59,11 +60,11 @@ 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 @@ -438,9 +439,13 @@ 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. + QEvent::LanguageChange event, and will call this function when necessary. + + \l{QEvent::LanguageChange}{LanguageChange} events are posted when a new + translation is installed using the QCoreApplication::installTranslator() + function. Additionally, other application components can also force + widgets to update themselves by posting LanguageChange events to them. + \section1 Translating Non-Qt Classes @@ -516,3 +521,265 @@ 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}. */ + +/*! + \page i18n-source-translation.html + \title Writing Source Code for Translation + \ingroup i18n + \previouspage Internationalization with Qt + \contentspage Internationalization with Qt + \nextpage Translation Rules for Plurals + \brief How to write source code in a way that makes it possible for user-visible text to be translated. + + \tableofcontents + + \section1 The Basics + + Developers use the \l{QObject::}{tr()} function to obtain translated text + for their classes, typically for display purposes. This function is also + used to indicate which text strings in an application are translatable. + + Qt indexes each translatable string by the \e{translation context} it is + associated with; this is generally the name of the QObject subclass it is + used in. + + Translation contexts are defined for new QObject-based classes by the use + of the Q_OBJECT macro in each new class definition. + + When tr() is called, it looks up the translatable string using a QTranslator + object. For translation to work, one or more of these must have been + installed on the application object in the way described in the + \l{#Enabling Translation}{Enabling Translation} section below. + + \section1 Defining a Translation Context + + The translation context for QObject and each QObject subclass is the + class name itself. Developers subclassing QObject must use the + Q_OBJECT macro in their class definition to override the translation + context. This macro sets the context to the name of the subclass. + + For example, the following class definition includes the Q_OBJECT macro, + implementing a new tr() that uses the \c MainWindow context: + + \snippet mainwindows/sdi/mainwindow.h class definition with macro + \dots + + If Q_OBJECT is not used in a class definition, the context will be + inherited from the base class. For example, since all QObject-based + classes in Qt provide a context, a new QWidget subclass defined without + a Q_OBJECT macro will use the \c QWidget context if its tr() function + is invoked. + + \section1 Using tr() to Obtain a Translation + + The following example shows how a translation is obtained for the + class shown in the previous section: + + \snippet mainwindows/sdi/mainwindow.cpp implicit tr context + \dots + + Here, the translation context is \c MainWindow because it is the + \c MainWindow::tr() function that is invoked. The text returned + by the tr() function is a translation of "&File" obtained from + the \c MainWindow context. + + When Qt's translation tool, \l lupdate, is used to process a set of source + files, the text wrapped in tr() calls is stored in a section of the translation + file that corresponds to its translation context. + + In some situations, it is useful to give a translation context explicitly + by fully qualifying the call to tr(); for example: + + \snippet doc/src/snippets/code/src_corelib_kernel_qobject.cpp explicit tr context + + This call obtains the translated text for "Page up" from the \c QScrollBar + context. Developers can also use the QCoreApplication::translate() function + to obtain a translation for a particular translation context. + + \section1 Translator Comments + + Developers can include information about each translatable string to + help translators with the translation process. These are extracted + when \l lupdate is used to process the source files. The recommended + way to add comments is to annotate the tr() calls in your code with + comments of the form: + + \tt{//: ...} + + or + + \tt{\begincomment: ... \endcomment} + + Examples: + + \snippet doc/src/snippets/code/src_corelib_kernel_qobject.cpp 40 + + In these examples, the comments will be associated with the strings + passed to tr() in the context of each call. + + \section1 Adding Meta-Data to Strings + + Additional data can be attached to each translatable message. These are + extracted when \l lupdate is used to process the source files. The + recommended way to add meta-data is to annotate the tr() calls in your code + with comments of the form: + + \tt{//= <id>} + + This can be used to give the message a unique identifier to support tools + which need it. + + An alternative way to attach meta-data is to use the following syntax: + + \tt{//~ <field name> <field contents>} + + This can be used to attach meta-data to the message. The field name should + consist of a domain prefix (possibly the conventional file extension of the + file format the field is inspired by), a hyphen and the actual field name + in underscore-delimited notation. For storage in TS files, the field name + together with the prefix "extra-" will form an XML element name. The field + contents will be XML-escaped, but otherwise appear verbatim as the + element's contents. Any number of unique fields can be added to each + message. + + Example: + + \snippet doc/src/snippets/code/src_corelib_kernel_qobject.cpp meta data + + Meta-data appearing right in front of a magic TRANSLATOR comment applies to + the whole TS file. + + \section1 Disambiguation + + If the same translatable string is used in different roles within the same + translation context, an additional identifying string may be passed in + the call to \l{QObject::}{tr()}. This optional disambiguation argument + is used to distinguish between otherwise identical strings. + + Example: + + \snippet doc/src/snippets/code/src_corelib_kernel_qobject.cpp 17 + \dots + + In Qt 4.4 and earlier, this disambiguation parameter was the preferred + way to specify comments to translators. + + \section1 Character Encodings + + You can set the encoding for the source text by calling QTextCodec::setCodecForTr(). + By default, the source text is assumed to be in Latin-1 encoding. + + \section1 Handling Plurals + + Some translatable strings contain placeholders for integer values and need + to be translated differently depending on the values in use. + + To help with this problem, developers pass an additional integer argument + to the \l{QObject::}{tr()} function, and typically use a special notation + for plurals in each translatable string. + + If this argument is equal or greater than zero, all occurrences of + \c %n in the resulting string are replaced with a decimal representation + of the value supplied. In addition, the translation used will adapt to the + value according to the rules for each language. + + Example: + + \snippet doc/src/snippets/code/src_corelib_kernel_qobject.cpp 18 + + The table below shows what string is returned depending on the + active translation: + + \table + \header \o \o{3,1} Active Translation + \header \o \a n \o No Translation \o French \o English + \row \o 0 \o "0 message(s) saved" \o "0 message sauvegard\unicode{0xE9}" \o "0 message\bold{s} saved" + \row \o 1 \o "1 message(s) saved" \o "1 message sauvegard\unicode{0xE9}" \o "1 message saved" + \row \o 2 \o "2 message(s) saved" \o "2 message\bold{s} sauvegard\unicode{0xE9}\bold{s}" \o "2 message\bold{s} saved" + \row \o 37 \o "37 message(s) saved" \o "37 message\bold{s} sauvegard\unicode{0xE9}\bold{s}" \o "37 message\bold{s} saved" + \endtable + + This idiom is more flexible than the traditional approach; e.g., + + \snippet doc/src/snippets/code/src_corelib_kernel_qobject.cpp 19 + + because it also works with target languages that have several + plural forms (e.g., Irish has a special "dual" form that should + be used when \c n is 2), and it handles the \e n == 0 case + correctly for languages such as French that require the singular. + See the \l{Qt Linguist Manual} for details. + + Instead of \c %n, you can use \c %Ln to produce a localized + representation of \a n. The conversion uses the default locale, + set using QLocale::setDefault(). (If no default locale was + specified, the "C" locale is used.) + + A summary of the rules used to translate strings containing plurals can be + found in the \l{Translation Rules for Plurals} document. + + \section1 Enabling Translation + + 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. + + \section1 Further Reading + + \l{Qt Linguist Manual}, \l{Hello tr Example}, \l{Translation Rules for Plurals} +*/ + +/*! + \page i18n-plural-rules.html + \title Translation Rules for Plurals + \ingroup i18n + \previouspage Writing Source Code for Translation + \contentspage Internationalization with Qt + \brief A summary of the translation rules for plurals produced by Qt's i18n tools. + + The table below shows the specific rules that are produced by Qt Linguist + and \c lrelease for a selection of languages. Cells marked \e otherwise + indicate the form used when none of the other rules are appropriate for a + specific language. + + \table 80% + \header \o Language \o Rule 1 \o Rule 2 \o Rule 3 + \row \o English \o \c{n == 1} + \o \e{otherwise} \o N/A + \row \o French \o \c{n < 2} + \o \e{otherwise} \o N/A + \row \o Czech \o \c{n % 100 == 1} + \o \c{n % 100 >= 2 && n % 100 <= 4} + \o \e{otherwise} + \row \o Irish \o \c{n == 1} + \o \c{n == 2} \o \e{otherwise} + \row \o Latvian \o \c{n % 10 == 1&& n % 100 != 11} + \o \c{n != 0} \o \e{otherwise} + \row \o Lithuanian \o \c{n % 10 == 1&& n % 100 != 11} + \o \c{n % 100 != 12 && n % 10 == 2} + \o \e{otherwise} + \row \o Macedonian \o \c{n % 10 == 1} + \o \c{n % 10 == 2} \o \e{otherwise} + \row \o Polish \o \c{n == 1} + \o \c{n % 10 >= 2 && n % 10 <= 4 + && (n % 100 < 10 || n % 100 > 20)} + \o \e{otherwise} + \row \o Romanian \o \c{n == 1} + \o \c{n == 0|| (n % 100 >= 1 && n % 100 <= 20)} + \o \e{otherwise} + \row \o Russian \o \c{n % 10 == 1&& n % 100 != 11} + \o \c{n % 10 >= 2 && n % 10 <= 4 + && (n % 100 < 10 || n % 100 > 20)} + \o \e{otherwise} + \row \o Slovak \o \c{n == 1} \o \c{n >= 2 && n <= 4} + \o \e{otherwise} + \row \o Japanese \o \e{otherwise} \o N/A \o N/A + \endtable + + The rules themselves are not documented and are internal to Qt Linguist and \c lrelease. +*/ diff --git a/doc/src/internationalization/linguist-manual.qdoc b/doc/src/internationalization/linguist-manual.qdoc index 5d388f1..3e06a2f 100644 --- a/doc/src/internationalization/linguist-manual.qdoc +++ b/doc/src/internationalization/linguist-manual.qdoc @@ -62,7 +62,7 @@ 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 + create run-time translation files for use by the released application. The \l{linguist-translators.html}{Translators} chapter is for @@ -119,7 +119,7 @@ \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 + are inserted programmatically at run-time may need to be reworded because in a different language the word order and therefore the placement of the variables may have to change. @@ -147,7 +147,7 @@ \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. @@ -508,7 +508,7 @@ 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 @@ -781,7 +781,7 @@ 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 + run-time. As with Alt key accelerators, if the translator changes the character, the new character must not conflict with any other Ctrl key accelerator. @@ -790,14 +790,14 @@ supported languages, \e {Qt} automatically translates these strings. - \section2 Handling Numbered Arguments + \section2 Handling Numbered Arguments and Plurals Some phrases contain numbered arguments. A numbered argument is a - placeholder that will be replaced with text at runtime. A numbered + placeholder that will be replaced with text at run-time. 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 + \c{%2} are numbered arguments. At run-time, \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 @@ -808,336 +808,14 @@ of where argument \e{i} appears in the argument sequence in the source string. - \section2 Plurals - - The problem of plurals in output is resolved by using an overload of - the \c tr() function with the signature - \code - QString tr(const char *text, const char *comment, int n); - \endcode - Using built in comparisons for the value of \c n the tr() function will - translate the phrase to the plural form for the target language. - - Different languages have various forms for plurals beyond simply - \e singular and \e plural. The rules for determining which form of the - plural to use are encoded as conditional tests. Below is a table - representing the numbers associated with the forms rather than the - conditional tests themselves. - - - - \table 90% - \header - \o Language - \o Form 1 - \o Form 2 - \o Form 3 - \o Form 4 - \row - \o Arabic - \o 0, 1, 11-102, 111-202... - \o 2 - \o 3-10, 103-110, 203-210... - \o - \row - \o Basque - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Bulgarian - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Catalan - \o 1 - \o 11, 11 000-11 999, 11 000 000-11 999 999... - \o 0, 2-10, 12-10 999, 12-10 999 999... - \o - \row - \o Chinese-CN - \o 0- - \o - \o - \o - \row - \o Chinese-HK - \o 0- - \o - \o - \o - \row - \o Chinese-TW - \o 0- - \o - \o - \o - \row - \o Croation - \o 1, 21, 31, 41, 51, 61, 71, 81, 91, 101... - \o 2-4, 22-24, 32-34, 42-44... - \o 0, 5-20, 25-30, 35-40... - \o - \row - \o Czech - \o 1 - \o 2-4 - \o 0, 5- - \o - \row - \o Danish - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Dutch - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o English - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o English-US - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Estonian - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Finnish - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o French-CA - \o 0, 1 - \o 2-100, 101- - \o - \o - \row - \o French-FR - \o 0, 1 - \o 2-100, 101- - \o - \o - \row - \o Galician - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o German - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Greek - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Hebrew - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Hungarian - \o 0- - \o - \o - \o - \row - \o Icelandic - \o 1, 21, 31, 41, 51....101, 121, 131... - \o 0, 2-20, 22-30, 32-40...102-120... - \o - \o - \row - \o Indonesian - \o 0- - \o - \o - \o - \row - \o Italian - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Japanese - \o 0- - \o - \o - \o - \row - \o Korean - \o 0- - \o - \o - \o - \row - \o Latvian - \o 0 - \o 1, 21, 31, 41, 51, 61, 71, 81, 91, 101, 131, 141... - \o 2-20, 22-30, 32-40, 42-50...202-220, 222-230... - \o - \row - \o Lithuanian - \o 1, 21, 31, 41, 51...101, 121, 131... - \o 2-9, 22-29, 32-39...102-109, 122-129, 132-139... - \o 0, 10-20, 30, 40, 50...110-120, 130, 140... - \o - \row - \o Malay - \o 0- - \o - \o - \o - \row - \o Norwegian - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Persian - \o 0- - \o - \o - \o - \row - \o Polish - \o 1 - \o 2-4, 22-24, 32-34... - \o 5-21, 25-31, 35-41... - \o - \row - \o Portugese-BR - \o 0, 1 - \o 2-100, 101- - \o - \o - \row - \o Portugese-PT - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Romanian - \o 1 - \o 0, 2-19, 101-119, 201-219... - \o 20-100, 120-200, 220-300... - \o - \row - \o Russian - \o 1, 21, 31, 41, 51, 61, 71, 81, 91, 101... - \o 2-4, 22-24, 32-34... - \o 0, 5-20, 25-30, 35-40... - \o - \row - \o Serbian - \o 1, 21, 31, 41, 51, 61, 71, 81, 91, 101... - \o 2-4, 22-24, 32-34... - \o 0, 5-20, 25-30, 35-40... - \o - \row - \o Slovak - \o 1 - \o 2-4 - \o 0, 5-20, 25-30, 35-40... - \o - \row - \o Slovene - \o 1, 101, 201, 301... - \o 2, 102, 202, 302... - \o 3, 4, 103, 104, 203, 204, 303, 304... - \o 0, 5-100, 105-200, 205-300... - \row - \o Spanish-US - \o 1 - \o 0, 2- - \o - \o - \row - \o Spanish-ES - \o 1 - \o 0, 2- - \o - \o - \row - \o Swedish - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Tagalog - \o 0, 1 - \o 2, 3, 5, 7-8, 10-13, 15, 17-18, 20-23...101...1001 - \o 4, 6, 9, 14, 16, 19, 24, 26, 29...104, 106, 109... - \o - \row - \o Thai - \o 0- - \o - \o - \o - \row - \o Turkish - \o 0- - \o - \o - \o - \row - \o Ukrainian - \o 1, 21, 31, 41, 51, 61, 71, 81, 91, 101... - \o 2-4, 22-24, 32-34... - \o 0, 5-20, 25-30, 35-40... - \o - \row - \o Urdu - \o 1 - \o 0, 2-100, 101- - \o - \o - \row - \o Vietnamese - \o 0- - \o - \o - \o - \endtable - - These rules are embedded within the Qt libraries, there is no need for - the developer to know them. Merely to use the correct \c tr() call. - + The use of numbered arguments is often accompanied by the use of + plurals in the source text. In many languages, the form of the + text will depend on the value shown, and more than one translation + is required. If the developers have marked up the source text in + correct way, fields for each of the possible plural forms will be + available in the translation area. (The + \l{Writing Source Code for Translation#Handling Plurals}{Writing Source Code for Translation} + document contains details about this feature for developers.) \section2 Reusing Translations @@ -1157,7 +835,7 @@ {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, + file name. For example, \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 @@ -1287,7 +965,7 @@ 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 + translations used by an application at run-time. 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 @@ -1416,7 +1094,7 @@ \endlist - \o \gui {Tools} + \o \gui {Tools} \list \o \gui {Batch Translation...} \BR Opens a \l{Batch @@ -1427,7 +1105,7 @@ Preview}. This window let you instantly see translations for forms created with \QD. \endlist - \o \gui {View} + \o \gui {View} \list \o \gui {Revert Sorting} \BR puts the items in the \l{Context @@ -1449,7 +1127,7 @@ \endlist - \o \gui {Help} + \o \gui {Help} \list \o \gui {Manual F1} \BR opens this manual. \o \gui {About Qt Linguist} \BR Shows information about \QL. @@ -1621,7 +1299,7 @@ \code CODECFORTR = UTF-8 \endcode - + See the \l lupdate and \l lrelease sections. \section2 Loading Translations @@ -1683,7 +1361,7 @@ \snippet doc/src/snippets/code/doc_src_linguist-manual.qdoc 9 - \section2 Distinguishing Identical Strings That Require Different Translations + \section2 Distinguishing Between Identical Translatable Strings The \l lupdate program automatically provides a \e context for every source text. This context is the class name of the class that contains diff --git a/doc/src/modules.qdoc b/doc/src/modules.qdoc index 9c92a31..ea5a9dc 100644 --- a/doc/src/modules.qdoc +++ b/doc/src/modules.qdoc @@ -367,6 +367,9 @@ The QtSql module is part of the \l{Qt Full Framework Edition} and the \l{Open Source Versions of Qt}. + + See the \l{SQL Programming} guide for information about using this + module in your applications. */ /*! @@ -576,7 +579,7 @@ the module under the appropriate version of the GNU LGPL; version 2.1 for applications and libraries licensed under the GNU GPL version 2, or version 3 for applications and libraries licensed under the GNU - GPL version 2. + GPL version 3. \legalese This file is part of the KDE project diff --git a/doc/src/network-programming/qtnetwork.qdoc b/doc/src/network-programming/qtnetwork.qdoc index d9377fb..b44b84f 100644 --- a/doc/src/network-programming/qtnetwork.qdoc +++ b/doc/src/network-programming/qtnetwork.qdoc @@ -155,7 +155,7 @@ commands based on the result of a previous command. It also enables you to provide detailed feedback to the user. - The \l{network/ftp}{FTP} example + The \l{network/qftp}{FTP} example illustrates how to write an FTP client. Writing your own FTP (or HTTP) server is possible using the lower-level classes QTcpSocket and QTcpServer. diff --git a/doc/src/snippets/code/doc_src_i18n.qdoc b/doc/src/snippets/code/doc_src_i18n.qdoc index eca2868..80faabc 100644 --- a/doc/src/snippets/code/doc_src_i18n.qdoc +++ b/doc/src/snippets/code/doc_src_i18n.qdoc @@ -184,7 +184,7 @@ void Clock::setTime(const QTime &time) //! [12] -void QWidget::changeEvent(QEvent *event) +void MyWidget::changeEvent(QEvent *event) { if (e->type() == QEvent::LanguageChange) { titleLabel->setText(tr("Document Title")); diff --git a/doc/src/snippets/code/src_corelib_kernel_qobject.cpp b/doc/src/snippets/code/src_corelib_kernel_qobject.cpp index 4c64374..88d8025 100644 --- a/doc/src/snippets/code/src_corelib_kernel_qobject.cpp +++ b/doc/src/snippets/code/src_corelib_kernel_qobject.cpp @@ -235,9 +235,8 @@ MyWindow::MyWindow() { QLabel *senderLabel = new QLabel(tr("Name:")); QLabel *recipientLabel = new QLabel(tr("Name:", "recipient")); - ... -} //! [17] +} //! [18] diff --git a/doc/src/snippets/statemachine/main2.cpp b/doc/src/snippets/statemachine/main2.cpp index 2419dc2..9a2890f 100644 --- a/doc/src/snippets/statemachine/main2.cpp +++ b/doc/src/snippets/statemachine/main2.cpp @@ -69,17 +69,18 @@ int main(int argv, char **args) //![1] QButton *interruptButton = new QPushButton("Interrupt Button"); + QWidget *mainWindow = new QWidget(); //![3] QHistoryState *s1h = new QHistoryState(s1); QState *s3 = new QState(); s3->assignProperty(label, "text", "In s3"); - QMessageBox mbox; - mbox.addButton(QMessageBox::Ok); - mbox.setText("Interrupted!"); - mbox.setIcon(QMessageBox::Information); - QObject::connect(s3, SIGNAL(entered()), &mbox, SLOT(exec())); + QMessageBox *mbox = new QMessageBox(mainWindow); + mbox->addButton(QMessageBox::Ok); + mbox->setText("Interrupted!"); + mbox->setIcon(QMessageBox::Information); + QObject::connect(s3, SIGNAL(entered()), mbox, SLOT(exec())); s3->addTransition(s1h); machine.addState(s3); diff --git a/doc/src/snippets/statemachine/main5.cpp b/doc/src/snippets/statemachine/main5.cpp index a9d4091..ff25b7b 100644 --- a/doc/src/snippets/statemachine/main5.cpp +++ b/doc/src/snippets/statemachine/main5.cpp @@ -44,14 +44,13 @@ int main(int argv, char **args) { QApplication app(argv, args); + QWidget *button; { //![0] QStateMachine machine; machine.setGlobalRestorePolicy(QStateMachine::RestoreProperties); -//![0] -//![1] QState *s1 = new QState(); s1->assignProperty(object, "fooBar", 1.0); machine.addState(s1); @@ -59,7 +58,7 @@ int main(int argv, char **args) QState *s2 = new QState(); machine.addState(s2); -//![1] +//![0] } { @@ -110,21 +109,50 @@ int main(int argv, char **args) } { + QMainWindow *mainWindow = 0; //![5] + QMessageBox *messageBox = new QMessageBox(mainWindow); + messageBox->addButton(QMessageBox::Ok); + messageBox->setText("Button geometry has been set!"); + messageBox->setIcon(QMessageBox::Information); + QState *s1 = new QState(); - s1->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); QState *s2 = new QState(); + s2->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); + connect(s2, SIGNAL(entered()), messageBox, SLOT(exec())); - s1->addTransition(s1, SIGNAL(polished()), s2); + s1->addTransition(button, SIGNAL(clicked()), s2); //![5] - } { + QMainWindow *mainWindow = 0; + +//![6] + QMessageBox *messageBox = new QMessageBox(mainWindow); + messageBox->addButton(QMessageBox::Ok); + messageBox->setText("Button geometry has been set!"); + messageBox->setIcon(QMessageBox::Information); + + QState *s1 = new QState(); + + QState *s2 = new QState(); + s2->assignProperty(button, "geometry", QRectF(0, 0, 50, 50)); + + QState *s3 = new QState(); + connect(s3, SIGNAL(entered()), messageBox, SLOT(exec())); + s1->addTransition(button, SIGNAL(clicked()), s2); + s2->addTransition(s2, SIGNAL(propertiesAssigned()), s3); //![6] + + } + + { + +//![7] QState *s1 = new QState(); QState *s2 = new QState(); @@ -134,10 +162,12 @@ int main(int argv, char **args) QStateMachine machine; machine.setInitialState(s1); machine.addDefaultAnimation(new QPropertyAnimation(object, "fooBar")); -//![6] +//![7] } + + return app.exec(); } diff --git a/doc/src/sql-programming/sql-programming.qdoc b/doc/src/sql-programming/sql-programming.qdoc index d0b6776..3aceb17 100644 --- a/doc/src/sql-programming/sql-programming.qdoc +++ b/doc/src/sql-programming/sql-programming.qdoc @@ -49,6 +49,7 @@ /*! \page sql-programming.html \title SQL Programming + \nextpage Connecting to Databases \brief Database integration for Qt applications. @@ -95,7 +96,7 @@ and the SQL API layer. See \l{SQL Database Drivers} for more information. \section2 SQL API Layer - + These classes provide access to databases. Connections are made using the QSqlDatabase class. Database interaction is achieved by using the QSqlQuery class. @@ -119,6 +120,7 @@ \title Connecting to Databases \contentspage SQL Programming + \previouspage SQL Programming \nextpage Executing SQL Statements To access a database with QSqlQuery or QSqlQueryModel, create and |