diff options
| author | Warwick Allison <warwick.allison@nokia.com> | 2009-07-12 23:46:39 (GMT) |
|---|---|---|
| committer | Warwick Allison <warwick.allison@nokia.com> | 2009-07-12 23:46:39 (GMT) |
| commit | 4ca1f77ab54f1e02045dc7e680bd99103f680fea (patch) | |
| tree | 3d947d55e6d2c75faf263d555d5237bb73c59582 /doc | |
| parent | 5b56189c9a6c322fa595b716a9f17e39a35bcbc0 (diff) | |
| parent | 66c9d55e58fd9ee9a80270e63a8ebba52db00904 (diff) | |
| download | Qt-4ca1f77ab54f1e02045dc7e680bd99103f680fea.zip Qt-4ca1f77ab54f1e02045dc7e680bd99103f680fea.tar.gz Qt-4ca1f77ab54f1e02045dc7e680bd99103f680fea.tar.bz2 | |
Merge branch 'kinetic-declarativeui' of git@scm.dev.nokia.troll.no:qt/kinetic into kinetic-declarativeui
Conflicts:
src/declarative/qml/qmlscriptparser.cpp
src/declarative/qml/qmlscriptparser_p.h
Compiles, but probably next needs a revert/change of module stuff,
since that work seems to have been duplicated.
Diffstat (limited to 'doc')
39 files changed, 536 insertions, 277 deletions
diff --git a/doc/src/declarative/extending-examples.qdoc b/doc/src/declarative/extending-examples.qdoc index 09239c1..4fc1bee 100644 --- a/doc/src/declarative/extending-examples.qdoc +++ b/doc/src/declarative/extending-examples.qdoc @@ -256,3 +256,54 @@ This example builds on: \endlist */ + +/*! +\example declarative/extending/signal +\title Extending QML - Signal Support Example + +This example builds on: +\list +\o \l {Extending QML - Attached Properties Example} +\o \l {Extending QML - Grouped Properties Example} +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/extending/valuesource +\title Extending QML - Property Value Source Example + +This example builds on: +\list +\o \l {Extending QML - Signal Support Example} +\o \l {Extending QML - Attached Properties Example} +\o \l {Extending QML - Grouped Properties Example} +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ + +/*! +\example declarative/extending/binding +\title Extending QML - Binding Example + +This example builds on: +\list +\o \l {Extending QML - Property Value Source Example} +\o \l {Extending QML - Signal Support Example} +\o \l {Extending QML - Attached Properties Example} +\o \l {Extending QML - Grouped Properties Example} +\o \l {Extending QML - Default Property Example} +\o \l {Extending QML - Inheritance and Coercion Example} +\o \l {Extending QML - Object and List Property Types Example} +\o \l {Extending QML - Adding Types Example} +\endlist + +*/ diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 0f9148a..ac3dc41 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -359,15 +359,174 @@ object will only be returned if it has previously been created. \l {Extending QML - Attached Properties Example} shows the complete code used to implement the rsvp attached property. -\section1 Signal support +\section1 Signal Support -\section1 Property Binding +\snippet examples/declarative/extending/signal/example.qml 0 +\snippet examples/declarative/extending/signal/example.qml 1 + +The QML snippet shown above associates the evaluation of a ECMAScript expression +with the emission of a Qt signal. + +All Qt signals on a registered class become available as special "signal +propeties" within QML to which the user can assign a single ECMAScript +expression. The signal property's name is a transformed version of the Qt +signal name: "on" is prepended, and the first letter of the signal name upper +cased. For example, the signal used in the example above has the following +C++ signature: + +\snippet examples/declarative/extending/signal/birthdayparty.h 0 + +In classes with multiple signals with the same name, only the final signal +is accessible as a signal property. Although QML provides an element, +\l Connection, for accessing the other signals it is less elegant. For the best +QML API, class developers should avoid overloading signal names. + +Signal parameters become accessible by name to the assigned script. An +unnamed parameter cannot be accessed, so care should be taken to name all the +signal parameters in the C++ class declaration. The intrinsic types +listed in \l {Adding Types}, as well registered object types are permitted as +signal parameter types. Using other types is not an error, but the parameter +value will not be accessible from script. + +\l {Extending QML - Signal Support Example} shows the complete code used to +implement the onPartyStarted signal property. \section1 Property Value Sources +\snippet examples/declarative/extending/valuesource/example.qml 0 +\snippet examples/declarative/extending/valuesource/example.qml 1 + +The QML snippet shown above assigns a property value to the speaker property. +A property value source generates a value for a property that changes over time. + +Property value sources are most commonly used to do animation. Rather than +constructing an animation object and manually setting the animation's "target" +property, a property value source can be assigned directly to a property of any +type and automatically set up this association. + +The example shown here is rather contrived: the speaker property of the +BirthdayParty object is a string that is printed every time it is assigned and +the HappyBirthday value source generates the lyrics of the song +"Happy Birthday". + +\snippet examples/declarative/extending/valuesource/birthdayparty.h 0 + +Normally, assigning an object to a string property would not be allowed. In +the case of a property value source, rather than assigning the object instance +itself, the QML engine sets up an association between the value source and +the property. + +Property value sources are special types that derive from the +QmlPropertyValueSource base class. This base class contains a single method, +QmlPropertyValueSource::setTarget(), that the QML engine invokes when +associating the property value source with a property. The relevant part of +the HappyBirthday type declaration looks like this: + +\snippet examples/declarative/extending/valuesource/happybirthday.h 0 +\snippet examples/declarative/extending/valuesource/happybirthday.h 1 +\snippet examples/declarative/extending/valuesource/happybirthday.h 2 + +In all other respects, property value sources are regular QML types. They must +be registered with the QML engine using the same macros as other types, and can +contain properties, signals and methods just like other types. + +When a property value source object is assigned to a property, QML first tries +to assign it normally, as though it were a regular QML type. Only if this +assignment fails does the engine call the setTarget() method. This allows +the type to also be used in contexts other than just as a value source. + +\l {Extending QML - Property Value Source Example} shows the complete code used +implement the HappyBirthday property value source. + +\section1 Property Binding + +\snippet examples/declarative/extending/binding/example.qml 0 +\snippet examples/declarative/extending/binding/example.qml 1 + +The QML snippet shown above uses a property binding to ensure the +HappyBirthday's name property remains up to date with the celebrant. + +Property binding is a core feature of QML. In addition to assigning literal +values, property bindings allow the developer to assign an arbitrarily complex +ECMAScript expression that may include dependencies on other property values. +Whenever the expression's result changes - through a change in one of its +constituent values - the expression is automatically reevaluated and +the new result assigned to the property. + +All properties on custom types automatically support property binding. However, +for binding to work correctly, QML must be able to reliably determine when a +property has changed so that it knows to reevaluate any bindings that depend on +the property's value. QML relies on the presence of a +\c {Qt's Property System}{NOTIFY signal} for this determination. + +Here is the celebrant property declaration: + +\snippet examples/declarative/extending/binding/birthdayparty.h 0 + +The NOTIFY attribute is followed by a signal name. It is the responsibility of +the class implementer to ensure that whenever the property's value changes, the +NOTIFY signal is emitted. The signature of the NOTIFY signal is not important to QML. + +To prevent loops or excessive evaluation, developers should ensure that the +signal is only emitted whenever the property's value is actually changed. If +a property, or group of properties, is infrequently used it is permitted to use +the same NOTIFY signal for several properties. This should be done with care to +ensure that performance doesn't suffer. + +To keep QML reliable, if a property does not have a NOTIFY signal, it cannot be +used in a binding expression. However, the property can still be assigned +a binding as QML does not need to monitor the property for change in that +scenario. + +Consider a custom type, \c TestElement, that has two properties, "a" and "b". +Property "a" does not have a NOTIFY signal, and property "b" does have a NOTIFY +signal. + +\code +TestElement { + // This is OK + a: b +} +TestElement { + // Will NOT work + b: a +} +\endcode + +The presence of a NOTIFY signal does incur a small overhead. There are cases +where a property's value is set at object construction time, and does not +subsequently change. The most common case of this is when a type uses +\l {Grouped Properties}, and the grouped property object is allocated once, and +only freed when the object is deleted. In these cases, the CONSTANT attribute +may be added to the property declaration instead of a NOTIFY signal. + +\snippet examples/declarative/extending/binding/person.h 0 + +Extreme care must be taken here or applications using your type may misbehave. +The CONSTANT attribute should only be used for properties whose value is set, +and finalized, only in the class constructor. All other properties that want +to be used in bindings should have a NOTIFY signal instead. + +\l {Extending QML - Binding Example} shows the BirthdayParty example updated to +include NOTIFY signals for use in binding. + \section1 Extension Objects -\section1 Parser Status +\snippet examples/declarative/extending/extended/example.qml 0 + +The QML snippet shown above adds a new property to an existing C++ type without +modifying its source code. + +When integrating existing classes and technology into QML, their APIs will often +need to be tweaked to fit better into the declarative environment. Although +the best results are usually obtained by modifying the original classes +directly, if this is either not possible or is complicated by some other +concerns extension objects allow limited extension possibilities without +direct modifications. + +Extension objects can only add properties. + +\section1 Optimization */ diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc index 194be40..60cf2a4 100644 --- a/doc/src/declarative/modules.qdoc +++ b/doc/src/declarative/modules.qdoc @@ -25,6 +25,7 @@ The import statement cannot be used by remote content. Ideas for full module support.... +See QT-558. * Modularity within applications diff --git a/doc/src/designer-manual.qdoc b/doc/src/designer-manual.qdoc index 67114b9..25e7455 100644 --- a/doc/src/designer-manual.qdoc +++ b/doc/src/designer-manual.qdoc @@ -86,7 +86,7 @@ \o \l{Creating Main Windows in Qt Designer} \o \l{Editing Resources with Qt Designer} \o \l{Using Stylesheets with Qt Designer} - \o \l{Using a Designer .ui File in Your Application} + \o \l{Using a Designer UI File in Your Application} \endlist For advanced usage of \QD, you can refer to these links: @@ -158,7 +158,7 @@ has been introduced to aid translators in the case of two source texts being the same but used for different purposes. For example, a dialog could have two \gui{Add} buttons for two different - reasons. \note To maintain compatibility, comments in \c{.ui} files + reasons. \note To maintain compatibility, comments in UI files created prior to Qt 4.5 will be listed in the \gui{Disambiguation} field. \endlist @@ -620,7 +620,7 @@ \key{Ctrl+O}. At any point, you can save your form by selecting the \gui{Save From As...} - option from the \gui File menu. The \c{.ui} files saved by \QD contain + option from the \gui File menu. The UI files saved by \QD contain information about the objects used, and any details of signal and slot connections between them. @@ -953,7 +953,7 @@ \image designer-form-layout.png - The \c{.ui} file above results in the previews shown below. + The UI file above results in the previews shown below. \table \header @@ -1226,7 +1226,7 @@ The whole connection can be selected by clicking on any of its path segments. Once selected, a connection can be deleted with the - \key Delete key, ensuring that it will not be set up in the \c{.ui} + \key Delete key, ensuring that it will not be set up in the UI file. \endtable */ @@ -1795,7 +1795,7 @@ pixmap property in the property editor. \page designer-stylesheet.html \contentspage {Qt Designer Manual}{Contents} \previouspage Editing Resources with Qt Designer - \nextpage Using a Designer .ui File in Your Application + \nextpage Using a Designer UI File in Your Application \title Using Stylesheets with Qt Designer @@ -1824,7 +1824,7 @@ pixmap property in the property editor. \contentspage {Qt Designer Manual}{Contents} \nextpage Using Custom Widgets with Qt Designer - \title Using a Designer .ui File in Your Application + \title Using a Designer UI File in Your Application With Qt's integrated build tools, \l{qmake Manual}{qmake} and \l uic, the code for user interface components created with \QD is automatically @@ -1855,11 +1855,11 @@ pixmap property in the property editor. \section2 The Direct Approach - To demonstrate how to use user interface (\c{.ui}) files straight from + To demonstrate how to use user interface (UI) files straight from \QD, we create a simple Calculator Form application. This is based on the original \l{Calculator Form Example}{Calculator Form} example. - The application consists of one source file, \c main.cpp and a \c{.ui} + The application consists of one source file, \c main.cpp and a UI file. The \c{calculatorform.ui} file designed with \QD is shown below: @@ -1882,7 +1882,7 @@ pixmap property in the property editor. \snippet doc/src/snippets/uitools/calculatorform/main.cpp 0 This include is an additional check to ensure that we do not generate code - for \c .ui files that are not used. + for UI files that are not used. The \c main function creates the calculator widget by constructing a standard QWidget that we use to host the user interface described by the @@ -2003,7 +2003,7 @@ pixmap property in the property editor. \section2 The UiTools Approach - A resource file containing a \c{.ui} file is required to process forms at + A resource file containing a UI file is required to process forms at run time. Also, the application needs to be configured to use the QtUiTools module. This is done by including the following declaration in a \c qmake project file, ensuring that the application is compiled and linked @@ -2034,7 +2034,7 @@ pixmap property in the property editor. \snippet examples/uitools/textfinder/textfinder.cpp 1 Processing forms at run-time gives the developer the freedom to change a - program's user interface, just by changing the \c{.ui} file. This is useful + program's user interface, just by changing the UI file. This is useful when customizing programs to suit various user needs, such as extra large icons or a different colour scheme for accessibility support. @@ -2130,12 +2130,12 @@ pixmap property in the property editor. \image designer-form-settings.png - When saving a form in \QD, it is stored as an \c .ui file. Several form + When saving a form in \QD, it is stored as a UI file. Several form settings, for example the grid settings or the margin and spacing for the default layout, are stored along with the form's components. These settings are used when the \l uic generates the form's C++ code. For more information on how to use forms in your application, see the - \l{Using a Designer .ui File in Your Application} section. + \l{Using a Designer UI File in Your Application} section. \section1 Modifying the Form Settings @@ -2168,7 +2168,7 @@ pixmap property in the property editor. You can also specify the form's \gui{Include Hints}; i.e., provide a list of the header files which will then be included in the form window's - associated \c .ui file. Header files may be local, i.e., relative to the + associated UI file. Header files may be local, i.e., relative to the project's directory, \c "mywidget.h", or global, i.e. part of Qt or the compilers standard libraries: \c <QtGui/QWidget>. @@ -2331,7 +2331,7 @@ pixmap property in the property editor. \row \o \c includeFile() \o The header file that must be included in applications that use - this widget. This information is stored in .ui files and will + this widget. This information is stored in UI files and will be used by \c uic to create a suitable \c{#includes} statement in the code it generates for the form containing the custom widget. @@ -2379,12 +2379,12 @@ pixmap property in the property editor. \section2 Notes on the \c{domXml()} Function - The \c{domXml()} function returns a \c{.ui} file snippet that is used by + The \c{domXml()} function returns a UI file snippet that is used by \QD's widget factory to create a custom widget and its applicable properties. - Since Qt 4.4, \QD's widget box allows for a complete \c{.ui} file to - describe \bold one custom widget. The \c{.ui} file can be loaded using the + Since Qt 4.4, \QD's widget box allows for a complete UI file to + describe \bold one custom widget. The UI file can be loaded using the \c{<ui>} tag. Specifying the <ui> tag allows for adding the <customwidget> element that contains additional information for custom widgets. The \c{<widget>} tag is sufficient if no additional information is required @@ -2800,7 +2800,7 @@ pixmap property in the property editor. \title Qt Designer's UI File Format - The \c .ui file format used by \QD is described by the + The \c UI file format used by \QD is described by the \l{http://www.w3.org/XML/Schema}{XML schema} presented below, which we include for your convenience. Be aware that the format may change in future Qt releases. diff --git a/doc/src/dnd.qdoc b/doc/src/dnd.qdoc index 8d3d79d..5ede20c 100644 --- a/doc/src/dnd.qdoc +++ b/doc/src/dnd.qdoc @@ -141,15 +141,17 @@ types of data that the widget accepts. You must reimplement this function if you want to receive either QDragMoveEvent or QDropEvent in your reimplementations of - \l{QWidget::dragMoveEvent()}{dragMoveEvent()} and dropEvent(). + \l{QWidget::dragMoveEvent()}{dragMoveEvent()} and + \l{QWidget::dropEvent()}{dropEvent()}. - The following code shows how dragEnterEvent() can be reimplemented to + The following code shows how \l{QWidget::dragEnterEvent()}{dragEnterEvent()} + can be reimplemented to tell the drag and drop system that we can only handle plain text: \snippet doc/src/snippets/dropevents/window.cpp 3 - The dropEvent() is used to unpack dropped data and handle it in way that - is suitable for your application. + The \l{QWidget::dropEvent()}{dropEvent()} is used to unpack dropped data + and handle it in way that is suitable for your application. In the following code, the text supplied in the event is passed to a QTextBrowser and a QComboBox is filled with the list of MIME types that @@ -159,7 +161,8 @@ In this case, we accept the proposed action without checking what it is. In a real world application, it may be necessary to return from the - dropEvent() function without accepting the proposed action or handling + \l{QWidget::dropEvent()}{dropEvent()} function without accepting the + proposed action or handling the data if the action is not relevant. For example, we may choose to ignore Qt::LinkAction actions if we do not support links to external sources in our application. @@ -435,7 +438,7 @@ \title Porting to Qt 4 - Drag and Drop \contentspage {Porting Guides}{Contents} \previouspage Porting to Qt 4 - Virtual Functions - \nextpage Porting .ui Files to Qt 4 + \nextpage Porting UI Files to Qt 4 \ingroup porting \brief An overview of the porting process for applications that use drag and drop. diff --git a/doc/src/examples/arrowpad.qdoc b/doc/src/examples/arrowpad.qdoc index 9e9268c..fa19fbb 100644 --- a/doc/src/examples/arrowpad.qdoc +++ b/doc/src/examples/arrowpad.qdoc @@ -140,10 +140,10 @@ QLocale::system() can be influenced by setting the \c LANG environment variable, for example. Notice that the use of a naming convention that incorporates the locale for \c .qm message files, - (and \c .ts files), makes it easy to implement choosing the + (and TS files), makes it easy to implement choosing the translation file according to locale. - If there is no \c .qm message file for the locale chosen the original + If there is no QM message file for the locale chosen the original source text will be used and no error raised. \section1 Translating to French and Dutch @@ -194,9 +194,9 @@ \endlist We have to convert the \c tt1_fr.ts and \c tt1_nl.ts translation source - files into \c .qm files. We could use \e {Qt Linguist} as we've done + files into QM files. We could use \e {Qt Linguist} as we've done before; however using the command line tool \c lrelease ensures that - \e all the \c .qm files for the application are created without us + \e all the QM files for the application are created without us having to remember to load and \gui File|Release each one individually from \e {Qt Linguist}. diff --git a/doc/src/examples/calculatorform.qdoc b/doc/src/examples/calculatorform.qdoc index 7cbf2ac..90eef3b 100644 --- a/doc/src/examples/calculatorform.qdoc +++ b/doc/src/examples/calculatorform.qdoc @@ -45,8 +45,8 @@ The Calculator Form Example shows how to use a form created with \QD in an application by using the user interface information from - a QWidget subclass. We use \l{Using a Designer .ui File in Your Application} - {uic's auto-connection} feature to automatically connect signals + a QWidget subclass. We use \l{Using a Designer UI File in Your Application} + {uic's auto-connection} feature to automatically connect signals from widgets on the form to slots in our code. \image calculatorform-example.png Screenshot of the Calculator Form example @@ -59,7 +59,7 @@ \section1 Preparation The user interface for this example is designed completely using \QD. The - result is a .ui file describing the form, the widgets used, any signal-slot + result is a UI file describing the form, the widgets used, any signal-slot connections between them, and other standard user interface properties. To ensure that the example can use this file, we need to include a \c FORMS diff --git a/doc/src/examples/helloscript.qdoc b/doc/src/examples/helloscript.qdoc index a18e4ad..1b0f43c 100644 --- a/doc/src/examples/helloscript.qdoc +++ b/doc/src/examples/helloscript.qdoc @@ -121,7 +121,7 @@ window). Don't forget the exclamation mark! Click the \gui Done checkbox and choose \gui File|Save from the - menu bar. The \c .ts file will no longer contain + menu bar. The TS file will no longer contain \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 3 @@ -129,11 +129,11 @@ \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 4 - To see the application running in Latin, we have to generate a \c .qm - file from the \c .ts file. Generating a \c .qm file can be achieved - either from within \e {Qt Linguist} (for a single \c .ts file), or - by using the command line program \c lrelease which will produce one \c - .qm file for each of the \c .ts files listed in the project file. + To see the application running in Latin, we have to generate a QM + file from the TS file. Generating a QM file can be achieved + either from within \e {Qt Linguist} (for a single TS file), or + by using the command line program \c lrelease which will produce one + QM file for each of the TS files listed in the project file. Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing \gui File|Release from \e {Qt Linguist}'s menu bar and pressing \gui Save in the file save dialog that pops up. Now run the \c helloscript diff --git a/doc/src/examples/hellotr.qdoc b/doc/src/examples/hellotr.qdoc index bb38737..18e0715 100644 --- a/doc/src/examples/hellotr.qdoc +++ b/doc/src/examples/hellotr.qdoc @@ -108,12 +108,12 @@ Note that the file extension is \c .ts, not \c .qm. The \c .ts translation source format is designed for use during the application's development. Programmers or release managers run - the \c lupdate program to generate and update \c .ts files with + the \c lupdate program to generate and update TS files with the source text that is extracted from the source code. - Translators read and update the \c .ts files using \e {Qt + Translators read and update the TS files using \e {Qt Linguist} adding and editing their translations. - The \c .ts format is human-readable XML that can be emailed directly + The TS format is human-readable XML that can be emailed directly and is easy to put under version control. If you edit this file manually, be aware that the default encoding for XML is UTF-8, not Latin1 (ISO 8859-1). One way to type in a Latin1 character such as @@ -121,8 +121,8 @@ "\ø". This will work for any Unicode 4.0 character. Once the translations are complete the \c lrelease program is used to - convert the \c .ts files into the \c .qm Qt message file format. The - \c .qm format is a compact binary format designed to deliver very + convert the TS files into the QM Qt message file format. The + QM format is a compact binary format designed to deliver very fast lookup performance. Both \c lupdate and \c lrelease read all the project's source and header files (as specified in the HEADERS and SOURCES lines of the project file) and extract the strings that @@ -131,7 +131,7 @@ \c lupdate is used to create and update the message files (\c hellotr_la.ts in this case) to keep them in sync with the source code. It is safe to run \c lupdate at any time, as \c lupdate does not remove any - information. For example, you can put it in the makefile, so the \c .ts + information. For example, you can put it in the makefile, so the TS files are updated whenever the source changes. Try running \c lupdate right now, like this: @@ -151,7 +151,7 @@ We will use \e {Qt Linguist} to provide the translation, although you can use any XML or plain text editor to enter a translation into a - \c .ts file. + TS file. To start \e {Qt Linguist}, type @@ -163,7 +163,7 @@ window). Don't forget the exclamation mark! Click the \gui Done checkbox and choose \gui File|Save from the - menu bar. The \c .ts file will no longer contain + menu bar. The TS file will no longer contain \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 3 @@ -173,11 +173,11 @@ \section1 Running the Application in Latin - To see the application running in Latin, we have to generate a \c .qm - file from the \c .ts file. Generating a \c .qm file can be achieved - either from within \e {Qt Linguist} (for a single \c .ts file), or - by using the command line program \c lrelease which will produce one \c - .qm file for each of the \c .ts files listed in the project file. + To see the application running in Latin, we have to generate a QM + file from the TS file. Generating a QM file can be achieved + either from within \e {Qt Linguist} (for a single TS file), or + by using the command line program \c lrelease which will produce one + QM file for each of the TS files listed in the project file. Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing \gui File|Release from \e {Qt Linguist}'s menu bar and pressing \gui Save in the file save dialog that pops up. Now run the \c hellotr diff --git a/doc/src/examples/multipleinheritance.qdoc b/doc/src/examples/multipleinheritance.qdoc index 5a77275..1622fb0 100644 --- a/doc/src/examples/multipleinheritance.qdoc +++ b/doc/src/examples/multipleinheritance.qdoc @@ -103,6 +103,6 @@ There are various approaches to include forms into applications. The Multiple Inheritance approach is just one of them. See - \l{Using a Designer .ui File in Your Application} for more information on + \l{Using a Designer UI File in Your Application} for more information on the other approaches available. */ diff --git a/doc/src/examples/qtscripttetrix.qdoc b/doc/src/examples/qtscripttetrix.qdoc index c94697a..fb2d537 100644 --- a/doc/src/examples/qtscripttetrix.qdoc +++ b/doc/src/examples/qtscripttetrix.qdoc @@ -57,7 +57,7 @@ \section1 Setting up the GUI - The graphical user interface is defined in a \c{.ui} file, creating + The graphical user interface is defined in a UI file, created using Qt Designer, and is set up in the example's C++ \c{main.cpp} file. \snippet examples/script/qstetrix/main.cpp 0 diff --git a/doc/src/examples/simpletextviewer.qdoc b/doc/src/examples/simpletextviewer.qdoc index 87eae57..2531a86 100644 --- a/doc/src/examples/simpletextviewer.qdoc +++ b/doc/src/examples/simpletextviewer.qdoc @@ -198,12 +198,7 @@ <file>openfile.html</file> <file>wildcardmatching.html</file> <file>images/browse.png</file> - <file>images/fadedfilemenu.png</file> - <file>images/filedialog.png</file> - <file>images/handbook.png</file> - <file>images/mainwindow.png</file> - <file>images/open.png</file> - <file>images/wildcard.png</file> + <file>images/*.png</file> </files> </filterSection> </QtHelpProject> diff --git a/doc/src/examples/svggenerator.qdoc b/doc/src/examples/svggenerator.qdoc index 09fe6e1..dd7459a 100644 --- a/doc/src/examples/svggenerator.qdoc +++ b/doc/src/examples/svggenerator.qdoc @@ -55,8 +55,8 @@ The example consists of two classes: \c Window and \c DisplayWidget. The \c Window class contains the application logic and constructs the user - interface from a Qt Designer \c{.ui} file as described in the - \l{Using a Designer .ui File in Your Application#The Multiple Inheritance Approach}{Qt Designer manual}. + interface from a Qt Designer UI file as described in the + \l{Using a Designer UI File in Your Application#The Multiple Inheritance Approach}{Qt Designer manual}. It also contains the code to write an SVG file. The \c DisplayWidget class performs all the work of painting a picture on diff --git a/doc/src/examples/textfinder.qdoc b/doc/src/examples/textfinder.qdoc index adbbd0d..acfbd0f 100644 --- a/doc/src/examples/textfinder.qdoc +++ b/doc/src/examples/textfinder.qdoc @@ -45,7 +45,7 @@ The Text Finder example demonstrates how to dynamically process forms using the QtUiTools module. Dynamic form processing enables a form to - be processed at run-time only by changing the .ui file for the project. + be processed at run-time only by changing the UI file for the project. The program allows the user to look up a particular word within the contents of a text file. This text file is included in the project's resource and is loaded into the display at startup. @@ -95,7 +95,7 @@ \snippet examples/uitools/textfinder/textfinder.h 0 The slot \c{on_find_Button_clicked()} is a slot named according to the - \l{Using a Designer .ui File in Your Application#Automatic Connections} + \l{Using a Designer UI File in Your Application#Automatic Connections} {Automatic Connection} naming convention required by \c uic. diff --git a/doc/src/examples/worldtimeclockbuilder.qdoc b/doc/src/examples/worldtimeclockbuilder.qdoc index 55246e9..f38062a 100644 --- a/doc/src/examples/worldtimeclockbuilder.qdoc +++ b/doc/src/examples/worldtimeclockbuilder.qdoc @@ -66,7 +66,7 @@ generate a dependency on the \c libQtUiTools library containing the QtUiTools classes. - Note that we do not inform \c qmake about any .ui files, and so none will + Note that we do not inform \c qmake about any UI files, and so none will be processed and built into the application. The resource file contains an entry for the particular form that we wish to use: diff --git a/doc/src/i18n.qdoc b/doc/src/i18n.qdoc index 4109b62..5964926 100644 --- a/doc/src/i18n.qdoc +++ b/doc/src/i18n.qdoc @@ -266,19 +266,19 @@ \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 \c .ts file). The utility recognizes the tr() + for translators (a TS file). The utility recognizes the tr() construct and the \c{QT_TR*_NOOP()} macros described above and - produces \c .ts files (usually one per language). + produces TS files (usually one per language). - \o Provide translations for the source texts in the \c .ts file, using - \e{Qt Linguist}. Since \c .ts files are in XML format, you can also + \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 \c .qm - file) from the \c .ts file, suitable only for end use. Think of the \c - .ts files as "source files", and \c .qm files as "object files". The - translator edits the \c .ts files, but the users of your application - only need the \c .qm files. Both kinds of files are platform and + \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 diff --git a/doc/src/linguist-manual.qdoc b/doc/src/linguist-manual.qdoc index ee59fdc..fd062bb 100644 --- a/doc/src/linguist-manual.qdoc +++ b/doc/src/linguist-manual.qdoc @@ -247,10 +247,10 @@ subsequent \l lupdate runs would probably take place during the final beta phase. - The \c .ts file format is a simple human-readable XML format that + 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; file in this format typically have file names that + 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 @@ -266,19 +266,19 @@ Usage: \c {lrelease myproject.pro} - \l lrelease is a command line tool that produces \c .qm files out - of \c .ts files. The \c .qm file format is a compact binary format + \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 \c .ts files \l lrelease + 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 \c .qm files are not created, e.g. because an + 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 \c .qm files + the programmers placed in the source files. Once the QM files are available the application will detect them and use them automatically. @@ -293,7 +293,7 @@ \section1 Missing Translations - Both \l lupdate and \l lrelease may be used with \c .ts + 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. @@ -317,8 +317,8 @@ 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 (\c{.ts} file) to - load. If you don't have a \c{.ts} file, see the \l {Qt Linguist + {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. @@ -928,12 +928,12 @@ \image linguist-previewtool.png - Forms created by \e{Qt Designer} are stored in special \c .ui files. - \QL can make use of these \c .ui files to show the translations - done so far on the form itself. This of course requires access to the \c .ui + 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 \c .ui files \QL has detected are displayed in the Forms + 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 @@ -947,15 +947,15 @@ \QL makes use of four kinds of files: \list - \o \c .ts \e {translation source files} \BR are human-readable XML + \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 \c .ts file format is used. - \o \c .qm \e {Qt message files} \BR are binary files that contain + 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 @@ -974,18 +974,18 @@ \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 \c .ts files that + \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 \c .qm file with the same base + \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 \c .qm file of the translation + 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. @@ -1136,16 +1136,15 @@ \list \o \inlineimage linguist-fileopen.png \BR - Pops up the open file dialog to open a new translation source \c .ts - file. + 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 \c .ts file. + Saves the current translation source TS file. \o \inlineimage linguist-fileprint.png \BR - Prints the current translation source \c .ts file. + Prints the current translation source TS file. \o \inlineimage linguist-phrasebookopen.png \BR @@ -1263,10 +1262,10 @@ Translation files are created as follows: \list 1 - \o Run \l lupdate initially to generate the first set of \c .ts + \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 \c .ts files are given to the translator who adds 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 @@ -1274,7 +1273,7 @@ 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 \c .ts files and produce the \c .qm files used by the + read the TS files and produce the QM files used by the application at runtime. \endlist @@ -1319,7 +1318,7 @@ In production applications a more flexible approach, for example, loading translations according to locale, might be more appropriate. If - the \c .ts files are all named according to a convention such as + 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. @@ -1413,7 +1412,7 @@ 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 - \c .ts files containing only entries with plural forms. + TS files containing only entries with plural forms. See the \l{http://doc.trolltech.com/qq/}{Qt Quarterly} Article \l{http://doc.trolltech.com/qq/qq19-plurals.html}{Plural Forms in Translations} @@ -1503,7 +1502,7 @@ \contentspage {Qt Linguist Manual}{Contents} \previouspage Qt Linguist Manual: Programmers - The \c .ts file format used by \QL is described by the + 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. diff --git a/doc/src/porting4-canvas.qdoc b/doc/src/porting4-canvas.qdoc index fa0bc6b..d1221cf 100644 --- a/doc/src/porting4-canvas.qdoc +++ b/doc/src/porting4-canvas.qdoc @@ -43,7 +43,7 @@ \page graphicsview-porting.html \title Porting to Graphics View \contentspage {Porting Guides}{Contents} - \previouspage Porting .ui Files to Qt 4 + \previouspage Porting UI Files to Qt 4 \nextpage qt3to4 - The Qt 3 to 4 Porting Tool \ingroup porting \ingroup multimedia diff --git a/doc/src/porting4-designer.qdoc b/doc/src/porting4-designer.qdoc index 916894b..7de1d43 100644 --- a/doc/src/porting4-designer.qdoc +++ b/doc/src/porting4-designer.qdoc @@ -41,12 +41,12 @@ /*! \page porting4-designer.html - \title Porting .ui Files to Qt 4 + \title Porting UI Files to Qt 4 \contentspage {Porting Guides}{Contents} \previouspage Porting to Qt 4 - Drag and Drop \nextpage Porting to Graphics View \ingroup porting - \brief Information about changes to the .ui file format in Qt 4. + \brief Information about changes to the UI file format in Qt 4. Qt Designer has changed significantly in the Qt 4 release. We have moved away from viewing Qt Designer as an IDE and @@ -57,20 +57,20 @@ IDEs. The most important changes in Qt Designer 4 which affect porting - for \c .ui files are summarized below: + for UI files are summarized below: \list \o \bold{Removed project manager.} - Qt Designer now only reads and edits \c .ui - files. It has no notion of a project (\c .pro file). + Qt Designer now only reads and edits UI + files. It has no notion of a project file (\c .pro). \o \bold{Removed code editor.} Qt Designer can no longer be used to edit source files. - \o \bold{Changed format of \c .ui files.} + \o \bold{Changed format of UI files.} Qt Designer 4 cannot read files created by Qt Designer 3 and vice versa. However, we provide the tool \c uic3 to generate Qt - 4 code out of Qt 3 \c .ui files, and to convert old \c .ui files + 4 code out of Qt 3 UI files, and to convert old UI files into a format readable by Qt Designer 4. \o \bold{Changed structure of the code generated by \c uic.} @@ -80,7 +80,7 @@ \c Ui::MyForm. \o \bold{New resource file system.} Icon data is no longer - stored in the \c .ui file. Instead, icons are put into resource + stored in the UI file. Instead, icons are put into resource files (\c .qrc). \endlist @@ -146,9 +146,9 @@ therefore has an interface identical to that of a class generated by \c uic in Qt 3. - Creating POD classes from \c .ui files is more flexible and + Creating POD classes from UI files is more flexible and generic than the old approach of creating widgets. Qt Designer - doesn't need to know anything about the main container apart from + does not need to know anything about the main container apart from the base widget class it inherits. Indeed, \c Ui::HelloWorld can be used to populate any container that inherits QWidget. Conversely, all non-GUI aspects of the main container may be @@ -163,10 +163,10 @@ \list 1 \o To generate headers and source code for a widget to implement any custom signals and slots added using Qt Designer 3. - \o To generate a new \c .ui file that can be used with Qt Designer 4. + \o To generate a new UI file that can be used with Qt Designer 4. \endlist - You can use both these methods in combination to obtain \c{.ui}, header + You can use both these methods in combination to obtain UI, header and source files that you can use as a starting point when porting your user interface to Qt 4. @@ -179,7 +179,7 @@ The resulting files \c myform.h and \c myform.cpp implement the form in Qt 4 using a QWidget that will include custom signals, - slots and connections specified in the \c .ui file. However, + slots and connections specified in the UI file. However, see below for the \l{#Limitations of uic3}{limitations} of this method. @@ -190,7 +190,7 @@ The resulting file \c myform4.ui can be edited in Qt Designer 4. The header file for the form is generated by Qt 4's \c uic. See the - \l{Using a Designer .ui File in Your Application} chapter of the + \l{Using a Designer UI File in Your Application} chapter of the \l{Qt Designer Manual} for information about the preferred ways to use forms created with Qt Designer 4. @@ -218,7 +218,7 @@ \section1 Limitations of uic3 - Converting Qt 3 \c .ui files to Qt 4 has some limitations. The + Converting Qt 3 UI files to Qt 4 has some limitations. The most noticeable limitation is the fact that since \c uic no longer generates a QObject, it's not possible to define custom signals or slots for the form. Instead, the programmer must @@ -231,9 +231,9 @@ A quick and dirty way to port forms containing custom signals and slots is to generate the code using \c uic3, rather than \c uic. Since \c uic3 does generate a QWidget, it will populate it with custom - signals, slots and connections specified in the \c .ui file. - However, \c uic3 can only generate code from Qt 3 \c .ui files, which - implies that the \c .ui files never get translated and need to be + signals, slots and connections specified in the UI file. + However, \c uic3 can only generate code from Qt 3 UI files, which + implies that the UI files never get translated and need to be edited using Qt Designer 3. Note also that it is possible to create implicit connections @@ -256,7 +256,7 @@ \section1 Icons In Qt 3, the binary data for the icons used by a form was stored - in the \c .ui file. In Qt 4 icons and any other external files + in the UI file. In Qt 4 icons and any other external files can be compiled into the application by listing them in a \l{The Qt Resource System}{resource file} (\c .qrc). This file is translated into a C++ source file using Qt's resource compiler @@ -306,7 +306,7 @@ the following steps: \list 1 - \o Use \c{uic3 -convert} to obtain a \c .ui file understood by + \o Use \c{uic3 -convert} to obtain a UI file understood by Qt Designer 4. \o Create a \c .qrc file with a list of all the icon files. diff --git a/doc/src/porting4-overview.qdoc b/doc/src/porting4-overview.qdoc index d91729d..3494c6d 100644 --- a/doc/src/porting4-overview.qdoc +++ b/doc/src/porting4-overview.qdoc @@ -115,13 +115,13 @@ support these project-level features. We recommend using one of the - \l{Using a Designer .ui File in Your Application}{form subclassing approaches} + \l{Using a Designer UI File in Your Application}{form subclassing approaches} with forms created using Qt Designer. This avoids the need to use \c{.ui.h} files and special purpose code editors. Existing Qt 3 forms created using Qt Designer can be gradually ported to Qt 4 by following the advice in the - \l{Porting .ui Files to Qt 4} guide. However, some extra effort + \l{Porting UI Files to Qt 4} guide. However, some extra effort will be required to move application logic from \c{.ui.h} files into the main body of a Qt 4 application. diff --git a/doc/src/porting4.qdoc b/doc/src/porting4.qdoc index 7ce2969..2414c4d 100644 --- a/doc/src/porting4.qdoc +++ b/doc/src/porting4.qdoc @@ -97,7 +97,7 @@ to developers porting from Qt 3 to Qt 4. \o \l{Porting to Qt 4 - Drag and Drop} \mdash covers differences in the way drag and drop is handled between Qt 3 and Qt 4. - \o \l{Porting .ui Files to Qt 4} \mdash describes the new format used to + \o \l{Porting UI Files to Qt 4} \mdash describes the new format used to describe forms created with \QD. \o \l{Porting to Graphics View} \mdash provides a class-by-class overview of the differences between Qt 3's canvas API and Qt 4's Graphics @@ -135,7 +135,7 @@ \o Run the \l qt3to4 porting tool. The tool will go through your source code and adapt it to Qt 4. - \o Follow the instructions in the \l{Porting .ui Files to Qt 4} + \o Follow the instructions in the \l{Porting UI Files to Qt 4} page to port Qt Designer files. \o Recompile with Qt 4. For each error, search below for related @@ -347,7 +347,7 @@ macro, removing the need for a \c Q_OVERRIDE() macro. The table below lists the Qt properties that have been renamed in - Qt 4. Occurrences of these in \e{Qt Designer} \c .ui files are + Qt 4. Occurrences of these in \e{Qt Designer} UI files are automatically converted to the new name by \c uic. \table @@ -406,11 +406,11 @@ Some properties have been removed from Qt 4, but the associated access functions are provided if \c QT3_SUPPORT is defined to help - porting to Qt 4. When converting Qt 3 \c .ui files to Qt 4, \c uic + porting to Qt 4. When converting Qt 3 UI files to Qt 4, \c uic generates calls to the Qt 3 compatibility functions. Note that this only applies to the properties of the Qt3Support library, i.e. \c QT3_SUPPORT properties of the other libraries must be - ported manually when converting Qt 3 .ui files to Qt 4. + ported manually when converting Qt 3 UI files to Qt 4. The table below lists these properties with the read and write functions that you can use instead. The documentation for the @@ -518,7 +518,7 @@ (Notice the \c & in the parameter declaration.) \omit - \section1 Qt Designer .ui Files + \section1 Qt Designer UI Files ### \endomit diff --git a/doc/src/qmake-manual.qdoc b/doc/src/qmake-manual.qdoc index d4d51c7..0921ae7 100644 --- a/doc/src/qmake-manual.qdoc +++ b/doc/src/qmake-manual.qdoc @@ -235,7 +235,7 @@ \row \o CONFIG \o General project configuration options. \row \o DESTDIR \o The directory in which the executable or binary file will be placed. - \row \o FORMS \o A list of .ui files to be processed by \c uic. + \row \o FORMS \o A list of UI files to be processed by \c uic. \row \o HEADERS \o A list of filenames of header (.h) files used when building the project. \row \o QT \o Qt-specific configuration options. @@ -701,8 +701,8 @@ If a directory is specified, it will be included in the \c DEPENDPATH variable, and relevant code from there will be included in the generated project file. If a file is given, it will be appended to the correct - variable, depending on its extension; for example, .ui files are added - to \c FORMS, and .cpp files are added to \c SOURCES. + variable, depending on its extension; for example, UI files are added + to \c FORMS, and C++ files are added to \c SOURCES. You may also pass assignments on the command line in this mode. When doing so, these assignments will be placed last in the generated project file. @@ -829,6 +829,29 @@ Note that, if a project is later moved on the disk, \c qmake must be run again to process the project file and create a new Xcode project file. + \section2 On supporting two build targets simultaneously + + Implementing this is currently not feasible, because the XCode + concept of Active Build Configurations is conceptually different + from the qmake idea of build targets. + + The XCode Active Build Configurations settings are for modifying + xcode configurations, compiler flags and similar build + options. Unlike Visual Studio, XCode does not allow for the + selection of specific library files based on whether debug or + release build configurations are selected. The qmake debug and + release settings control which library files are linked to the + executable. + + It is currently not possible to set files in XCode configuration + settings from the qmake generated xcode project file. The way the + libraries are linked in the "Frameworks & Libraries" phase in the + XCode build system. + + Furthermore, The selected "Active Build Configuration" is stored + in a .pbxuser file, which is generated by xcode on first load, not + created by qmake. + \section1 Windows Features specific to this platform include support for creating Visual @@ -1021,6 +1044,26 @@ \snippet doc/src/snippets/code/doc_src_qmake-manual.qdoc 24 + When linking a library, \c qmake relies on the underlying platform to know + what other libraries this library links against. However, if linking + statically, \c qmake will not get this information unless we use the following + \c CONFIG options: + + \table 95% + \header \o Option \o Description + \row \o create_prl \o This option enables \c qmake to track these + dependencies. When this option is enabled, \c qmake will create a file + ending in \c .prl which will save meta-information about the library + (see \l{LibDepend}{Library Dependencies} for more info). + \row \o link_prl \o When this is enabled, \c qmake will process all + libraries linked to by the application and find their meta-information + (see \l{LibDepend}{Library Dependencies} for more info). + \endtable + + Please note that \c create_prl is required when \e {building} a + static library, while \c link_prl is required when \e {using} a + static library. + On Windows (or if Qt is configured with \c{-debug_and_release}, adding the \c build_all option to the \c CONFIG variable makes this rule the default when building the project, and installation targets will be created for @@ -1261,10 +1304,10 @@ \target FORMS \section1 FORMS - This variable specifies the .ui files (see \link + This variable specifies the UI files (see \link designer-manual.html Qt Designer \endlink) to be processed through \c uic before compiling. All dependencies, headers and source files required - to build these .ui files will automatically be added to the project. + to build these UI files will automatically be added to the project. For example: @@ -1277,10 +1320,10 @@ \target FORMS3 \section1 FORMS3 - This variable specifies the old style .ui files to be processed + This variable specifies the old style UI files to be processed through \c uic3 before compiling, when \c CONFIG contains uic3. All dependencies, headers and source files required to build these - .ui files will automatically be added to the project. + UI files will automatically be added to the project. For example: @@ -4108,7 +4151,7 @@ \list \o HEADERS - A list of all the header files for the application. \o SOURCES - A list of all the source files for the application. - \o FORMS - A list of all the .ui files (created using \c{Qt Designer}) + \o FORMS - A list of all the UI files (created using \c{Qt Designer}) for the application. \o LEXSOURCES - A list of all the lex source files for the application. \o YACCSOURCES - A list of all the yacc source files for the application. @@ -4126,7 +4169,7 @@ \endlist You only need to use the system variables that you have values for, - for instance, if you don't have any extra INCLUDEPATHs then you don't + for instance, if you do not have any extra INCLUDEPATHs then you do not need to specify any, \c qmake will add in the default ones needed. For instance, an example project file might look like this: diff --git a/doc/src/qmsdev.qdoc b/doc/src/qmsdev.qdoc index b8d8f85..127b514 100644 --- a/doc/src/qmsdev.qdoc +++ b/doc/src/qmsdev.qdoc @@ -87,7 +87,7 @@ the existing project. If you want to add an existing dialog to your project, then just select the - relevant \c .ui file. This will then add it to your existing project and add + relevant UI file. This will then add it to your existing project and add the relevant steps to create the generated code. \section2 Using the 'Qt Designer' button diff --git a/doc/src/qnamespace.qdoc b/doc/src/qnamespace.qdoc index 805855a..b691ac7 100644 --- a/doc/src/qnamespace.qdoc +++ b/doc/src/qnamespace.qdoc @@ -1208,6 +1208,9 @@ handle touch events. Without this attribute set, events from a touch device will be sent as mouse events. + \value WA_TouchPadAcceptSingleTouchEvents Allows touchpad single + touch events to be sent to the widget. + \omitvalue WA_SetLayoutDirection \omitvalue WA_InputMethodTransparent \omitvalue WA_WState_CompressKeys @@ -2697,20 +2700,6 @@ \internal */ -/*! \enum Qt::GestureType - \since 4.6 - - This enum lists standard gestures. - - \value UnknownGesture An unknown gesture. This enum value shouldn't be used. - \value TapGesture A single tap gesture. - \value DoubleTapGesture A double tap gesture. - \value TrippleTapGesture A tripple tap gesture. - \value TapAndHoldGesture A tap-and-hold (long tap) gesture. - \value PanGesture A pan gesture. - \value PinchGesture A pinch gesture. -*/ - /*! \enum Qt::GestureState \since 4.6 @@ -2719,30 +2708,8 @@ \omitvalue NoGesture \value GestureStarted A continuous gesture has started. - \value GestureUpdated A gesture continiues. + \value GestureUpdated A gesture continues. \value GestureFinished A gesture has finished. \sa QGesture */ - -/*! - \enum Qt::DirectionType - \since 4.6 - - This enum type describes directions. This could be used by the - gesture recognizers. - - \value NoDirection Non-specific direction. - \value LeftDownDirection - \value DownLeftDirection - \value DownDirection - \value RightDownDirection - \value DownRightDirection - \value LeftDirection - \value RightDirection - \value LeftUpDirection - \value UpLeftDirection - \value UpDirection - \value RightUpDirection - \value UpRightDirection -*/ diff --git a/doc/src/qt3to4.qdoc b/doc/src/qt3to4.qdoc index 9ffd52e..47e85b4 100644 --- a/doc/src/qt3to4.qdoc +++ b/doc/src/qt3to4.qdoc @@ -50,7 +50,7 @@ to Qt 4. It is designed to automate the most tedious part of the porting effort. - See \l{Porting to Qt 4} and \l{Porting .ui Files to Qt 4} for + See \l{Porting to Qt 4} and \l{Porting UI Files to Qt 4} for more information about porting Qt 3 applications to Qt 4. \section1 Usage diff --git a/doc/src/qt4-intro.qdoc b/doc/src/qt4-intro.qdoc index 2fda7cf..6f59cae 100644 --- a/doc/src/qt4-intro.qdoc +++ b/doc/src/qt4-intro.qdoc @@ -235,7 +235,7 @@ for your project (using "DEFINES +=") on to moc, which has its own built-in C++ preprocessor. - To compile code that uses .ui files, you will also need this line in + To compile code that uses UI files, you will also need this line in the .pro file: \snippet doc/src/snippets/code/doc_src_qt4-intro.qdoc 2 diff --git a/doc/src/qtdesigner.qdoc b/doc/src/qtdesigner.qdoc index 2117b27..d913b32 100644 --- a/doc/src/qtdesigner.qdoc +++ b/doc/src/qtdesigner.qdoc @@ -52,7 +52,7 @@ that enable you to access Qt Designer's components. In addition, the QFormBuilder class provides the possibility of - constructing user interfaces from \c .ui files at run-time. + constructing user interfaces from UI files at run-time. To include the definitions of the module's classes, use the following directive: @@ -155,7 +155,7 @@ The \c QtDesigner module contains the QFormBuilder class that provides a mechanism for dynamically creating user interfaces at - run-time, based on \c .ui files created with \QD. This class is + run-time, based on UI files created with \QD. This class is typically used by custom components and applications that embed \QD. Standalone applications that need to dynamically generate user interfaces at run-time use the QUiLoader class, found in @@ -1427,7 +1427,7 @@ \fn bool QDesignerPropertySheetExtension::isAttribute(int index) const Returns true if the property at the given \a index is an attribute, - which will be \e excluded from the .ui file, otherwise false. + which will be \e excluded from the UI file, otherwise false. \sa indexOf(), setAttribute() */ @@ -1436,7 +1436,7 @@ \fn void QDesignerPropertySheetExtension::setAttribute(int index, bool attribute) If \a attribute is true, the property at the given \a index is - made an attribute which will be \e excluded from the .ui file; + made an attribute which will be \e excluded from the UI file; otherwise it will be included. \sa indexOf(), isAttribute() diff --git a/doc/src/qthelp.qdoc b/doc/src/qthelp.qdoc index 7260b6e..92c9609 100644 --- a/doc/src/qthelp.qdoc +++ b/doc/src/qthelp.qdoc @@ -279,7 +279,7 @@ \section1 Qt Help Project File Format - The file format is XML based. For a better understanding of + The file format is XML-based. For a better understanding of the format we'll discuss the following example: \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 7 @@ -398,11 +398,13 @@ Finally, the actual documentation files have to be listed. Make sure that all files neccessary to display the help are mentioned, i.e. - stylesheets or similar files need to be there as well. The file, like all + stylesheets or similar files need to be there as well. The files, like all file references in a Qt help project, are relative to the help project file - itself. All listed files will be compressed and written to the Qt compressed - help file. So, in the end, one single Qt help file contains all - documentation files along with the contents and indices. \note The - referenced files must be inside the same directory (or within a subdirectory) - as the help project file. An absolute file path is not supported either. + itself. As the example shows, files (but not directories) can also be + specified as patterns using wildcards. All listed files will be compressed + and written to the Qt compressed help file. So, in the end, one single Qt + help file contains all documentation files along with the contents and + indices. \note The referenced files must be inside the same directory + (or within a subdirectory) as the help project file. An absolute file path + is not supported either. */ diff --git a/doc/src/qtscript.qdoc b/doc/src/qtscript.qdoc index f2ac6c9..6b8f639 100644 --- a/doc/src/qtscript.qdoc +++ b/doc/src/qtscript.qdoc @@ -1782,20 +1782,20 @@ \list 1 \o Run \c lupdate to extract translatable text from the script source code - of the Qt application, resulting in a message file for translators (a \c - .ts file). The utility recognizes qsTr(), qsTranslate() and the - \c{QT_TR*_NOOP()} functions described above and produces \c .ts files + of the Qt application, resulting in a message file for translators (a TS + file). The utility recognizes qsTr(), qsTranslate() and the + \c{QT_TR*_NOOP()} functions described above and produces TS files (usually one per language). - \o Provide translations for the source texts in the \c .ts file, using - \e{Qt Linguist}. Since \c .ts files are in XML format, you can also + \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 \c .qm - file) from the \c .ts file, suitable only for end use. Think of the \c - .ts files as "source files", and \c .qm files as "object files". The - translator edits the \c .ts files, but the users of your application - only need the \c .qm files. Both kinds of files are platform and + \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 @@ -1805,7 +1805,7 @@ translations from previous releases. When running \c lupdate, you must specify the location of the script(s), - and the name of the \c{.ts} file to produce. Examples: + and the name of the TS file to produce. Examples: \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 87 @@ -1823,7 +1823,7 @@ \snippet doc/src/snippets/code/doc_src_qtscript.qdoc 89 - When running \c lrelease, you must specify the name of the \c{.ts} input + When running \c lrelease, you must specify the name of the TS input file; or, if you are using a qmake project file to manage script translations, you specify the name of that file. \c lrelease will create \c myscript_la.qm, the binary representation of the translation. diff --git a/doc/src/qtuiloader.qdoc b/doc/src/qtuiloader.qdoc index 137cfeb..0a23366 100644 --- a/doc/src/qtuiloader.qdoc +++ b/doc/src/qtuiloader.qdoc @@ -53,7 +53,7 @@ These forms are processed at run-time to produce dynamically-generated user interfaces. In order to generate a form at run-time, a resource - file containing a \c{.ui} file is needed. Applications that use the + file containing a UI file is needed. Applications that use the form handling classes need to be configured to be built against the QtUiTools module. This is done by including the following declaration in a \c qmake project file to ensure that the application is compiled diff --git a/doc/src/signalsandslots.qdoc b/doc/src/signalsandslots.qdoc index 356db33..09eb0a6 100644 --- a/doc/src/signalsandslots.qdoc +++ b/doc/src/signalsandslots.qdoc @@ -190,7 +190,7 @@ know any information about each other. To enable this, the objects only need to be connected together, and this can be achieved with some simple QObject::connect() function calls, or with \c{uic}'s - \l{Using a Designer .ui File in Your Application#Automatic Connections} + \l{Using a Designer UI File in Your Application#Automatic Connections} {automatic connections} feature. \section1 Building the Example diff --git a/doc/src/snippets/code/doc_src_linguist-manual.qdoc b/doc/src/snippets/code/doc_src_linguist-manual.qdoc index ce3b997..5697300 100644 --- a/doc/src/snippets/code/doc_src_linguist-manual.qdoc +++ b/doc/src/snippets/code/doc_src_linguist-manual.qdoc @@ -42,7 +42,7 @@ Options: -pluralonly Only include plural form messages. -silent - Don't explain what is being done. + Do not explain what is being done. -version Display the version of lupdate and exit. //! [4] @@ -55,14 +55,14 @@ Usage: Options: -help Display this information and exit -compress - Compress the .qm files + Compress the QM files -nounfinished Do not include unfinished translations -removeidentical If the translated text is the same as the source text, do not include the message -silent - Don't explain what is being done + Do not explain what is being done -version Display the version of lrelease and exit //! [5] diff --git a/doc/src/snippets/code/doc_src_qmake-manual.qdoc b/doc/src/snippets/code/doc_src_qmake-manual.qdoc index edb66bc..82c710d 100644 --- a/doc/src/snippets/code/doc_src_qmake-manual.qdoc +++ b/doc/src/snippets/code/doc_src_qmake-manual.qdoc @@ -689,7 +689,7 @@ qmake -o Makefile hello.pro //! [115] -qmake -tp vc -o hello.dsp hello.pro +qmake -tp vc hello.pro //! [115] diff --git a/doc/src/snippets/code/doc_src_qthelp.qdoc b/doc/src/snippets/code/doc_src_qthelp.qdoc index 11d231f..949e2a5 100644 --- a/doc/src/snippets/code/doc_src_qthelp.qdoc +++ b/doc/src/snippets/code/doc_src_qthelp.qdoc @@ -92,8 +92,7 @@ if (links.count()) { </keywords> <files> <file>classic.css</file> - <file>index.html</file> - <file>doc.html</file> + <file>*.html</file> </files> </filterSection> </QtHelpProject> @@ -154,8 +153,7 @@ if (links.count()) { ... <files> <file>classic.css</file> - <file>index.html</file> - <file>doc.html</file> + <file>*.html</file> </files> ... //! [13] diff --git a/doc/src/snippets/code/src_corelib_global_qglobal.cpp b/doc/src/snippets/code/src_corelib_global_qglobal.cpp index 287181a..50052c3 100644 --- a/doc/src/snippets/code/src_corelib_global_qglobal.cpp +++ b/doc/src/snippets/code/src_corelib_global_qglobal.cpp @@ -358,6 +358,30 @@ QString global_greeting(int type) //! [36] +//! [qttrid] + //% "%n fooish bar(s) found.\n" + //% "Do you want to continue?" + QString text = qtTrId("qtn_foo_bar", n); +//! [qttrid] + + +//! [qttrid_noop] +static const char * const ids[] = { + //% "This is the first text." + QT_TRID_NOOP("qtn_1st_text"), + //% "This is the second text." + QT_TRID_NOOP("qtn_2nd_text"), + 0 +}; + +void TheClass::addLabels() +{ + for (int i = 0; ids[i]; ++i) + new QLabel(qtTrId(ids[i]), this); +} +//! [qttrid_noop] + + //! [37] qWarning("%s: %s", qPrintable(key), qPrintable(value)); //! [37] diff --git a/doc/src/snippets/code/src_corelib_kernel_qobject.cpp b/doc/src/snippets/code/src_corelib_kernel_qobject.cpp index 5a7c5a7..5c0f80c 100644 --- a/doc/src/snippets/code/src_corelib_kernel_qobject.cpp +++ b/doc/src/snippets/code/src_corelib_kernel_qobject.cpp @@ -376,6 +376,15 @@ hostNameLabel->setText(tr("Name:")); QString example = tr("Example"); //! [40] +//! [meta data] +//: This is a comment for the translator. +//= qtn_foo_bar +//~ loc-layout_id foo_dialog +//~ loc-blank False +//~ magic-stuff This might mean something magic. +QString text = MyMagicClass::tr("Sim sala bim."); +//! [meta data] + //! [explicit tr context] QString text = QScrollBar::tr("Page up"); //! [explicit tr context] diff --git a/doc/src/templates.qdoc b/doc/src/templates.qdoc index 5a8acf7..8cfb851 100644 --- a/doc/src/templates.qdoc +++ b/doc/src/templates.qdoc @@ -162,7 +162,7 @@ without having to know the exact types of the objects we are connecting. This is impossible with a template based solution. This kind of runtime introspection opens up new possibilities, for example GUIs that are - generated and connected from Qt Designer's XML \c{ui} files. + generated and connected from Qt Designer's XML UI files. \section1 Calling Performance is Not Everything diff --git a/doc/src/threads.qdoc b/doc/src/threads.qdoc index c9d0904..8469f51 100644 --- a/doc/src/threads.qdoc +++ b/doc/src/threads.qdoc @@ -262,48 +262,41 @@ \keyword thread-safe \section1 Reentrancy and Thread-Safety - Throughout the Qt documentation, the terms \e reentrant and \e - thread-safe are used to specify how a function can be used in - multithreaded applications: + Throughout the documentation, the terms \e{reentrant} and + \e{thread-safe} are used to mark classes and functions to indicate + how they can be used in multithread applications: \list - \o A \e reentrant function can be called simultaneously by - multiple threads provided that each invocation of the function - references unique data. - \o A \e thread-safe function can be called simultaneously by - multiple threads when each invocation references shared data. - All access to the shared data is serialized. + \o A \e thread-safe function can be called simultaneously from + multiple threads, even when the invocations use shared data, + because all references to the shared data are serialized. + \o A \e reentrant function can also be called simultaneously from + multiple threads, but only if each invocation uses its own data. \endlist - By extension, a class is said to be reentrant if each and every - one of its functions can be called simultaneously by multiple - threads on different instances of the class. Similarly, the class - is said to be thread-safe if the functions can be called by - different threads on the same instance. + Hence, a \e{thread-safe} function is always \e{reentrant}, but a + \e{reentrant} function is not always \e{thread-safe}. - Classes in the documentation will be documented as thread-safe only - if they are intended to be used by multiple threads. + By extension, a class is said to be \e{reentrant} if its member + functions can be called safely from multiple threads, as long as + each thread uses a \e{different} instance of the class. The class + is \e{thread-safe} if its member functions can be called safely + from multiple threads, even if all the threads use the \e{same} + instance of the class. - Note that the terminology in this domain isn't entirely - standardized. POSIX uses a somewhat different definition of - reentrancy and thread-safety for its C APIs. When dealing with an - object-oriented C++ class library such as Qt, the definitions - must be adapted. - - Most C++ classes are inherently reentrant, since they typically - only reference member data. Any thread can call such a member - function on an instance of the class, as long as no other thread - is calling a member function on the same instance. For example, - the \c Counter class below is reentrant: + C++ classes are often reentrant, simply because they only access + their own member data. Any thread can call a member function on an + instance of a reentrant class, as long as no other thread can call + a member function on the \e{same} instance of the class at the + same time. For example, the \c Counter class below is reentrant: \snippet doc/src/snippets/threads/threads.cpp 3 \snippet doc/src/snippets/threads/threads.cpp 4 The class isn't thread-safe, because if multiple threads try to modify the data member \c n, the result is undefined. This is - because C++'s \c ++ and \c -- operators aren't necessarily - atomic. Indeed, they usually expand to three machine - instructions: + because the \c ++ and \c -- operators aren't always atomic. + Indeed, they usually expand to three machine instructions: \list 1 \o Load the variable's value in a register. @@ -332,14 +325,27 @@ declared with the \c mutable qualifier because we need to lock and unlock the mutex in \c value(), which is a const function. - Most Qt classes are reentrant and not thread-safe, to avoid the - overhead of repeatedly locking and unlocking a QMutex. For - example, QString is reentrant, meaning that you can use it in - different threads, but you can't access the same QString object - from different threads simultaneously (unless you protect it with - a mutex yourself). A few classes and functions are thread-safe; - these are mainly thread-related classes such as QMutex, or - fundamental functions such as QCoreApplication::postEvent(). + Many Qt classes are \e{reentrant}, but they are not made + \e{thread-safe}, because making them thread-safe would incur the + extra overhead of repeatedly locking and unlocking a QMutex. For + example, QString is reentrant but not thread-safe. You can safely + access \e{different} instances of QString from multiple threads + simultaneously, but you can't safely access the \e{same} instance + of QString from multiple threads simultaneously (unless you + protect the accesses yourself with a QMutex). + + Some Qt classes and functions are thread-safe. These are mainly + the thread-related classes (e.g. QMutex) and fundamental functions + (e.g. QCoreApplication::postEvent()). + + \note Qt Classes are only documented as \e{thread-safe} if they + are intended to be used by multiple threads. + + \note Terminology in the multithreading domain isn't entirely + standardized. POSIX uses definitions of reentrant and thread-safe + that are somewhat different for its C APIs. When using other + object-oriented C++ class libraries with Qt, be sure the + definitions are understood. \section1 Threads and QObjects @@ -428,20 +434,22 @@ an object and its children (the object cannot be moved if it has a parent). - Calling \c delete on a QObject from another thread than the - thread where it is created (or accessing the object in other - ways) is unsafe unless you can guarantee that the object isn't - processing events at the same moment. Use QObject::deleteLater() - instead; it will post a - \l{QEvent::DeferredDelete}{DeferredDelete} event, which the - event loop of the object's thread will eventually pick up. + Calling \c delete on a QObject from a thread other than the one + that \e owns the object (or accessing the object in other ways) is + unsafe, unless you guarantee that the object isn't processing + events at that moment. Use QObject::deleteLater() instead, and a + \l{QEvent::DeferredDelete}{DeferredDelete} event will be posted, + which the event loop of the object's thread will eventually pick + up. By default, the thread that \e owns a QObject is the thread + that \e creates the QObject, but not after QObject::moveToThread() + has been called. If no event loop is running, events won't be delivered to the - object. For example, if you create a QTimer object in a thread - but never call \l{QThread::exec()}{exec()}, the QTimer will never emit its - \l{QTimer::timeout()}{timeout()} signal. Calling - \l{QObject::deleteLater()}{deleteLater()} won't work either. (These - restrictions apply to the main thread as well.) + object. For example, if you create a QTimer object in a thread but + never call \l{QThread::exec()}{exec()}, the QTimer will never emit + its \l{QTimer::timeout()}{timeout()} signal. Calling + \l{QObject::deleteLater()}{deleteLater()} won't work + either. (These restrictions apply to the main thread as well.) You can manually post events to any object in any thread at any time using the thread-safe function diff --git a/doc/src/tutorials/addressbook.qdoc b/doc/src/tutorials/addressbook.qdoc index 33832da..95394eb 100644 --- a/doc/src/tutorials/addressbook.qdoc +++ b/doc/src/tutorials/addressbook.qdoc @@ -876,7 +876,7 @@ \image addressbook-tutorial-part6-save.png - If \c fileName is not empty, we create a QFile object, \c file with + If \c fileName is not empty, we create a QFile object, \c file, with \c fileName. QFile works with QDataStream as QFile is a QIODevice. Next, we attempt to open the file in \l{QIODevice::}{WriteOnly} mode. @@ -906,18 +906,18 @@ \image addressbook-tutorial-part6-load.png If \c fileName is not empty, again, we use a QFile object, \c file, and - attempt to open it in \l{QIODevice::}{ReadOnly} mode. In a similar way - to our implementation of \c saveToFile(), if this attempt is unsuccessful, - we display a QMessageBox to inform the user. + attempt to open it in \l{QIODevice::}{ReadOnly} mode. Similar to our + implementation of \c saveToFile(), if this attempt is unsuccessful, we + display a QMessageBox to inform the user. \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part2 Otherwise, we instantiate a QDataStream object, \c in, set its version as above and read the serialized data into the \c contacts data structure. - Note that we empty \c contacts before reading data into it to simplify the - file reading process. A more advanced method would be to read the contacts - into temporary QMap object, and copy only the contacts that do not already - exist in \c contacts. + The \c contacts object is emptied before data is read into it to simplify + the file reading process. A more advanced method would be to read the + contacts into a temporary QMap object, and copy over non-duplicate contacts + into \c contacts. \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part3 |